Derived from: public BControl
Declared in: be/interface/PictureButton.h
Library: libbe.so
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:
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.
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
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()
virtual ~BPictureButton()
Deletes the model message and the BPicture objects that have been assigned to the BPictureButton.
static BArchivable *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()
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
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()
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()
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()
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
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.
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 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified January 29, 1998.