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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


/*!
	\fn void BPictureButton::WindowActivated(bool state)
	\see BControl::WindowActivated()
*/


/*!
	\fn void BPictureButton::MakeFocus(bool state)
	\see BControl::MakeFocus()
*/


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


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


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

	\sa BControl::KeyDown()
*/


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

	\sa BControl::MouseDown()
	\sa Behavior()
*/


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

	\sa BControl::MouseUp()
*/


/*!
	\fn void BPictureButton::MouseMoved(BPoint where, uint32 transit,
		const BMessage* message)
	\brief

	\sa BControl::MouseMoved()
*/


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


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


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


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


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


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


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


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


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


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

	\returns Either \c B_ONE_STATE_BUTTON or B_TWO_STATE_BUTTON.

	\see BPictureButton::SetBehavior()
*/


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


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


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


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


/*!
	\fn status_t BPictureButton::Perform(perform_code code, void* _data)
	\brief Perform some action (internal method defined for binary
	       compatibility purposes).
*/


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