Derived from: public BControl
Declared in: be/interface/TextControl.h
Library: libbe.so
A BTextControl object displays a labeled text field that behaves like other control devices. When the user presses certain keys after modifying the text in the field, it delivers 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 keyboard 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 delivers a 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 BTextControl is also invoked 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 arrange for another message--a "modification message"--to be sent 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). This message notifies the target that editing has begun.
Note that BTextControls only allow the user to edit a single line of text; newline characters are automatically stripped from the text, if they're inserted.
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; ChildAt() returns it when passed an index of 0.
BTextControl(BRect frame, const char *name,
const char *label, const char *text,
BMessage *message,
uint32 resizingMode = B_FOLLOW_LEFT | B_FOLLOW_TOP,
uint32 flags = B_WILL_DRAW | B_NAVIGABLE)
BTextControl(BMessage *archive)
Initializes the BTextControl by assigning it a label and some text, both of which can be NULL. If the label is NULL, the entire bounds rectangle is assigned to the text. 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() andSetTarget() in the BInvoker class 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. When the BTextControl is attached to a window, it will be resized to the optimal height for displaying the label and text.
See also: SetDivider(), SetAlignment(), BInvoker::SetMessage(), BInvoker::SetTarget(), BControl::Invoke()
virtual ~BTextControl()
Frees memory allocated by the BTextControl and its BTextView child.
static BArchivable *Instantiate(BMessage *archive)
Returns a new BTextControl 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 BTextControl object, Instantiate() returns NULL.
See also: BArchivable::Instantiate(), instantiate_object(), Archive()
virtual status_t Archive(BMessage *archive, bool deep = true) const
Calls the inherited version of Archive(), which will archive the child BTextView if the deep flag is true, then adds the alignment of the label and the text, the modification message, and the divider to the BMessage archive.
See also: BArchivable::Archive(), Instantiate() static function
virtual void AttachedToWindow(void)
Augments the BControl version of AttachedToWindow() to set up its child BTextView and to make the view and low colors of the BTextControl the same as the background view color of its new parent . This function also adjusts the height of the BTextControl to fit the height of the label and text, given the fonts used to display them.
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 GetPreferredSize(float *width, float *height)
virtual void ResizeToPreferred(void)
GetPreferredSize() calculates the optimal size for the BTextControl to display the label and the text, given its current font and the current font of its BTextView child; it places the result in the variables that the width and height arguments refer to. ResizeToPreferred() resizes the BTextControl to its preferred size, keeping its left and top sides constant, and adjusts the size of the BTextView to fit.
See also: BView::GetPreferredSize()
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 MessageReceived(BMessage *message)
Handles scripting requests for the BTextControl.
See also: BHandler::MessageReceived()
virtual void MouseDown(BPoint point)
Makes the child BTextView the focus view when the user clicks in the BTextControl but outside the text.
See also: BTextView::MouseDown()
virtual BHandler *ResolveSpecifier(BMessage *message, int32 index, BMessage *specifier, int32 command, const char *property)
Resolves specifiers for the "Text" and "Value" properties. See 10564: head2: Scripting Support in the class overview and "Scripting" in The Application Kit chapter for more information.
See also: BHandler::ResolveSpecifier()
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 SetModificationMessage(BMessage *message)
BMessage *ModificationMessage(void) const
These functions set and return the message that the BTextControl sends to its target 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 sends whenever the user modifies the text when the child BTextView is the focus view.
Before sending the message, the BTextControl adds these two pieces of information to it:
| Data name | Type code | Description |
|---|---|---|
| "when" | B_INT64_TYPE | When the user modified the text, as measured by the number of microseconds since 12:00:00 AM January 1, 1970.. |
| "source" | B_POINTER_TYPE | A pointer to the BTextControl object. |
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.
BTextView *TextView(void) const
Returns the child BTextView object that handles the BTextControl's editing chores.
See also: the BTextView class
virtual void WindowActivated(bool active)
Makes sure that the BTextControl is redrawn when the window is activated and deactivated, if its child BTextView is the current focus view. This gives the BTextControl a chance to draw or erase the indication that it's the current focus for keyboard navigation.
The Archive() function adds the following fields to its BMessage argument:
| Field | Type code | Meaning |
|---|---|---|
| "_a_label" | B_INT32_TYPE | Alignment of label in frame. |
| "_a_text" | B_INT32_TYPE | Alignment of text in frame. |
| "_divide" | B_FLOAT_TYPE | x-coordinate dividing label and text in frame. |
| "_mod_msg" | B_MESSAGE_TYPE | Invocation message for the control (only present if one was defined). |
The following view is added to the "_views" field (deep copy only):
| Name | Level | Meaning |
|---|---|---|
| "_input_" | 0 | Text input view. |
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified January 4, 1999.