// 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
"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}
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
*/
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.
*/
/**
If functions SetExtraControlCreator() and ShowModal() were called,
returns the extra window. Otherwise returns @NULL.
+
+ @since 2.9.0
*/
wxWindow* GetExtraControl() const;
*/
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.
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.
+
+ In wxGTK this will have little effect unless a default directory has previously been set.
*/
virtual void SetFilename(const wxString& setfilename);
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();
// Global functions/macros
// ============================================================================
-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */
//@{
/**
@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);
//@}
projects / wxWidgets.git / blobdiff