Reformat to FLTK style, improve documentation

No code changes.

Replace '#define fl_clip ..' with an inline method.

FL/fl_draw.H

@@ -39,7 +39,7 @@ FL_EXPORT extern char fl_draw_shortcut;
 
 // Colors:
 /**
- Sets the color for all subsequent drawing operations.
+  Set the color for all subsequent drawing operations.
   For colormapped displays, a color cell will be allocated out of
   \p fl_colormap the first time you use a color. If the colormap fills up
   then a least-squares algorithm is used to find the closest color.
@@ -47,11 +47,15 @@ FL_EXPORT extern char fl_draw_shortcut;
   the foreground is not set for the current window.
   \param[in] c color
 */
-inline void     fl_color(Fl_Color c) {fl_graphics_driver->color(c); } // select indexed color
+inline void fl_color(Fl_Color c) {
+  fl_graphics_driver->color(c);
+} // select indexed color
 /** for back compatibility - use fl_color(Fl_Color c) instead */
-inline void fl_color(int c) {fl_color((Fl_Color)c);}
+inline void fl_color(int c) {
+  fl_color((Fl_Color)c);
+}
 /**
- Sets the color for all subsequent drawing operations.
+  Set the color for all subsequent drawing operations.
   The closest possible match to the RGB color is used.
   The RGB color is used directly on TrueColor displays.
   For colormap visuals the nearest index in the gray
@@ -60,12 +64,16 @@ inline void fl_color(int c) {fl_color((Fl_Color)c);}
   the foreground is not set for the current window.
   \param[in] r,g,b color components
 */
-inline void     fl_color(uchar r, uchar g, uchar b) {fl_graphics_driver->color(r,g,b); } // select actual color
+inline void fl_color(uchar r, uchar g, uchar b) {
+  fl_graphics_driver->color(r, g, b);
+}
 /**
-  Returns the last fl_color() that was set.
+  Return the last fl_color() that was set.
   This can be used for state save/restore.
 */
-inline Fl_Color fl_color() {return fl_graphics_driver->color();}
+inline Fl_Color fl_color() {
+  return fl_graphics_driver->color();
+}
 /** @} */
 
 /** \addtogroup fl_drawings
@@ -73,32 +81,40 @@ inline Fl_Color fl_color() {return fl_graphics_driver->color();}
 */
 // clip:
 /**
- Intersects the current clip region with a rectangle and pushes this
+  Intersect the current clip region with a rectangle and push this
   new region onto the stack.
   \param[in] x,y,w,h position and size
 */
-inline void fl_push_clip(int x, int y, int w, int h) {fl_graphics_driver->push_clip(x,y,w,h); }
+inline void fl_push_clip(int x, int y, int w, int h) {
+  fl_graphics_driver->push_clip(x, y, w, h);
+}
 /**
- Intersects the current clip region with a rectangle and pushes this
+  Intersect the current clip region with a rectangle and push this
   new region onto the stack (deprecated).
   \param[in] x,y,w,h position and size
   \deprecated
-   fl_clip(int, int, int, int) is deprecated and will be removed from future releases.
     Please use fl_push_clip(int x, int y, int w, int h) instead.
+    fl_clip(int, int, int, int) will be removed in FLTK 1.5.
 */
-#define fl_clip fl_push_clip
+inline void fl_clip(int x, int y, int w, int h) {
+  fl_graphics_driver->push_clip(x, y, w, h);
+}
 /**
- Pushes an empty clip region onto the stack so nothing will be clipped.
+  Push an empty clip region onto the stack so nothing will be clipped.
 */
-inline void fl_push_no_clip() {fl_graphics_driver->push_no_clip(); }
+inline void fl_push_no_clip() {
+  fl_graphics_driver->push_no_clip();
+}
 /**
- Restores the previous clip region.
+  Restore the previous clip region.
 
   You must call fl_pop_clip() once for every time you call fl_push_clip().
   Unpredictable results may occur if the clip stack is not empty when
   you return to FLTK.
 */
-inline void fl_pop_clip() {fl_graphics_driver->pop_clip(); }
+inline void fl_pop_clip() {
+  fl_graphics_driver->pop_clip();
+}
 
 /**
   Does the rectangle intersect the current clip region?
@@ -118,7 +134,7 @@ inline int fl_not_clipped(int x, int y, int w, int h) {
 }
 
 /**
-  Intersects a rectangle with the current clip region and returns the
+  Intersect a rectangle with the current clip region and return the
   bounding box of the result.
 
   Returns non-zero if the resulting rectangle is different to the original.
@@ -163,13 +179,13 @@ inline int fl_clip_box(int x, int y, int w, int h, int& X, int& Y, int& W, int&
   return fl_graphics_driver->clip_box(x, y, w, h, X, Y, W, H);
 }
 
-/** Undoes any clobbering of clip done by your program */
+/** Undo any clobbering of the clip region done by your program. */
 inline void fl_restore_clip() {
   fl_graphics_driver->restore_clip();
 }
 
 /**
- Replaces the top of the clipping stack with a clipping region of any shape.
+  Replace the top of the clipping stack with a clipping region of any shape.
 
   Fl_Region is an operating system specific type.
   \note This function is mostly intended for internal use by the FLTK library
@@ -177,34 +193,40 @@ inline void fl_restore_clip() {
   Its effect can be null if the current drawing surface is not the display.
   \param[in] r clipping region
 */
-inline void fl_clip_region(Fl_Region r) { fl_graphics_driver->clip_region(r); }
+inline void fl_clip_region(Fl_Region r) {
+  fl_graphics_driver->clip_region(r);
+}
 
 /**
- Returns the current clipping region.
+  Return the current clipping region.
   \note This function is mostly intended for internal use by the FLTK library
   when drawing to the display.
   Its return value can be always NULL if the current drawing surface is not the display.
 */
-inline Fl_Region fl_clip_region() { return fl_graphics_driver->clip_region(); }
+inline Fl_Region fl_clip_region() {
+  return fl_graphics_driver->clip_region();
+}
 
 
 // points:
 /**
- Draws a single pixel at the given coordinates
+  Draw a single pixel at the given coordinates
 */
