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 initialSelection = 0);
 321
 322 int wxGetSingleChoiceIndex(const wxString& message,
 323                            const wxString& caption,
 324                            int n,
 325                            const wxString& choices[],
 326                            wxWindow* parent = NULL,
 327                            int x = -1,
 328                            int y = -1,
 329                            bool centre = true,
 330                            int width = 150,
 331                            int height = 200,
 332                            int initialSelection = 0);
 333
 334
 335 int wxGetSingleChoiceIndex(const wxString& message,
 336                            const wxString& caption,
 337                            const wxArrayString& choices,
 338                            int initialSelection,
 339                            wxWindow *parent = NULL);
 340
 341 int wxGetSingleChoiceIndex(const wxString& message,
 342                            const wxString& caption,
 343                            int n, const wxString *choices,
 344                            int initialSelection,
 345                            wxWindow *parent = NULL);
 346 //@}
 347
 348 /** @addtogroup group_funcmacro_dialog */
 349 //@{
 350
 351 /**
 352     Pops up a dialog box containing a message, OK/Cancel buttons and a
 353     single-selection listbox. The user may choose an item and press OK to
 354     return a string or Cancel to return the empty string. Use
 355     wxGetSingleChoiceIndex() if empty string is a valid choice and if you want
 356     to be able to detect pressing Cancel reliably.
 357
 358     You may pass the list of strings to choose from either using @c choices
 359     which is an array of @a n strings for the listbox or by using a single
 360     @c aChoices parameter of type wxArrayString.
 361
 362     If @c centre is @true, the message text (which may include new line
 363     characters) is centred; if @false, the message is left-justified.
 364
 365     @header{wx/choicdlg.h}
 366
 367     @beginWxPerlOnly
 368     Use an array reference for the @a choices parameter.
 369     @endWxPerlOnly
 370 */
 371 wxString wxGetSingleChoice(const wxString& message,
 372                            const wxString& caption,
 373                            const wxArrayString& aChoices,
 374                            wxWindow* parent = NULL,
 375                            int x = -1,
 376                            int y = -1,
 377                            bool centre = true,
 378                            int width = 150,
 379                            int height = 200
 380                            int initialSelection = 0);
 381 wxString wxGetSingleChoice(const wxString& message,
 382                            const wxString& caption,
 383                            int n,
 384                            const wxString& choices[],
 385                            wxWindow* parent = NULL,
 386                            int x = -1,
 387                            int y = -1,
 388                            bool centre = true,
 389                            int width = 150,
 390                            int height = 200
 391                            int initialSelection = 0);
 392
 393
 394 wxString wxGetSingleChoice(const wxString& message,
 395                            const wxString& caption,
 396                            const wxArrayString& choices,
 397                            int initialSelection,
 398                            wxWindow *parent = NULL);
 399
 400 wxString wxGetSingleChoice(const wxString& message,
 401                            const wxString& caption,
 402                            int n, const wxString *choices,
 403                            int initialSelection,
 404                            wxWindow *parent = NULL);
 405
 406 //@}
 407
 408 /** @addtogroup group_funcmacro_dialog */
 409 //@{
 410
 411 /**
 412     Same as wxGetSingleChoice but takes an array of client data pointers
 413     corresponding to the strings, and returns one of these pointers or @NULL
 414     if Cancel was pressed. The @c client_data array must have the same number
 415     of elements as @c choices or @c aChoices!
 416
 417     @header{wx/choicdlg.h}
 418
 419     @beginWxPerlOnly
 420     Use an array reference for the @a aChoices and @a client_data parameters.
 421     @endWxPerlOnly
 422 */
 423 wxString wxGetSingleChoiceData(const wxString& message,
 424                                const wxString& caption,
 425                                const wxArrayString& aChoices,
 426                                const wxString& client_data[],
 427                                wxWindow* parent = NULL,
 428                                int x = -1,
 429                                int y = -1,
 430                                bool centre = true,
 431                                int width = 150,
 432                                int height = 200
 433                                int initialSelection = 0);
 434
 435 wxString wxGetSingleChoiceData(const wxString& message,
 436                                const wxString& caption,
 437                                int n,
 438                                const wxString& choices[],
 439                                const wxString& client_data[],
 440                                wxWindow* parent = NULL,
 441                                int x = -1,
 442                                int y = -1,
 443                                bool centre = true,
 444                                int width = 150,
 445                                int height = 200
 446                                int initialSelection = 0);
 447
 448 void* wxGetSingleChoiceData(const wxString& message,
 449                             const wxString& caption,
 450                             const wxArrayString& choices,
 451                             void **client_data,
 452                             int initialSelection,
 453                             wxWindow *parent = NULL);
 454
 455 void* wxGetSingleChoiceData(const wxString& message,
 456                             const wxString& caption,
 457                             int n, const wxString *choices,
 458                             void **client_data,
 459                             int initialSelection,
 460                             wxWindow *parent = NULL);
 461
 462 //@}
 463
 464 /** @addtogroup group_funcmacro_dialog */
 465 //@{
 466
 467 /**
 468     Pops up a dialog box containing a message, OK/Cancel buttons and a
 469     multiple-selection listbox. The user may choose an arbitrary (including 0)
 470     number of items in the listbox whose indices will be returned in
 471     @c selections array. The initial contents of this array will be used to
 472     select the items when the dialog is shown. If the user cancels the dialog,
 473     the function returns -1 and @c selections array is left unchanged.
 474
 475     You may pass the list of strings to choose from either using @c choices
 476     which is an array of @a n strings for the listbox or by using a single
 477     @c aChoices parameter of type wxArrayString.
 478
 479     If @c centre is @true, the message text (which may include new line
 480     characters) is centred; if @false, the message is left-justified.
 481
 482     @header{wx/choicdlg.h}
 483
 484     @beginWxPerlOnly
 485     Use an array reference for the @a choices parameter.
 486     In wxPerl there is no @a selections parameter; the function
 487     returns an array containing the user selections.
 488     @endWxPerlOnly
 489 */
 490 int wxGetSelectedChoices(wxArrayInt& selections,
 491                             const wxString& message,
 492                             const wxString& caption,
 493                             const wxArrayString& aChoices,
 494                             wxWindow* parent = NULL,
 495                             int x = -1,
 496                             int y = -1,
 497                             bool centre = true,
 498                             int width = 150,
 499                             int height = 200);
 500
 501 int wxGetSelectedChoices(wxArrayInt& selections,
 502                             const wxString& message,
 503                             const wxString& caption,
 504                             int n,
 505                             const wxString& choices[],
 506                             wxWindow* parent = NULL,
 507                             int x = -1,
 508                             int y = -1,
 509                             bool centre = true,
 510                             int width = 150,
 511                             int height = 200);
 512
 513 //@}
 514