Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

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

diff --git a/interface/wx/filedlg.h b/interface/wx/filedlg.h
index ada7bba196b5e5d10333ce0ad4f34e03e8a4410e..a3c5bfd621646839fc6401657164a29a45ad1cd2 100644 (file)
--- a/interface/wx/filedlg.h
+++ b/interface/wx/filedlg.h
@@ -3,21 +3,75 @@
 // 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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxFileDialog
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxFileDialog

-    @wxheader{filedlg.h}

 
     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


@@ -25,41 +79,47 @@
     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:
     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:

+    @code

          "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"
          "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"

+    @endcode

     It must be noted that wildcard support in the native Motif file dialog is quite
     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
+    limited: only one file type 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
     @style{wxFD_DEFAULT_STYLE}
     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
     @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}
     @category{cmndlg}
 
     @endStyleTable
 
     @library{wxcore}
     @category{cmndlg}
 

-    @see @ref overview_wxfiledialog, ::wxFileSelector()
+    @see @ref overview_cmndlg_file, ::wxFileSelector()

 */
 class wxFileDialog : public wxDialog
 {
 */
 class wxFileDialog : public wxDialog
 {


@@ -80,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


@@ -89,35 +149,37 @@ public:
             Dialog name. Not implemented.
     */
     wxFileDialog(wxWindow* parent,
             Dialog name. Not implemented.
     */
     wxFileDialog(wxWindow* parent,

-                 const wxString& message = "Choose a file",
-                 const wxString& defaultDir = "",
-                 const wxString& defaultFile = "",
-                 const wxString& wildcard = ".",
+                 const wxString& message = wxFileSelectorPromptStr,
+                 const wxString& defaultDir = wxEmptyString,
+                 const wxString& defaultFile = wxEmptyString,
+                 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,

                  long style = wxFD_DEFAULT_STYLE,
                  const wxPoint& pos = wxDefaultPosition,
                  long style = wxFD_DEFAULT_STYLE,
                  const wxPoint& pos = wxDefaultPosition,

-                 const wxSize& sz = wxDefaultSize,
-                 const wxString& name = "filedlg");
+                 const wxSize& size = wxDefaultSize,
+                 const wxString& name = wxFileDialogNameStr);

 
     /**
         Destructor.
     */
 
     /**
         Destructor.
     */

-    ~wxFileDialog();
+    virtual ~wxFileDialog();

 
     /**
         Returns the default directory.
     */
 
     /**
         Returns the default directory.
     */

-    wxString GetDirectory() const;
+    virtual wxString GetDirectory() const;

 
     /**
         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;
 
     /**
         Returns the default filename.
     */
     */
     wxWindow* GetExtraControl() const;
 
     /**
         Returns the default filename.
     */

-    wxString GetFilename() const;
+    virtual wxString GetFilename() const;

 
     /**
         Fills the array @a filenames with the names of the files chosen.
 
     /**
         Fills the array @a filenames with the names of the files chosen.


@@ -130,7 +192,7 @@ public:
         of each referenced file by appending the directory containing the shortcuts
         to the filename.
     */
         of each referenced file by appending the directory containing the shortcuts
         to the filename.
     */

-    void GetFilenames(wxArrayString& filenames) const;
+    virtual void GetFilenames(wxArrayString& filenames) const;

 
     /**
         Returns the index into the list of filters supplied, optionally, in the
 
     /**
         Returns the index into the list of filters supplied, optionally, in the


@@ -141,17 +203,17 @@ public:
 
         After the dialog is shown, this is the index selected by the user.
     */
 
         After the dialog is shown, this is the index selected by the user.
     */

-    int GetFilterIndex() const;
+    virtual int GetFilterIndex() const;

 
     /**
         Returns the message that will be displayed on the dialog.
     */
 
     /**
         Returns the message that will be displayed on the dialog.
     */

-    wxString GetMessage() const;
+    virtual wxString GetMessage() const;

 
     /**
         Returns the full path (directory and filename) of the selected file.
     */
 
     /**
         Returns the full path (directory and filename) of the selected file.
     */

-    wxString GetPath() const;
+    virtual wxString GetPath() const;

 
     /**
         Fills the array @a paths with the full paths of the files chosen.
 
     /**
         Fills the array @a paths with the full paths of the files chosen.


@@ -159,17 +221,24 @@ public:
         This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
         use GetPath() for the others.
     */
         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;
+    virtual void GetPaths(wxArrayString& paths) const;

 
     /**
         Returns the file dialog wildcard.
     */
 
     /**
         Returns the file dialog wildcard.
     */

-    wxString GetWildcard() const;
+    virtual wxString GetWildcard() const;

 
     /**
         Sets the default directory.
     */
 
     /**
         Sets the default directory.
     */

-    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
 
     /**
         Customize file dialog by adding extra window, which is typically placed


@@ -180,30 +249,34 @@ 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(t_extraControlCreator creator);
+    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.

     */
     */

-    void SetFilename(const wxString& setfilename);
+    virtual void SetFilename(const wxString& setfilename);

 
     /**
         Sets the default filter index, starting from zero.
     */
 
     /**
         Sets the default filter index, starting from zero.
     */

-    void SetFilterIndex(int filterIndex);
+    virtual void SetFilterIndex(int filterIndex);

 
     /**
         Sets the message that will be displayed on the dialog.
     */
 
     /**
         Sets the message that will be displayed on the dialog.
     */

-    void SetMessage(const wxString& message);
+    virtual void SetMessage(const wxString& message);

 
     /**
         Sets the path (the combined directory and filename that will be returned when
         the dialog is dismissed).
     */
 
     /**
         Sets the path (the combined directory and filename that will be returned when
         the dialog is dismissed).
     */

-    void SetPath(const wxString& path);
+    virtual void SetPath(const wxString& path);

 
     /**
         Sets the wildcard, which can contain multiple file types, for example:
 
     /**
         Sets the wildcard, which can contain multiple file types, for example:


@@ -212,13 +285,13 @@ public:
         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.
     */

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

-    int ShowModal();
+    virtual int ShowModal();

 };
 
 
 };
 
 


@@ -227,7 +300,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

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


@@ -271,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,