-inline void fl_point(int x, int y) { fl_graphics_driver->point(x,y); }
+inline void fl_point(int x, int y) {
+  fl_graphics_driver->point(x, y);
+}
 
 // line type:
 /**
- Sets how to draw lines (the "pen").
+  Set how to draw lines (the "pen").
+
   If you change this it is your responsibility to set it back to the default
   using \c fl_line_style(0).
 
   \param[in] style A bitmask which is a bitwise-OR of a line style, a cap
     style, and a join style. If you don't specify a dash type you
     will get a solid line. If you don't specify a cap or join type
- you will get a system-defined default of whatever value is
+    you will get a system-defined default of whatever value is fastest.
- fastest.
   \param[in] width The thickness of the lines in pixels. Zero results in the
     system defined default, which on both X and Windows is somewhat
     different and nicer than 1.
@@ -219,10 +241,14 @@ inline void fl_point(int x, int y) { fl_graphics_driver->point(x,y); }
     you \e must set the line style \e after setting the drawing
     color. If you set the color after the line style you will lose
     the line style settings.
- \note      The \p dashes array does not work under Windows 95, 98 or Me,
+
- since those operating systems do not support complex line styles.
+  \note The \p dashes array does not work under the (unsupported!) operating
+    systems Windows 95, 98 or Me, since those operating systems do not
+    support complex line styles.
 */
-inline void fl_line_style(int style, int width=0, char* dashes=0) {fl_graphics_driver->line_style(style,width,dashes); }
+inline void fl_line_style(int style, int width = 0, char *dashes = 0) {
+  fl_graphics_driver->line_style(style, width, dashes);
+}
 enum {
   FL_SOLID = 0,      ///< line style: <tt>___________</tt>
   FL_DASH = 1,       ///< line style: <tt>_ _ _ _ _ _</tt>
@@ -240,104 +266,145 @@ enum {
 };
 
 /**
- Turns ON or OFF antialiased line drawings, if supported by platform.
+  Turn ON or OFF antialiased line drawings, if supported by platform.
- Currently, only the Windows platform allows to change whether line drawings are antialiased.
+  Currently, only the Windows platform allows to change whether line drawings
- Turning it OFF may accelerate heavy drawing operations.
+  are antialiased. Turning it OFF may accelerate heavy drawing operations.
 */
-inline void fl_antialias(int state) { fl_graphics_driver->antialias(state); }
+inline void fl_antialias(int state) {
+  fl_graphics_driver->antialias(state);
+}
 
-/** Returns whether line drawings are currently antialiased */
+/** Return whether line drawings are currently antialiased. */
-inline int fl_antialias() { return fl_graphics_driver->antialias(); }
+inline int fl_antialias() {
+  return fl_graphics_driver->antialias();
+}
 
 // rectangles tweaked to exactly fill the pixel rectangle:
 
 /**
- Draws a 1-pixel border \e inside the given bounding box.
+  Draw a 1-pixel border \e inside the given bounding box.
   This function is meant for quick drawing of simple boxes. The behavior is
   undefined for line widths that are not 1.
 */
-inline void fl_rect(int x, int y, int w, int h) { fl_graphics_driver->rect(x,y,w,h); }
+inline void fl_rect(int x, int y, int w, int h) {
+  fl_graphics_driver->rect(x, y, w, h);
+}
+
+/** Draw a dotted rectangle, used to indicate keyboard focus on a widget. */
+inline void fl_focus_rect(int x, int y, int w, int h) {
+  fl_graphics_driver->focus_rect(x, y, w, h);
+}
+
+/** Draw with passed color a 1-pixel border \e inside the given bounding box. */
+inline void fl_rect(int x, int y, int w, int h, Fl_Color c) {
+  fl_color(c);
+  fl_rect(x, y, w, h);
+}
+
+/** Color with current color a rectangle that exactly fills the given bounding box. */
+inline void fl_rectf(int x, int y, int w, int h) {
+  fl_graphics_driver->rectf(x, y, w, h);
+}
+
+/** Color with passed color a rectangle that exactly fills the given bounding box. */
+inline void fl_rectf(int x, int y, int w, int h, Fl_Color c) {
+  fl_color(c);
+  fl_rectf(x, y, w, h);
+}
 
 /**
- Draw a dotted rectangle, used to indicate keyboard focus on a widget.
+  Color a rectangle with "exactly" the passed <tt>r,g,b</tt> color.
- */
-inline void fl_focus_rect(int x, int y, int w, int h) { fl_graphics_driver->focus_rect(x, y, w, h); }
-/** Draws with passed color a 1-pixel border \e inside the given bounding box */
-inline void fl_rect(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_rect(x,y,w,h);}
-/** Colors with current color a rectangle that exactly fills the given bounding box */
-inline void fl_rectf(int x, int y, int w, int h) { fl_graphics_driver->rectf(x,y,w,h); }
-/** Colors with passed color a rectangle that exactly fills the given bounding box */
-inline void fl_rectf(int x, int y, int w, int h, Fl_Color c) {fl_color(c); fl_rectf(x,y,w,h);}
-
-/**
-  Colors a rectangle with "exactly" the passed <tt>r,g,b</tt> color.
   On screens with less than 24 bits of color this is done by drawing a
   solid-colored block using fl_draw_image() so that the correct color
   shade is produced.
 */
-inline void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) { fl_graphics_driver->colored_rectf(x,y,w,h,r,g,b); }
+inline void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b) {
+  fl_graphics_driver->colored_rectf(x, y, w, h, r, g, b);
+}
 
 // line segments:
 /**
- Draws a line from (x,y) to (x1,y1)
+  Draw a line from (x,y) to (x1,y1)
 */
-inline void fl_line(int x, int y, int x1, int y1) {fl_graphics_driver->line(x,y,x1,y1); }
+inline void fl_line(int x, int y, int x1, int y1) {
+  fl_graphics_driver->line(x, y, x1, y1);
+}
 /**
- Draws a line from (x,y) to (x1,y1) and another from (x1,y1) to (x2,y2)
+  Draw a line from (x,y) to (x1,y1) and another from (x1,y1) to (x2,y2)
 */
