added wxString::Clone() and made wxString(wxCStrData) ctor make deep copy too

[wxWidgets.git] / interface / filedlg.h

diff --git a/interface/filedlg.h b/interface/filedlg.h
index 3c9fa30d9c3576c89963aeef998dfed96e8c7e25..ada7bba196b5e5d10333ce0ad4f34e03e8a4410e 100644 (file)
--- a/interface/filedlg.h
+++ b/interface/filedlg.h
@@ -12,28 +12,46 @@
 
     This class represents the file chooser dialog.
 
 
     This class represents the file chooser dialog.
 

+    It pops up a file selector box (native for Windows and GTK2.4+).
+
+    The path and filename are distinct elements of a full file pathname.
+    If path is "", the current directory will be used. If filename is "", no default
+    filename will be supplied. The wildcard determines what files are displayed in the
+    file selector, and file extension supplies a type extension for the required filename.
+
+    @remarks
+    All implementations of the wxFileDialog provide a wildcard filter. Typing a filename
+    containing wildcards (*, ?) in the filename text item, and clicking on Ok, will
+    result in only those files matching the pattern being displayed.
+    The wildcard may be a specification for multiple types of file with a description
+    for each, such as:
+         "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"
+    It must be noted that wildcard support in the native Motif file dialog is quite
+    limited: only one alternative is supported, and it is displayed without the
+    descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both
+    "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif"
+    are errors.
+

     @beginStyleTable
     @beginStyleTable

-    @style{wxFD_DEFAULT_STYLE}:
+    @style{wxFD_DEFAULT_STYLE}

            Equivalent to wxFD_OPEN.
            Equivalent to wxFD_OPEN.

-    @style{wxFD_OPEN}:
+    @style{wxFD_OPEN}

            This is an open dialog; usually this means that the default
            This is an open dialog; usually this means that the default

-           button's label of the dialog is "Open". Cannot be combined with
-           wxFD_SAVE.
-    @style{wxFD_SAVE}:
+           button's label of the dialog is "Open". Cannot be combined with wxFD_SAVE.
+    @style{wxFD_SAVE}

            This is a save dialog; usually this means that the default button's
            label of the dialog is "Save". Cannot be combined with wxFD_OPEN.
            This is a save dialog; usually this means that the default button's
            label of the dialog is "Save". Cannot be combined with wxFD_OPEN.

-    @style{wxFD_OVERWRITE_PROMPT}:
+    @style{wxFD_OVERWRITE_PROMPT}

            For save dialog only: prompt for a confirmation if a file will be
            overwritten.
            For save dialog only: prompt for a confirmation if a file will be
            overwritten.

-    @style{wxFD_FILE_MUST_EXIST}:
-           For open dialog only: the user may only select files that actually
-           exist.
-    @style{wxFD_MULTIPLE}:
+    @style{wxFD_FILE_MUST_EXIST}
+           For open dialog only: the user may only select files that actually exist.
+    @style{wxFD_MULTIPLE}

            For open dialog only: allows selecting multiple files.
            For open dialog only: allows selecting multiple files.

-    @style{wxFD_CHANGE_DIR}:
+    @style{wxFD_CHANGE_DIR}

            Change the current working directory to the directory where the
            file(s) chosen by the user are.
            Change the current working directory to the directory where the
            file(s) chosen by the user are.

-    @style{wxFD_PREVIEW}:
+    @style{wxFD_PREVIEW}

            Show the preview of the selected files (currently only supported by
            wxGTK using GTK+ 2.4 or later).
     @endStyleTable
            Show the preview of the selected files (currently only supported by
            wxGTK using GTK+ 2.4 or later).
     @endStyleTable


@@ -41,15 +59,14 @@
     @library{wxcore}
     @category{cmndlg}
 
     @library{wxcore}
     @category{cmndlg}
 

