Property Attributes

Property attributes are values associated with a property that affect the way the property is displayed in the iTool property sheet interface. Attributes could be considered properties-of-properties; as with actual properties, special methods are used to get and set attribute values.

Note
A property must be registered in order to set or retrieve attribute values.

Property attributes can be set in the call to the IDLitComponent::RegisterProperty method; simply include the attribute name and its value as a keyword-value pair.

If a property has already been registered, you can change the registered attribute values using the SetPropertyAttribute method of the IDLitComponent class:

self->SetPropertyAttribute, PropertyIdentifier, ATTRIBUTE = value

where PropertyIdentifier is a string that uniquely identifies the property, ATTRIBUTE is one of the property attributes described in Available Property Attributes, and value is the attribute value. See Property Identifiers for a discussion of property identifier strings.

A typical property attribute modification call looks like the following:

self->SetPropertyAttribute, 'COLOR', NAME = 'Surface color'

Here, we change the Name attribute of the COLOR property; when this property is displayed in a property sheet, the label will be Surface color.

See "IDLitComponent::SetPropertyAttribute" (IDL Reference Guide) for additional details.

Available Property Attributes

Every registered iTool property has the following attributes. Property attributes can be specified as keywords to the RegisterProperty method of the IDLitComponent class. Attributes whose names are followed by the word "Get" can be retrieved using the GetPropertyAttribute method of the IDLitComponent class; attributes whose names are followed by the word "Set" can be set using the SetPropertyAttribute method.

DESCRIPTION (Get, Set)

A string value containing a text description of the property. This string is displayed in the property sheet interface.

ENUMLIST (Get, Set)

An array of string values to be displayed in the property sheet interface as an enumerated list. This property type allows the user to select a string value from a dropdown list in the user interface, but returns the integer index of the selected item as the value of the property. This attribute is only used by properties of TYPE = 9 (enumerated list).

HIDE (Get, Set)

A Boolean flag that specifies whether the property should be displayed in the property sheet interface.

NAME (Get, Set)

A string value that is displayed as the property name in the property sheet interface. If the NAME attribute is not specified in the call to the RegisterProperty method, this attribute will be set to the property identifier string.

PROPERTY_IDENTIFIER (Get)

A string value containing the property identifier. See Property Identifiers for details.

SENSITIVE (Get, Set)

A Boolean flag that specifies whether the property should be editable by the user when displayed in the property sheet interface. Properties with the SENSITIVE attribute set to 0 are displayed, but are dimmed and are not editable.

TYPE (Get)

The property data type code for the property. See Property Data Types for details.

UNDEFINED (Get, Set)

A Boolean flag that indicates that the property should appear as a blank cell when displayed in the property sheet interface. This is useful in situations where properties of multiple objects are displayed in the property sheet (either because multiple objects are selected, or because the objects have been grouped).

Note
The iTool developer is responsible for setting this property attribute back to zero. Use the SET_DEFINED field of the WIDGET_PROPERTYSHEET event structure to determine when to set the UNDEFINED attribute back to zero.

USERDEF (Get, Set)

A string that represents the value of a user-defined property. See User Defined Property Types for details.

VALID_RANGE (Get, Set)

For integer or float types (TYPE = 2 or TYPE = 3), set this keyword to a two- or three-element vector specifying the [minimum, maximum] or [minimum, maximum, increment] for valid values of the property.

What is displayed for the property sheet number cell depends upon the following:

If this attribute is not specified — the property sheet displays an editable text field where masked editing is enforced, and the range is that of the data type. The only accepted keystrokes are the ten digits, and the plus and minus signs. If the float type is specified, the decimal, and "d" and "e" (scientific exponent notation tokens) are also allowed.

If a range is specified without an increment — the property sheet displays a spinner control that allows the user to click, or click and hold the up or down buttons to change the value. For an integer type, the increment is one. For a float type, the increment equals approximately 1/100 of the range. For example, a range of 100 results in an increment of 1. A value is snapped to the nearest allowable value when a value outside the range, or not equal to an incremental value, is entered. The editable text field (featuring masked editing) also allows the user to enter a numerical value.

If a range and increment are specified — the property sheet displays a slider with a marker that can be repositioned to change the value. A value is snapped to the nearest allowable value when a value outside the range, or not equal to an incremental value, is entered. The increment value must be positive. Specifying an increment of 0 (zero) is the same as specifying a range without an increment. The editable text field (featuring masked editing) also allows the user to enter a numerical value.