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     @beginEventTable{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_eventhandling, 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 = 0,
  89                long style = wxRA_SPECIFY_COLS,
  90                const wxValidator& validator = wxDefaultValidator,
  91                const wxString& name = "radioBox");
  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 = 0,
 129                long style = wxRA_SPECIFY_COLS,
 130                const wxValidator& validator = wxDefaultValidator,
 131                const wxString& name = "radioBox");
 132
 133     /**
 134         Destructor, destroying the radiobox item.
 135     */
 136     ~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 = "radioBox");
 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 = "radioBox");
 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     /**
 191         Finds a button matching the given string, returning the position if found, or
 192         -1 if not found.
 193
 194         @param string
 195             The string to find.
 196     */
 197     int FindString(const wxString& string) const;
 198
 199     /**
 200         Returns the number of columns in the radiobox.
 201     */
 202     unsigned int GetColumnCount() const;
 203
 204     /**
 205         Returns a radio box item under the point, a zero-based item index, or @c
 206         wxNOT_FOUND if no item is under the point.
 207
 208         @param pt
 209             Point in client coordinates.
 210     */
 211     int GetItemFromPoint(const wxPoint pt) const;
 212
 213     /**
 214         Returns the helptext associated with the specified @a item if any or @c
 215         wxEmptyString.
 216
 217         @param item
 218             The zero-based item index.
 219
 220         @see SetItemHelpText()
 221     */
 222     wxString GetItemHelpText(unsigned int item) const;
 223
 224     /**
 225         Returns the tooltip associated with the specified @a item if any or @NULL.
 226
 227         @see SetItemToolTip(), wxWindow::GetToolTip()
 228     */
 229     wxToolTip* GetItemToolTip(unsigned int item) const;
 230
 231     /**
 232         Returns the number of rows in the radiobox.
 233     */
 234     unsigned int GetRowCount() const;
 235
 236     /**
 237         Returns @true if the item is enabled or @false if it was disabled using
 238         @ref Enable(unsigned int,bool) "Enable(n, false)".
 239
 240         This function is currently only implemented in wxMSW, wxGTK and
 241         wxUniversal and always returns @true in the other ports.
 242
 243         @param n
 244             The zero-based button position.
 245     */
 246     bool IsItemEnabled(unsigned int n) const;
 247
 248     /**
 249         Returns @true if the item is currently shown or @false if it was hidden
 250         using @ref Show(unsigned int,bool) "Show(n, false)".
 251
 252         Note that this function returns @true for an item which hadn't been hidden
 253         even if the entire radiobox is not currently shown.
 254
 255         This function is currently only implemented in wxMSW, wxGTK and
 256         wxUniversal and always returns @true in the other ports.
 257
 258         @param n
 259             The zero-based button position.
 260     */
 261     bool IsItemShown(unsigned int n) const;
 262
 263     /**
 264         Sets the helptext for an item. Empty string erases any existing helptext.
 265
 266         @param item
 267             The zero-based item index.
 268         @param helptext
 269             The help text to set for the item.
 270
 271         @see GetItemHelpText()
 272     */
 273     void SetItemHelpText(unsigned int item, const wxString& helptext);
 274
 275     /**
 276         Sets the tooltip text for the specified item in the radio group.
 277
 278         This function is currently only implemented in wxMSW and wxGTK2 and
 279         does nothing in the other ports.
 280
 281         @param item
 282             Index of the item the tooltip will be shown for.
 283         @param text
 284             Tooltip text for the item, the tooltip is removed if empty.
 285
 286         @see GetItemToolTip(), wxWindow::SetToolTip()
 287     */
 288     void SetItemToolTip(unsigned int item, const wxString& text);
 289
 290     /**
 291         Shows or hides individual buttons.
 292
 293         @param show
 294             @true to show, @false to hide.
 295         @param item
 296             The zero-based position of the button to show or hide.
 297
 298         @return
 299             @true if the item has been shown or hidden or @false if nothing
 300             was done because it already was in the requested state.
 301
 302         @see
 303             wxWindow::Show()
 304
 305         @beginWxPythonOnly
 306         In place of a single overloaded method name, wxPython implements the following methods:
 307
 308         @beginTable
 309         @row2col{Show(flag), Shows or hides the entire radiobox.}
 310         @row2col{ShowItem(n\, flag), Shows or hides individual buttons.}
 311         @endTable
 312
 313         @endWxPythonOnly
 314
 315     */
 316     virtual bool Show(unsigned int item, const bool show = true);
 317 };