haiku/docs/user/interface/Button.dox

/*
 * 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	 hrev47274
 *		src/kits/interface/Button.cpp	 hrev47273


/*!
	\file Button.h
	\ingroup interface
	\ingroup libbe
	\brief Describes the BButton class.
*/


/*!
	\class BButton Button.h
	\ingroup interface
	\ingroup libbe
	\brief A control used to initiate an action.

	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
	<span class="keycap">Enter</span> key.

	\image html BButton_example.png

	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.

	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.
*/


/*!
	\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. 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. 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.
*/


/*!
	\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. 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. 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. Can be \c NULL.
	\param message The buttons action \a message. Can be \c NULL.
*/


/*! \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 data deep, the BButton object will also unarchive each
	of its child views recursively.

	\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()
*/


/*!
	\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::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::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 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 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:
		- \c 0 (\c B_CONTROL_OFF)
		- \c 1 (\c B_CONTROL_ON)

	\see BControl::SetValue()
*/