]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: filedlg.h | |
e54c96f1 | 3 | // Purpose: interface of wxFileDialog |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxFileDialog | |
7c913512 | 11 | |
23324ae1 | 12 | This class represents the file chooser dialog. |
7c913512 | 13 | |
0ce6d6c8 FM |
14 | It pops up a file selector box (native for Windows and GTK2.4+). |
15 | ||
16 | The path and filename are distinct elements of a full file pathname. | |
17 | If path is "", the current directory will be used. If filename is "", no default | |
18 | filename will be supplied. The wildcard determines what files are displayed in the | |
19 | file selector, and file extension supplies a type extension for the required filename. | |
20 | ||
21 | @remarks | |
22 | All implementations of the wxFileDialog provide a wildcard filter. Typing a filename | |
23 | containing wildcards (*, ?) in the filename text item, and clicking on Ok, will | |
24 | result in only those files matching the pattern being displayed. | |
25 | The wildcard may be a specification for multiple types of file with a description | |
26 | for each, such as: | |
0b70c946 | 27 | @code |
0ce6d6c8 | 28 | "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png" |
0b70c946 | 29 | @endcode |
0ce6d6c8 FM |
30 | It must be noted that wildcard support in the native Motif file dialog is quite |
31 | limited: only one alternative is supported, and it is displayed without the | |
32 | descriptive test; "BMP files (*.bmp)|*.bmp" is displayed as "*.bmp", and both | |
33 | "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" and "Image files|*.bmp;*.gif" | |
34 | are errors. | |
35 | ||
23324ae1 | 36 | @beginStyleTable |
8c6791e4 | 37 | @style{wxFD_DEFAULT_STYLE} |
23324ae1 | 38 | Equivalent to wxFD_OPEN. |
8c6791e4 | 39 | @style{wxFD_OPEN} |
23324ae1 | 40 | This is an open dialog; usually this means that the default |
0ce6d6c8 | 41 | button's label of the dialog is "Open". Cannot be combined with wxFD_SAVE. |
8c6791e4 | 42 | @style{wxFD_SAVE} |
23324ae1 FM |
43 | This is a save dialog; usually this means that the default button's |
44 | label of the dialog is "Save". Cannot be combined with wxFD_OPEN. | |
8c6791e4 | 45 | @style{wxFD_OVERWRITE_PROMPT} |
23324ae1 FM |
46 | For save dialog only: prompt for a confirmation if a file will be |
47 | overwritten. | |
8c6791e4 | 48 | @style{wxFD_FILE_MUST_EXIST} |
0ce6d6c8 | 49 | For open dialog only: the user may only select files that actually exist. |
8c6791e4 | 50 | @style{wxFD_MULTIPLE} |
23324ae1 | 51 | For open dialog only: allows selecting multiple files. |
8c6791e4 | 52 | @style{wxFD_CHANGE_DIR} |
23324ae1 FM |
53 | Change the current working directory to the directory where the |
54 | file(s) chosen by the user are. | |
8c6791e4 | 55 | @style{wxFD_PREVIEW} |
23324ae1 FM |
56 | Show the preview of the selected files (currently only supported by |
57 | wxGTK using GTK+ 2.4 or later). | |
58 | @endStyleTable | |
7c913512 | 59 | |
23324ae1 FM |
60 | @library{wxcore} |
61 | @category{cmndlg} | |
7c913512 | 62 | |
23b7f0cb | 63 | @see @ref overview_cmndlg_file, ::wxFileSelector() |
23324ae1 FM |
64 | */ |
65 | class wxFileDialog : public wxDialog | |
66 | { | |
67 | public: | |
68 | /** | |
69 | Constructor. Use ShowModal() to show the dialog. | |
3c4f71cc | 70 | |
7c913512 | 71 | @param parent |
4cc4bfaf | 72 | Parent window. |
7c913512 | 73 | @param message |
4cc4bfaf | 74 | Message to show on the dialog. |
7c913512 | 75 | @param defaultDir |
4cc4bfaf | 76 | The default directory, or the empty string. |
7c913512 | 77 | @param defaultFile |
4cc4bfaf | 78 | The default filename, or the empty string. |
7c913512 | 79 | @param wildcard |
0ce6d6c8 | 80 | A wildcard, such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". |
4cc4bfaf FM |
81 | Note that the native Motif dialog has some limitations with respect to |
82 | wildcards; see the Remarks section above. | |
7c913512 | 83 | @param style |
4cc4bfaf | 84 | A dialog style. See wxFD_* styles for more info. |
7c913512 | 85 | @param pos |
4cc4bfaf | 86 | Dialog position. Not implemented. |
7c913512 | 87 | @param size |
4cc4bfaf | 88 | Dialog size. Not implemented. |
7c913512 | 89 | @param name |
4cc4bfaf | 90 | Dialog name. Not implemented. |
23324ae1 FM |
91 | */ |
92 | wxFileDialog(wxWindow* parent, | |
a44f3b5a FM |
93 | const wxString& message = wxFileSelectorPromptStr, |
94 | const wxString& defaultDir = wxEmptyString, | |
95 | const wxString& defaultFile = wxEmptyString, | |
96 | const wxString& wildcard = wxFileSelectorDefaultWildcardStr, | |
23324ae1 FM |
97 | long style = wxFD_DEFAULT_STYLE, |
98 | const wxPoint& pos = wxDefaultPosition, | |
76e9224e | 99 | const wxSize& size = wxDefaultSize, |
a44f3b5a | 100 | const wxString& name = wxFileDialogNameStr); |
23324ae1 FM |
101 | |
102 | /** | |
103 | Destructor. | |
104 | */ | |
adaaa686 | 105 | virtual ~wxFileDialog(); |
23324ae1 FM |
106 | |
107 | /** | |
108 | Returns the default directory. | |
109 | */ | |
adaaa686 | 110 | virtual wxString GetDirectory() const; |
23324ae1 FM |
111 | |
112 | /** | |
0ce6d6c8 | 113 | If functions SetExtraControlCreator() and ShowModal() were called, |
23324ae1 FM |
114 | returns the extra window. Otherwise returns @NULL. |
115 | */ | |
328f5751 | 116 | wxWindow* GetExtraControl() const; |
23324ae1 FM |
117 | |
118 | /** | |
119 | Returns the default filename. | |
120 | */ | |
adaaa686 | 121 | virtual wxString GetFilename() const; |
23324ae1 FM |
122 | |
123 | /** | |
0ce6d6c8 FM |
124 | Fills the array @a filenames with the names of the files chosen. |
125 | ||
126 | This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, | |
23324ae1 | 127 | use GetFilename() for the others. |
0ce6d6c8 | 128 | |
23324ae1 FM |
129 | Note that under Windows, if the user selects shortcuts, the filenames |
130 | include paths, since the application cannot determine the full path | |
131 | of each referenced file by appending the directory containing the shortcuts | |
132 | to the filename. | |
133 | */ | |
adaaa686 | 134 | virtual void GetFilenames(wxArrayString& filenames) const; |
23324ae1 FM |
135 | |
136 | /** | |
137 | Returns the index into the list of filters supplied, optionally, in the | |
138 | wildcard parameter. | |
0ce6d6c8 | 139 | |
23324ae1 FM |
140 | Before the dialog is shown, this is the index which will be used when the |
141 | dialog is first displayed. | |
0ce6d6c8 | 142 | |
23324ae1 FM |
143 | After the dialog is shown, this is the index selected by the user. |
144 | */ | |
adaaa686 | 145 | virtual int GetFilterIndex() const; |
23324ae1 FM |
146 | |
147 | /** | |
148 | Returns the message that will be displayed on the dialog. | |
149 | */ | |
adaaa686 | 150 | virtual wxString GetMessage() const; |
23324ae1 FM |
151 | |
152 | /** | |
153 | Returns the full path (directory and filename) of the selected file. | |
154 | */ | |
adaaa686 | 155 | virtual wxString GetPath() const; |
23324ae1 FM |
156 | |
157 | /** | |
0ce6d6c8 FM |
158 | Fills the array @a paths with the full paths of the files chosen. |
159 | ||
160 | This function should only be used with the dialogs which have @c wxFD_MULTIPLE style, | |
23324ae1 FM |
161 | use GetPath() for the others. |
162 | */ | |
adaaa686 | 163 | virtual void GetPaths(wxArrayString& paths) const; |
23324ae1 FM |
164 | |
165 | /** | |
166 | Returns the file dialog wildcard. | |
167 | */ | |
adaaa686 | 168 | virtual wxString GetWildcard() const; |
23324ae1 FM |
169 | |
170 | /** | |
171 | Sets the default directory. | |
172 | */ | |
adaaa686 | 173 | virtual void SetDirectory(const wxString& directory); |
23324ae1 FM |
174 | |
175 | /** | |
176 | Customize file dialog by adding extra window, which is typically placed | |
177 | below the list of files and above the buttons. | |
0ce6d6c8 FM |
178 | |
179 | SetExtraControlCreator() can be called only once, before calling ShowModal(). | |
180 | ||
23324ae1 FM |
181 | The @c creator function should take pointer to parent window (file dialog) |
182 | and should return a window allocated with operator new. | |
0ce6d6c8 | 183 | |
23324ae1 FM |
184 | Supported platforms: wxGTK, wxUniv. |
185 | */ | |
5267aefd | 186 | bool SetExtraControlCreator(ExtraControlCreatorFunction); |
23324ae1 FM |
187 | |
188 | /** | |
189 | Sets the default filename. | |
190 | */ | |
adaaa686 | 191 | virtual void SetFilename(const wxString& setfilename); |
23324ae1 FM |
192 | |
193 | /** | |
194 | Sets the default filter index, starting from zero. | |
195 | */ | |
adaaa686 | 196 | virtual void SetFilterIndex(int filterIndex); |
23324ae1 FM |
197 | |
198 | /** | |
199 | Sets the message that will be displayed on the dialog. | |
200 | */ | |
adaaa686 | 201 | virtual void SetMessage(const wxString& message); |
23324ae1 FM |
202 | |
203 | /** | |
204 | Sets the path (the combined directory and filename that will be returned when | |
205 | the dialog is dismissed). | |
206 | */ | |
adaaa686 | 207 | virtual void SetPath(const wxString& path); |
23324ae1 FM |
208 | |
209 | /** | |
210 | Sets the wildcard, which can contain multiple file types, for example: | |
0ce6d6c8 FM |
211 | "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". |
212 | ||
23324ae1 FM |
213 | Note that the native Motif dialog has some limitations with respect to |
214 | wildcards; see the Remarks section above. | |
215 | */ | |
adaaa686 | 216 | virtual void SetWildcard(const wxString& wildCard); |
23324ae1 FM |
217 | |
218 | /** | |
219 | Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL | |
220 | otherwise. | |
221 | */ | |
adaaa686 | 222 | virtual int ShowModal(); |
23324ae1 FM |
223 | }; |
224 | ||
225 | ||
e54c96f1 | 226 | |
23324ae1 FM |
227 | // ============================================================================ |
228 | // Global functions/macros | |
229 | // ============================================================================ | |
230 | ||
ba2874ff BP |
231 | /** @ingroup group_funcmacro_dialog */ |
232 | //@{ | |
233 | ||
23324ae1 FM |
234 | /** |
235 | Pops up a file selector box. In Windows, this is the common file selector | |
ba2874ff BP |
236 | dialog. In X, this is a file selector box with the same functionality. The |
237 | path and filename are distinct elements of a full file pathname. If path | |
238 | is empty, the current directory will be used. If filename is empty, no | |
239 | default filename will be supplied. The wildcard determines what files are | |
240 | displayed in the file selector, and file extension supplies a type | |
241 | extension for the required filename. Flags may be a combination of | |
242 | wxFD_OPEN, wxFD_SAVE, wxFD_OVERWRITE_PROMPT or wxFD_FILE_MUST_EXIST. | |
243 | ||
244 | @note wxFD_MULTIPLE can only be used with wxFileDialog and not here since | |
245 | this function only returns a single file name. | |
246 | ||
23324ae1 FM |
247 | Both the Unix and Windows versions implement a wildcard filter. Typing a |
248 | filename containing wildcards (*, ?) in the filename text item, and | |
249 | clicking on Ok, will result in only those files matching the pattern being | |
250 | displayed. | |
ba2874ff BP |
251 | |
252 | The wildcard may be a specification for multiple types of file with a | |
253 | description for each, such as: | |
4cc4bfaf | 254 | |
23324ae1 FM |
255 | @code |
256 | "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" | |
257 | @endcode | |
7c913512 | 258 | |
23324ae1 FM |
259 | The application must check for an empty return value (the user pressed |
260 | Cancel). For example: | |
4cc4bfaf | 261 | |
23324ae1 FM |
262 | @code |
263 | wxString filename = wxFileSelector("Choose a file to open"); | |
264 | if ( !filename.empty() ) | |
265 | { | |
266 | // work with the file | |
267 | ... | |
268 | } | |
269 | //else: cancelled by user | |
270 | @endcode | |
ba2874ff BP |
271 | |
272 | @header{wx/filedlg.h} | |
23324ae1 FM |
273 | */ |
274 | wxString wxFileSelector(const wxString& message, | |
275 | const wxString& default_path = "", | |
276 | const wxString& default_filename = "", | |
277 | const wxString& default_extension = "", | |
278 | const wxString& wildcard = ".", | |
279 | int flags = 0, | |
4cc4bfaf | 280 | wxWindow* parent = NULL, |
23324ae1 FM |
281 | int x = -1, |
282 | int y = -1); | |
283 | ||
ba2874ff BP |
284 | //@} |
285 |