X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12f5e1e78fe906050ff2fee9529476db332633f0..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/filedlg.h?ds=sidebyside diff --git a/interface/wx/filedlg.h b/interface/wx/filedlg.h index 4fe26d6c86..92ac23c70c 100644 --- a/interface/wx/filedlg.h +++ b/interface/wx/filedlg.h @@ -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 @@ -24,41 +98,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: + @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} @category{cmndlg} - @see @ref overview_wxfiledialog, ::wxFileSelector() + @see @ref overview_cmndlg_file, ::wxFileSelector() */ class wxFileDialog : public wxDialog { @@ -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); //@}