]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/filedlg.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / filedlg.h
index 89760406b1108fc58cec7acead3e552cbac8f72b..92ac23c70ca7291deda0585bd51d7db4bf2ab07d 100644 (file)
@@ -2,21 +2,95 @@
 // Name:        filedlg.h
 // Purpose:     interface of wxFileDialog
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+enum
+{
+    wxFD_OPEN              = 0x0001,
+    wxFD_SAVE              = 0x0002,
+    wxFD_OVERWRITE_PROMPT  = 0x0004,
+    wxFD_FILE_MUST_EXIST   = 0x0010,
+    wxFD_MULTIPLE          = 0x0020,
+    wxFD_CHANGE_DIR        = 0x0080,
+    wxFD_PREVIEW           = 0x0100
+};
+
+#define wxFD_DEFAULT_STYLE      wxFD_OPEN
+
+/**
+    Default wildcard string used in wxFileDialog corresponding to all files.
+
+    It is defined as "*.*" under MSW and OS/2 and "*" everywhere else.
+*/
+const char wxFileSelectorDefaultWildcardStr[];
+
 /**
     @class wxFileDialog
 
     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.
+    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
     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"
+    @endcode
     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}
-           Equivalent to wxFD_OPEN.
+           Equivalent to @c wxFD_OPEN.
     @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
-           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}
-           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}
-           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
-           wxGTK using GTK+ 2.4 or later).
+           wxGTK).
     @endStyleTable
 
     @library{wxcore}
@@ -79,7 +159,7 @@ public:
             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
@@ -88,35 +168,57 @@ public:
             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,
-                 const wxSize& sz = wxDefaultSize,
-                 const wxString& name = "filedlg");
+                 const wxSize& size = wxDefaultSize,
+                 const wxString& name = wxFileDialogNameStr);
 
     /**
         Destructor.
     */
-    ~wxFileDialog();
+    virtual ~wxFileDialog();
+
+    /**
+        Returns the path of the file currently selected in dialog.
+
+        Notice that this file is not necessarily going to be accepted by the
+        user, so calling this function mostly makes sense from an update UI
+        event handler of a custom file dialog extra control to update its state
+        depending on the currently selected file.
+
+        Currently this function is fully implemented under GTK and MSW and
+        always returns an empty string elsewhere.
+
+        @since 2.9.5
+
+        @return The path of the currently selected file or an empty string if
+            nothing is selected.
+
+        @see SetExtraControlCreator()
+    */
+    virtual wxString GetCurrentlySelectedFilename() const;
 
     /**
         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.
+
+        @since 2.9.0
     */
     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.
@@ -129,7 +231,7 @@ public:
         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
@@ -140,17 +242,17 @@ public:
 
         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.
     */
-    wxString GetMessage() const;
+    virtual wxString GetMessage() const;
 
     /**
         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.
@@ -158,17 +260,24 @@ public:
         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.
     */
-    wxString GetWildcard() const;
+    virtual wxString GetWildcard() const;
 
     /**
         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
@@ -179,30 +288,34 @@ public:
         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.
+        
+        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.
     */
-    void SetFilterIndex(int filterIndex);
+    virtual void SetFilterIndex(int filterIndex);
 
     /**
         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).
     */
-    void SetPath(const wxString& path);
+    virtual void SetPath(const wxString& path);
 
     /**
         Sets the wildcard, which can contain multiple file types, for example:
@@ -211,13 +324,13 @@ public:
         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.
     */
-    int ShowModal();
+    virtual int ShowModal();
 };
 
 
@@ -226,7 +339,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */
 //@{
 
 /**
@@ -270,14 +383,43 @@ public:
     @header{wx/filedlg.h}
 */
 wxString wxFileSelector(const wxString& message,
-                        const wxString& default_path = "",
-                        const wxString& default_filename = "",
-                        const wxString& default_extension = "",
-                        const wxString& wildcard = ".",
+                        const wxString& default_path = wxEmptyString,
+                        const wxString& default_filename = wxEmptyString,
+                        const wxString& default_extension = wxEmptyString,
+                        const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
                         int flags = 0,
                         wxWindow* parent = NULL,
-                        int x = -1,
-                        int y = -1);
+                        int x = wxDefaultCoord,
+                        int y = wxDefaultCoord);
+
+/**
+    An extended version of wxFileSelector
+*/
+wxString wxFileSelectorEx(const wxString& message = wxFileSelectorPromptStr,
+                          const wxString& default_path = wxEmptyString,
+                          const wxString& default_filename = wxEmptyString,
+                          int *indexDefaultExtension = NULL,
+                          const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
+                          int flags = 0,
+                          wxWindow *parent = NULL,
+                          int x = wxDefaultCoord,
+                          int y = wxDefaultCoord);
+
+/**
+    Ask for filename to load
+*/
+wxString wxLoadFileSelector(const wxString& what,
+                            const wxString& extension,
+                            const wxString& default_name = wxEmptyString,
+                            wxWindow *parent = NULL);
+
+/**
+    Ask for filename to save
+*/
+wxString wxSaveFileSelector(const wxString& what,
+                            const wxString& extension,
+                            const wxString& default_name = wxEmptyString,
+                            wxWindow *parent = NULL);
 
 //@}