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 rev 42794 10 * src/kits/interface/Button.cpp rev 42794 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 BButton is a labeled on-screen button. 26 27 A BButton control is used to initiate an action. An action is activated 28 by clicking on the button with the mouse or by a keyboard button. 29 If the BButton is the default button for the active window then you can 30 activate it by pushing the <span class="keycap">Enter</span> key. 31 32 \image html BButton_example.png 33 34 A BButton, unlike other user interface elements such as check boxes and 35 radio buttons has only a single state. During a click event the 36 BButton's value is set to 1, (\c B_CONTROL_ON) otherwise this value 37 is 0 (\c B_CONTROL_OFF). 38 39 BButton inherits from the BControl class. 40*/ 41 42 43/*! 44 \fn BButton::BButton(BRect frame, const char* name, const char* label, 45 BMessage* message, uint32 resizingMode, uint32 flags) 46 \brief Creates and initializes a BButton control. 47 48 \note A BButton created with a constructor that includes a frame 49 parameter does \b not utilize the Layout Kit to position and size the 50 control. 51 52 BControl initializes the button's label and assigns it a message that 53 identifies the action that should be carried out when the button is 54 pressed. When the button is attached to a window it is resizes to the 55 height of the button's frame rectangle to fit the button's border and 56 label in the button's font. 57 58 The \a frame, \a name, \a resizingMode, and \a flags parameters are 59 passed up the inheritance chain to the BView class. 60 61 \param frame The frame rectangle that the button is draw into. 62 \param name The name of the button 63 \param label The button label text 64 \param message The BButtons's action message 65 \param resizingMode Mask sets the parameters by which the BButton can be 66 resized. It should be set to one option for vertical resizing combined 67 with one option for horizontal resizing. 68 \n\n Horizontal resizing options are 69 \li \c B_FOLLOW_LEFT 70 \li \c B_FOLLOW_RIGHT 71 \li \c B_FOLLOW_LEFT_RIGHT 72 \li \c B_FOLLOW_H_CENTER 73 74 Vertical resizing options are 75 \li \c B_FOLLOW_TOP 76 \li \c B_FOLLOW_BOTTOM 77 \li \c B_FOLLOW_TOP_BOTTOM 78 \li \c B_FOLLOW_V_CENTER 79 80 There are two other possibilities 81 \li \c B_FOLLOW_ALL_SIDES 82 \li \c B_FOLLOW_NONE 83 84 See BView for more information on resizing options. 85 \param flags The flags mask sets what notifications the BButton can receive. 86 \n\n Any combination of the following options is allowed 87 \li \c B_WILL_DRAW 88 \li \c B_PULSE_NEEDED 89 \li \c B_FRAME_EVENTS 90 \li \c B_FULL_UPDATE_ON_RESIZE 91 \li \c B_NAVIAGBLE 92 \li \c B_NAVIAGBLE_JUMP 93 \li \c B_SUBPIXEL_PRECISE 94 95 See BView for more information on \a flags. 96*/ 97 98 99/*! 100 \fn BButton::BButton(const char* name, const char* label, BMessage* message, 101 uint32 flags) 102 \brief Creates and initializes a BButton control. 103 104 BControl initializes the button's label and assigns it a message that 105 identifies the action that should be carried out when the button is 106 pressed. When the button is attached to a window it is resizes to the 107 height of the button's frame rectange to fit the button's border and 108 label in the button's font. 109 110 \param name The \a name of the button 111 \param label The button's \a label text 112 \param message The button's action \a message 113 \param flags The \a flags mask sets what notifications the button can 114 receive. Any combination of the following options is allowed: 115 \li \c B_WILL_DRAW 116 \li \c B_PULSE_NEEDED 117 \li \c B_FRAME_EVENTS 118 \li \c B_FULL_UPDATE_ON_RESIZE 119 \li \c B_NAVIAGBLE 120 \li \c B_NAVIAGBLE_JUMP 121 \li \c B_SUBPIXEL_PRECISE 122 123 See BView for more information on \a flags. 124*/ 125 126 127/*! 128 \fn BButton::BButton(const char* label, BMessage* message) 129 \brief Creates and initializes a BButton control. 130 131 Creates the button with the specified \a label. The action carried out 132 by the button is specified by the \a message. 133 134 \param label The button's \a label text 135 \param message The buttons action \a message 136*/ 137 138 139/*! 140 \fn BButton::~BButton() 141 \brief Destructor method. 142 143 Standard Destructor. 144*/ 145 146 147/*! \fn BButton::BButton(BMessage* archive) 148 \brief Constructs a BButton object from an \a archive message. 149 150 This method is usually not called directly. If you want to build a 151 button from a message you should call Instantiate() which can 152 handle errors properly. 153 154 If the \a archive deep, the BButton object will also unarchive each 155 of its child views recursively. 156 157 \param archive The \a archive message to restore from. 158*/ 159 160 161/*! 162 \fn void BButton::Draw(BRect updateRect) 163 \brief Draws the area of the button that intersects \a updateRect and 164 sets the label. 165 166 \note This is an hook method called by the Interface Kit, you don't 167 have to call it yourself. If you need to forcefully redraw the button 168 consider calling Invalidate() instead. 169 170 \param updateRect The rectangular area to be drawn. 171 172 \sa BView::Draw() 173*/ 174 175 176/*! 177 \fn void BButton::MakeDefault(bool flag) 178 \brief Make the BButton the default button i.e. it will be activated 179 when the user pushes the \key{Enter} key. 180 181 \param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned 182 by the Layout Kit. 183*/ 184 185 186/*! 187 \fn void BButton::SetLabel(const char *string) 188 \brief Sets the BButton's label. 189 190 \param string The string to set the label to. 191*/ 192 193 194/*! 195 \fn bool BButton::IsDefault() const 196 \brief Returns whether or not the BButton is the default button or not, i.e. 197 it responds to the \key{Enter} key. 198 199 \retval true The button is the default button. 200 \retval false The button is \b not the default button. 201*/ 202 203 204/*! 205 \fn void BButton::SetValue(int32 value) 206 \brief Sets the value of the BButton. 207 208 \note This method can be overridden in order to take a different action 209 when the value changes. 210 211 \param value The value to set to the BButton to. Options include: 212 \li \c 0 (\c B_CONTROL_OFF) 213 \li \c 1 (\c B_CONTROL_ON) 214 215 \see BControl::SetValue() 216*/ 217 218 219/*! 220 \fn void BButton::GetPreferredSize(float *_width, float *_height) 221 \brief Gets the dimensions that the BButton would prefer to be. 222 223 The size is computed from the children sizes, unless it was explicitly set 224 for the BButton (which can be done only if the BButton is configured to 225 use the Layout Kit). 226 227 \note Either the \a _width or \a _height parameter may be set to \c NULL 228 if you only want to get the other one. 229 230 \param[out] _width The width of the preferred size is placed in here. 231 \param[out] _height The height of the preferred size is placed in here. 232*/ 233 234 235/*! 236 \fn status_t BButton::Invoke(BMessage *message) 237 \brief The BButton is invoked from a message. 238 239 This method is used to post a message when the button is clicked or 240 activated by a keyboard button. You can set the object that will 241 handle the message by calling a BControl::SetTarget() from a 242 BInvoker inherited control. A model for the message is set by the 243 BButton constructor or by the BControl::SetMessage() method 244 inherited from BInvoker. 245 246 \returns B_OK If the BButton was invoked, otherwise an error 247 \a status_t flag is returned. 248 249 \see BControl::Invoke() 250*/ 251
