Add wxPopupWindow

[wxWidgets.git] / interface / cmdline.h

diff --git a/interface/cmdline.h b/interface/cmdline.h
index 1345a6ea415cc6adfcb879ca544a59ad22ddf94b..11d7b27d758a599a9c9a4b07a5aef35dc949e3ff 100644 (file)
--- a/interface/cmdline.h
+++ b/interface/cmdline.h
@@ -6,6 +6,84 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+/**
+    wxCmdLineEntryDesc::flags field is a combination of these bit masks.
+
+    Notice that by default (i.e. if flags are just 0), options are optional
+    (sic) and each call to wxCmdLineEntryDesc::AddParam() allows one more
+    parameter - this may be changed by giving non-default flags to it, i.e. use
+    wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
+    wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional. Also,
+    wxCMD_LINE_PARAM_MULTIPLE may be specified if the programs accepts a
+    variable number of parameters - but it only can be given for the last
+    parameter in the command line description. If you use this flag, you will
+    probably need to use wxCmdLineEntryDesc::GetParamCount() to retrieve the
+    number of parameters effectively specified after calling
+    wxCmdLineEntryDesc::Parse().
+
+    wxCMD_LINE_NEEDS_SEPARATOR can be specified to require a separator (either
+    a colon, an equal sign or white space) between the option name and its
+    value. By default, no separator is required.
+*/
+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 a separator before the value.
+};
+
+/**
+    The possible values of wxCmdLineEntryDesc::type which specifies the type of
+    the value accepted by an option.
+*/
+enum wxCmdLineParamType
+{
+    wxCMD_LINE_VAL_STRING,
+    wxCMD_LINE_VAL_NUMBER,
+    wxCMD_LINE_VAL_DATE,
+    wxCMD_LINE_VAL_DOUBLE,
+    wxCMD_LINE_VAL_NONE
+};
+
+/**
+    The type of a command line entity used for wxCmdLineEntryDesc::kind.
+*/
+enum wxCmdLineEntryType
+{
+    wxCMD_LINE_SWITCH,
+    wxCMD_LINE_OPTION,
+    wxCMD_LINE_PARAM,
+    wxCMD_LINE_NONE     ///< Use this to terminate the list.
+};
+
+/**
+    The structure wxCmdLineEntryDesc is used to describe the one command line
+    switch, option or parameter. An array of such structures should be passed
+    to wxCmdLineParser::SetDesc(). Also, the meanings of parameters of the
+    wxCmdLineParser::AddXXX() functions are the same as of the corresponding
+    fields in this structure.
+
+    The field @c shortName is the usual, short, name of the switch or the
+    option. @c longName is the corresponding long name or empty if the option
+    has no long name. Both of these fields are unused for the parameters. Both
+    the short and long option names can contain only letters, digits and the
+    underscores.
+
+    @c description is used by the wxCmdLineEntryDesc::Usage() method to
+    construct a help message explaining the syntax of the program.
+*/
+struct wxCmdLineEntryDesc
+{
+    wxCmdLineEntryType kind;
+    const char *shortName;
+    const char *longName;
+    const char *description;
+    wxCmdLineParamType type;
+    int flags;
+};
+

 /**
     @class wxCmdLineParser
     @wxheader{cmdline.h}
 /**
     @class wxCmdLineParser
     @wxheader{cmdline.h}


@@ -14,81 +92,176 @@
 
     It has the following features:
 
 
     It has the following features:
 

-     distinguishes options, switches and parameters; allows option grouping
-     allows both short and long options
-     automatically generates the usage message from the command line description
-     does type checks on the options values (number, date, ...).
+    - distinguishes options, switches and parameters
+    - allows option grouping
+    - allows both short and long options
+    - automatically generates the usage message from the command line description
+    - checks types of the options values (number, date, ...).

 
     To use it you should follow these steps:
 
 
     To use it you should follow these steps:
 

-     @ref wxCmdLineParser::construction construct an object of this class
-    giving it the command line to parse and optionally its description or use
-    @c AddXXX() functions later
-     call @c Parse()
-     use @c Found() to retrieve the results
+    -# @ref cmdlineparser_construction "Construct" an object of this class
+       giving it the command line to parse and optionally its description or
+       use the @c AddXXX() functions later.
+    -# Call Parse().
+    -# Use Found() to retrieve the results.

 
     In the documentation below the following terminology is used:
 
 
     In the documentation below the following terminology is used:
 

+    - @b switch: This is a boolean option which can be given or not, but which
+                 doesn't have any value. We use the word switch to distinguish
+                 such boolean options from more generic options like those
+                 described below. For example, @c "-v" might be a switch
+                 meaning "enable verbose mode".
+    - @b option: Option for us here is something which comes with a value 0
+                 unlike a switch. For example, @c -o:filename might be an
+                 option for specifing the name of the output file.
+    - @b parameter: This is a required program argument.
+
+
+    @section cmdlineparser_construction Construction

 
 

+    Before Parse() can be called, the command line parser object must have the
+    command line to parse and also the rules saying which switches, options and
+    parameters are valid - this is called command line description in what
+    follows.

 
 

-    switch
+    You have complete freedom of choice as to when specify the required
+    information, the only restriction is that it must be done before calling
+    Parse().

 
 

+    To specify the command line to parse you may use either one of constructors
+    accepting it (wxCmdLineParser(int, char**) or
+    wxCmdLineParser(const wxString&) usually) or, if you use the default
+    constructor, you can do it later by calling SetCmdLine().

 
 

-    This is a boolean option which can be given or not, but
-    which doesn't have any value. We use the word switch to distinguish such boolean
-    options from more generic options like those described below. For example,
-    @c -v might be a switch meaning "enable verbose mode".
+    The same holds for command line description: it can be specified either in
+    the constructor (with or without the command line itself) or constructed
+    later using either SetDesc() or combination of AddSwitch(), AddOption() and
+    AddParam() methods.

 
 

+    Using constructors or SetDesc() uses a (usually const static) table
+    containing the command line description. If you want to decide which
+    options to accept during the run-time, using one of the AddXXX() functions
+    above might be preferable.

 
 

-    option

 
 

+    @section cmdlineparser_customization Customization

 
 

-    Option for us here is something which comes with a value 0
-    unlike a switch. For example, @c -o:filename might be an option which allows
-    to specify the name of the output file.
+    wxCmdLineParser has several global options which may be changed by the
+    application. All of the functions described in this section should be
+    called before Parse().

 
 

+    First global option is the support for long (also known as GNU-style)
+    options. The long options are the ones which start with two dashes and look
+    like "--verbose", i.e. they generally are complete words and not some
+    abbreviations of them. As long options are used by more and more
+    applications, they are enabled by default, but may be disabled with
+    DisableLongOptions().

 
 

-    parameter
+    Another global option is the set of characters which may be used to start
+    an option (otherwise, the word on the command line is assumed to be a
+    parameter). Under Unix, "-" is always used, but Windows has at least two
+    common choices for this: "-" and "/". Some programs also use "+". The
+    default is to use what suits most the current platform, but may be changed
+    with SetSwitchChars() method.

 
 

+    Finally, SetLogo() can be used to show some application-specific text
+    before the explanation given by Usage() function.

 
 

-    This is a required program argument.

 
 

+    @section cmdlineparser_parsing Parsing the Command Line
+
+    After the command line description was constructed and the desired options
+    were set, you can finally call Parse() method. It returns 0 if the command
+    line was correct and was parsed, -1 if the help option was specified (this
+    is a separate case as, normally, the program will 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 wxWidgets logging
+    functions.
+
+
+    @section cmdlineparser_results Getting Results
+
+    After calling Parse() (and if it returned 0), you may access the results of
+    parsing using one of overloaded Found() methods.
+
+    For a simple switch, you will simply call Found to determine if the switch
+    was given or not, for an option or a parameter, you will call a version of
+    Found() which also returns the associated value in the provided variable.
+    All Found() functions return true if the switch or option were found in the
+    command line or false if they were not specified.

 
 
     @library{wxbase}
     @category{appmanagement}
 
 
 
     @library{wxbase}
     @category{appmanagement}
 

-    @see wxApp::argc and wxApp::argv, console sample
+    @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"

 */
 class wxCmdLineParser
 {
 public:
 */
 class wxCmdLineParser
 {
 public:

-    //@{

     /**
     /**

-        Specifies both the command line (in Windows format) and the
-        @ref setdesc() "command line description".
+        Default constructor, you must use SetCmdLine() later.

     */
     wxCmdLineParser();
     */
     wxCmdLineParser();

+
+    //@{
+    /**
+        Constructor which specifies the command line to parse. This is the
+        traditional (Unix) command line format. The parameters @a argc and
+        @a argv have the same meaning as the typical @c main() function.
+
+        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.
+    */

     wxCmdLineParser(int argc, char** argv);
     wxCmdLineParser(int argc, wchar_t** argv);
     wxCmdLineParser(int argc, char** argv);
     wxCmdLineParser(int argc, wchar_t** argv);

+    //@}
+
+    /**
+        Constructor which specify the command line to parse in Windows format.
+        The parameter cmdline has the same meaning as the corresponding
+        parameter of @c WinMain().
+    */

     wxCmdLineParser(const wxString& cmdline);
     wxCmdLineParser(const wxString& cmdline);

+
+    /**
+        Specifies the @ref SetDesc() "command line description" but not the
+        command line. You must use SetCmdLine() later.
+    */

     wxCmdLineParser(const wxCmdLineEntryDesc* desc);
     wxCmdLineParser(const wxCmdLineEntryDesc* desc);

+
+    /**
+        Specifies both the command line (in Unix format) and the
+        @ref SetDesc() "command line description".
+    */

     wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
                     char** argv);
     wxCmdLineParser(const wxCmdLineEntryDesc* desc, int argc,
                     char** argv);

+
+    /**
+        Specifies both the command line (in Windows format) and the
+        @ref SetDesc() "command line description".
+    */

     wxCmdLineParser(const wxCmdLineEntryDesc* desc,
                     const wxString& cmdline);
     wxCmdLineParser(const wxCmdLineEntryDesc* desc,
                     const wxString& cmdline);

-    //@}

 
     /**
         Frees resources allocated by the object.
 
     /**
         Frees resources allocated by the object.

-        @b NB: destructor is not virtual, don't use this class polymorphically.
+
+        @note This destructor is not virtual, don't use this class
+              polymorphically.

     */
     ~wxCmdLineParser();
 
     /**
     */
     ~wxCmdLineParser();
 
     /**

-        Add an option @a name with an optional long name @a 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.
+        Add an option @a name with an optional long name @a 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.

     */
     void AddOption(const wxString& name,
                    const wxString& lng = wxEmptyString,
     */
     void AddOption(const wxString& name,
                    const wxString& lng = wxEmptyString,


@@ -104,9 +277,9 @@ public:
                   int flags = 0);
 
     /**
                   int flags = 0);
 
     /**

-        Add a switch @a name with an optional long name @a lng (no long name if it
-        is empty, which is default), description @a desc and flags @a flags to the
-        command line description.
+        Add a switch @a name with an optional long name @a lng (no long name if
+        it is empty, which is default), description @a desc and flags @a flags
+        to the command line description.

     */
     void AddSwitch(const wxString& name,
                    const wxString& lng = wxEmptyString,
     */
     void AddSwitch(const wxString& name,
                    const wxString& lng = wxEmptyString,


@@ -115,145 +288,92 @@ public:
 
     /**
         Returns @true if long options are enabled, otherwise @false.
 
     /**
         Returns @true if long options are enabled, otherwise @false.

-        
+

         @see EnableLongOptions()
     */
         @see EnableLongOptions()
     */

-    bool AreLongOptionsEnabled();
+    bool AreLongOptionsEnabled() const;

 
     /**
 
     /**

-        Before Parse() can be called, the command line
-        parser object must have the command line to parse and also the rules saying
-        which switches, options and parameters are valid - this is called command line
-        description in what follows.
-        You have complete freedom of choice as to when specify the required information,
-        the only restriction is that it must be done before calling
-        Parse().
-        To specify the command line to parse you may use either one of constructors
-        accepting it (@c wxCmdLineParser(argc, argv) or @c wxCmdLineParser(const
-        wxString) usually)
-        or, if you use the default constructor, you can do it later by calling
-        SetCmdLine().
-        The same holds for command line description: it can be specified either in
-        the @ref wxcmdlineparserctor() constructor (with or without
-        the command line itself) or constructed later using either
-        SetDesc() or combination of
-        AddSwitch(),
-        AddOption() and
-        AddParam() methods.
-        Using constructors or SetDesc() uses a (usually
-        @c const static) table containing the command line description. If you want
-        to decide which options to accept during the run-time, using one of the
-        @c AddXXX() functions above might be preferable.
+        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.

     */
     */

+    static wxArrayString ConvertStringToArgs(const wxChar cmdline);

 
 

+    /**
+        Identical to EnableLongOptions(@false).
+    */
+    void DisableLongOptions();

 
     /**
 
     /**

-        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.
+        Enable or disable support for the long options.
+
+        As long options are not (yet) POSIX-compliant, this option allows to
+        disable them.
+
+        @see @ref cmdlineparser_customization and AreLongOptionsEnabled()

     */
     */

-    static wxArrayString ConvertStringToArgs(const wxChar cmdline);
+    void EnableLongOptions(bool enable = true);

 
     /**
 
     /**

-        wxCmdLineParser has several global options which may be changed by the
-        application. All of the functions described in this section should be called
-        before Parse().
-        First global option is the support for long (also known as GNU-style) options.
-        The long options are the ones which start with two dashes (@c "--") and look
-        like this: @c --verbose, i.e. they generally are complete words and not some
-        abbreviations of them. As long options are used by more and more applications,
-        they are enabled by default, but may be disabled with
-        DisableLongOptions().
-        Another global option is the set of characters which may be used to start an
-        option (otherwise, the word on the command line is assumed to be a parameter).
-        Under Unix, @c '-' is always used, but Windows has at least two common
-        choices for this: @c '-' and @c '/'. Some programs also use @c '+'.
-        The default is to use what suits most the current platform, but may be changed
-        with SetSwitchChars() method.
-        Finally, SetLogo() can be used to show some
-        application-specific text before the explanation given by
-        Usage() function.
+        Returns @true if the given switch was found, @false otherwise.

     */
     */

+    bool Found(const wxString& name) const;

 
 

+    /**
+        Returns true if an option taking a string value was found and stores
+        the value in the provided pointer (which should not be @NULL).
+    */
+    bool Found(const wxString& name, wxString* value) const;

 
     /**
 
     /**

-        Identical to @ref enablelongoptions() EnableLongOptions(@false).
+        Returns @true if an option taking an integer value was found and stores
+        the value in the provided pointer (which should not be @NULL).

     */
     */

-    void DisableLongOptions();
+    bool Found(const wxString& name, long* value) const;

 
     /**
 
     /**

-        Enable or disable support for the long options.
-        As long options are not (yet) POSIX-compliant, this option allows to disable
-        them.
-        
-        @see Customization() and AreLongOptionsEnabled()
+        Returns @true if an option taking a float value was found and stores
+        the value in the provided pointer (which should not be @NULL).

     */
     */

-    void EnableLongOptions(bool enable = true);
+    bool Found(const wxString& name, double* value) const;

 
 

-    //@{

     /**
         Returns @true if an option taking a date value was found and stores the
         value in the provided pointer (which should not be @NULL).
     */
     /**
         Returns @true if an option taking a date value was found and stores the
         value in the provided pointer (which should not be @NULL).
     */

-    bool Found(const wxString& name) const;
-    const bool Found(const wxString& name, wxString* value) const;
-    const bool Found(const wxString& name, long* value) const;
-    const bool Found(const wxString& name, wxDateTime* value) const;
-    //@}
+    bool Found(const wxString& name, wxDateTime* value) const;

 
     /**
         Returns the value of Nth parameter (as string only).
     */
 
     /**
         Returns the value of Nth parameter (as string only).
     */

-    wxString GetParam(size_t n = 0u) const;
+    wxString GetParam(size_t n = 0) const;

 
     /**
 
     /**

-        Returns the number of parameters found. This function makes sense mostly if you
-        had used @c wxCMD_LINE_PARAM_MULTIPLE flag.
+        Returns the number of parameters found. This function makes sense
+        mostly if you had used @c wxCMD_LINE_PARAM_MULTIPLE flag.

     */
     size_t GetParamCount() const;
 
     */
     size_t GetParamCount() const;
 

-    /**
-        After calling Parse() (and if it returned 0),
-        you may access the results of parsing using one of overloaded @c Found()
-        methods.
-        For a simple switch, you will simply call
-        Found() to determine if the switch was given
-        or not, for an option or a parameter, you will call a version of @c Found()
-        which also returns the associated value in the provided variable. All
-        @c Found() functions return @true if the switch or option were found in the
-        command line or @false if they were not specified.
-    */
-
-

     /**
         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"
     /**
         Parse the command line, return 0 if ok, -1 if @c "-h" or @c "--help"

-        option was encountered and the help message was given or a positive value if a
-        syntax error occurred.
-        
+        option was encountered and the help message was given or a positive
+        value if a syntax error occurred.
+

         @param giveUsage
         @param giveUsage

-            If @true (default), the usage message is given if a
-            syntax error was encountered while parsing the command line or if help was
-            requested. If @false, only error messages about possible syntax errors
-            are given, use Usage to show the usage message
-            from the caller if needed.
+            If @true (default), the usage message is given if a syntax error
+            was encountered while parsing the command line or if help was
+            requested. If @false, only error messages about possible syntax
+            errors are given, use Usage to show the usage message from the
+            caller if needed.

     */
     int Parse(bool giveUsage = true);
 
     */
     int Parse(bool giveUsage = true);
 

-    /**
-        After the command line description was constructed and the desired options were
-        set, you can finally call Parse() method.
-        It returns 0 if the command line was correct and was parsed, -1 if the help
-        option was specified (this is a separate case as, normally, the program will
-        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 wxWidgets logging functions.
-    */
-
-

     //@{
     /**
     //@{
     /**

-        Set command line to parse after using one of the constructors which don't do it.
+        Set the command line to parse after using one of the constructors which
+        don't do it.

     */
     void SetCmdLine(int argc, char** argv);
     void SetCmdLine(int argc, wchar_t** argv);
     */
     void SetCmdLine(int argc, char** argv);
     void SetCmdLine(int argc, wchar_t** argv);


@@ -261,31 +381,55 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        Construct the command line description
-        Take the command line description from the wxCMD_LINE_NONE terminated table.
+        Constructs the command line description.
+
+        Take the command line description from the wxCMD_LINE_NONE terminated
+        table.
+

         Example of usage:
         Example of usage:

+
+        @code
+        static const wxCmdLineEntryDesc cmdLineDesc[] =
+        {
+            { wxCMD_LINE_SWITCH, "v", "verbose", "be verbose" },
+            { wxCMD_LINE_SWITCH, "q", "quiet",   "be quiet" },
+
+            { wxCMD_LINE_OPTION, "o", "output",  "output file" },
+            { wxCMD_LINE_OPTION, "i", "input",   "input dir" },
+            { wxCMD_LINE_OPTION, "s", "size",    "output block size", wxCMD_LINE_VAL_NUMBER },
+            { wxCMD_LINE_OPTION, "d", "date",    "output file date", wxCMD_LINE_VAL_DATE },
+
+            { wxCMD_LINE_PARAM,  NULL, NULL, "input file", wxCMD_LINE_VAL_STRING, wxCMD_LINE_PARAM_MULTIPLE },
+
+            { wxCMD_LINE_NONE }
+        };
+
+        wxCmdLineParser parser;
+
+        parser.SetDesc(cmdLineDesc);
+        @endcode

     */
     void SetDesc(const wxCmdLineEntryDesc* desc);
 
     /**
     */
     void SetDesc(const wxCmdLineEntryDesc* desc);
 
     /**

-        @a logo is some extra text which will be shown by
-        Usage() method.
+        The @a logo is some extra text which will be shown by Usage() method.

     */
     void SetLogo(const wxString& logo);
 
     /**
     */
     void SetLogo(const wxString& logo);
 
     /**

-        @a switchChars contains all characters with which an option or switch may
-        start. Default is @c "-" for Unix, @c "-/" for Windows.
+        @a switchChars contains all characters with which an option or switch
+        may start. Default is @c "-" for Unix, @c "-/" for Windows.

     */
     void SetSwitchChars(const wxString& switchChars);
 
     /**
     */
     void SetSwitchChars(const wxString& switchChars);
 
     /**

-        Give the standard usage message describing all program options. It will use the
-        options and parameters descriptions specified earlier, so the resulting message
-        will not be helpful to the user unless the descriptions were indeed specified.
-        
+        Give the standard usage message describing all program options. It will
+        use the options and parameters descriptions specified earlier, so the
+        resulting message will not be helpful to the user unless the
+        descriptions were indeed specified.
+

         @see SetLogo()
     */
         @see SetLogo()
     */

-    void Usage();
+    void Usage() const;

 };
 
 };