-inline void fl_line(int x, int y, int x1, int y1, int x2, int y2) {fl_graphics_driver->line(x,y,x1,y1,x2,y2); }
+inline void fl_line(int x, int y, int x1, int y1, int x2, int y2) {
+  fl_graphics_driver->line(x, y, x1, y1, x2, y2);
+}
 
 // closed line segments:
 /**
- Outlines a 3-sided polygon with lines
+  Outline a 3-sided polygon with lines
 */
-inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2) {fl_graphics_driver->loop(x,y,x1,y1,x2,y2); }
+inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2) {
+  fl_graphics_driver->loop(x, y, x1, y1, x2, y2);
+}
 /**
- Outlines a 4-sided polygon with lines
+  Outline a 4-sided polygon with lines
 */
-inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
+inline void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
-  {fl_graphics_driver->loop(x,y,x1,y1,x2,y2,x3,y3); }
+  fl_graphics_driver->loop(x, y, x1, y1, x2, y2, x3, y3);
+}
 
 // filled polygons
 /**
- Fills a 3-sided polygon. The polygon must be convex.
+  Fill a 3-sided polygon. The polygon must be convex.
 */
-inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) {fl_graphics_driver->polygon(x,y,x1,y1,x2,y2); }
+inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) {
+  fl_graphics_driver->polygon(x, y, x1, y1, x2, y2);
+}
 /**
- Fills a 4-sided polygon. The polygon must be convex.
+  Fill a 4-sided polygon. The polygon must be convex.
 */
-inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3)
+inline void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) {
-  { fl_graphics_driver->polygon(x,y,x1,y1,x2,y2,x3,y3); }
+  fl_graphics_driver->polygon(x, y, x1, y1, x2, y2, x3, y3);
+}
 
 // draw rectilinear lines, horizontal segment first:
 /**
- Draws a horizontal line from (x,y) to (x1,y)
+  Draw a horizontal line from (x,y) to (x1,y).
 */
-inline void fl_xyline(int x, int y, int x1) {fl_graphics_driver->xyline(x,y,x1);}
+inline void fl_xyline(int x, int y, int x1) {
+  fl_graphics_driver->xyline(x, y, x1);
+}
 /**
- Draws a horizontal line from (x,y) to (x1,y), then vertical from (x1,y) to (x1,y2)
+  Draw a horizontal line from (x,y) to (x1,y), then vertical from (x1,y) to (x1,y2).
 */
-inline void fl_xyline(int x, int y, int x1, int y2) {fl_graphics_driver->xyline(x,y,x1,y2);}
+inline void fl_xyline(int x, int y, int x1, int y2) {
+  fl_graphics_driver->xyline(x, y, x1, y2);
+}
 /**
- Draws a horizontal line from (x,y) to (x1,y), then a vertical from (x1,y) to (x1,y2)
+  Draw a horizontal line from (x,y) to (x1,y), then a vertical from (x1,y) to (x1,y2)
- and then another horizontal from (x1,y2) to (x3,y2)
+  and then another horizontal from (x1,y2) to (x3,y2).
 */
-inline void fl_xyline(int x, int y, int x1, int y2, int x3) {fl_graphics_driver->xyline(x,y,x1,y2,x3);}
+inline void fl_xyline(int x, int y, int x1, int y2, int x3) {
+  fl_graphics_driver->xyline(x, y, x1, y2, x3);
+}
 
 // draw rectilinear lines, vertical segment first:
 /**
- Draws a vertical line from (x,y) to (x,y1)
+  Draw a vertical line from (x,y) to (x,y1)
 */
-inline void fl_yxline(int x, int y, int y1) {fl_graphics_driver->yxline(x,y,y1);}
+inline void fl_yxline(int x, int y, int y1) {
+  fl_graphics_driver->yxline(x, y, y1);
+}
 /**
- Draws a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1)
+  Draw a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1) to (x2,y1).
 */
-inline void fl_yxline(int x, int y, int y1, int x2) {fl_graphics_driver->yxline(x,y,y1,x2);}
+inline void fl_yxline(int x, int y, int y1, int x2) {
+  fl_graphics_driver->yxline(x, y, y1, x2);
+}
 /**
- Draws a vertical line from (x,y) to (x,y1) then a horizontal from (x,y1)
+  Draw a vertical line from (x,y) to (x,y1), then a horizontal from (x,y1)
- to (x2,y1), then another vertical from (x2,y1) to (x2,y3)
+  to (x2,y1), then another vertical from (x2,y1) to (x2,y3).
 */
-inline void fl_yxline(int x, int y, int y1, int x2, int y3) {fl_graphics_driver->yxline(x,y,y1,x2,y3);}
+inline void fl_yxline(int x, int y, int y1, int x2, int y3) {
+  fl_graphics_driver->yxline(x, y, y1, x2, y3);
+}
 
 // circular lines and pie slices (code in fl_arci.C):
 /**
@@ -365,7 +432,9 @@ inline void fl_yxline(int x, int y, int y1, int x2, int y3) {fl_graphics_driver-
   \image html  fl_pie_arc_diagram.png "fl_pie() and fl_arc()"
   \image latex fl_pie_arc_diagram.png "fl_pie() and fl_arc()" width=4cm
 */
-inline void fl_arc(int x, int y, int w, int h, double a1, double a2) {fl_graphics_driver->arc(x,y,w,h,a1,a2); }
+inline void fl_arc(int x, int y, int w, int h, double a1, double a2) {
+  fl_graphics_driver->arc(x, y, w, h, a1, a2);
+}
 /**
   Draw filled ellipse sections using integer coordinates.
 
@@ -381,85 +450,107 @@ inline void fl_arc(int x, int y, int w, int h, double a1, double a2) {fl_graphic
   \image html  fl_pie_arc_diagram.png "fl_pie() and fl_arc()"
   \image latex fl_pie_arc_diagram.png "fl_pie() and fl_arc()" width=4cm
 */
