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();
// argument parsers:
static int arg(int, char**, int&);
static int args(int, char**, int&, Fl_Args_Handler ah = 0);
static void args(int, char**);
static int arg(int argc, char **argv, int& i);
static int args(int argc, char **argv, int& i, Fl_Args_Handler cb = 0);
static void args(int argc, char **argv);
/**
Usage string displayed if Fl::args() detects an invalid argument.
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;
/**
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
recognized) and adds the same value to i. You can use this
function if you prefer to control the incrementing through the
arguments yourself.
recognized) and adds the same value to \p i.
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) {
arg_called = 1;
@ -167,48 +170,51 @@ int Fl::arg(int argc, char **argv, int &i) {
}
/**
Consume all switches from argv. Returns number of words eaten
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.
/**
Parse command line switches using the \p cb argument handler.
<P>FLTK provides an <I>entirely optional</I> command-line switch parser.
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.
Returns 0 on error, or the number of words eaten.
<P>To use the switch parser, call Fl::args(...) near the start
of your program. This does <I>not</I> open the display, instead
switches that need the display open are stashed into static variables.
Then you <I>must</I> display your first window by calling
window-&gt;show(argc,argv), which will do anything stored in the
static variables.
After the call returns, \p i will either point at the first word
that does not start with '-', or the word that does not match a
valid switch, or after a '--' denoting the end of the switches,
or at \p argc. If your program does not take any additional
arguments you can report an error if <tt>i < argc</tt>.
<P>callback lets you define your own switches. It is called
with the same argc and argv, and with i the
index of each word. The callback should return zero if the switch is
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
more to consume words after the switch). This function is called
<i>before</i> any other tests, so <i>you can override any FLTK
switch</i> (this is why FLTK can use very short switches instead of
FLTK provides this as an <i>entirely optional</i> command line
switch parser. You don't have to call it if you don't want to.
Everything it can do can be done with other calls to FLTK
To use the switch parser, call Fl::args(...) near the start
of your program. This does \b not open the display, instead
switches that need the display open are stashed into static
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).
<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:
<UL>
<LI>The first word that does not start with '-'. </LI>
<LI>The word '-' (used by many programs to name stdin as a file) </LI>
<LI>The first unrecognized switch (return value is 0). </LI>
<LI>argc</LI>
</UL>
- The first word that does not start with '-'.
- The word '-' (used by many programs to name stdin as a file)
- The first unrecognized switch (return value is 0).
- \p argc
<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
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:
@ -268,13 +274,13 @@ int Fl::arg(int argc, char **argv, int &i) {
</UL>
<P>The second form of Fl::args() 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).
<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
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.
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) {
@ -387,7 +393,15 @@ static const char * const helpmsg =
" -to[oltips]";
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) {
int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg);
}