]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/filedlg.h
Move code removing "-psn_xxx" command line arguments to common code.
[wxWidgets.git] / interface / wx / filedlg.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: filedlg.h
e54c96f1 3// Purpose: interface of wxFileDialog
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
e9321277
RD
8enum
9{
10 wxFD_OPEN = 0x0001,
11 wxFD_SAVE = 0x0002,
12 wxFD_OVERWRITE_PROMPT = 0x0004,
13 wxFD_FILE_MUST_EXIST = 0x0010,
14 wxFD_MULTIPLE = 0x0020,
15 wxFD_CHANGE_DIR = 0x0080,
16 wxFD_PREVIEW = 0x0100
17};
18
50e55c13
RD
19#define wxFD_DEFAULT_STYLE wxFD_OPEN
20
0b59366f
VZ
21/**
22 Default wildcard string used in wxFileDialog corresponding to all files.
23
24 It is defined as "*.*" under MSW and OS/2 and "*" everywhere else.
25*/
26const char wxFileSelectorDefaultWildcardStr[];
27
23324ae1
FM
28/**
29 @class wxFileDialog
7c913512 30
23324ae1 31 This class represents the file chooser dialog.
7c913512 32
0ce6d6c8 33 The path and filename are distinct elements of a full file pathname.
9d90f08b
FM
34 If path is ::wxEmptyString, the current directory will be used.
35 If filename is ::wxEmptyString, no default filename will be supplied.
e9c3992c
FM
36 The wildcard determines what files are displayed in the file selector,
37 and file extension supplies a type extension for the required filename.
0ce6d6c8 38
9d90f08b
FM
39 The typical usage for the open file dialog is:
40 @code
41 void MyFrame::OnOpen(wxCommandEvent& WXUNUSED(event))
42 {
43 if (...current content has not been saved...)
44 {
45 if (wxMessageBox(_("Current content has not been saved! Proceed?"), _("Please confirm"),
46 wxICON_QUESTION | wxYES_NO, this) == wxNO )
47 return;
48 //else: proceed asking to the user the new file to open
49 }
50
51 wxFileDialog
52 openFileDialog(this, _("Open XYZ file"), "", "",
53 "XYZ files (*.xyz)|*.xyz", wxFD_OPEN|wxFD_FILE_MUST_EXIST);
54
55 if (openFileDialog.ShowModal() == wxID_CANCEL)
56 return; // the user changed idea...
57
58 // proceed loading the file chosen by the user;
59 // this can be done with e.g. wxWidgets input streams:
60 wxFileInputStream input_stream(openFileDialog.GetPath());
61 if (!input_stream.IsOk())
62 {
63 wxLogError("Cannot open file '%s'.", openFileDialog.GetPath());
64 return;
65 }
66
67 ...
68 }
69 @endcode
70
71 The typical usage for the save file dialog is instead somewhat simpler:
72 @code
73 void MyFrame::OnSaveAs(wxCommandEvent& WXUNUSED(event))
74 {
75 wxFileDialog
76 saveFileDialog(this, _("Save XYZ file"), "", "",
77 "XYZ files (*.xyz)|*.xyz", wxFD_SAVE|wxFD_OVERWRITE_PROMPT);
78
79 if (saveFileDialog.ShowModal() == wxID_CANCEL)
80 return; // the user changed idea...
81
82 // save the current contents in the file;
83 // this can be done with e.g. wxWidgets output streams:
84 wxFileOutputStream output_stream(saveFileDialog.GetPath());
85 if (!output_stream.IsOk())
86 {
87 wxLogError("Cannot save current contents in file '%s'.", saveFileDialog.GetPath());
88 return;
89 }
90
91 ...
92 }
93 @endcode
94
0ce6d6c8
FM
95 @remarks
96 All implementations of the wxFileDialog provide a wildcard filter. Typing a filename
97 containing wildcards (*, ?) in the filename text item, and clicking on Ok, will
98 result in only those files matching the pattern being displayed.
99 The wildcard may be a specification for multiple types of file with a description
100 for each, such as:
0b70c946 101 @code
0ce6d6c8 102 "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"
0b70c946 103 @endcode
0ce6d6c8 104 It must be noted that wildcard support in the native Motif file dialog is quite
806f8df3 105 limited: only one file type is supported, and it is displayed without the
0ce6d6c8
FM
106 descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both
107 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif"
108 are errors.
109
23324ae1 110 @beginStyleTable
8c6791e4 111 @style{wxFD_DEFAULT_STYLE}
9d90f08b 112 Equivalent to @c wxFD_OPEN.
8c6791e4 113 @style{wxFD_OPEN}
23324ae1 114 This is an open dialog; usually this means that the default
9d90f08b 115 button's label of the dialog is "Open". Cannot be combined with @c wxFD_SAVE.
8c6791e4 116 @style{wxFD_SAVE}
23324ae1 117 This is a save dialog; usually this means that the default button's
9d90f08b 118 label of the dialog is "Save". Cannot be combined with @c wxFD_OPEN.
8c6791e4 119 @style{wxFD_OVERWRITE_PROMPT}
23324ae1
FM
120 For save dialog only: prompt for a confirmation if a file will be
121 overwritten.
8c6791e4 122 @style{wxFD_FILE_MUST_EXIST}
83527a0a
VZ
123 For open dialog only: the user may only select files that actually
124 exist. Notice that under OS X the file dialog with @c wxFD_OPEN
125 style always behaves as if this style was specified, because it is
126 impossible to choose a file that doesn't exist from a standard OS X
127 file dialog.
8c6791e4 128 @style{wxFD_MULTIPLE}
23324ae1 129 For open dialog only: allows selecting multiple files.
8c6791e4 130 @style{wxFD_CHANGE_DIR}
9d90f08b
FM
131 Change the current working directory (when the dialog is dismissed)
132 to the directory where the file(s) chosen by the user are.
8c6791e4 133 @style{wxFD_PREVIEW}
23324ae1 134 Show the preview of the selected files (currently only supported by
d6dae1b4 135 wxGTK).
23324ae1 136 @endStyleTable
7c913512 137
23324ae1
FM
138 @library{wxcore}
139 @category{cmndlg}
7c913512 140
23b7f0cb 141 @see @ref overview_cmndlg_file, ::wxFileSelector()
23324ae1
FM
142*/
143class wxFileDialog : public wxDialog
144{
145public:
146 /**
147 Constructor. Use ShowModal() to show the dialog.
3c4f71cc 148
7c913512 149 @param parent
4cc4bfaf 150 Parent window.
7c913512 151 @param message
4cc4bfaf 152 Message to show on the dialog.
7c913512 153 @param defaultDir
4cc4bfaf 154 The default directory, or the empty string.
7c913512 155 @param defaultFile
4cc4bfaf 156 The default filename, or the empty string.
7c913512 157 @param wildcard
0ce6d6c8 158 A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
4cc4bfaf
FM
159 Note that the native Motif dialog has some limitations with respect to
160 wildcards; see the Remarks section above.
7c913512 161 @param style
9d90f08b 162 A dialog style. See @c wxFD_* styles for more info.
7c913512 163 @param pos
4cc4bfaf 164 Dialog position. Not implemented.
7c913512 165 @param size
4cc4bfaf 166 Dialog size. Not implemented.
7c913512 167 @param name
4cc4bfaf 168 Dialog name. Not implemented.
23324ae1
FM
169 */
170 wxFileDialog(wxWindow* parent,
a44f3b5a
FM
171 const wxString& message = wxFileSelectorPromptStr,
172 const wxString& defaultDir = wxEmptyString,
173 const wxString& defaultFile = wxEmptyString,
174 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
23324ae1
FM
175 long style = wxFD_DEFAULT_STYLE,
176 const wxPoint& pos = wxDefaultPosition,
76e9224e 177 const wxSize& size = wxDefaultSize,
a44f3b5a 178 const wxString& name = wxFileDialogNameStr);
23324ae1
FM
179
180 /**
181 Destructor.
182 */
adaaa686 183 virtual ~wxFileDialog();
23324ae1 184
926df8a1
VZ
185 /**
186 Returns the path of the file currently selected in dialog.
187
188 Notice that this file is not necessarily going to be accepted by the
189 user, so calling this function mostly makes sense from an update UI
190 event handler of a custom file dialog extra control to update its state
191 depending on the currently selected file.
192
193 Currently this function is fully implemented under GTK and MSW and
194 always returns an empty string elsewhere.
195
196 @since 2.9.5
197
198 @return The path of the currently selected file or an empty string if
199 nothing is selected.
200
201 @see SetExtraControlCreator()
202 */
203 virtual wxString GetCurrentlySelectedFilename() const;
204
23324ae1
FM
205 /**
206 Returns the default directory.
207 */
adaaa686 208 virtual wxString GetDirectory() const;
23324ae1
FM
209
210 /**
0ce6d6c8 211 If functions SetExtraControlCreator() and ShowModal() were called,
23324ae1 212 returns the extra window. Otherwise returns @NULL.
d6dae1b4
VZ
213
214 @since 2.9.0
23324ae1 215 */
328f5751 216 wxWindow* GetExtraControl() const;
23324ae1
FM
217
218 /**
219 Returns the default filename.
220 */
adaaa686 221 virtual wxString GetFilename() const;
23324ae1
FM
222
223 /**
0ce6d6c8
FM
224 Fills the array @a filenames with the names of the files chosen.
225
226 This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
23324ae1 227 use GetFilename() for the others.
0ce6d6c8 228
23324ae1
FM
229 Note that under Windows, if the user selects shortcuts, the filenames
230 include paths, since the application cannot determine the full path
231 of each referenced file by appending the directory containing the shortcuts
232 to the filename.
233 */
adaaa686 234 virtual void GetFilenames(wxArrayString& filenames) const;
23324ae1
FM
235
236 /**
237 Returns the index into the list of filters supplied, optionally, in the
238 wildcard parameter.
0ce6d6c8 239
23324ae1
FM
240 Before the dialog is shown, this is the index which will be used when the
241 dialog is first displayed.
0ce6d6c8 242
23324ae1
FM
243 After the dialog is shown, this is the index selected by the user.
244 */
adaaa686 245 virtual int GetFilterIndex() const;
23324ae1
FM
246
247 /**
248 Returns the message that will be displayed on the dialog.
249 */
adaaa686 250 virtual wxString GetMessage() const;
23324ae1
FM
251
252 /**
253 Returns the full path (directory and filename) of the selected file.
254 */
adaaa686 255 virtual wxString GetPath() const;
23324ae1
FM
256
257 /**
0ce6d6c8
FM
258 Fills the array @a paths with the full paths of the files chosen.
259
260 This function should only be used with the dialogs which have @c wxFD_MULTIPLE style,
23324ae1
FM
261 use GetPath() for the others.
262 */
adaaa686 263 virtual void GetPaths(wxArrayString& paths) const;
23324ae1
FM
264
265 /**
266 Returns the file dialog wildcard.
267 */
adaaa686 268 virtual wxString GetWildcard() const;
23324ae1
FM
269
270 /**
271 Sets the default directory.
272 */
adaaa686 273 virtual void SetDirectory(const wxString& directory);
23324ae1 274
d6dae1b4
VZ
275 /**
276 The type of function used as an argument for SetExtraControlCreator().
277
278 @since 2.9.0
279 */
280 typedef wxWindow *(*ExtraControlCreatorFunction)(wxWindow*);
281
23324ae1
FM
282 /**
283 Customize file dialog by adding extra window, which is typically placed
284 below the list of files and above the buttons.
0ce6d6c8
FM
285
286 SetExtraControlCreator() can be called only once, before calling ShowModal().
287
23324ae1
FM
288 The @c creator function should take pointer to parent window (file dialog)
289 and should return a window allocated with operator new.
0ce6d6c8 290
d6dae1b4
VZ
291 Supported platforms: wxGTK, wxMSW, wxUniv.
292
293 @since 2.9.0
23324ae1 294 */
d6dae1b4 295 bool SetExtraControlCreator(ExtraControlCreatorFunction creator);
23324ae1
FM
296
297 /**
298 Sets the default filename.
02a40b8a
JS
299
300 In wxGTK this will have little effect unless a default directory has previously been set.
23324ae1 301 */
adaaa686 302 virtual void SetFilename(const wxString& setfilename);
23324ae1
FM
303
304 /**
305 Sets the default filter index, starting from zero.
306 */
adaaa686 307 virtual void SetFilterIndex(int filterIndex);
23324ae1
FM
308
309 /**
310 Sets the message that will be displayed on the dialog.
311 */
adaaa686 312 virtual void SetMessage(const wxString& message);
23324ae1
FM
313
314 /**
315 Sets the path (the combined directory and filename that will be returned when
316 the dialog is dismissed).
317 */
adaaa686 318 virtual void SetPath(const wxString& path);
23324ae1
FM
319
320 /**
321 Sets the wildcard, which can contain multiple file types, for example:
0ce6d6c8
FM
322 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
323
23324ae1
FM
324 Note that the native Motif dialog has some limitations with respect to
325 wildcards; see the Remarks section above.
326 */
adaaa686 327 virtual void SetWildcard(const wxString& wildCard);
23324ae1
FM
328
329 /**
9d90f08b 330 Shows the dialog, returning @c wxID_OK if the user pressed OK, and @c wxID_CANCEL
23324ae1
FM
331 otherwise.
332 */
adaaa686 333 virtual int ShowModal();
23324ae1
FM
334};
335
336
e54c96f1 337
23324ae1
FM
338// ============================================================================
339// Global functions/macros
340// ============================================================================
341
b21126db 342/** @addtogroup group_funcmacro_dialog */
ba2874ff
BP
343//@{
344
23324ae1
FM
345/**
346 Pops up a file selector box. In Windows, this is the common file selector
ba2874ff
BP
347 dialog. In X, this is a file selector box with the same functionality. The
348 path and filename are distinct elements of a full file pathname. If path
349 is empty, the current directory will be used. If filename is empty, no
350 default filename will be supplied. The wildcard determines what files are
351 displayed in the file selector, and file extension supplies a type
352 extension for the required filename. Flags may be a combination of
353 wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST.
354
355 @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since
356 this function only returns a single file name.
357
23324ae1
FM
358 Both the Unix and Windows versions implement a wildcard filter. Typing a
359 filename containing wildcards (*, ?) in the filename text item, and
360 clicking on Ok, will result in only those files matching the pattern being
361 displayed.
ba2874ff
BP
362
363 The wildcard may be a specification for multiple types of file with a
364 description for each, such as:
4cc4bfaf 365
23324ae1
FM
366 @code
367 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
368 @endcode
7c913512 369
23324ae1
FM
370 The application must check for an empty return value (the user pressed
371 Cancel). For example:
4cc4bfaf 372
23324ae1
FM
373 @code
374 wxString filename = wxFileSelector("Choose a file to open");
375 if ( !filename.empty() )
376 {
377 // work with the file
378 ...
379 }
380 //else: cancelled by user
381 @endcode
ba2874ff
BP
382
383 @header{wx/filedlg.h}
23324ae1
FM
384*/
385wxString wxFileSelector(const wxString& message,
e9c3992c
FM
386 const wxString& default_path = wxEmptyString,
387 const wxString& default_filename = wxEmptyString,
388 const wxString& default_extension = wxEmptyString,
0b59366f 389 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
23324ae1 390 int flags = 0,
4cc4bfaf 391 wxWindow* parent = NULL,
0b59366f
VZ
392 int x = wxDefaultCoord,
393 int y = wxDefaultCoord);
23324ae1 394
68a8473f
VZ
395/**
396 An extended version of wxFileSelector
397*/
398wxString wxFileSelectorEx(const wxString& message = wxFileSelectorPromptStr,
399 const wxString& default_path = wxEmptyString,
400 const wxString& default_filename = wxEmptyString,
401 int *indexDefaultExtension = NULL,
402 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
403 int flags = 0,
404 wxWindow *parent = NULL,
405 int x = wxDefaultCoord,
406 int y = wxDefaultCoord);
407
408/**
409 Ask for filename to load
410*/
411wxString wxLoadFileSelector(const wxString& what,
412 const wxString& extension,
413 const wxString& default_name = wxEmptyString,
414 wxWindow *parent = NULL);
415
416/**
417 Ask for filename to save
418*/
419wxString wxSaveFileSelector(const wxString& what,
420 const wxString& extension,
421 const wxString& default_name = wxEmptyString,
422 wxWindow *parent = NULL);
423
ba2874ff
BP
424//@}
425