-inline void fl_pie(int x, int y, int w, int h, double a1, double a2) {fl_graphics_driver->pie(x,y,w,h,a1,a2); }
+inline void fl_pie(int x, int y, int w, int h, double a1, double a2) {
+  fl_graphics_driver->pie(x, y, w, h, a1, a2);
+}
 /** fl_chord declaration is a place holder - the function does not yet exist */
 FL_EXPORT void fl_chord(int x, int y, int w, int h, double a1, double a2); // nyi
 
-// scalable drawing code (code in fl_vertex.C and fl_arc.C):
+// scalable drawing code (code in fl_vertex.cxx and fl_arc.cxx):
 /**
- Saves the current transformation matrix on the stack.
+  Save the current transformation matrix on the stack.
   The maximum depth of the stack is 32.
 */
-inline void fl_push_matrix() { fl_graphics_driver->push_matrix(); }
+inline void fl_push_matrix() {
+  fl_graphics_driver->push_matrix();
+}
 /**
- Restores the current transformation matrix from the stack.
+  Restore the current transformation matrix from the stack.
 */
-inline void fl_pop_matrix() { fl_graphics_driver->pop_matrix(); }
+inline void fl_pop_matrix() {
+  fl_graphics_driver->pop_matrix();
+}
 /**
- Concatenates scaling transformation onto the current one.
+  Concatenate scaling transformation onto the current one.
   \param[in] x,y scale factors in x-direction and y-direction
 */
 inline void fl_scale(double x, double y) {
   fl_graphics_driver->mult_matrix(x, 0, 0, y, 0, 0);
 }
 /**
- Concatenates scaling transformation onto the current one.
+  Concatenate scaling transformation onto the current one.
   \param[in] x scale factor in both x-direction and y-direction
 */
 inline void fl_scale(double x) {
   fl_graphics_driver->mult_matrix(x, 0, 0, x, 0, 0);
 }
 /**
- Concatenates translation transformation onto the current one.
+  Concatenate translation transformation onto the current one.
   \param[in] x,y translation factor in x-direction and y-direction
 */
-inline void fl_translate(double x, double y) { fl_graphics_driver->translate(x, y); }
+inline void fl_translate(double x, double y) {
+  fl_graphics_driver->translate(x, y);
+}
 /**
- Concatenates rotation transformation onto the current one.
+  Concatenate rotation transformation onto the current one.
   \param[in] d - rotation angle, counter-clockwise in degrees (not radians)
 */
-inline void fl_rotate(double d) { fl_graphics_driver->rotate(d); }
+inline void fl_rotate(double d) {
+  fl_graphics_driver->rotate(d);
+}
 /**
- Concatenates another transformation onto the current one.
+  Concatenate another transformation onto the current one.
 
   \param[in] a,b,c,d,x,y transformation matrix elements such that
  <tt> X' = aX + cY + x </tt> and <tt> Y' = bX +dY + y </tt>
 */
-inline void fl_mult_matrix(double a, double b, double c, double d, double x,double y)
+inline void fl_mult_matrix(double a, double b, double c, double d, double x, double y) {
-        { fl_graphics_driver->mult_matrix(a, b, c, d, x, y); }
+  fl_graphics_driver->mult_matrix(a, b, c, d, x, y);
+}
 /**
- Starts drawing a list of points. Points are added to the list with fl_vertex()
+  Start drawing a list of points. Points are added to the list with fl_vertex().
 */
-inline void fl_begin_points() {fl_graphics_driver->begin_points(); }
+inline void fl_begin_points() {
+  fl_graphics_driver->begin_points();
+}
 /**
- Starts drawing a list of lines.
+  Start drawing a list of lines.
 */
-inline void fl_begin_line() {fl_graphics_driver->begin_line(); }
+inline void fl_begin_line() {
+  fl_graphics_driver->begin_line();
+}
 /**
- Starts drawing a closed sequence of lines.
+  Start drawing a closed sequence of lines.
 */
-inline void fl_begin_loop() {fl_graphics_driver->begin_loop(); }
+inline void fl_begin_loop() {
+  fl_graphics_driver->begin_loop();
+}
 /**
- Starts drawing a convex filled polygon.
+  Start drawing a convex filled polygon.
 */
-inline void fl_begin_polygon() {fl_graphics_driver->begin_polygon(); }
+inline void fl_begin_polygon() {
+  fl_graphics_driver->begin_polygon();
+}
 /**
- Adds a single vertex to the current path.
+  Add a single vertex to the current path.
   \param[in] x,y coordinate
 */
-inline void fl_vertex(double x, double y) {fl_graphics_driver->vertex(x,y); }
+inline void fl_vertex(double x, double y) {
+  fl_graphics_driver->vertex(x, y);
+}
 /**
- Adds a series of points on a Bezier curve to the path.
+  Add a series of points on a Bézier curve to the path.
   The curve ends (and two of the points) are at X0,Y0 and X3,Y3.
   \param[in] X0,Y0 curve start point
   \param[in] X1,Y1 curve control point
   \param[in] X2,Y2 curve control point
   \param[in] X3,Y3 curve end point
 */
-inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3)
+inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3) {
-  {fl_graphics_driver->curve(X0,Y0,X1,Y1,X2,Y2,X3,Y3); }
+  fl_graphics_driver->curve(X0, Y0, X1, Y1, X2, Y2, X3, Y3);
+}
 /**
- Adds a series of points to the current path on the arc of a circle.
+  Add a series of points to the current path on the arc of a circle.
   You can get elliptical paths by using scale and rotate before calling fl_arc().
   \param[in] x,y,r center and radius of circular arc
   \param[in] start,end angles of start and end of arc measured in degrees
@@ -487,33 +578,45 @@ inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, doub
     fl_end_polygon();
   \endcode
 */
