While it is possible to execute an iTool operation with just the operation's component identifier (as described in Running Operations), in many cases you will want to modify the operation's properties before execution. In other cases you may not wish to execute an operation at all - you may only be interested in changing the value of one or more properties of a given component object. Modifying the properties of an iTool component (as described in Changing Property Values) requires that you know the property identifier of the component object property you wish to change.
Once you have retrieved the component identifier string for an iTool component (as described in Retrieving Component Identifiers), you can use the component identifier to retrieve the property identifiers for properties of that component. For example, the following statements create an iPlot tool containing some random data, retrieve the component object identifier for the Smooth operation, and print the property identifiers:
IPLOT, RANDOMU(seed, 15) idTool = ITGETCURRENT(TOOL=oTool) idSmooth= oTool->FindIdentifiers('*smooth*', /OPERATIONS) objSmooth = oTool->GetByIdentifier(idSmooth) propsSmooth = objSmooth->QueryProperty() PRINT, propsSmooth
NAME DESCRIPTION TYPES SHOW_EXECUTION_UI WIDTH
The strings displayed are the property identifiers for the Smooth operation.
Note that after we have retrieved the full identifier for the Smooth operation, we use the identifier as the argument to the GetByIdentifier method of the IDLitContainer class. The GetByIdentifier method returns the object reference to the Smooth operation; we need the object reference in order to then call the QueryProperty method, which returns a string array containing the property identifiers.
See IDLitComponent::QueryProperty and IDLitContainer::GetByIdentifier for additional details on these methods.
Knowing the property identifier for the property you wish to change is often enough, if you are already familiar with the property, its data type, and range of possible values. For example, suppose you want to change the line thickness of a plot line. You may already know that the value of the THICK property of a plot line is a floating-point integer, so you can confidently call the DoSetProperty method as described in Changing Property Values, specifying a floating-point number for the new line thickness value.
But you may not always know the data type or range of allowed values for a given property. If you have the property identifier, you can get additional information on the property using the GetPropertyAttribute method of the IDLitComponent class.
For example, suppose we want to set the value of the WIDTH property of the Smooth operation. The following statements will retrieve the text description, the data type, and the range of allowed values for the WIDTH property:
objSmooth->GetPropertyAttribute, 'WIDTH', DESCRIPTION=desc, $ TYPE=type, VALID_RANGE=range PRINT, desc, type, range
Smooth Filter Width. 2 0
The first attribute (DESCRIPTION) is the text description of the property. The second attribute (TYPE) is the data type accepted by the property; the description of the TYPE attribute reveals that the value 2 indicates that the property accepts an integer value. The third attribute (VALID_RANGE) is the range of accepted values; the scalar value 0 indicates that there are no restrictions on the range of integer values allowed.
See IDLitComponent::GetPropertyAttribute for additional information on retrieving property attributes. An Example Property Information Retrieval Routine discusses an example utility (included in the IDL distribution) that uses these techniques.
To retrieve the current value of a property, you must use the property identifier and the GetPropertyByIdentifier method of the IDLitComponent class.
For example, the following statements will retrieve and print the current value of the WIDTH property of the Smooth operation in the current iTool:
success = objSmooth->GetPropertyByIdentifier('WIDTH', width_value) IF success THEN PRINT, 'Width is: ', width_value ELSE $ PRINT, 'No value returned'
Width is: 3
The GetPropertyByIdentifier function method returns a value of 1 (one) if the property value was retrieved successfully, or 0 (zero) otherwise. In the example, the property value of 3 is successfully retrieved.
Note that you could also use the GetProperty method:
objSmooth->GetProperty, WIDTH=width_value) PRINT, 'Width is: ', width_value
While this is slightly simpler, it makes the error handling slightly trickier, and forces you to hard-code the name of the property whose value you are retrieving.
See IDLitComponent::GetPropertyByIdentifier for additional information on retrieving property values.
An example utility routine named
itpropertyreport.pro uses the methods discussed in the previous sections to retrieve property information. It is included in the
examples/doc/itools directory of the IDL distribution.
itpropertyreport.pro by specifying an iTool object reference and the full object identifier (as returned by the FindIdentifiers method) of the component whose properties you would like to inspect. For example, calling
itpropertyreport with the iTool object reference and operation identifier used above:
itpropertyreport, oTool, idSmooth
produces the following output:
Properties of /TOOLS/PLOT TOOL/OPERATIONS/OPERATIONS/FILTER/SMOOTH Identifier Name Type ---------- ---- ---- NAME Name STRING DESCRIPTION Description STRING TYPES TYPES USERDEF SHOW_EXECUTION_UI Show dialog BOOLEAN WIDTH Width INTEGER
itpropertyreportutility produces formatted text output in the IDL output log. This output will be correctly aligned only if the command log uses a fixed-width font.
Additionally, you can set the VALUE keyword to
itpropertyreport to display a column containing the current values of the properties listed; you can set the DESCRIPTION keyword to display a column containing the text description of the property. You may want to inspect the
itpropertyreport.pro file for additional information and example code.