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