-inline void fl_arc(double x, double y, double r, double start, double end) {fl_graphics_driver->arc(x,y,r,start,end); }
+inline void fl_arc(double x, double y, double r, double start, double end) {
+  fl_graphics_driver->arc(x, y, r, start, end);
+}
 /**
   fl_circle(x,y,r) is equivalent to fl_arc(x,y,r,0,360), but may be faster.
 
   It must be the \e only thing in the path: if you want a circle as part of
- a complex polygon you must use fl_arc()
+  a complex polygon you must use fl_arc().
   \param[in] x,y,r center and radius of circle
 */
-inline void fl_circle(double x, double y, double r) {fl_graphics_driver->circle(x,y,r); }
+inline void fl_circle(double x, double y, double r) {
+  fl_graphics_driver->circle(x, y, r);
+}
 /**
- Ends list of points, and draws.
+  End list of points, and draw.
 */
-inline void fl_end_points() {fl_graphics_driver->end_points(); }
+inline void fl_end_points() {
+  fl_graphics_driver->end_points();
+}
 /**
- Ends list of lines, and draws.
+  End list of lines, and draw.
 */
-inline void fl_end_line() {fl_graphics_driver->end_line(); }
+inline void fl_end_line() {
+  fl_graphics_driver->end_line();
+}
 /**
- Ends closed sequence of lines, and draws.
+  End closed sequence of lines, and draw.
 */
-inline void fl_end_loop() {fl_graphics_driver->end_loop(); }
+inline void fl_end_loop() {
+  fl_graphics_driver->end_loop();
+}
 /**
- Ends convex filled polygon, and draws.
+  End convex filled polygon, and draw.
 */
-inline void fl_end_polygon() {fl_graphics_driver->end_polygon(); }
+inline void fl_end_polygon() {
+  fl_graphics_driver->end_polygon();
+}
 /**
- Starts drawing a complex filled polygon.
+  Start drawing a complex filled polygon.
 
   The polygon may be concave, may have holes in it, or may be several
   disconnected pieces. Call fl_gap() to separate loops of the path.
@@ -521,49 +624,64 @@ inline void fl_end_polygon() {fl_graphics_driver->end_polygon(); }
   To outline the polygon, use fl_begin_loop() and replace each fl_gap()
   with fl_end_loop();fl_begin_loop() pairs.
 
- \note
+  \note For portability, you should only draw polygons that appear the same
- For portability, you should only draw polygons that appear the same
     whether "even/odd" or "non-zero" winding rules are used to fill them.
     Holes should be drawn in the opposite direction to the outside loop.
 */
-inline void fl_begin_complex_polygon() {fl_graphics_driver->begin_complex_polygon(); }
+inline void fl_begin_complex_polygon() {
+  fl_graphics_driver->begin_complex_polygon();
+}
 /**
- Call fl_gap() to separate loops of the path.
+  Separate loops of the path.
 
   It is unnecessary but harmless to call fl_gap() before the first vertex,
   after the last vertex, or several times in a row.
 */
-inline void fl_gap() {fl_graphics_driver->gap(); }
+inline void fl_gap() {
+  fl_graphics_driver->gap();
+}
 /**
- Ends complex filled polygon, and draws.
+  End complex filled polygon, and draw.
 */
-inline void fl_end_complex_polygon() {fl_graphics_driver->end_complex_polygon(); }
+inline void fl_end_complex_polygon() {
+  fl_graphics_driver->end_complex_polygon();
+}
 // get and use transformed positions:
 /**
- Transforms coordinate using the current transformation matrix.
+  Transform coordinate using the current transformation matrix.
   \param[in] x,y coordinate
 */
-inline double fl_transform_x(double x, double y) {return fl_graphics_driver->transform_x(x, y); }
+inline double fl_transform_x(double x, double y) {
+  return fl_graphics_driver->transform_x(x, y);
+}
 /**
- Transforms coordinate using the current transformation matrix.
+  Transform coordinate using the current transformation matrix.
   \param[in] x,y coordinate
 */
-inline double fl_transform_y(double x, double y) {return fl_graphics_driver->transform_y(x, y); }
+inline double fl_transform_y(double x, double y) {
+  return fl_graphics_driver->transform_y(x, y);
+}
 /**
- Transforms distance using current transformation matrix.
+  Transform distance using current transformation matrix.
   \param[in] x,y coordinate
 */
-inline double fl_transform_dx(double x, double y) {return fl_graphics_driver->transform_dx(x, y); }
+inline double fl_transform_dx(double x, double y) {
+  return fl_graphics_driver->transform_dx(x, y);
+}
 /**
- Transforms distance using current transformation matrix.
+  Transform distance using current transformation matrix.
   \param[in] x,y coordinate
 */
-inline double fl_transform_dy(double x, double y) {return fl_graphics_driver->transform_dy(x, y); }
+inline double fl_transform_dy(double x, double y) {
+  return fl_graphics_driver->transform_dy(x, y);
+}
 /**
- Adds coordinate pair to the vertex list without further transformations.
+  Add coordinate pair to the vertex list without further transformations.
   \param[in] xf,yf transformed coordinate
 */
-inline void fl_transformed_vertex(double xf, double yf) {fl_graphics_driver->transformed_vertex(xf,yf); }
+inline void fl_transformed_vertex(double xf, double yf) {
+  fl_graphics_driver->transformed_vertex(xf, yf);
+}
 
 /** Copy a rectangular area of the given offscreen buffer into the current drawing destination.
   \param x,y        position where to draw the copied rectangle
@@ -589,46 +707,63 @@ FL_EXPORT void fl_rescale_offscreen(Fl_Offscreen &ctx);
 
 // Fonts:
 /*
-  Sets the current font, which is then used in various drawing routines.
+  Set the current font, which is then used in various drawing routines.
   Implemented and documented in src/fl_draw.cxx
 */
 FL_EXPORT void fl_font(Fl_Font face, Fl_Fontsize fsize);
 
 /**
-  Returns the \p face set by the most recent call to fl_font().
+  Return the \p face set by the most recent call to fl_font().
   This can be used to save/restore the font.
 */
