Using BTextControl

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.

Archived Fields

: 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.