interface/wx/choicdlg.h

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