GenValue: 2 GenValue Instance Data

| Up: GEOS SDK TechDocs | Up | Prev: 1 GenValue Features | Next: 3 GenValue Basics

The GenValue contains instance fields that affect the current value, the display units of that value, and the action to take when any value operation has been completed. These instance fields are listed in GenValue Instance Data . Remember, in addition to these instance data variables, there are also the instance fields inherited from the GenValue's superclass, GenClass .

Code Display 8-1 GenValue Instance Data

/* The instance data fields for GenValue are shown below. Those that are records
 * of flags have their default flags shown with other possible flags listed below.
 * Other fields are shown with their default values. */
    @instance WWFixedAsDWord				GVLI_value = MakeWWFixed(0.0);
    @instance WWFixedAsDWord				GVLI_minimum = MakeWWFixed(0.0);
    @instance WWFixedAsDWord				GVLI_maximum = MakeWWFixed(32766);
    @instance WWFixedAsDWord				GVLI_increment = MakeWWFixed(1.0);
    @instance GenValueStateFlags				GVLI_stateFlags = 0;
/* GenValueStateFlags */
    typedef ByteFlags GenValueStateFlags;
    #define GVSF_INDETERMINATE				0x80
    #define GVSF_MODIFIED				0x40
    #define GVSF_OUT_OF_DATE				0x20
    @instance GenValueDisplayFormat 			GVLI_displayFormat = GVDF_INTEGER;
/* GenValueDisplayFormat */
    typedef ByteEnum GenValueDisplayFormat;
    #define GVDF_INTEGER 0
    #define GVDF_DECIMAL 1
    #define GVDF_POINTS 2
    #define GVDF_INCHES 3
    #define GVDF_CENTIMETERS 4
    #define GVDF_MILLIMETERS 5
    #define GVDF_PICAS 6
    #define GVDF_EUR_POINTS 7
    #define GVDF_CICEROS 8
    #define GVDF_POINTS_OR_MILLIMETERS 9
    #define GVDF_POINTS_OR_CENTIMETERS 10
    @instance optr				GVLI_destination;
    @instance Message				GVLI_applyMsg = 0;

GVLI_value is the current numerical value of the GenValue. By default, it is an integer constant defined by the application. Depending on the GVLI_ displayFormat , it can be interpreted as an integer, a decimal, or distance unit.

GVLI_maximum is the maximum possible value that the GenValue may display. This value may be positive or negative. The default value is 32766.

GVLI_minimum is the minimum possible value that the GenValue may display. This value may be positive or negative. The default value is zero.

GVLI_increment is the value to increment (or decrement) the GenValue when its value is changed by UI controls rather than direct text input. The default value is one.

GVLI_ stateFlags specifies the GenValueStateFlags for the GenValue to operate under. These flags affect whether the data within the GenValue is indeterminate (not necessarily true) or modified (changed since the last MSG_GEN_APPLY ).

GVLI_ displayFormat specifies the units of measurement ( GenValueDisplayFormat ) that the numerical value represents. By default, this is an integer, but it could also be a decimal or a unit of measurement (such as inches, points, or centimeters).

GVLI_applyMsg is the message to send out upon GenValue changes (i.e. whenever it receives MSG_GEN_APPLY). There is no default message.

GVLI_destination is the object or process to send the message upon GenValue changes. This can be an optr to an object or a valid TravelOption . See the MetaClass chapter. There is no default destination object.

Code Display 8-2 GenValue Optional Attribute Fields

    @vardata Message			ATTR_GEN_VALUE_STATUS_MSG;
    @vardata word			ATTR_GEN_VALUE_DECIMAL_PLACES;
    @vardata WWFixed			ATTR_GEN_VALUE_METRIC_INCREMENT;
    @vardata void			ATTR_GEN_VALUE_SET_MODIFIED_ON_REDUNDANT_SELECTION;

ATTR_GEN_VALUE_STATUS_MSG sets a status message for a GenValue. A status message allows your object to communicate with other objects when changes occur without sending out its apply message (GVLI_ applyMsg ).

ATTR_GEN_VALUE_DECIMAL_PLACES specifies the number of decimal places to display to the right of the decimal point if the GVLI_ displayFormat allows fractional quantities.

ATTR_GEN_VALUE_METRIC_INCREMENT allows you to specify a particular metric increment to use besides the default if the GVLI_ displayFormat is GVDF_POINTS_OR_MILLIMETERS or GVDF_INCHES_OR_CENTIMETERS.

ATTR_GEN_VALUE_SET_MODIFIED_ON_REDUNDANT_SELECTION specifies that the GenValue should be marked modified whether or not a change in the value has occurred. This will result in that value being applied whenever it receives a MSG_GEN_APPLY . (The default behavior for when no change in state occurs, no message will be sent out.)

Code Display 8-3 GenValue Hints

    @vardata void 			HINT_VALUE_INCREMENTABLE;
    @vardata void 			HINT_VALUE_NOT_INCREMENTABLE;
    @vardata void			HINT_VALUE_NAVIGATE_TO_NEXT_FIELD_ON_RETURN_PRESS;
    @vardata Message			HINT_VALUE_CUSTOM_RETURN_PRESS;
    @vardata WWFixedAsDWord 				HINT_VALUE_DISPLAYS_RANGE;
    @vardata GenValueIntervals				HINT_VALUE_DISPLAY_INTERVALS;
    @vardata void			HINT_VALUE_CONSTRAIN_TO_INTERVALS;
