bd2238a33b7831d2cdb210d4044840d28c138c45
[wxWidgets.git] / interface / wx / choicdlg.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: choicdlg.h
3 // Purpose: interface of wx[Multi|Single]ChoiceDialog
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxMultiChoiceDialog
11
12 This class represents a dialog that shows a list of strings, and allows the
13 user to select one or more.
14
15 @library{wxbase}
16 @category{cmndlg}
17
18 @see @ref overview_cmndlg_multichoice, wxSingleChoiceDialog
19 */
20 class wxMultiChoiceDialog : public wxDialog
21 {
22 public:
23 //@{
24 /**
25 Constructor taking an array of wxString choices.
26
27 @param parent
28 Parent window.
29 @param message
30 Message to show on the dialog.
31 @param caption
32 The dialog caption.
33 @param n
34 The number of choices.
35 @param choices
36 An array of strings, or a string list, containing the choices.
37 @param style
38 A dialog style (bitlist) containing flags chosen from standard
39 dialog style and the ones listed below. The default value is
40 equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
41 wxCANCEL | wxCENTRE.
42 @param pos
43 Dialog position. Not Windows.
44
45 @beginStyleTable
46 @style{wxOK}
47 Show an OK button.
48 @style{wxCANCEL}
49 Show a Cancel button.
50 @style{wxCENTRE}
51 Centre the message. Not Windows.
52 @endStyleTable
53
54 @remarks Use ShowModal() to show the dialog.
55
56 @beginWxPythonOnly
57
58 For Python the two parameters @a n and @a choices are collapsed into a
59 multi parameter @a choices which is expected to be a Python list of
60 strings.
61
62 @endWxPythonOnly
63 */
64 wxMultiChoiceDialog(wxWindow* parent, const wxString& message,
65 const wxString& caption,
66 int n, const wxString* choices,
67 long style = wxCHOICEDLG_STYLE,
68 const wxPoint& pos = wxDefaultPosition);
69 /**
70 Constructor taking an array of wxString choices.
71
72 @param parent
73 Parent window.
74 @param message
75 Message to show on the dialog.
76 @param caption
77 The dialog caption.
78 @param choices
79 An array of strings, or a string list, containing the choices.
80 @param style
81 A dialog style (bitlist) containing flags chosen from standard
82 dialog style and the ones listed below. The default value is
83 equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
84 wxCANCEL | wxCENTRE.
85 @param pos
86 Dialog position. Not Windows.
87
88 @beginStyleTable
89 @style{wxOK}
90 Show an OK button.
91 @style{wxCANCEL}
92 Show a Cancel button.
93 @style{wxCENTRE}
94 Centre the message. Not Windows.
95 @endStyleTable
96
97 @remarks Use ShowModal() to show the dialog.
98
99 @beginWxPythonOnly
100
101 For Python the two parameters @a n and @a choices are collapsed into a
102 multi parameter @a choices which is expected to be a Python list of
103 strings.
104
105 @endWxPythonOnly
106 */
107 wxMultiChoiceDialog(wxWindow* parent,
108 const wxString& message,
109 const wxString& caption,
110 const wxArrayString& choices,
111 long style = wxCHOICEDLG_STYLE,
112 const wxPoint& pos = wxDefaultPosition);
113 //@}
114
115 /**
116 Returns array with indexes of selected items.
117 */
118 wxArrayInt GetSelection() const;
119
120 /**
121 Sets selected items from the array of selected items' indexes.
122 */
123 void SetSelections(const wxArrayInt& selections);
124
125 /**
126 Shows the dialog, returning either wxID_OK or wxID_CANCEL.
127 */
128 int ShowModal();
129 };
130
131
132
133 /**
134 @class wxSingleChoiceDialog
135
136 This class represents a dialog that shows a list of strings, and allows the
137 user to select one. Double-clicking on a list item is equivalent to
138 single-clicking and then pressing OK.
139
140 @library{wxbase}
141 @category{cmndlg}
142
143 @see @ref overview_cmndlg_singlechoice, wxMultiChoiceDialog
144 */
145 class wxSingleChoiceDialog : public wxDialog
146 {
147 public:
148 //@{
149 /**
150 Constructor, taking an array of wxString choices and optional client
151 data.
152
153 @param parent
154 Parent window.
155 @param message
156 Message to show on the dialog.
157 @param caption
158 The dialog caption.
159 @param n
160 The number of choices.
161 @param choices
162 An array of strings, or a string list, containing the choices.
163 @param clientData
164 An array of client data to be associated with the items. See
165 GetSelectionClientData().
166 @param style
167 A dialog style (bitlist) containing flags chosen from standard
168 dialog styles and the ones listed below. The default value is
169 equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
170 wxCANCEL | wxCENTRE.
171 @param pos
172 Dialog position. Not Windows.
173
174 @beginStyleTable
175 @style{wxOK}
176 Show an OK button.
177 @style{wxCANCEL}
178 Show a Cancel button.
179 @style{wxCENTRE}
180 Centre the message. Not Windows.
181 @endStyleTable
182
183 @remarks Use ShowModal() to show the dialog.
184
185 @beginWxPythonOnly
186
187 For Python the two parameters @a n and @a choices are collapsed into a
188 multi parameter @a choices which is expected to be a Python list of
189 strings.
190
191 @endWxPythonOnly
192 */
193 wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
194 const wxString& caption,
195 int n, const wxString* choices,
196 void** clientData = NULL,
197 long style = wxCHOICEDLG_STYLE,
198 const wxPoint& pos = wxDefaultPosition);
199 /**
200 Constructor, taking an array of wxString choices and optional client
201 data.
202
203 @param parent
204 Parent window.
205 @param message
206 Message to show on the dialog.
207 @param caption
208 The dialog caption.
209 @param choices
210 An array of strings, or a string list, containing the choices.
211 @param clientData
212 An array of client data to be associated with the items. See
213 GetSelectionClientData().
214 @param style
215 A dialog style (bitlist) containing flags chosen from standard
216 dialog styles and the ones listed below. The default value is
217 equivalent to wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxOK |
218 wxCANCEL | wxCENTRE.
219 @param pos
220 Dialog position. Not Windows.
221
222 @beginStyleTable
223 @style{wxOK}
224 Show an OK button.
225 @style{wxCANCEL}
226 Show a Cancel button.
227 @style{wxCENTRE}
228 Centre the message. Not Windows.
229 @endStyleTable
230
231 @remarks Use ShowModal() to show the dialog.
232
233 @beginWxPythonOnly
234
235 For Python the two parameters @a n and @a choices are collapsed into a
236 multi parameter @a choices which is expected to be a Python list of
237 strings.
238
239 @endWxPythonOnly
240 */
241 wxSingleChoiceDialog(wxWindow* parent,
242 const wxString& message,
243 const wxString& caption,
244 const wxArrayString& choices,
245 void** clientData = NULL,
246 long style = wxCHOICEDLG_STYLE,
247 const wxPoint& pos = wxDefaultPosition);
248 //@}
249
250 /**
251 Returns the index of selected item.
252 */
253 int GetSelection() const;
254
255 /**
256 Returns the client data associated with the selection.
257 */
258 char* GetSelectionClientData() const;
259
260 /**
261 Returns the selected string.
262 */
263 wxString GetStringSelection() const;
264
265 /**
266 Sets the index of the initially selected item.
267 */
268 void SetSelection(int selection);
269
270 /**
271 Shows the dialog, returning either wxID_OK or wxID_CANCEL.
272 */
273 int ShowModal();
274 };
275
276
277
278 // ============================================================================
279 // Global functions/macros
280 // ============================================================================
281
282 /** @addtogroup group_funcmacro_dialog */
283 //@{
284
285 /**
286 Same as wxGetSingleChoice() but returns the index representing the
287 selected string. If the user pressed cancel, -1 is returned.
288
289 @header{wx/choicdlg.h}
290 */
291 int wxGetSingleChoiceIndex(const wxString& message,
292 const wxString& caption,
293 const wxArrayString& aChoices,
294 wxWindow* parent = NULL,
295 int x = -1,
296 int y = -1,
297 bool centre = true,
298 int width = 150,
299 int height = 200);
300 int wxGetSingleChoiceIndex(const wxString& message,
301 const wxString& caption,
302 int n,
303 const wxString& choices[],
304 wxWindow* parent = NULL,
305 int x = -1,
306 int y = -1,
307 bool centre = true,
308 int width = 150,
309 int height = 200);
310
311 //@}
312
313 /** @addtogroup group_funcmacro_dialog */
314 //@{
315
316 /**
317 Pops up a dialog box containing a message, OK/Cancel buttons and a
318 single-selection listbox. The user may choose an item and press OK to
319 return a string or Cancel to return the empty string. Use
320 wxGetSingleChoiceIndex() if empty string is a valid choice and if you want
321 to be able to detect pressing Cancel reliably.
322
323 You may pass the list of strings to choose from either using @c choices
324 which is an array of @a n strings for the listbox or by using a single
325 @c aChoices parameter of type wxArrayString.
326
327 If @c centre is @true, the message text (which may include new line
328 characters) is centred; if @false, the message is left-justified.
329
330 @header{wx/choicdlg.h}
331 */
332 wxString wxGetSingleChoice(const wxString& message,
333 const wxString& caption,
334 const wxArrayString& aChoices,
335 wxWindow* parent = NULL,
336 int x = -1,
337 int y = -1,
338 bool centre = true,
339 int width = 150,
340 int height = 200);
341 wxString wxGetSingleChoice(const wxString& message,
342 const wxString& caption,
343 int n,
344 const wxString& choices[],
345 wxWindow* parent = NULL,
346 int x = -1,
347 int y = -1,
348 bool centre = true,
349 int width = 150,
350 int height = 200);
351
352 //@}
353
354 /** @addtogroup group_funcmacro_dialog */
355 //@{
356
357 /**
358 Same as wxGetSingleChoice but takes an array of client data pointers
359 corresponding to the strings, and returns one of these pointers or @NULL
360 if Cancel was pressed. The @c client_data array must have the same number
361 of elements as @c choices or @c aChoices!
362
363 @header{wx/choicdlg.h}
364 */
365 wxString wxGetSingleChoiceData(const wxString& message,
366 const wxString& caption,
367 const wxArrayString& aChoices,
368 const wxString& client_data[],
369 wxWindow* parent = NULL,
370 int x = -1,
371 int y = -1,
372 bool centre = true,
373 int width = 150,
374 int height = 200);
375 wxString wxGetSingleChoiceData(const wxString& message,
376 const wxString& caption,
377 int n,
378 const wxString& choices[],
379 const wxString& client_data[],
380 wxWindow* parent = NULL,
381 int x = -1,
382 int y = -1,
383 bool centre = true,
384 int width = 150,
385 int height = 200);
386
387 //@}
388
389 /** @addtogroup group_funcmacro_dialog */
390 //@{
391
392 /**
393 Pops up a dialog box containing a message, OK/Cancel buttons and a
394 multiple-selection listbox. The user may choose an arbitrary (including 0)
395 number of items in the listbox whose indices will be returned in
396 @c selections array. The initial contents of this array will be used to
397 select the items when the dialog is shown.
398
399 You may pass the list of strings to choose from either using @c choices
400 which is an array of @a n strings for the listbox or by using a single
401 @c aChoices parameter of type wxArrayString.
402
403 If @c centre is @true, the message text (which may include new line
404 characters) is centred; if @false, the message is left-justified.
405
406 @header{wx/choicdlg.h}
407 */
408 size_t wxGetMultipleChoices(wxArrayInt& selections,
409 const wxString& message,
410 const wxString& caption,
411 const wxArrayString& aChoices,
412 wxWindow* parent = NULL,
413 int x = -1,
414 int y = -1,
415 bool centre = true,
416 int width = 150,
417 int height = 200);
418 size_t wxGetMultipleChoices(wxArrayInt& selections,
419 const wxString& message,
420 const wxString& caption,
421 int n,
422 const wxString& choices[],
423 wxWindow* parent = NULL,
424 int x = -1,
425 int y = -1,
426 bool centre = true,
427 int width = 150,
428 int height = 200);
429
430 //@}
431