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 45 46/*! 47 \fn BRadioButton::BRadioButton(BRect frame, const char* name, 48 const char* label, BMessage* message, uint32 resizingMode, 49 uint32 flags) 50 \brief Construct a radio button in the \a frame rectangle with a \a name, 51 \a label, model \a message, \a resizingMode, and creation \a flags. 52 53 \note This constructor will resize the control to it's minimum height if needed 54 for compatibility with BeOS R5. 55 56 The initial value of the radio button is 0 (\c B_CONTROL_OFF). 57 58 \param frame The \a frame to draw the radio button in. 59 \param name The \a name of the radio button, can be \c NULL. 60 \param label The \a label displayed along with the radio button control, 61 can be \c NULL. 62 \param message The \a message to send when the radio button is activated, 63 can be \c NULL. 64 \param resizingMode Defines the behavior of the radio button as the parent 65 view resizes. See BView for details. 66 \param flags Behavior flags for the radio button. See BView for details. 67*/ 68 69 70/*! 71 \fn BRadioButton::BRadioButton(const char* name, const char* label, 72 BMessage* message, uint32 flags) 73 \brief Construct a radio button with a \a name, \a label, model \a message, 74 and creation \a flags suitable for use with the Layout API. 75 76 The initial value of the radio button is 0 (\c B_CONTROL_OFF). 77 78 \param name The \a name of the radio button, can be \c NULL. 79 \param label The \a label displayed along with the radio button control, 80 can be \c NULL. 81 \param message The \a message to send when the radio button is activated, 82 can be \c NULL. 83 \param flags Behavior flags for the checkbox. See BView for details. 84*/ 85 86 87/*! 88 \fn BRadioButton::BRadioButton(const char* label, BMessage* message) 89 \brief Constructs a BRadioButton object with just a \a label and model 90 \a message. 91 92 The initial value of the radio button is set to 0 (\c B_CONTROL_OFF). 93 The \a label and the \a message parameters can be set to \c NULL. 94 95 \param label The \a label displayed along with the radio button control, 96 can be \c NULL. 97 \param message The \a message to send when the radio button is activated, 98 can be \c NULL. 99*/ 100 101 102/*! 103 \fn BRadioButton::BRadioButton(BMessage* archive) 104 \brief Constructs a BRadioButton object from an \a archive message. 105 106 This method is usually not called directly, if you want to build a 107 radio button from an archived message you should call Instantiate() 108 instead because it can handle errors properly. 109 110 \param archive The message to construct the BRadioButton object from. 111*/ 112 113 114/*! 115 \fn BRadioButton::~BRadioButton() 116 \brief Destructor, does nothing. 117*/ 118 119 120/*! 121 \name Archiving 122*/ 123 124 125//! @{ 126 127 128/*! 129 \fn BArchivable* BRadioButton::Instantiate(BMessage* archive) 130 \brief Creates a new BRadioButton object from the \a archive message. 131 132 \return A newly created radio button or \c NULL if the message doesn't 133 contain an archived BRadioButton. 134*/ 135 136 137/*! 138 \fn status_t BRadioButton::Archive(BMessage* archive, bool deep) const 139 \brief Archives the object into the \a data message. 140 141 \param archive A pointer to the BMessage object to archive the object into. 142 \param deep Whether or not to archive child views as well. 143 144 \return A status code, \c B_OK if everything went well or an error code 145 otherwise. 146 147 \sa BControl::Archive() 148*/ 149 150 151//! @} 152 153 154/*! 155 \name Hook Methods 156*/ 157 158 159//! @{ 160 161 162/*! 163 \fn void BRadioButton::AttachedToWindow() 164 \brief Hook method called when the control is attached to a window. 165 166 The default implementation does nothing. 167 168 \sa BControl::AttachedToWindow() 169*/ 170 171 172/*! 173 \fn void BRadioButton::DetachedFromWindow() 174 \brief Hook method called when the control is detached from a window. 175 176 The default implementation does nothing. 177 178 \sa BControl::DetachedFromWindow() 179*/ 180 181 182/*! 183 \fn void BRadioButton::AllAttached() 184 \brief Similar to AttachedToWindow() but this method is triggered after 185 all child views have already been attached to a window. 186 187 The default implementation does nothing. 188 189 \sa BView::AllAttached() 190*/ 191 192 193/*! 194 \fn void BRadioButton::AllDetached() 195 \brief Similar to AttachedToWindow() but this method is triggered after 196 all child views have already been detached from a window. 197 198 The default implementation does nothing. 199 200 \sa BView::AllDetached() 201*/ 202 203 204/*! 205 \fn void BRadioButton::Draw(BRect updateRect) 206 \brief Draws the area of the radio button that intersects \a updateRect. 207 208 \note This is an hook method called by the Interface Kit, you don't 209 have to call it yourself. If you need to forcefully redraw a 210 radio button consider calling Invalidate() instead. 211 212 \param updateRect The rectangular area to be drawn. 213 214 \sa BView::Draw() 215*/ 216 217 218/*! 219 \fn void BRadioButton::FrameMoved(BPoint newPosition) 220 \brief Hook method called when the radio button is moved. 221 222 The default implementation does nothing. 223 224 \param newPosition The point that the radio button has been moved to. 225 226 \sa BView::FrameMoved() 227*/ 228 229 230/*! 231 \fn void BRadioButton::FrameResized(float width, float height) 232 \brief Hook method called when the radio button is resized. 233 234 The default implementation does nothing. 235 236 \param width The new \a width of the radio button. 237 \param height The new \a height of the radio button. 238 239 \sa BView::FrameResized() 240*/ 241 242 243/*! 244 \fn void BRadioButton::KeyDown(const char* bytes, int32 numBytes) 245 \brief Hook method called when a keyboard key is pressed. 246 247 Overrides \c B_RETURN and \c B_SPACE from BControl to toggle the value, 248 but don't allow turning the control off, only on. 249 250 \param bytes The bytes of the key combination pressed. 251 \param numBytes The number of bytes in \a bytes. 252*/ 253 254 255/*! 256 \fn void BRadioButton::MessageReceived(BMessage* message) 257 \brief Handle \a message received by the associated looper. 258 259 The default implemenation does nothing. 260 261 \param message The \a message received by the associated looper. 262 263 \see BControl::MessageReceived() 264*/ 265 266 267/*! 268 \fn void BRadioButton::MouseDown(BPoint where) 269 \brief Hook method called when a mouse button is pressed. 270 271 Begins tracking the mouse cursor. 272 273 \param where The point on the screen where to mouse pointer is when 274 the mouse button is pressed. 275*/ 276 277 278/*! 279 \fn void BRadioButton::MouseMoved(BPoint where, uint32 code, 280 const BMessage* dragMessage) 281 \brief Hook method called when the mouse is moved. 282 283 Once MouseDown() has been called on a radio button this method updates 284 the outline when the cursor is inside the control redrawing as necessary. 285 286 \param where The new location of the mouse in the control's coordinate system. 287 \param code One of the following: 288 - \c B_ENTERED_VIEW The cursor has just entered the control. 289 - \c B_INSIDE_VIEW The cursor is inside the control. 290 - \c B_EXITED_VIEW The cursor has left the control's bounds. This only gets 291 sent if the scope of the mouse events that the control can receive has 292 been expanded by BView::SetEventMask() or BView::SetMouseEventMask(). 293 - \c B_OUTSIDE_VIEW The cursor is outside the button. This only gets sent if 294 the scope of the mouse events that the control can receive has been 295 expanded by SetEventMask() or SetMouseEventMask(). 296 \param dragMessage If a drag-and-drop operation is taking place this is a 297 pointer to a BMessage that holds the drag information, otherwise the 298 pointer is \c NULL. 299*/ 300 301 302/*! 303 \fn void BRadioButton::MouseUp(BPoint where) 304 \brief Hook method called when a mouse button is released. 305 306 Turns the button on turning off all sibling radio buttons and calls the 307 Invoke() method. Unlike a BCheckBox, a BRadioButton only posts its message when 308 it is turned on, not when it is turned off. 309 310 \param where The point on the screen where the mouse pointer is located when 311 the mouse button is released in the view's coordinate system. 312 313 \sa BControl::MouseUp() 314*/ 315 316 317/*! 318 \fn void BRadioButton::WindowActivated(bool active) 319 \brief Hook method called when the attached window is activated or 320 deactivated. 321 322 The default implementation does nothing. 323 324 \param active \c true if the window becomes activated, \c false if the 325 window becomes deactivated. 326 327 \sa BControl::WindowActivated() 328*/ 329 330 331//! @} 332 333 334/*! 335 \fn void BRadioButton::MakeFocus(bool focused) 336 \brief Makes the radio button the current focus view of the window or 337 gives up being the window's focus view. 338 339 The default implementation does nothing. 340 341 \param focused \a true to set focus, \a false to remove it. 342 343 \sa BControl::MakeFocus() 344*/ 345 346 347/*! 348 \fn BHandler* BRadioButton::ResolveSpecifier(BMessage* message, 349 int32 index, BMessage* specifier, int32 what, const char* property) 350 \brief Determine the proper specifier for scripting messages. 351 352 The default implementation does nothing. 353 354 \sa BControl::ResolveSpecifier() 355*/ 356 357 358/*! 359 \fn void BRadioButton::SetValue(int32 value) 360 \brief Turn the radio button on or off. 361 362 Turning a radio button on turns off all sibling radio buttons and calls the 363 Invoke() method. 364 365 \param value The value to set the radio button to, should be 366 either \c B_CONTROL_ON or \c B_CONTROL_OFF. 367 368 \sa BControl::SetValue() 369*/ 370 371 372/*! 373 \fn void BRadioButton::GetPreferredSize(float* _width, float* _height) 374 \brief Fill out the preferred width and height of the radio button 375 into the \a _width and \a _height parameters. 376 377 \remark Either the \a _width or \a _height parameter may be set to \c NULL 378 if you only want to get the other one. 379 380 \param[out] _width Pointer to a \c float to store the width. 381 \param[out] _height Pointer to a \c float to store the height. 382*/ 383 384 385/*! 386 \fn status_t BRadioButton::GetSupportedSuites(BMessage* message) 387 \brief Report the suites of messages this control understands. 388 389 \param message Allows you to add the names of the suites the radio button 390 implements to the suites array. 391 392 \return \c B_OK if all went well or an error code otherwise. 393 394 \sa BControl::GetSupportedSuites(); 395*/ 396 397 398/*! 399 \fn status_t BRadioButton::Invoke(BMessage* message) 400 \brief Sends a copy of the model \a message to the designated target. 401 402 The default implementation does nothing. 403 404 \sa BControl::Invoke() 405*/ 406 407 408/*! 409 \fn status_t BRadioButton::Perform(perform_code code, void* _data) 410 \brief Perform some action. (Internal Method) 411*/ 412 413 414/*! 415 \fn BAlignment BRadioButton::LayoutAlignment() 416 \brief Returns the alignment used by this control in a layout. 417 418 \return The alignment used by this control as a BAlignment. 419*/ 420 421 422/*! 423 \fn BSize BRadioButton::MaxSize() 424 \brief Get the maximum size of the radio button. 425 426 \return The maximum size of the radio button as a BSize. 427 428 \sa BAbstractLayout::MaxSize() 429*/ 430 431 432/*! 433 \fn void BRadioButton::ResizeToPreferred() 434 \brief Resize the control to its preferred size. 435 436 The default implementation does nothing. 437 438 \sa BControl::ResizeToPreferred() 439*/ 440 441 442/*! 443 \fn status_t BRadioButton::SetIcon(const BBitmap* icon, uint32 flags) 444 \brief Set the icon used by the radio button. 445 446 \see BControl::SetIcon() 447*/ 448
