haiku/docs/user/interface/PictureButton.dox

/*
 * Copyright 2014 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/PictureButton.h	 hrev47233
 *		src/kits/interface/PictureButton.cpp	 hrev47233
 */


/*!
	\file PictureButton.h
	\ingroup interface
	\ingroup libbe
	\brief BPictureButton class definition and support structures.
*/


/*!
	\var B_ONE_STATE_BUTTON

	Acts like a normal BButton, the value is set to \c B_CONTROL_ON when the
	button is being pressed and is set to \c B_CONTROL_OFF otherwise.

	\since BeOS R3
*/


/*!
	\var B_TWO_STATE_BUTTON

	Acts like a checkbox, the value alternates between \c B_CONTROL_ON and
	\c B_CONTROL_OFF each time the user presses and releases the button.

	\since BeOS R3
*/


/*!
	\class BPictureButton
	\ingroup interface
	\ingroup libbe
	\brief A button draw with a BPicture image instead of a text label.

	There are two types:
	- \c B_ONE_STATE_BUTTON Acts like a normal BButton, the value is set to
	     \c B_CONTROL_ON when the button is being pressed and is set to
		 \c B_CONTROL_OFF otherwise.
	- \c B_TWO_STATE_BUTTON Acts like a checkbox, the value alternates between
	     \c B_CONTROL_ON and \c B_CONTROL_OFF each time the user presses and
		 releases the button.

	\since BeOS R3
*/


/*!
	\fn BPictureButton::BPictureButton(BRect frame, const char* name,
		BPicture* off, BPicture* on, BMessage* message,
		uint32 behavior, uint32 resizingMode, uint32 flags)
	\brief Initializes a new BPictureButton object.

	\param frame The \a frame rectangle of the button.
	\param name The \a name of the button used internally.
	\param off The BPicture object to use when the object is \a off.
	\param on The BPicture object to use when the object is \a on.
	\param message The BMessage to send when the object is invoked.
	\param behavior Either \c B_ONE_STATE_BUTTON or \c B_TWO_STATE_BUTTON.
	\param resizingMode Defines the view's behavior when its parent is
	       resized, see BView for more details.
	\param flags The view flags, see BView for more details.

	\sa BPictureButton::SetBehavior()
	\sa BPictureButton::SetEnabledOn()
	\sa BPictureButton::SetEnabledOff()
	\sa BPictureButton::SetDisabledOn()
	\sa BPictureButton::SetDisabledOff()

	\since BeOS R3
*/


/*!
	\fn BPictureButton::BPictureButton(BMessage* data)
	\brief Initializes an BPictureButton object copying the data from from the
	       passed in \a data archive.

	\since BeOS R3
*/


/*!
	\fn BPictureButton::~BPictureButton()
	\brief Destroys the BPictureButton along with the associated BPicture objects.

	\since BeOS R3
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn BArchivable* BPictureButton::Instantiate(BMessage* data)
	\brief Returns a pointer to a new BPictureButton object created from the
	       BPictureButton data archived in \a data.

	\returns A newly created BPictureButton object or \c NULL if the message
	         doesn't contain an archived BPictureButton.

	\see BArchivable::Instantiate()

	\since BeOS R3
*/


/*!
	\fn status_t BPictureButton::Archive(BMessage* data, bool deep) const
	\brief Archives the BPictureButton object into the \a data message.

	\param data A pointer to the BMessage object to archive into.
	\param deep Also archive the associated BPicture objects.

	\return A status code, \c B_OK if everything went well or an error code
	        otherwise.
	\retval B_OK The object was archived successfully.
	\retval B_NO_MEMORY Ran out of memory while archiving the object.

	\sa BArchivable::Archive()
	\sa BPictureButton::Instantiate()

	\since BeOS R3
*/


//! @}


/*!
	\name Hook Methods
*/


//! @{


/*!
	\fn void BPictureButton::AttachedToWindow()
	\copydoc BControl::AttachedToWindow()
*/


/*!
	\fn void BPictureButton::DetachedFromWindow()
	\copydoc BControl::DetachedFromWindow()
*/


/*!
	\fn void BPictureButton::AllAttached()
	\copydoc BControl::AllAttached()
*/


/*!
	\fn void BPictureButton::AllDetached()
	\copydoc BControl::AllDetached()
*/


/*!
	\fn void BPictureButton::Draw(BRect updateRect)
	\brief Draws the BPictureButton from its associated BPicture objects.

	\copydetails BControl::Draw()
*/


/*!
	\fn void BPictureButton::FrameMoved(BPoint newPosition)
	\copydoc BControl::FrameMoved()
*/


/*!
	\fn BPictureButton::FrameResized(float newWidth, float newHeight)
	\copydoc BControl::FrameResized()
*/


/*!
	\fn void BPictureButton::KeyDown(const char* bytes, int32 numBytes)
	\brief Invokes the button on either \c B_ENTER \c B_SPACE.

	\copydetails BControl::KeyDown()
*/


/*!
	\fn void BPictureButton::MessageReceived(BMessage* message)
	\copydoc BControl::MessageReceived()
*/


