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     @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 GetSelections() 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             GetSelectionData().
 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             GetSelectionData().
 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         @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 = -1,
 318                            int y = -1,
 319                            bool centre = true,
 320                            int width = 150,
 321                            int height = 200,
 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 = -1,
 330                            int y = -1,
 331                            bool centre = true,
 332                            int width = 150,
 333                            int height = 200,
 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 = -1,
 378                            int y = -1,
 379                            bool centre = true,
 380                            int width = 150,
 381                            int height = 200
 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 = -1,
 389                            int y = -1,
 390                            bool centre = true,
 391                            int width = 150,
 392                            int height = 200
 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 = -1,
 431                                int y = -1,
 432                                bool centre = true,
 433                                int width = 150,
 434                                int height = 200
 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 = -1,
 444                                int y = -1,
 445                                bool centre = true,
 446                                int width = 150,
 447                                int height = 200
 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 = -1,
 498                             int y = -1,
 499                             bool centre = true,
 500                             int width = 150,
 501                             int height = 200);
 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 = -1,
 510                             int y = -1,
 511                             bool centre = true,
 512                             int width = 150,
 513                             int height = 200);
 514
 515 //@}
 516