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, wxRadioButton, wxCheckBox
  40 */
  41 class wxRadioBox : public wxControlWithItems
  42 {
  43 public:
  44     //@{
  45     /**
  46         Constructor, creating and showing a radiobox.
  47
  48         @param parent
  49             Parent window. Must not be @NULL.
  50         @param id
  51             Window identifier. The value wxID_ANY indicates a default value.
  52         @param label
  53             Label for the static box surrounding the radio buttons.
  54         @param pos
  55             Window position. If wxDefaultPosition is specified then a default
  56         position is chosen.
  57         @param size
  58             Window size. If wxDefaultSize is specified then a default size
  59         is chosen.
  60         @param n
  61             Number of choices with which to initialize the radiobox.
  62         @param choices
  63             An array of choices with which to initialize the radiobox.
  64         @param majorDimension
  65             Specifies the maximum number of rows (if style contains wxRA_SPECIFY_ROWS)
  66         or columns (if style contains wxRA_SPECIFY_COLS) for a two-dimensional
  67             radiobox.
  68         @param style
  69             Window style. See wxRadioBox.
  70         @param validator
  71             Window validator.
  72         @param name
  73             Window name.
  74
  75         @see Create(), wxValidator
  76     */
  77     wxRadioBox();
  78     wxRadioBox(wxWindow* parent, wxWindowID id,
  79                const wxString& label,
  80                const wxPoint& point = wxDefaultPosition,
  81                const wxSize& size = wxDefaultSize,
  82                int n = 0,
  83                const wxString choices[] = NULL,
  84                int majorDimension = 0,
  85                long style = wxRA_SPECIFY_COLS,
  86                const wxValidator& validator = wxDefaultValidator,
  87                const wxString& name = "radioBox");
  88     wxRadioBox(wxWindow* parent, wxWindowID id,
  89                const wxString& label,
  90                const wxPoint& point,
  91                const wxSize& size,
  92                const wxArrayString& choices,
  93                int majorDimension = 0,
  94                long style = wxRA_SPECIFY_COLS,
  95                const wxValidator& validator = wxDefaultValidator,
  96                const wxString& name = "radioBox");
  97     //@}
  98
  99     /**
 100         Destructor, destroying the radiobox item.
 101     */
 102     ~wxRadioBox();
 103
 104     //@{
 105     /**
 106         Creates the radiobox for two-step construction. See wxRadioBox()
 107         for further details.
 108     */
 109     bool Create(wxWindow* parent, wxWindowID id,
 110                 const wxString& label,
 111                 const wxPoint& point = wxDefaultPosition,
 112                 const wxSize& size = wxDefaultSize,
 113                 int n = 0,
 114                 const wxString choices[] = NULL,
 115                 int majorDimension = 0,
 116                 long style = wxRA_SPECIFY_COLS,
 117                 const wxValidator& validator = wxDefaultValidator,
 118                 const wxString& name = "radioBox");
 119     bool Create(wxWindow* parent, wxWindowID id,
 120                 const wxString& label,
 121                 const wxPoint& point,
 122                 const wxSize& size,
 123                 const wxArrayString& choices,
 124                 int majorDimension = 0,
 125                 long style = wxRA_SPECIFY_COLS,
 126                 const wxValidator& validator = wxDefaultValidator,
 127                 const wxString& name = "radioBox");
 128     //@}
 129
 130     //@{
 131     /**
 132         Enables or disables an individual button in the radiobox.
 133
 134         @param enable
 135             @true to enable, @false to disable.
 136         @param n
 137             The zero-based button to enable or disable.
 138
 139         @see wxWindow::Enable
 140     */
 141     virtual bool Enable(bool enable = true);
 142     virtual bool Enable(unsigned int n, bool enable = true);
 143     //@}
 144
 145     /**
 146         Finds a button matching the given string, returning the position if found, or
 147         -1 if not found.
 148
 149         @param string
 150             The string to find.
 151     */
 152     int FindString(const wxString& string);
 153
 154     /**
 155         Returns the number of columns in the radiobox.
 156     */
 157     unsigned int GetColumnCount();
 158
 159     /**
 160         Returns a radio box item under the point, a zero-based item index, or @c
 161         wxNOT_FOUND if no item is under the point.
 162
 163         @param pt
 164             Point in client coordinates.
 165     */
 166     int GetItemFromPoint(const wxPoint pt);
 167
 168     /**
 169         Returns the helptext associated with the specified @a item if any or @c
 170         wxEmptyString.
 171
 172         @param item
 173             The zero-based item index.
 174
 175         @see SetItemHelpText()
 176     */
 177     wxString GetItemHelpText(unsigned int item);
 178
 179     /**
 180         Returns the tooltip associated with the specified @a item if any or @NULL.
 181
 182         @see SetItemToolTip(), wxWindow::GetToolTip
 183     */
 184     wxToolTip* GetItemToolTip(unsigned int item);
 185
 186     /**
 187         Returns the radiobox label.
 188
 189         @param n
 190             The zero-based button index.
 191
 192         @see SetLabel()
 193     */
 194     wxString GetLabel();
 195
 196     /**
 197         Returns the number of rows in the radiobox.
 198     */
 199     unsigned int GetRowCount();
 200
 201     /**
 202         Returns the zero-based position of the selected button.
 203     */
 204     int GetSelection();
 205
 206     /**
 207         Returns the label for the button at the given position.
 208
 209         @param n
 210             The zero-based button position.
 211     */
 212     wxString GetString(unsigned int n);
 213
 214     /**
 215         Returns the selected string.
 216     */
 217     wxString GetStringSelection();
 218
 219     /**
 220         Returns @true if the item is enabled or @false if it was disabled using
 221         @ref enable() "Enable(n, @false)".
 222         @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
 223         and always returns @true in the other ports.
 224
 225         @param n
 226             The zero-based button position.
 227     */
 228     bool IsItemEnabled(unsigned int n);
 229
 230     /**
 231         Returns @true if the item is currently shown or @false if it was hidden
 232         using
 233         @ref show() "Show(n, @false)".
 234         Note that this function returns @true for an item which hadn't been hidden
 235         even
 236         if the entire radiobox is not currently shown.
 237         @b Platform note: Currently only implemented in wxMSW, wxGTK and wxUniversal
 238         and always returns @true in the other ports.
 239
 240         @param n
 241             The zero-based button position.
 242     */
 243     bool IsItemShown(unsigned int n);
 244
 245     /**
 246         Sets the helptext for an item. Empty string erases any existing helptext.
 247
 248         @param item
 249             The zero-based item index.
 250         @param helptext
 251             The help text to set for the item.
 252
 253         @see GetItemHelpText()
 254     */
 255     void SetItemHelpText(unsigned int item, const wxString& helptext);
 256
 257     /**
 258         Sets the tooltip text for the specified item in the radio group.
 259         @b Platform note: Currently only implemented in wxMSW and wxGTK2 and does
 260         nothing in the other ports.
 261
 262         @param item
 263             Index of the item the tooltip will be shown for.
 264         @param text
 265             Tooltip text for the item, the tooltip is removed if empty.
 266
 267         @see GetItemToolTip(), wxWindow::SetToolTip
 268     */
 269     void SetItemToolTip(unsigned int item, const wxString& text);
 270
 271     /**
 272         Sets the radiobox label.
 273
 274         @param label
 275             The label to set.
 276         @param n
 277             The zero-based button index.
 278     */
 279     void SetLabel(const wxString& label);
 280
 281     /**
 282         Sets a button by passing the desired string position. This does not cause
 283         a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
 284
 285         @param n
 286             The zero-based button position.
 287     */
 288     void SetSelection(int n);
 289
 290     /**
 291         Sets the selection to a button by passing the desired string. This does not
 292         cause
 293         a wxEVT_COMMAND_RADIOBOX_SELECTED event to get emitted.
 294
 295         @param string
 296             The label of the button to select.
 297     */
 298     void SetStringSelection(const wxString& string);
 299 };