reorder the classes, putting first the basic ones and towards the end of the file...

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

diff --git a/interface/wx/cmdline.h b/interface/wx/cmdline.h
index 2196edb66a9c6de7e65c9b3f53248f8a6174e216..4b7b85f4c25240d195e0263f250137ed576836f6 100644 (file)
--- a/interface/wx/cmdline.h
+++ b/interface/wx/cmdline.h
@@ -59,35 +59,52 @@ enum wxCmdLineEntryType
     wxCMD_LINE_NONE     ///< Use this to terminate the list.
 };
 
+/**
+    Flags determining wxCmdLineParser::ConvertStringToArgs() behaviour.
+ */
+enum wxCmdLineSplitType
+{
+    wxCMD_LINE_SPLIT_DOS,
+    wxCMD_LINE_SPLIT_UNIX
+};
+
 /**
     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.
+    to wxCmdLineParser::SetDesc().
+
+    Also, the meanings of parameters of the wxCmdLineParser::AddXXX() functions
+    are the same as of the corresponding fields in this structure.
 */
 struct wxCmdLineEntryDesc
 {
     wxCmdLineEntryType kind;
+
+    /**
+        This is the usual, short, name of the switch or the option.
+    */
     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.
+    */
     const char *longName;
+
+    /**
+        This description is used by the wxCmdLineEntryDesc::Usage() method to
+        construct a help message explaining the syntax of the program.
+    */
     const char *description;
+
     wxCmdLineParamType type;
     int flags;
 };
 
 /**
     @class wxCmdLineParser
-    @wxheader{cmdline.h}
 
     wxCmdLineParser is a class for parsing the command line.
 
@@ -107,6 +124,9 @@ struct wxCmdLineEntryDesc
     -# Call Parse().
     -# Use Found() to retrieve the results.
 
+    You can also use wxApp's default command line processing just overriding
+    wxAppConsole::OnInitCmdLine() and wxAppConsole::OnCmdLineParsed().
+
     In the documentation below the following terminology is used:
 
     - @b switch: This is a boolean option which can be given or not, but which
@@ -200,7 +220,7 @@ struct wxCmdLineEntryDesc
     @library{wxbase}
     @category{appmanagement}
 
-    @see wxApp::argc, wxApp::argv, @ref page_samples_console "Console Sample"
+    @see wxApp::argc, wxApp::argv, @ref page_samples_console
 */
 class wxCmdLineParser
 {
@@ -210,20 +230,27 @@ public:
     */
     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
+        This constructor 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);
+
+    /**
+        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.
+
+        This constructor is only available in Unicode build.
+    */
     wxCmdLineParser(int argc, wchar_t** argv);
-    //@}
 
     /**
         Constructor which specify the command line to parse in Windows format.
@@ -302,12 +329,20 @@ public:
     bool AreLongOptionsEnabled() const;
 
     /**
-        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.
+        Breaks down the string containing the full command line in words.
+
+        Words are separated by whitespace and double quotes can be used to
+        preserve the spaces inside the words.
+
+        By default, this function uses Windows-like word splitting algorithm,
+        i.e. single quotes have no special meaning and backslash can't be used
+        to escape spaces neither. With @c wxCMD_LINE_SPLIT_UNIX flag Unix
+        semantics is used, i.e. both single and double quotes can be used and
+        backslash can be used to escape all the other special characters.
     */
-    static wxArrayString ConvertStringToArgs(const wxChar cmdline);
+    static wxArrayString
+    ConvertStringToArgs(const wxString& cmdline,
+                        wxCmdLineSplitType flags = wxCMD_LINE_SPLIT_DOS);
 
     /**
         Identical to EnableLongOptions(@false).