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