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()