haiku/docs/user/interface/Button.dox

251 lines
7.2 KiB
Plaintext
Raw Normal View History

/*
* Copyright 2011 Haiku Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* headers/os/interface/Button.h rev 42794
* src/kits/interface/Button.cpp rev 42794
/*!
\file Button.h
\ingroup interface
\ingroup libbe
\brief Describes the BButton class.
*/
/*!
\class BButton Button.h
\ingroup interface
\ingroup libbe
\brief A BButton is a labeled on-screen button.
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 <span class="keycap">Enter</span> 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).
BButton inherits from the BControl class.
*/
/*!
\fn BButton::BButton(BRect frame, const char* name, const char* label,
BMessage* message, uint32 resizingMode, uint32 flags)
\brief Creates and initializes a BButton control.
\note A BButton created with a constructor that includes a frame
parameter does \b not utilize the Layout Kit to position and size the
control.
BControl initializes the button's label and assigns it a message that
identifies the action that should be carried out when the button is
pressed. When the button is attached to a window it is resizes to the
height of the button's frame rectangle to fit the button's border and
label in the button's font.
The \a frame, \a name, \a resizingMode, and \a flags parameters are
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 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.
*/
/*!
\fn BButton::BButton(const char* name, const char* label, BMessage* message,
uint32 flags)
\brief Creates and initializes a BButton control.
BControl initializes the button's label and assigns it a message that
identifies the action that should be carried out when the button is
pressed. When the button is attached to a window it is resizes to the
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 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.
*/
/*!
\fn BButton::BButton(const char* label, BMessage* message)
\brief Creates and initializes a BButton control.
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
*/
/*!
\fn BButton::~BButton()
\brief Destructor method.
Standard Destructor.
*/
/*! \fn BButton::BButton(BMessage* archive)
\brief Constructs a BButton object from an \a archive 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
of its child views recursively.
\param archive The \a archive message to restore from.
*/
/*!
\fn void BButton::Draw(BRect updateRect)
\brief Draws the area of the button that intersects \a updateRect and
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.
\param updateRect The rectangular area to be drawn.
\sa BView::Draw()
*/
/*!
\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::SetLabel(const char *string)
\brief Sets the BButton's label.
\param string 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.
*/
/*!
\fn void BButton::SetValue(int32 value)
\brief Sets the value of the BButton.
\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)
\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()
*/