X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/97d590469d4aaa67459aa4f041ea9bfa409dbecb..3cc305b2b4a0674c56c84d7088cfd70676b850f0:/docs/latex/wx/cmdlpars.tex?ds=sidebyside

diff --git a/docs/latex/wx/cmdlpars.tex b/docs/latex/wx/cmdlpars.tex
index c7164c0163..e7ab669a51 100644
--- a/docs/latex/wx/cmdlpars.tex
+++ b/docs/latex/wx/cmdlpars.tex
@@ -11,10 +11,11 @@
 
 \section{\class{wxCmdLineParser}}\label{wxcmdlineparser}
 
-wxCmdLineParser is a class for parsing command line.
+wxCmdLineParser is a class for parsing the command line.
 
 It has the following features:
-\begin{enumerate}
+
+\begin{enumerate}\itemsep=0pt
 \item distinguishes options, switches and parameters; allows option grouping
 \item allows both short and long options
 \item automatically generates the usage message from the command line description
@@ -22,7 +23,8 @@ It has the following features:
 \end{enumerate}
 
 To use it you should follow these steps:
-\begin{enumerate}
+
+\begin{enumerate}\itemsep=0pt
 \item \helpref{construct}{wxcmdlineparserconstruction} an object of this class
 giving it the command line to parse and optionally its description or use 
 {\tt AddXXX()} functions later
@@ -51,6 +53,10 @@ No base class
 
 <wx/cmdline.h>
 
+\wxheading{Library}
+
+\helpref{wxBase}{librarieslist}
+
 \wxheading{Constants}
 
 The structure wxCmdLineEntryDesc is used to describe the one command
@@ -73,15 +79,18 @@ struct wxCmdLineEntryDesc
 
 The type of a command line entity is in the {\tt kind} field and may be one of
 the following constants:
-{\small \begin{verbatim}
+
+{\small%
+\begin{verbatim}
 enum wxCmdLineEntryType
 {
-    wxCMD\_LINE\_SWITCH,
-    wxCMD\_LINE\_OPTION,
-    wxCMD\_LINE\_PARAM,
-    wxCMD\_LINE\_NONE         // use this to terminate the list
+    wxCMD_LINE_SWITCH,
+    wxCMD_LINE_OPTION,
+    wxCMD_LINE_PARAM,
+    wxCMD_LINE_NONE         // use this to terminate the list
+}
+\end{verbatim}
 }
-\end{verbatim}}
 
 The field {\tt shortName} is the usual, short, name of the switch or the option.
 {\tt longName} is the corresponding long name or NULL if the option has no long
@@ -93,27 +102,33 @@ to construct a help message explaining the syntax of the program.
 
 The possible values of {\tt type} which specifies the type of the value accepted
 by an option or parameter are:
-{\small \begin{verbatim}
+
+{\small%
+\begin{verbatim}
 enum wxCmdLineParamType
 {
-    wxCMD\_LINE\_VAL\_STRING,  // default
-    wxCMD\_LINE\_VAL\_NUMBER,
-    wxCMD\_LINE\_VAL\_DATE,
-    wxCMD\_LINE\_VAL\_NONE
+    wxCMD_LINE_VAL_STRING,  // default
+    wxCMD_LINE_VAL_NUMBER,
+    wxCMD_LINE_VAL_DATE,
+    wxCMD_LINE_VAL_NONE
+}
+\end{verbatim}
 }
-\end{verbatim}}
 
 Finally, the {\tt flags} field is a combination of the following bit masks:
-{\small \begin{verbatim}
+
+{\small%
+\begin{verbatim}
 enum
 {
-    wxCMD\_LINE\_OPTION\_MANDATORY = 0x01, // this option must be given
-    wxCMD\_LINE\_PARAM\_OPTIONAL   = 0x02, // the parameter may be omitted
-    wxCMD\_LINE\_PARAM\_MULTIPLE   = 0x04, // the parameter may be repeated
-    wxCMD\_LINE\_OPTION\_HELP      = 0x08, // this option is a help request
-    wxCMD\_LINE\_NEEDS\_SEPARATOR  = 0x10, // must have sep before the value
+    wxCMD_LINE_OPTION_MANDATORY = 0x01, // this option must be given
+    wxCMD_LINE_PARAM_OPTIONAL   = 0x02, // the parameter may be omitted
+    wxCMD_LINE_PARAM_MULTIPLE   = 0x04, // the parameter may be repeated
+    wxCMD_LINE_OPTION_HELP      = 0x08, // this option is a help request
+    wxCMD_LINE_NEEDS_SEPARATOR  = 0x10, // must have sep before the value
+}
+\end{verbatim}
 }
-\end{verbatim}}
 
 Notice that by default (i.e. if flags are just $0$), options are optional (sic)
 and each call to \helpref{AddParam()}{wxcmdlineparseraddparam} allows one more
@@ -139,6 +154,7 @@ console sample
 %%%%%%%%%%%%% Methods by group %%%%%%%%%%%%%
 \latexignore{\rtfignore{\wxheading{Function groups}}}
 
+
 \membersection{Construction}\label{wxcmdlineparserconstruction}
 
 Before \helpref{Parse}{wxcmdlineparserparse} can be called, the command line
@@ -151,15 +167,13 @@ the only restriction is that it must be done before calling
 \helpref{Parse}{wxcmdlineparserparse}.
 
 To specify the command line to parse you may use either one of constructors
-accepting it (\helpref{wxCmdLineParser(argc, argv)}{wxcmdlineparserwxcmdlineparserargc} or 
-\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdescargc} usually) or,
-if you use \helpref{the default constructor}{wxcmdlineparserwxcmdlineparserdef},
-you can do it later by calling 
-\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc}.
+accepting it (\tt{wxCmdLineParser(argc, argv)} or \tt{wxCmdLineParser(const wxString&)} usually) 
+or, if you use the default constructor, you can do it later by calling 
+\helpref{SetCmdLine}{wxcmdlineparsersetcmdline}.
 
 The same holds for command line description: it can be specified either in
-the constructor (\helpref{without command line}{wxcmdlineparserwxcmdlineparserdesc} or 
-\helpref{together with it}{wxcmdlineparserwxcmdlineparserdescargc}) or
+the constructor (\helpref{without\ command\ line}{wxcmdlineparserwxcmdlineparser} or 
+\helpref{together\ with\ it}{wxcmdlineparserwxcmdlineparserdescargc}) or
 constructed later using either \helpref{SetDesc}{wxcmdlineparsersetdesc} or
 combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch}, 
 \helpref{AddOption}{wxcmdlineparseraddoption} and 
@@ -167,9 +181,10 @@ combination of \helpref{AddSwitch}{wxcmdlineparseraddswitch},
 
 Using constructors or \helpref{SetDesc}{wxcmdlineparsersetdesc} uses a (usually 
 {\tt const static}) table containing the command line description. If you want
-to decide which options to acccept during the run-time, using one of the 
+to decide which options to accept during the run-time, using one of the 
 {\tt AddXXX()} functions above might be preferable.
 
+
 \membersection{Customization}\label{wxcmdlineparsercustomization}
 
 wxCmdLineParser has several global options which may be changed by the
@@ -194,6 +209,7 @@ Finally, \helpref{SetLogo}{wxcmdlineparsersetlogo} can be used to show some
 application-specific text before the explanation given by 
 \helpref{Usage}{wxcmdlineparserusage} function.
 
+
 \membersection{Parsing command line}\label{wxcmdlineparserparsing}
 
 After the command line description was constructed and the desired options were
@@ -204,7 +220,8 @@ terminate after this) or a positive number if there was an error during the
 command line parsing.
 
 In the latter case, the appropriate error message and usage information are
-logged by wxCmdLineParser itself using the standard wxWindows logging functions.
+logged by wxCmdLineParser itself using the standard wxWidgets logging functions.
+
 
 \membersection{Getting results}\label{wxcmdlineparsergettingresults}
 
