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 license
   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 @c wxDefaultPosition is specified then a
  61             default position is chosen.
  62         @param size
  63             Window size. If @c 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.
  73         @param style
  74             Window style. See wxRadioBox.
  75         @param validator
  76             Window validator.
  77         @param name
  78             Window name.
  79
  80         @see Create(), wxValidator
  81     */
  82     wxRadioBox(wxWindow* parent, wxWindowID id,
  83                const wxString& label,
  84                const wxPoint& pos = wxDefaultPosition,
  85                const wxSize& size = wxDefaultSize,
  86                int n = 0,
  87                const wxString choices[] = NULL,
  88                int majorDimension = 1,
  89                long style = wxRA_SPECIFY_COLS,
  90                const wxValidator& validator = wxDefaultValidator,
  91                const wxString& name = wxRadioBoxNameStr);
  92
  93     /**
  94         Constructor, creating and showing a radiobox.
  95
  96         @param parent
  97             Parent window. Must not be @NULL.
  98         @param id
  99             Window identifier. The value @c wxID_ANY indicates a default value.
 100         @param label
 101             Label for the static box surrounding the radio buttons.
 102         @param pos
 103             Window position. If @c wxDefaultPosition is specified then a
 104             default position is chosen.
 105         @param size
 106             Window size. If @c wxDefaultSize is specified then a default size
 107             is chosen.
 108         @param choices
 109             An array of choices with which to initialize the radiobox.
 110         @param majorDimension
 111             Specifies the maximum number of rows (if style contains
 112             @c wxRA_SPECIFY_ROWS) or columns (if style contains
 113             @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox.
 114         @param style
 115             Window style. See wxRadioBox.
 116         @param validator
 117             Window validator.
 118         @param name
 119             Window name.
 120
 121         @see Create(), wxValidator
 122     */
 123     wxRadioBox(wxWindow* parent, wxWindowID id,
 124                const wxString& label,
 125                const wxPoint& pos,
 126                const wxSize& size,
 127                const wxArrayString& choices,
 128                int majorDimension = 1,
 129                long style = wxRA_SPECIFY_COLS,
 130                const wxValidator& validator = wxDefaultValidator,
 131                const wxString& name = wxRadioBoxNameStr);
 132
 133     /**
 134         Destructor, destroying the radiobox item.
 135     */
 136     virtual ~wxRadioBox();
 137
 138     /**
 139         Creates the radiobox for two-step construction. See wxRadioBox()
 140         for further details.
 141     */
 142     bool Create(wxWindow* parent, wxWindowID id,
 143                 const wxString& label,
 144                 const wxPoint& pos = wxDefaultPosition,
 145                 const wxSize& size = wxDefaultSize,
 146                 int n = 0,
 147                 const wxString choices[] = NULL,
 148                 int majorDimension = 0,
 149                 long style = wxRA_SPECIFY_COLS,
 150                 const wxValidator& validator = wxDefaultValidator,
 151                 const wxString& name = wxRadioBoxNameStr);
 152
 153     /**
 154         Creates the radiobox for two-step construction. See wxRadioBox()
 155         for further details.
 156     */
 157     bool Create(wxWindow* parent, wxWindowID id,
 158                 const wxString& label,
 159                 const wxPoint& pos,
 160                 const wxSize& size,
 161                 const wxArrayString& choices,
 162                 int majorDimension = 0,
 163                 long style = wxRA_SPECIFY_COLS,
 164                 const wxValidator& validator = wxDefaultValidator,
 165                 const wxString& name = wxRadioBoxNameStr);
 166
 167     /**
 168         Enables or disables an individual button in the radiobox.
 169
 170         @param enable
 171             @true to enable, @false to disable.
 172         @param n
 173             The zero-based button to enable or disable.
 174
 175         @see wxWindow::Enable()
 176
 177         @beginWxPythonOnly
 178         In place of a single overloaded method name, wxPython implements the following methods:
 179
 180         @beginTable
 181         @row2col{Enable(flag), Enables or disables the entire radiobox.}
 182         @row2col{EnableItem(n\, flag), Enables or disables an individual button in the radiobox.}
 183         @endTable
 184
 185         @endWxPythonOnly
 186     */
 187     virtual bool Enable(unsigned int n, bool enable = true);
 188
 189     /**
 190         Finds a button matching the given string, returning the position if found,
 191         or @c wxNOT_FOUND if not found.
 192
 193         @param string
 194             The string to find.
 195         @param bCase
 196             Should the search be case-sensitive?
 197     */
 198     virtual int FindString(const wxString& string, bool bCase = false) const;
 199
 200     /**
 201         Returns the number of columns in the radiobox.
 202     */
 203     unsigned int GetColumnCount() const;
 204
 205     /**
 206         Returns a radio box item under the point, a zero-based item index, or @c
 207         wxNOT_FOUND if no item is under the point.
 208
 209         @param pt
 210             Point in client coordinates.
 211     */
 212     virtual int GetItemFromPoint(const wxPoint& pt) const;
 213
 214     /**
 215         Returns the helptext associated with the specified @a item if any or @c
 216         wxEmptyString.
 217
 218         @param item
 219             The zero-based item index.
 220
 221         @see SetItemHelpText()
 222     */
 223     wxString GetItemHelpText(unsigned int item) const;
 224
 225     /**
 226         Returns the tooltip associated with the specified @a item if any or @NULL.
 227
 228         @see SetItemToolTip(), wxWindow::GetToolTip()
 229     */
 230     wxToolTip* GetItemToolTip(unsigned int item) const;
 231
 232     /**
 233         Returns the number of rows in the radiobox.
 234     */
 235     unsigned int GetRowCount() const;
 236
 237     /**
 238         Returns @true if the item is enabled or @false if it was disabled using
 239         @ref Enable(unsigned int,bool) "Enable(n, false)".
 240
 241         This function is currently only implemented in wxMSW, wxGTK and
 242         wxUniversal and always returns @true in the other ports.
 243
 244         @param n
 245             The zero-based button position.
 246     */
 247     virtual bool IsItemEnabled(unsigned int n) const;
 248
 249     /**
 250         Returns @true if the item is currently shown or @false if it was hidden
 251         using @ref Show(unsigned int,bool) "Show(n, false)".
 252
 253         Note that this function returns @true for an item which hadn't been hidden
 254         even if the entire radiobox is not currently shown.
 255
 256         This function is currently only implemented in wxMSW, wxGTK and
 257         wxUniversal and always returns @true in the other ports.
 258
 259         @param n
 260             The zero-based button position.
 261     */
 262     virtual bool IsItemShown(unsigned int n) const;
 263
 264     /**
 265         Sets the helptext for an item. Empty string erases any existing helptext.
 266
 267         @param item
 268             The zero-based item index.
 269         @param helptext
 270             The help text to set for the item.
 271
 272         @see GetItemHelpText()
 273     */
 274     void SetItemHelpText(unsigned int item, const wxString& helptext);
 275
 276     /**
 277         Sets the tooltip text for the specified item in the radio group.
 278
 279         This function is currently only implemented in wxMSW and wxGTK2 and
 280         does nothing in the other ports.
 281
 282         @param item
 283             Index of the item the tooltip will be shown for.
 284         @param text
 285             Tooltip text for the item, the tooltip is removed if empty.
 286
 287         @see GetItemToolTip(), wxWindow::SetToolTip()
 288     */
 289     void SetItemToolTip(unsigned int item, const wxString& text);
 290
 291     /**
 292         Shows or hides individual buttons.
 293
 294         @param show
 295             @true to show, @false to hide.
 296         @param item
 297             The zero-based position of the button to show or hide.
 298
 299         @return
 300             @true if the item has been shown or hidden or @false if nothing
 301             was done because it already was in the requested state.
 302
 303         @see
 304             wxWindow::Show()
 305
 306         @beginWxPythonOnly
 307         In place of a single overloaded method name, wxPython implements the following methods:
 308
 309         @beginTable
 310         @row2col{Show(flag), Shows or hides the entire radiobox.}
 311         @row2col{ShowItem(n\, flag), Shows or hides individual buttons.}
 312         @endTable
 313
 314         @endWxPythonOnly
 315
 316     */
 317     virtual bool Show(unsigned int item, bool show = true);
 318 };