The Text Objects: 6.2 Using GenText: GenText Basics

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 GenText Instance Data | Next: 7 The Controllers

The GenText instance fields can be set to specific values in your Goc files. They may also be modified by your application at run-time. These instance fields may be modified by both GenTextClass messages or VisTextClass messages.

GenTextClass always builds out into a completely functioning subclass of VisTextClass . With the exception of geometry management behavior, you can assume that they will behave the same. You may send any VisTextClass message to a GenText object. Messages are only provided in GenTextClass to manipulate and alter behavior solely of GenTextClass origins.

VisText Instance Fields

The chunk handle stored in GTXI_ text is copied to the VisText instance field VTI_ text at run-time. To perform operations on this text, you may use any of the VisTextClass messages in The Text . Similarly, the text object maximum length stored in GTXI_ maxLength is copied to VTI_ maxLength at run-time. To perform operations on this data, use an appropriate message under Using VisText .

GenText Attributes

GTXI_attrs, MSG_GEN_TEXT_SET_ATTRS, MSG_GEN_TEXT_GET_ATTRS

GTXI_ attrs stores the GenTextAttrs of the GenText object. These attribute flags are listed below.

GTA_SINGLE_LINE_TEXT
This flag indicates that this text object is only one line high. Vertical scrolling is disabled. Scrolling may be implemented horizontally if this is set.
GTA_USE_TAB_FOR_NAVIGATION
This flag indicates that the Tab key is used for navigation purposes in your application and should be interpreted to move to the next field rather than inserted into the text object.
GTA_INIT_SCROLLING
This flag indicates that the text object should appear with initial scrollbars.
GTA_NO_WORD_WRAPPING
This flag disables word wrapping.
GTA_ALLOW_TEXT_OFF_END
This flag is set if text may be allowed to overflow past the end of the text box. The text will still be stored in the object's text chunk, but it will not force horizontal (or vertical) scrolling to show the text on-screen.
GTA_TAIL_ORIENTED
This flag is set if you prefer to display the tail end of text rather than the top end. In a scrolling text box, this ensures that the text being added at the end is always displayed.
GTA_DONT_SCROLL_TO_CHANGES
This flag disables the default behavior of scrolling to any changes being made within the text object. Normally, insertion or deletion of text will force a scrolling GenText to scroll to the point of action; this flag will turn this behavior off.

You may alter the contents of a GenText's GTXI_ attrs instance field at run-time by sending the object a MSG_GEN_TEXT_SET_ATTRS . You may only send this message to a non-usable (~GS_USABLE) text object. To retrieve the current GenTextAttrs in use, send the text object MSG_GEN_TEXT_GET_ATTRS .

MSG_GEN_TEXT_SET_ATTRS

void	MSG_GEN_TEXT_SET_ATTRS(
        byte	attrsToSet,
        byte	attrsToClear);

This message sets a GenText object's GenTextAttrs (GTXI_ attrs ). The GenText object must not be GS_USABLE when sent this message.

Source: Unrestricted.

Destination: Any non-usable GenText object.

Parameters: attrsToSet GenTextAttrs to add.

attrsToClear
GenTextAttrs to remove. An attribute set in both parameters will be cleared.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_TEXT_GET_ATTRS

byte	MSG_GEN_TEXT_GET_ATTRS();

This message retrieves the GenText object's GenTextAttrs (GTXI_ attrs ).

Source: Unrestricted.

Destination: Any GenText object.

Parameters: None.

Return: GenTextAttrs in use by the GenText object( GTXI_attrs ).

Interception: Generally not intercepted.

GenTextStates

GTXI_stateFlags, MSG_GEN_TEXT_SET_INDETERMINATE_STATE, MSG_GEN_TEXT_SET_MODIFIED_STATE, MSG_GEN_TEXT_IS_INDETERMINATE, MSG_GEN_TEXT_IS_MODIFIED

GTXI_ stateFlags stores the current state of the GenText object. There are two GenTextStateFlags :