@@ -213,11 +230,11 @@ you may access the results of parsing using one of overloaded {\tt Found()}
 methods.
 
 For a simple switch, you will simply call 
-\helpref{Found}{wxcmdlineparserfoundswitch} to determine if the switch was given
+\helpref{Found}{wxcmdlineparserfound} to determine if the switch was given
 or not, for an option or a parameter, you will call a version of {\tt Found()} 
 which also returns the associated value in the provided variable. All 
-{\tt Found()} functions return TRUE if the switch or option were found in the
-command line or FALSE if they were not specified.
+{\tt Found()} functions return true if the switch or option were found in the
+command line or false if they were not specified.
 
 %%%%%%%%%%%%% Methods in alphabetic order %%%%%%%%%%%%%
 \helponly{\insertatlevel{2}{
@@ -226,69 +243,73 @@ command line or FALSE if they were not specified.
 
 }}
 
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdef}
+
+\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparser}
 
 \func{}{wxCmdLineParser}{\void}
 
 Default constructor. You must use 
-\helpref{SetCmdLine}{wxcmdlineparsersetcmdlineargc} later.
+\helpref{SetCmdLine}{wxcmdlineparsersetcmdline} later.
 
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserargc}
+\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc}
 
 \func{}{wxCmdLineParser}{\param{int }{argc}, \param{char** }{argv}}
 
-Constructor specifies the command line to parse. This is the traditional
+\func{}{wxCmdLineParser}{\param{int }{argc}, \param{wchar\_t** }{argv}}
+
+Constructors which specify the command line to parse. This is the traditional
 (Unix) command line format. The parameters {\it argc} and {\it argv} have the
 same meaning as for {\tt main()} function.
 
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserstr}
+The second overloaded constructor is only available in Unicode build. The
+first one is available in both ANSI and Unicode modes because under some
+platforms the command line arguments are passed as ASCII strings even to
+Unicode programs.
 
 \func{}{wxCmdLineParser}{\param{const wxString\& }{cmdline}}
 
-Constructor specifies the command line to parse in Windows format. The parameter 
+Constructor which specify the command line to parse in Windows format. The parameter 
 {\it cmdline} has the same meaning as the corresponding parameter of 
 {\tt WinMain()}.
 
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdesc}
-
 \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}}
 
-Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserdef}, but also
-specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
-
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescargc}
+Specifies the \helpref{command line description}{wxcmdlineparsersetdesc} but not the
+command line. You must use \helpref{SetCmdLine}{wxcmdlineparsersetcmdline} later.
 
 \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{int }{argc}, \param{char** }{argv}}
 
-Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}, but also
-specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
-
-\membersection{wxCmdLineParser::wxCmdLineParser}\label{wxcmdlineparserwxcmdlineparserdescstr}
+Specifies both the command line (in Unix format) and the 
+\helpref{command line description}{wxcmdlineparsersetdesc}.
 
 \func{}{wxCmdLineParser}{\param{const wxCmdLineEntryDesc* }{desc}, \param{const wxString\& }{cmdline}}
 
-Same as \helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}, but also
-specifies the \helpref{command line description}{wxcmdlineparsersetdesc}.
+Specifies both the command line (in Windows format) and the 
+\helpref{command line description}{wxcmdlineparsersetdesc}.
 
-\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlineargc}
+\membersection{wxCmdLineParser::ConvertStringToArgs}\label{wxcmdlineparserconvertstringtoargs}
 
-\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
+\func{static wxArrayString}{ConvertStringToArgs}{\param{const wxChar }{*cmdline}}
 
-Set command line to parse after using one of the constructors which don't do it.
+Breaks down the string containing the full command line in words. The words are
+separated by whitespace. The quotes can be used in the input string to quote
+the white space and the back slashes can be used to quote the quotes.
 
-\wxheading{See also}
 
-\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserargc}
+\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdline}
 
