Add a link to Microsoft guidelines from wxICON_QUESTION documentation.

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

diff --git a/interface/wx/filedlg.h b/interface/wx/filedlg.h
index 1093760f988762782cb8c7068b8361d71a359838..6e28ee3b0bb9e3bbdc396416d3d8608766941966 100644 (file)
--- a/interface/wx/filedlg.h
+++ b/interface/wx/filedlg.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxFileDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxFileDialog
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -11,12 +11,67 @@
 
     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.
     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.
+    If path is ::wxEmptyString, the current directory will be used.
+    If filename is ::wxEmptyString, 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.
+
+    The typical usage for the open file dialog is:
+    @code
+    void MyFrame::OnOpen(wxCommandEvent& WXUNUSED(event))
+    {
+        if (...current content has not been saved...)
+        {
+            if (wxMessageBox(_("Current content has not been saved! Proceed?"), _("Please confirm"),
+                             wxICON_QUESTION | wxYES_NO, this) == wxNO )
+                return;
+            //else: proceed asking to the user the new file to open
+        }
+        
+        wxFileDialog 
+            openFileDialog(this, _("Open XYZ file"), "", "",
+                           "XYZ files (*.xyz)|*.xyz", wxFD_OPEN|wxFD_FILE_MUST_EXIST);
+
+        if (openFileDialog.ShowModal() == wxID_CANCEL)
+            return;     // the user changed idea...
+        
+        // proceed loading the file chosen by the user;
+        // this can be done with e.g. wxWidgets input streams:
+        wxFileInputStream input_stream(openFileDialog.GetPath());
+        if (!input_stream.IsOk())
+        {
+            wxLogError("Cannot open file '%s'.", openFileDialog.GetPath());
+            return;
+        }
+        
+        ...
+    }
+    @endcode
+    
+    The typical usage for the save file dialog is instead somewhat simpler:
+    @code
+    void MyFrame::OnSaveAs(wxCommandEvent& WXUNUSED(event))
+    {
+        wxFileDialog 
+            saveFileDialog(this, _("Save XYZ file"), "", "",
+                           "XYZ files (*.xyz)|*.xyz", wxFD_SAVE|wxFD_OVERWRITE_PROMPT);
+
+        if (saveFileDialog.ShowModal() == wxID_CANCEL)
+            return;     // the user changed idea...
+        
+        // save the current contents in the file;
+        // this can be done with e.g. wxWidgets output streams:
+        wxFileOutputStream output_stream(saveFileDialog.GetPath());
+        if (!output_stream.IsOk())
+        {
+            wxLogError("Cannot save current contents in file '%s'.", saveFileDialog.GetPath());
+            return;
+        }
+        
+        ...
+    }
+    @endcode

 
     @remarks
     All implementations of the wxFileDialog provide a wildcard filter. Typing a filename
 
     @remarks
     All implementations of the wxFileDialog provide a wildcard filter. Typing a filename


@@ -35,26 +90,30 @@
 
     @beginStyleTable
     @style{wxFD_DEFAULT_STYLE}
 
     @beginStyleTable
     @style{wxFD_DEFAULT_STYLE}

-           Equivalent to wxFD_OPEN.
+           Equivalent to @c wxFD_OPEN.

     @style{wxFD_OPEN}
            This is an open dialog; usually this means that the default
     @style{wxFD_OPEN}
            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.
+           button's label of the dialog is "Open". Cannot be combined with @c wxFD_SAVE.

     @style{wxFD_SAVE}
            This is a save dialog; usually this means that the default button's
     @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.
+           label of the dialog is "Save". Cannot be combined with @c wxFD_OPEN.

     @style{wxFD_OVERWRITE_PROMPT}
            For save dialog only: prompt for a confirmation if a file will be
            overwritten.
     @style{wxFD_FILE_MUST_EXIST}
     @style{wxFD_OVERWRITE_PROMPT}
            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.
+           For open dialog only: the user may only select files that actually
+           exist. Notice that under OS X the file dialog with @c wxFD_OPEN
+           style always behaves as if this style was specified, because it is
+           impossible to choose a file that doesn't exist from a standard OS X
+           file dialog.

     @style{wxFD_MULTIPLE}
            For open dialog only: allows selecting multiple files.
     @style{wxFD_CHANGE_DIR}
     @style{wxFD_MULTIPLE}
            For open dialog only: allows selecting multiple files.
     @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 (when the dialog is dismissed) 
+           to the directory where the file(s) chosen by the user are.

     @style{wxFD_PREVIEW}
            Show the preview of the selected files (currently only supported by
     @style{wxFD_PREVIEW}
            Show the preview of the selected files (currently only supported by

-           wxGTK using GTK+ 2.4 or later).
+           wxGTK).

     @endStyleTable
 
     @library{wxcore}
     @endStyleTable
 
     @library{wxcore}


@@ -81,7 +140,7 @@ public:
             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

-            A dialog style. See wxFD_* styles for more info.
+            A dialog style. See @c wxFD_* styles for more info.

         @param pos
             Dialog position. Not implemented.
         @param size
         @param pos
             Dialog position. Not implemented.
         @param size


@@ -112,6 +171,8 @@ public:
     /**
         If functions SetExtraControlCreator() and ShowModal() were called,
         returns the extra window. Otherwise returns @NULL.
     /**
         If functions SetExtraControlCreator() and ShowModal() were called,
         returns the extra window. Otherwise returns @NULL.

+
+        @since 2.9.0

     */
     wxWindow* GetExtraControl() const;
 
     */
     wxWindow* GetExtraControl() const;
 


@@ -172,6 +233,13 @@ public:
     */
     virtual void SetDirectory(const wxString& directory);
 
     */
     virtual void SetDirectory(const wxString& directory);
 

+    /**
+        The type of function used as an argument for SetExtraControlCreator().
+
+        @since 2.9.0
+    */
+    typedef wxWindow *(*ExtraControlCreatorFunction)(wxWindow*);
+

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


@@ -181,12 +249,16 @@ public:
         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.
+        Supported platforms: wxGTK, wxMSW, wxUniv.
+
+        @since 2.9.0

     */
     */

-    bool SetExtraControlCreator(ExtraControlCreatorFunction);
+    bool SetExtraControlCreator(ExtraControlCreatorFunction creator);

 
     /**
         Sets the default filename.
 
     /**
         Sets the default filename.

+        
+        In wxGTK this will have little effect unless a default directory has previously been set.

     */
     virtual void SetFilename(const wxString& setfilename);
 
     */
     virtual void SetFilename(const wxString& setfilename);
 


@@ -216,7 +288,7 @@ public:
     virtual void SetWildcard(const wxString& wildCard);
 
     /**
     virtual void SetWildcard(const wxString& wildCard);
 
     /**

-        Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
+        Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c wxID_CANCEL

         otherwise.
     */
     virtual int ShowModal();
         otherwise.
     */
     virtual int ShowModal();


@@ -272,9 +344,9 @@ public:
     @header{wx/filedlg.h}
 */
 wxString wxFileSelector(const wxString& message,
     @header{wx/filedlg.h}
 */
 wxString wxFileSelector(const wxString& message,

-                        const wxString& default_path = "",
-                        const wxString& default_filename = "",
-                        const wxString& default_extension = "",
+                        const wxString& default_path = wxEmptyString,
+                        const wxString& default_filename = wxEmptyString,
+                        const wxString& default_extension = wxEmptyString,

                         const wxString& wildcard = ".",
                         int flags = 0,
                         wxWindow* parent = NULL,
                         const wxString& wildcard = ".",
                         int flags = 0,
                         wxWindow* parent = NULL,