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 \since BeOS R3 47*/ 48 49 50/*! 51 \fn BCheckBox::BCheckBox(BRect frame, const char* name, const char* label, 52 BMessage* message, uint32 resizingMode, uint32 flags) 53 \brief Construct a check box in the \a frame with a \a name, \a label, 54 model \a message, \a resizingMode, and creation \a flags. 55 56 \note This constructor will resize the control to its minimum height if needed 57 for compatibility with BeOS R5. 58 59 The initial value of the check box is 0 (\c B_CONTROL_OFF). 60 The \a label and the \a message parameters can be set to \c NULL. 61 62 \param frame The \a frame to draw the check box in. 63 \param name The \a name of the check box. 64 \param label The \a label displayed along with the check box control. 65 \param message The \a message to send when the check box is activated. 66 \param resizingMode Defines the behavior of the check box as the parent 67 view resizes. See BView for details. 68 \param flags Behavior \a flags for the check box. See BView for details. 69 70 \since BeOS R3 71*/ 72 73 74/*! 75 \fn BCheckBox::BCheckBox(const char* name, const char* label, 76 BMessage* message, uint32 flags) 77 \brief Construct a check box with a \a name, \a label, model \a message, 78 and creation \a flags suitable for use with the Layout API. 79 80 The initial value of the check box is 0 (\c B_CONTROL_OFF). 81 The \a label and the \a message parameters can be set to \c NULL. 82 83 \param name The \a name of the check box. 84 \param label The \a label displayed along with the check box control. 85 \param message The \a message to send when the check box is activated. 86 See BView for details. 87 \param flags Behavior \a flags for the check box. See BView for details. 88 89 \since Haiku R1 90*/ 91 92 93/*! 94 \fn BCheckBox::BCheckBox(const char* label, BMessage* message) 95 \brief Constructs a BCheckBox object with just a \a label and model 96 \a message. 97 98 The initial value of the check box is set to 0 (\c B_CONTROL_OFF). 99 The \a label and the \a message parameters can be set to \c NULL. 100 101 \param label The \a label displayed along with the check box. 102 \param message The \a message to send when the check box is activated. 103 104 \since Haiku R1 105*/ 106 107 108/*! 109 \fn BCheckBox::BCheckBox(BMessage* archive) 110 \brief Constructs a BCheckBox object from an \a archive message. 111 112 This method is usually not called directly, if you want to build a 113 check box from an archived message you should call Instantiate() instead 114 because it can handle errors properly. 115 116 \param archive The message to construct the BCheckBox object from. 117 118 \since BeOS R3 119*/ 120 121 122/*! 123 \fn BCheckBox::~BCheckBox() 124 \brief Destructor, does nothing. 125 126 \since BeOS R3 127*/ 128 129 130/*! 131 \name Archiving 132*/ 133 134 135//! @{ 136 137 138/*! 139 \fn BArchivable* BCheckBox::Instantiate(BMessage* archive) 140 \brief Creates a new BCheckBox object from the \a archive message. 141 142 \param archive The \a archive message to restore from. 143 144 \return A newly created check box or \c NULL if the message doesn't 145 contain an archived BCheckBox. 146 147 \since BeOS R3 148*/ 149 150 151/*! 152 \fn status_t BCheckBox::Archive(BMessage* data, bool deep) const 153 \brief Archives the object into the \a data message. 154 155 \copydetails BControl::Archive() 156*/ 157 158 159//! @} 160 161 162/*! 163 \name Hook Methods 164*/ 165 166 167//! @{ 168 169 170/*! 171 \fn void BCheckBox::AttachedToWindow() 172 \brief Hook method called when the control is attached to a window. 173 174 \copydetails BControl::AttachedToWindow() 175*/ 176 177 178/*! 179 \fn void BCheckBox::DetachedFromWindow() 180 \brief Hook method called when the control is detached from a window. 181 182 \copydetails BControl::DetachedFromWindow() 183*/ 184 185 186/*! 187 \fn void BCheckBox::AllAttached() 188 \brief Similar to AttachedToWindow() but this method is triggered after 189 all child views have already been attached to a window. 190 191 \copydetails BView::AllAttached() 192*/ 193 194 195/*! 196 \fn void BCheckBox::AllDetached() 197 \brief Similar to AttachedToWindow() but this method is triggered after 198 all child views have already been detached from a window. 199 200 \copydetails BView::AllDetached() 201*/ 202 203 204/*! 205 \fn void BCheckBox::Draw(BRect updateRect) 206 \brief Draws the area of the check box that intersects \a updateRect. 207 208 \note This is an hook method called by the Interface Kit, you don't 209 have to call it yourself. If you need to forcefully redraw a 210 check box consider calling Invalidate() instead. 211 212 \param updateRect The rectangular area to be drawn. 213 214 \sa BView::Draw() 215 216 \since BeOS R3 217*/ 218 219 220/*! 221 \fn void BCheckBox::FrameMoved(BPoint newPosition) 222 \brief Hook method called when the check box is moved. 223 224 \copydetails BView::FrameMoved() 225*/ 226 227 228/*! 229 \fn void BCheckBox::FrameResized(float newWidth, float newHeight) 230 \brief Hook method called when the check box is resized. 231 232 \copydetails BView::FrameResized() 233*/ 234 235 236/*! 237 \fn void BCheckBox::GetPreferredSize(float* _width, float* _height) 238 \brief Fill out the preferred width and height of the check box 239 into the \a _width and \a _height parameters. 240 241 \copydetails BView::GetPreferredSize() 242*/ 243 244 245/*! 246 \fn status_t BCheckBox::GetSupportedSuites(BMessage* message) 247 \brief Report the suites of messages this control understands. 248 249 \param message Allows you to add the names of the suites the check box 250 implements to the suites array. 251 252 \return \c B_OK if all went well or an error code otherwise. 253 254 \sa BControl::GetSupportedSuites(); 255 256 \since BeOS R3 257*/ 258 259 260/*! 261 \fn void BCheckBox::KeyDown(const char* bytes, int32 numBytes) 262 \brief Hook method called when a keyboard key is pressed. 263 264 Inverts the value on \a B_ENTER or \a B_SPACE. 265 266 \copydetails BControl::KeyDown() 267*/ 268 269 270/*! 271 \fn void BCheckBox::MessageReceived(BMessage* message) 272 \brief Handle \a message received by the associated looper. 273 274 \copydetails BControl::MessageReceived() 275*/ 276 277 278/*! 279 \fn void BCheckBox::MouseDown(BPoint where) 280 \brief Hook method called when a mouse button is pressed. 281 282 Begins tracking the mouse cursor. 283 284 \copydetails BControl::MouseDown() 285*/ 286 287 288/*! 289 \fn void BCheckBox::MouseMoved(BPoint where, uint32 code, 290 const BMessage* dragMessage) 291 \brief Hook method called when the mouse is moved. 292 293 Once MouseDown() has been called on a check box this method updates 294 the outline when the cursor is inside the control redrawing as necessary. 295 296 \copydetails BControl::MouseMoved() 297*/ 298 299 300/*! 301 \fn void BCheckBox::MouseUp(BPoint where) 302 \brief Hook method called when a mouse button is released. 303 304 Inverts the check box value. 305 306 \copydetails BControl::MouseUp() 307*/ 308 309 310 311/*! 312 \fn void BCheckBox::WindowActivated(bool active) 313 \brief Hook method called when the attached window is activated or 314 deactivated. 315 316 \copydetails BControl::WindowActivated() 317*/ 318 319 320//! @} 321 322 323/*! 324 \fn void BCheckBox::SetValue(int32 value) 325 \brief Turn the check box on or off. 326 327 \param value The value to set the check box to, should be 328 either \c B_CONTROL_ON or \c B_CONTROL_OFF. 329 330 \sa BControl::SetValue() 331 332 \since BeOS R3 333*/ 334 335 336/*! 337 \fn BHandler* BCheckBox::ResolveSpecifier(BMessage* message, int32 index, 338 BMessage* specifier, int32 what, const char* property) 339 \copydoc BHandler::ResolveSpecifier() 340*/ 341
