]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/radiobox.h
Moved wxPGChoices m_choices member from various property classes to base wxPGProperty...
[wxWidgets.git] / interface / wx / radiobox.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: radiobox.h
e54c96f1 3// Purpose: interface of wxRadioBox
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxRadioBox
7c913512 11
23324ae1
FM
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.
7c913512 15
23324ae1 16 @beginStyleTable
8c6791e4 17 @style{wxRA_SPECIFY_ROWS}
23324ae1 18 The major dimension parameter refers to the maximum number of rows.
8c6791e4 19 @style{wxRA_SPECIFY_COLS}
23324ae1
FM
20 The major dimension parameter refers to the maximum number of
21 columns.
8c6791e4 22 @style{wxRA_USE_CHECKBOX}
23324ae1
FM
23 Use of the checkbox controls instead of radio buttons (currently
24 supported only on PalmOS)
25 @endStyleTable
7c913512 26
1f1d2182 27 @beginEventTable{wxCommandEvent}
8c6791e4 28 @event{EVT_RADIOBOX(id, func)}
3ed3a1c8 29 Process a @c wxEVT_COMMAND_RADIOBOX_SELECTED event, when a radiobutton
23324ae1
FM
30 is clicked.
31 @endEventTable
7c913512 32
23324ae1
FM
33 @library{wxcore}
34 @category{ctrl}
0c7fe6f2 35 <!-- @appearance{radiobox.png} -->
7c913512 36
1f1d2182 37 @see @ref overview_eventhandling, wxRadioButton, wxCheckBox
23324ae1 38*/
bf84f3e2 39class wxRadioBox : public wxControl, wxItemContainerImmutable
23324ae1
FM
40{
41public:
3ed3a1c8
BP
42
43 /**
44 Default constructor.
45
46 @see Create(), wxValidator
47 */
48 wxRadioBox();
49
23324ae1
FM
50 /**
51 Constructor, creating and showing a radiobox.
3c4f71cc 52
7c913512 53 @param parent
4cc4bfaf 54 Parent window. Must not be @NULL.
7c913512 55 @param id
3ed3a1c8 56 Window identifier. The value @c wxID_ANY indicates a default value.
7c913512 57 @param label
4cc4bfaf 58 Label for the static box surrounding the radio buttons.
7c913512 59 @param pos
3ed3a1c8
BP
60 Window position. If @c wxDefaultPosition is specified then a
61 default position is chosen.
7c913512 62 @param size
3ed3a1c8
BP
63 Window size. If @c wxDefaultSize is specified then a default size
64 is chosen.
7c913512 65 @param n
4cc4bfaf 66 Number of choices with which to initialize the radiobox.
7c913512 67 @param choices
4cc4bfaf 68 An array of choices with which to initialize the radiobox.
7c913512 69 @param majorDimension
3ed3a1c8
BP
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.
7c913512 73 @param style
4cc4bfaf 74 Window style. See wxRadioBox.
7c913512 75 @param validator
4cc4bfaf 76 Window validator.
7c913512 77 @param name
4cc4bfaf 78 Window name.
3c4f71cc 79
4cc4bfaf 80 @see Create(), wxValidator
23324ae1 81 */
7c913512
FM
82 wxRadioBox(wxWindow* parent, wxWindowID id,
83 const wxString& label,
3ed3a1c8 84 const wxPoint& pos = wxDefaultPosition,
7c913512
FM
85 const wxSize& size = wxDefaultSize,
86 int n = 0,
4cc4bfaf 87 const wxString choices[] = NULL,
7c913512
FM
88 int majorDimension = 0,
89 long style = wxRA_SPECIFY_COLS,
90 const wxValidator& validator = wxDefaultValidator,
91 const wxString& name = "radioBox");
3ed3a1c8
BP
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 */
7c913512
FM
123 wxRadioBox(wxWindow* parent, wxWindowID id,
124 const wxString& label,
3ed3a1c8 125 const wxPoint& pos,
7c913512
FM
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");
23324ae1
FM
132
133 /**
134 Destructor, destroying the radiobox item.
135 */
136 ~wxRadioBox();
137
23324ae1
FM
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,
3ed3a1c8 144 const wxPoint& pos = wxDefaultPosition,
23324ae1
FM
145 const wxSize& size = wxDefaultSize,
146 int n = 0,
4cc4bfaf 147 const wxString choices[] = NULL,
23324ae1
FM
148 int majorDimension = 0,
149 long style = wxRA_SPECIFY_COLS,
150 const wxValidator& validator = wxDefaultValidator,
151 const wxString& name = "radioBox");
3ed3a1c8
BP
152
153 /**
154 Creates the radiobox for two-step construction. See wxRadioBox()
155 for further details.
156 */
7c913512
FM
157 bool Create(wxWindow* parent, wxWindowID id,
158 const wxString& label,
3ed3a1c8 159 const wxPoint& pos,
7c913512
FM
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");
23324ae1 166
23324ae1
FM
167 /**
168 Enables or disables an individual button in the radiobox.
3c4f71cc 169
7c913512 170 @param enable
4cc4bfaf 171 @true to enable, @false to disable.
7c913512 172 @param n
4cc4bfaf 173 The zero-based button to enable or disable.
3c4f71cc 174
3ed3a1c8
BP
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
23324ae1 186 */
4cc4bfaf 187 virtual bool Enable(unsigned int n, bool enable = true);
3ed3a1c8 188
23324ae1
FM
189
190 /**
191 Finds a button matching the given string, returning the position if found, or
192 -1 if not found.
3c4f71cc 193
7c913512 194 @param string
4cc4bfaf 195 The string to find.
23324ae1 196 */
328f5751 197 int FindString(const wxString& string) const;
23324ae1
FM
198
199 /**
200 Returns the number of columns in the radiobox.
201 */
328f5751 202 unsigned int GetColumnCount() const;
23324ae1
FM
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.
3c4f71cc 207
7c913512 208 @param pt
4cc4bfaf 209 Point in client coordinates.
23324ae1 210 */
328f5751 211 int GetItemFromPoint(const wxPoint pt) const;
23324ae1
FM
212
213 /**
4cc4bfaf 214 Returns the helptext associated with the specified @a item if any or @c
23324ae1 215 wxEmptyString.
3c4f71cc 216
7c913512 217 @param item
4cc4bfaf 218 The zero-based item index.
3c4f71cc 219
4cc4bfaf 220 @see SetItemHelpText()
23324ae1 221 */
328f5751 222 wxString GetItemHelpText(unsigned int item) const;
23324ae1
FM
223
224 /**
4cc4bfaf 225 Returns the tooltip associated with the specified @a item if any or @NULL.
3c4f71cc 226
3ed3a1c8 227 @see SetItemToolTip(), wxWindow::GetToolTip()
23324ae1 228 */
328f5751 229 wxToolTip* GetItemToolTip(unsigned int item) const;
23324ae1 230
23324ae1
FM
231 /**
232 Returns the number of rows in the radiobox.
233 */
328f5751 234 unsigned int GetRowCount() const;
23324ae1 235
23324ae1
FM
236 /**
237 Returns @true if the item is enabled or @false if it was disabled using
3ed3a1c8
BP
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.
3c4f71cc 242
7c913512 243 @param n
4cc4bfaf 244 The zero-based button position.
23324ae1 245 */
328f5751 246 bool IsItemEnabled(unsigned int n) const;
23324ae1
FM
247
248 /**
249 Returns @true if the item is currently shown or @false if it was hidden
3ed3a1c8
BP
250 using @ref Show(unsigned int,bool) "Show(n, false)".
251
23324ae1 252 Note that this function returns @true for an item which hadn't been hidden
3ed3a1c8
BP
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.
3c4f71cc 257
7c913512 258 @param n
4cc4bfaf 259 The zero-based button position.
23324ae1 260 */
328f5751 261 bool IsItemShown(unsigned int n) const;
23324ae1
FM
262
263 /**
264 Sets the helptext for an item. Empty string erases any existing helptext.
3c4f71cc 265
7c913512 266 @param item
4cc4bfaf 267 The zero-based item index.
7c913512 268 @param helptext
4cc4bfaf 269 The help text to set for the item.
3c4f71cc 270
4cc4bfaf 271 @see GetItemHelpText()
23324ae1
FM
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.
3ed3a1c8
BP
277
278 This function is currently only implemented in wxMSW and wxGTK2 and
279 does nothing in the other ports.
3c4f71cc 280
7c913512 281 @param item
4cc4bfaf 282 Index of the item the tooltip will be shown for.
7c913512 283 @param text
4cc4bfaf 284 Tooltip text for the item, the tooltip is removed if empty.
3c4f71cc 285
3ed3a1c8 286 @see GetItemToolTip(), wxWindow::SetToolTip()
23324ae1
FM
287 */
288 void SetItemToolTip(unsigned int item, const wxString& text);
289
290 /**
3ed3a1c8 291 Shows or hides individual buttons.
3c4f71cc 292
3ed3a1c8
BP
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.
23324ae1 297
3ed3a1c8
BP
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.
3c4f71cc 301
3ed3a1c8
BP
302 @see
303 wxWindow::Show()
23324ae1 304
3ed3a1c8
BP
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
3c4f71cc 314
23324ae1 315 */
3ed3a1c8 316 virtual bool Show(unsigned int item, const bool show = true);
23324ae1 317};