Modifying Object Properties

Some IDL objects have properties associated with them — things like color, line style, size, and so on. Properties are set or changed by supplying property-value pairs in a call to the object class' Init or SetProperty method:

Obj->OBJ_NEW('ObjectClass', PROPERTY = value, ... ) 

or

Obj->SetProperty, PROPERTY = value, ... 

where PROPERTY is the name of a property and value is the associated property value.

Property values are retrieved by supplying property-value pairs in a call to the object class' GetProperty method:

Obj->GetProperty, PROPERTY = variable, ... 

where PROPERTY is the name of a property and variable is the name of an IDL variable that will hold the associated property value.

Note
Property-value pairs behave in exactly the same way as Keyword-value pairs. This means that you can set the value of a boolean property to 1 by preceding the name of the property with a "/" character. The following are equivalent:

Obj->SetProperty, PROPERTY = 1

Obj->SetProperty, /PROPERTY

If you are familiar with IDL Direct Graphics, you will note that many of the properties of IDL objects correspond to keywords to the Direct Graphics routines. Unlike IDL Direct Graphics, the IDL Object Graphics system allows you to change the value of an object's properties without re-creating the entire object. Objects must be redrawn, however, with a call to the destination object's Draw method, for the changes to become visible.

Properties and the Property Sheet Interface

In addition to being able to set and change object property values programmatically, IDL provides a way for users to change property values via a graphical user interface. The WIDGET_PROPERTYSHEET function creates a user interface that allows users to select and change property values using the mouse and keyboard.

For an object property to be displayed in a property sheet, the property must be registered.

See Registered Properties (IDL Reference Guide) for additional discussion.

Setting Properties at Initialization

Often, you will set an object's properties when creating the object for the first time, which is done by specifying any keywords to the object's Init method directly in the call of OBJ_NEW that creates the object. For example, suppose you are creating a plot and wish to use a red line to draw the plot line. You could specify the COLOR keyword to the IDLgrPlot::Init method directly in the call to OBJ_NEW:

myPlot = OBJ_NEW('IDLgrPlot', xdata, ydata, COLOR = [255, 0, 0]) 

In most cases, an object's Init method cannot be called directly. Arguments to OBJ_NEW are passed directly to the Init method when the object is created.

For some graphics objects, you can specify a keyword that has the same meaning as an argument. In Object Graphics, the value of the keyword overrides the value set by the argument. For example,

myPlot = OBJ_NEW('IDLgrPlot', xdata, ydata, DATAX = newXData) 

The Plot object uses the data in newXData for the plot's X data.

Setting Properties of Existing Objects

After you have created an object, you can also set its properties using the object's SetProperty method. For example, the following two statements duplicate the single call to OBJ_NEW shown above:

myPlot = OBJ_NEW('IDLgrPlot', xdata, ydata) 
myPlot->SetProperty, COLOR = [255, 0, 0] 

Note
Not all keywords available when the object is being initialized are necessarily available via the SetProperty method. Keywords available when using an object's SetProperty method are noted with the word "Set" in the table included after the text description of the property.

Retrieving Property Settings

You can retrieve the value of a particular property using an object's GetProperty method. The GetProperty method accepts a list of keyword-variable pairs and returns the value of the specified properties in the variables specified. For example, to return the value of the COLOR property of the plot object in our example, use the statement:

myPlot->GetProperty, COLOR = plotcolor 

The value of the COLOR property is returned in the IDL variable plotcolor.

You can retrieve the values of all of the properties associated with a graphics object by using the ALL keyword to the object's GetProperty method. The following statement:

myPlot->GetProperty, ALL = allprops 

returns an anonymous structure in the variable allprops; the structure contains the values of all of the retrievable properties of the object.

Note
Not all keywords available when the object is being initialized are necessarily available via the GetProperty method. Keywords available when using an object's GetProperty method are noted with the word "Get" in the table included after the text description of the property.

About Object Property Descriptions

In the documentation for the IDL object class library, the description of each class is followed by a section describing the properties of the class. Each property description is followed by a table that looks like this:

where

See Registered Property Data Types and Registered Properties (IDL Reference Guide) for additional information.