1/* 2 * Copyright 2011 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/Button.h hrev47274 10 * src/kits/interface/Button.cpp hrev47273 11 12 13/*! 14 \file Button.h 15 \ingroup interface 16 \ingroup libbe 17 \brief Describes the BButton class. 18*/ 19 20 21/*! 22 \class BButton Button.h 23 \ingroup interface 24 \ingroup libbe 25 \brief A control used to initiate an action. 26 27 An action is activated by clicking on the button with the mouse 28 or by a keyboard button. If the button is the default button for 29 the active window then you can activate it by pushing the 30 <span class="keycap">Enter</span> key. 31 32 \image html BButton_example.png 33 34 The behavior of a button depends on its behavior. The normal behavior 35 of a button is to set the value to 1 (\c B_CONTROL_ON) only when the 36 button is activated, otherwise the value is 0 (\c B_CONTROL_OFF). 37 Setting a button to use \c B_TOGGLE_BEHAVIOR makes the button behave 38 like a checkbox so that each time the button is activate the value 39 toggles between \c B_CONTROL_OFF and \c B_CONTROL_ON. The third 40 behavior to use is \c B_POP_UP_BEHAVIOR which adds a pop-up marker 41 to the button similar to that of BMenuField. 42 43 A button may have either a text label, an icon, or both. The button's 44 label is set in the constructor or by the SetLabel() method. To set the 45 icon for a button use the SetIcon() method. The text label will draw 46 to the right of the icon. 47 48 \since BeOS R3 49*/ 50 51 52/*! 53 \fn BButton::BButton(BRect frame, const char* name, const char* label, 54 BMessage* message, uint32 resizingMode, uint32 flags) 55 \brief Creates and initializes a BButton control. 56 57 \note A BButton created with a constructor that includes a frame 58 parameter does \b not utilize the Layout Kit to position and size the 59 control. 60 61 BControl initializes the button's label and assigns it a message that 62 identifies the action that should be carried out when the button is 63 pressed. When the button is attached to a window it is resizes to the 64 height of the button's frame rectangle to fit the button's border and 65 label in the button's font. 66 67 The \a frame, \a name, \a resizingMode, and \a flags parameters are 68 passed up the inheritance chain to the BView class. 69 70 \param frame The frame rectangle that the button is draw into. 71 \param name The name of the button. Can be \c NULL. 72 \param label The button label text. Can be \c NULL. 73 \param message The BButtons's action message. Can be \c NULL. 74 \param resizingMode Mask sets the parameters by which the BButton can be 75 resized. See BView for more information on resizing options. 76 \param flags The \a flags mask sets what notifications the BButton can 77 receive. See BView for more information on \a flags. 78 79 \since BeOS R3 80*/ 81 82 83/*! 84 \fn BButton::BButton(const char* name, const char* label, BMessage* message, 85 uint32 flags) 86 \brief Creates and initializes a BButton control. 87 88 BControl initializes the button's label and assigns it a message that 89 identifies the action that should be carried out when the button is 90 pressed. When the button is attached to a window it is resizes to the 91 height of the button's frame rectange to fit the button's border and 92 label in the button's font. 93 94 \param name The \a name of the button. Can be \c NULL. 95 \param label The button's \a label text. Can be \c NULL. 96 \param message The button's action \a message. Can be \c NULL. 97 \param flags The \a flags mask sets what notifications the button can 98 receive. See BView for more information on \a flags. 99 100 \since Haiku R1 101*/ 102 103 104/*! 105 \fn BButton::BButton(const char* label, BMessage* message) 106 \brief Creates and initializes a BButton control. 107 108 Creates the button with the specified \a label. The action carried out 109 by the button is specified by the \a message. 110 111 \param label The button's \a label text. Can be \c NULL. 112 \param message The buttons action \a message. Can be \c NULL. 113 114 \since Haiku R1 115*/ 116 117 118/*! \fn BButton::BButton(BMessage* data) 119 \brief Constructs a BButton object from an \a data message. 120 121 This method is usually not called directly. If you want to build a 122 button from a message you should call Instantiate() which can 123 handle errors properly. 124 125 If the \a data deep, the BButton object will also unarchive each 126 of its child views recursively. 127 128 \param data The \a data message to restore from. 129 130 \since BeOS R3 131*/ 132 133 134/*! 135 \fn BButton::~BButton() 136 \brief Destructor, does nothing. 137 138 \since BeOS R3 139*/ 140 141 142/*! 143 \name Archiving 144*/ 145 146 147//! @{ 148 149 150/*! 151 \fn BArchivable* BButton::Instantiate(BMessage* archive) 152 \brief Creates a new BButton object from the \a archive message. 153 154 \param archive The \a archive message to restore from. 155 156 \return A newly created check box or \c NULL if the message doesn't 157 contain an archived BButton. 158 159 \since BeOS R3 160*/ 161 162 163/*! 164 \fn status_t BButton::Archive(BMessage* data, bool deep) const 165 \brief Archives the object into the \a data message. 166 167 \param data A pointer to the BMessage object to archive the object into. 168 \param deep Whether or not to archive child views as well. 169 170 \return A status code, \c B_OK if everything went well or an error code 171 otherwise. 172 173 \sa BControl::Archive() 174 175 \since BeOS R3 176*/ 177 178 179//! @} 180 181 182/*! 183 \name Hook Methods 184*/ 185 186 187//! @{ 188 189 190/*! 191 \fn void BButton::AttachedToWindow() 192 \brief Hook method called when the button is attached to a window. 193 194 The view color is set to \c B_TRANSPARENT_COLOR. If the button is 195 the default button the window's default button is updated. 196 197 \sa BControl::AttachedToWindow() 198 199 \since BeOS R3 200*/ 201 202 203/*! 204 \fn void BButton::DetachedFromWindow() 205 \brief Hook method called when the button is detached from a window. 206 207 \copydetails BControl::DetachedFromWindow() 208*/ 209 210 211/*! 212 \fn void BButton::AllAttached() 213 \brief Similar to AttachedToWindow() but this method is triggered after 214 all child views have already been attached to a window. 215 216 \copydetails BView::AllAttached() 217*/ 218 219 220/*! 221 \fn void BButton::AllDetached() 222 \brief Similar to AttachedToWindow() but this method is triggered after 223 all child views have already been detached from a window. 224 225 \copydetails BView::AllDetached() 226*/ 227 228 229/*! 230 \fn void BButton::Draw(BRect updateRect) 231 \brief Draws the area of the button that intersects \a updateRect and 232 sets the label. 233 234 \note This is an hook method called by the Interface Kit, you don't 235 have to call it yourself. If you need to forcefully redraw the 236 button consider calling Invalidate() instead. 237 238 \param updateRect The rectangular area to be drawn. 239 240 \sa BView::Draw() 241 242 \since BeOS R3 243*/ 244 245 246/*! 247 \fn void BButton::FrameMoved(BPoint newPosition) 248 \brief Hook method called when the button is moved. 249 250 \copydetails BView::FrameMoved() 251*/ 252 253 254/*! 255 \fn void BButton::FrameResized(float newWidth, float newHeight) 256 \brief Hook method called when the button is resized. 257 258 \copydetails BView::FrameResized() 259*/ 260 261 262/*! 263 \fn void BButton::KeyDown(const char* bytes, int32 numBytes) 264 \brief Hook method called when a keyboard key is pressed. 265 266 Invokes the button on \a B_ENTER or \a B_SPACE. 267 268 \param bytes The bytes of the key combination pressed. 269 \param numBytes The number of bytes in \a bytes. 270 271 \since BeOS R3 272*/ 273 274 275/*! 276 \fn void BButton::LayoutInvalidated(bool descendants) 277 \brief Hook method called when the layout is invalidated. 278 279 Invalidate cached preferred size. 280 281 \param descendants Whether or not child views have also been invalidated. 282 283 \since Haiku R1 284*/ 285 286 287/*! 288 \fn void BButton::MessageReceived(BMessage* message) 289 \brief Handle \a message received by the associated looper. 290 291 \copydetails BControl::MessageReceived() 292*/ 293 294 295/*! 296 \fn void BButton::MouseDown(BPoint where) 297 \brief Hook method called when a mouse button is pressed. 298 299 Begins tracking the mouse cursor. 300 301 \copydetails BControl::MouseDown() 302*/ 303 304 305/*! 306 \fn void BButton::MouseMoved(BPoint where, uint32 code, 307 const BMessage* dragMessage) 308 \brief Hook method called when the mouse is moved. 309 310 Once MouseDown() has been called this method updates the button's value 311 if the mouse cursor is inside the button. The value that is set depends on 312 if the button is using \c B_TOGGLE_BEHAVIOR or not. 313 314 \copydetails BControl::MouseMoved() 315*/ 316 317 318/*! 319 \fn void BButton::MouseUp(BPoint where) 320 \brief Hook method called when a mouse button is released. 321 322 Set the value of the button if MouseDown() was previously called on the 323 button. The value that is set depends on if the button is using 324 \c B_TOGGLE_BEHAVIOR or not. 325 326 \copydetails BControl::MouseUp() 327*/ 328 329 330/*! 331 \fn void BButton::WindowActivated(bool active) 332 \brief Hook method called when the attached window is activated or 333 deactivated. 334 335 \copydetails BControl::WindowActivated() 336*/ 337 338 339//! @} 340 341 342/*! 343 \fn void BButton::GetPreferredSize(float* _width, float* _height) 344 \brief Fill out the preferred width and height of the button 345 into the \a _width and \a _height parameters. 346 347 \copydetails BControl::GetPreferredSize() 348*/ 349 350 351/*! 352 \fn status_t BButton::GetSupportedSuites(BMessage* message) 353 \brief Report the suites of messages this control understands. 354 355 \copydetails BControl::GetSupportedSuites(); 356*/ 357 358 359/*! 360 \fn status_t BButton::Invoke(BMessage* message) 361 \brief Sends a copy of the model \a message to the designated target. 362 363 \copydetails BControl::Invoke() 364*/ 365 366 367/*! 368 \fn void BButton::MakeDefault(bool flag) 369 \brief Make the BButton the default button i.e. it will be activated 370 when the user pushes the \key{Enter} key. 371 372 A window can have only one default button at a time. 373 374 \param flag \c true to make the button the default button, \c false 375 to remove the default button status. 376 377 \sa BWindow::SetDefaultButton() 378 379 \since BeOS R3 380*/ 381 382 383/*! 384 \fn void BButton::MakeFocus(bool focus) 385 \brief Makes the button the current focus view of the window or 386 gives up being the window's focus view. 387 388 \copydetails BControl::MakeFocus() 389*/ 390 391 392/*! 393 \fn BSize BButton::MinSize() 394 \brief Returns the button's minimum size. 395 396 \return The button's minimum size as a BSize. 397 398 \since Haiku R1 399*/ 400 401 402/*! 403 \fn BSize BButton::MaxSize() 404 \brief Returns the button's maximum size. 405 406 \return The button's maximum size as a BSize. 407 408 \since Haiku R1 409*/ 410 411 412/*! 413 \fn BSize BButton::PreferredSize() 414 \brief Returns the button's preferred size. 415 416 \return The button's preferred size as a BSize. 417 418 \since Haiku R1 419*/ 420 421 422/*! 423 \fn status_t BButton::Perform(perform_code code, void* _data) 424 \copydoc BView::Perform() 425*/ 426 427 428/*! 429 \fn void BButton::ResizeToPreferred() 430 \brief Resize the button to its preferred size. 431 432 \copydetails BView::ResizeToPreferred() 433*/ 434 435 436/*! 437 \fn BHandler* BButton::ResolveSpecifier(BMessage* message, 438 int32 index, BMessage* specifier, int32 what, const char* property) 439 \copydoc BHandler::ResolveSpecifier() 440*/ 441 442 443/*! 444 \fn void BButton::SetLabel(const char* label) 445 \brief Sets the button's label. 446 447 \param label The string to set the label to. 448 449 \since BeOS R3 450*/ 451 452 453/*! 454 \fn bool BButton::IsDefault() const 455 \brief Returns whether or not the button is the default button on the 456 window, i.e. whether or not it responds to the \key{Enter} key. 457 458 \returns \c true if the button is the default button, \c false otherwise. 459 460 \since BeOS R3 461*/ 462 463 464/*! 465 \fn bool BButton::IsFlat() const 466 \brief Returns whether or not the button is flat or not. 467 468 \returns \c true if the button is flat, \c false otherwise. 469 470 \since Haiku R1 471*/ 472 473 474/*! 475 \fn void BButton::SetFlat(bool flat) 476 \brief Sets or unsets the button to be flat. 477 478 \param flat \c true to make the button flat, \c false to make the button 479 not flat. 480 481 \since Haiku R1 482*/ 483 484 485/*! 486 \fn BButton::BBehavior BButton::Behavior() const 487 \brief Returns the buttons behavior. 488 489 \return The button behavior flag. 490 491 \since Haiku R1 492*/ 493 494 495/*! 496 \fn void BButton::SetBehavior(BBehavior behavior) 497 \brief Sets the button behavior. 498 499 \param behavior One of the following: 500 - \c B_BUTTON_BEHAVIOR Normal behavior, 501 - \c B_TOGGLE_BEHAVIOR Acts like a check box, 502 - \c B_POP_UP_BEHAVIOR Adds a pop-up marker to the button 503 (similar to that of BMenuField). 504 505 \since Haiku R1 506*/ 507 508 509/*! 510 \fn BMessage* BButton::PopUpMessage() const 511 \brief Returns the message sent to the button's target when the 512 pop-up marker is selected using \c B_POP_UP_BEHAVIOR. 513 514 \return The message sent to the button's target. 515 516 \since Haiku R1 517*/ 518 519 520/*! 521 \fn void BButton::SetPopUpMessage(BMessage* message) 522 \brief Sets the message sent to the button's target when the 523 pop-up marker is selected using \c B_POP_UP_BEHAVIOR. 524 525 \param message The \a message sent to the button's target. 526 527 \since Haiku R1 528*/ 529 530 531/*! 532 \fn status_t BControl::SetIcon(const BBitmap* icon, uint32 flags) 533 \brief This convenience method is used to set the bitmaps 534 for the standard states from a single bitmap. 535 536 \param icon The \a icon to set. 537 \param flags Modify how the icon is set. 538 539 \return \c B_OK if the icon was set or an error code otherwise. 540 541 \sa BControl::SetIcon() 542 543 \since Haiku R1 544*/ 545 546 547/*! 548 \fn void BButton::SetValue(int32 value) 549 \brief Sets the value of the button. 550 551 \note This method can be overridden in order to take a different action 552 when the value changes. 553 554 \param value The value to set to the BButton to. Options include: 555 - \c 0 (\c B_CONTROL_OFF) 556 - \c 1 (\c B_CONTROL_ON) 557 558 \see BControl::SetValue() 559 560 \since BeOS R3 561*/ 562
