interface/choicdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        choicdlg.h
   3 // Purpose:     interface of wxMultiChoiceDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMultiChoiceDialog
  11     @wxheader{choicdlg.h}
  12
  13     This class represents a dialog that shows a list of strings, and allows
  14     the user to select one or more.
  15
  16     @library{wxbase}
  17     @category{cmndlg}
  18
  19     @see @ref overview_wxmultichoicedialogoverview "wxMultiChoiceDialog overview",
  20     wxSingleChoiceDialog
  21 */
  22 class wxMultiChoiceDialog : public wxDialog
  23 {
  24 public:
  25     //@{
  26     /**
  27         Constructor taking an array of wxString choices.
  28
  29         @param parent
  30             Parent window.
  31         @param message
  32             Message to show on the dialog.
  33         @param caption
  34             The dialog caption.
  35         @param n
  36             The number of choices.
  37         @param choices
  38             An array of strings, or a string list, containing the choices.
  39         @param style
  40             A dialog style (bitlist) containing flags chosen from standard
  41             dialog styles and the following:
  42
  43
  44
  45
  46
  47
  48
  49             wxOK
  50
  51
  52
  53
  54             Show an OK button.
  55
  56
  57
  58
  59
  60             wxCANCEL
  61
  62
  63
  64
  65             Show a Cancel button.
  66
  67
  68
  69
  70
  71             wxCENTRE
  72
  73
  74
  75
  76             Centre the message. Not Windows.
  77
  78
  79
  80
  81
  82             The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
  83         wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
  84         @param pos
  85             Dialog position. Not Windows.
  86
  87         @remarks Use ShowModal() to show the dialog.
  88     */
  89     wxMultiChoiceDialog(wxWindow* parent, const wxString& message,
  90                         const wxString& caption,
  91                         int n,
  92                         const wxString* choices,
  93                         long style = wxCHOICEDLG_STYLE,
  94                         const wxPoint& pos = wxDefaultPosition);
  95     wxMultiChoiceDialog(wxWindow* parent,
  96                         const wxString& message,
  97                         const wxString& caption,
  98                         const wxArrayString& choices,
  99                         long style = wxCHOICEDLG_STYLE,
 100                         const wxPoint& pos = wxDefaultPosition);
 101     //@}
 102
 103     /**
 104         Returns array with indexes of selected items.
 105     */
 106     wxArrayInt GetSelection() const;
 107
 108     /**
 109         Sets selected items from the array of selected items' indexes.
 110     */
 111     void SetSelections(const wxArrayInt& selections) const;
 112
 113     /**
 114         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 115     */
 116     int ShowModal();
 117 };
 118
 119
 120
 121 /**
 122     @class wxSingleChoiceDialog
 123     @wxheader{choicdlg.h}
 124
 125     This class represents a dialog that shows a list of strings, and allows the
 126     user to select one. Double-clicking on a list item is equivalent to
 127     single-clicking and then pressing OK.
 128
 129     @library{wxbase}
 130     @category{cmndlg}
 131
 132     @see @ref overview_wxsinglechoicedialogoverview "wxSingleChoiceDialog
 133     overview", wxMultiChoiceDialog
 134 */
 135 class wxSingleChoiceDialog : public wxDialog
 136 {
 137 public:
 138     //@{
 139     /**
 140         Constructor, taking an array of wxString choices and optional client data.
 141
 142         @param parent
 143             Parent window.
 144         @param message
 145             Message to show on the dialog.
 146         @param caption
 147             The dialog caption.
 148         @param n
 149             The number of choices.
 150         @param choices
 151             An array of strings, or a string list, containing the choices.
 152         @param clientData
 153             An array of client data to be associated with the items.
 154             See GetSelectionClientData.
 155         @param style
 156             A dialog style (bitlist) containing flags chosen from standard
 157             dialog styles and the following:
 158
 159
 160
 161
 162
 163
 164
 165             wxOK
 166
 167
 168
 169
 170             Show an OK button.
 171
 172
 173
 174
 175
 176             wxCANCEL
 177
 178
 179
 180
 181             Show a Cancel button.
 182
 183
 184
 185
 186
 187             wxCENTRE
 188
 189
 190
 191
 192             Centre the message. Not Windows.
 193
 194
 195
 196
 197
 198             The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
 199         wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
 200         @param pos
 201             Dialog position. Not Windows.
 202
 203         @remarks Use ShowModal() to show the dialog.
 204     */
 205     wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
 206                          const wxString& caption,
 207                          int n,
 208                          const wxString* choices,
 209                          void** clientData = NULL,
 210                          long style = wxCHOICEDLG_STYLE,
 211                          const wxPoint& pos = wxDefaultPosition);
 212     wxSingleChoiceDialog(wxWindow* parent,
 213                          const wxString& message,
 214                          const wxString& caption,
 215                          const wxArrayString& choices,
 216                          void** clientData = NULL,
 217                          long style = wxCHOICEDLG_STYLE,
 218                          const wxPoint& pos = wxDefaultPosition);
 219     //@}
 220
 221     /**
 222         Returns the index of selected item.
 223     */
 224     int GetSelection() const;
 225
 226     /**
 227         Returns the client data associated with the selection.
 228     */
 229     char* GetSelectionClientData() const;
 230
 231     /**
 232         Returns the selected string.
 233     */
 234     wxString GetStringSelection() const;
 235
 236     /**
 237         Sets the index of the initially selected item.
 238     */
 239     void SetSelection(int selection) const;
 240
 241     /**
 242         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 243     */
 244     int ShowModal();
 245 };
 246
 247
 248
 249 // ============================================================================
 250 // Global functions/macros
 251 // ============================================================================
 252
 253 //@{
 254 /**
 255     As @b wxGetSingleChoice but returns the index representing the selected
 256     string. If the user pressed cancel, -1 is returned.
 257 */
 258 int wxGetSingleChoiceIndex(const wxString& message,
 259                            const wxString& caption,
 260                            const wxArrayString& aChoices,
 261                            wxWindow* parent = NULL,
 262                            int x = -1,
 263                            int y = -1,
 264                            bool centre = true,
 265                            int width = 150,
 266                            int height = 200);
 267 int wxGetSingleChoiceIndex(const wxString& message,
 268                            const wxString& caption,
 269                            int n,
 270                            const wxString& choices[],
 271                            wxWindow* parent = NULL,
 272                            int x = -1,
 273                            int y = -1,
 274                            bool centre = true,
 275                            int width = 150,
 276                            int height = 200);
 277 //@}
 278
 279 //@{
 280 /**
 281     Pops up a dialog box containing a message, OK/Cancel buttons and a
 282     single-selection listbox. The user may choose an item and press OK to return a
 283     string or Cancel to return the empty string. Use
 284     wxGetSingleChoiceIndex() if empty string is a
 285     valid choice and if you want to be able to detect pressing Cancel reliably.
 286     You may pass the list of strings to choose from either using @e choices
 287     which is an array of @a n strings for the listbox or by using a single
 288     @a aChoices parameter of type wxArrayString.
 289     If @a centre is @true, the message text (which may include new line
 290     characters) is centred; if @false, the message is left-justified.
 291 */
 292 wxString wxGetSingleChoice(const wxString& message,
 293                            const wxString& caption,
 294                            const wxArrayString& aChoices,
 295                            wxWindow* parent = NULL,
 296                            int x = -1,
 297                            int y = -1,
 298                            bool centre = true,
 299                            int width = 150,
 300                            int height = 200);
 301 wxString wxGetSingleChoice(const wxString& message,
 302                            const wxString& caption,
 303                            int n,
 304                            const wxString& choices[],
 305                            wxWindow* parent = NULL,
 306                            int x = -1,
 307                            int y = -1,
 308                            bool centre = true,
 309                            int width = 150,
 310                            int height = 200);
 311 //@}
 312
 313 //@{
 314 /**
 315     As @b wxGetSingleChoice but takes an array of client data pointers
 316     corresponding to the strings, and returns one of these pointers or @NULL if
 317     Cancel was pressed. The @e client_data array must have the same number of
 318     elements as @e choices or @e aChoices!
 319 */
 320 wxString wxGetSingleChoiceData(const wxString& message,
 321                                const wxString& caption,
 322                                const wxArrayString& aChoices,
 323                                const wxString& client_data[],
 324                                wxWindow* parent = NULL,
 325                                int x = -1,
 326                                int y = -1,
 327                                bool centre = true,
 328                                int width = 150,
 329                                int height = 200);
 330 wxString wxGetSingleChoiceData(const wxString& message,
 331                                const wxString& caption,
 332                                int n,
 333                                const wxString& choices[],
 334                                const wxString& client_data[],
 335                                wxWindow* parent = NULL,
 336                                int x = -1,
 337                                int y = -1,
 338                                bool centre = true,
 339                                int width = 150,
 340                                int height = 200);
 341 //@}
 342
 343 //@{
 344 /**
 345     Pops up a dialog box containing a message, OK/Cancel buttons and a
 346     multiple-selection listbox. The user may choose an arbitrary (including 0)
 347     number of items in the listbox whose indices will be returned in
 348     @e selection array. The initial contents of this array will be used to
 349     select the items when the dialog is shown.
 350     You may pass the list of strings to choose from either using @e choices
 351     which is an array of @a n strings for the listbox or by using a single
 352     @a aChoices parameter of type wxArrayString.
 353     If @a centre is @true, the message text (which may include new line
 354     characters) is centred; if @false, the message is left-justified.
 355 */
 356 size_t wxGetMultipleChoices(wxArrayInt& selections,
 357                             const wxString& message,
 358                             const wxString& caption,
 359                             const wxArrayString& aChoices,
 360                             wxWindow* parent = NULL,
 361                             int x = -1,
 362                             int y = -1,
 363                             bool centre = true,
 364                             int width = 150,
 365                             int height = 200);
 366 size_t wxGetMultipleChoices(wxArrayInt& selections,
 367                             const wxString& message,
 368                             const wxString& caption,
 369                             int n,
 370                             const wxString& choices[],
 371                             wxWindow* parent = NULL,
 372                             int x = -1,
 373                             int y = -1,
 374                             bool centre = true,
 375                             int width = 150,
 376                             int height = 200);
 377 //@}
 378