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
parent
0cbfd64a28
commit
455b8c4a84
6
FL/Fl.H
6
FL/Fl.H
@ -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.
|
||||
|
||||
@ -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;
|
||||
@ -168,47 +171,50 @@ 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->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);
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user