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