# The Interface Kit: BTextControl

Derived from: public BControl

Declared in: be/interface/TextControl.h

Library: libbe.so

## Overview

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.

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.

### Scripting Support

A BTextControl object supports the following scripting requests, but doesn't assign them a suite name:

- Property name: "Text" or "Value" for all the text assigned to the object
  Specifiers: `B_DIRECT_SPECIFIER` only
  Messages: `B_SET_PROPERTY` and `B_GET_PROPERTY
  ` Data type: a null-terminated character string (`char *`)

  In other words, it interprets the "Value" property declared by the BControl class to mean the text string (not the label) that the object displays. Its type is therefore `B_STRING_TYPE`, rather than `B_INT32_TYPE` as it is for other control devices. The same data can be specified using "Text" as the property name.

  See "Scripting" in The Application Kit chapter for more on scripting and message suites.

  ## Constructor and Destructor

  ### BTextControl()

            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()` and`SetTarget()` 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()`

  ### ~BTextControl()

            virtual ~BTextControl()

  Frees memory allocated by the BTextControl and its BTextView child.

  ## Static Functions

  ### Instantiate()

            static BTextControl *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()`

  ## Member Functions

  ### 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

  ### AttachedToWindow()

            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()`

  ### Divider() see SetDivider()

  ### Draw()

            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()`

  ### GetAlignment() see SetAlignment()

  ### GetPreferredSize(), ResizeToPreferred()

            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()`

  ### MakeFocus()

            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()`

  ### MessageReceived()

            virtual void MessageReceived(BMessage *message)

  Handles scripting requests for the BTextControl.

  See also: `BHandler::MessageReceived()`

  ### ModificationMessage() see SetModificationMessage()

  ### MouseDown()

            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()`

  ### ResizeToPreferred() see GetPreferredSize()

  ### ResolveSpecifier()

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

  Resolves specifiers for the "Text" and "Value" properties. See Scripting Support in the class overview and "Scripting" in The Application Kit chapter for more information.

  See also: `BHandler::ResolveSpecifier()`

  ### SetAlignment(), GetAlignment()

            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()`

  ### SetDivider(), Divider()

            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

  ### SetEnabled()

            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()`

  ### SetModificationMessage(), ModificationMessage()

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

  ### SetText(), Text()

            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.

  ### TextView()

            BTextView *TextView(void) const

  Returns the child BTextView object that handles the BTextControl's editing chores.

  See also: the BTextView class

  ### WindowActivated()

            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.

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

  The Be Book, in lovely HTML, for BeOS Release 3.

  Copyright © 1998 Be, Inc. All rights reserved.

  Last modified March 26, 1998.