xref: /haiku/docs/user/interface/Control.dox (revision 6ac7032dc66744139522bdef3fab49d4e894a84a)

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

/*!
	\file Control.h
	\brief BControl class definition and support enums.
*/


/*!
	\var B_CONTROL_ON
	Control on
*/


/*!
	\var B_CONTROL_OFF
	Control off
*/


/*!
	\class BControl
	\ingroup interface
	\ingroup libbe
	\brief BControl is the base class for user-event handling objects.

	Simple controls such as BCheckBox and BButton deviate only a bit from
	BControl, whereas more complicated controls such as BColorControl and
	BSlider re-implement much more functionality. Whether you are building
	a simple control or something more complicated you should inherit from
	BControl as it provides a common set of methods for intercepting
	received messages from mouse and keyboard events.

	Controls have state which they keep in their value. The value of a
	control, stored as an int32, is read and set by the virtual Value() and
	SetValue() methods. BControl defines \c B_CONTROL_ON and \c B_CONTROL_OFF
	values that you can use as a convenience if your control has a simple
	on/off state. If your BControl derived class stores a larger set of
	states then you should define your own integer values instead.
*/


/*!
	\fn BControl::BControl(BRect frame, const char *name, const char *label,
						   BMessage *message, uint32 resizingMode,
						   uint32 flags)
	\brief Construct a control in the \a frame with a \a name, \a label,
		model \a message, \a resizingMode, and creation \a flags.

	The initial value of the control is set to 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 control in.
	\param name The \a name of the control.
	\param label The \a label displayed along with the control.
	\param message The \a message to send when the control is activated.
	\param resizingMode Defines the behavior of the control as the parent
		view resizes.
	\param flags Behavior \a flags for the control. See BView for details.
*/


/*!
	\fn BControl::BControl(const char *name, const char *label,
						   BMessage *message, uint32 flags)
	\brief Construct a control 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 control is set to 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 control.
	\param label The \a label displayed along with the control.
	\param message The \a message to send when the control is activated.
	\param flags Behavior \a flags for the control. See BView for details.
*/


/*!
	\fn BControl::~BControl()
	\brief Frees all memory used by the BControl object including the memory
		used by the model message.
*/


/*!
	\fn BControl::BControl(BMessage *archive)
	\brief Constructs a BControl object from an \a archive message.

	This method is usually not called directly. If you want to build a
	control from a message you should call Instantiate() which can
	handle errors properly.

	If the \a archive deep, the BControl object will also unarchive each
	of its child views recursively.

	\param archive The \a archive message to restore from.
*/


/*!
	\fn BArchivable* BControl::Instantiate(BMessage *archive)
	\brief Creates a new object from an \a archive.

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

	\param archive The \a archive message.

	\returns An instance of the object if \a archive is valid or \c NULL.

	\sa BArchivable::Instantiate()
*/


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

	\param archive The target \a archive that the data will go into.
	\param deep Whether or not to recursively archive child views.

	\retval B_OK The archive operation was successful.
	\retval B_BAD_VALUE \c NULL \a archive message.
	\retval B_ERROR The archive operation failed.

	\sa BArchivable::Archive()
*/


/*!
	\fn void BControl::WindowActivated(bool active)
	\brief Hook method that is called when the attached window becomes
		activated or deactivated.

	The BControl is redrawn if it is a child of the focused view.

	\param active \c true if the window becomes activated, \c false if the
		window becomes deactivated.

	\sa BView::WindowActivated()
*/


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

	This method overrides BView::AttachedToWindow() setting the low color
	and view color of the BControl so that it matches the view color of the
	control's parent view. It also makes the attached window the default
	target for Invoke() as long as another target has not already been set.

	\sa BView::AttachedToWindow()
	\sa Invoke()
	\sa BInvoker::SetTarget()
*/


/*!
	\fn void BControl::DetachedFromWindow()
	\brief Hook method that is called when the object is detached from a
		window.

	\sa BView::DetachedFromWindow()
*/


/*!
	\fn void BControl::AllAttached()
	\brief Similar to AttachedToWindow() but this method is triggered after
		all child views have already been attached to a window.

	\sa BView::AllAttached()
*/


/*!
	\fn void BControl::AllDetached()
	\brief Similar to AttachedToWindow() but this method is triggered after
		all child views have already been detached from a window.

	\sa BView::AllDetached()
*/


/*!
	\fn void BControl::MakeFocus(bool focused)
	\brief Gives or removes focus from the control.

	BControl::MakeFocus() overrides BView::MakeFocus() to call Draw() when
	the focus changes. Derived classes generally don't have to re-implement
	MakeFocus().

	IsFocusChanging() returns \c true when Draw() is called from this method.

	\param focused \a true to set focus, \a false to remove it.

	\sa BView::MakeFocus()
	\sa IsFocusChanging()
*/


