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