typedef struct {
	word	GVI_numMajorIntervals;
	word	GVI_numMinorIntervals;
} GenValueIntervals;
    @vardata void			HINT_VALUE_SHOW_MIN_AND_MAX;
    @vardata void			HINT_VALUE_IMMEDIATE_DRAG_NOTIFICATION;
    @vardata void			HINT_VALUE_DELAYED_DRAG_NOTIFICATION;
    @vardata void			HINT_VALUE_ORIENT_HORIZONTALLY;
    @vardata void			HINT_VALUE_ORIENT_VERTICALLY;
    @vardata void			HINT_VALUE_ANALOG_DISPLAY;
    @vardata void			HINT_VALUE_DIGITAL_DISPLAY;
    @vardata void			HINT_VALUE_NO_DIGITAL_DISPLAY;
    @vardata void			HINT_VALUE_NO_ANALOG_DISPLAY;
    @vardata void			HINT_VALUE_NOT_DIGITALLY_EDITABLE;
    @vardata void			HINT_VALUE_DO_NOT_MAKE_LARGER_ON_PEN_SYSTEMS;

HINT_VALUE_INCREMENTABLE and HINT_VALUE_NOT_INCREMENTABLE specify whether increment (and decrement) gadgets are appropriate for this GenValue. By default, GenValues are incrementable.

HINT_VALUE_CUSTOM_RETURN_PRESS stores a Message to send out if the user hits return within the textual portion of a GenValue. Normally, this action triggers the interaction default (sending the apply message).

HINT_VALUE_DISPLAYS_RANGE indicates that this GenValue displays a range of values between its minimum and maximum. In most cases, this suggests that the GenValue use sliders or some other UI gadget that is able to show the width of a range. It is up to the specific UI to support range values. If this hint is present, GVLI_ value refers to the starting point of the range of values, whose width is stored in the WWFixedAsDWord value here. The maximum GVLI_ value in this case would be GVLI_ maximum minus the range. If this hint is not present, the range "length" is presumed to be zero, even in gadgets that specify a range length by default.

HINT_VALUE_DISPLAY_INTERVALS indicates that intervals should be displayed along an object's range. This hint is used most often in analog (e.g. slider) type displays. If possible, hash marks will appear along the GenValue's display at the intervals specified by GenValueIntervals . This structure stores entries for both major intervals and minor intervals. In general, minor intervals will have smaller tick marks than major intervals.

typedef struct {
	word GVI_numMajorIntervals;
	word GVI_numMinorIntervals;
} GenValueIntervals;

If either GVI_ numMajorIntervals or GVI_ numMinorIntervals is zero, only one set of marks will appear.

HINT_VALUE_CONSTRAIN_TO_INTERVALS suggests that the value within GVLI_ value constrain itself to the GVI_ numMinorIntervals interval within HINT_VALUE_DISPLAY_INTERVALS.

HINT_VALUE_SHOW_MIN_AND_MAX instructs the GenValue to display its minimum and maximum values, if possible.

HINT_VALUE_IMMEDIATE_DRAG_NOTIFICATION instructs the GenValue to send out its status and/or apply messages constantly during a drag operation (each time the value changes). It is up to the specific UI to support this behavior.

HINT_VALUE_DELAYED_DRAG_NOTIFICATION instructs the GenValue to delay sending out status and/or apply message until the user releases the mouse after the drag operation. It is up to the specific UI to support this behavior.

HINT_VALUE_ORIENT_HORIZONTALLY instructs the specific UI to arrange an analog GenValue, if available, in the horizontal dimension.

HINT_VALUE_ORIENT_VERTICALLY instructs the specific UI to arrange an analog GenValue, if available, in the vertical dimension.

HINT_VALUE_ANALOG_DISPLAY indicates that the GenValue should be displayed in an analog fashion, if applicable. HINT_VALUE_DIGITAL_DISPLAY indicates that the GenValue should be displayed in a digital fashion (i.e. numerically). Similarly, HINT_VALUE_NO_DIGITAL_DISPLAY and HINT_VALUE_NO_ANALOG_DISPLAY indicate that a digital or analog display is not appropriate.

HINT_VALUE_NOT_DIGITALLY_EDITABLE instructs the UI to disallow editing of the text within a numerical GenValue. This hint is only applicable if some other UI means of changing the value is available. To remove a numeric display of values entirely, use HINT_VALUE_NO_DIGITAL_DISPLAY.

HINT_VALUE_DO_NOT_MAKE_LARGER_ON_PEN_SYSTEMS instructs the specific UI to avoid expanding a GenValue object to accept pen input, if possible. By default, text areas of GenValues grow larger under pen systems to allow ink strokes. This hint usually indicates that non-ink means of entering values is available.

| Up: GEOS SDK TechDocs | Up | Prev: 1 GenValue Features | Next: 3 GenValue Basics