1/* 2 * Copyright 2011, Haiku inc. 3 * Distributed under the terms of the MIT Licence. 4 * 5 * Documentation by: 6 * John Scipione <jscipione@gmail.com> 7 * Corresponds to: 8 * /trunk/headers/os/interface/Button.h 9 * /trunk/src/kits/interface/Button.cpp 10 11 12/*! 13 \file Button.h 14 \brief Describes the BButton class. 15*/ 16 17 18/*! 19 \class BButton Button.h 20 \ingroup interface 21 \brief A BButton is a labeled on-screen button. 22 23 A BButton control is used to initiate an action. An action is activated 24 by clicking on the button with the mouse or by a keyboard button. 25 If the BButton is the default button for the active window then you can 26 activate it by pushing the <span class="keycap">Enter</span> key. 27 28 \image html BButton_example.png 29 30 A BButton, unlike other user interface elements such as check boxes and 31 radio buttons has only a single state. During a click event the 32 BButton's value is set to \c 1, (\c B_CONTROL_ON) otherwise this value 33 is \c 0 (\c B_CONTROL_OFF). 34 35 BButton inherits from the BControl class. 36*/ 37 38 39/*! 40 \fn BButton::BButton(BRect frame, const char* name, const char* label, 41 BMessage* message, uint32 resizingMode, uint32 flags) 42 \brief Creates and initializes a BButton control. 43 44 \note A BButton created with a constructor that includes a frame 45 parameter does \b not utilize the Layout Kit to position and size the 46 control. 47 48 BControl initializes the button's label and assigns it a message that 49 identifies the action that should be carried out when the button is 50 pressed. When the button is attached to a window it is resizes to the 51 height of the button's frame rectangle to fit the button's border and 52 label in the button's font. 53 54 The \a frame, \a name, \a resizingMode, and \a flags parameters are 55 passed up the inheritance chain to the BView class. 56 57 \param frame The frame rectangle that the button is draw into. 58 \param name The name of the button 59 \param label The button label text 60 \param message The BButtons's action message 61 \param resizingMode Mask sets the parameters by which the BButton can be 62 resized. It should be set to one option for vertical resizing combined 63 with one option for horizontal resizing. 64 \n\n Horizontal resizing options are 65 \li \c B_FOLLOW_LEFT 66 \li \c B_FOLLOW_RIGHT 67 \li \c B_FOLLOW_LEFT_RIGHT 68 \li \c B_FOLLOW_H_CENTER 69 70 Vertical resizing options are 71 \li \c B_FOLLOW_TOP 72 \li \c B_FOLLOW_BOTTOM 73 \li \c B_FOLLOW_TOP_BOTTOM 74 \li \c B_FOLLOW_V_CENTER 75 76 There are two other possibilities 77 \li \c B_FOLLOW_ALL_SIDES 78 \li \c B_FOLLOW_NONE 79 80 See BView for more information on resizing options. 81 \param flags The flags mask sets what notifications the BButton can receive. 82 \n\n Any combination of the following options is allowed 83 \li \c B_WILL_DRAW 84 \li \c B_PULSE_NEEDED 85 \li \c B_FRAME_EVENTS 86 \li \c B_FULL_UPDATE_ON_RESIZE 87 \li \c B_NAVIAGBLE 88 \li \c B_NAVIAGBLE_JUMP 89 \li \c B_SUBPIXEL_PRECISE 90 91 See BView for more information on \a flags. 92*/ 93 94 95/*! 96 \fn BButton::BButton(const char* name, const char* label, BMessage* message, 97 uint32 flags) 98 \brief Creates and initializes a BButton control. 99 100 BControl initializes the button's label and assigns it a message that 101 identifies the action that should be carried out when the button is 102 pressed. When the button is attached to a window it is resizes to the 103 height of the button's frame rectange to fit the button's border and 104 label in the button's font. 105 106 \param name The \a name of the button 107 \param label The button's \a label text 108 \param message The button's action \a message 109 \param flags The \a flags mask sets what notifications the button can 110 receive. Any combination of the following options is allowed: 111 \li \c B_WILL_DRAW 112 \li \c B_PULSE_NEEDED 113 \li \c B_FRAME_EVENTS 114 \li \c B_FULL_UPDATE_ON_RESIZE 115 \li \c B_NAVIAGBLE 116 \li \c B_NAVIAGBLE_JUMP 117 \li \c B_SUBPIXEL_PRECISE 118 119 See BView for more information on \a flags. 120*/ 121 122 123/*! 124 \fn BButton::BButton(const char* label, BMessage* message) 125 \brief Creates and initializes a BButton control. 126 127 Creates the button with the specified \a label. The action carried out 128 by the button is specified by the \a message. 129 130 \param label The button's \a label text 131 \param message The buttons action \a message 132*/ 133 134 135/*! 136 \fn BButton::~BButton() 137 \brief Destructor method. 138 139 Standard Destructor. 140*/ 141 142 143/*! \fn BButton::BButton(BMessage* archive) 144 \brief Creates a new BButton from an \a archive. 145 146 If the message is a valid button then an instance of BButton created 147 from the passed in \a archive will be returned. Otherwise this method 148 will return \c NULL. 149 150 \returns An instance of BButton if the \a archive is valid or \c NULL. 151*/ 152 153 154/*! 155 \fn BArchivable* BButton::Instantiate(BMessage* archive) 156 \brief Instantiates a BButton from a BMessage. 157 158 \param archive The \c archive message to instantiate the BButton. 159 160 \returns a BArchivable object of the BButton. 161*/ 162 163 164/*! 165 \fn status_t BButton::Archive(BMessage* archive, bool deep) const 166 \brief Archives the BButton into \a archive. 167 168 \param archive The target \a archive which the BButton data will 169 go into. 170 \param deep Whether or not to recursively archive the BButton's children. 171 172 \retval B_OK The archive operation was successful. 173 \retval B_BAD_VALUE The archive operation failed. 174*/ 175 176 177/*! 178 \fn void BButton::Draw(BRect updateRect) 179 \brief Draws the button and sets its label. 180 181 \param updateRect The BRect which the button is drawn into. 182*/ 183 184 185/*! 186 \fn void BButton::MouseDown(BPoint point) 187 \brief Hook method to respond to a MouseDown event. 188 189 \param point The point on the screen that the mouse pointer is located at. 190*/ 191 192 193/*! 194 \fn void BButton::AttachedToWindow() 195 \brief Hook method that is called when the BButton view is attached 196 to the window. 197*/ 198 199 200/*! 201 \fn void BButton::KeyDown(const char *bytes, int32 numBytes) 202 \brief Hook method that is called when a keyboard key is pushed down. 203 to the window. 204 205 \param bytes The key pressed. 206 \param numBytes The number of keys pressed. 207*/ 208 209 210/*! 211 \fn void BButton::MakeDefault(bool flag) 212 \brief Make the BButton the default button i.e. it will be activated 213 when the user pushes the \key{Enter} key. 214 215 \param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned 216 by the Layout Kit. 217*/ 218 219 220/*! 221 \fn void BButton::SetLabel(const char *string) 222 \brief Sets the BButton's label. 223 224 \param string The string to set the label to. 225*/ 226 227 228/*! 229 \fn bool BButton::IsDefault() const 230 \brief Returns whether or not the BButton is the default button or not, i.e. 231 it responds to the \key{Enter} key. 232 233 \retval true The button is the default button. 234 \retval false The button is \b not the default button. 235*/ 236 237 238/*! 239 \fn void BButton::MessageReceived(BMessage *message) 240 \brief Hook method that is called when a message is received by the BButton. 241 242 \param message The message received. 243*/ 244 245 246/*! 247 \fn void BButton::WindowActivated(bool active) 248 \brief Sets the window that the BButton is attached to as activated or not. 249 250 \param active if \c true the window is activated, if \c false the window is 251 deactivated. 252*/ 253 254 255/*! 256 \fn void BButton::MouseMoved(BPoint point, uint32 transit, 257 const BMessage *message) 258 \brief Hook method that is called when the mouse is moved. 259 260 \param point The point on the screen that the mouse pointer is located at. 261 \param transit ??? 262 \param message The message that is received when the mouse is moved. 263*/ 264 265 266/*! 267 \fn void BButton::MouseUp(BPoint point) 268 \brief Hook method that is called when a mouse button is unpressed. 269 270 \param point The point on the screen that the mouse pointer is located at. 271*/ 272 273 274/*! 275 \fn void BButton::DetachedFromWindow() 276 \brief Detaches the BButton from the window. 277 278 \see BControl::DetachedFromWindow() 279*/ 280 281 282/*! 283 \fn void BButton::SetValue(int32 value) 284 \brief Sets the value of the BButton. 285 286 \note This method can be overridden in order to take a different action 287 when the value changes. 288 289 \param value The value to set to the BButton to. Options include: 290 \li \c 0 (\c B_CONTROL_OFF) 291 \li \c 1 (\c B_CONTROL_ON) 292 293 \see BControl::SetValue() 294*/ 295 296 297/*! 298 \fn void BButton::GetPreferredSize(float *_width, float *_height) 299 \brief Gets the dimensions that the BButton would prefer to be. 300 301 The size is computed from the children sizes, unless it was explicitly set 302 for the BButton (which can be done only if the BButton is configured to 303 use the Layout Kit). 304 305 \note Either the \a _width or \a _height parameter may be set to \c NULL 306 if you only want to get the other one. 307 308 \param[out] _width The width of the preferred size is placed in here. 309 \param[out] _height The height of the preferred size is placed in here. 310*/ 311 312 313/*! 314 \fn void BButton::ResizeToPreferred() 315 \brief Resizes the BButton to its preferred size. 316 317 \see BControl::ResizeToPreferred() 318*/ 319 320 321/*! 322 \fn status_t BButton::Invoke(BMessage *message) 323 \brief The BButton is invoked from a message. 324 325 This method is used to post a message when the button is clicked or 326 activated by a keyboard button. You can set the object that will 327 handle the message by calling a BControl::SetTarget() from a 328 BInvoker inherited control. A model for the message is set by the 329 BButton constructor or by the BControl::SetMessage() method 330 inherited from BInvoker. 331 332 \returns B_OK If the BButton was invoked, otherwise an error 333 \a status_t flag is returned. 334 335 \see BControl::Invoke() 336*/ 337 338 339/*! 340 \fn void BButton::FrameMoved(BPoint newLocation) 341 \brief Hook method that is called when the BButton has moved. 342 343 \param newLocation The location on the screen that the BButton 344 is moved to. 345 346 \see BControl::FrameMoved(); 347*/ 348 349 350/*! 351 \fn void BButton::FrameResized(float width, float height) 352 \brief Hook method that is called when the BButton changes size. 353 354 \param width the new \a width of the BButton 355 \param height the new \a height of the BButton 356 357 \see BControl::FrameResized(); 358*/ 359 360 361/*! 362 \fn void BButton::MakeFocus(bool focused) 363 \brief Focus or unfocus the BButton. 364 365 \param focused If \c true focus the BButton, otherwise unfocus the BButton. 366 367 \see BControl::MakeFocus() 368*/ 369 370 371/*! 372 \fn void BButton::AllAttached() 373 \brief Hook method that is called when the BButton is attached. 374 375 \see BControl::AllAttached() 376*/ 377 378 379/*! 380 \fn void BButton::AllDetached() 381 \brief Hook method that is called when the BButton is deattached. 382 383 \see BControl::AllDetached() 384*/ 385 386 387/*! 388 \fn BHandler* BButton::ResolveSpecifier(BMessage *message, int32 index, 389 BMessage *specifier, int32 what, property) 390 \brief Resolves specifiers for properties. 391 \see BHandler::ResolveSpecifier() 392*/ 393 394 395/*! 396 \fn status_t BButton::GetSupportedSuites(BMessage *message) 397 \brief Reports the suites of messages and specifiers that derived classes 398 understand. 399 400 \param message The message to report the suite of messages and specifiers. 401 402 \see BWindow::GetSupportedSuites() 403*/ 404 405 406/*! 407 \fn status_t BButton::Perform(perform_code code, void* _data) 408 \brief Perform an action on the BButton. 409 410 \param code The \a perform_code. One of the following: 411 \li \c PERFORM_CODE_MIN_SIZE 412 \li \c PERFORM_CODE_MAX_SIZE 413 \li \c PERFORM_CODE_PREFERRED_SIZE 414 \li \c PERFORM_CODE_LAYOUT_ALIGNMENT 415 \li \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH 416 \li \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH 417 \li \c PERFORM_CODE_SET_LAYOUT 418 \li \c PERFORM_CODE_INVALIDATE_LAYOUT 419 \li \c PERFORM_CODE_DO_LAYOUT 420 \param _data Data to use to act on. 421 422 \returns \c B_OK if the action was successful or an error code if not. 423*/ 424 425 426/*! 427 \fn void BButton::InvalidateLayout(bool descendants) 428 \brief Redraws the BButton. 429 430 \param descendants Redraw subviews as well. 431*/ 432 433 434/*! 435 \fn BSize BButton::MinSize() 436 \brief Returns the minimum size of the BButton. 437 438 \returns The minimum BButton size as a BSize 439*/ 440 441 442/*! 443 \fn BSize BButton::MaxSize() 444 \brief Returns the maximum size of the BButton. 445 446 \returns The maximum BButton size as a BSize 447*/ 448 449 450/*! 451 \fn BSize BButton::PreferredSize() 452 \brief Returns the preferred size of the BButton. 453 454 \returns The preferred BButton size as a BSize 455*/ 456 457
