1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/RadioButton.h hrev47274 10 * src/kits/interface/RadioButton.cpp hrev47274 11 */ 12 13 14/*! 15 \file RadioButton.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BRadioButton class definition. 19*/ 20 21 22/*! 23 \class BRadioButton 24 \ingroup interface 25 \ingroup libbe 26 \brief A user interface control used to select between a set of mutually 27 exclusive options. 28 29 \image html BRadioButton_example.png 30 31 Radio buttons, unlike check boxes, are always used as part of a group. 32 Only one radio button in a group can be on at a time, when one is turned 33 on all sibling radio buttons are turned off. When a radio button is on it 34 has a value of 1 (\c B_CONTROL_ON), when it is off it has a value of 0 35 (\c B_CONTROL_OFF). Since all sibling radio buttons are connected to 36 create separate groups of radio buttons each group must be attached to 37 a different parent, for instance a separate BView. 38 39 Each radio button in a group sends its own BMessage, it's up to you to 40 determine what action takes place when each radio button is selected, if 41 any. The message is sent only when a radio button is turned on, not when 42 it is turned off. 43 44 \since BeOS R3 45*/ 46 47 48/*! 49 \fn BRadioButton::BRadioButton(BRect frame, const char* name, 50 const char* label, BMessage* message, uint32 resizingMode, 51 uint32 flags) 52 \brief Construct a radio button in the \a frame rectangle with a \a name, 53 \a label, model \a message, \a resizingMode, and creation \a flags. 54 55 \note This constructor will resize the control to it's minimum height if needed 56 for compatibility with BeOS R5. 57 58 The initial value of the radio button is 0 (\c B_CONTROL_OFF). 59 60 \param frame The \a frame to draw the radio button in. 61 \param name The \a name of the radio button, can be \c NULL. 62 \param label The \a label displayed along with the radio button control, 63 can be \c NULL. 64 \param message The \a message to send when the radio button is activated, 65 can be \c NULL. 66 \param resizingMode Defines the behavior of the radio button as the parent 67 view resizes. See BView for details. 68 \param flags Behavior flags for the radio button. See BView for details. 69 70 \since BeOS R3 71*/ 72 73 74/*! 75 \fn BRadioButton::BRadioButton(const char* name, const char* label, 76 BMessage* message, uint32 flags) 77 \brief Construct a radio button with a \a name, \a label, model \a message, 78 and creation \a flags suitable for use with the Layout API. 79 80 The initial value of the radio button is 0 (\c B_CONTROL_OFF). 81 82 \param name The \a name of the radio button, can be \c NULL. 83 \param label The \a label displayed along with the radio button control, 84 can be \c NULL. 85 \param message The \a message to send when the radio button is activated, 86 can be \c NULL. 87 \param flags Behavior flags for the checkbox. See BView for details. 88 89 \since Haiku R1 90*/ 91 92 93/*! 94 \fn BRadioButton::BRadioButton(const char* label, BMessage* message) 95 \brief Constructs a BRadioButton object with just a \a label and model 96 \a message. 97 98 The initial value of the radio button is set to 0 (\c B_CONTROL_OFF). 99 The \a label and the \a message parameters can be set to \c NULL. 100 101 \param label The \a label displayed along with the radio button control, 102 can be \c NULL. 103 \param message The \a message to send when the radio button is activated, 104 can be \c NULL. 105 106 \since Haiku R1 107*/ 108 109 110/*! 111 \fn BRadioButton::BRadioButton(BMessage* archive) 112 \brief Constructs a BRadioButton object from an \a archive message. 113 114 This method is usually not called directly, if you want to build a 115 radio button from an archived message you should call Instantiate() 116 instead because it can handle errors properly. 117 118 \param archive The message to construct the BRadioButton object from. 119 120 \since BeOS R3 121*/ 122 123 124/*! 125 \fn BRadioButton::~BRadioButton() 126 \brief Destructor, does nothing. 127 128 \since BeOS R3 129*/ 130 131 132/*! 133 \name Archiving 134*/ 135 136 137//! @{ 138 139 140/*! 141 \fn BArchivable* BRadioButton::Instantiate(BMessage* archive) 142 \brief Creates a new BRadioButton object from the \a archive message. 143 144 \return A newly created radio button or \c NULL if the message doesn't 145 contain an archived BRadioButton. 146 147 \since BeOS R3 148*/ 149 150 151/*! 152 \fn status_t BRadioButton::Archive(BMessage* archive, bool deep) const 153 \brief Archives the object into the \a data message. 154 155 \param archive A pointer to the BMessage object to archive the object into. 156 \param deep Whether or not to archive child views as well. 157 158 \return A status code, \c B_OK if everything went well or an error code 159 otherwise. 160 161 \sa BControl::Archive() 162 163 \since BeOS R3 164*/ 165 166 167//! @} 168 169 170/*! 171 \name Hook Methods 172*/ 173 174 175//! @{ 176 177 178/*! 179 \fn void BRadioButton::AllAttached() 180 \copydoc BView::AllAttached() 181*/ 182 183 184/*! 185 \fn void BRadioButton::AllDetached() 186 \copydoc BView::AllDetached() 187*/ 188 189 190/*! 191 \fn void BRadioButton::AttachedToWindow() 192 \brief Hook method called when the control is attached to a window. 193 194 \copydetails BControl::AttachedToWindow() 195*/ 196 197 198/*! 199 \fn void BRadioButton::DetachedFromWindow() 200 \brief Hook method called when the control is detached from a window. 201 202 \copydetails BControl::DetachedFromWindow() 203*/ 204 205 206/*! 207 \fn void BRadioButton::Draw(BRect updateRect) 208 \brief Draws the area of the radio button that intersects \a updateRect. 209 210 \note This is an hook method called by the Interface Kit, you don't 211 have to call it yourself. If you need to forcefully redraw a 212 radio button consider calling Invalidate() instead. 213 214 \param updateRect The rectangular area to be drawn. 215 216 \sa BView::Draw() 217 218 \since BeOS R3 219*/ 220 221 222/*! 223 \fn void BRadioButton::FrameMoved(BPoint newPosition) 224 \brief Hook method called when the radio button is moved. 225 226 \copydetails BView::FrameMoved() 227*/ 228 229 230/*! 231 \fn void BRadioButton::FrameResized(float newWidth, float newHeight) 232 \brief Hook method called when the radio button is resized. 233 234 \copydetails BView::FrameResized() 235*/ 236 237 238/*! 239 \fn void BRadioButton::KeyDown(const char* bytes, int32 numBytes) 240 \brief Hook method called when a keyboard key is pressed. 241 242 Overrides \c B_RETURN and \c B_SPACE from BControl to toggle the value, 243 but don't allow turning the control off, only on. 244 245 \copydetails BControl::KeyDown() 246*/ 247 248 249/*! 250 \fn void BRadioButton::MessageReceived(BMessage* message) 251 \brief Handle \a message received by the associated looper. 252 253 \copydetails BControl::MessageReceived() 254*/ 255 256 257/*! 258 \fn void BRadioButton::MouseDown(BPoint where) 259 \brief Hook method called when a mouse button is pressed. 260 261 Begins tracking the mouse cursor. 262 263 \copydetails BControl::MouseDown() 264*/ 265 266 267/*! 268 \fn void BRadioButton::MouseMoved(BPoint where, uint32 code, 269 const BMessage* dragMessage) 270 \brief Hook method called when the mouse is moved. 271 272 Once MouseDown() has been called on a radio button this method updates 273 the outline when the cursor is inside the control redrawing as necessary. 274 275 \copydetails BControl::MouseMoved() 276*/ 277 278 279/*! 280 \fn void BRadioButton::MouseUp(BPoint where) 281 \brief Hook method called when a mouse button is released. 282 283 Turns the button on turning off all sibling radio buttons and calls the 284 Invoke() method. Unlike a BCheckBox, a BRadioButton only posts its message when 285 it is turned on, not when it is turned off. 286 287 \copydetails BControl::MouseUp() 288*/ 289 290 291/*! 292 \fn void BRadioButton::WindowActivated(bool active) 293 \brief Hook method called when the attached window is activated or 294 deactivated. 295 296 \copydetails BControl::WindowActivated() 297*/ 298 299 300//! @} 301 302 303/*! 304 \fn void BRadioButton::MakeFocus(bool focus) 305 \brief Makes the radio button the current focus view of the window or 306 gives up being the window's focus view. 307 308 \copydetails BControl::MakeFocus() 309*/ 310 311 312/*! 313 \fn BHandler* BRadioButton::ResolveSpecifier(BMessage* message, 314 int32 index, BMessage* specifier, int32 what, const char* property) 315 \copydoc BHandler::ResolveSpecifier() 316*/ 317 318 319/*! 320 \fn void BRadioButton::SetValue(int32 value) 321 \brief Turn the radio button on or off. 322 323 Turning a radio button on turns off all sibling radio buttons and calls the 324 Invoke() method. 325 326 \copydetails BControl::SetValue() 327*/ 328 329 330/*! 331 \fn void BRadioButton::GetPreferredSize(float* _width, float* _height) 332 \brief Fill out the preferred width and height of the radio button 333 into the \a _width and \a _height parameters. 334 335 \remark Either the \a _width or \a _height parameter may be set to \c NULL 336 if you only want to get the other one. 337 338 \param[out] _width Pointer to a \c float to store the width. 339 \param[out] _height Pointer to a \c float to store the height. 340 341 \since BeOS R3 342*/ 343 344 345/*! 346 \fn status_t BRadioButton::GetSupportedSuites(BMessage* message) 347 \copydoc BControl::GetSupportedSuites(); 348*/ 349 350 351/*! 352 \fn status_t BRadioButton::Invoke(BMessage* message) 353 \copydoc BControl::Invoke() 354*/ 355 356 357/*! 358 \fn status_t BRadioButton::Perform(perform_code code, void* _data) 359 \brief Perform some action. (Internal Method) 360 361 \since Haiku R1 362*/ 363 364 365/*! 366 \fn BAlignment BRadioButton::LayoutAlignment() 367 \brief Returns the alignment used by this control in a layout. 368 369 \return The alignment used by this control as a BAlignment. 370 371 \since Haiku R1 372*/ 373 374 375/*! 376 \fn BSize BRadioButton::MaxSize() 377 \brief Get the maximum size of the radio button. 378 379 \return The maximum size of the radio button as a BSize. 380 381 \sa BAbstractLayout::MaxSize() 382 383 \since Haiku R1 384*/ 385 386 387/*! 388 \fn void BRadioButton::ResizeToPreferred() 389 \brief Resize the control to its preferred size. 390 391 The default implementation does nothing. 392 393 \sa BControl::ResizeToPreferred() 394 395 \since BeOS R3 396*/ 397 398 399/*! 400 \fn status_t BRadioButton::SetIcon(const BBitmap* icon, uint32 flags) 401 \brief Set the icon used by the radio button. 402 403 \see BControl::SetIcon() 404 405 \since Haiku R1 406*/ 407
