# The Interface Kit: BButton

Derived from: public BControl

Declared in: be/interface/Button.h

Library: libbe.so

## Overview

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 BButton *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 set the background color of the button so that it matches the background color of its parent. This function also resizes the button vertically so that its height is just adequate to display the label and the button border. The height of the label depends on the BView's font.

Finally, if `MakeDefault()` had already been called to make the BButton the default button for its window, this function informs the BWindow of that fact.

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.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.