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     @endStyleTable
  23
  24     @beginEventEmissionTable{wxCommandEvent}
  25     @event{EVT_RADIOBOX(id, func)}
  26            Process a @c wxEVT_RADIOBOX event, when a radiobutton
  27            is clicked.
  28     @endEventTable
  29
  30     @library{wxcore}
  31     @category{ctrl}
  32     @appearance{radiobox}
  33
  34     @see @ref overview_events, wxRadioButton, wxCheckBox
  35 */
  36 class wxRadioBox : public wxControl, wxItemContainerImmutable
  37 {
  38 public:
  39
  40     /**
  41         Default constructor.
  42
  43         @see Create(), wxValidator
  44     */
  45     wxRadioBox();
  46
  47     /**
  48         Constructor, creating and showing a radiobox.
  49
  50         @param parent
  51             Parent window. Must not be @NULL.
  52         @param id
  53             Window identifier. The value @c wxID_ANY indicates a default value.
  54         @param label
  55             Label for the static box surrounding the radio buttons.
  56         @param pos
  57             Window position. If ::wxDefaultPosition is specified then a
  58             default position is chosen.
  59         @param size
  60             Window size. If ::wxDefaultSize is specified then a default size
  61             is chosen.
  62         @param n
  63             Number of choices with which to initialize the radiobox.
  64         @param choices
  65             An array of choices with which to initialize the radiobox.
  66         @param majorDimension
  67             Specifies the maximum number of rows (if style contains
  68             @c wxRA_SPECIFY_ROWS) or columns (if style contains
  69             @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. The default
  70             value of 0 means to use the number of items, i.e. @a n.
  71         @param style
  72             Window style. See wxRadioBox.
  73         @param validator
  74             Window validator.
  75         @param name
  76             Window name.
  77
  78         @beginWxPerlOnly
  79         Not supported by wxPerl.
  80         @endWxPerlOnly
  81
  82         @see Create(), wxValidator
  83     */
  84     wxRadioBox(wxWindow* parent, wxWindowID id,
  85                const wxString& label,
  86                const wxPoint& pos = wxDefaultPosition,
  87                const wxSize& size = wxDefaultSize,
  88                int n = 0,
  89                const wxString choices[] = NULL,
  90                int majorDimension = 0,
  91                long style = wxRA_SPECIFY_COLS,
  92                const wxValidator& validator = wxDefaultValidator,
  93                const wxString& name = wxRadioBoxNameStr);
  94
  95     /**
  96         Constructor, creating and showing a radiobox.
  97
  98         @param parent
  99             Parent window. Must not be @NULL.
 100         @param id
 101             Window identifier. The value @c wxID_ANY indicates a default value.
 102         @param label
 103             Label for the static box surrounding the radio buttons.
 104         @param pos
 105             Window position. If ::wxDefaultPosition is specified then a
 106             default position is chosen.
 107         @param size
 108             Window size. If ::wxDefaultSize is specified then a default size
 109             is chosen.
 110         @param choices
 111             An array of choices with which to initialize the radiobox.
 112         @param majorDimension
 113             Specifies the maximum number of rows (if style contains
 114             @c wxRA_SPECIFY_ROWS) or columns (if style contains
 115             @c wxRA_SPECIFY_COLS) for a two-dimensional radiobox. The default
 116             value of 0 means to use the number of items, i.e. number of
 117             elements in @a choices.
 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 = 0,
 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     */
 186     virtual bool Enable(unsigned int n, bool enable = true);
 187
 188     /**
 189         Finds a button matching the given string, returning the position if found,
 190         or @c wxNOT_FOUND if not found.
 191
 192         @param string
 193             The string to find.
 194         @param bCase
 195             Should the search be case-sensitive?
 196     */
 197     virtual int FindString(const wxString& string, bool bCase = false) 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     virtual 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     virtual 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     virtual 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         Sets the selection to the given item.
 292
 293         Notice that a radio box always has selection, so @a n must be valid
 294         here and passing @c wxNOT_FOUND is not allowed.
 295      */
 296     virtual void SetSelection(int n);
 297
 298     /**
 299         Shows or hides individual buttons.
 300
 301         @param show
 302             @true to show, @false to hide.
 303         @param item
 304             The zero-based position of the button to show or hide.
 305
 306         @return
 307             @true if the item has been shown or hidden or @false if nothing
 308             was done because it already was in the requested state.
 309
 310         @see
 311             wxWindow::Show()
 312
 313     */
 314     virtual bool Show(unsigned int item, bool show = true);
 315
 316
 317     // pure virtuals that have implementations here
 318     virtual unsigned int GetCount() const;
 319     virtual wxString GetString(unsigned int n) const;
 320     virtual void SetString(unsigned int n, const wxString& string);
 321     virtual int GetSelection() const;
 322
 323 };