BControl¶

Constructor and Destructor¶

BControl()

BControl::BControl(BRect frame, const char *name, const char *label, BMessage *message, uint32 resizingMode, uint32 flags)
BControl::BControl(BMessage *archive)

Initializes the BControl by setting its initial value to 0 (B_CONTROL_OFF), assigning it a label, and registering a model message that captures what the control does—the command it gives when it’s invoked and the information that accompanies the command. The label and the message can each be NULL.

The label is copied, but the message is not. The BMessage object becomes the property of the BControl; it should not be deleted, posted, assigned to another object, or otherwise used in application code. The label and message can be altered after construction with the SetLabel() and SetMessage() functions.

The BControl class doesn’t define a Draw() function to draw the label or a MouseDown() function to post the message. (It does define KeyDown(), but only to enable keyboard navigation between controls.) It’s up to derived classes to determine how the label is drawn and how the message is to be used. Typically, when a BControl object needs to take action (in response to a click, for example), it calls the Invoke() function, which copies the model message and delivers the copy to the designated target. By default, the target is the window where the control is located, but BInvoker::SetTarget() can designate another handler.

Before delivering the message, Invoke() adds two data field to it, under the names when and source. These names should not be used for data items in the model.

The frame, name, resizingMode, and flags arguments are identical to those declared for the BView class and are passed unchanged to the BView constructor.

The BControl begins life enabled, and the system plain font is made the default font for all control devices.

~BControl()

virtual BControl::~BControl()

Frees the model message and all memory allocated by the BControl.

Hook Functions¶

AttachedToWindow()

virtual void BControl::AttachedToWindow()

Overrides BView’s version of this function to set the BControl’s low color and view color so that it matches the view color of its new parent. It also makes the BWindow to which the BControl has become attached the default target for the Invoke() function, provided that another target hasn’t already been set.

AttachedToWindow() is called for you when the BControl becomes a child of a view already associated with the window.

KeyDown()

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

Augments the BView version of KeyDown() to toggle the BControl’s value and call Invoke() when the character encoded in bytes is either B_SPACE or B_ENTER. This is done to facilitate keyboard navigation and make all derived control devices operable from the keyboard. Some derived classes—BCheckBox in particular—find this version of the function to be adequate. Others, like BRadioButton, reimplement it.

KeyDown() is called only when the BControl is the focus view in the active window. (However, if the window has a default button, B_ENTER events will be passed to that object and won’t be dispatched to the focus view.)

MessageReceived()

virtual void BControl::MessageReceived(BMessage *message)

Handles scripting messages for the BControl. See “Scripting Support” for a description of the messages.

SetEnabled(), IsEnabled()

virtual void BControl::SetEnabled(bool enabled)

bool BControl::IsEnabled() const

SetEnabled() enables the BControl if the enabled flag is true, and disables it if enabled is false. IsEnabled() returns whether or not the object is currently enabled. BControls are enabled by default.

While disabled, a BControl won’t let the user navigate to it; the B_NAVIGABLE flag is turned off if enabled is false and turned on again if enabled is true.

Typically, a disabled BControl also won’t post messages or respond visually to mouse and keyboard manipulation. To indicate this nonfunctional state, the control device is displayed on-screen in subdued colors. However, it’s left to each derived class to carry out this strategy in a way that’s appropriate for the kind of control it implements. The BControl class merely marks an object as being enabled or disabled; none of its functions take the enabled state of the device into account.

Derived classes can augment SetEnabled() (override it) to take action when the control device becomes enabled or disabled. To be sure that SetEnabled() has been called to actually make a change, its current state should be checked before calling the inherited version of the function. For example:

void MyControl::SetEnabled(bool enabled)
{
   if ( enabled == IsEnabled() )
      return;
   BControl::SetEnabled(enabled);
   /* Code that responds to the change in state goes here. */
}

Note, however, that you don’t have to override SetEnabled() just to update the on-screen display when the control becomes enabled or disabled. If the BControl is attached to a window, the kit’s version of SetEnabled() always calls the Draw() function. Therefore, the device on-screen will be updated automatically—as long as Draw() has been implemented to take the enabled state into account.

SetValue(), Value()

virtual void BControl::SetValue(int32 value)

int32 BControl::Value() const

These functions set and return the value of the BControl object.

SetValue() assigns the object a new value. If the value passed is in fact different from the BControl’s current value, this function calls the object’s Draw() function so that the new value will be reflected in what the user sees on-screen; otherwise it does nothing.

Value() returns the current value.

Classes derived from BControl should call SetValue() to change the value of the control device in response to user actions. The derived classes defined in the Be software kits change values only by calling this function.

Since SetValue() is a virtual function, you can override it to take note whenever a control’s value changes. However, if you want your code to act only when the value actually changes, you must check to be sure the new value doesn’t match the old before calling the inherited version of the function. For example:

void MyControl::SetValue(int32 value)
{
   if ( value != Value() ) {
      BControl::SetValue(value);
      /* MyControl's additions to SetValue() go here*/
   }
}

Remember that the BControl version of SetValue() does nothing unless the new value differs from the old.

WindowActivated()

virtual void BControl::WindowActivated(bool active)

Makes sure that the BControl, if it’s the focus view, is redrawn when the window is activated or deactivated.

Member Functions¶

Archive()

