Derived from: public BControl
Declared in: <interface/TextControl.h>
A BTextControl object displays a labeled text field that behaves like other control devices. When the user takes certain key actions after modifying the text in the field, it posts a message to a designated target.
There are two parts to the view: A static label on the left, which the user cannot modify, and an editable field on the right, which behaves just like a one-line BTextView. In fact, the BTextControl installs a BTextView object as its child to handle editing chores within this part of the view. It's this child view that responds to events for the BTextControl rather than the control object itself.
The child BTextView must become the focus view for the window before the user can enter or edit text in the field. If the user modifies the contents of the field and then causes the child to cease being the focus view, the BTextControl posts a copy of its model message to its target, just like any other BControl object when it's invoked. The message notifies the target that the user has finished making changes to the text. (It doesn't matter what causes the change in focus--a click in another text field, for example, or a B_TAB character that navigates to another view.)
The message is also posted when the user types a B_ENTER character, though this doesn't change the focus view. It selects all the text in the field.
You can also arrange for another message--a "modification message" --to be posted when the user makes the first change to the text after the child BTextView has become the focus view (or after B_ENTER caused all the text to be selected).
Because the label is drawn by the BTextControl itself and the editable text is drawn by its child BTextView, you can assign different properties (color or font, for example) to each string. The BTextControl has only one child, so ChildAt() returns it when passed an index of 0.
BTextControl(BRect frame, const char *name,
const char *label, const char *text,
BMessage *message,
ulong resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
ulong flags = B_WILL_DRAW | B_NAVIGABLE)
Initializes the BTextControl by assigning it a label and some text, both of which can be NULL. If the label is NULL, the text can fill the bounds rectangle. Otherwise, half the view is assigned to the label and half to the text, though the exact proportion can be changed by the SetDivider() function. The label always is on the left and the text always on the right. By default, both label and text are aligned at the left margins of their respective sections; call SetAlignment() to alter the alignment.
The message parameter is the same as the one declared for the BControl constructor. It establishes a model for the messages the BTextControl will send when it's invoked. It can be NULL. See SetMessage(), SetTarget() , and Invoke() in the BControl class for more information.
The frame, name, resizingMode, and flags arguments are the same as those declared for the BView class and are passed up the inheritance hierarchy to the BView constructor without change.
See also: SetDivider() , SetAlignment(), BControl::SetMessage(), BControl::SetTarget() , BControl::Invoke()
virtual ~BTextControl(void)
Frees memory allocated by the BTextControl and its BTextView child.
virtual void AttachedToWindow(void)
Augments the BControl version of AttachedToWindow() to make the background color of the BTextControl the same as the background color of its parent and to set up its child BTextView.
See also: BView::AttachedToWindow(), BControl::AttachedToWindow()
virtual void Draw(BRect updateRect)
Draws the label. (The BTextControl defers to its child BTextView to draw the editable text string.)
See also: BView::Draw()
virtual void MakeFocus(bool flag = TRUE)
Passes the MakeFocus() instruction on to the child BTextView. If the flag is TRUE, this function selects all the text in the child BTextView, which becomes the new focus view for the window. If the flag is FALSE, the child will no longer be the focus view. If the text has changed when the child ceases to be the focus view, the BTextControl is considered to have been invoked; a copy of its model message is posted so that it will be delivered to the target handler.
Note that the BTextControl itself never becomes the focus view, so will return FALSE to all IsFocus() queries.
See also: BView::MakeFocus()
virtual void MouseDown(BPoint point)
Does nothing. The child BTextView handles the job of responding to the user.
See also: BTextView::MouseDown()
virtual void SetAlignment(alignment forLabel, alignment forText)
void GetAlignment(alignment *forLabel, alignment *forText) const
These functions set and report the alignment of the label and the text within their respective portions of the view. Three settings are possible:
| B_ALIGN_LEFT | The label or text is aligned at the left boundary of its part of the view rectangle. |
| B_ALIGN_RIGHT | The label or text is aligned at the right boundary of its part of the view rectangle. |
| B_ALIGN_CENTER | The label or text is centered within its part of the view rectangle. |
The default alignment is B_ALIGN_LEFT for both label and text.
See also: SetDivider()
virtual void SetDivider(float xCoordinate)
float Divider(void) const
These functions set and return the x coordinate value that marks the division between the label portion of the view rectangle on the left and the text portion on the right. It's stated in the coordinate system of the BTextControl.
See also: the BTextControl constructor
virtual void SetEnabled(bool enabled)
Disables the BTextControl if the enabled flag is FALSE, and reenables it if enabled is TRUE. BTextControls are enabled by default.
This function augments the BControl version of SetEnabled() . When the control is disabled, it makes the text unselectable (and therefore uneditable) and draws it in a way that displays its disabled state. When the control is re-enabled, it makes the text editable (and therefore selectable) and draws it as normal text.
See also: BControl::SetEnabled()
virtual void SetLabel(const char *text)
const char *Label(void) const
These functions set and return the label displayed by the BTextControl. The label is first set by the constructor.
virtual void SetModificationMessage(BMessage *message)
BMessage *ModificationMessage(void) const
These functions set and return the message that the BTextControl posts when the user begins to enter or edit text.
SetModificationMessage() assigns message to the BTextControl, freeing the message previously assigned, if any. The message becomes the responsibility of the BTextControl object and will be freed only when it's replaced by another message or the BTextControl is freed; you shouldn't free it yourself. Passing a NULL pointer to this function deletes the current modification message without replacing it.
The assigned BMessage becomes the model for the message that the BTextControl posts when the user first modifies the text after the child BTextView has become the focus view (or after the user pressed the Enter key). The message is sent only for the first character the user types, pastes, or deletes. Subsequent changes don't invoke the message, until after the user presses the Enter key to select all the text or after the child BTextView loses focus view status and regains it again.
Before posting the message, the BTextControl adds two data entries to the copy:
| Data name | Type code | Description | ||
|---|---|---|---|---|
| "when" | B_DOUBLE_TYPE | When the user modified the text, as measured in microseconds since the machines was last booted. |
These names should not be used for any data that you place in the model message.
ModificationMessage() returns the model message.
virtual void SetText(const char *text)
const char *Text(void) const
These functions set and return the text displayed by the BTextControl --or rather by its child BTextView. The text is first set by the constructor.
The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.