From b03e8ffe7fd1ed4cd59ca23e69798e666f39b5be Mon Sep 17 00:00:00 2001 From: John Scipione Date: Wed, 28 May 2014 14:19:44 -0400 Subject: [PATCH] Update BButton docs. Document some old missing methods, but more importantly document the new methods added by Ingo recently. --- docs/user/interface/Button.dox | 595 ++++++++++++++++++++++++++------- 1 file changed, 469 insertions(+), 126 deletions(-) diff --git a/docs/user/interface/Button.dox b/docs/user/interface/Button.dox index 55587df63e..4c9bca0c40 100644 --- a/docs/user/interface/Button.dox +++ b/docs/user/interface/Button.dox @@ -6,8 +6,8 @@ * John Scipione, jscipione@gmail.com * * Corresponds to: - * headers/os/interface/Button.h rev 42794 - * src/kits/interface/Button.cpp rev 42794 + * headers/os/interface/Button.h hrev47274 + * src/kits/interface/Button.cpp hrev47273 /*! @@ -22,21 +22,28 @@ \class BButton Button.h \ingroup interface \ingroup libbe - \brief A BButton is a labeled on-screen button. + \brief A control used to initiate an action. - A BButton control is used to initiate an action. An action is activated - by clicking on the button with the mouse or by a keyboard button. - If the BButton is the default button for the active window then you can - activate it by pushing the Enter key. + An action is activated by clicking on the button with the mouse + or by a keyboard button. If the button is the default button for + the active window then you can activate it by pushing the + Enter key. \image html BButton_example.png - A BButton, unlike other user interface elements such as check boxes and - radio buttons has only a single state. During a click event the - BButton's value is set to 1, (\c B_CONTROL_ON) otherwise this value - is 0 (\c B_CONTROL_OFF). + The behavior of a button depends on its behavior. The normal behavior + of a button is to set the value to 1 (\c B_CONTROL_ON) only when the + button is activated, otherwise the value is 0 (\c B_CONTROL_OFF). + Setting a button to use \c B_TOGGLE_BEHAVIOR makes the button behave + like a checkbox so that each time the button is activate the value + toggles between \c B_CONTROL_OFF and \c B_CONTROL_ON. The third + behavior to use is \c B_POP_UP_BEHAVIOR which adds a pop-up marker + to the button similar to that of BMenuField. - BButton inherits from the BControl class. + A button may have either a text label, an icon, or both. The button's + label is set in the constructor or by the SetLabel() method. To set the + icon for a button use the SetIcon() method. The text label will draw + to the right of the icon. */ @@ -59,40 +66,13 @@ passed up the inheritance chain to the BView class. \param frame The frame rectangle that the button is draw into. - \param name The name of the button - \param label The button label text - \param message The BButtons's action message + \param name The name of the button. Can be \c NULL. + \param label The button label text. Can be \c NULL. + \param message The BButtons's action message. Can be \c NULL. \param resizingMode Mask sets the parameters by which the BButton can be - resized. It should be set to one option for vertical resizing combined - with one option for horizontal resizing. - \n\n Horizontal resizing options are - \li \c B_FOLLOW_LEFT - \li \c B_FOLLOW_RIGHT - \li \c B_FOLLOW_LEFT_RIGHT - \li \c B_FOLLOW_H_CENTER - - Vertical resizing options are - \li \c B_FOLLOW_TOP - \li \c B_FOLLOW_BOTTOM - \li \c B_FOLLOW_TOP_BOTTOM - \li \c B_FOLLOW_V_CENTER - - There are two other possibilities - \li \c B_FOLLOW_ALL_SIDES - \li \c B_FOLLOW_NONE - - See BView for more information on resizing options. - \param flags The flags mask sets what notifications the BButton can receive. - \n\n Any combination of the following options is allowed - \li \c B_WILL_DRAW - \li \c B_PULSE_NEEDED - \li \c B_FRAME_EVENTS - \li \c B_FULL_UPDATE_ON_RESIZE - \li \c B_NAVIAGBLE - \li \c B_NAVIAGBLE_JUMP - \li \c B_SUBPIXEL_PRECISE - - See BView for more information on \a flags. + resized. See BView for more information on resizing options. + \param flags The \a flags mask sets what notifications the BButton can + receive. See BView for more information on \a flags. */ @@ -107,20 +87,11 @@ height of the button's frame rectange to fit the button's border and label in the button's font. - \param name The \a name of the button - \param label The button's \a label text - \param message The button's action \a message + \param name The \a name of the button. Can be \c NULL. + \param label The button's \a label text. Can be \c NULL. + \param message The button's action \a message. Can be \c NULL. \param flags The \a flags mask sets what notifications the button can - receive. Any combination of the following options is allowed: - \li \c B_WILL_DRAW - \li \c B_PULSE_NEEDED - \li \c B_FRAME_EVENTS - \li \c B_FULL_UPDATE_ON_RESIZE - \li \c B_NAVIAGBLE - \li \c B_NAVIAGBLE_JUMP - \li \c B_SUBPIXEL_PRECISE - - See BView for more information on \a flags. + receive. See BView for more information on \a flags. */ @@ -131,30 +102,113 @@ Creates the button with the specified \a label. The action carried out by the button is specified by the \a message. - \param label The button's \a label text - \param message The buttons action \a message + \param label The button's \a label text. Can be \c NULL. + \param message The buttons action \a message. Can be \c NULL. */ -/*! - \fn BButton::~BButton() - \brief Destructor method. - - Standard Destructor. -*/ - - -/*! \fn BButton::BButton(BMessage* archive) - \brief Constructs a BButton object from an \a archive message. +/*! \fn BButton::BButton(BMessage* data) + \brief Constructs a BButton object from an \a data message. This method is usually not called directly. If you want to build a button from a message you should call Instantiate() which can handle errors properly. - If the \a archive deep, the BButton object will also unarchive each + If the \a data deep, the BButton object will also unarchive each of its child views recursively. - \param archive The \a archive message to restore from. + \param data The \a data message to restore from. +*/ + + +/*! + \fn BButton::~BButton() + \brief Destructor, does nothing. +*/ + + +/*! + \name Archiving +*/ + + +//! @{ + + +/*! + \fn BArchivable* BButton::Instantiate(BMessage* archive) + \brief Creates a new BButton object from the \a archive message. + + \return A newly created check box or \c NULL if the message doesn't + contain an archived BButton. +*/ + + +/*! + \fn status_t BButton::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 BButton::AttachedToWindow() + \brief Hook method called when the button is attached to a window. + + The view color is set to \c B_TRANSPARENT_COLOR. If the button is + the default button the window's default button is updated. + + \sa BControl::AttachedToWindow() +*/ + + +/*! + \fn void BButton::DetachedFromWindow() + \brief Hook method called when the button is detached from a window. + + The default implementation does nothing. + + \sa BControl::DetachedFromWindow() +*/ + + +/*! + \fn void BButton::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 BButton::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() */ @@ -164,8 +218,8 @@ sets the label. \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 button - consider calling Invalidate() instead. + have to call it yourself. If you need to forcefully redraw the + button consider calling Invalidate() instead. \param updateRect The rectangular area to be drawn. @@ -174,77 +228,366 @@ /*! - \fn void BButton::MakeDefault(bool flag) - \brief Make the BButton the default button i.e. it will be activated - when the user pushes the \key{Enter} key. - - \param flag Pass in \c B_SUPPORTS_LAYOUT if the BButton is positioned - by the Layout Kit. + \fn void BButton::FrameMoved(BPoint newPosition) + \brief Hook method called when the button is moved. + + The default implementation does nothing. + + \param newPosition The point that the button has been moved to. + + \sa BView::FrameMoved() */ /*! - \fn void BButton::SetLabel(const char *string) - \brief Sets the BButton's label. - - \param string The string to set the label to. + \fn void BButton::FrameResized(float width, float height) + \brief Hook method called when the button is resized. + + The default implementation does nothing. + + \param width The new \a width of the button. + \param height The new \a height of the button. + + \sa BView::FrameResized() +*/ + + +/*! + \fn void BButton::KeyDown(const char* bytes, int32 numBytes) + \brief Hook method called when a keyboard key is pressed. + + Invokes the button 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 BButton::LayoutInvalidated(bool descendants) + \brief Hook method called when the layout is invalidated. + + Invalidate cached preferred size. + + \note This method was not available in BeOS R5. + + \param descendants Whether or not child views have also been invalidated. +*/ + + +/*! + \fn void BButton::MessageReceived(BMessage* message) + \brief Handle \a message received by the associated looper. + + The default implemenation does nothing. + + \param message The \a message received by the associated looper. + + \see BControl::MessageReceived() +*/ + + +/*! + \fn void BButton::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 BButton::MouseMoved(BPoint where, uint32 code, + const BMessage* dragMessage) + \brief Hook method called when the mouse is moved. + + Once MouseDown() has been called this method updates the button's value + if the mouse cursor is inside the button. The value that is set depends on + if the button is using \c B_TOGGLE_BEHAVIOR or not. + + \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 button. + - \c B_INSIDE_VIEW The cursor is inside the button. + - \c B_EXITED_VIEW The cursor has left the button's bounds. This only gets + sent if the scope of the mouse events that the button 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 BButton::MouseUp(BPoint where) + \brief Hook method called when a mouse button is released. + + Set the value of the button if MouseDown() was previously called on the + button. The value that is set depends on if the button is using + \c B_TOGGLE_BEHAVIOR or not. + + \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. +*/ + + +/*! + \fn void BButton::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 BButton::GetPreferredSize(float* _width, float* _height) + \brief Fill out the preferred width and height of the button + into the \a _width and \a _height parameters. + + The size is computed from the children sizes, unless it was explicitly set + for the BButton, which can be done only if the BButton is configured to + use the Layout APIs. + + \note Either the \a _width or \a _height parameter may be set to \c NULL + if you only want to get the other one. + + \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 BButton::GetSupportedSuites(BMessage* message) + \brief Report the suites of messages this control understands. + + \param message Allows you to add the names of the suites the button + implements to the suites array. + + \return \c B_OK if all went well or an error code otherwise. + + \sa BControl::GetSupportedSuites(); +*/ + + +/*! + \fn status_t BButton::Invoke(BMessage* message) + \brief Sends a copy of the model \a message to the designated target. + + \param message The \a message to send. + + \return \c B_OK if the button was invoked, otherwise an error + code is returned. + + \sa BControl::Invoke() +*/ + + +/*! + \fn void BButton::MakeDefault(bool flag) + \brief Make the BButton the default button i.e. it will be activated + when the user pushes the \key{Enter} key. + + A window can have only one default button at a time. + + \param flag \c true to make the button the default button, \c false + to remove the default button status. + + \sa BWindow::SetDefaultButton() +*/ + + +/*! + \fn void BButton::MakeFocus(bool focused) + \brief Makes the button the current focus view of the window or + gives up being the window's focus view. + + The default implementation does nothing. + + \param focused \a true to set focus, \a false to remove it. + + \sa BControl::MakeFocus() +*/ + + +/*! + \fn BSize BButton::MinSize() + \brief Returns the button's minimum size. + + \note This method was not available in BeOS R5. + + \return The button's minimum size as a BSize. +*/ + + +/*! + \fn BSize BButton::MaxSize() + \brief Returns the button's maximum size. + + \note This method was not available in BeOS R5. + + \return The button's maximum size as a BSize. +*/ + + +/*! + \fn BSize BButton::PreferredSize() + \brief Returns the button's preferred size. + + \note This method was not available in BeOS R5. + + \return The button's preferred size as a BSize. +*/ + + +/*! + \fn status_t BButton::Perform(perform_code code, void* _data) + \brief Perform some action. (Internal Method) +*/ + + +/*! + \fn void BButton::ResizeToPreferred() + \brief Resize the button to its preferred size. + + \sa BView::ResizeToPreferred() +*/ + + +/*! + \fn BHandler* BButton::ResolveSpecifier(BMessage* message, + int32 index, BMessage* specifier, int32 what, const char* property) + \brief Determine the proper specifier for scripting messages. + + The default implementation does nothing. + + \sa BControl::ResolveSpecifier() +*/ + + +/*! + \fn void BButton::SetLabel(const char* label) + \brief Sets the button's label. + + \param label The string to set the label to. */ /*! \fn bool BButton::IsDefault() const - \brief Returns whether or not the BButton is the default button or not, i.e. - it responds to the \key{Enter} key. - - \retval true The button is the default button. - \retval false The button is \b not the default button. + \brief Returns whether or not the button is the default button on the + window, i.e. whether or not it responds to the \key{Enter} key. + + \returns \c true if the button is the default button, \c false otherwise. +*/ + + +/*! + \fn bool BButton::IsFlat() const + \brief Returns whether or not the button is flat or not. + + \note This method was not available in BeOS R5. + + \returns \c true if the button is flat, \c false otherwise. +*/ + + +/*! + \fn void BButton::SetFlat(bool flat) + \brief Sets or unsets the button to be flat. + + \note This method was not available in BeOS R5. + + \param flat \c true to make the button flat, \c false to make the button + not flat. +*/ + + +/*! + \fn BButton::BBehavior BButton::Behavior() const + \brief Returns the buttons behavior. + + \note This method was not available in BeOS R5. + + \return The button behavior flag. +*/ + + +/*! + \fn void BButton::SetBehavior(BBehavior behavior) + \brief Sets the button behavior. + + \note This method was not available in BeOS R5. + + \param behavior One of the following: + - \c B_BUTTON_BEHAVIOR Normal behavior, + - \c B_TOGGLE_BEHAVIOR Acts like a check box, + - \c B_POP_UP_BEHAVIOR Adds a pop-up marker to the button + (similar to that of BMenuField). +*/ + + +/*! + \fn BMessage* BButton::PopUpMessage() const + \brief Returns the message sent to the button's target when the + pop-up marker is selected using \c B_POP_UP_BEHAVIOR. + + \note This method was not available in BeOS R5. + + \return The message sent to the button's target. +*/ + + +/*! + \fn void BButton::SetPopUpMessage(BMessage* message) + \brief Sets the message sent to the button's target when the + pop-up marker is selected using \c B_POP_UP_BEHAVIOR. + + \note This method was not available in BeOS R5. + + \param message The \a message sent to the button's target. +*/ + + +/*! + \fn status_t BControl::SetIcon(const BBitmap* icon, uint32 flags) + \brief This convenience method is used to set the bitmaps + for the standard states from a single bitmap. + + \note This method was not available in BeOS R5. + + \param icon The \a icon to set. + \param flags Modify how the icon is set. + + \return \c B_OK if the icon was set or an error code otherwise. + + \sa BControl::SetIcon() */ /*! \fn void BButton::SetValue(int32 value) - \brief Sets the value of the BButton. + \brief Sets the value of the button. \note This method can be overridden in order to take a different action when the value changes. \param value The value to set to the BButton to. Options include: - \li \c 0 (\c B_CONTROL_OFF) - \li \c 1 (\c B_CONTROL_ON) + - \c 0 (\c B_CONTROL_OFF) + - \c 1 (\c B_CONTROL_ON) \see BControl::SetValue() */ - - -/*! - \fn void BButton::GetPreferredSize(float *_width, float *_height) - \brief Gets the dimensions that the BButton would prefer to be. - - The size is computed from the children sizes, unless it was explicitly set - for the BButton (which can be done only if the BButton is configured to - use the Layout Kit). - - \note Either the \a _width or \a _height parameter may be set to \c NULL - if you only want to get the other one. - - \param[out] _width The width of the preferred size is placed in here. - \param[out] _height The height of the preferred size is placed in here. -*/ - - -/*! - \fn status_t BButton::Invoke(BMessage *message) - \brief The BButton is invoked from a message. - - This method is used to post a message when the button is clicked or - activated by a keyboard button. You can set the object that will - handle the message by calling a BControl::SetTarget() from a - BInvoker inherited control. A model for the message is set by the - BButton constructor or by the BControl::SetMessage() method - inherited from BInvoker. - - \returns B_OK If the BButton was invoked, otherwise an error - \a status_t flag is returned. - - \see BControl::Invoke() -*/