361 lines
9.7 KiB
Plaintext
361 lines
9.7 KiB
Plaintext
/*
|
|
* Copyright 2011-2014 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Stephan Aßmus, superstippi@gmx.de
|
|
* Marc Flerackers, mflerackers@androme.be
|
|
* John Scipione, jscipione@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/interface/CheckBox.h hrev47274
|
|
* src/kits/interface/CheckBox.cpp hrev47274
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file CheckBox.h
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief Defines the BCheckBox class
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BCheckBox
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief A user interface element used to make a binary decision.
|
|
|
|
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 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 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 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 check box in the \a frame with a \a name, \a label,
|
|
model \a message, \a resizingMode, and creation \a flags.
|
|
|
|
\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 \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 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 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 \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)
|
|
\brief Constructs a BCheckBox object with just a \a label and model
|
|
\a message.
|
|
|
|
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 \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)
|
|
\brief Constructs a BCheckBox object from an \a archive message.
|
|
|
|
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.
|
|
|
|
\param archive The message to construct the BCheckBox object from.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BCheckBox::~BCheckBox()
|
|
\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 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 a
|
|
check box consider calling Invalidate() instead.
|
|
|
|
\param updateRect The rectangular area to be drawn.
|
|
|
|
\sa BView::Draw()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BCheckBox::FrameMoved(BPoint newPosition)
|
|
\brief Hook method called when the check box is moved.
|
|
|
|
The default implementation does nothing.
|
|
|
|
\param newPosition The point that the check box has been moved to.
|
|
|
|
\sa BView::FrameMoved()
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BCheckBox::FrameResized(float width, float height)
|
|
\brief Hook method called when the check box is resized.
|
|
|
|
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()
|
|
*/
|