interface/wx/radiobox.h

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