docs/user/interface/Control.dox

   1 /*
   2  * Copyright 2011-2014 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   hrev47274
  10  *              src/kits/interface/Control.cpp   hrev47274
  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         \since BeOS R3
  28 */
  29
  30
  31 /*!
  32         \var B_CONTROL_OFF
  33
  34         Control off. Value equal to 0.
  35
  36         \since BeOS R3
  37 */
  38
  39
  40 /*!
  41         \class BControl
  42         \ingroup interface
  43         \ingroup libbe
  44         \brief BControl is the base class for user-event handling objects.
  45
  46         Simple controls such as BCheckBox and BButton deviate only a bit from
  47         BControl, whereas more complicated controls such as BColorControl and
  48         BSlider re-implement much more functionality. Whether you are building
  49         a simple control or something more complicated you should inherit from
  50         BControl as it provides a common set of methods for intercepting
  51         received messages from mouse and keyboard events.
  52
  53         Controls have state which they keep in their value. The value of a
  54         control, stored as an int32, is read and set by the virtual Value() and
  55         SetValue() methods. BControl defines \c B_CONTROL_ON and \c B_CONTROL_OFF
  56         values that you can use as a convenience if your control has a simple
  57         on/off state. If your BControl derived class stores a larger set of
  58         states then you should define your own integer values instead.
  59
  60         \since BeOS R3
  61 */
  62
  63
  64 /*!
  65         \fn BControl::BControl(BRect frame, const char* name, const char* label,
  66                 BMessage* message, uint32 resizingMode, uint32 flags)
  67         \brief Construct a control in the \a frame with a \a name, \a label,
  68                model \a message, \a resizingMode, and creation \a flags.
  69
  70         The initial value of the control is set to 0 (\c B_CONTROL_OFF).
  71         The \a label and the \a message parameters can be set to \c NULL.
  72
  73         \param frame The \a frame to draw the control in.
  74         \param name The \a name of the control.
  75         \param label The \a label displayed along with the control.
  76         \param message The \a message to send when the control is activated.
  77         \param resizingMode Defines the behavior of the control as the parent
  78                view resizes, see BView for more details.
  79         \param flags Behavior \a flags for the control, see BView for details.
  80
  81         \since BeOS R3
  82 */
  83
  84
  85 /*!
  86         \fn BControl::BControl(const char* name, const char* label,
  87                 BMessage* message, uint32 flags)
  88         \brief Construct a control with a \a name, \a label, model \a message,
  89                and creation \a flags suitable for use with the Layout API.
  90
  91         The initial value of the control is set to 0 (\c B_CONTROL_OFF).
  92         The \a label and the \a message parameters can be set to \c NULL.
  93
  94         \param name The \a name of the control.
  95         \param label The \a label displayed along with the control.
  96         \param message The \a message to send when the control is activated.
  97         \param flags Behavior \a flags for the control, see BView for details.
  98
  99         \since Haiku R1
 100 */
 101
 102
 103 /*!
 104         \fn BControl::~BControl()
 105         \brief Frees all memory used by the BControl object including the memory
 106                used by the model message.
 107
 108         \since BeOS R3
 109 */
 110
 111
 112 /*!
 113         \name Archiving
 114 */
 115
 116
 117 //! @{
 118
 119
 120 /*!
 121         \fn BControl::BControl(BMessage* data)
 122         \brief Creates a new BControl object from an \a data message.
 123
 124         This method is usually not called directly. If you want to build a
 125         control from a message you should call Instantiate() which can
 126         handle errors properly.
 127
 128         If the \a data deep, the BControl object will also undata each
 129         of its child views recursively.
 130
 131         \param data The \a data message to restore from.
 132
 133         \since BeOS R3
 134 */
 135
 136
 137 /*!
 138         \fn BArchivable* BControl::Instantiate(BMessage* data)
 139         \brief Creates a new object from an \a data.
 140
 141         If the message is a valid object then the instance created from the
 142         passed in \a data will be returned. Otherwise this method will
 143         return \c NULL.
 144
 145         \param data The \a data message.
 146
 147         \returns An instance of the object if \a data is valid or \c NULL.
 148
 149         \sa BArchivable::Instantiate()
 150
 151         \since BeOS R3
 152 */
 153
 154
 155 /*!
 156         \fn status_t BControl::Archive(BMessage* data, bool deep) const
 157         \brief Archives the control into \a data.
 158
 159         \param data The target \a data that the data will go into.
 160         \param deep Whether or not to recursively data child views.
 161
 162         \retval B_OK The data operation was successful.
 163         \retval B_BAD_VALUE \c NULL \a data message.
 164         \retval B_ERROR The archive operation failed.
 165
 166         \sa BArchivable::Archive()
 167
 168         \since BeOS R3
 169 */
 170
 171
 172 //! @}
 173
 174
 175 /*!
 176         \fn void BControl::WindowActivated(bool active)
 177         \brief Hook method called when the attached window is activated or
 178                deactivated.
 179
 180         Redraws the focus ring around the control when the window is activated
 181         or deactivated if it is the window's current focus view.
 182
 183         \param active \c true if the window becomes activated, \c false if the
 184                window becomes deactivated.
 185
 186         \sa BView::WindowActivated()
 187
 188         \since BeOS R3
 189 */
 190
 191
 192 /*!
 193         \fn void BControl::AttachedToWindow()
 194         \brief Hook method called when the control is attached to a window.
 195
 196         This method overrides BView::AttachedToWindow() setting the low color
 197         and view color of the BControl so that it matches the view color of the
 198         control's parent view. It also makes the attached window the default
 199         target for Invoke() as long as another target has not already been set.
 200
 201         \sa BView::AttachedToWindow()
 202         \sa Invoke()
 203         \sa BInvoker::SetTarget()
 204
 205         \since BeOS R3
 206 */
 207
 208
 209 /*!
 210         \fn void BControl::DetachedFromWindow()
 211         \brief Hook method called when the control is detached from a window.
 212
 213         \copydetails BView::DetachedFromWindow()
 214 */
 215
 216
 217 /*!
 218         \fn void BControl::AllAttached()
 219         \brief Similar to AttachedToWindow() but this method is triggered after
 220                all child views have already been detached from a window.
 221
 222         \copydetails BView::AllAttached()
 223 */
 224
 225
 226 /*!
 227         \fn void BControl::AllDetached()
 228         \brief Similar to AttachedToWindow() but this method is triggered after
 229                all child views have already been detached from a window.
 230
 231         \copydetails BView::AllDetached()
 232 */
 233
 234
 235 /*!
 236         \fn void BControl::MakeFocus(bool focus)
 237         \brief Gives or removes focus from the control.
 238
 239         BControl::MakeFocus() overrides BView::MakeFocus() to call Draw() when
 240         the focus changes. Derived classes generally don't have to re-implement
 241         MakeFocus().
 242
 243         IsFocusChanging() returns \c true when Draw() is called from this method.
 244
 245         \param focus \a true to set focus, \a false to remove it.
 246
 247         \sa BView::MakeFocus()
 248         \sa IsFocusChanging()
 249
 250         \since BeOS R3
 251 */
 252
 253
 254 /*!
 255         \fn void BControl::KeyDown(const char *bytes, int32 numBytes)
 256         \brief Hook method called when a keyboard key is pressed.
 257
 258         Overrides BView::KeyDown() to toggle the control value and then
 259         calls Invoke() for \c B_SPACE or \c B_ENTER. If this is not desired
 260         you should override this method in derived classes.
 261
 262         The KeyDown() method is only called if the BControl is the focus view
 263         in the active window. If the window has a default button, \c B_ENTER
 264         will be passed to that object instead of the focus view.
 265
 266         \param bytes The bytes of the key combination pressed.
 267         \param numBytes The number of bytes in \a bytes.
 268
 269         \sa BView::KeyDown()
 270         \sa MakeFocus()
 271
 272         \since BeOS R3
 273 */
 274
 275
 276 /*!
 277         \fn void BControl::MessageReceived(BMessage* message)
 278         \brief Handle \a message received by the associated looper.
 279
 280         \copydetails BView::MessageReceived()
 281 */
 282
 283
 284 /*!
 285         \fn void BControl::MouseDown(BPoint where)
 286         \brief Hook method called when a mouse button is pressed.
 287
 288         \copydetails BView::MouseDown()
 289 */
 290
 291
 292 /*!
 293         \fn void BControl::MouseMoved(BPoint where, uint32 code,
 294                 const BMessage* dragMessage)
 295         \brief Hook method called when the mouse is moved.
 296
 297         \copydetails BView::MouseMoved()
 298 */
 299
 300
 301 /*!
 302         \fn void BControl::MouseUp(BPoint where)
 303         \brief Hook method called when a mouse button is released.
 304
 305         \copydetails BView::MouseUp()
 306 */
 307
 308
 309
 310 /*!
 311         \fn void BControl::SetLabel(const char *label)
 312         \brief Sets the \a label of the control.
 313
 314         If the \a label changes the control is redrawn.
 315
 316         \param label The \a label to set, can be \c NULL.
 317
 318         \since BeOS R3
 319 */
 320
 321
 322 /*!
 323         \fn const char* BControl::Label() const
 324         \brief Gets the label of the control.
 325
 326         \return The control's label.
 327
 328         \since BeOS R3
 329 */
 330
 331
 332 /*!
 333         \fn void BControl::SetValue(int32 value)
 334         \brief Sets the value of the control.
 335
 336         If the \a value changes the control is redrawn.
 337
 338         \param value The \a value to set.
 339
 340         \sa SetValueNoUpdate()
 341
 342         \since BeOS R3
 343 */
 344
 345
 346 /*!
 347         \fn void BControl::SetValueNoUpdate(int32 value)
 348         \brief Sets the value of the control without redrawing.
 349
 350         \param value The \a value to set.
 351
 352         \sa SetValue()
 353
 354         \since Haiku R1
 355 */
 356
 357
 358 /*!
 359         \fn int32 BControl::Value() const
 360         \brief Gets the value of the control.
 361
 362         \return The control's value.
 363
 364         \since BeOS R3
 365 */
 366
 367
 368 /*!
 369         \fn void BControl::SetEnabled(bool enabled)
 370         \brief Enables or disables the control.
 371
 372         BControl objects are enabled by default. If the control changes enabled
 373         state then it is redrawn.
 374
 375         Disabled controls generally won't allow the user to focus on them
 376         (The \c B_NAVIGABLE flag is turned off), and don't post any messages.
 377
 378         Disabled controls in derived classes should be drawn in subdued colors
 379         to visually indicate that they are disabled and should not respond to
 380         keyboard or mouse events.
 381
 382         \param enabled If \c true enables the control, if \c false, disables it.
 383
 384         \since BeOS R3
 385 */
 386
 387
 388 /*!
 389         \fn bool BControl::IsEnabled() const
 390         \brief Gets whether or not the control is currently enabled.
 391
 392         \return \c true if the control is enabled, \c false if it is disabled.
 393
 394         \since BeOS R3
 395 */
 396
 397
 398 /*!
 399         \fn void BControl::GetPreferredSize(float *_width, float *_height)
 400         \brief Fill out the preferred width and height of the control
 401                 into the \a _width and \a _height parameters.
 402
 403         Derived classes can override this method to set the preferred
 404         width and height of the control.
 405
 406         \param[out] _width Pointer to a \c float to hold the width of the control.
 407         \param[out] _height Pointer to a \c float to hold the height of the control.
 408
 409         \sa BView::GetPreferredSize()
 410
 411         \since BeOS R3
 412 */
 413
 414
 415 /*!
 416         \fn void BControl::ResizeToPreferred()
 417         \brief Resize the control to its preferred size.
 418
 419         \sa BView::ResizeToPreferred()
 420
 421         \since BeOS R3
 422 */
 423
 424
 425 /*!
 426         \fn status_t BControl::Invoke(BMessage* message)
 427         \brief Sends a copy of the model \a message to the designated target.
 428
 429         BControl::Invoke() overrides BInvoker::Invoke(). Derived classes
 430         should use this method in their MouseDown() and KeyDown() methods
 431         and should call IsEnabled() to check if the control is enabled
 432         before calling Invoke().
 433
 434         The following fields added to the BMessage:
 435                 - "when"        \c B_INT64_TYPE system_time()
 436                 - "source"      \c B_POINTER_TYPE       A pointer to the BControl object.
 437
 438         \param message The \a message to send.
 439
 440         \return \c B_OK if the control was invoked, otherwise an error
 441                 code is returned.
 442
 443         \sa BInvoker::Invoke()
 444         \sa IsEnabled()
 445
 446         \since BeOS R3
 447 */
 448
 449
 450 /*!
 451         \fn BHandler* BControl::ResolveSpecifier(BMessage* message, int32 index,
 452                 BMessage* specifier, int32 what, const char* property)
 453         \copydoc BHandler::ResolveSpecifier()
 454 */
 455
 456
 457 /*!
 458         \fn status_t BControl::GetSupportedSuites(BMessage* message)
 459         \brief Report the suites of messages this control understands.
 460
 461         Adds the string "suite/vnd.Be-control" to the message.
 462
 463         \copydetails BHandler::GetSupportedSuites()
 464 */
 465
 466
 467 /*!
 468         \fn status_t BControl::Perform(perform_code code, void* _data)
 469         \copydoc BView::Perform()
 470 */
 471
 472
 473 /*!
 474         \fn status_t BControl::SetIcon(const BBitmap* icon, uint32 flags)
 475         \brief This convenience method is used to set the bitmaps
 476                for the standard states from a single bitmap.
 477
 478         It also supports cropping the icon to its non-transparent area.
 479         The icon is meant as an addition to or replacement of the label.
 480
 481         \param icon The \a icon to set.
 482         \param flags Modify how the icon is set.
 483         - \c B_TRIM_ICON_BITMAP Crop the bitmap to the not fully transparent
 484              area, may change the icon size.
 485         - \c B_TRIM_ICON_BITMAP_KEEP_ASPECT Like \c B_TRIM_BITMAP, but keeps
 486              the aspect ratio.
 487         - \c B_CREATE_ACTIVE_ICON_BITMAP
 488         - \c B_CREATE_PARTIALLY_ACTIVE_ICON_BITMAP
 489         - \c B_CREATE_DISABLED_ICON_BITMAPS
 490
 491         \return \c B_OK if the icon was set or an error code otherwise.
 492
 493         \since Haiku R1
 494 */
 495
 496
 497 /*!
 498         \fn status_t BControl::SetIconBitmap(const BBitmap* bitmap,
 499                 uint32 which, uint32 flags)
 500         \brief Icon bitmaps for various states of the control (off, on,
 501                partially on, each enabled or disabled, plus up to 125
 502                custom states) can be set individually.
 503
 504         \param bitmap The \a bitmap icon to set.
 505         \param which The state to set the icon for.
 506         \param flags Modify how the icon is set.
 507                 - \c B_KEEP_ICON_BITMAP Transfer ownership of the bitmap to the control.
 508
 509         \return \c B_OK if the icon was set or an error code otherwise.
 510
 511         \since Haiku R1
 512 */