/*!
	\fn void BControl::KeyDown(const char *bytes, int32 numBytes)
	\brief Hook method that is called when a keyboard key is pressed.

	Overrides BView::KeyDown() to toggle the control value and then
	calls Invoke() for \c B_SPACE or \c B_ENTER. If this is not desired
	you should override this method in derived classes.

	The KeyDown() method is only called if the BControl is the focus view
	in the active window. If the window has a default button, \c B_ENTER
	will be passed to that object instead of the focus view.

	\param bytes The bytes of the key combination pressed.
	\param numBytes The number of bytes in \a bytes.

	\sa BView::KeyDown()
	\sa MakeFocus()
*/


/*!
	\fn void BControl::MouseDown(BPoint point)
	\brief Hook method that is called when a mouse button is pressed.

	\param point The point on the screen where to mouse pointer is when
		the mouse button is pressed.

	\sa BView::MouseDown()
*/


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

	\param point The point on the screen where to mouse pointer is when
		the mouse button is released.

	\sa BView::MouseUp()
*/


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

	\sa BView::MouseMoved()
*/


/*!
	\fn void BControl::SetLabel(const char *label)
	\brief Sets the \a label of the control.

	If the \a label changes the control is redrawn.

	\param label The \a label to set, can be \c NULL.
*/


/*!
	\fn const char* BControl::Label() const
	\brief Gets the label of the control.

	returns The control's label.
*/


/*!
	\fn void BControl::SetValue(int32 value)
	\brief Sets the value of the control.

	If the \a value changes the control is redrawn.

	\param value The \a value to set.

	\sa SetValueNoUpdate()
*/


/*!
	\fn void BControl::SetValueNoUpdate(int32 value)
	\brief Sets the value of the control without redrawing.

	\param value The \a value to set.

	\sa SetValue()
*/


/*!
	\fn int32 BControl::Value() const
	\brief Gets the value of the control.

	\returns The control's value.
*/


/*!
	\fn void BControl::SetEnabled(bool enabled)
	\brief Enables or disables the control.

	BControl objects are enabled by default. If the control changes enabled
	state then it is redrawn.

	Disabled controls generally won't allow the user to focus on them
	(The \c B_NAVIGABLE flag is turned off), and don't post any messages.

	Disabled controls in derived classes should be drawn in subdued colors
	to visually indicate that they are disabled and should not respond to
	keyboard or mouse events.

	\param enabled If \c true enables the control, if \c false, disables it.
*/


/*!
	\fn bool BControl::IsEnabled() const
	\brief Gets whether or not the control is currently enabled.

	\returns \c true if the control is enabled, \c false if it is disabled.
*/


/*!
	\fn void BControl::GetPreferredSize(float *_width, float *_height)
	\brief Fill out the preferred width and height of the control
		into the \a _width and \a _height parameters.

	Derived classes can override this method to set the preferred
	width and height of the control.

	\param _width Pointer to a \c float to hold the width of the control.
	\param _height Pointer to a \c float to hold the height of the control.

	\sa BView::GetPreferredSize()
*/


/*!
	\fn void BControl::ResizeToPreferred()
	\brief Resize the control to its preferred size.

	\sa BView::ResizeToPreferred()
*/


/*!
	\fn status_t BControl::Invoke(BMessage *message)
	\brief Sends a copy of the model \a message to the designated target.

	BControl::Invoke() overrides BInvoker::Invoke(). Derived classes
	should use this method in their MouseDown() and KeyDown() methods
	and should call IsEnabled() to check if the control is enabled
	before calling Invoke().

	The following fields added to the BMessage:
		- "when"	\c B_INT64_TYPE	system_time()
		- "source"	\c B_POINTER_TYPE	A pointer to the BControl object.

	\param message The \a message to send.

	\sa BInvoker::Invoke()
	\sa IsEnabled()
*/


/*!
	\fn BHandler* BControl::ResolveSpecifier(BMessage *message, int32 index,
											 BMessage *specifier, int32 what,
											 const char *property)
	\brief Determine the proper specifier for scripting messages.

	\sa BHandler::ResolveSpecifier()
*/


/*!
	\fn status_t BControl::GetSupportedSuites(BMessage *message)
	\brief Report the suites of understood messages.

	\sa BHandler::GetSupportedSuites();
*/


/*!
	\fn status_t BControl::Perform(perform_code code, void* _data)
	\brief Perform some action. (Internal Method)

	The following perform codes are recognized:
		- \c PERFORM_CODE_MIN_SIZE
		- \c PERFORM_CODE_MAX_SIZE
		- \c PERFORM_CODE_PREFERRED_SIZE
		- \c PERFORM_CODE_LAYOUT_ALIGNMENT
		- \c PERFORM_CODE_HAS_HEIGHT_FOR_WIDTH
		- \c PERFORM_CODE_GET_HEIGHT_FOR_WIDTH
		- \c PERFORM_CODE_SET_LAYOUT
		- \c PERFORM_CODE_INVALIDATE_LAYOUT
		- \c PERFORM_CODE_DO_LAYOUT

	\param code The perform code.
	\param _data A pointer to store some data.

	\returns A status code.

	\sa BHandler::Perform()
*/