-\membersection{wxCmdLineParser::SetCmdLine}\label{wxcmdlineparsersetcmdlinestr}
+\func{void}{SetCmdLine}{\param{int }{argc}, \param{char** }{argv}}
+
+\func{void}{SetCmdLine}{\param{int }{argc}, \param{wchar\_t** }{argv}}
+
+Set command line to parse after using one of the constructors which don't do it.
+The second overload of this function is only available in Unicode build.
 
 \func{void}{SetCmdLine}{\param{const wxString\& }{cmdline}}
 
 Set command line to parse after using one of the constructors which don't do it.
 
-\wxheading{See also}
 
-\helpref{wxCmdLineParser}{wxcmdlineparserwxcmdlineparserstr}
 
 \membersection{wxCmdLineParser::\destruct{wxCmdLineParser}}\label{wxcmdlineparserdtor}
 
@@ -298,6 +319,7 @@ Frees resources allocated by the object.
 
 {\bf NB:} destructor is not virtual, don't use this class polymorphically.
 
+
 \membersection{wxCmdLineParser::SetSwitchChars}\label{wxcmdlineparsersetswitchchars}
 
 \func{void}{SetSwitchChars}{\param{const wxString\& }{switchChars}}
@@ -305,9 +327,10 @@ Frees resources allocated by the object.
 {\it switchChars} contains all characters with which an option or switch may
 start. Default is {\tt "-"} for Unix, {\tt "-/"} for Windows.
 
+
 \membersection{wxCmdLineParser::EnableLongOptions}\label{wxcmdlineparserenablelongoptions}
 
-\func{void}{EnableLongOptions}{\param{bool }{enable = TRUE}}
+\func{void}{EnableLongOptions}{\param{bool }{enable = true}}
 
 Enable or disable support for the long options.
 
@@ -316,13 +339,26 @@ them.
 
 \wxheading{See also}
 
-\helpref{Customization}{wxcmdlineparsercustomization}
+\helpref{Customization}{wxcmdlineparsercustomization} and \helpref{AreLongOptionsEnabled}{wxcmdlineparserarelongoptionsenabled}
+
 
 \membersection{wxCmdLineParser::DisableLongOptions}\label{wxcmdlineparserdisablelongoptions}
 
 \func{void}{DisableLongOptions}{\void}
 
-Ientical to \helpref{EnableLongOptions(FALSE)}{wxcmdlineparserenablelongoptions}.
+Identical to \helpref{EnableLongOptions(false)}{wxcmdlineparserenablelongoptions}.
+
+
+\membersection{wxCmdLineParser::AreLongOptionsEnabled}\label{wxcmdlineparserarelongoptionsenabled}
+
+\func{bool}{AreLongOptionsEnabled}{\void}
+
+Returns true if long options are enabled, otherwise false.
+
+\wxheading{See also}
+
+\helpref{EnableLongOptions}{wxcmdlineparserenablelongoptions}
+
 
 \membersection{wxCmdLineParser::SetLogo}\label{wxcmdlineparsersetlogo}
 
@@ -331,6 +367,7 @@ Ientical to \helpref{EnableLongOptions(FALSE)}{wxcmdlineparserenablelongoptions}
 {\it logo} is some extra text which will be shown by 
 \helpref{Usage}{wxcmdlineparserusage} method.
 
+
 \membersection{wxCmdLineParser::SetDesc}\label{wxcmdlineparsersetdesc}
 
 \func{void}{SetDesc}{\param{const wxCmdLineEntryDesc* }{desc}}
@@ -362,6 +399,7 @@ wxCmdLineParser parser;
 parser.SetDesc(cmdLineDesc);
 \end{verbatim}
 
+
 \membersection{wxCmdLineParser::AddSwitch}\label{wxcmdlineparseraddswitch}
 
 \func{void}{AddSwitch}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{int }{flags = 0}}
