GenValue: 3.5 GenValue Basics: Display Formats

| Up: GEOS SDK TechDocs | Up | Prev: 3.4 GenValue States | Next: 3.6 Sending an Action 
GVLI_displayFormat, MSG_GEN_VALUE_SET_DISPLAY_FORMAT, MSG_GEN_VALUE_GET_DISPLAY_FORMAT, ATTR_GEN_VALUE_METRIC_EQUIVALENT, ATTR_GEN_VALUE_DECIMAL_PLACES

In addition to displaying an integer numerical value, a GenValue may also display numerical values of several other formats. These formats may be any one of the GenValueDisplayFormat enumerations provided in GenValueClass . The allowed enumerations of type GenValueDisplayFormat are:

GVDF_INTEGER
GVDF_DECIMAL
GVDF_POINTS
GVDF_INCHES
GVDF_CENTIMETERS
GVDF_MILLIMETERS
GVDF_PICAS
GVDF_EUR_POINTS
GVDF_CICEROS
GVDF_POINTS_OR_MILLIMETERS
GVDF_INCHES_OR_CENTIMETERS

GVLI_ displayFormat controls how the values of the GenValue will be represented. For example, if the display format is in centimeters, the display will include the text "cm" after the numerical value; if the display includes a fractional part, a decimal point will be present. These display formats will also convert the values (which are stored as points) into the proper distance units for the textual display.

By default, the value's fractional portion will be displayed using 3 places to the right of the decimal point. You may alter this number of places with ATTR_GEN_VALUE_DECIMAL_PLACES. You may only choose a number of decimal places between zero to four (inclusive), because of the limited text space offered within a GenValue.

Your GenApplication object contains instance data which specifies whether the application is being run under US or metric units. This setting may affect the display of your units depending on the particular GenValueDisplayFormat .

GVDF_INTEGER displays the value as an integer (the high word of the fixed point value) and ignores any fractional part.
GVDF_DECIMAL displays the value as a decimal value.
GVDF_POINTS displays the value in points (1/72 of an inch) regardless of whether metric or US units are specified for the application.
GVDF_INCHES displays the value in inches regardless of whether metric or US units are specified for the application.
GVDF_CENTIMETERS displays the value in centimeters regardless of whether metric or US units are specified for the application.
GVDF_MILLIMETERS displays the value in millimeters regardless of whether metric or US units are specified for the application.
GVDF_PICAS displays the value as a distance in picas. One pica is equal to 12 US Points, or 1/6 of an inch.
GVDF_EUR_POINTS displays the value as a distance in European Points. One european point is about equal to 1.0656 US Points.
GVDF_CICEROS displays the value as a distance in Ciceros. One Cicero is equal to 12 European Points.
GVDF_POINTS_OR_MILLIMETERS and GVDF_INCHES_OR_CENTIMETERS are special cases. These display formats display the value in points (or inches) if US units are specified for the application; the value will be represented in millimeters (or centimeters) if metric units are instead specified.

Importantly, all distance units (inches, picas, centimeters, etc.) store their values as Points (1/72 inch). The system automatically converts these values (in Points) into the proper units of the GenValue's GVLI_ displayFormat when it displays the numerical value within the textual display.

Code Display 8-6 Setting a Distance Display Format

@object GenValueClass MyValue = {
    GI_visMoniker = "My Value";
    GVLI_displayFormat = GVDF_INCHES;
/* For an initial value of 1 inch, the equivalent value in Points is 72. */
    GVLI_value = MakeWWFixed(72.0);
/* For an initial value of 1/2 inch, the equivalent value in Points is 36. */
    GVLI_increment = MakeWWFixed(36.0);
}

For example, if your display format is GVDF_INCHES and you wish to set an initial value of 1 inch and an increment of 1/2 an inch, you should set these values to 72 (points which equals 1 inch) and 36 (points which equals one-half inch) respectively. This is necessary because the system expects these values to be in Points for other system operations. A conversion table is provided below.

Any increments for GVDF_POINTS_OR_MILLIMETERS or GVDF_INCHES_OR_CENTIMETERS are assumed to be in US units. If the application instead operates in metric, the increment will be automatically converted to a metric equivalent by the system; this metric equivalent will usually be rounded to a convenient numerical value. You may specify an ATTR_GEN_VALUE_METRIC_EQUIVALENT to override the default increment that the system calculates, however.

For example, assume GVDF_INCHES_OR_CENTIMETERS is selected and the value and increment are 72 (points which equals 1 inch). If the application is in US units, the display will specify inches and the value and increment will be 72 (1 inch); if the application is instead in metric, the display will specify centimeters and the increment will be 70.866 (2.5 cm). If instead, you choose an ATTR_GEN_VALUE_METRIC_INCREMENT of 52.692 (2 cm), that will be the increment used if the application is metric.

Code Display 8-7 ATTR_GEN_VALUE_METRIC_INCREMENT

/* If the application is US, the initial value will be 1 inch and the increment 
 * will be 1 inch. If the application is metric, the initial value will be 2.54 cm
 * (1 inch or 72 points) but the increment will be 2.0 cm (56.692 points). If
 * ATTR_GEN_VALUE_METRIC_INCREMENT were not included, the system would have chosen
 * an increment of 2.5 cm (70.866 points) which is the closest "nice" value to the
 * original increment of 72 points (1 inch). */
@object GenValueClass MyValue = {
    GI_visMoniker = "My Value";
    GVLI_displayFormat = GVDF_INCHES_OR_CENTIMETERS;
    GVLI_value = MakeWWFixed(72.0);
    GVLI_increment = MakeWWFixed(72.0);
    ATTR_GEN_VALUE_METRIC_INCREMENT = MakeWWFixed(56.692);
}

To set a new display format, send MSG_GEN_VALUE_SET_DISPLAY_FORMAT . To retrieve the current display format, send the GenValue MSG_GEN_VALUE_GET_DISPLAY_FORMAT . Note that changing the display format will not change the numerical value of that display. For example, if the display format changes from decimal to integer, the GenValue will round the number down and display only the integer portion of the value.

MSG_GEN_VALUE_GET_DISPLAY_FORMAT

GenValueDisplayFormat MSG_GEN_VALUE_GET_DISPLAY_FORMAT();

This message returns the GVLI_ displayFormat field of the GenValue.

Source: Unrestricted.

Destination: Any GenValue object.

Parameters: None.

Return: GenValueDisplayFormat of the GenValue.

Interception: Generally not intercepted.

MSG_GEN_VALUE_SET_DISPLAY_FORMAT

void	MSG_GEN_VALUE_SET_DISPLAY_FORMAT(
        GenValueDisplayFormat			format);

This message sets the GVLI_displayFormat of the GenValue to the given format. The current value in GVLI_ value is unaffected, but the display will be updated to reflect the new display format.

Source: Unrestricted. This message is also used internally when the GenValue is being built.

Destination: Any GenValue object.

Parameters: format GenValueDisplayFormat to set the GenValue to.

Return: Nothing.

Interception: Generally not intercepted.

| Up: GEOS SDK TechDocs | Up | Prev: 3.4 GenValue States | Next: 3.6 Sending an Action