reworked doxygen comments for Fl::arg() and Fl::args() - part 2
added a note to examples.dox about the 'examples' directory updated Fl_arg.cxx to move the description of standard FLTK options to Fl::arg() and simplified/rationalized the Fl::args() description. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7731 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
engelsman
parent
10ebe9f862
commit
7e2590ddea
@ -13,6 +13,10 @@ Most of the example programs were created while testing a group of widgets.
|
||||
They are not meant to be great achievements in clean C++ programming, but
|
||||
merely a test platform to verify the functionality of the FLTK library.
|
||||
|
||||
Note that extra example programs are also available in an additional
|
||||
'examples' directory, but these are \b NOT built automatically when
|
||||
you build FLTK, unlike those in the 'test' directory shown below.
|
||||
|
||||
\section example_applications Example Applications
|
||||
|
||||
<table width=100% border=0>
|
||||
|
||||
179
src/Fl_arg.cxx
179
src/Fl_arg.cxx
@ -72,10 +72,69 @@ extern const char *fl_bg2;
|
||||
Returns the number of words eaten (1 or 2, or 0 if it is not
|
||||
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.
|
||||
This is the default argument handler used internally by Fl::args(...),
|
||||
but you can use this function if you prefer to step through the
|
||||
standard FLTK switches yourself.
|
||||
|
||||
All standard FLTK switches except -bg2 may be abbreviated to just
|
||||
one letter and case is ignored:
|
||||
|
||||
\li -bg color or -background color
|
||||
<br>
|
||||
Sets the background color using Fl::background().
|
||||
|
||||
\li -bg2 color or -background2 color
|
||||
<br>
|
||||
Sets the secondary background color using Fl::background2().
|
||||
|
||||
\li -display host:n.n
|
||||
<br>
|
||||
Sets the X display to use; this option is silently
|
||||
ignored under WIN32 and MacOS.
|
||||
|
||||
\li -dnd and -nodnd
|
||||
<br>
|
||||
Enables or disables drag and drop text operations
|
||||
using Fl::dnd_text_ops().
|
||||
|
||||
\li -fg color or -foreground color
|
||||
<br>
|
||||
Sets the foreground color using Fl::foreground().
|
||||
|
||||
\li -geometry WxH+X+Y
|
||||
<br>
|
||||
Sets the initial window position and size according
|
||||
to the standard X geometry string.
|
||||
|
||||
\li -iconic
|
||||
<br>
|
||||
Iconifies the window using Fl_Window::iconize().
|
||||
|
||||
\li -kbd and -nokbd
|
||||
<br>
|
||||
Enables or disables visible keyboard focus for
|
||||
non-text widgets using Fl::visible_focus().
|
||||
|
||||
\li -name string
|
||||
<br>
|
||||
Sets the window class using Fl_Window::xclass().
|
||||
|
||||
\li -scheme string
|
||||
<br>
|
||||
Sets the widget scheme using Fl::scheme().
|
||||
|
||||
\li -title string
|
||||
<br>
|
||||
Sets the window title using Fl_Window::label().
|
||||
|
||||
\li -tooltips and -notooltips
|
||||
<br>
|
||||
Enables or disables tooltips using Fl_Tooltip::enable().
|
||||
|
||||
|
||||
If your program requires other switches in addition to the standard
|
||||
FLTK options, you will need to pass your own argument handler to
|
||||
Fl::args(int,char**,int&,Fl_Args_Handler) explicitly.
|
||||
*/
|
||||
int Fl::arg(int argc, char **argv, int &i) {
|
||||
arg_called = 1;
|
||||
@ -173,17 +232,11 @@ int Fl::arg(int argc, char **argv, int &i) {
|
||||
/**
|
||||
Parse command line switches using the \p cb argument handler.
|
||||
|
||||
Returns 0 on error, or the number of words eaten.
|
||||
|
||||
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>.
|
||||
Returns 0 on error, or the number of words processed.
|
||||
|
||||
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
|
||||
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
|
||||
@ -192,95 +245,43 @@ int Fl::arg(int argc, char **argv, int &i) {
|
||||
<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
|
||||
Providing an argument handler callback \p cb lets you define
|
||||
your own switches. It is called with the same \p argc and \p argv,
|
||||
and with \p i set to the index of the switch to be processed.
|
||||
The \p cb handler should return zero if the switch is unrecognized,
|
||||
and not change \p i. It should return non-zero to indicate the
|
||||
number of words processed if the switch is recognized, i.e. 1 for
|
||||
just the switch, and more than 1 for the switch plus associated
|
||||
parameters. \p i should be incremented by the same amount.
|
||||
|
||||
The \p cb handler is called \b 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).
|
||||
See Fl::arg() for descriptions of the standard switches.
|
||||
|
||||
On return \p i is set to the index of the first non-switch.
|
||||
This is either:
|
||||
|
||||
- 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
|
||||
\li The first word that does not start with '-'.
|
||||
\li The word '-' (used by many programs to name stdin as a file)
|
||||
\li The first unrecognized switch (return value is 0).
|
||||
\li \p argc
|
||||
|
||||
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 \p argc.
|
||||
|
||||
<P>All switches except -bg2 may be abbreviated one letter and case is ignored:
|
||||
|
||||
<UL>
|
||||
|
||||
<LI>-bg color or -background color
|
||||
|
||||
<P>Sets the background color using Fl::background().</LI>
|
||||
|
||||
<LI>-bg2 color or -background2 color
|
||||
|
||||
<P>Sets the secondary background color using Fl::background2().</LI>
|
||||
|
||||
<LI>-display host:n.n
|
||||
|
||||
<P>Sets the X display to use; this option is silently
|
||||
ignored under WIN32 and MacOS.</LI>
|
||||
|
||||
<LI>-dnd and -nodnd
|
||||
|
||||
<P>Enables or disables drag and drop text operations
|
||||
using Fl::dnd_text_ops().</LI>
|
||||
|
||||
<LI>-fg color or -foreground color
|
||||
|
||||
<P>Sets the foreground color using Fl::foreground().</LI>
|
||||
|
||||
<LI>-geometry WxH+X+Y
|
||||
|
||||
<P>Sets the initial window position and size according
|
||||
to the standard X geometry string.</LI>
|
||||
|
||||
<LI>-iconic
|
||||
|
||||
<P>Iconifies the window using Fl_Window::iconize().</LI>
|
||||
|
||||
<LI>-kbd and -nokbd
|
||||
|
||||
<P>Enables or disables visible keyboard focus for
|
||||
non-text widgets using Fl::visible_focus().</LI>
|
||||
|
||||
<LI>-name string
|
||||
|
||||
<P>Sets the window class using Fl_Window::xclass().</LI>
|
||||
|
||||
<LI>-scheme string
|
||||
|
||||
<P>Sets the widget scheme using Fl::scheme().</LI>
|
||||
|
||||
<LI>-title string
|
||||
|
||||
<P>Sets the window title using Fl_Window::label().</LI>
|
||||
|
||||
<LI>-tooltips and -notooltips
|
||||
|
||||
<P>Enables or disables tooltips using Fl_Tooltip::enable().</LI>
|
||||
|
||||
</UL>
|
||||
|
||||
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.
|
||||
|
||||
A very simple command line parser can be found in <tt>examples/howto-parse-args.cxx</tt>
|
||||
|
||||
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).
|
||||
does not have command line switches of its own.
|
||||
*/
|
||||
|
||||
int Fl::args(int argc, char** argv, int& i, Fl_Args_Handler cb) {
|
||||
@ -395,12 +396,12 @@ static const char * const helpmsg =
|
||||
const char * const Fl::help = helpmsg+13;
|
||||
|
||||
/**
|
||||
* 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.
|
||||
Parse all command line switches matching standard FLTK options only.
|
||||
|
||||
It parses all the switches, and if any are not recognized it calls
|
||||
Fl::abort(Fl::help), i.e. unlike the long form, an unrecognized
|
||||
switch generates an error message and causes the program to exit.
|
||||
|
||||
*/
|
||||
void Fl::args(int argc, char **argv) {
|
||||
int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg);
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user