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