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