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