The Interface Kit: BPictureButton

The Interface Kit Table of Contents | The Interface Kit Index

# BPictureButton

Derived from: BControl > BView > BHandler > BArchivable

Declared in: be/interface/PictureButton.h

Library: libbe.so

Allocation: Constructor only

###### Summary

A BPictureButton draws a button that displays an image (a BPicture object) rather than a text label. A BPictureButton can be either a one-state or a two-state control`:`

- One-state. Acts like a normal BButton: The value is `B_CONTROL_ON` while the object is being pressed and `B_CONTROL_OFF` otherwise. The images for these two states should be different; by convention, the "on" image is a highlighted version of the "off" image. If the button can be disabled, it needs an additional "disabled" image.

- Two-state. Acts like a checkbox: Its value switches between `B_CONTROL_ON` and `B_CONTROL_OFF` every time the user presses (and releases) the button. If the button can be disabled, it needs two additional "disabled" images: One for disabled-while-on and the other for disabled-while-off.

## 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`) `

Creates a new BPictureButton. The off and an on images correspond to the object's `B_CONTROL_OFF` and `B_CONTROL_ON` values; the behavior argument sets the object to be a one-state (`B_ONE_STATE_BUTTON`) or two-state (`B_TWO_STATE_BUTTON`) control, as explained in the class description. The other arguments are inherited from the BView and BControl constructors. The object's initial value is `B_CONTROL_OFF`.

If the BPictureButton can be disabled, it needs additional "disabled" images, as set through `SetDisabledOff()` and `SetDisabledOn()`.

The BPictureButton copies all BPictures that are passed to it. It's the caller's responsibility to free the BPicture objects that are passed as arguments.

### ~BPictureButton()

virtual `~BPictureButton() `

Deletes the object and its data.

## Member Functions

### Behavior() see SetBehavior()

### DisabledOff(), DisabledOn(), EnabledOff(), EnabledOn() see SetEnabledOff()

### BView::Draw()

### KeyDown() (implementation detail) see BControl::KeyDown()

### BControl::MouseDown()

### SetBehavior() , Behavior()

virtual void `SetBehavior(`uint32 behavior`) `
uint32 `Behavior(`void`)` const

These functions set and return whether the BPictureButton is a one-state (`B_ONE_STATE_BUTTON`) or a two-state (`B_TWO_STATE_BUTTON`) control. A one-state object acts like a normal button: It's on while the user is pressing it, and off otherwise. A two-state object switches to the opposite state each time the user presses and release the button.

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

virtual void `SetEnabledOff(`BPictureBControl::MouseDown() *picture`) `
BPicture *`EnabledOff(`void`)` const
virtual void `SetEnabledOn(` BPicture *picture`) `
BPicture *`EnabledOn(`void`)` const
virtual void `SetDisabledOff(` BPicture *picture`) `
BPicture *`DisabledOff(`void`)` const
virtual void `SetDisabledOn(` BPicture *picture`) `
BPicture *`DisabledOn(`void`)` const

These pairs of functions set and return one of the four images the BPictureButton displays: enabled-and-on, enabled-and-off, disabled-and-on, and disabled-and-off, respectively. If this is a one-state object, the disabled-and-on image needn't be set since a disabled one-state control can never be on.

The BPicture-retrieving functions return `NULL` if the requested image hasn't been set.

The BPictureButton copies all BPictures that are passed to it. It's the caller's responsibility to free the BPicture objects that are passed as arguments.

## Archived Fields

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

Field | Type code | Meaning
--- | --- | ---
"_e_on" (deep copy only) | `B_MESSAGE_TYPE` | BPicture displayed when control is enabled and on.
"_e_off" (deep copy only) | `B_MESSAGE_TYPE` | BPicture displayed when control is enabled and off.
"_d_on" (deep copy only) | `B_MESSAGE_TYPE` | BPicture displayed when control is disabled and on.
"_d_off" (deep copy only) | `B_MESSAGE_TYPE` | BPicture displayed when control is disabled and off.
"_behave" | `B_INT32_TYPE` | BPictureButton behavior either `B_ONE_STATE_BUTTON` or `B_TWO_STATE_BUTTON`

See also: `BArchivable::Archive()`

The Interface Kit Table of Contents | The Interface Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..