-inline Fl_Font fl_font() {return fl_graphics_driver->font();}
+inline Fl_Font fl_font() {
+  return fl_graphics_driver->font();
+}
 /**
-  Returns the \p size set by the most recent call to fl_font().
+  Return the \p size set by the most recent call to fl_font().
   This can be used to save/restore the font.
 */
-inline Fl_Fontsize fl_size() {return fl_graphics_driver->size();}
+inline Fl_Fontsize fl_size() {
+  return fl_graphics_driver->size();
+}
 
-// information you can get about the current font:
+// Information you can get about the current font:
 /**
-  Returns the recommended minimum line spacing for the current font.
+  Return the recommended minimum line spacing for the current font.
-  You can also use the value of \p size passed to fl_font()
+  You can also use the value of \p size passed to fl_font().
 */
-inline int fl_height() {return fl_graphics_driver->height();}
+inline int fl_height() {
+  return fl_graphics_driver->height();
+}
 FL_EXPORT int fl_height(int font, int size);
 /**
-  Returns the recommended distance above the bottom of a fl_height() tall box to
+  Return the recommended distance above the bottom of a fl_height() tall
-  draw the text at so it looks centered vertically in that box.
+  box to draw the text at so it looks centered vertically in that box.
 */
-inline int  fl_descent() {return fl_graphics_driver->descent();}
+inline int fl_descent() {
-/** Returns the typographical width of a nul-terminated string
+  return fl_graphics_driver->descent();
-    using the current font face and size. */
+}
-FL_EXPORT double fl_width(const char* txt);
+/** Return the typographical width of a nul-terminated string
-/** Returns the typographical width of a sequence of \p n characters
-    using the current font face and size. */
-inline double fl_width(const char* txt, int n) {return fl_graphics_driver->width(txt, n);}
-/** Returns the typographical width of a single character
     using the current font face and size.
-    \note if a valid fl_gc is NOT found then it uses the first window gc,
+*/
-    or the screen gc if no fltk window is available when called. */
+FL_EXPORT double fl_width(const char *txt);
-inline double fl_width(unsigned int c)  {return fl_graphics_driver->width(c);}
+
-/** Determines the minimum pixel dimensions of a nul-terminated string
+/** Return the typographical width of a sequence of \p n characters
+    using the current font face and size.
+*/
+inline double fl_width(const char *txt, int n) {
+  return fl_graphics_driver->width(txt, n);
+}
+/** Return the typographical width of a single character
+    using the current font face and size.
+
+  \note If a valid fl_gc is NOT found then it uses the first window gc,
+  or the screen gc if no fltk window is available when called.
+*/
+inline double fl_width(unsigned int c) {
+  return fl_graphics_driver->width(c);
+}
+/** Determine the minimum pixel dimensions of a nul-terminated string
     using the current fl_font().
 
   Usage: given a string "txt" drawn using fl_draw(txt, x, y) you would determine
@@ -647,47 +782,49 @@ inline double fl_width(unsigned int c)  {return fl_graphics_driver->width(c);}
 
   Example use:
   \code
-  :
     int dx,dy,W,H;
     fl_font(FL_HELVETICA, 12);                   // set font face+size first
     fl_text_extents("Some text", dx, dy, W, H);  // get width and height of string
     printf("text's width=%d, height=%d\n", W, H);
-  :
   \endcode
 */
-FL_EXPORT void fl_text_extents(const char*, int& dx, int& dy, int& w, int& h); // NO fltk symbol expansion will be performed
+FL_EXPORT void fl_text_extents(const char *, int &dx, int &dy, int &w, int &h);
-/** Determines the minimum pixel dimensions of a sequence of \p n characters
+
-    using the current fl_font().
+/** Determine the minimum pixel dimensions of a sequence of \p n characters
+    (bytes) using the current fl_font().
+
+  \note The string length is measured in bytes, not (UTF-8) characters.
   \see fl_text_extents(const char*, int& dx, int& dy, int& w, int& h)
 */
-inline void fl_text_extents(const char *t, int n, int& dx, int& dy, int& w, int& h)
+inline void fl_text_extents(const char *t, int n, int &dx, int &dy, int &w, int &h) {
-  {fl_graphics_driver->text_extents(t, n, dx, dy, w, h);}
+  fl_graphics_driver->text_extents(t, n, dx, dy, w, h);
+}
 
 // font encoding:
 // Note: doxygen comments here to avoid duplication for os-sepecific cases
 /**
-  Converts text from Windows/X11 latin1 character set to local encoding.
+  Convert text from Windows/X11 latin1 character set to local encoding.
   \param[in] t character string (latin1 encoding)
-  \param[in] n optional number of characters to convert (default is all)
+  \param[in] n optional number of characters (bytes) to convert (default is all)
   \returns pointer to internal buffer containing converted characters
 */
 FL_EXPORT const char *fl_latin1_to_local(const char *t, int n = -1);
 /**
-  Converts text from local encoding to Windowx/X11 latin1 character set.
+  Convert text from local encoding to Windows/X11 latin1 character set.
   \param[in] t character string (local encoding)
-  \param[in] n optional number of characters to convert (default is all)
+  \param[in] n optional number of characters (bytes) to convert (default is all)
   \returns pointer to internal buffer containing converted characters
 */
 FL_EXPORT const char *fl_local_to_latin1(const char *t, int n = -1);
 /**
-  Converts text from Mac Roman character set to local encoding.
+  Convert text from Mac Roman character set to local encoding.
   \param[in] t character string (Mac Roman encoding)
   \param[in] n optional number of characters to convert (default is all)
   \returns pointer to internal buffer containing converted characters
 */
 FL_EXPORT const char *fl_mac_roman_to_local(const char *t, int n = -1);
 /**
-  Converts text from local encoding to Mac Roman character set.
+  Convert text from local encoding to Mac Roman character set.
   \param[in] t character string (local encoding)
   \param[in] n optional number of characters to convert (default is all)
   \returns pointer to internal buffer containing converted characters
@@ -703,7 +840,7 @@ FL_EXPORT float fl_override_scale();
 FL_EXPORT void fl_restore_scale(float s);
 
 /**
-  Draws a nul-terminated UTF-8 string starting at the given \p x, \p y location.
+  Draw a nul-terminated UTF-8 string starting at the given \p x, \p y location.
 
   Text is aligned to the left and to the baseline of the font.
   To align to the bottom, subtract fl_descent() from \p y.
@@ -714,7 +851,7 @@ FL_EXPORT void fl_restore_scale(float s);
 */
 FL_EXPORT void fl_draw(const char *str, int x, int y);
 /**
-  Draws a nul-terminated UTF-8 string starting at the given \p x, \p y
+  Draw a nul-terminated UTF-8 string starting at the given \p x, \p y
   location and rotating \p angle degrees counter-clockwise.
   This version of fl_draw provides direct access to the text drawing
   function of the underlying OS and is supported by Xft, Win32 and MacOS
@@ -724,9 +861,11 @@ FL_EXPORT void fl_draw(int angle, const char* str, int x, int y);
 /**
   Draws starting at the given \p x, \p y location a UTF-8 string of length \p n bytes.
 */
