1/* 2 * Copyright 2011-2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Stephan Aßmus, superstippi@gmx.de 7 * Marc Flerackers, mflerackers@androme.be 8 * John Scipione, jscipione@gmail.com 9 * 10 * Corresponds to: 11 * headers/os/interface/CheckBox.h hrev47274 12 * src/kits/interface/CheckBox.cpp hrev47274 13 */ 14 15 16/*! 17 \file CheckBox.h 18 \ingroup interface 19 \ingroup libbe 20 \brief Defines the BCheckBox class 21*/ 22 23 24/*! 25 \class BCheckBox 26 \ingroup interface 27 \ingroup libbe 28 \brief A user interface element used to make a binary decision. 29 30 A BCheckBox is used to draw a check box UI control. This simple control 31 has 2 states, \c B_CONTROL_OFF when the check box is unchecked and 32 \c B_CONTROL_ON when the check box is checked. A check box can also have a 33 descriptive label drawn to the right of the check box. 34 35 When the check box is checked it has an X drawn inside of it. The check box 36 can be checked by a mouse click or by pushing \key{Space} on the 37 keyboard when the check box has focus. A check box object with focus 38 is surrounded by a blue border. A check box can also be set 39 programmatically by calling the SetValue() method. 40 41 A few check box examples can be seen below in unchecked state, checked 42 state, and another unchecked check box with focus on it. 43 44 \image html BCheckBox_example.png 45*/ 46 47 48/*! 49 \fn BCheckBox::BCheckBox(BRect frame, const char* name, const char* label, 50 BMessage* message, uint32 resizingMode, uint32 flags) 51 \brief Construct a check box in the \a frame with a \a name, \a label, 52 model \a message, \a resizingMode, and creation \a flags. 53 54 \note This constructor will resize the control to it's minimum height if needed 55 for compatibility with BeOS R5. 56 57 The initial value of the check box is 0 (\c B_CONTROL_OFF). 58 The \a label and the \a message parameters can be set to \c NULL. 59 60 \param frame The \a frame to draw the check box in. 61 \param name The \a name of the check box. 62 \param label The \a label displayed along with the check box control. 63 \param message The \a message to send when the check box is activated. 64 \param resizingMode Defines the behavior of the check box as the parent 65 view resizes. See BView for details. 66 \param flags Behavior \a flags for the check box. See BView for details. 67*/ 68 69 70/*! 71 \fn BCheckBox::BCheckBox(const char* name, const char* label, 72 BMessage* message, uint32 flags) 73 \brief Construct a check box with a \a name, \a label, model \a message, 74 and creation \a flags suitable for use with the Layout API. 75 76 The initial value of the check box is 0 (\c B_CONTROL_OFF). 77 The \a label and the \a message parameters can be set to \c NULL. 78 79 \param name The \a name of the check box. 80 \param label The \a label displayed along with the check box control. 81 \param message The \a message to send when the check box is activated. 82 See BView for details. 83 \param flags Behavior \a flags for the check box. See BView for details. 84*/ 85 86 87/*! 88 \fn BCheckBox::BCheckBox(const char* label, BMessage* message) 89 \brief Constructs a BCheckBox object with just a \a label and model 90 \a message. 91 92 The initial value of the check box is set to 0 (\c B_CONTROL_OFF). 93 The \a label and the \a message parameters can be set to \c NULL. 94 95 \param label The \a label displayed along with the check box. 96 \param message The \a message to send when the check box is activated. 97*/ 98 99 100/*! 101 \fn BCheckBox::BCheckBox(BMessage* archive) 102 \brief Constructs a BCheckBox object from an \a archive message. 103 104 This method is usually not called directly, if you want to build a 105 check box from an archived message you should call Instantiate() instead 106 because it can handle errors properly. 107 108 \param archive The message to construct the BCheckBox object from. 109*/ 110 111 112/*! 113 \fn BCheckBox::~BCheckBox() 114 \brief Destructor, does nothing. 115*/ 116 117 118/*! 119 \name Archiving 120*/ 121 122 123//! @{ 124 125 126/*! 127 \fn BArchivable* BCheckBox::Instantiate(BMessage* archive) 128 \brief Creates a new BCheckBox object from the \a archive message. 129 130 \return A newly created check box or \c NULL if the message doesn't 131 contain an archived BCheckBox. 132*/ 133 134 135/*! 136 \fn status_t BCheckBox::Archive(BMessage* data, bool deep) const 137 \brief Archives the object into the \a data message. 138 139 \param data A pointer to the BMessage object to archive the object into. 140 \param deep Whether or not to archive child views as well. 141 142 \return A status code, \c B_OK if everything went well or an error code 143 otherwise. 144 145 \sa BControl::Archive() 146*/ 147 148 149//! @} 150 151 152/*! 153 \name Hook Methods 154*/ 155 156 157//! @{ 158 159 160/*! 161 \fn void BCheckBox::AttachedToWindow() 162 \brief Hook method called when the control is attached to a window. 163 164 The default implementation does nothing. 165 166 \sa BControl::AttachedToWindow() 167*/ 168 169 170/*! 171 \fn void BCheckBox::DetachedFromWindow() 172 \brief Hook method called when the control is detached from a window. 173 174 The default implementation does nothing. 175 176 \sa BControl::DetachedFromWindow() 177*/ 178 179 180/*! 181 \fn void BCheckBox::AllAttached() 182 \brief Similar to AttachedToWindow() but this method is triggered after 183 all child views have already been attached to a window. 184 185 The default implementation does nothing. 186 187 \sa BView::AllAttached() 188*/ 189 190 191/*! 192 \fn void BCheckBox::AllDetached() 193 \brief Similar to AttachedToWindow() but this method is triggered after 194 all child views have already been detached from a window. 195 196 The default implementation does nothing. 197 198 \sa BView::AllDetached() 199*/ 200 201 202/*! 203 \fn void BCheckBox::Draw(BRect updateRect) 204 \brief Draws the area of the check box that intersects \a updateRect. 205 206 \note This is an hook method called by the Interface Kit, you don't 207 have to call it yourself. If you need to forcefully redraw a 208 check box consider calling Invalidate() instead. 209 210 \param updateRect The rectangular area to be drawn. 211 212 \sa BView::Draw() 213*/ 214 215 216/*! 217 \fn void BCheckBox::FrameMoved(BPoint newPosition) 218 \brief Hook method called when the check box is moved. 219 220 The default implementation does nothing. 221 222 \param newPosition The point that the check box has been moved to. 223 224 \sa BView::FrameMoved() 225*/ 226 227 228/*! 229 \fn void BCheckBox::FrameResized(float width, float height) 230 \brief Hook method called when the check box is resized. 231 232 The default implementation does nothing. 233 234 \param width The new \a width of the check box. 235 \param height The new \a height of the check box. 236 237 \sa BView::FrameResized() 238*/ 239 240 241/*! 242 \fn void BCheckBox::GetPreferredSize(float* _width, float* _height) 243 \brief Fill out the preferred width and height of the check box 244 into the \a _width and \a _height parameters. 245 246 \param[out] _width Pointer to a \c float to store the width. 247 \param[out] _height Pointer to a \c float to store the height. 248*/ 249 250 251/*! 252 \fn status_t BCheckBox::GetSupportedSuites(BMessage* message) 253 \brief Report the suites of messages this control understands. 254 255 \param message Allows you to add the names of the suites the check box 256 implements to the suites array. 257 258 \return \c B_OK if all went well or an error code otherwise. 259 260 \sa BControl::GetSupportedSuites(); 261*/ 262 263 264 265/*! 266 \fn void BCheckBox::KeyDown(const char* bytes, int32 numBytes) 267 \brief Hook method called when a keyboard key is pressed. 268 269 Inverts the value on \a B_ENTER or \a B_SPACE. 270 271 \param bytes The bytes of the key combination pressed. 272 \param numBytes The number of bytes in \a bytes. 273*/ 274 275 276/*! 277 \fn void BCheckBox::MessageReceived(BMessage* message) 278 \brief Handle \a message received by the associated looper. 279 280 \param message The \a message received by the associated looper. 281 282 \see BControl::MessageReceived() 283*/ 284 285 286/*! 287 \fn void BCheckBox::MouseDown(BPoint where) 288 \brief Hook method called when a mouse button is pressed. 289 290 Begins tracking the mouse cursor. 291 292 \param where The point on the screen where to mouse pointer is when 293 the mouse button is pressed. 294*/ 295 296 297/*! 298 \fn void BCheckBox::MouseMoved(BPoint where, uint32 code, 299 const BMessage* dragMessage) 300 \brief Hook method called when the mouse is moved. 301 302 Once MouseDown() has been called on a check box this method updates 303 the outline when the cursor is inside the control redrawing as necessary. 304 305 \param where The new location of the mouse in the control's coordinate system. 306 \param code One of the following: 307 - \c B_ENTERED_VIEW The cursor has just entered the control. 308 - \c B_INSIDE_VIEW The cursor is inside the control. 309 - \c B_EXITED_VIEW The cursor has left the control's bounds. This only gets 310 sent if the scope of the mouse events that the control can receive has 311 been expanded by BView::SetEventMask() or BView::SetMouseEventMask(). 312 - \c B_OUTSIDE_VIEW The cursor is outside the button. This only gets sent if 313 the scope of the mouse events that the control can receive has been 314 expanded by SetEventMask() or SetMouseEventMask(). 315 \param dragMessage If a drag-and-drop operation is taking place this is a 316 pointer to a BMessage that holds the drag information, otherwise the 317 pointer is \c NULL. 318*/ 319 320 321/*! 322 \fn void BCheckBox::MouseUp(BPoint where) 323 \brief Hook method called when a mouse button is released. 324 325 Inverts the check box value. 326 327 \param where The point on the screen where the mouse pointer is located when 328 the mouse button is released in the view's coordinate system. 329 330 \sa BControl::MouseUp() 331*/ 332 333 334 335/*! 336 \fn void BCheckBox::WindowActivated(bool active) 337 \brief Hook method called when the attached window is activated or 338 deactivated. 339 340 The default implementation does nothing. 341 342 \param active \c true if the window becomes activated, \c false if the 343 window becomes deactivated. 344 345 \sa BControl::WindowActivated() 346*/ 347 348 349//! @} 350 351 352/*! 353 \fn void BCheckBox::SetValue(int32 value) 354 \brief Turn the check box on or off. 355 356 \param value The value to set the check box to, should be 357 either \c B_CONTROL_ON or \c B_CONTROL_OFF. 358 359 \sa BControl::SetValue() 360*/ 361
