1/* 2 * Copyright 2011-2013 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/Control.h rev 42794 10 * src/kits/interface/Control.cpp rev 42794 11 */ 12 13 14/*! 15 \file Control.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BControl class definition and support enums. 19*/ 20 21 22/*! 23 \var B_CONTROL_ON 24 25 Control on. Value equal to 1. 26*/ 27 28 29/*! 30 \var B_CONTROL_OFF 31 32 Control off. Value equal to 0. 33*/ 34 35 36/*! 37 \class BControl 38 \ingroup interface 39 \ingroup libbe 40 \brief BControl is the base class for user-event handling objects. 41 42 Simple controls such as BCheckBox and BButton deviate only a bit from 43 BControl, whereas more complicated controls such as BColorControl and 44 BSlider re-implement much more functionality. Whether you are building 45 a simple control or something more complicated you should inherit from 46 BControl as it provides a common set of methods for intercepting 47 received messages from mouse and keyboard events. 48 49 Controls have state which they keep in their value. The value of a 50 control, stored as an int32, is read and set by the virtual Value() and 51 SetValue() methods. BControl defines \c B_CONTROL_ON and \c B_CONTROL_OFF 52 values that you can use as a convenience if your control has a simple 53 on/off state. If your BControl derived class stores a larger set of 54 states then you should define your own integer values instead. 55*/ 56 57 58/*! 59 \fn BControl::BControl(BRect frame, const char* name, const char* label, 60 BMessage* message, uint32 resizingMode, uint32 flags) 61 \brief Construct a control in the \a frame with a \a name, \a label, 62 model \a message, \a resizingMode, and creation \a flags. 63 64 The initial value of the control is set to 0 (\c B_CONTROL_OFF). 65 The \a label and the \a message parameters can be set to \c NULL. 66 67 \param frame The \a frame to draw the control in. 68 \param name The \a name of the control. 69 \param label The \a label displayed along with the control. 70 \param message The \a message to send when the control is activated. 71 \param resizingMode Defines the behavior of the control as the parent 72 view resizes, see BView for more details. 73 \param flags Behavior \a flags for the control, see BView for details. 74*/ 75 76 77/*! 78 \fn BControl::BControl(const char* name, const char* label, 79 BMessage* message, uint32 flags) 80 \brief Construct a control with a \a name, \a label, model \a message, 81 and creation \a flags suitable for use with the Layout API. 82 83 The initial value of the control is set to 0 (\c B_CONTROL_OFF). 84 The \a label and the \a message parameters can be set to \c NULL. 85 86 \note This method was not available in BeOS R5. 87 88 \param name The \a name of the control. 89 \param label The \a label displayed along with the control. 90 \param message The \a message to send when the control is activated. 91 \param flags Behavior \a flags for the control, see BView for details. 92*/ 93 94 95/*! 96 \fn BControl::~BControl() 97 \brief Frees all memory used by the BControl object including the memory 98 used by the model message. 99*/ 100 101 102/*! 103 \fn BControl::BControl(BMessage* archive) 104 \brief Creates a new BControl object from an \a archive message. 105 106 This method is usually not called directly. If you want to build a 107 control from a message you should call Instantiate() which can 108 handle errors properly. 109 110 If the \a archive deep, the BControl object will also unarchive each 111 of its child views recursively. 112 113 \param archive The \a archive message to restore from. 114*/ 115 116 117/*! 118 \fn BArchivable* BControl::Instantiate(BMessage* archive) 119 \brief Creates a new object from an \a archive. 120 121 If the message is a valid object then the instance created from the 122 passed in \a archive will be returned. Otherwise this method will 123 return \c NULL. 124 125 \param archive The \a archive message. 126 127 \returns An instance of the object if \a archive is valid or \c NULL. 128 129 \sa BArchivable::Instantiate() 130*/ 131 132 133/*! 134 \fn status_t BControl::Archive(BMessage* archive, bool deep) const 135 \brief Archives the control into \a archive. 136 137 \param archive The target \a archive that the data will go into. 138 \param deep Whether or not to recursively archive child views. 139 140 \retval B_OK The archive operation was successful. 141 \retval B_BAD_VALUE \c NULL \a archive message. 142 \retval B_ERROR The archive operation failed. 143 144 \sa BArchivable::Archive() 145*/ 146 147 148/*! 149 \fn void BControl::WindowActivated(bool active) 150 \brief Hook method called when the attached window is activated or 151 deactivated. 152 153 Redraws the focus ring around the menu field when the window is activated 154 or deactivated if it is the window's current focus view. 155 156 \param active \c true if the window becomes activated, \c false if the 157 window becomes deactivated. 158 159 \sa BView::WindowActivated() 160*/ 161 162 163/*! 164 \fn void BControl::AttachedToWindow() 165 \brief Hook method called when the control is attached to a window. 166 167 This method overrides BView::AttachedToWindow() setting the low color 168 and view color of the BControl so that it matches the view color of the 169 control's parent view. It also makes the attached window the default 170 target for Invoke() as long as another target has not already been set. 171 172 \sa BView::AttachedToWindow() 173 \sa Invoke() 174 \sa BInvoker::SetTarget() 175*/ 176 177 178/*! 179 \fn void BControl::DetachedFromWindow() 180 \brief Hook method called when the object is detached from a 181 window. 182 183 \sa BView::DetachedFromWindow() 184*/ 185 186 187/*! 188 \fn void BControl::AllAttached() 189 \brief Similar to AttachedToWindow() but this method is triggered after 190 all child views have already been attached to a window. 191 192 \sa BView::AllAttached() 193*/ 194 195 196/*! 197 \fn void BControl::AllDetached() 198 \brief Similar to AttachedToWindow() but this method is triggered after 199 all child views have already been detached from a window. 200 201 \sa BView::AllDetached() 202*/ 203 204 205/*! 206 \fn void BControl::MakeFocus(bool focused) 207 \brief Gives or removes focus from the control. 208 209 BControl::MakeFocus() overrides BView::MakeFocus() to call Draw() when 210 the focus changes. Derived classes generally don't have to re-implement 211 MakeFocus(). 212 213 IsFocusChanging() returns \c true when Draw() is called from this method. 214 215 \param focused \a true to set focus, \a false to remove it. 216 217 \sa BView::MakeFocus() 218 \sa IsFocusChanging() 219*/ 220 221 222/*! 223 \fn void BControl::KeyDown(const char *bytes, int32 numBytes) 224 \brief Hook method called when a keyboard key is pressed. 225 226 Overrides BView::KeyDown() to toggle the control value and then 227 calls Invoke() for \c B_SPACE or \c B_ENTER. If this is not desired 228 you should override this method in derived classes. 229 230 The KeyDown() method is only called if the BControl is the focus view 231 in the active window. If the window has a default button, \c B_ENTER 232 will be passed to that object instead of the focus view. 233 234 \param bytes The bytes of the key combination pressed. 235 \param numBytes The number of bytes in \a bytes. 236 237 \sa BView::KeyDown() 238 \sa MakeFocus() 239*/ 240 241 242/*! 243 \fn void BControl::MouseDown(BPoint point) 244 \brief Hook method called when a mouse button is pressed. 245 246 \param point The point on the screen where to mouse pointer is when 247 the mouse button is pressed. 248 249 \sa BView::MouseDown() 250*/ 251 252 253/*! 254 \fn void BControl::MouseUp(BPoint point) 255 \brief Hook method called when a mouse button is released. 256 257 \param point The point on the screen where to mouse pointer is when 258 the mouse button is released. 259 260 \sa BView::MouseUp() 261*/ 262 263 264/*! 265 \fn void BControl::MouseMoved(BPoint point, uint32 transit, 266 const BMessage *message) 267 \brief Hook method called when the mouse is moved. 268 269 \sa BView::MouseMoved() 270*/ 271 272 273/*! 274 \fn void BControl::SetLabel(const char *label) 275 \brief Sets the \a label of the control. 276 277 If the \a label changes the control is redrawn. 278 279 \param label The \a label to set, can be \c NULL. 280*/ 281 282 283/*! 284 \fn const char* BControl::Label() const 285 \brief Gets the label of the control. 286 287 \return The control's label. 288*/ 289 290 291/*! 292 \fn void BControl::SetValue(int32 value) 293 \brief Sets the value of the control. 294 295 If the \a value changes the control is redrawn. 296 297 \param value The \a value to set. 298 299 \sa SetValueNoUpdate() 300*/ 301 302 303/*! 304 \fn void BControl::SetValueNoUpdate(int32 value) 305 \brief Sets the value of the control without redrawing. 306 307 \note This method was not available in BeOS R5. 308 309 \param value The \a value to set. 310 311 \sa SetValue() 312*/ 313 314 315/*! 316 \fn int32 BControl::Value() const 317 \brief Gets the value of the control. 318 319 \return The control's value. 320*/ 321 322 323/*! 324 \fn void BControl::SetEnabled(bool enabled) 325 \brief Enables or disables the control. 326 327 BControl objects are enabled by default. If the control changes enabled 328 state then it is redrawn. 329 330 Disabled controls generally won't allow the user to focus on them 331 (The \c B_NAVIGABLE flag is turned off), and don't post any messages. 332 333 Disabled controls in derived classes should be drawn in subdued colors 334 to visually indicate that they are disabled and should not respond to 335 keyboard or mouse events. 336 337 \param enabled If \c true enables the control, if \c false, disables it. 338*/ 339 340 341/*! 342 \fn bool BControl::IsEnabled() const 343 \brief Gets whether or not the control is currently enabled. 344 345 \return \c true if the control is enabled, \c false if it is disabled. 346*/ 347 348 349/*! 350 \fn void BControl::GetPreferredSize(float *_width, float *_height) 351 \brief Fill out the preferred width and height of the control 352 into the \a _width and \a _height parameters. 353 354 Derived classes can override this method to set the preferred 355 width and height of the control. 356 357 \param _width Pointer to a \c float to hold the width of the control. 358 \param _height Pointer to a \c float to hold the height of the control. 359 360 \sa BView::GetPreferredSize() 361*/ 362 363 364/*! 365 \fn void BControl::ResizeToPreferred() 366 \brief Resize the control to its preferred size. 367 368 \sa BView::ResizeToPreferred() 369*/ 370 371 372/*! 373 \fn status_t BControl::Invoke(BMessage* message) 374 \brief Sends a copy of the model \a message to the designated target. 375 376 BControl::Invoke() overrides BInvoker::Invoke(). Derived classes 377 should use this method in their MouseDown() and KeyDown() methods 378 and should call IsEnabled() to check if the control is enabled 379 before calling Invoke(). 380 381 The following fields added to the BMessage: 382 - "when" \c B_INT64_TYPE system_time() 383 - "source" \c B_POINTER_TYPE A pointer to the BControl object. 384 385 \param message The \a message to send. 386 387 \sa BInvoker::Invoke() 388 \sa IsEnabled() 389*/ 390 391 392/*! 393 \fn BHandler* BControl::ResolveSpecifier(BMessage* message, int32 index, 394 BMessage* specifier, int32 what, const char* property) 395 \brief Determine the proper specifier for scripting messages. 396 397 \sa BHandler::ResolveSpecifier() 398*/ 399 400 401/*! 402 \fn status_t BControl::GetSupportedSuites(BMessage* message) 403 \brief Report the suites of understood messages. 404 405 \sa BHandler::GetSupportedSuites(); 406*/ 407 408 409/*! 410 \fn status_t BControl::Perform(perform_code code, void* _data) 411 \brief Perform some action. (Internal Method) 412 413 The following perform codes are recognized: 414 - \c PERFORM_CODE_MIN_SIZE 415 - \c PERFORM_CODE_MAX_SIZE 416 - \c PERFORM_CODE_PREFERRED_SIZE 417 - \c PERFORM_CODE_LAYOUT_ALIGNMENT 418 - \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH 419 - \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH 420 - \c PERFORM_CODE_SET_LAYOUT 421 - \c PERFORM_CODE_INVALIDATE_LAYOUT 422 - \c PERFORM_CODE_DO_LAYOUT 423 424 \param code The perform code. 425 \param _data A pointer to store some data. 426 427 \returns A status code. 428 429 \sa BHandler::Perform() 430*/ 431