Setting iTool Properties

The iTools procedural interface allows you to change the values of individual properties of visualization items in an iTool window. In IDL versions prior to IDL 7.1, properties could only be modified interactively, by changing values in a property sheet.

What is a Property?

Properties are values associated with a visualization. In most cases, properties control the visual presentation of the data — things such as the color or thickness of a plot line, whether an axis is displayed, or the style used to render a surface. In other cases, properties contain the data that defines a visualization; for example, the STRING property of a text annotation defines the text to be displayed.

Changing a Property Value

Use the ISETPROPERTY procedure to change the value of a property. To change a property, you will need to know:

The iTool identifier of the visualization whose property you want to change, or a string that will allow the IGETID function to find the identifier

The identifier of the property to be changed

The new value

For example, suppose you have created a surface plot:

ISURFACE, HANNING(300,300)*300

Now suppose you want to change the surface style from the default (filled) to a wire mesh:

ISETPROPERTY, 'surface', STYLE=1, COLOR=[200,100,0]
ISETCURRENT, /SHOW

In this example, we pass the string `surface' to the ISETPROPERTY procedure to represent the iTool identifier of the surface visualization. Within the ISETPROPERTY routine, the string is passed to the IGETID function, which uses it to locate the full identifier for the surface. (See Understanding iTool Identifiers and IGETID for more on IGETID.)

Next, we specify that we want to change the STYLE property to the value 1 (one) and the COLOR property to the RGB value [200,100,0] (a reddish brown). See Determining Property Identifiers and Allowed Values for more on how to come up with property identifiers and acceptable values.

Note that we can specify any number of properties in a single call to the ISETPROPERTY routine. Similarly, we can change the value of properties of more than one item simultaneously by passing multiple iTool identifiers. For example, to change the Tick Direction of all of the axes on the surface plot at once, we could use the following command:

ISETPROPERTY, 'axis*', TICKDIR=1 & ISETCURRENT, /SHOW

Here, the string 'axis*' is expanded by the IGETID routine to a string array of iTools identifiers for all of the axes in the surface visualization. ISETPROPERTY then sets the value of the TICKDIR property for all the axes to 1 (one).

Getting the Current Property Value

To retrieve the current value of a visualization property, use the IGETPROPERTY procedure. To retrieve a property, you will need to know:

The iTool identifier of the visualization whose property you want to retrieve, or a string that will allow the IGETID function to find the identifier

The identifier of the property to be retrieved

For example, suppose you have created a surface plot:

ISURFACE, HANNING(300,300)*300

and wish to retrieve the color used to draw the surface. You would use the following call to the IGETPROPERTY routine:

IGETPROPERTY, 'surface', COLOR=c
PRINT, c

Here, the variable c contains a three-element byte array specifying the RGB value used as the color of the surface.

Determining Property Identifiers and Allowed Values

Prior to the release of the iTools procedural interface, the only way to change a property value was through the iTools' interactive property sheet interface. In that interface, all of the available properties are shown visually in a graphical user interface, along with the current value.

Note, however, that the descriptive names shown in the iTools graphical user interface are not the same as the property identifiers used internally by the iTools system to identify visualization properties. Documentation for both the graphical user interface and the associated property identifiers is provided in Visualization Properties (iTool User's Guide).

You can also use the IGETPROPERTY procedure to find the property identifiers of a visualization. Use the _REGISTERED keyword (note the underscore) to return a string array containing the identifiers of all of the registered properties of the visualization. For example:

ISURFACE, HANNING(300,300)*300
IGETPROPERTY, 'surface', _REGISTERED=list
FOR i=0, N_ELEMENTS(list)-1 DO PRINT, list[i]

IDL prints:

NAME 
DESCRIPTION 
HIDE 
COLOR 
USE_DEFAULT_COLOR 
TRANSPARENCY 
BOTTOM 
MIN_VALUE 
MAX_VALUE 
STYLE 
SHADING 
USE_TRIANGLES 
LINESTYLE 
THICK 
HIDDEN_LINES 
SHOW_SKIRT 
SKIRT 
TEXTURE_INTERP 
TEXTURE_HIGHRES 
ZERO_OPACITY_SKIP

By comparing these property identifiers with the property names shown in the iTool's property sheet (or with the documentation), you can determine which identifier corresponds to each property.