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