/*!
	\fn void BPictureButton::MouseDown(BPoint where)
	\brief Sets the button value based on the buttons Behavior().

	\copydetails BControl::MouseDown()

	\sa Behavior()
*/


/*!
	\fn void BPictureButton::MouseMoved(BPoint where, uint32 code,
		const BMessage* dragMessage)

	\copydetails BControl::MouseMoved()
*/


/*!
	\fn void BPictureButton::MouseUp(BPoint where)
	\brief Invokes the button.

	\copydetails BControl::MouseUp()
*/


/*!
	\fn void BPictureButton::WindowActivated(bool active)
	\copydoc BControl::WindowActivated()
*/


//! @}


/*!
	\fn void BPictureButton::ResizeToPreferred()
	\copydoc BControl::ResizeToPreferred()
*/


/*!
	\fn void BPictureButton::GetPreferredSize(float* _width, float* _height)
	\copydoc BControl::GetPreferredSize()
*/


/*!
	\fn void BPictureButton::MakeFocus(bool focus)
	\copydoc BControl::MakeFocus()
*/


/*!
	\fn void BPictureButton::SetEnabledOn(BPicture* picture)
	\brief Sets the BPicture to draw when the button is enabled and on.

	\param picture A pointer to the BPicture object to set.

	\since BeOS R3
*/


/*!
	\fn void BPictureButton::SetEnabledOff(BPicture* picture)
	\brief Sets the BPicture to draw when the button is enabled and off.

	\param picture A pointer to the BPicture object to set.

	\since BeOS R3
*/


/*!
	\fn void BPictureButton::SetDisabledOn(BPicture* picture)
	\brief Sets the BPicture to draw when the button is disabled and on.

	If the behavior is set to \c B_ONE_STATE_BUTTON this does not need be
	set because a disabled one-state control can never be on.

	\param picture A pointer to the BPicture object to set.

	\since BeOS R3
*/


/*!
	\fn void BPictureButton::SetDisabledOff(BPicture* picture)
	\brief Sets the BPicture to draw when the button is disabled and off.

	\param picture A pointer to the BPicture object to set.

	\since BeOS R3
*/


/*!
	\fn BPicture* BPictureButton::EnabledOn() const
	\brief Returns a pointer to the BPicture object used when the button
	       is enabled and on.

	\returns A pointer to a BPicture object or \c NULL if not set.

	\since BeOS R3
*/


/*!
	\fn BPicture* BPictureButton::EnabledOff() const
	\brief Returns a pointer to the BPicture object used when the button
	       is enabled and off.

	\returns A pointer to a BPicture object or \c NULL if not set.

	\since BeOS R3
*/


/*!
	\fn BPicture* BPictureButton::DisabledOn() const
	\brief Returns a pointer to the BPicture object used when the button
	       is disabled and on.

	\returns A pointer to a BPicture object or \c NULL if not set.

	\since BeOS R3
*/


/*!
	\fn BPicture* BPictureButton::DisabledOff() const
	\brief Returns a pointer to the BPicture object used when the button
	       is disabled and off.

	\returns A pointer to a BPicture object or \c NULL if not set.

	\since BeOS R3
*/


/*!
	\fn void BPictureButton::SetBehavior(uint32 behavior)
	\brief Set the behavior to either \c B_ONE_STATE_BUTTON or
	       \c B_TWO_STATE_BUTTON.

	A one-state BPictureButton acts like a normal button, the value is set to
	\c B_CONTROL_ON when the button is being pressed and it is set to
	\c B_CONTROL_OFF otherwise. A two-state object acts like a checkbox, the
	value alternates between \c B_CONTROL_ON and \c B_CONTROL_OFF each time
	the user presses and releases the button.

	\param behavior Either \c B_ONE_STATE_BUTTON or \c B_TWO_STATE_BUTTON.

	\since BeOS R3
*/


/*!
	\fn uint32 BPictureButton::Behavior() const
	\brief Return the currently set behavior.

	\returns Either \c B_ONE_STATE_BUTTON or B_TWO_STATE_BUTTON.

	\see SetBehavior()

	\since BeOS R3
*/


/*!
	\fn void BPictureButton::SetValue(int32 value)
	\copydoc BControl::SetValue()
*/


/*!
	\fn status_t BPictureButton::Invoke(BMessage* message)
	\copydoc BControl::Invoke()
*/


/*!
	\fn BHandler* BPictureButton::ResolveSpecifier(BMessage* message,
		int32 index, BMessage* specifier, int32 what, const char* property)
	\copydoc BControl::ResolveSpecifier()
*/


/*!
	\fn status_t BPictureButton::GetSupportedSuites(BMessage* data)
	\copydoc BControl::GetSupportedSuites()
*/


/*!
	\fn status_t BPictureButton::Perform(perform_code code, void* _data)
	\copydoc BHandler::GetSupportedSuites()
*/


/*!
	\fn status_t BPictureButton::SetIcon(const BBitmap* icon, uint32 flags)
	\see BControl::SetIcon()

	\since Haiku R1
*/