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