virtual status_t BControl::Archive(BMessage *archive, bool deep = true) const

Archives the BControl by recording its label, current value, model message, and whether or not it’s disabled in the BMessage archive.

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

GetSupportedSuites()

virtual status_t BControl::GetSupportedSuites(BMessage *message)

Adds the name “suite/vnd.Be-control” to the message. See “Scripting Support” and the “Scripting” section in The Application Kit overview for more information.

Invoke()

virtual status_t BControl::Invoke(BMessage *message = NULL)

Copies the BControl’s model BMessage and sends the copy so that it will be dispatched to the designated target (which may be a BLooper’s preferred handler). The following two pieces of information are added to the copy before it’s delivered:

Data name	Type code	Description
“when”	`B_INT64_TYPE`	When the control was invoked, as measured in the number of milliseconds since 12:00:00 AM January 1, 1970.
“source”	`B_POINTER_TYPE`	A pointer to the BControl object. This permits the message handler to request more information from the source of the message.

These two names shouldn’t be used for data fields in the model.

BControl’s version of Invoke() overrides the version that the BInvoker class defines. It’s designed to be called by derived classes in their MouseDown() and KeyDown() functions; it’s not called for you in BControl code. It’s up to each derived class to define what user actions trigger the call to Invoke()—what activity constitutes “invoking” the control.

This function doesn’t check to make sure the BControl is currently enabled. Derived classes should make that determination before calling Invoke().

IsFocusChanging()

bool BControl::IsFocusChanging() const

Returns true if the BControl is being asked to draw because the focus changed, and false if not. If the return value is true, either the BControl has just become the focus view or it has just lost that status and the Draw() function has been called to update the on-screen display.

This function can be called from inside Draw() to learn whether it’s necessary to draw or erase the visible indication that the BControl is the focus view. IsFocusChanging() will return the new status of the view.

MakeFocus()

virtual void BControl::MakeFocus(bool focused = true)

Augments the BView version of this function to call the BControl’s Draw() function when the focus changes. This is done to aid keyboard navigation among control devices. If the Draw() function of a derived class has a section of code that checks whether the object is in focus and marks the on-screen display to show that it is (and removes any such marking when it isn’t), the visual part of keyboard navigation will be taken care of. The derived class doesn’t have to reimplement MakeFocus(). Most of the derived classes implemented in the Interface Kit depend on this version of the function.

When Draw() is called from this function, IsFocusChanging() returns true.

ResolveSpecifier()

virtual BHandler *BControl::ResolveSpecifier(BMessage *message, int32 index, BMessage *specifier, int32 command, const char *property)

Resolves specifiers for the “Label” and “Value” properties. See “Scripting Support” and the “Scripting” section in The Application Kit overview for more information.

SetLabel(), Label()

virtual void BControl::SetLabel(const char *string)

const char *BControl::Label() const

These functions set and return the label on a control device—the text that’s displayed, for example, on top of a button or alongside a check box or radio button. The label is a null-terminated string.

SetLabel() frees the old label, replaces it with a copy of string, and updates the control on-screen so the new label will be displayed to the user—but only if the string that’s passed differs from the current label. The label is first set by the constructor and can be modified thereafter by this function.

Label() returns the current label. The string it returns belongs to the BControl and may be altered or freed in due course.

See also: the BControl constructor, BView::AttachedToWindow()

Static Functions¶

Instantiate()

static BArchivable *BControl::Instantiate(BMessage *archive)

Returns a new BControl object, allocated by new and created with the version of the constructor that takes a BMessage archive. However, if the archive doesn’t contain data for a BControl object, Instantiate() returns NULL.

Scripting Support¶

The BControl class implements the suite called “suite/vnd.Be-control” consisting of the following messages:

The Enabled Property¶

Whether or not the control is enabled

The “Enabled” property corresponds to the methods IsEnabled() and SetEnabled(), using a boolean to store the data.

Message	Specifiers	Description
`B_GET_PROPERTY`	`B_DIRECT_SPECIFIER`	Returns whether or not the BControl is currently enabled.
`B_SET_PROPERTY`	`B_DIRECT_SPECIFIER`	Enables or disables the BControl.

The Label Property¶

The text label for the control

The “Label” property corresponds to the methods Label() and SetLabel(), using a string to store the data.

Message	Specifiers	Description
`B_GET_PROPERTY`	`B_DIRECT_SPECIFIER`	Returns the BControl’s label.
`B_SET_PROPERTY`	`B_DIRECT_SPECIFIER`	Sets the label of the BControl.

The Value Property¶

The value of the control

The “Value” property corresponds to the methods Value() and SetValue(), using an int32 to store the data.

Message	Specifiers	Description
`B_GET_PROPERTY`	`B_DIRECT_SPECIFIER`	Returns the BControl’s value.
`B_SET_PROPERTY`	`B_DIRECT_SPECIFIER`	Sets the value of the BControl.

Archived Fields¶

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

Field	Type code	Description
_msg	`B_MESSAGE_TYPE`	The BControl’s modal invocation message.
_label	`B_STRING_TYPE`	The BControl’s label.
_val	`B_INT32_TYPE`	The BControl’s value.
_disable	`B_BOOL_TYPE`	true if the control is disabled.

Some of these fields may not be present if the setting they represent isn’t used, or is the default value. For example, if the value is 0, the _val field won’t be found in the archive.