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, ...
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
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
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:
theory = SIN(2.0*FINDGEN(200)*!PI/25.0)*EXP(-0.02*FINDGEN(200))
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
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.
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 describes the property type associated with the property. If the property is registered, the property type will be one of a number of registered property data types. If the property is not registered, this field will describe the generic IDL data type of the property value.
- Name String is the default value of the Name property attribute. If the property is registered, this is the value that appears in the left-hand column when the property is displayed in a property sheet widget. If the property is not registered, this field will contain the words not displayed.
- Get, Set, and Init describe whether the property can be specified as a keyword to the GetProperty, SetProperty, and Init methods, respectively.
- Registered describes whether the property is registered for display in a property sheet widget.
See Registered Property Data Types and Registered Properties for additional information.