interface/wx/radiobox.h

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