GTSF_INDETERMINATE
This flag specifies that the text within the GenText is indeterminate (may or may not reflect the current state). In most cases, you will not need to set this flag.
GTSF_MODIFIED
This flag specifies that the text within the GenText has changed since it last received a MSG_GEN_APPLY . The handler for MSG_GEN_APPLY checks whether this flag is set before sending out the GenText's GTXI_ applyMsg .

GenText objects should normally be marked by the application as not modified anytime their state is set with an external message. They will automatically be marked modified whenever the user interacts with them and marked not modified after receiving MSG_GEN_APPLY .

You may set a GenText's indeterminate or modified state with MSG_GEN_TEXT_SET_INDETERMINATE_STATE or MSG_GEN_TEXT_SET_MODIFIED_STATE , respectively. To check whether a GenText is indeterminate or modified, use MSG_GEN_TEXT_IS_INDETERMINATE or MSG_GEN_TEXT_IS_MODIFIED .

MSG_GEN_TEXT_SET_INDETERMINATE_STATE

void	MSG_GEN_TEXT_SET_INDETERMINATE_STATE(
        Boolean indeterminateState);

This message sets the GenText object's indeterminate state (the GTSF_INDETERMINATE flag in GTXI_ stateFlags ). This message does not affect the stored text.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: indeterminateState
True to set the text object indeterminate (GTSF_INDETERMINATE); false otherwise.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_TEXT_SET_MODIFIED_STATE

void	MSG_GEN_TEXT_SET_MODIFIED_STATE(
        Boolean modifiedState);

This message allows you to set the modified state of a GenText object (the GTSF_MODIFIED flag in GTXI_ stateFlags ). This message does not affect the stored text.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: modifiedState True to set the text object modified (GTSF_MODIFIED); false otherwise.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_TEXT_IS_INDETERMINATE

Boolean	MSG_GEN_TEXT_IS_INDETERMINATE();

This message checks whether a GenText object is indeterminate in state.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: None.

Return: The indeterminate state of the GenText object ( true if the object is indeterminate, false otherwise).

Interception: Generally not intercepted.

MSG_GEN_TEXT_IS_MODIFIED

Boolean	MSG_GEN_TEXT_IS_MODIFIED();

This message checks whether a GenText object has been modified.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: None.

Return: The modified state of the GenText object ( true if the object has been modified, false otherwise).

Interception: Generally not intercepted.

Sending an Action

GTXI_applyMsg, GTXI_destination, MSG_GEN_TEXT_GET_DESTINATION, MSG_GEN_TEXT_SET_DESTINATION, MSG_GEN_TEXT_GET_APPLY_MSG, MSG_GEN_TEXT_SET_APPLY_MSG

GTXI_ applyMsg holds the message for the GenText to send out whenever it has been modified and needs to apply its changes. Whenever a GenText receives MSG_GEN_APPLY , it checks whether its GTSF_MODIFIED flag has been set; if it has, it will send out its apply message. If a GenText is operating in immediate mode, these actions will happen immediately, resulting in an immediate action.

Use the prototype GEN_TEXT_APPLY_MSG to define your apply message. This ensures that the apply message passes the correct parameters (the current GenTextStateFlags ). GTXI_ destination specifies the destination object (or process) to send the GTXI_ applyMsg to. (This may also be a TravelOption such as TO_APP_FOCUS.) Use of these two fields is shown in Sending an Apply Message .

Code Display 10-24 Sending an Apply Message

	/* Define the apply message using the provided prototype. */
@message (GEN_TEXT_APPLY_MSG) MSG_MY_TEXT_STUFF_TEXT_IN_BUFFER;
	/* In the object declaration, set the destination and the apply message. */
@object GenTextClass MyText = {
    GI_visMoniker = "My Text Object";
    GTXI_text = "Initial Text Here";
    GTXI_maxLength = 99;
    GTXI_applyMsg = MSG_MY_TEXT_STUFF_TEXT_IN_BUFFER;
    GTXI_destination = process;
}
/* Retrieve the current text and place it in the indicated buffer. */
@method MyTextProcessClass, MSG_MY_TEXT_STUFF_TEXT_IN_BUFFER {
    char tempBuffer[100];
/* The GET_ALL_PTR retrieves the current text and stuffs at the location it in the
 * passed pointer. Pass a text length of zero for null-terminated text strings. */
    @call MyText::MSG_VIS_TEXT_GET_ALL_PTR(tempBuffer);
}

