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