# The Interface Kit: BPictureButton

Derived from: public BControl

Declared in: be/interface/PictureButton.h

Library: libbe.so

## Overview

A BPictureButton object draws a button with a graphic image on its face, rather than a textual label. The image is set by a BPicture object.

Like other BControl objects, BPictureButtons can have two values, `B_CONTROL_OFF` and `B_CONTROL_ON`. A separate BPicture object is associated with each value. How the BPictureButton displays these pictures depends on its behavior--whether it's set to remain in one state or to toggle between two states:

- A one-state BPictureButton usually has a value of 0 (`B_CONTROL_OFF`), and it displays the BPicture associated with that value. However, while it's being operated (while the cursor is over the button on-screen and the user keeps the mouse button down), its value is set to 1 (`B_CONTROL_ON`) and it displays the alternate picture. That picture should be a highlighted version of the picture that's normally shown.

  This behavior is exactly like an ordinary, labeled BButton object. Just as a BButton displays the same label, a one-state BPictureButton shows the same picture. Both kinds of objects are appropriate devices for initiating an action of some kind.

- A two-state BPictureButton toggles between the `B_CONTROL_OFF` and `B_CONTROL_ON` values. Each time the user operates the button, it's value changes. The picture that's displayed changes with the value. The two BPictures are alternatives to each other. The `B_CONTROL_ON` picture might be a highlighted version of the `B_CONTROL_OFF` picture, but it doesn't need to be. The value of the object changes only after it has been toggled to the other state, not while it's being operated.

  This behavior is exactly like a BCheckBox or an individual BRadioButton. Like those objects, a two-state BPictureButton is an appropriate device for setting a state.

Every BPictureButton must be assigned at least two BPictures. If it's a one-state button, one picture will be the one that's normally shown and another will be shown while the button is being operated. If it's a two-state button, one picture is shown when the button is turned on and one when it's off.

If a one-state button can be disabled, it also needs to be assigned an image that can be shown while it's disabled. If a two-state button can be disabled, it needs two additional images--one in case it's disabled while in the `B_CONTROL_OFF` state and another if it's disabled in the `B_CONTROL_ON` state.

Often the BPictures that are assigned to a BPictureButton simply wrap around a bitmap image. For example:

       BPicture *myPict;
       someView->BeginPicture(new BPicture);
       someView->DrawBitmap(&buttonBitmap);
       myPict = someView->EndPicture();

See also: the BPicture class

## Constructor and Destructor

### BPictureButton()

          BPictureButton(BRect frame, const char* name,
             BPicture *off,
             BPicture *on,
             BMessage *message,
             uint32 behavior = B_ONE_STATE_BUTTON,
             uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
             uint32 flags = B_WILL_DRAW | B_NAVIGABLE)
          BPictureButton(BMessage *archive)

Initializes the BPictureButton by assigning it two images--an off picture that will be displayed when the object's value is `B_CONTROL_OFF` and an on picture that's displayed when the value is `B_CONTROL_ON`--and by setting its behavior to either `B_ONE_STATE_BUTTON` or `B_TWO_STATE_BUTTON`. A one-state button displays the off image normally and the on image to highlight the button as it's being operated by the user. A two-state button toggles between the off image and the on image (between the `B_CONTROL_OFF` and `B_CONTROL_ON` values). The initial value is set to `B_CONTROL_OFF`.

If the BPictureButton can be disabled, it will need additional BPicture images that indicate its disabled state. They can be set by calling `SetDisabledOff()` and `SetDisabledOn()`.

All the BPictures assigned to the BPictureButton object become its property. It takes responsibility for deleting them when they're no longer needed.

The message parameter is the same as the one declared for the BControl constructor. It establishes a model for the messages the BPictureButton sends to a target object each time it's invoked.

The frame, name, resizingMode, and flags parameters are the same as those declared for the BView constructor. They're passed up the inheritance hierarchy to the BView class unchanged. See the BView constructor for details.

See also: the BControl and BView constructors, `SetEnabledOff()`, `BControl::Invoke()`, `BInvoker::SetMessage()`, `BInvoker::SetTarget()`

### ~BPictureButton()

          virtual ~BPictureButton()

Deletes the model message and the BPicture objects that have been assigned to the BPictureButton.

## Static Functions

### Instantiate()

          static BPictureButton *Instantiate(BMessage *archive)

Returns a new BPictureButton object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn't contain data for a BPictureButton object, the return value will be `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()`, then adds the behavior flag (`B_ONE_STATE_BUTTON` or `B_TWO_STATE_BUTTON`) to the BMessage archive. If the deep flag is `true`, all the BPictures the object displays are also archived.

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