To change a GenText's apply message or destination, send it MSG_GEN_TEXT_SET_APPLY_MSG or MSG_GEN_TEXT_SET_DESTINATION , respectively. Use MSG_GEN_TEXT_GET_APPLY_MSG or MSG_GEN_TEXT_GET_DESTINATION to return the current apply message or destination.

MSG_GEN_TEXT_SET_APPLY_MSG

void	MSG_GEN_TEXT_SET_APPLY_MSG(
        Message		message);

This message sets a new apply message (GTXI_ applyMsg ) for the text object.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: message The new apply message.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_TEXT_GET_APPLY_MSG

Message	MSG_GEN_TEXT_GET_APPLY_MSG();

This message retrieves the current apply message (GTXI_ applyMsg ) of a GenText object.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: None.

Return: The apply message of the GenText object.

Interception: Generally not intercepted.

MSG_GEN_TEXT_SET_DESTINATION

void	MSG_GEN_TEXT_SET_DESTINATION(
        optr	dest);

This message sets the destination object or process (GTXI_ destination ) of a GenText object.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: dest The optr of the new destination object or process.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_TEXT_GET_DESTINATION

optr	MSG_GEN_TEXT_GET_DESTINATION();

This message returns the current destination object (GTXI_ destination ) of a GenText object.

Source: Unrestricted.

Destination: Any GenText object.

Parameters: None.

Return: The optr of the GenText's destination object (GTXI_ destination ).

Interception: Generally not intercepted.

GEN_TEXT_APPLY_MSG

void	GEN_TEXT_APPLY_MSG(
        word	stateFlags);

This prototype should be used to define your GenText's apply message (with GTXI_ applyMsg ).

Parameters: stateFlags The text object's GTXI_ stateFlags status.

Status Messages

ATTR_GEN_TEXT_STATUS_MSG, MSG_GEN_TEXT_SEND_STATUS_MSG

If your GenText is operating in delayed mode, there usually occur times when its current state may not reflect the most recent changes. In most cases, this is fine, but in some cases you may wish to notify other UI objects of a change in your GenText's state without sending out an apply message. This can be done with a status message .

A status message allows your GenText object to send out a message whenever the user interacts with the text object, regardless of whether that change will be immediately applied. This is most useful for cases in which two UI objects depend on each other. The status message allows one UI object to inform its counterpart that its state has changed, and that the counterpart should change its state to reflect the new information.

To give a GenText object a status message, include ATTR_GEN_TEXT_STATUS_MSG in the object's declaration. Use the prototype GEN_TEXT_STATUS_MSG to define your status message. This prototype ensures that the status message passes the correct parameters (the current GenTextStateFlags ).

Any user changes that do not result in the sending of the object's apply message will result in the sending of the object's status message. For an object in immediate mode, this attribute will have no effect. You may also manually send an object's status message by sending the GenText object MSG_GEN_TEXT_SEND_STATUS_MSG .

MSG_GEN_TEXT_SEND_STATUS_MSG

void	MSG_GEN_TEXT_SEND_STATUS_MSG(
        Boolean		modifiedState);

This message causes a GenText object to send out its status message, stored in the text object's ATTR_GEN_TEXT_STATUS_MSG vardata field. This message will still function even if the text object is not enabled (or usable).

Source: Unrestricted.

Destination: Any GenText object.

Parameters: modifiedState Non-zero if GVSF_MODIFIED bit should be passed with the status message.

Return: Nothing.

Interception: Generally not intercepted.

GEN_TEXT_STATUS_MSG

void	GEN_TEXT_STATUS_MSG(
        word	stateFlags);

This prototype should be used to define your GenText's status message (with ATTR_GEN_TEXT_STATUS_MSG).

Parameters: stateFlags The text object's GTXI_ stateFlags status.

| Up: GEOS SDK TechDocs | Up | Prev: 6.1 GenText Instance Data | Next: 7 The Controllers