-inline void fl_draw(const char* str, int n, int x, int y) {fl_graphics_driver->draw(str,n,x,y); }
+inline void fl_draw(const char *str, int n, int x, int y) {
+  fl_graphics_driver->draw(str, n, x, y);
+}
 /**
-  Draws at the given \p x, \p y location a UTF-8 string of length \p n bytes
+  Draw at the given \p x, \p y location a UTF-8 string of length \p n bytes
   rotating \p angle degrees counter-clockwise.
 
   \note When using X11 (Unix, Linux, Cygwin et al.) this needs Xft to work.
@@ -734,20 +873,20 @@ inline void fl_draw(const char* str, int n, int x, int y) {fl_graphics_driver->d
         A warning will be issued to stderr at runtime (only once) if you
         use this method with an angle other than 0.
 */
-inline void fl_draw(int angle, const char* str, int n, int x, int y) {fl_graphics_driver->draw(angle,str,n,x,y); }
+inline void fl_draw(int angle, const char *str, int n, int x, int y) {
+  fl_graphics_driver->draw(angle, str, n, x, y);
+}
 /**
-  Draws a UTF-8 string of length \p n bytes right to left starting at the given \p x, \p y location.
+  Draw a UTF-8 string of length \p n bytes right to left starting at the given \p x, \p y location.
 */
-inline void fl_rtl_draw(const char* str, int n, int x, int y) {fl_graphics_driver->rtl_draw(str,n,x,y); }
+inline void fl_rtl_draw(const char *str, int n, int x, int y) {
-FL_EXPORT void fl_measure(const char* str, int& x, int& y,
+  fl_graphics_driver->rtl_draw(str, n, x, y);
+}
+FL_EXPORT void fl_measure(const char *str, int &x, int &y, int draw_symbols = 1);
+FL_EXPORT void fl_draw(const char *str, int x, int y, int w, int h, Fl_Align align, Fl_Image *img = 0,
                        int draw_symbols = 1);
-FL_EXPORT void fl_draw(const char* str, int x, int y, int w, int h,
+FL_EXPORT void fl_draw(const char *str, int x, int y, int w, int h, Fl_Align align,
-                       Fl_Align align,
+                       void (*callthis)(const char *, int, int, int), Fl_Image *img = 0, int draw_symbols = 1);
-                       Fl_Image* img=0, int draw_symbols = 1);
-FL_EXPORT void fl_draw(const char* str, int x, int y, int w, int h,
-                       Fl_Align align,
-                       void (*callthis)(const char *,int,int,int),
-                       Fl_Image* img=0, int draw_symbols = 1);
 
 // boxtypes:
 
@@ -763,7 +902,7 @@ void fl_draw_check(Fl_Rect bb, Fl_Color col);
 // images:
 
 /**
-  Draws an 8-bit per color RGB or luminance image.
+  Draw an 8-bit per color RGB or luminance image.
   \param[in] buf points at the "r" data of the top-left pixel.
                  Color data must be in <tt>r,g,b</tt> order.
                  Luminance data is only one <tt>gray</tt> byte.
@@ -797,27 +936,31 @@ void fl_draw_check(Fl_Rect bb, Fl_Color col);
   any visual of 8 bits or less, and all common TrueColor visuals up
   to 32 bits.
 */
-inline void fl_draw_image(const uchar* buf, int X,int Y,int W,int H, int D=3, int L=0)
+inline void fl_draw_image(const uchar *buf, int X, int Y, int W, int H, int D = 3, int L = 0) {
-  { fl_graphics_driver->draw_image(buf, X, Y, W, H, D, L); }
+  fl_graphics_driver->draw_image(buf, X, Y, W, H, D, L);
+}
 
 /**
-  Draws a gray-scale (1 channel) image.
+  Draw a gray-scale (1 channel) image.
   \see fl_draw_image(const uchar* buf, int X,int Y,int W,int H, int D, int L)
 */
-inline void fl_draw_image_mono(const uchar* buf, int X,int Y,int W,int H, int D=1, int L=0)
+inline void fl_draw_image_mono(const uchar *buf, int X, int Y, int W, int H, int D = 1, int L = 0) {
-  { fl_graphics_driver->draw_image_mono(buf, X, Y, W, H, D, L); }
+  fl_graphics_driver->draw_image_mono(buf, X, Y, W, H, D, L);
+}
 
 /**
-  Draws an image using a callback function to generate image data.
+  Draw an image using a callback function to generate image data.
 
   You can generate the image as it is being drawn, or do arbitrary
   decompression of stored data, provided it can be decompressed to
-  individual scan lines easily.
+  individual scan lines.
+
   \param[in] cb   callback function to generate scan line data
   \param[in] data user data passed to callback function
   \param[in] X,Y  screen position of top left pixel
   \param[in] W,H  image width and height
-  \param[in] D    data size in bytes (must be greater than 0)
+  \param[in] D    data size per pixel in bytes (must be greater than 0)
+
   \see fl_draw_image(const uchar* buf, int X, int Y, int W, int H, int D, int L)
 
   The callback function \p cb is called with the <tt>void*</tt> \p data
@@ -840,22 +983,26 @@ inline void fl_draw_image_mono(const uchar* buf, int X,int Y,int W,int H, int D=
 
   If \p D is 4 or more, you must fill in the unused bytes with zero.
 */
-inline void fl_draw_image(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D=3)
+inline void fl_draw_image(Fl_Draw_Image_Cb cb, void *data, int X, int Y, int W, int H, int D = 3) {
-  { fl_graphics_driver->draw_image(cb, data, X, Y, W, H, D); }
+  fl_graphics_driver->draw_image(cb, data, X, Y, W, H, D);
+}
 
 /**
-  Draws a gray-scale image using a callback function to generate image data.
+  Draw a gray-scale image using a callback function to generate image data.
   \see fl_draw_image(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D)
 */
-inline void fl_draw_image_mono(Fl_Draw_Image_Cb cb, void* data, int X,int Y,int W,int H, int D=1)
+inline void fl_draw_image_mono(Fl_Draw_Image_Cb cb, void *data, int X, int Y, int W, int H, int D = 1) {
-  { fl_graphics_driver->draw_image_mono(cb, data, X, Y, W, H, D); }
+  fl_graphics_driver->draw_image_mono(cb, data, X, Y, W, H, D);
+}
 
 /**
-  Checks whether platform supports true alpha blending for RGBA images.
+  Check whether platform supports true alpha blending for RGBA images.
   \returns 1 if true alpha blending supported by platform
   \returns 0 not supported so FLTK will use screen door transparency
 */
-inline char fl_can_do_alpha_blending() {return Fl_Graphics_Driver::default_driver().can_do_alpha_blending();}
+inline char fl_can_do_alpha_blending() {
+  return Fl_Graphics_Driver::default_driver().can_do_alpha_blending();
+}
 
 FL_EXPORT uchar *fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha = 0);
 FL_EXPORT Fl_RGB_Image *fl_capture_window_part(Fl_Window *win, int x, int y, int w, int h);