### Behavior() see SetBehavior()

### Draw()

          virtual void Draw(BRect updateRect)

Draws the BPictureButton. This function is called as the result of an update message to draw the button in its current appearance; it's also called from the `MouseDown()` function to draw the button in its highlighted state.

See also: `BView::Draw()`

### KeyDown()

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

Augments the inherited version of `KeyDown()` so that users can correctly operate both one-state and two-state buttons by pressing the Enter key or the space bar (`B_ENTER` or `B_SPACE`).

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

### MouseDown()

          virtual void MouseDown(BPoint point)

Responds to a mouse-down event in the button by tracking the cursor while the user holds the mouse button down. If the BPictureButton is a one-state object, this function resets its value as the cursor moves in and out of the button on-screen. The `SetValue()` virtual function is called to make the change each time. If it's a two-state object, the value is not reset. (However, the picture corresponding to the `B_CONTROL_ON` value is shown while the cursor is in the button on-screen and the mouse button remains down.)

If the cursor is inside the BPictureButton'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 handler. If it's a one-state object, it's value is reset to `B_CONTROL_OFF`. If it's a two-state object, it's value is toggled on or off and the corresponding picture is displayed.

See also: `BView::MouseDown()`, `BControl::Invoke()`, `SetBehavior()`

### SetBehavior(), Behavior()

          virtual void SetBehavior(uint32 behavior)

          uint32 Behavior(void) const

These functions set and return whether the BPictureButton is a `B_ONE_STATE_BUTTON` or a `B_TWO_STATE_BUTTON`. If it's a one-state button, its value is normally set to `B_CONTROL_OFF` and it displays a fixed image (the off picture passed to the constructor or the one passed to `SetEnabledOff()`). Its value is reset as its being operated and it displays the alternate image (the on picture passed to the constructor or the one passed to `SetEnabledOn()`).

If it's a two-state button, its value toggles between `B_CONTROL_OFF` and `B_CONTROL_ON` each time the user operates it. The image the button displays similarly toggles between two pictures (the off and on images passed to the constructor or the ones passed to `SetEnabledOff()` and `SetEnabledOn()`).

See also: the BPictureButton constructor

### SetEnabledOff(), SetEnabledOn(), SetDisabledOff(), SetDisabledOn(), EnabledOff(), EnabledOn(), DisabledOff(), DisabledOn

          virtual void SetEnabledOff(BPicture *picture)

          virtual void SetEnabledOn(BPicture *picture)

          virtual void SetDisabledOff(BPicture *picture)

          virtual void SetDisabledOn(BPicture *picture)

          BPicture *EnabledOff(void) const

          BPicture *EnabledOn(void) const

          BPicture *DisabledOff(void) const

          BPicture *DisabledOn(void) const

These functions set and return the images the BPictureButton displays. Each BPictureButton object needs to be assigned at least two BPicture objects--one corresponding to the `B_CONTROL_OFF` value and another corresponding to the `B_CONTROL_ON` value. These are the images that are displayed when the BPictureButton is enabled, as it is by default. They're initially set when the object is constructed and can be replaced by calling the `SetEnabledOff()` and `SetEnabledOn()` functions.

If a BPictureButton can be disabled, it needs to display an image that indicates its disabled condition. A two-state button might be disabled when its value is either `B_CONTROL_OFF` or `B_CONTROL_ON`, so it needs two BPictures to indicate disabling, one corresponding to each value. They can be set by calling `SetDisabledOff()` and `SetDisabledOn()`.

The value of a one-state button is always `B_CONTROL_OFF` (except when it's being operated), so it needs only a single BPicture to indicate disabling; you can set it by calling `SetDisabledOff()`.

All four of the `Set`...`()` functions free the image previously set, if any, and replace it with picture. The picture belongs to the BPictureButton; it should not be freed or assigned to any other object.

The last four functions listed above return the BPictureButton's four images, or `NULL` if it hasn't been assigned a BPicture object in the requested category.

## Archived Fields

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

Field | Type code | Meaning
"_e_on" | `B_MESSAGE_TYPE` | BPicture displayed when control is enabled and on.
"_e_off" | `B_MESSAGE_TYPE` | BPicture displayed when control is enabled and off.
"_d_on" | `B_MESSAGE_TYPE` | BPicture displayed when control is disabled and on.
"_d_off" | `B_MESSAGE_TYPE` | BPicture displayed when control is disabled and off.
"_behave" | `B_INT32_TYPE` | BPictureButton behavior.

Some of these fields may not be present if the setting they represent isn't used, or is the default value. For example, if there is no picture defined for the control when it is enabled and off, the "_e_off" field won't be found in the archive.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.