BButton

Derived from: public BControl

Declared in: be/interface/Button.h

Library: libbe.so

A BButton object draws a labeled button on-screen and responds when the button is clicked or when it's operated from the keyboard. If the BButton is the default button for its window and the window is the active window, the user can operate it by pressing the Enter key.

BButtons have a single state. Unlike check boxes and radio buttons, the user can't toggle a button on and off. However, the button's value changes while it's being operated. During a click (while the user holds the mouse button down and the cursor points to the button on-screen), the BButton's value is set to 1 (B_CONTROL_ON). Otherwise, the value is 0 (B_CONTROL_OFF).

This class depends on the control framework defined in the BControl class. In particular, it calls these BControl functions:

SetValue() to make each change in the BControl's value. This is a hook function that you can override to take collateral action when the value changes.
Invoke() to post a message each time the button is clicked or operated from the keyboard. You can designate the object that should handle the message by calling BControl's SetTarget() function. A model for the message is set by the BButton constructor (or by BControl's SetMessage() function).
IsEnabled() to determine how the button should be drawn and whether it's enabled to post a message. You can call BControl's SetEnabled() to enable and disable the button.

A BButton is an appropriate control device for initiating an action. Use a BCheckBox, a BPictureButton, or BRadioButtons to set a state.

Hook Functions

MakeDefault()Makes the BButton the default button for its window or removes that status; can be augmented by derived classes to take note when the status of the button changes.

Constructor and Destructor

BButton()

      BButton(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) 
      BButton(BMessage *archive)

Initializes the BButton by passing all arguments to the BControl constructor. BControl initializes the button's label and assigns it a model message that identifies the action that should be carried out when the button is invoked.

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

When the button is attached to a window, it will be resized to its preferred height; the height of BButton's frame rectangle will exactly accommodate the button border and label, given the BButton's current font.

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

~BButton()

      virtual ~BButton()

Does nothing; a BButton has no data to free.

Static Functions

Instantiate()

      static BArchivable *Instantiate(BMessage *archive)

Returns a new BButton object--or NULL, if the archive message doesn't contain data for a BButton object. The new object is allocated by new and created with the version of the constructor that takes a BMessage archive.

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 records the BButton's label and whether or not it's the default button for its window in the BMessage archive.

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

AttachedToWindow()

      virtual void AttachedToWindow(void)

Augments the BControl version of this function to tell the BWindow that the button is the default button, if MakeDefault() has already been called.

See also: BView::AttachedToWindow(), BControl::AttachedToWindow(), MakeDefault()

Draw()

      virtual void Draw(BRect updateRect)

Draws the button and labels it. If the BButton's value is anything but 0, the button is highlighted. If it's disabled, it drawn in muted shades of gray. Otherwise, it's drawn in its ordinary, enabled, unhighlighted state.

See also: BView::Draw()

GetPreferredSize()

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

Calculates how big the button needs to be to display its label in the current font, and writes the results into 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. A button is automatically resized to its preferred height (but not to its preferred width) by AttachedToWindow().

MakeDefault

KeyDown()

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

Augments the inherited version of KeyDown() to respond to messages reporting that the user pressed the Enter key or the space bar. Its response is to:

Momentarily highlight the button and change its value.
Call Invoke() to deliver a copy of the model BMessage to the target receiver.

The BButton gets KeyDown() function calls when it's the focus view for the active window (which results when the user navigates to it) and also when it's the default button for the window and the character the user types is B_ENTER.

See also: BControl::Invoke(), BView::KeyDown(), MakeDefault()

MakeDefault(), IsDefault()

      virtual void MakeDefault(bool flag)
      bool IsDefault(void) const

MakeDefault() makes the BButton the default button for its window when flag is true, and removes that status when flag is false. The default button is the button the user can operate by striking the Enter key when the window is the active window. IsDefault() returns whether the BButton is currently the default button.

A window can have only one default button at a time. Setting a new default button, therefore, may deprive another button of that status. When MakeDefault() is called with an argument of true, it generates a MakeDefault() call with an argument of false for previous default button. Both buttons are redisplayed so that the user can see which one is currently the default.

The default button can also be set by calling BWindow's SetDefaultButton() function. That function makes sure that the button that's forced to give up default status and the button that obtains it are both notified through MakeDefault() function calls.

MakeDefault() is therefore a hook function that can be augmented to take note each time the default status of the button changes. It's called once for each change in status, no matter which function initiated the change.

See also: BWindow::SetDefaultButton()

MouseDown()

      virtual void MouseDown(BPoint point)

Overrides the BView version of MouseDown() to track the cursor while the user holds the mouse button down. As the cursor moves in and out of the button, the BButton's value is reset accordingly. The SetValue() virtual function is called to make the change each time.

If the cursor is inside the BButton's bounds rectangle when the user releases the mouse button, this function posts a copy of the model message so that it will be dispatched to the target object.

See also: BView::MouseDown(), BControl::Invoke(), BControl::SetTarget()

SetLabel()

      virtual void SetLabel(const char *string)

Overrides the BControl version of this function to make sure that calculations based on the width of the label won't assume cached results for the previous label.

See also: BControl::SetLabel()

Archived Fields

The Archive() function adds the following fields to its BMessage argument:

Field Type code Meaning
"_default" B_BOOL_TYPE Exists and is true if the button is the default.

Field	Type code	Meaning
"_default"	`B_BOOL_TYPE`	Exists and is `true` if the button is the default.

The Be Book, in lovely HTML, for BeOS Release 4.

Last modified December 9, 1998.