So this
issue came up on fltk.discussions regarding the use of
fl_arc(), where three people including myself were probably more
confused than we should have been about why one of the two forms
of the fl_arc() functions wasn't drawing at all.
After solving, I offered the confusion could be avoided by a small
clarification in the documentation (red highlighted paragraphs
below):
Normally I would just make the change, but fl_arc() is not a
function I use much, and wanted to make sure in clarifying, I
wasn't missing some other details or drawing contexts, as I
think some of you other developers are more familiar with the
internals of this than I am.
I'm generally fine with the suggested changes, and I would also add
what Manolo proposed to clarify it even more.
However, I'm not sure if "Valid path types are \c points, \c line,
\c loop, \c polygon, and \c complex_polygon" is correct in this
context. Can all these path types be combined with arcs ? I'm
leaving this open for now.
Another point for better documentation experience (doxygen related):
I would change
"Unlike the integer-coordinate \c
fl_arc(x,y,w,h,a1,a2) overload"
to
"Unlike the integer-coordinate fl_arc(int,
int, int, int, double, double) overload".
Note: remove "\c" and let doxygen's
auto-link feature create a link to the docs of that
integer-coordinate function (tested, works well, see screenshot
below).
Furthermore, the given example is superfluous, because there are
already examples below the image.
My suggestion would therefore be:
```diff
diff --git a/FL/fl_draw.H b/FL/fl_draw.H
index e936de5ab..a13814a0e 100644
--- a/FL/fl_draw.H
+++ b/FL/fl_draw.H
@@ -634,6 +634,13 @@ inline void fl_curve(double X0, double Y0, double X1, double Y1, double X2, doub
/**
Add a series of points to the current path on the arc of a circle.
+ Unlike the fl_arc(int, int, int, int, double, double) overload that uses
+ integer coordinates, this function is not a standalone drawing operation.
+ It requires an active path; that is, it must be enclosed by corresponding calls
+ to `fl_begin_*()` and `fl_end_*()`.
+ Valid path types are \c points, \c line, \c loop, \c polygon, and \c complex_polygon.
+ See examples below.
+
The arc is drawn counter-clockwise from 3 o'clock. If \p end is less than
\p start then it draws the arc in a clockwise direction. To draw an arc across
the 3 o'clock line, \p start and \p end can be greater than 360 or less than 0.
```
Note: I used google translate to translate the text to German and
back to English for better wording than my own. Feel free to improve
this.
I think there's another section as well in the "drawing with
fltk" where this info might be duplicated, and thus a similar
change done there as well.
I'm not a friend of duplicating the same information "everywhere".
My general suggestion to change the docs would be to enhance the
chapter "Drawing Things in FLTK" with all required information (and
examples?) and to refer to this wherever needed so the docs in the
code can be shorter (like a reference manual should be) but link to
the detailed info for users that need it. However, this is more like
a long-term solution than a quick fix.
Screenshot (note the generated link to the integer version):
Comments are owned by the poster. All other content is copyright 1998-2026 by Bill Spitzak and others. This project is hosted by The FLTK Team. Please report site problems to 'erco@seriss.com'.
