haiku/docs/user/interface/Button.dox

/*
 * Copyright 2011, Haiku inc.
 * Distributed under the terms of the MIT Licence.
 *
 * Documentation by:
 *  John Scipione <jscipione@gmail.com>
 * Corresponds to:
 *  /trunk/headers/os/interface/Button.h
 *  /trunk/src/kits/interface/Button.cpp


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


/*!
	\class BButton Button.h
	\ingroup interface
	\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 \c 1, (\c B_CONTROL_ON) otherwise this value
	is \c 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 Creates a new BButton from an \a archive.

	If the message is a valid button then an instance of BButton created
	from the passed in \a archive will be returned. Otherwise this method
	will return \c NULL.

	\returns An instance of BButton if the \a archive is valid or \c NULL.
*/


/*!
	\fn BArchivable* BButton::Instantiate(BMessage* archive)
	\brief Instantiates a BButton from a BMessage.

	\param archive The \c archive message to instantiate the BButton.

	\returns a BArchivable object of the BButton.
*/


/*!
	\fn status_t BButton::Archive(BMessage* archive, bool deep) const
	\brief Archives the BButton into \a archive.

	\param archive The target \a archive which the BButton data will
		go into.
	\param deep Whether or not to recursively archive the BButton's children.

	\retval B_OK The archive operation was successful.
	\retval B_BAD_VALUE The archive operation failed.
*/


/*!
	\fn void BButton::Draw(BRect updateRect)
	\brief Draws the button and sets its label.

	\param updateRect The BRect which the button is drawn into.
*/


/*!
	\fn void BButton::MouseDown(BPoint point)
	\brief Hook method to respond to a MouseDown event.

	\param point The point on the screen that the mouse pointer is located at.
*/


/*!
	\fn void BButton::AttachedToWindow()
	\brief Hook method that is called when the BButton view is attached
	to the window.
*/


/*!
	\fn void BButton::KeyDown(const char *bytes, int32 numBytes)
	\brief Hook method that is called when a keyboard key is pushed down.
		to the window.
	
	\param bytes The key pressed.
	\param numBytes The number of keys pressed.
*/


/*!
	\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::MessageReceived(BMessage *message)
	\brief Hook method that is called when a message is received by the BButton.

	\param message The message received.
*/


/*!
	\fn void BButton::WindowActivated(bool active)
	\brief Sets the window that the BButton is attached to as activated or not.

	\param active if \c true the window is activated, if \c false the window is
		deactivated.
*/


/*!
	\fn void BButton::MouseMoved(BPoint point, uint32 transit,
		const BMessage *message)
	\brief Hook method that is called when the mouse is moved.

	\param point The point on the screen that the mouse pointer is located at.
	\param transit ???
	\param message The message that is received when the mouse is moved.
*/


/*!
	\fn void BButton::MouseUp(BPoint point)
	\brief Hook method that is called when a mouse button is unpressed.

	\param point The point on the screen that the mouse pointer is located at.
*/


/*!
	\fn void BButton::DetachedFromWindow()
	\brief Detaches the BButton from the window.

	\see BControl::DetachedFromWindow()
*/


/*!
	\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 void BButton::ResizeToPreferred()
	\brief Resizes the BButton to its preferred size.

	\see BControl::ResizeToPreferred()
*/


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


/*!
	\fn void BButton::FrameMoved(BPoint newLocation)
	\brief Move the frame of the BButton.

	\param newLocation The location on the screen that the BButton
		is moved to.

	\see BControl::FrameMoved();
*/


/*!
	\fn void BButton::FrameResized(float width, float height)
	\brief Resize the BButton.

	\param width the new \a width of the BButton
	\param height the new \a height of the BButton

	\see BControl::FrameResized();
*/


/*!
	\fn void BButton::MakeFocus(bool focused)
	\brief Focus or unfocus the BButton.

	\param focused If \c true focus the BButton, otherwise unfocus the BButton.

	\see BControl::MakeFocus()
*/


/*!
	\fn void BButton::AllAttached()
	\brief Hook method that is called when the BButton is attached.

	\see BControl::AllAttached()
*/


/*!
	\fn void BButton::AllDetached()
	\brief Hook method that is called when the BButton is deattached.

	\see BControl::AllDetached()
*/


/*!
	\fn BHandler* BButton::ResolveSpecifier(BMessage *message, int32 index,
		BMessage *specifier, int32 what, property)
	\brief Resolves specifiers for properties.
	\see BHandler::ResolveSpecifier()
*/


/*!
	\fn status_t BButton::GetSupportedSuites(BMessage *message)
	\brief Reports the suites of messages and specifiers that derived classes
		understand.

	\param message The message to report the suite of messages and specifiers.

	\see BWindow::GetSupportedSuites()
*/


/*!
	\fn status_t BButton::Perform(perform_code code, void* _data)
	\brief Perform an action on the BButton.

	\param code The \a perform_code. One of the following:
		\li \c PERFORM_CODE_MIN_SIZE
		\li \c PERFORM_CODE_MAX_SIZE
		\li \c PERFORM_CODE_PREFERRED_SIZE
		\li \c PERFORM_CODE_LAYOUT_ALIGNMENT
		\li \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH
		\li \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH
		\li \c PERFORM_CODE_SET_LAYOUT
		\li \c PERFORM_CODE_INVALIDATE_LAYOUT
		\li \c PERFORM_CODE_DO_LAYOUT
	\param _data Data to use to act on.

	\returns \c B_OK if the action was successful or an error code if not.
*/


/*!
	\fn void BButton::InvalidateLayout(bool descendants)
	\brief Redraws the BButton.

	\param descendants Redraw subviews as well.
*/


/*!
	\fn BSize BButton::MinSize()
	\brief Returns the minimum size of the BButton.

	\returns The minimum BButton size as a BSize
*/


/*!
	\fn BSize BButton::MaxSize()
	\brief Returns the maximum size of the BButton.

	\returns The maximum BButton size as a BSize
*/


/*!
	\fn BSize BButton::PreferredSize()
	\brief Returns the preferred size of the BButton.

	\returns The preferred BButton size as a BSize
*/