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