Retrieving Property Information

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.

Retrieving Property Identifiers

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 = IGETCURRENT(TOOL=oTool) 
idSmooth= oTool->FindIdentifiers('*smooth*', /OPERATIONS) 
objSmooth = oTool->GetByIdentifier(idSmooth) 
propsSmooth = objSmooth->QueryProperty() 
PRINT, propsSmooth 

IDL prints:

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" (IDL Reference Guide) for additional details on these methods.

Property Attribute Information

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 

IDL prints:

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" (IDL Reference Guide) 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.

Property Value Information

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' 

IDL prints:

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" (IDL Reference Guide) for additional information on retrieving property values.

An Example Property Information Retrieval Routine

An example utility routine named itpropertyreport.pro uses the methods discussed in the previous sections to retrieve property information.

Example Code
The routine itpropertyreport.pro is included in the examples/doc/itools directory of the IDL distribution. Run the example procedure by entering itpropertyreport at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT itpropertyreport.pro.

Call 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 


Note

The itpropertyreport utility 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.