haiku/docs/user/interface/RadioButton.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/RadioButton.h	 hrev47274
 *		src/kits/interface/RadioButton.cpp	 hrev47274
 */


/*!
	\file RadioButton.h
	\ingroup interface
	\ingroup libbe
	\brief BRadioButton class definition.
*/


/*!
	\class BRadioButton
	\ingroup interface
	\ingroup libbe
	\brief A user interface control used to select between a set of mutually
	       exclusive options.

	\image html BRadioButton_example.png

	Radio buttons, unlike check boxes, are always used as part of a group.
	Only one radio button in a group can be on at a time, when one is turned
	on all sibling radio buttons are turned off. When a radio button is on it
	has a value of 1 (\c B_CONTROL_ON), when it is off it has a value of 0
	(\c B_CONTROL_OFF). Since all sibling radio buttons are connected to
	create separate groups of radio buttons each group must be attached to
	a different parent, for instance a separate BView.

	Each radio button in a group sends its own BMessage, it's up to you to
	determine what action takes place when each radio button is selected, if
	any. The message is sent only when a radio button is turned on, not when
	it is turned off.

	\since BeOS R3
*/


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

	\note This constructor will resize the control to its minimum height if needed
	      for compatibility with BeOS R5.

	The initial value of the radio button is 0 (\c B_CONTROL_OFF).

	\param frame The \a frame to draw the radio button in.
	\param name The \a name of the radio button, can be \c NULL.
	\param label The \a label displayed along with the radio button control,
	       can be \c NULL.
	\param message The \a message to send when the radio button is activated,
	       can be \c NULL.
	\param resizingMode Defines the behavior of the radio button as the parent
		view resizes. See BView for details.
	\param flags Behavior flags for the radio button. See BView for details.

	\since BeOS R3
*/


/*!
	\fn BRadioButton::BRadioButton(const char* name, const char* label,
		BMessage* message, uint32 flags)
	\brief Construct a radio button 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 radio button is 0 (\c B_CONTROL_OFF).

	\param name The \a name of the radio button, can be \c NULL.
	\param label The \a label displayed along with the radio button control,
	       can be \c NULL.
	\param message The \a message to send when the radio button is activated,
	       can be \c NULL.
	\param flags Behavior flags for the checkbox. See BView for details.

	\since Haiku R1
*/


/*!
	\fn BRadioButton::BRadioButton(const char* label, BMessage* message)
	\brief Constructs a BRadioButton object with just a \a label and model
		\a message.

	The initial value of the radio button is set to 0 (\c B_CONTROL_OFF).
	The \a label and the \a message parameters can be set to \c NULL.

	\param label The \a label displayed along with the radio button control,
	       can be \c NULL.
	\param message The \a message to send when the radio button is activated,
	       can be \c NULL.

	\since Haiku R1
*/


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

	This method is usually not called directly, if you want to build a
	radio button from an archived message you should call Instantiate()
	instead because it can handle errors properly.

	\param archive The message to construct the BRadioButton object from.

	\since BeOS R3
*/


/*!
	\fn BRadioButton::~BRadioButton()
	\brief Destructor, does nothing.

	\since BeOS R3
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn BArchivable* BRadioButton::Instantiate(BMessage* archive)
	\brief Creates a new BRadioButton object from the \a archive message.

	\return A newly created radio button or \c NULL if the message doesn't
	        contain an archived BRadioButton.

	\since BeOS R3
*/


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

	\param archive 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()

	\since BeOS R3
*/


//! @}


/*!
	\name Hook Methods
*/


//! @{


/*!
	\fn void BRadioButton::AllAttached()
	\copydoc BView::AllAttached()
*/


/*!
	\fn void BRadioButton::AllDetached()
	\copydoc BView::AllDetached()
*/


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

	\copydetails BControl::AttachedToWindow()
*/


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

	\copydetails BControl::DetachedFromWindow()
*/


/*!
	\fn void BRadioButton::Draw(BRect updateRect)
	\brief Draws the area of the radio button that intersects \a updateRect.

	\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 a
	      radio button consider calling Invalidate() instead.

	\param updateRect The rectangular area to be drawn.

	\sa BView::Draw()

	\since BeOS R3
*/


/*!
	\fn void BRadioButton::FrameMoved(BPoint newPosition)
	\brief Hook method called when the radio button is moved.

	\copydetails BView::FrameMoved()
*/


/*!
	\fn void BRadioButton::FrameResized(float newWidth, float newHeight)
	\brief Hook method called when the radio button is resized.

	\copydetails BView::FrameResized()
*/


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

	Overrides \c B_RETURN and \c B_SPACE from BControl to toggle the value,
	but don't allow turning the control off, only on.

	\copydetails BControl::KeyDown()
*/


/*!
	\fn void BRadioButton::MessageReceived(BMessage* message)
	\brief Handle \a message received by the associated looper.

	\copydetails BControl::MessageReceived()
*/


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

	Begins tracking the mouse cursor.

	\copydetails BControl::MouseDown()
*/


/*!
	\fn void BRadioButton::MouseMoved(BPoint where, uint32 code,
		const BMessage* dragMessage)
	\brief Hook method called when the mouse is moved.

	Once MouseDown() has been called on a radio button this method updates
	the outline when the cursor is inside the control redrawing as necessary.

	\copydetails BControl::MouseMoved()
*/


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

	Turns the button on turning off all sibling radio buttons and calls the
	Invoke() method. Unlike a BCheckBox, a BRadioButton only posts its message when
	it is turned on, not when it is turned off.

	\copydetails BControl::MouseUp()
*/


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

	\copydetails BControl::WindowActivated()
*/


//! @}


/*!
	\fn void BRadioButton::MakeFocus(bool focus)
	\brief Makes the radio button the current focus view of the window or
	       gives up being the window's focus view.

	\copydetails BControl::MakeFocus()
*/


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


/*!
	\fn void BRadioButton::SetValue(int32 value)
	\brief Turn the radio button on or off.

	Turning a radio button on turns off all sibling radio buttons and calls the
	Invoke() method.

	\copydetails BControl::SetValue()
*/


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

	\remark 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.

	\since BeOS R3
*/


/*!
	\fn status_t BRadioButton::GetSupportedSuites(BMessage* message)
	\copydoc BControl::GetSupportedSuites()
*/


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


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

	\since Haiku R1
*/


/*!
	\fn BAlignment BRadioButton::LayoutAlignment()
	\brief Returns the alignment used by this control in a layout.

	\return The alignment used by this control as a BAlignment.

	\since Haiku R1
*/


/*!
	\fn BSize BRadioButton::MaxSize()
	\brief Get the maximum size of the radio button.

	\return The maximum size of the radio button as a BSize.

	\sa BAbstractLayout::MaxSize()

	\since Haiku R1
*/


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

	The default implementation does nothing.

	\sa BControl::ResizeToPreferred()

	\since BeOS R3
*/


/*!
	\fn status_t BRadioButton::SetIcon(const BBitmap* icon, uint32 flags)
	\brief Set the icon used by the radio button.

	\see BControl::SetIcon()

	\since Haiku R1
*/