interface/radiobox.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        radiobox.h
   3 // Purpose:     documentation for wxRadioBox class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRadioBox
  11     @wxheader{radiobox.h}
  12
  13     A radio box item is used to select one of number of mutually exclusive
  14     choices.  It is displayed as a vertical column or horizontal row of
  15     labelled buttons.
  16
  17     @beginStyleTable
  18     @style{wxRA_SPECIFY_ROWS}:
  19            The major dimension parameter refers to the maximum number of rows.
  20     @style{wxRA_SPECIFY_COLS}:
  21            The major dimension parameter refers to the maximum number of
  22            columns.
  23     @style{wxRA_USE_CHECKBOX}:
  24            Use of the checkbox controls instead of radio buttons (currently
  25            supported only on PalmOS)
  26     @endStyleTable
  27
  28     @beginEventTable
  29     @event{EVT_RADIOBOX(id\, func)}:
  30            Process a wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton
  31            is clicked.
  32     @endEventTable
  33
  34     @library{wxcore}
  35     @category{ctrl}
  36     @appearance{radiobox.png}
  37
  38     @seealso
  39     @ref overview_eventhandlingoverview "Event handling overview", wxRadioButton,
  40     wxCheckBox
  41 */
  42 class wxRadioBox : public wxControlWithItems
  43 {
  44 public:
  45     //@{
  46     /**
  47         Constructor, creating and showing a radiobox.
  48
  49         @param parent
  50         Parent window. Must not be @NULL.
  51
  52         @param id
  53         Window identifier. The value wxID_ANY indicates a default value.
  54
  55         @param label
  56         Label for the static box surrounding the radio buttons.
  57
  58         @param pos
  59         Window position. If wxDefaultPosition is specified then a default position
  60         is chosen.
  61
  62         @param size
  63         Window size. If wxDefaultSize is specified then a default size is
  64         chosen.
  65
  66         @param n
  67         Number of choices with which to initialize the radiobox.
  68
  69         @param choices
  70         An array of choices with which to initialize the radiobox.
  71
  72         @param majorDimension
  73         Specifies the maximum number of rows (if style contains wxRA_SPECIFY_ROWS) or
  74         columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional
  75         radiobox.
  76
  77         @param style
  78         Window style. See wxRadioBox.
  79
  80         @param validator
  81         Window validator.
  82
  83         @param name
  84         Window name.
  85
  86         @sa Create(), wxValidator
  87     */
  88     wxRadioBox();
  89     wxRadioBox(wxWindow* parent, wxWindowID id,
  90                const wxString& label,
  91                const wxPoint& point = wxDefaultPosition,
  92                const wxSize& size = wxDefaultSize,
  93                int n = 0,
  94                const wxString choices[] = @NULL,
  95                int majorDimension = 0,
  96                long style = wxRA_SPECIFY_COLS,
  97                const wxValidator& validator = wxDefaultValidator,
  98                const wxString& name = "radioBox");
  99     wxRadioBox(wxWindow* parent, wxWindowID id,
 100                const wxString& label,
 101                const wxPoint& point,
 102                const wxSize& size,
 103                const wxArrayString& choices,
 104                int majorDimension = 0,
 105                long style = wxRA_SPECIFY_COLS,
 106                const wxValidator& validator = wxDefaultValidator,
 107                const wxString& name = "radioBox");
 108     //@}
 109
 110     /**
 111         Destructor, destroying the radiobox item.
 112     */
 113     ~wxRadioBox();
 114
 115     //@{
 116     /**
 117         Creates the radiobox for two-step construction. See wxRadioBox()
 118         for further details.
 119     */
 120     bool Create(wxWindow* parent, wxWindowID id,
 121                 const wxString& label,
 122                 const wxPoint& point = wxDefaultPosition,
 123                 const wxSize& size = wxDefaultSize,
 124                 int n = 0,
 125                 const wxString choices[] = @NULL,
 126                 int majorDimension = 0,
 127                 long style = wxRA_SPECIFY_COLS,
 128                 const wxValidator& validator = wxDefaultValidator,
 129                 const wxString& name = "radioBox");
 130     bool Create(wxWindow* parent, wxWindowID id,
 131                 const wxString& label,
 132                 const wxPoint& point,
 133                 const wxSize& size,
 134                 const wxArrayString& choices,
 135                 int majorDimension = 0,
 136                 long style = wxRA_SPECIFY_COLS,
 137                 const wxValidator& validator = wxDefaultValidator,
 138                 const wxString& name = "radioBox");
 139     //@}
 140
 141     //@{
 142     /**
 143         Enables or disables an individual button in the radiobox.
 144
 145         @param enable
 146         @true to enable, @false to disable.
 147
 148         @param n
 149         The zero-based button to enable or disable.
 150
 151         @sa wxWindow::Enable
 152     */
 153     virtual bool Enable(bool enable = @true);
 154     virtual bool Enable(unsigned int n, bool enable = @true);
 155     //@}
 156
 157     /**
 158         Finds a button matching the given string, returning the position if found, or
 159         -1 if not found.
 160
 161         @param string
 162         The string to find.
 163     */
 164     int FindString(const wxString& string);
 165
 166     /**
 167         Returns the number of columns in the radiobox.
 168     */
 169     unsigned int GetColumnCount();
 170
 171     /**
 172         Returns a radio box item under the point, a zero-based item index, or @c
 173         wxNOT_FOUND if no item is under the point.
 174
 175         @param pt
 176         Point in client coordinates.
 177     */
 178     int GetItemFromPoint(const wxPoint pt);
 179
 180     /**
 181         Returns the helptext associated with the specified @e item if any or @c
 182         wxEmptyString.
 183
 184         @param item
 185         The zero-based item index.
 186
 187         @sa SetItemHelpText()
 188     */
 189     wxString GetItemHelpText(unsigned int item);
 190
 191     /**
 192         Returns the tooltip associated with the specified @e item if any or @NULL.
 193
 194         @sa SetItemToolTip(), wxWindow::GetToolTip
 195     */
 196     wxToolTip * GetItemToolTip(unsigned int item);
 197
 198     /**
 199         Returns the radiobox label.
 200
 201         @param n
 202         The zero-based button index.
 203
 204         @sa SetLabel()
 205     */
 206     wxString GetLabel();
 207
 208     /**
 209         Returns the number of rows in the radiobox.
 210     */
 211     unsigned int GetRowCount();
 212
 213     /**
 214         Returns the zero-based position of the selected button.
 215     */
 216     int GetSelection();
 217
 218     /**
 219         Returns the label for the button at the given position.
 220
 221         @param n
 222         The zero-based button position.
 223     */
 224     wxString GetString(unsigned int n);
 225
 226     /**
 227         Returns the selected string.
 228     */
 229     wxString GetStringSelection();
 230
 231     /**
 232         Returns @true if the item is enabled or @false if it was disabled using
 233         @ref enable() "Enable(n, @false)".
 234
 235         @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
 236         and always returns @true in the other ports.
 237
 238         @param n
 239         The zero-based button position.
 240     */
 241     bool IsItemEnabled(unsigned int n);
 242
 243     /**
 244         Returns @true if the item is currently shown or @false if it was hidden
 245         using
 246         @ref show() "Show(n, @false)".
 247
 248         Note that this function returns @true for an item which hadn't been hidden
 249         even
 250         if the entire radiobox is not currently shown.
 251
 252         @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
 253         and always returns @true in the other ports.
 254
 255         @param n
 256         The zero-based button position.
 257     */
 258     bool IsItemShown(unsigned int n);
 259
 260     /**
 261         Sets the helptext for an item. Empty string erases any existing helptext.
 262
 263         @param item
 264         The zero-based item index.
 265
 266         @param helptext
 267         The help text to set for the item.
 268
 269         @sa GetItemHelpText()
 270     */
 271     void SetItemHelpText(unsigned int item, const wxString& helptext);
 272
 273     /**
 274         Sets the tooltip text for the specified item in the radio group.
 275
 276         @b Platform note: Currently only implemented in wxMSW and wxGTK2 and does
 277         nothing in the other ports.
 278
 279         @param item
 280         Index of the item the tooltip will be shown for.
 281
 282         @param text
 283         Tooltip text for the item, the tooltip is removed if empty.
 284
 285         @sa GetItemToolTip(), wxWindow::SetToolTip
 286     */
 287     void SetItemToolTip(unsigned int item, const wxString& text);
 288
 289     /**
 290         Sets the radiobox label.
 291
 292         @param label
 293         The label to set.
 294
 295         @param n
 296         The zero-based button index.
 297     */
 298     void SetLabel(const wxString& label);
 299
 300     /**
 301         Sets a button by passing the desired string position. This does not cause
 302         a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
 303
 304         @param n
 305         The zero-based button position.
 306     */
 307     void SetSelection(int n);
 308
 309     /**
 310         Sets the selection to a button by passing the desired string. This does not
 311         cause
 312         a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
 313
 314         @param string
 315         The label of the button to select.
 316     */
 317     void SetStringSelection(const wxString& string);
 318 };