-    @see @ref overview_wxfiledialogoverview "wxFileDialog overview",
-    wxFileSelector()
+    @see @ref overview_wxfiledialog, ::wxFileSelector()

 */
 class wxFileDialog : public wxDialog
 {
 public:
     /**
         Constructor. Use ShowModal() to show the dialog.
 */
 class wxFileDialog : public wxDialog
 {
 public:
     /**
         Constructor. Use ShowModal() to show the dialog.

-        
+

         @param parent
             Parent window.
         @param message
         @param parent
             Parent window.
         @param message


@@ -59,8 +76,7 @@ public:
         @param defaultFile
             The default filename, or the empty string.
         @param wildcard
         @param defaultFile
             The default filename, or the empty string.
         @param wildcard

-            A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files
-        (*.gif)|*.gif".
+            A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".

             Note that the native Motif dialog has some limitations with respect to
             wildcards; see the Remarks section above.
         @param style
             Note that the native Motif dialog has some limitations with respect to
             wildcards; see the Remarks section above.
         @param style


@@ -93,9 +109,7 @@ public:
     wxString GetDirectory() const;
 
     /**
     wxString GetDirectory() const;
 
     /**

-        If functions
-        SetExtraControlCreator()
-        and ShowModal() were called,
+        If functions SetExtraControlCreator() and ShowModal() were called,

         returns the extra window. Otherwise returns @NULL.
     */
     wxWindow* GetExtraControl() const;
         returns the extra window. Otherwise returns @NULL.
     */
     wxWindow* GetExtraControl() const;


@@ -106,9 +120,11 @@ public:
     wxString GetFilename() const;
 
     /**
     wxString GetFilename() const;
 
     /**

-        Fills the array @a filenames with the names of the files chosen. This
-        function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
+        Fills the array @a filenames with the names of the files chosen.
+
+        This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,

         use GetFilename() for the others.
         use GetFilename() for the others.

+

         Note that under Windows, if the user selects shortcuts, the filenames
         include paths, since the application cannot determine the full path
         of each referenced file by appending the directory containing the shortcuts
         Note that under Windows, if the user selects shortcuts, the filenames
         include paths, since the application cannot determine the full path
         of each referenced file by appending the directory containing the shortcuts


@@ -119,8 +135,10 @@ public:
     /**
         Returns the index into the list of filters supplied, optionally, in the
         wildcard parameter.
     /**
         Returns the index into the list of filters supplied, optionally, in the
         wildcard parameter.

+

         Before the dialog is shown, this is the index which will be used when the
         dialog is first displayed.
         Before the dialog is shown, this is the index which will be used when the
         dialog is first displayed.

+

         After the dialog is shown, this is the index selected by the user.
     */
     int GetFilterIndex() const;
         After the dialog is shown, this is the index selected by the user.
     */
     int GetFilterIndex() const;


@@ -136,8 +154,9 @@ public:
     wxString GetPath() const;
 
     /**
     wxString GetPath() const;
 
     /**

-        Fills the array @a paths with the full paths of the files chosen. This
-        function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
+        Fills the array @a paths with the full paths of the files chosen.
+
+        This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,

         use GetPath() for the others.
     */
     void GetPaths(wxArrayString& paths) const;
         use GetPath() for the others.
     */
     void GetPaths(wxArrayString& paths) const;


@@ -155,10 +174,12 @@ public:
     /**
         Customize file dialog by adding extra window, which is typically placed
         below the list of files and above the buttons.
     /**
         Customize file dialog by adding extra window, which is typically placed
         below the list of files and above the buttons.

-        SetExtraControlCreator can be called only once, before calling
-        ShowModal().
+
+        SetExtraControlCreator() can be called only once, before calling ShowModal().
+

         The @c creator function should take pointer to parent window (file dialog)
         and should return a window allocated with operator new.
         The @c creator function should take pointer to parent window (file dialog)
         and should return a window allocated with operator new.

+

         Supported platforms: wxGTK, wxUniv.
     */
     bool SetExtraControlCreator(t_extraControlCreator creator);
         Supported platforms: wxGTK, wxUniv.
     */
     bool SetExtraControlCreator(t_extraControlCreator creator);


@@ -186,7 +207,8 @@ public:
 
     /**
         Sets the wildcard, which can contain multiple file types, for example:
 
     /**
         Sets the wildcard, which can contain multiple file types, for example:

-        "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+        "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
+

         Note that the native Motif dialog has some limitations with respect to
         wildcards; see the Remarks section above.
     */
         Note that the native Motif dialog has some limitations with respect to
         wildcards; see the Remarks section above.
     */