Class: TTextControl

Declaration: TextControl.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TContentView, MMouseEventHandler, MControl, MDelegatingTextControl

Inherited By:

None.

Purpose:

TTextControl provides the protocol for presenting an editable text field in a box with, optionally, a label. TTextControl derives from TContentView, from MControl, which provides the layout features, from MMouseEventHandler, which allows the control to be activated by mouse downs, and from MDelegatingTextControl, which provides protocol for manipulating the text field data. TTextControl needs an object of an MTextControlState derived class at construction. The text control adopts this control state object, which then maintains the text state data. By default, TTextControl uses an object of TSimpleTextControlState, which maintains the text state data in an object of TSimpleTextStore.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class is designed to be used directly.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TTextControl::~TTextControl

virtual ~ TTextControl ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Typically not called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::operator=

TTextControl & operator =(const TTextControl &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

May be called directly by clients.

Parameters:

const TTextControl & -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

May be called directly by clients.

Parameters:

TStream & -The stream this object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

May be called directly by clients.

Parameters:

TStream & -The stream this object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the object has detected an unsupportable version during the stream-in process.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::AdoptLabel

virtual void AdoptLabel (TLabel * label)

Interface Category:

API.

Purpose:

Specifies a label for this text control to adopt and display.

Calling Context:

May be called directly by clients.

Parameters:

TLabel * label -The label for this text control to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::OrphanLabel

virtual TLabel * OrphanLabel ()

Interface Category:

API.

Purpose:

Orphans this control's label by removing the reference and marking the layout as invalid.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the orphaned label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::GetLabel

virtual TLabel * GetLabel () const

Interface Category:

API.

Purpose:

Returns a pointer to the current label.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the current label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::GetGap

virtual GCoordinate GetGap () const

Interface Category:

API.

Purpose:

Returns the current gap between the label and the text field.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

The label gap of this control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetGap

virtual void SetGap (GCoordinate gap)

Interface Category:

API.

Purpose:

Sets the gap between the label and the text field.

Calling Context:

May be called directly by clients.

Parameters:

GCoordinate gap -The coordinate to set as the gap between the label and text field for this control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::GetTextBorderThickness

virtual GCoordinate GetTextBorderThickness () const

Interface Category:

API.

Purpose:

Gets the coordinate representing the thickness of the border around the text field for this text control.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

The thickness of the border around the text field.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetTextBorderThickness

virtual void SetTextBorderThickness (GCoordinate thickness)

Interface Category:

API.

Purpose:

Sets a value representing the thickness of the border around the text field.

Calling Context:

May be called directly by clients.

Parameters:

GCoordinate thickness -The thickness of the border around the text field.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::AdoptState

virtual void AdoptState (MTextControlState * state)

Interface Category:

API.

Purpose:

Adopts the specified object as the current text control state. Any existing text control state is replaced, as the control can only maintain a single control state at a time.

Calling Context:

May be called directly by clients.

Parameters:

MTextControlState * state -The control state object to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetState

virtual void SetState (MTextControlState * state)

Interface Category:

API.

Purpose:

Sets a control state object for this control which is not adopted. Any existing text control state is replaced, as the control can only maintain a single control state at a time.

Calling Context:

May be called directly by clients.

Parameters:

MTextControlState * state -The control state object to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetAllocatedArea

virtual void SetAllocatedArea (const TGArea & area)
virtual void SetAllocatedArea (const TGRect & area)

Interface Category:

API.

Purpose:

Sets the allocated area for this control. This function overrides the inherited function from the View system. It calls the inherited function, and marks the layout as invalid.

Calling Context:

May be called directly by clients.

Parameters:

const TGArea & area -The new area for the control.
const TGRect & area -The new area for the control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::GetPreferredSize

virtual TGPoint GetPreferredSize (GCoordinate maximumMainDimension =kInfinity) const

Interface Category:

API.

Purpose:

Returns the minimum size required by this control to display the label and text field.

Calling Context:

May be called directly by clients.

Parameters:

GCoordinate maximumMainDimension =kInfinity -Parameter defined by MControl but currently ignored.

Return Value:

Returns the preferred size for this control.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetControlLayout

virtual void SetControlLayout (ELayout layout)

Interface Category:

API.

Purpose:

Sets the layout for the control (left-to-right, top-to-bottom, and so on). Calls the function inherited from MControl and marks the layout invalid.

Calling Context:

May be called directly by clients. control.

Parameters:

ELayout layout -Determines the layout of the control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::Deactivate

virtual void Deactivate ()

Interface Category:

API.

Purpose:

Deactivates this control.

Calling Context:

May be called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::DrawContents

virtual void DrawContents (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws this control.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

TGrafPort & -The graf port into which to draw.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextControl::Layout

virtual void Layout ()
virtual void Layout (const TGRect & actualBounds, TGRect & textBoxBounds, TGRect & labelBounds) const

Interface Category:

API.

Purpose:

Lays out this control. If the text box has been created, this function calls Layout #2 to get the appropriate text box bounds and label bounds, and SetAllocatedArea to set the new preferred size.
Calculates the layout (the appropriate text box bounds and label bounds), given the bounds of the control. This function takes into consideration the layout set in SetControlLayout.

Calling Context:

Called by the Text Framework classes. Typically not called directly by clients.
Called by the Text Framework classes. Typically not called directly by clients.

Parameters:

Takes no parameters.
const TGRect & actualBounds -The bounds within which to layout the control. If this parameter is 0, the function assumes a preferred size layout.
TGRect & textBoxBounds -The bounds for the text field.
TGRect & labelBounds -The bounds for the label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextControl::GetLayout

virtual void GetLayout (TGRect & textBoxBounds, TGRect & labelBounds) const

Interface Category:

API.

Purpose:

Returns layout information calculated by the Layout function.

Calling Context:

May be called directly by clients.

Parameters:

TGRect & textBoxBounds -The bounds for the text field.
TGRect & labelBounds -The bounds for the label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextControl::OrphanBehavior

virtual MEventTarget * OrphanBehavior (MEventTarget * aBehavior)

Interface Category:

API.

Purpose:

Orphans the current event target object behavior. If the text box has been created, this function returns the result of calling the text box object's OrphanBehavior function. Otherwise, this function returns NIL. It does not delete the event target object.

Calling Context:

May be called directly by clients.

Parameters:

MEventTarget * aBehavior -The event target behavior to be orphaned.

Return Value:

Returns a pointer to the orphaned event target object; if the event target was not adopted, or the text box has not been created, returns NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::AdoptBehavior

virtual void AdoptBehavior (MEventTarget * aBehavior)

Interface Category:

API.

Purpose:

Adopts the specified event target object as a behavior. If the text box has been created, this function calls the text box object's AdoptBehavior function. Otherwise, it does nothing.

Calling Context:

May be called directly by clients.

Parameters:

MEventTarget * aBehavior -The event target object to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SelectText

virtual void SelectText (const TTextRange & range =TTextRange :: GetMaximumRange ())

Interface Category:

API.

Purpose:

Selects the text in the specified range. If the upper bound of the range is beyond the actual text length, uses the end of the text as the upper bound of the selection.

Calling Context:

May be called directly by clients.

Parameters:

const TTextRange & range =TTextRange :: GetMaximumRange () -The range for the text to be selected (default: the maximum range, to select all the text).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetAllocatedAreaInParent

virtual void SetAllocatedAreaInParent (const TGArea & area)

Interface Category:

API.

Purpose:

Sets the allocated area for this control's parent. This function overrides the inherited function from the View system. It calls the inherited function, and marks the layout as invalid.

Calling Context:

May be called directly by clients.

Parameters:

const TGArea & area -The new area for the control's parent.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetTextState

virtual void SetTextState (const TText & newText)

Interface Category:

API.

Purpose:

Calls the inherited MDelegatingTextControl function to set the text data for this text control state, replacing any existing text.

Calling Context:

May be called directly by clients.

Parameters:

const TText & newText -The new text data for the control.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Overrides inherited MDelegatingTextControl function.

Member Function: TTextControl::SetInitialTextStyles

virtual void SetInitialTextStyles (const TStyleSet & initialStyles)

Interface Category:

API.

Purpose:

Sets the initial styles for the control's text to the specified styles. These initial styles are used as the typing styles in an empty control. Note that these styles are applied to new text programmatically inserted into the control via the AdoptState, SetState, or SetTextState member functions.

Calling Context:

May be called directly by clients.

Parameters:

const TStyleSet & initialStyles -The initial styles.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::GetInitialTextStyles

virtual void GetInitialTextStyles (TStyleSet & initialStyles) const

Interface Category:

API.

Purpose:

Gets the initial styles to be used for the control's text.

Calling Context:

May be called directly by clients.

Parameters:

TStyleSet & initialStyles -Receives the initial styles.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::EnableTextMenus

virtual void EnableTextMenus (TWindowGroup & windowGroupForMenus)

Interface Category:

API.

Purpose:

Creates and lays out the text menus. Makes a window for the menus, adopts the window into the provided windowgroup, and opens the window.

Calling Context:

May be called directly by clients.

Parameters:

TWindowGroup & windowGroupForMenus -The windowgroup to adopt the text menu window.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::IsActive

virtual bool IsActive () const

Interface Category:

API.

Purpose:

Determine if this is active or not.

Calling Context:

May be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this is active, otherwise false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::Activate

virtual bool Activate ()

Interface Category:

API.

Purpose:

Activate this text control.

Calling Context:

May be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this was activated.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::SetEnabled

virtual void SetEnabled (bool enable)

Interface Category:

API.

Purpose:

Set the enabled state of this.

Calling Context:

May be called directly.

Parameters:

bool enable -The enabled state to set this to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::IsEnabled

virtual bool IsEnabled () const

Interface Category:

API.

Purpose:

Determine if this is enabled or not.

Calling Context:

May be called directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this is enabled, otherwise return false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextControl::TTextControl

TTextControl (MTextControlState * state, TLabel * label =NIL, MEventTarget * filter =NIL)
TTextControl (const TTextControl & copy)
TTextControl ()

Interface Category:

API.

Purpose:

Main constructor.
Copy constructor.
Default constructor.

Calling Context:

Called to construct an object with a control state, optional label and filter.
Called to copy an object.
Called by the stream-in operators and

Parameters:

MTextControlState * state -Pointer to text control state to adopt.
TLabel * label =NIL -Pointer to label to adopt.
MEventTarget * filter =NIL -Obsolete parameter. Do not use. Use ::AdoptBehavior member function after construction.
const TTextControl & copy -The object to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.