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