reworked doxygen comments for Fl::arg() and Fl::args() - part 1

harmonised parameter names in Fl.H and Fl_arg.cxx and reworked
doxygen comments to make them a bit clearer. More work required.



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7729 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman 2010-10-23 16:34:22 +00:00
parent 0cbfd64a28
commit 455b8c4a84
2 changed files with 61 additions and 47 deletions

View File

@ -176,9 +176,9 @@ public:
static double version(); static double version();
// argument parsers: // argument parsers:
static int arg(int, char**, int&); static int arg(int argc, char **argv, int& i);
static int args(int, char**, int&, Fl_Args_Handler ah = 0); static int args(int argc, char **argv, int& i, Fl_Args_Handler cb = 0);
static void args(int, char**); static void args(int argc, char **argv);
/** /**
Usage string displayed if Fl::args() detects an invalid argument. Usage string displayed if Fl::args() detects an invalid argument.
This may be changed to point to customized text at run-time. This may be changed to point to customized text at run-time.

View File

@ -68,11 +68,14 @@ extern const char *fl_bg;
extern const char *fl_bg2; extern const char *fl_bg2;
/** /**
Consume a single switch from argv, starting at word i. Parse a single switch from \p argv, starting at word \p i.
Returns the number of words eaten (1 or 2, or 0 if it is not Returns the number of words eaten (1 or 2, or 0 if it is not
recognized) and adds the same value to i. You can use this recognized) and adds the same value to \p i.
function if you prefer to control the incrementing through the
arguments yourself. You can use this function if you prefer to control the incrementing
through the standard FLTK switches yourself. If you want to handle
additional switches, you will need to provide your own argument handler
and pass it to Fl::args(int,char**,int&,Fl_Args_Handler) explicitly.
*/ */
int Fl::arg(int argc, char **argv, int &i) { int Fl::arg(int argc, char **argv, int &i) {
arg_called = 1; arg_called = 1;
@ -168,47 +171,50 @@ int Fl::arg(int argc, char **argv, int &i) {
/** /**
Consume all switches from argv. Returns number of words eaten Parse command line switches using the \p cb argument handler.
Returns zero on error. 'i' will either point at first word that
does not start with '-', at the error word, or after a '--', or at
argc. If your program does not take any word arguments you can
report an error if i < argc.
<P>FLTK provides an <I>entirely optional</I> command-line switch parser. Returns 0 on error, or the number of words eaten.
You don't have to call it if you don't like them! Everything it can do
can be done with other calls to FLTK.
<P>To use the switch parser, call Fl::args(...) near the start After the call returns, \p i will either point at the first word
of your program. This does <I>not</I> open the display, instead that does not start with '-', or the word that does not match a
switches that need the display open are stashed into static variables. valid switch, or after a '--' denoting the end of the switches,
Then you <I>must</I> display your first window by calling or at \p argc. If your program does not take any additional
window-&gt;show(argc,argv), which will do anything stored in the arguments you can report an error if <tt>i < argc</tt>.
static variables.
<P>callback lets you define your own switches. It is called FLTK provides this as an <i>entirely optional</i> command line
with the same argc and argv, and with i the switch parser. You don't have to call it if you don't want to.
index of each word. The callback should return zero if the switch is Everything it can do can be done with other calls to FLTK
unrecognized, and not change i. It should return non-zero if
the switch is recognized, and add at least 1 to i (it can add To use the switch parser, call Fl::args(...) near the start
more to consume words after the switch). This function is called of your program. This does \b not open the display, instead
<i>before</i> any other tests, so <i>you can override any FLTK switches that need the display open are stashed into static
switch</i> (this is why FLTK can use very short switches instead of variables. Then you \b must display your first window by calling
<tt>window->show(argc,argv)</tt>, which will do anything stored
in the static variables.
The \p cb argument handler lets you define your own switches.
It is called with the same \p argc and \p argv, and with \p i
the index of each word. The \p cb handler should return zero
if the switch is unrecognized, and not change \p i. It should
return non-zero if the switch is recognized, and add at least
1 to \p i (it can add more to consume words after the switch).
This \p cb handler is called \i before any other tests, so
<i>you can also override any standard FLTK switch</i>
(this is why FLTK can use very short switches instead of
the long ones all other toolkits force you to use). the long ones all other toolkits force you to use).
<P>On return i is set to the index of the first non-switch. On return \p i is set to the index of the first non-switch.
This is either: This is either:
<UL> - The first word that does not start with '-'.
<LI>The first word that does not start with '-'. </LI> - The word '-' (used by many programs to name stdin as a file)
<LI>The word '-' (used by many programs to name stdin as a file) </LI> - The first unrecognized switch (return value is 0).
<LI>The first unrecognized switch (return value is 0). </LI> - \p argc
<LI>argc</LI>
</UL>
<P>The return value is i unless an unrecognized switch is found, The return value is \p i unless an unrecognized switch is found,
in which case it is zero. If your program takes no arguments other in which case it is zero. If your program takes no arguments other
than switches you should produce an error if the return value is less than switches you should produce an error if the return value is less
than argc. than \p argc.
<P>All switches except -bg2 may be abbreviated one letter and case is ignored: <P>All switches except -bg2 may be abbreviated one letter and case is ignored:
@ -268,13 +274,13 @@ int Fl::arg(int argc, char **argv, int &i) {
</UL> </UL>
<P>The second form of Fl::args() is useful if your program does A usage string is displayed if Fl::args() detects an invalid argument
not have command line switches of its own. It parses all the switches, on the command-line. You can change the message by setting the
and if any are not recognized it calls Fl::abort(Fl::help).
<P>A usage string is displayed if Fl::args() detects an invalid
argument on the command-line. You can change the message by setting the
Fl::help pointer. Fl::help pointer.
The simpler Fl::args(int argc, char **argv) form is useful if your program
does not have command line switches of its own. It parses all the switches,
and if any are not recognized it calls Fl::abort(Fl::help).
*/ */
int Fl::args(int argc, char** argv, int& i, Fl_Args_Handler cb) { int Fl::args(int argc, char** argv, int& i, Fl_Args_Handler cb) {
@ -387,7 +393,15 @@ static const char * const helpmsg =
" -to[oltips]"; " -to[oltips]";
const char * const Fl::help = helpmsg+13; const char * const Fl::help = helpmsg+13;
/** See Fl::args(int argc, char **argv, int& i, int (*cb)(int,char**,int&)) */
/**
* Parse all command line switches matching standard FLTK options only.
*
* This calls Fl::args(int,char**,int&,Fl_Args_Handler) with the
* argument handler set to the Fl::arg(int,char**,int&) function.
*
* Note: an unexpected switch will cause an error message and program exit.
*/
void Fl::args(int argc, char **argv) { void Fl::args(int argc, char **argv) {
int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg); int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg);
} }