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