@@ -370,6 +408,7 @@ Add a switch {\it name} with an optional long name {\it lng} (no long name if it
 is empty, which is default), description {\it desc} and flags {\it flags} to the
 command line description.
 
+
 \membersection{wxCmdLineParser::AddOption}\label{wxcmdlineparseraddoption}
 
 \func{void}{AddOption}{\param{const wxString\& }{name}, \param{const wxString\& }{lng = wxEmptyString}, \param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}}
@@ -378,19 +417,30 @@ Add an option {\it name} with an optional long name {\it lng} (no long name if
 it is empty, which is default) taking a value of the given type (string by
 default) to the command line description.
 
+
 \membersection{wxCmdLineParser::AddParam}\label{wxcmdlineparseraddparam}
 
 \func{void}{AddParam}{\param{const wxString\& }{desc = wxEmptyString}, \param{wxCmdLineParamType }{type = wxCMD\_LINE\_VAL\_STRING}, \param{int }{flags = 0}}
 
 Add a parameter of the given {\it type} to the command line description.
 
+
 \membersection{wxCmdLineParser::Parse}\label{wxcmdlineparserparse}
 
-\func{int}{Parse}{\void}
+\func{int}{Parse}{\param{bool }{giveUsage = {\tt true}}}
 
 Parse the command line, return $0$ if ok, $-1$ if {\tt "-h"} or {\tt "--help"} 
 option was encountered and the help message was given or a positive value if a
-syntax error occured.
+syntax error occurred.
+
+\wxheading{Parameters}
+
+\docparam{giveUsage}{If {\tt true} (default), the usage message is given if a
+syntax error was encountered while parsing the command line or if help was
+requested. If {\tt false}, only error messages about possible syntax errors
+are given, use \helpref{Usage}{wxcmdlineparserusage} to show the usage message
+from the caller if needed.}
+
 
 \membersection{wxCmdLineParser::Usage}\label{wxcmdlineparserusage}
 
@@ -404,33 +454,29 @@ will not be helpful to the user unless the descriptions were indeed specified.
 
 \helpref{SetLogo}{wxcmdlineparsersetlogo}
 
-\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundswitch}
 
-\constfunc{bool}{Found}{\param{const wxString\& }{name}}
+\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfound}
 
-Returns TRUE if the given switch was found, FALSE otherwise.
+\constfunc{bool}{Found}{\param{const wxString\& }{name}}
 
-\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundstringoption}
+Returns \true if the given switch was found, false otherwise.
 
 \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxString* }{value}}
 
-Returns TRUE if an option taking a string value was found and stores the
+Returns \true if an option taking a string value was found and stores the
 value in the provided pointer (which should not be NULL).
 
-\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfoundintoption}
-
 \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{long* }{value}}
 
-Returns TRUE if an option taking an integer value was found and stores
+Returns \true if an option taking an integer value was found and stores
 the value in the provided pointer (which should not be NULL).
 
-\membersection{wxCmdLineParser::Found}\label{wxcmdlineparserfounddateoption}
-
 \constfunc{bool}{Found}{\param{const wxString\& }{name}, \param{wxDateTime* }{value}}
 
-Returns TRUE if an option taking a date value was found and stores the
+Returns \true if an option taking a date value was found and stores the
 value in the provided pointer (which should not be NULL).
 
+
 \membersection{wxCmdLineParser::GetParamCount}\label{wxcmdlineparsergetparamcount}
 
 \constfunc{size\_t}{GetParamCount}{\void}
@@ -438,11 +484,12 @@ value in the provided pointer (which should not be NULL).
 Returns the number of parameters found. This function makes sense mostly if you
 had used {\tt wxCMD\_LINE\_PARAM\_MULTIPLE} flag.
 
+
 \membersection{wxCmdLineParser::GetParam}\label{wxcmdlineparsergetparam}
 
 \constfunc{wxString}{GetParam}{\param{size\_t }{n = 0u}}
 
-Returns the value of Nth parameter (as string only for now).
+Returns the value of Nth parameter (as string only).
 
 \wxheading{See also}
 
