synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / cmdline.h

diff --git a/interface/wx/cmdline.h b/interface/wx/cmdline.h
index 4b7b85f4c25240d195e0263f250137ed576836f6..479239781c525848473acb2bc96d97d987c65e19 100644 (file)
--- a/interface/wx/cmdline.h
+++ b/interface/wx/cmdline.h
@@ -3,39 +3,47 @@
 // Purpose:     interface of wxCmdLineParser
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxCmdLineParser
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     wxCmdLineEntryDesc::flags field is a combination of these bit masks.
 
     Notice that by default (i.e. if flags are just 0), options are optional
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     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
+    (sic) and each call to wxCmdLineParser::AddParam() allows one more

     parameter - this may be changed by giving non-default flags to it, i.e. use
     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
+    @c wxCMD_LINE_OPTION_MANDATORY to require that the option is given and
+    @c wxCMD_LINE_PARAM_OPTIONAL to make a parameter optional.
+    
+    Also, @c 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().
 
     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
+    @c 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.
     a colon, an equal sign or white space) between the option name and its
     value. By default, no separator is required.

+
+    @c wxCMD_LINE_SWITCH_NEGATABLE can be specified if you want to allow the
+    user to specify the switch in both normal form and in negated one (e.g.
+    /R-). You will need to use wxCmdLineParser::FoundSwitch() to distinguish
+    between the normal and negated forms of the switch. This flag is new since
+    wxWidgets 2.9.2.

 */
 */

-enum
+enum wxCmdLineEntryFlags

 {
     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_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.
+    wxCMD_LINE_NEEDS_SEPARATOR  = 0x10, ///< Must have a separator before the value.
+    wxCMD_LINE_SWITCH_NEGATABLE = 0x20  ///< This switch can be negated (e.g. /S-)

 };
 
 /**
 };
 
 /**

-    The possible values of wxCmdLineEntryDesc::type which specifies the type of
+    The possible values of wxCmdLineEntryDesc::type which specify the type of

     the value accepted by an option.
 */
 enum wxCmdLineParamType
     the value accepted by an option.
 */
 enum wxCmdLineParamType


@@ -52,13 +60,40 @@ enum wxCmdLineParamType
 */
 enum wxCmdLineEntryType
 {
 */
 enum wxCmdLineEntryType
 {

+    /// A boolean argument of the program; e.g. @c -v to enable verbose mode.

     wxCMD_LINE_SWITCH,
     wxCMD_LINE_SWITCH,

+    
+    /// An argument with an associated value; e.g. @c "-o filename" to specify
+    /// an optional output filename.

     wxCMD_LINE_OPTION,
     wxCMD_LINE_OPTION,

+    
+    /// A parameter: a required program argument.

     wxCMD_LINE_PARAM,
     wxCMD_LINE_PARAM,

+    
+    /// Additional usage text. See wxCmdLineParser::AddUsageText.

     wxCMD_LINE_USAGE_TEXT,
     wxCMD_LINE_USAGE_TEXT,

+    

     wxCMD_LINE_NONE     ///< Use this to terminate the list.
 };
 
     wxCMD_LINE_NONE     ///< Use this to terminate the list.
 };
 

+/**
+    The state of a switch as returned by wxCmdLineParser::FoundSwitch().
+
+    @since 2.9.2
+*/
+enum wxCmdLineSwitchState
+{
+    /// The switch was found in negated form, i.e. followed by a '-'.
+    wxCMD_SWITCH_OFF,
+
+    /// The switch was not found at all on the command line.
+    wxCMD_SWITCH_NOT_FOUND
+
+    /// The switch was found (and was not negated)
+    wxCMD_SWITCH_ON
+};
+
+

 /**
     Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
  */
 /**
     Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
  */


