diff --git a/docs/user/interface/CheckBox.dox b/docs/user/interface/CheckBox.dox index 5c6f31f75b..6db5bc982a 100644 --- a/docs/user/interface/CheckBox.dox +++ b/docs/user/interface/CheckBox.dox @@ -1,5 +1,5 @@ /* - * Copyright 2011 Haiku Inc. All rights reserved. + * Copyright 2011-2014 Haiku Inc. All rights reserved. * Distributed under the terms of the MIT License. * * Authors: @@ -8,8 +8,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/interface/CheckBox.h rev 42794 - * src/kits/interface/CheckBox.cpp rev 42794 + * headers/os/interface/CheckBox.h hrev47274 + * src/kits/interface/CheckBox.cpp hrev47274 */ @@ -25,104 +25,187 @@ \class BCheckBox \ingroup interface \ingroup libbe - \brief BCheckBox is a user interface element used to make a binary - decision. + \brief A user interface element used to make a binary decision. - A BCheckBox object is used to draw a checkbox element. This simple control - has 2 states, \c B_CONTROL_OFF when the checkbox is unchecked and - \c B_CONTROL_ON when the checkbox is checked. A checkbox can also have a - descriptive label drawn to the right of the checkbox. + A BCheckBox is used to draw a check box UI control. This simple control + has 2 states, \c B_CONTROL_OFF when the check box is unchecked and + \c B_CONTROL_ON when the check box is checked. A check box can also have a + descriptive label drawn to the right of the check box. - When the checkbox is checked it has an X drawn inside of it. The checkbox + When the check box is checked it has an X drawn inside of it. The check box can be checked by a mouse click or by pushing \key{Space} on the - keyboard when the checkbox has focus. A checkbox object with focus - is surrounded by a blue border. A checkbox can also be set + keyboard when the check box has focus. A check box object with focus + is surrounded by a blue border. A check box can also be set programmatically by calling the SetValue() method. - A few checkbox examples can be seen below in unchecked state, checked - state, and another unchecked checkbox with focus on it. + A few check box examples can be seen below in unchecked state, checked + state, and another unchecked check box with focus on it. \image html BCheckBox_example.png */ /*! - \fn BCheckBox::BCheckBox(BRect frame, const char *name, const char *label, - BMessage *message, uint32 resizingMode, - uint32 flags) - \brief Construct a checkbox in the \a frame with a \a name, \a label, + \fn BCheckBox::BCheckBox(BRect frame, const char* name, const char* label, + BMessage* message, uint32 resizingMode, uint32 flags) + \brief Construct a check box in the \a frame with a \a name, \a label, model \a message, \a resizingMode, and creation \a flags. - The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF). + \note This constructor will resize the control to it's minimum height if needed + for compatibility with BeOS R5. + + The initial value of the check box is 0 (\c B_CONTROL_OFF). The \a label and the \a message parameters can be set to \c NULL. - \param frame The frame to draw the checkbox in. - \param name The name of the checkbox. - \param label The label displayed along with the checkbox. - \param message The message to send when the checkbox is activated. - \param resizingMode Defines the behavior of the checkbox as the parent - view resizes. - \param flags Behavior flags for the checkbox. See BView for details. + \param frame The \a frame to draw the check box in. + \param name The \a name of the check box. + \param label The \a label displayed along with the check box control. + \param message The \a message to send when the check box is activated. + \param resizingMode Defines the behavior of the check box as the parent + view resizes. See BView for details. + \param flags Behavior \a flags for the check box. See BView for details. */ /*! - \fn BCheckBox::BCheckBox(const char *name, const char *label, - BMessage *message, uint32 flags) - \brief Construct a checkbox with a \a name, \a label, model \a message, + \fn BCheckBox::BCheckBox(const char* name, const char* label, + BMessage* message, uint32 flags) + \brief Construct a check box with a \a name, \a label, model \a message, and creation \a flags suitable for use with the Layout API. - The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF). + The initial value of the check box is 0 (\c B_CONTROL_OFF). The \a label and the \a message parameters can be set to \c NULL. - \param name The name of the checkbox. - \param label The label displayed along with the checkbox. - \param message The message to send when the checkbox is activated. - \param flags Behavior flags for the checkbox. See BView for details. + \param name The \a name of the check box. + \param label The \a label displayed along with the check box control. + \param message The \a message to send when the check box is activated. + See BView for details. + \param flags Behavior \a flags for the check box. See BView for details. */ /*! - \fn BCheckBox::BCheckBox(const char *label, BMessage *message) + \fn BCheckBox::BCheckBox(const char* label, BMessage* message) \brief Constructs a BCheckBox object with just a \a label and model \a message. - The initial value of the checkbox is set to 0 (\c B_CONTROL_OFF). + The initial value of the check box is set to 0 (\c B_CONTROL_OFF). The \a label and the \a message parameters can be set to \c NULL. - \param label The label displayed along with the checkbox. - \param message The message to send when the checkbox is activated. + \param label The \a label displayed along with the check box. + \param message The \a message to send when the check box is activated. */ /*! - \fn BCheckBox::BCheckBox(BMessage *archive) + \fn BCheckBox::BCheckBox(BMessage* archive) \brief Constructs a BCheckBox object from an \a archive message. - This method is usually not called directly. If you want to build a - checkbox from a message you should call Instantiate() which can - handle errors properly. + This method is usually not called directly, if you want to build a + check box from an archived message you should call Instantiate() instead + because it can handle errors properly. - If the \a archive deep, the BCheckBox object will also unarchive each - of its child views recursively. - - \param archive The \a archive message to restore from. + \param archive The message to construct the BCheckBox object from. */ /*! \fn BCheckBox::~BCheckBox() - \brief Destructor Method. + \brief Destructor, does nothing. +*/ + + +/*! + \name Archiving +*/ + + +//! @{ + + +/*! + \fn BArchivable* BCheckBox::Instantiate(BMessage* archive) + \brief Creates a new BCheckBox object from the \a archive message. + + \return A newly created check box or \c NULL if the message doesn't + contain an archived BCheckBox. +*/ + + +/*! + \fn status_t BCheckBox::Archive(BMessage* data, bool deep) const + \brief Archives the object into the \a data message. + + \param data A pointer to the BMessage object to archive the object into. + \param deep Whether or not to archive child views as well. + + \return A status code, \c B_OK if everything went well or an error code + otherwise. + + \sa BControl::Archive() +*/ + + +//! @} + + +/*! + \name Hook Methods +*/ + + +//! @{ + + +/*! + \fn void BCheckBox::AttachedToWindow() + \brief Hook method called when the control is attached to a window. + + The default implementation does nothing. + + \sa BControl::AttachedToWindow() +*/ + + +/*! + \fn void BCheckBox::DetachedFromWindow() + \brief Hook method called when the control is detached from a window. + + The default implementation does nothing. + + \sa BControl::DetachedFromWindow() +*/ + + +/*! + \fn void BCheckBox::AllAttached() + \brief Similar to AttachedToWindow() but this method is triggered after + all child views have already been attached to a window. + + The default implementation does nothing. + + \sa BView::AllAttached() +*/ + + +/*! + \fn void BCheckBox::AllDetached() + \brief Similar to AttachedToWindow() but this method is triggered after + all child views have already been detached from a window. + + The default implementation does nothing. + + \sa BView::AllDetached() */ /*! \fn void BCheckBox::Draw(BRect updateRect) - \brief Draws the area of the checkbox that intersects \a updateRect. + \brief Draws the area of the check box that intersects \a updateRect. \note This is an hook method called by the Interface Kit, you don't - have to call it yourself. If you need to forcefully redraw the checkbox - consider calling Invalidate() instead. + have to call it yourself. If you need to forcefully redraw a + check box consider calling Invalidate() instead. \param updateRect The rectangular area to be drawn. @@ -131,22 +214,146 @@ /*! - \fn void BCheckBox::GetPreferredSize(float* _width, float* _height) - \brief Fill out the preferred width and height of the checkbox - into the \a _width and \a _height parameters. + \fn void BCheckBox::FrameMoved(BPoint newPosition) + \brief Hook method called when the check box is moved. - \param _width Pointer to a \c float to hold the width of the checkbox. - \param _height Pointer to a \c float to hold the height of the checkbox. + The default implementation does nothing. - \sa BView::GetPreferredSize() + \param newPosition The point that the check box has been moved to. + + \sa BView::FrameMoved() */ /*! - \fn void BCheckBox::SetValue(int32 value) - \brief Turn the checkbox on or off. + \fn void BCheckBox::FrameResized(float width, float height) + \brief Hook method called when the check box is resized. - \param value The value to set the checkbox to, should be + The default implementation does nothing. + + \param width The new \a width of the check box. + \param height The new \a height of the check box. + + \sa BView::FrameResized() +*/ + + +/*! + \fn void BCheckBox::GetPreferredSize(float* _width, float* _height) + \brief Fill out the preferred width and height of the check box + into the \a _width and \a _height parameters. + + \param[out] _width Pointer to a \c float to store the width. + \param[out] _height Pointer to a \c float to store the height. +*/ + + +/*! + \fn status_t BCheckBox::GetSupportedSuites(BMessage* message) + \brief Report the suites of messages this control understands. + + \param message Allows you to add the names of the suites the check box + implements to the suites array. + + \return \c B_OK if all went well or an error code otherwise. + + \sa BControl::GetSupportedSuites(); +*/ + + + +/*! + \fn void BCheckBox::KeyDown(const char* bytes, int32 numBytes) + \brief Hook method called when a keyboard key is pressed. + + Inverts the value on \a B_ENTER or \a B_SPACE. + + \param bytes The bytes of the key combination pressed. + \param numBytes The number of bytes in \a bytes. +*/ + + +/*! + \fn void BCheckBox::MessageReceived(BMessage* message) + \brief Handle \a message received by the associated looper. + + \param message The \a message received by the associated looper. + + \see BControl::MessageReceived() +*/ + + +/*! + \fn void BCheckBox::MouseDown(BPoint where) + \brief Hook method called when a mouse button is pressed. + + Begins tracking the mouse cursor. + + \param where The point on the screen where to mouse pointer is when + the mouse button is pressed. +*/ + + +/*! + \fn void BCheckBox::MouseMoved(BPoint where, uint32 code, + const BMessage* dragMessage) + \brief Hook method called when the mouse is moved. + + Once MouseDown() has been called on a check box this method updates + the outline when the cursor is inside the control redrawing as necessary. + + \param where The new location of the mouse in the control's coordinate system. + \param code One of the following: + - \c B_ENTERED_VIEW The cursor has just entered the control. + - \c B_INSIDE_VIEW The cursor is inside the control. + - \c B_EXITED_VIEW The cursor has left the control's bounds. This only gets + sent if the scope of the mouse events that the control can receive has + been expanded by BView::SetEventMask() or BView::SetMouseEventMask(). + - \c B_OUTSIDE_VIEW The cursor is outside the button. This only gets sent if + the scope of the mouse events that the control can receive has been + expanded by SetEventMask() or SetMouseEventMask(). + \param dragMessage If a drag-and-drop operation is taking place this is a + pointer to a BMessage that holds the drag information, otherwise the + pointer is \c NULL. +*/ + + +/*! + \fn void BCheckBox::MouseUp(BPoint where) + \brief Hook method called when a mouse button is released. + + Inverts the check box value. + + \param where The point on the screen where the mouse pointer is located when + the mouse button is released in the view's coordinate system. + + \sa BControl::MouseUp() +*/ + + + +/*! + \fn void BCheckBox::WindowActivated(bool active) + \brief Hook method called when the attached window is activated or + deactivated. + + The default implementation does nothing. + + \param active \c true if the window becomes activated, \c false if the + window becomes deactivated. + + \sa BControl::WindowActivated() +*/ + + +//! @} + + +/*! + \fn void BCheckBox::SetValue(int32 value) + \brief Turn the check box on or off. + + \param value The value to set the check box to, should be either \c B_CONTROL_ON or \c B_CONTROL_OFF. \sa BControl::SetValue()