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{wxCommandEvent}
  29     @event{EVT_RADIOBOX(id, func)}
  30            Process a @c 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_eventhandling, wxRadioButton, wxCheckBox
  39 */
  40 class wxRadioBox : public wxControl, wxItemContainerImmutable
  41 {
  42 public:
  43
  44     /**
  45         Default constructor.
  46
  47         @see Create(), wxValidator
  48     */
  49     wxRadioBox();
  50
  51     /**
  52         Constructor, creating and showing a radiobox.
  53
  54         @param parent
  55             Parent window. Must not be @NULL.
  56         @param id
  57             Window identifier. The value @c wxID_ANY indicates a default value.
  58         @param label
  59             Label for the static box surrounding the radio buttons.
  60         @param pos
  61             Window position. If @c wxDefaultPosition is specified then a
  62             default position is chosen.
  63         @param size
  64             Window size. If @c wxDefaultSize is specified then a default size
  65             is chosen.
  66         @param n
  67             Number of choices with which to initialize the radiobox.
  68         @param choices
  69             An array of choices with which to initialize the radiobox.
  70         @param majorDimension
  71             Specifies the maximum number of rows (if style contains
  72             @c wxRA_SPECIFY_ROWS) or columns (if style contains
  73             @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox.
  74         @param style
  75             Window style. See wxRadioBox.
  76         @param validator
  77             Window validator.
  78         @param name
  79             Window name.
  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 = "radioBox");
  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 @c wxDefaultPosition is specified then a
 105             default position is chosen.
 106         @param size
 107             Window size. If @c 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.
 115         @param style
 116             Window style. See wxRadioBox.
 117         @param validator
 118             Window validator.
 119         @param name
 120             Window name.
 121
 122         @see Create(), wxValidator
 123     */
 124     wxRadioBox(wxWindow* parent, wxWindowID id,
 125                const wxString& label,
 126                const wxPoint& pos,
 127                const wxSize& size,
 128                const wxArrayString& choices,
 129                int majorDimension = 0,
 130                long style = wxRA_SPECIFY_COLS,
 131                const wxValidator& validator = wxDefaultValidator,
 132                const wxString& name = "radioBox");
 133
 134     /**
 135         Destructor, destroying the radiobox item.
 136     */
 137     ~wxRadioBox();
 138
 139     /**
 140         Creates the radiobox for two-step construction. See wxRadioBox()
 141         for further details.
 142     */
 143     bool Create(wxWindow* parent, wxWindowID id,
 144                 const wxString& label,
 145                 const wxPoint& pos = wxDefaultPosition,
 146                 const wxSize& size = wxDefaultSize,
 147                 int n = 0,
 148                 const wxString choices[] = NULL,
 149                 int majorDimension = 0,
 150                 long style = wxRA_SPECIFY_COLS,
 151                 const wxValidator& validator = wxDefaultValidator,
 152                 const wxString& name = "radioBox");
 153
 154     /**
 155         Creates the radiobox for two-step construction. See wxRadioBox()
 156         for further details.
 157     */
 158     bool Create(wxWindow* parent, wxWindowID id,
 159                 const wxString& label,
 160                 const wxPoint& pos,
 161                 const wxSize& size,
 162                 const wxArrayString& choices,
 163                 int majorDimension = 0,
 164                 long style = wxRA_SPECIFY_COLS,
 165                 const wxValidator& validator = wxDefaultValidator,
 166                 const wxString& name = "radioBox");
 167
 168     /**
 169         Enables or disables an individual button in the radiobox.
 170
 171         @param enable
 172             @true to enable, @false to disable.
 173         @param n
 174             The zero-based button to enable or disable.
 175
 176         @see wxWindow::Enable()
 177
 178         @beginWxPythonOnly
 179         In place of a single overloaded method name, wxPython implements the following methods:
 180
 181         @beginTable
 182         @row2col{Enable(flag), Enables or disables the entire radiobox.}
 183         @row2col{EnableItem(n\, flag), Enables or disables an individual button in the radiobox.}
 184         @endTable
 185
 186         @endWxPythonOnly
 187     */
 188     virtual bool Enable(unsigned int n, bool enable = true);
 189
 190
 191     /**
 192         Finds a button matching the given string, returning the position if found, or
 193         -1 if not found.
 194
 195         @param string
 196             The string to find.
 197     */
 198     int FindString(const wxString& string) 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     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     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     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, const bool show = true);
 318 };