GenValue: 4.3 Supplemental Usage: Retrieving Text

MSG_GEN_VALUE_GET_VALUE_TEXT, MSG_GEN_VALUE_SET_VALUE_FROM_TEXT, MSG_GEN_VALUE_GET_MAX_TEXT_LEN, MSG_GEN_VALUE_SET_MAX_TEXT_LEN, MSG_GEN_VALUE_SELECT_TEXT

The GenValue's numeric values are displayed within a special text field. In addition to retrieving the numeric value of the GenValue, you may also retrieve the textual representation of that number with MSG_GEN_VALUE_GET_VALUE_TEXT . Similarly, you can set the value of the GenValue from a textual representation with MSG_GEN_VALUE_SET_VALUE_FROM_TEXT .

You must pass these messages a GenValueType which specifies the instance data field you are wishing to set or get. The GenValueType types are:

typedef enum /* word */ {
	GVT_VALUE,			/* GVLI_value */
	GVT_MINIMUM,			/* GVLI_minimum */
	GVT_MAXIMUM,			/* GVLI_maximum */
	GVT_INCREMENT		,	/* GVLI_increment */
	GVT_LONG,			/* Longest value we can
				 * create. */
	GVT_RANGE_LENGTH,			/* End of the displayed
				 * range, if applicable. */
	GVT_RANGE_END,			/* Last value in the range,
				 * if applicable. */
	GVT_VALUE_AS_RATIO_OF_AVAILABLE_RANGE
				/* The current value, 
				 * relative to minimum. */
} GenValueType;

Some special subclasses of the GenValue will want to calculate how many characters it will allow the user to type into its text field. By default, the number of characters is determined by the maximum and minimum values, but subclasses can handle MSG_GEN_VALUE_GET_MAX_TEXT_LEN to set it specifically. This message is sent by the range to itself when deciding how big the text field should be. The maximum text length allowed is thirty characters long.

If you wish to select a GenValue's text, send the GenValue MSG_GEN_VALUE_SELECT_TEXT. The specific UI has final say on whether it allows a GenValue to exhibit selectable text.

MSG_GEN_VALUE_GET_VALUE_TEXT

void	MSG_GEN_VALUE_GET_VALUE_TEXT(
        char		*buffer,
        GenValueType		valueType);

This message retrieves a fixed point value (either GVLI_value , GVLI_minimum , GVLI_maximum , or GVLI_increment ) from the GenValue and stores its textual representation (in a null-terminated text string) in the passed buffer. This message is not affected by the indeterminate state of the GenValue.

Source: Unrestricted.

Destination: Any GenValue object.

Parameters: buffer The pointer to the buffer to store the null-terminated text string. This buffer must be at least GEN_VALUE_MAX_TEXT_LEN bytes long.

valueType: The GenValueType , specifying the instance data to retrieve and convert into text.

Return: Nothing. The buffer will be filled in with text.

Interception: Can be intercepted by a subclass of GenValue to allow custom text formats to be displayed on the screen. In this case you would also subclass MSG_GEN_VALUE_SET_VALUE_FROM_TEXT .

MSG_GEN_VALUE_SET_VALUE_FROM_TEXT

void	MSG_GEN_VALUE_SET_VALUE_FROM_TEXT(
        char		*text,
        GenValueType		valueType);

This message sets a fixed point value (either GVLI_value , GVLI_minimum , GVLI_maximum , or GVLI_increment ) of the GenValue from a textual representation (in a null-terminated text string) in the passed buffer. This message clears the indeterminate state of the GenValue but does not change its modified state.

Source: Unrestricted.

Destination: Any GenValue object.

Parameters: text The pointer to a null-terminated text string to set the GenValue's text to.

valueType: The GenValueType , specifying the instance data to convert into a fixed point value from the passed text.

Return: Nothing. The instance field will be updated.

Interception: Can be intercepted by a subclass of GenValue to allow custom text formats to be displayed on the screen. In this case, you would also subclass MSG_GEN_VALUE_GET_VALUE_TEXT .

MSG_GEN_VALUE_GET_MAX_TEXT_LEN

byte	MSG_GEN_VALUE_GET_MAX_TEXT_LEN();

This message retrieves the maximum number of characters allowed to be typed into a textual GenValue. By default, this number is calculated from the minimums and maximums specified. Subclasses of GenValue may wish to intercept this message to allow different text lengths (such as values represented with floating point or enumerated type instance data).

Source: The GenValue object sends this to itself when it needs to figure out its maximum text length.

Destination: Itself.

Return: Maximum number of allowable characters

Interception: May be intercepted to allow different text lengths.

MSG_GEN_VALUE_SELECT_TEXT

void	MSG_GEN_VALUE_SELECT_TEXT();

This message selects a GenValue's text, if allowed by the specific UI.

Source: Unrestricted.

Destination: Any GenValue object.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

4.2 Status Messages | Next:

4.4 Using Value Ratios