interface/choicdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        choicdlg.h
   3 // Purpose:     documentation for wxMultiChoiceDialog class
   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     @seealso
  20     @ref overview_wxmultichoicedialogoverview "wxMultiChoiceDialog overview",
  21     wxSingleChoiceDialog
  22 */
  23 class wxMultiChoiceDialog : public wxDialog
  24 {
  25 public:
  26     //@{
  27     /**
  28         Constructor taking an array of wxString choices.
  29
  30         @param parent
  31             Parent window.
  32         @param message
  33             Message to show on the dialog.
  34         @param caption
  35             The dialog caption.
  36         @param n
  37             The number of choices.
  38         @param choices
  39             An array of strings, or a string list, containing the choices.
  40         @param style
  41             A dialog style (bitlist) containing flags chosen from standard
  42             dialog styles and the following:
  43
  44
  45
  46
  47
  48
  49
  50             wxOK
  51
  52
  53
  54
  55             Show an OK button.
  56
  57
  58
  59
  60
  61             wxCANCEL
  62
  63
  64
  65
  66             Show a Cancel button.
  67
  68
  69
  70
  71
  72             wxCENTRE
  73
  74
  75
  76
  77             Centre the message. Not Windows.
  78
  79
  80
  81
  82
  83             The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
  84         wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
  85         @param pos
  86             Dialog position. Not Windows.
  87
  88         @remarks Use ShowModal() to show the dialog.
  89     */
  90     wxMultiChoiceDialog(wxWindow* parent, const wxString& message,
  91                         const wxString& caption,
  92                         int n,
  93                         const wxString* choices,
  94                         long style = wxCHOICEDLG_STYLE,
  95                         const wxPoint& pos = wxDefaultPosition);
  96     wxMultiChoiceDialog(wxWindow* parent,
  97                         const wxString& message,
  98                         const wxString& caption,
  99                         const wxArrayString& choices,
 100                         long style = wxCHOICEDLG_STYLE,
 101                         const wxPoint& pos = wxDefaultPosition);
 102     //@}
 103
 104     /**
 105         Returns array with indexes of selected items.
 106     */
 107     wxArrayInt GetSelection() const;
 108
 109     /**
 110         Sets selected items from the array of selected items' indexes.
 111     */
 112     void SetSelections(const wxArrayInt& selections) const;
 113
 114     /**
 115         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 116     */
 117     int ShowModal();
 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     @seealso
 133     @ref overview_wxsinglechoicedialogoverview "wxSingleChoiceDialog overview",
 134     wxMultiChoiceDialog
 135 */
 136 class wxSingleChoiceDialog : public wxDialog
 137 {
 138 public:
 139     //@{
 140     /**
 141         Constructor, taking an array of wxString choices and optional client data.
 142
 143         @param parent
 144             Parent window.
 145         @param message
 146             Message to show on the dialog.
 147         @param caption
 148             The dialog caption.
 149         @param n
 150             The number of choices.
 151         @param choices
 152             An array of strings, or a string list, containing the choices.
 153         @param clientData
 154             An array of client data to be associated with the items.
 155             See GetSelectionClientData.
 156         @param style
 157             A dialog style (bitlist) containing flags chosen from standard
 158             dialog styles and the following:
 159
 160
 161
 162
 163
 164
 165
 166             wxOK
 167
 168
 169
 170
 171             Show an OK button.
 172
 173
 174
 175
 176
 177             wxCANCEL
 178
 179
 180
 181
 182             Show a Cancel button.
 183
 184
 185
 186
 187
 188             wxCENTRE
 189
 190
 191
 192
 193             Centre the message. Not Windows.
 194
 195
 196
 197
 198
 199             The default value is equivalent to wxDEFAULT_DIALOG_STYLE |
 200         wxRESIZE_BORDER |  wxOK |  wxCANCEL |  wxCENTRE.
 201         @param pos
 202             Dialog position. Not Windows.
 203
 204         @remarks Use ShowModal() to show the dialog.
 205     */
 206     wxSingleChoiceDialog(wxWindow* parent, const wxString& message,
 207                          const wxString& caption,
 208                          int n,
 209                          const wxString* choices,
 210                          void** clientData = NULL,
 211                          long style = wxCHOICEDLG_STYLE,
 212                          const wxPoint& pos = wxDefaultPosition);
 213     wxSingleChoiceDialog(wxWindow* parent,
 214                          const wxString& message,
 215                          const wxString& caption,
 216                          const wxArrayString& choices,
 217                          void** clientData = NULL,
 218                          long style = wxCHOICEDLG_STYLE,
 219                          const wxPoint& pos = wxDefaultPosition);
 220     //@}
 221
 222     /**
 223         Returns the index of selected item.
 224     */
 225     int GetSelection() const;
 226
 227     /**
 228         Returns the client data associated with the selection.
 229     */
 230     char* GetSelectionClientData() const;
 231
 232     /**
 233         Returns the selected string.
 234     */
 235     wxString GetStringSelection() const;
 236
 237     /**
 238         Sets the index of the initially selected item.
 239     */
 240     void SetSelection(int selection) const;
 241
 242     /**
 243         Shows the dialog, returning either wxID_OK or wxID_CANCEL.
 244     */
 245     int ShowModal();
 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