From 0a813c73fe9e73c503b1ded8843a53445f795767 Mon Sep 17 00:00:00 2001 From: John Scipione Date: Wed, 28 May 2014 14:16:18 -0400 Subject: [PATCH] Add documentation for BRadioButton. --- docs/user/interface/RadioButton.dox | 447 ++++++++++++++++++ .../interface/images/BRadioButton_example.png | Bin 0 -> 6099 bytes 2 files changed, 447 insertions(+) create mode 100644 docs/user/interface/RadioButton.dox create mode 100644 docs/user/interface/images/BRadioButton_example.png diff --git a/docs/user/interface/RadioButton.dox b/docs/user/interface/RadioButton.dox new file mode 100644 index 0000000000..c07f551cb2 --- /dev/null +++ b/docs/user/interface/RadioButton.dox @@ -0,0 +1,447 @@ +/* + * 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. +*/ + + +/*! + \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 it's 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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \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. +*/ + + +/*! + \fn BRadioButton::~BRadioButton() + \brief Destructor, does nothing. +*/ + + +/*! + \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. +*/ + + +/*! + \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() +*/ + + +//! @} + + +/*! + \name Hook Methods +*/ + + +//! @{ + + +/*! + \fn void BRadioButton::AttachedToWindow() + \brief Hook method called when the control is attached to a window. + + The default implementation does nothing. + + \sa BControl::AttachedToWindow() +*/ + + +/*! + \fn void BRadioButton::DetachedFromWindow() + \brief Hook method called when the control is detached from a window. + + The default implementation does nothing. + + \sa BControl::DetachedFromWindow() +*/ + + +/*! + \fn void BRadioButton::AllAttached() + \brief Similar to AttachedToWindow() but this method is triggered after + all child views have already been attached to a window. + + The default implementation does nothing. + + \sa BView::AllAttached() +*/ + + +/*! + \fn void BRadioButton::AllDetached() + \brief Similar to AttachedToWindow() but this method is triggered after + all child views have already been detached from a window. + + The default implementation does nothing. + + \sa BView::AllDetached() +*/ + + +/*! + \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() +*/ + + +/*! + \fn void BRadioButton::FrameMoved(BPoint newPosition) + \brief Hook method called when the radio button is moved. + + The default implementation does nothing. + + \param newPosition The point that the radio button has been moved to. + + \sa BView::FrameMoved() +*/ + + +/*! + \fn void BRadioButton::FrameResized(float width, float height) + \brief Hook method called when the radio button is resized. + + The default implementation does nothing. + + \param width The new \a width of the radio button. + \param height The new \a height of the radio button. + + \sa 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. + + \param bytes The bytes of the key combination pressed. + \param numBytes The number of bytes in \a bytes. +*/ + + +/*! + \fn void BRadioButton::MessageReceived(BMessage* message) + \brief Handle \a message received by the associated looper. + + The default implemenation does nothing. + + \param message The \a message received by the associated looper. + + \see BControl::MessageReceived() +*/ + + +/*! + \fn void BRadioButton::MouseDown(BPoint where) + \brief Hook method called when a mouse button is pressed. + + Begins tracking the mouse cursor. + + \param where The point on the screen where to mouse pointer is when + the mouse button is pressed. +*/ + + +/*! + \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. + + \param where The new location of the mouse in the control's coordinate system. + \param code One of the following: + - \c B_ENTERED_VIEW The cursor has just entered the control. + - \c B_INSIDE_VIEW The cursor is inside the control. + - \c B_EXITED_VIEW The cursor has left the control's bounds. This only gets + sent if the scope of the mouse events that the control can receive has + been expanded by BView::SetEventMask() or BView::SetMouseEventMask(). + - \c B_OUTSIDE_VIEW The cursor is outside the button. This only gets sent if + the scope of the mouse events that the control can receive has been + expanded by SetEventMask() or SetMouseEventMask(). + \param dragMessage If a drag-and-drop operation is taking place this is a + pointer to a BMessage that holds the drag information, otherwise the + pointer is \c NULL. +*/ + + +/*! + \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. + + \param where The point on the screen where the mouse pointer is located when + the mouse button is released in the view's coordinate system. + + \sa BControl::MouseUp() +*/ + + +/*! + \fn void BRadioButton::WindowActivated(bool active) + \brief Hook method called when the attached window is activated or + deactivated. + + The default implementation does nothing. + + \param active \c true if the window becomes activated, \c false if the + window becomes deactivated. + + \sa BControl::WindowActivated() +*/ + + +//! @} + + +/*! + \fn void BRadioButton::MakeFocus(bool focused) + \brief Makes the radio button the current focus view of the window or + gives up being the window's focus view. + + The default implementation does nothing. + + \param focused \a true to set focus, \a false to remove it. + + \sa BControl::MakeFocus() +*/ + + +/*! + \fn BHandler* BRadioButton::ResolveSpecifier(BMessage* message, + int32 index, BMessage* specifier, int32 what, const char* property) + \brief Determine the proper specifier for scripting messages. + + The default implementation does nothing. + + \sa BControl::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. + + \param value The value to set the radio button to, should be + either \c B_CONTROL_ON or \c B_CONTROL_OFF. + + \sa 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. +*/ + + +/*! + \fn status_t BRadioButton::GetSupportedSuites(BMessage* message) + \brief Report the suites of messages this control understands. + + \param message Allows you to add the names of the suites the radio button + implements to the suites array. + + \return \c B_OK if all went well or an error code otherwise. + + \sa BControl::GetSupportedSuites(); +*/ + + +/*! + \fn status_t BRadioButton::Invoke(BMessage* message) + \brief Sends a copy of the model \a message to the designated target. + + The default implementation does nothing. + + \sa BControl::Invoke() +*/ + + +/*! + \fn status_t BRadioButton::Perform(perform_code code, void* _data) + \brief Perform some action. (Internal Method) +*/ + + +/*! + \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. +*/ + + +/*! + \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() +*/ + + +/*! + \fn void BRadioButton::ResizeToPreferred() + \brief Resize the control to its preferred size. + + The default implementation does nothing. + + \sa BControl::ResizeToPreferred() +*/ + + +/*! + \fn status_t BRadioButton::SetIcon(const BBitmap* icon, uint32 flags) + \brief Set the icon used by the radio button. + + \see BControl::SetIcon() +*/ diff --git a/docs/user/interface/images/BRadioButton_example.png b/docs/user/interface/images/BRadioButton_example.png new file mode 100644 index 0000000000000000000000000000000000000000..7acbdfa157d6dc5b4f88ac3b42ac35694497f175 GIT binary patch literal 6099 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 N$V)3rRZEx#{U0!7XO92? literal 0 HcmV?d00001