interface/radiobox.h

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