Modifying Object Properties

Some IDL objects have properties associated with them; things like color, line style, size, and so on.

You can set properties at object initialization by providing property-value pairs in a call to the object's Init method:

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

If your object inherits from the IDL_Object class, you can set or change the object's properties after object initialization by calling the property directly using the dot operator:

Obj.PROPERTY = value, ...

or

By calling the object's SetProperty method with a property-value pair:

 Obj.SetProperty, PROPERTY = value, ...

where PROPERTY is the name of an object property and value is the associated property value.

If your object inherits from the IDL_Object class, you can retrieve property values by calling the property directly with the dot operator:

variable = Obj.PROPERTY

or

By calling the object's GetProperty method with a property-value pair:

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. Assuming that Obj inherits from IDL_Object, then the following are equivalent:

Obj.MYPROPERTY = 1

Obj.SetProperty, MYPROPERTY = 1

Obj.SetProperty, /MYPROPERTY

If you are familiar with Direct Graphics, you will note that many of the properties of IDL objects correspond to keywords in Direct Graphics routines. Unlike Direct Graphics, the 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 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 on object creation by calling the object name and specifying keywords to the object’s Init method as function parameters. 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 when calling the PLOT function:

myPlot = PLOT(xdata, ydata, COLOR = [255, 0, 0])

In most cases, an object’s Init method cannot be called directly. Arguments to object creation 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 = PLOT(xdata, ydata, DATAX = newXData)

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

If a property is Boolean (valid values of 0 or 1 only), it can be set during initialization using the alternate "/" syntax as in the "HIDE" property in the following example:

 

;Create the data "theory"

theory = SIN(2.0*FINDGEN(200)*!PI/25.0)*EXP(-0.02*FINDGEN(200))

 

;The following two lines produce the same plot result:

plot = PLOT(theory, "r4D-", TITLE="Sine Wave", /HIDE)

plot = PLOT(theory, "r4D-", TITLE="Sine Wave", HIDE=1)

 

Note: After initialization the alternate "/" syntax does not work to modify a Boolean property; you will need to use the dot operator or call the object's SetProperty method.

Setting Properties of Existing Objects

After you have created an object, you can set or change its properties by calling the property directly with the dot operator (if the object inherits from IDL_Object) or by calling the object’s SetProperty method.

The following code duplicates the single call to PLOT shown previously:

myPlot = PLOT(xdata, ydata)

myPlot.COLOR = "red"

You can achieve the same results by calling the object's SetProperty method:

myPlot = PLOT(xdata, ydata)

myPlot.SetProperty, COLOR = "red"

Retrieving Property Settings

You can retrieve the value of a particular property using an object’s dot operator (if the object inherits from IDL_Object) or by calling the object's GetProperty method.

To retrieve a property value with the dot operator, assign the result to a variable:

plotcolor = myPlot.COLOR

The GetProperty method accepts a list of keyword-variable pairs and returns the value of the specified properties in the variables specified.

myPlot.GetProperty, COLOR = plotcolor

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

Getting/Setting Properties and Method Scope

Under most circumstances, if you get or set an object property using the dot operator, IDL will call the object's GetProperty or SetProperty method. However, if inside of a method you get or set a property of the self object, IDL will access the property directly.

Accessing Properties with Nested Object References

The following examples illustrate how to use nested object references:

p = PLOT(/TEST, TITLE="My Plot")

ax = p.AXES

ax[3].COLOR= 'red'

In the ax object array, the fourth object is retrieved, and SetProperty, COLOR='red' is called for the object.

p["Title"].COLOR = "green"

For the scalar object p that inherits from IDL_Object, the object's _overloadBracketRightSide method is called to retrieve the value (presumably an object), and SetProperty, COLOR="green" is called for the retrieved object.

PRINT, p.TITLE.STRING

For the object p, GetProperty is called to retrieve the TITLE object, and then GetProperty is called on the title object to retrieve the title's string value.

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:

Property Type

Boolean

Name String

Hide

Get: Yes

Set: No

Init: Yes

Registered: Yes

where

See Registered Property Data Types and Registered Properties for additional information.