Changing Property Values

Given the object identifier for a property, there are two ways to change the property value: using the DoSetProperty method of the IDLitTool class, and using the SetProperty method of the IDLitComponent class. When changing the value of a registered property, in most cases, it is better to use the DoSetProperty method.

Using the DoSetProperty Method

Use the DoSetProperty method of the IDLitTool class to change the value of a property associated with an item in the iTool hierarchy. Using the DoSetProperty method has two advantages over using the SetProperty method:

  1. DoSetProperty takes an object identifier as its argument; there is no need to retrieve the object reference to the property you wish to change.
  2. The DoSetProperty method takes care of adding the property change to the iTool's undo-redo buffer.

    3. Warning
    To use the DoSetProperty method, the property whose value is being changed must be a registered property of the selected iTool component object. If the property is not registered, use the SetProperty method instead.

For example, suppose you have created an iPlot tool with the following command: 

IPLOT, RANDOMU(seed, 15)

To change the color of the plot line, you could use the following statements: 

idTool = IGETCURRENT(TOOL=oTool) 
idPlot = oTool->FindIdentifiers('*plot', /VISUALIZATIONS) 
success = oTool->DoSetProperty(idPlot, 'COLOR', [40,120,200]) 
oTool->CommitActions 



Warning

Make sure you understand what the FindIdentifiers method will return for a given search string and keyword; care is necessary to ensure that you retrieve the identifier for the correct item. See Retrieving Component Identifiers for details.

Note that the property identifier used as the second argument to the DoSetProperty method is often, but not always, the same as the property name that is displayed in the Visualization Browser property sheet. Methods for finding property identifiers are discussed in detail in Retrieving Property Information.

The third argument to the DoSetProperty method is the new value for the property. Techniques for determining the data type and allowed values for a given property are described in Property Attribute Information.

Finally, the CommitActions method of the IDLitTool class commits all pending transactions to the undo-redo buffer and refreshes the current window. Note that the property changes are not undoable until the changes have been committed with a call to the CommitActions method.

Tip
You can do make several calls to the DoSetProperty method, followed by a single call to the CommitActions method. This will bundle all of the SetProperty actions into a single item in the undo-redo buffer.

Using the SetProperty Method

Use the SetProperty method of the component object class to change the value of a property associated with an item in the iTool hierarchy. Using the SetProperty method requires that you retrieve an object reference to the object whose properties you are setting.

Note
If the property whose value you want to change is not registered, you must use the SetProperty method rather than the DoSetProperty method.

For example, suppose you have created an iPlot tool with the following command: 

IPLOT, RANDOMU(seed, 15)

To change the color of the plot line, you could use the following statements: 

idTool = IGETCURRENT(TOOL=oTool) 
idPlot = oTool->FindIdentifiers('*plot', /VISUALIZATIONS) 
oPlot = oTool->GetByIdentifier(idPlot) 
oPlot->SetProperty,COLOR=[40,120,200] 
oTool->RefreshCurrentWindow 



Warning

Property changes made using the SetProperty method are not placed in the undo-redo buffer.