BRadioButton

Derived from: public BControl
Declared in:  be/interface/RadioButton.h
Library: libbe.so
Summary:  more...

A BRadioButton object draws a labeled, two-state button that's displayed in a group along with other similar buttons. The button itself is a round icon that has a filled center when the BRadioButton is turned on, and is empty when it's off. The label appears next to the icon.

Only one radio button in the group can be on at a time; when the user clicks a button to turn it on, the button that's currently on is turned off. One button in the group must be on at all times; the user can turn a button off only by turning another one on. The button that's on has a value of 1 (B_CONTROL_ON); the others have a value of 0 (B_CONTROL_OFF).

The BRadioButton class handles the interaction between radio buttons in the following way: A direct user action can only turn on a radio button, not turn it off. However, when the user turns a button on, the BRadioButton object turns off all sibling BRadioButtons—that is, all BRadioButtons that have the same parent as the one that was turned on.

This means that a parent view should have no more than one group of radio buttons among its children. Each set of radio buttons should be assigned a separate parent—perhaps an empty BView that simply contains the radio buttons and does no drawing of its own.

Constructor and Destructor

BRadioButton()

BRadioButton(BRect frame, const char *name,       const char *label,       BMessage *message,       uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,       uint32 flags = B_WILL_DRAW | B_NAVIGABLE) BRadioButton(BMessage *archive)

Initializes the BRadioButton by passing all arguments to the BControl constructor without change. BControl initializes the radio button's label and assigns it a model message that identifies the action that should be taken when the radio button is turned on. When the user turns the button on, the BRadioButton posts a copy of the message so that it can be delivered to the target handler.

The frame, name, resizingMode, and flags arguments are the same as those declared for the BView class and are passed without change from BControl to the BView constructor.

The BRadioButton draws at the bottom of its frame rectangle beginning at the left side. It ignores any extra space at the top or on the right. (However, the user can click anywhere within the frame rectangle to turn on the radio button). When the object is attached to a window, the height of the rectangle will be adjusted so that there is exactly the right amount of room to accommodate the label.

See also: the BControl and BView constructors, AttachedToWindow()

~BRadioButton()

virtual ~BRadioButton()

Does nothing; a BRadioButton doesn't need to clean up after itself when it's deleted.

Static Functions

Instantiate()

static BArchivable *Instantiate(BMessage *archive)

Returns a new BRadioButton object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the message doesn't contain data for an archived BRadioButton object, this function returns NULL.

See also: BArchivable::Instantiate(), instantiate_object(), Archive()

Member Functions

Archive()

virtual status_t Archive(BMessage *archive, bool deep = true) const

Calls the inherited version of Archive() and doesn't add anything specific to the BRadioButton class to the BMessage archive.

See also: BArchivable::Archive(), Instantiate() static function

AttachedToWindow()

virtual void AttachedToWindow(void)

Augments the BControl version of AttachedToWindow() to set the view and low colors of the BRadioButton to the match its parent's view color, and to resize the radio button vertically to fit the height of the label it displays. The height of the label depends on the BRadioButton's font.

See also: BControl::AttachedToWindow()

Draw()

virtual void Draw(BRect updateRect)

Draws the radio button—the circular icon—and its label. The center of the icon is filled when the BRadioButton's value is 1 (B_CONTROL_ON); it's left empty when the value is 0 (B_CONTROL_OFF).

See also: BView::Draw()

GetPreferredSize()

virtual void GetPreferredSize(float *width, float *height)

Calculates the optimal size for the radio button to display the icon and the label in the current font, and places the result in the variables that the width and height arguments refer to. ResizeToPreferred(), defined in the BView class, resizes a view's frame rectangle to the preferred size, keeping its left and top sides constant. AttachedToWindow() automatically resizes a radio button to its preferred height, but doesn't modify its width.

See also: BView::GetPreferredSize(), AttachedToWindow()

KeyDown()

virtual void KeyDown(const char *bytes, int32 numBytes)

Augments the inherited versions of KeyDown() to turn the radio button on and deliver a message to the target BHandler when the character passed in bytes is B_SPACE or B_ENTER.

See also: BView::KeyDown(), SetValue()

MouseDown()

virtual void MouseDown(BPoint point)

Responds to a mouse-down event in the radio button by tracking the cursor while the user holds the mouse button down. If the cursor is pointing to the radio button when the user releases the mouse button, this function turns the button on (and consequently turns all sibling BRadioButtons off), calls the BRadioButton's Draw() function, and posts a message that will be delivered to the target BHandler. Unlike a BCheckBox, a BRadioButton posts the message—it's "invoked"—only when it's turned on, not when it's turned off.

See also: BControl::Invoke(), BControl::SetTarget(), SetValue()

SetValue()

virtual void SetValue(int32 value)

Augments the BControl version of SetValue() to turn all sibling BRadioButtons off (set their values to 0) when this BRadioButton is turned on (when the value passed is anything but 0).

See also: BControl::SetValue()