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. If the user cancels the dialog,
 398     the function returns -1 and @c selections array is left unchanged.
 399
 400     You may pass the list of strings to choose from either using @c choices
 401     which is an array of @a n strings for the listbox or by using a single
 402     @c aChoices parameter of type wxArrayString.
 403
 404     If @c centre is @true, the message text (which may include new line
 405     characters) is centred; if @false, the message is left-justified.
 406
 407     @header{wx/choicdlg.h}
 408 */
 409 int wxGetSelectedChoices(wxArrayInt& selections,
 410                             const wxString& message,
 411                             const wxString& caption,
 412                             const wxArrayString& aChoices,
 413                             wxWindow* parent = NULL,
 414                             int x = -1,
 415                             int y = -1,
 416                             bool centre = true,
 417                             int width = 150,
 418                             int height = 200);
 419 int wxGetSelectedChoices(wxArrayInt& selections,
 420                             const wxString& message,
 421                             const wxString& caption,
 422                             int n,
 423                             const wxString& choices[],
 424                             wxWindow* parent = NULL,
 425                             int x = -1,
 426                             int y = -1,
 427                             bool centre = true,
 428                             int width = 150,
 429                             int height = 200);
 430
 431 //@}
 432