@@ -865,9 +1012,11 @@ FL_EXPORT Fl_RGB_Image *fl_capture_window_part(Fl_Window *win, int x, int y, int
   Draw XPM image data, with the top-left corner at the given position.
   The image is dithered on 8-bit displays so you won't lose color
   space for programs displaying both images and pixmaps.
+
   \param[in] data pointer to XPM image data
   \param[in] x,y  position of top-left corner
   \param[in] bg   background color
+
   \returns 0 if there was any error decoding the XPM data.
 */
 FL_EXPORT int fl_draw_pixmap(const char *const *data, int x, int y, Fl_Color bg = FL_GRAY);
@@ -875,8 +1024,7 @@ FL_EXPORT int fl_draw_pixmap(const char* const* data, int x,int y,Fl_Color bg=FL
   Draw XPM image data, with the top-left corner at the given position.
   \see fl_draw_pixmap(const char* const* data, int x, int y, Fl_Color bg)
 */
-inline int fl_draw_pixmap(/*const*/ char* const* data, int x, int y, Fl_Color bg=FL_GRAY)
+inline int fl_draw_pixmap(/*const*/ char *const *data, int x, int y, Fl_Color bg = FL_GRAY) {
-{
   return fl_draw_pixmap((const char *const *)data, x, y, bg);
 }
 FL_EXPORT int fl_measure_pixmap(/*const*/ char *const *data, int &w, int &h);
@@ -892,9 +1040,8 @@ FL_EXPORT void fl_overlay_rect(int x,int y,int w,int h);
 FL_EXPORT void fl_overlay_clear();
 FL_EXPORT void fl_cursor(Fl_Cursor);
 FL_EXPORT void fl_cursor(Fl_Cursor, Fl_Color fg, Fl_Color bg = FL_WHITE);
-FL_EXPORT const char* fl_expand_text(const char* from, char* buf, int maxbuf,
+FL_EXPORT const char *fl_expand_text(const char *from, char *buf, int maxbuf, double maxw,
-                                     double maxw, int& n, double &width,
+                                     int &n, double &width, int wrap, int draw_symbols = 0);
-                                     int wrap, int draw_symbols = 0);
 
 // XIM:
 /** \todo provide user documentation for fl_set_status function */
@@ -905,7 +1052,6 @@ FL_EXPORT void fl_set_spot(int font, int size, int X, int Y, int W, int H, Fl_Wi
 FL_EXPORT void fl_reset_spot(void);
 
 
-
 // XForms symbols:
 FL_EXPORT int fl_draw_symbol(const char *label, int x, int y, int w, int h, Fl_Color);
 FL_EXPORT int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable);

documentation/src/drawing.dox

@@ -635,7 +635,7 @@ Add a single vertex to the current path.
 void fl_curve(double X0, double Y0, double X1, double Y1, double X2, double Y2, double X3, double Y3)
 
 \par
-Add a series of points on a Bezier curve to the path. The curve ends
+Add a series of points on a Bézier curve to the path. The curve ends
 (and two of the points are) at <tt>X0,Y0</tt> and <tt>X3,Y3</tt>.
 
 \anchor drawing_fl_arc

documentation/src/examples.dox

@@ -266,7 +266,7 @@ on few systems (some version of Irix for example).
 \subsection examples_curve curve
 
 \par
-\c curve draws a nice Bezier curve into a custom widget. The
+\c curve draws a nice Bézier curve into a custom widget. The
 <i>points</i> option for splines is not supported on all platforms.
 
 

src/fl_curve.cxx

@@ -1,5 +1,5 @@
 //
-// Bezier curve functions for the Fast Light Tool Kit (FLTK).
+// Bézier curve functions for the Fast Light Tool Kit (FLTK).
 //
 // Copyright 1998-2010 by Bill Spitzak and others.
 //
@@ -16,7 +16,7 @@
 
 /**
   \file fl_curve.cxx
-  \brief Utility for drawing Bezier curves, adding the points to the
+  \brief Utility for drawing Bézier curves, adding the points to the
          current fl_begin/fl_vertex/fl_end path.
 
   Incremental math implementation: