1/* 2 * Copyright 2011, Haiku inc. 3 * Distributed under the terms of the MIT License. 4 * 5 * Documentation by: 6 * John Scipione, jscipione@gmail.com 7 * Corresponds to: 8 * /trunk/headers/os/interface/Button.h rev 42794 9 * /trunk/src/kits/interface/Button.cpp rev 42794 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 Constructs a BButton object from an \a archive message. 145 146 This method is usually not called directly. If you want to build a 147 button from a message you should call Instantiate() which can 148 handle errors properly. 149 150 If the \a archive deep, the BButton object will also unarchive each 151 of its child views recursively. 152 153 \param archive The \a archive message to restore from. 154*/ 155 156 157/*! 158 \fn void BButton::Draw(BRect updateRect) 159 \brief Draws the area of the button that intersects \a updateRect and 160 sets the label. 161 162 \note This is an hook method called by the Interface Kit, you don't 163 have to call it yourself. If you need to forcefully redraw the button 164 consider calling Invalidate() instead. 165 166 \param updateRect The rectangular area to be drawn. 167 168 \sa BView::Draw() 169*/ 170 171 172/*! 173 \fn void BButton::MouseDown(BPoint point) 174 \brief Hook method that is called when a mouse button is pressed. 175 176 \param point The point on the screen where to mouse pointer is when 177 the mouse button is pressed. 178 179 \sa BView::MouseDown() 180*/ 181 182 183/*! 184 \fn void BButton::AttachedToWindow() 185 \brief Hook method that is called when the object is attached to a 186 window. 187 188 \sa BControl::AttachedToWindow() 189*/ 190 191 192/*! 193 \fn void BButton::KeyDown(const char *bytes, int32 numBytes) 194 \brief Hook method that is called when a keyboard key is pushed down. 195 to the window. 196 197 \param bytes The key pressed. 198 \param numBytes The number of keys pressed. 199*/ 200 201 202/*! 203 \fn void BButton::MakeDefault(bool flag) 204 \brief Make the BButton the default button i.e. it will be activated 205 when the user pushes the \key{Enter} key. 206 207 \param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned 208 by the Layout Kit. 209*/ 210 211 212/*! 213 \fn void BButton::SetLabel(const char *string) 214 \brief Sets the BButton's label. 215 216 \param string The string to set the label to. 217*/ 218 219 220/*! 221 \fn bool BButton::IsDefault() const 222 \brief Returns whether or not the BButton is the default button or not, i.e. 223 it responds to the \key{Enter} key. 224 225 \retval true The button is the default button. 226 \retval false The button is \b not the default button. 227*/ 228 229 230/*! 231 \fn void BButton::SetValue(int32 value) 232 \brief Sets the value of the BButton. 233 234 \note This method can be overridden in order to take a different action 235 when the value changes. 236 237 \param value The value to set to the BButton to. Options include: 238 \li \c 0 (\c B_CONTROL_OFF) 239 \li \c 1 (\c B_CONTROL_ON) 240 241 \see BControl::SetValue() 242*/ 243 244 245/*! 246 \fn void BButton::GetPreferredSize(float *_width, float *_height) 247 \brief Gets the dimensions that the BButton would prefer to be. 248 249 The size is computed from the children sizes, unless it was explicitly set 250 for the BButton (which can be done only if the BButton is configured to 251 use the Layout Kit). 252 253 \note Either the \a _width or \a _height parameter may be set to \c NULL 254 if you only want to get the other one. 255 256 \param[out] _width The width of the preferred size is placed in here. 257 \param[out] _height The height of the preferred size is placed in here. 258*/ 259 260 261/*! 262 \fn void BButton::ResizeToPreferred() 263 \brief Resizes the BButton to its preferred size. 264 265 \see BView::ResizeToPreferred() 266*/ 267 268 269/*! 270 \fn status_t BButton::Invoke(BMessage *message) 271 \brief The BButton is invoked from a message. 272 273 This method is used to post a message when the button is clicked or 274 activated by a keyboard button. You can set the object that will 275 handle the message by calling a BControl::SetTarget() from a 276 BInvoker inherited control. A model for the message is set by the 277 BButton constructor or by the BControl::SetMessage() method 278 inherited from BInvoker. 279 280 \returns B_OK If the BButton was invoked, otherwise an error 281 \a status_t flag is returned. 282 283 \see BControl::Invoke() 284*/ 285 286 287/*! 288 \fn void BButton::FrameMoved(BPoint newLocation) 289 \brief Hook method that is called when the BButton has moved. 290 291 \param newLocation The location on the screen that the BButton 292 is moved to. 293 294 \see BView::FrameMoved(); 295*/ 296 297 298/*! 299 \fn void BButton::FrameResized(float width, float height) 300 \brief Hook method that is called when the BButton changes size. 301 302 \param width the new \a width of the BButton 303 \param height the new \a height of the BButton 304 305 \see BView::FrameResized(); 306*/ 307 308 309/*! 310 \fn void BButton::MakeFocus(bool focused) 311 \brief Focus or unfocus the BButton. 312 313 \param focused If \c true focus the button, otherwise remove focus from 314 the button. 315 316 \see BControl::MakeFocus() 317*/ 318 319 320/*! 321 \fn status_t BButton::Perform(perform_code code, void* _data) 322 \brief Perform an action on the BButton. 323 324 \param code The \a perform_code. One of the following: 325 \li \c PERFORM_CODE_MIN_SIZE 326 \li \c PERFORM_CODE_MAX_SIZE 327 \li \c PERFORM_CODE_PREFERRED_SIZE 328 \li \c PERFORM_CODE_LAYOUT_ALIGNMENT 329 \li \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH 330 \li \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH 331 \li \c PERFORM_CODE_SET_LAYOUT 332 \li \c PERFORM_CODE_INVALIDATE_LAYOUT 333 \li \c PERFORM_CODE_DO_LAYOUT 334 \param _data Data to use to act on. 335 336 \returns \c B_OK if the action was successful or an error code if not. 337*/ 338 339 340/*! 341 \fn void BButton::InvalidateLayout(bool descendants) 342 \brief Redraws the BButton. 343 344 \param descendants Redraw subviews as well. 345*/ 346 347 348/*! 349 \fn BSize BButton::MinSize() 350 \brief Returns the minimum size of the BButton. 351 352 \returns The minimum BButton size as a BSize 353*/ 354 355 356/*! 357 \fn BSize BButton::MaxSize() 358 \brief Returns the maximum size of the BButton. 359 360 \returns The maximum BButton size as a BSize 361*/ 362 363 364/*! 365 \fn BSize BButton::PreferredSize() 366 \brief Returns the preferred size of the BButton. 367 368 \returns The preferred BButton size as a BSize 369*/ 370
