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