]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/filepicker.h
Make storing non-trivial data in wxThreadSpecificInfo possible.
[wxWidgets.git] / interface / wx / filepicker.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: filepicker.h
e54c96f1 3// Purpose: interface of wxFilePickerCtrl
23324ae1 4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
23324ae1
FM
6/////////////////////////////////////////////////////////////////////////////
7
575821fa
RD
8#define wxFLP_OPEN 0x0400
9#define wxFLP_SAVE 0x0800
10#define wxFLP_OVERWRITE_PROMPT 0x1000
11#define wxFLP_FILE_MUST_EXIST 0x2000
12#define wxFLP_CHANGE_DIR 0x4000
13#define wxFLP_SMALL wxPB_SMALL
14#define wxFLP_USE_TEXTCTRL (wxPB_USE_TEXTCTRL)
15#define wxFLP_DEFAULT_STYLE (wxFLP_OPEN|wxFLP_FILE_MUST_EXIST)
16
17#define wxDIRP_DIR_MUST_EXIST 0x0008
18#define wxDIRP_CHANGE_DIR 0x0010
19#define wxDIRP_SMALL wxPB_SMALL
20#define wxDIRP_USE_TEXTCTRL (wxPB_USE_TEXTCTRL)
21#define wxDIRP_DEFAULT_STYLE (wxDIRP_DIR_MUST_EXIST)
22
ce7fe42e
VZ
23wxEventType wxEVT_FILEPICKER_CHANGED;
24wxEventType wxEVT_DIRPICKER_CHANGED;
575821fa
RD
25
26
23324ae1
FM
27/**
28 @class wxFilePickerCtrl
7c913512 29
23324ae1
FM
30 This control allows the user to select a file. The generic implementation is
31 a button which brings up a wxFileDialog when clicked. Native implementation
32 may differ but this is usually a (small) widget which give access to the
0b70c946 33 file-chooser dialog.
23324ae1 34 It is only available if @c wxUSE_FILEPICKERCTRL is set to 1 (the default).
7c913512 35
23324ae1 36 @beginStyleTable
8c6791e4 37 @style{wxFLP_DEFAULT_STYLE}
23324ae1
FM
38 The default style: includes wxFLP_OPEN | wxFLP_FILE_MUST_EXIST and,
39 under wxMSW only, wxFLP_USE_TEXTCTRL.
8c6791e4 40 @style{wxFLP_USE_TEXTCTRL}
23324ae1
FM
41 Creates a text control to the left of the picker button which is
42 completely managed by the wxFilePickerCtrl and which can be used by
43 the user to specify a path (see SetPath). The text control is
44 automatically synchronized with button's value. Use functions
45 defined in wxPickerBase to modify the text control.
8c6791e4 46 @style{wxFLP_OPEN}
23324ae1 47 Creates a picker which allows the user to select a file to open.
8c6791e4 48 @style{wxFLP_SAVE}
23324ae1 49 Creates a picker which allows the user to select a file to save.
8c6791e4 50 @style{wxFLP_OVERWRITE_PROMPT}
23324ae1
FM
51 Can be combined with wxFLP_SAVE only: ask confirmation to the user
52 before selecting a file.
8c6791e4 53 @style{wxFLP_FILE_MUST_EXIST}
23324ae1
FM
54 Can be combined with wxFLP_OPEN only: the selected file must be an
55 existing file.
8c6791e4 56 @style{wxFLP_CHANGE_DIR}
23324ae1 57 Change current working directory on each user file selection change.
75bc8b34
VZ
58 @style{wxFLP_SMALL}
59 Use smaller version of the control with a small "..." button instead
60 of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.
23324ae1 61 @endStyleTable
7c913512 62
0b70c946 63
3051a44a 64 @beginEventEmissionTable{wxFileDirPickerEvent}
0b70c946
FM
65 @event{EVT_FILEPICKER_CHANGED(id, func)}
66 The user changed the file selected in the control either using the
67 button or using text control (see wxFLP_USE_TEXTCTRL; note that in
68 this case the event is fired only if the user's input is valid,
69 e.g. an existing file path if wxFLP_FILE_MUST_EXIST was given).
70 @endEventTable
71
23324ae1 72 @library{wxcore}
d18d9f60 73 @category{pickers}
ce154616 74 @appearance{filepickerctrl}
7c913512 75
e54c96f1 76 @see wxFileDialog, wxFileDirPickerEvent
23324ae1
FM
77*/
78class wxFilePickerCtrl : public wxPickerBase
79{
80public:
575821fa
RD
81 wxFilePickerCtrl();
82
23324ae1
FM
83 /**
84 Initializes the object and calls Create() with
85 all the parameters.
86 */
4cc4bfaf 87 wxFilePickerCtrl(wxWindow* parent, wxWindowID id,
23324ae1 88 const wxString& path = wxEmptyString,
a44f3b5a
FM
89 const wxString& message = wxFileSelectorPromptStr,
90 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
23324ae1
FM
91 const wxPoint& pos = wxDefaultPosition,
92 const wxSize& size = wxDefaultSize,
93 long style = wxFLP_DEFAULT_STYLE,
94 const wxValidator& validator = wxDefaultValidator,
a44f3b5a 95 const wxString& name = wxFilePickerCtrlNameStr);
23324ae1
FM
96
97 /**
0b70c946
FM
98 Creates this widget with the given parameters.
99
7c913512 100 @param parent
4cc4bfaf 101 Parent window, must not be non-@NULL.
7c913512 102 @param id
4cc4bfaf 103 The identifier for the control.
7c913512 104 @param path
4cc4bfaf 105 The initial file shown in the control. Must be a valid path to a file or
0b70c946 106 the empty string.
7c913512 107 @param message
4cc4bfaf 108 The message shown to the user in the wxFileDialog shown by the control.
7c913512 109 @param wildcard
4cc4bfaf 110 A wildcard which defines user-selectable files (use the same syntax as for
0b70c946 111 wxFileDialog's wildcards).
7c913512 112 @param pos
4cc4bfaf 113 Initial position.
7c913512 114 @param size
4cc4bfaf 115 Initial size.
7c913512 116 @param style
4cc4bfaf 117 The window style, see wxFLP_* flags.
7c913512 118 @param validator
77bfb902 119 Validator which can be used for additional data checks.
7c913512 120 @param name
4cc4bfaf 121 Control name.
3c4f71cc 122
d29a9a8a 123 @return @true if the control was successfully created or @false if
0b70c946 124 creation failed.
23324ae1 125 */
4cc4bfaf 126 bool Create(wxWindow* parent, wxWindowID id,
23324ae1 127 const wxString& path = wxEmptyString,
43c48e1e
FM
128 const wxString& message = wxFileSelectorPromptStr,
129 const wxString& wildcard = wxFileSelectorDefaultWildcardStr,
23324ae1
FM
130 const wxPoint& pos = wxDefaultPosition,
131 const wxSize& size = wxDefaultSize,
132 long style = wxFLP_DEFAULT_STYLE,
133 const wxValidator& validator = wxDefaultValidator,
43c48e1e 134 const wxString& name = wxFilePickerCtrlNameStr);
23324ae1
FM
135
136 /**
0b70c946
FM
137 Similar to GetPath() but returns the path of the currently selected
138 file as a wxFileName object.
23324ae1 139 */
328f5751 140 wxFileName GetFileName() const;
23324ae1
FM
141
142 /**
143 Returns the absolute path of the currently selected file.
144 */
328f5751 145 wxString GetPath() const;
23324ae1
FM
146
147 /**
0b70c946
FM
148 This method does the same thing as SetPath() but takes a wxFileName
149 object instead of a string.
23324ae1 150 */
4cc4bfaf 151 void SetFileName(const wxFileName& filename);
23324ae1 152
75cb911c
VZ
153 /**
154 Set the directory to show when starting to browse for files.
155
156 This function is mostly useful for the file picker controls which have
157 no selection initially to configure the directory that should be shown
158 if the user starts browsing for files as otherwise the directory of
159 initially selected file is used, which is usually the desired
160 behaviour and so the directory specified by this function is ignored in
161 this case.
162
163 @since 2.9.4
164 */
165 void SetInitialDirectory(const wxString& dir);
166
23324ae1 167 /**
0b70c946
FM
168 Sets the absolute path of the currently selected file.
169 This must be a valid file if the @c wxFLP_FILE_MUST_EXIST style was given.
23324ae1 170 */
4cc4bfaf 171 void SetPath(const wxString& filename);
23324ae1
FM
172};
173
174
e54c96f1 175
23324ae1
FM
176/**
177 @class wxDirPickerCtrl
7c913512 178
23324ae1 179 This control allows the user to select a directory. The generic implementation
0b70c946 180 is a button which brings up a wxDirDialog when clicked. Native implementation
23324ae1 181 may differ but this is usually a (small) widget which give access to the
0b70c946 182 dir-chooser dialog.
23324ae1 183 It is only available if @c wxUSE_DIRPICKERCTRL is set to 1 (the default).
7c913512 184
23324ae1 185 @beginStyleTable
8c6791e4 186 @style{wxDIRP_DEFAULT_STYLE}
23324ae1
FM
187 The default style: includes wxDIRP_DIR_MUST_EXIST and, under wxMSW
188 only, wxDIRP_USE_TEXTCTRL.
8c6791e4 189 @style{wxDIRP_USE_TEXTCTRL}
23324ae1
FM
190 Creates a text control to the left of the picker button which is
191 completely managed by the wxDirPickerCtrl and which can be used by
192 the user to specify a path (see SetPath). The text control is
193 automatically synchronized with button's value. Use functions
194 defined in wxPickerBase to modify the text control.
8c6791e4 195 @style{wxDIRP_DIR_MUST_EXIST}
23324ae1
FM
196 Creates a picker which allows to select only existing directories.
197 wxGTK control always adds this flag internally as it does not
198 support its absence.
8c6791e4 199 @style{wxDIRP_CHANGE_DIR}
0b70c946 200 Change current working directory on each user directory selection change.
75bc8b34
VZ
201 @style{wxDIRP_SMALL}
202 Use smaller version of the control with a small "..." button instead
203 of the normal "Browse" one. This flag is new since wxWidgets 2.9.3.
23324ae1 204 @endStyleTable
7c913512 205
3051a44a 206 @beginEventEmissionTable{wxFileDirPickerEvent}
0b70c946
FM
207 @event{EVT_DIRPICKER_CHANGED(id, func)}
208 The user changed the directory selected in the control either using the
209 button or using text control (see wxDIRP_USE_TEXTCTRL; note that in this
210 case the event is fired only if the user's input is valid, e.g. an
211 existing directory path).
212 @endEventTable
213
214
23324ae1 215 @library{wxcore}
d18d9f60 216 @category{pickers}
ce154616 217 @appearance{dirpickerctrl}
7c913512 218
e54c96f1 219 @see wxDirDialog, wxFileDirPickerEvent
23324ae1
FM
220*/
221class wxDirPickerCtrl : public wxPickerBase
222{
223public:
575821fa
RD
224 wxDirPickerCtrl();
225
23324ae1
FM
226 /**
227 Initializes the object and calls Create() with
228 all the parameters.
229 */
4cc4bfaf 230 wxDirPickerCtrl(wxWindow* parent, wxWindowID id,
23324ae1 231 const wxString& path = wxEmptyString,
408776d0 232 const wxString& message = wxDirSelectorPromptStr,
23324ae1
FM
233 const wxPoint& pos = wxDefaultPosition,
234 const wxSize& size = wxDefaultSize,
235 long style = wxDIRP_DEFAULT_STYLE,
236 const wxValidator& validator = wxDefaultValidator,
408776d0 237 const wxString& name = wxDirPickerCtrlNameStr);
23324ae1
FM
238
239 /**
0b70c946
FM
240 Creates the widgets with the given parameters.
241
7c913512 242 @param parent
4cc4bfaf 243 Parent window, must not be non-@NULL.
7c913512 244 @param id
4cc4bfaf 245 The identifier for the control.
7c913512 246 @param path
4cc4bfaf 247 The initial directory shown in the control. Must be a valid path to a
0b70c946 248 directory or the empty string.
7c913512 249 @param message
4cc4bfaf 250 The message shown to the user in the wxDirDialog shown by the control.
7c913512 251 @param pos
4cc4bfaf 252 Initial position.
7c913512 253 @param size
4cc4bfaf 254 Initial size.
7c913512 255 @param style
4cc4bfaf 256 The window style, see wxDIRP_* flags.
7c913512 257 @param validator
4cc4bfaf 258 Validator which can be used for additional date checks.
7c913512 259 @param name
4cc4bfaf 260 Control name.
3c4f71cc 261
d29a9a8a 262 @return @true if the control was successfully created or @false if
0b70c946 263 creation failed.
23324ae1 264 */
4cc4bfaf 265 bool Create(wxWindow* parent, wxWindowID id,
23324ae1 266 const wxString& path = wxEmptyString,
43c48e1e 267 const wxString& message = wxDirSelectorPromptStr,
23324ae1
FM
268 const wxPoint& pos = wxDefaultPosition,
269 const wxSize& size = wxDefaultSize,
270 long style = wxDIRP_DEFAULT_STYLE,
271 const wxValidator& validator = wxDefaultValidator,
43c48e1e 272 const wxString& name = wxDirPickerCtrlNameStr);
23324ae1
FM
273
274 /**
0b70c946
FM
275 Returns the absolute path of the currently selected directory as a
276 wxFileName object.
277 This function is equivalent to GetPath().
23324ae1 278 */
328f5751 279 wxFileName GetDirName() const;
23324ae1
FM
280
281 /**
282 Returns the absolute path of the currently selected directory.
283 */
328f5751 284 wxString GetPath() const;
23324ae1
FM
285
286 /**
0b70c946 287 Just like SetPath() but this function takes a wxFileName object.
23324ae1 288 */
4cc4bfaf 289 void SetDirName(const wxFileName& dirname);
23324ae1 290
75cb911c
VZ
291 /**
292 Set the directory to show when starting to browse for directories.
293
294 This function is mostly useful for the directory picker controls which
295 have no selection initially to configure the directory that should be
296 shown if the user starts browsing for directories as otherwise the
297 initially selected directory is used, which is usually the desired
298 behaviour and so the directory specified by this function is ignored in
299 this case.
300
301 @since 2.9.4
302 */
303 void SetInitialDirectory(const wxString& dir);
304
23324ae1 305 /**
04783062
VZ
306 Sets the absolute path of the currently selected directory (the default converter uses current locale's
307 charset).
0b70c946 308 This must be a valid directory if @c wxDIRP_DIR_MUST_EXIST style was given.
23324ae1 309 */
4cc4bfaf 310 void SetPath(const wxString& dirname);
23324ae1
FM
311};
312
313
e54c96f1 314
23324ae1
FM
315/**
316 @class wxFileDirPickerEvent
7c913512 317
23324ae1
FM
318 This event class is used for the events generated by
319 wxFilePickerCtrl and by wxDirPickerCtrl.
7c913512 320
674d80a7
FM
321 @beginEventTable{wxFileDirPickerEvent}
322 @event{EVT_FILEPICKER_CHANGED(id, func)}
323 Generated whenever the selected file changes.
324 @event{EVT_DIRPICKER_CHANGED(id, func)}
325 Generated whenever the selected directory changes.
326 @endEventTable
327
23324ae1 328 @library{wxcore}
0b70c946 329 @category{events}
7c913512 330
0b70c946 331 @see wxFilePickerCtrl, wxDirPickerCtrl
23324ae1
FM
332*/
333class wxFileDirPickerEvent : public wxCommandEvent
334{
335public:
575821fa
RD
336 wxFileDirPickerEvent();
337
23324ae1
FM
338 /**
339 The constructor is not normally used by the user code.
340 */
4cc4bfaf 341 wxFileDirPickerEvent(wxEventType type, wxObject* generator,
23324ae1 342 int id,
a44f3b5a 343 const wxString& path);
23324ae1
FM
344
345 /**
346 Retrieve the absolute path of the file/directory the user has just selected.
347 */
328f5751 348 wxString GetPath() const;
23324ae1
FM
349
350 /**
351 Set the absolute path of the file/directory associated with the event.
352 */
4cc4bfaf 353 void SetPath(const wxString& path);
23324ae1 354};
e54c96f1 355