@@ -69,37 +104,53 @@ enum wxCmdLineSplitType
 };
 
 /**
 };
 
 /**

-    The structure wxCmdLineEntryDesc is used to describe the one command line
+    The structure wxCmdLineEntryDesc is used to describe a command line

     switch, option or parameter. An array of such structures should be passed
     to wxCmdLineParser::SetDesc().
 
     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
+    Note that the meanings of parameters of the wxCmdLineParser::AddXXX() functions

     are the same as of the corresponding fields in this structure.
 */
 struct wxCmdLineEntryDesc
 {
     are the same as of the corresponding fields in this structure.
 */
 struct wxCmdLineEntryDesc
 {

+    /**
+        The kind of this program argument.
+        See ::wxCmdLineEntryType for more info.
+    */

     wxCmdLineEntryType kind;
 
     /**
     wxCmdLineEntryType kind;
 
     /**

-        This is the usual, short, name of the switch or the option.
+        The usual, short, name of the switch or the option.
+        
+        It may contain only letters, digits and the underscores.
+        This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.

     */
     const char *shortName;
 
     /**
     */
     const char *shortName;
 
     /**

-        @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.
+        The long name for this program argument (may be empty if the option
+        has no long name).
+        
+        It may contain only letters, digits and the underscores.
+        This field is unused if <tt>kind == wxCMD_LINE_PARAM</tt>.

     */
     const char *longName;
 
     /**
     */
     const char *longName;
 
     /**

-        This description is used by the wxCmdLineEntryDesc::Usage() method to
+        This description is used by the wxCmdLineParser::Usage() method to

         construct a help message explaining the syntax of the program.
     */
     const char *description;
 
         construct a help message explaining the syntax of the program.
     */
     const char *description;
 

+    /**
+        The type associated with this option (ignored if <tt>kind != wxCMD_LINE_OPTION</tt>).
+        See ::wxCmdLineParamType for more info.
+    */

     wxCmdLineParamType type;
     wxCmdLineParamType type;

+    
+    /**
+        A combination of one or more ::wxCmdLineEntryFlags enum values.
+    */

     int flags;
 };
 
     int flags;
 };
 


@@ -129,16 +180,15 @@ struct wxCmdLineEntryDesc
 
     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
+    - @b switch: a boolean option which can be given or not, but which doesn't have 
+                 any value. We use the word @e 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".
                  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: @c filename might be an
+    - @b option: a switch with a value associated to it. 
+                 For example, @c "-o filename" might be an

                  option for specifying the name of the output file.
                  option for specifying the name of the output file.

-    - @b parameter: This is a required program argument.
-    - @b text: This is a text which can be shown in usage information.
+    - @b parameter: a required program argument.

 
 
     @section cmdlineparser_construction Construction
 
 
     @section cmdlineparser_construction Construction


@@ -286,6 +336,32 @@ public:
     */
     ~wxCmdLineParser();
 
     */
     ~wxCmdLineParser();
 

+    /**
+        Adds an option with only long form.
+
+        This is just a convenient wrapper for AddOption() passing an empty
+        string as short option name.
+
+        @since 2.9.3
+     */
+    void AddLongOption(const wxString& lng,
+                       const wxString& desc = wxEmptyString,
+                       wxCmdLineParamType type = wxCMD_LINE_VAL_STRING,
+                       int flags = 0);
+
+    /**
+        Adds a switch with only long form.
+
+        This is just a convenient wrapper for AddSwitch() passing an empty
+        string as short switch name.
+
+        @since 2.9.3
+     */
+
+    void AddLongSwitch(const wxString& lng,
+                       const wxString& desc = wxEmptyString,
+                       int flags = 0);
+

     /**
         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
     /**
         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


@@ -364,6 +440,26 @@ public:
     */
     bool Found(const wxString& name) const;
 
     */
     bool Found(const wxString& name) const;
 

+    /**
+        Returns whether the switch was found on the command line and whether it
+        was negated.
+
+        This method can be used for any kind of switch but is especially useful
+        for switches that can be negated, i.e. were added with
+        wxCMD_LINE_SWITCH_NEGATABLE flag, as otherwise Found() is simpler to
+        use.
+
+        However Found() doesn't allow to distinguish between switch specified
+        normally, i.e. without dash following it, and negated switch, i.e. with
+        the following dash. This method will return @c wxCMD_SWITCH_ON or @c
+        wxCMD_SWITCH_OFF depending on whether the switch was negated or not.
+        And if the switch was not found at all, @c wxCMD_SWITCH_NOT_FOUND is
+        returned.
+
+        @since 2.9.2
+    */
+    wxCmdLineSwitchState FoundSwitch(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).
     /**
         Returns true if an option taking a string value was found and stores
         the value in the provided pointer (which should not be @NULL).