Retrieving Component Identifiers
In order to affect an item within an iTool — change a property of a visualization, for example, or apply an operation — you must first retrieve the identifier for the item. iTool identifiers are described in detail in iTool Object Identifiers.
In the case of operations, you may be able to construct the appropriate identifier string based on visual inspection of the hierarchy shown in the Operations Browser coupled with your knowledge of the iTools framework. Similarly, in the case of visualizations, you may be able to construct the identifier string based on visual inspection of the hierarchy shown in the Visualization Browser. However, the FindIdentifiers method of the IDLitTool class lets you programmatically (and unambiguously) retrieve the identifier of any item in the current iTool's component object hierarchy.
Using the FindIdentifiers Method
Use the FindIdentifiers method to retrieve the full object identifier for an iTool component object: a visualization, an operation, a view, a window — any component that exists in the current iTool's component object hierarchy. Once you have the identifier for a component object, you can use iTool framework methods to affect that object as described in the later sections of this chapter.
The syntax for the FindIdentifiers method is:
Result = Obj->IDLitTool::FindIdentifiers([Pattern] [, Keywords])
where Obj is an IDLitTool object and Result is a string array containing the full object identifiers of iTool component objects that contain the string specified by Pattern. (See "IDLitTool::FindIdentifiers" (IDL Reference Guide) for complete information on the keywords accepted.)
Note on Pattern Matching
The FindIdentifiers method finds matches for Pattern in full object identifiers using the same rules as the STRMATCH function, with the exception that searches are case-insensitive. In almost all cases, you will want to use wildcard characters to allow a substring of the full identifier to be matched. See the examples below for additional information.
FindIdentifier Examples
For these examples, suppose you have an iSurface tool created by the following statement:
The full object identifier for this surface visualization looks something like:
If you retrieve an object reference to our surface tool using the following statement:
you might suppose that the following statement would return the identifier string shown above:
In fact, this statement returns no results, since there is no object identifier in the iTool hierarchy that consists solely of the string 'surface'.
You might next try the following statement:
to match any object identifier that contains the string 'surface'. This statement will produces many lines of output; in fact, it will list every component in the surface tool's object hierarchy, because each object identifier contains the string '/TOOLS/SURFACE TOOL'.
You might next try the following statement:
to match any object identifier that contains the string 'surface' at the end of the identifier. This statement will produce output that looks something like this:
/TOOLS/SURFACE TOOL/OPERATIONS/FILE/NEW/SURFACE /TOOLS/SURFACE TOOL/CURRENT STYLE/VISUALIZATIONS/SURFACE /TOOLS/SURFACE TOOL/CURRENT STYLE/VISUALIZATIONS/ISOSURFACE /TOOLS/SURFACE TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/SURFACE
Here, a smaller number of identifiers match the pattern, but still more than you are interested in.
Finally, you might try the following statement:
This statement will match any object identifier in the visualization layer that contains the string 'surface'. It will produce output that looks something like this:
which is the identifier for the plot line just created. Note that if your iTool contained more than one surface visualization, identifiers for each surface would be returned.
Similarly, suppose you wanted the object identifier for the New Surface operation. Either of the following statements:
PRINT, surfaceTool->FindIdentifiers('*surface', /OPERATIONS)
PRINT, surfaceTool->FindIdentifiers('*/operations/*surface')
produce the following output:
See "IDLitTool::FindIdentifiers" (IDL Reference Guide) for complete information on the keywords accepted by this method.
Warning
The FindIdentifiers method recurses through the entire object hierarchy of the specified object, which may be slow for large container hierarchies. If you find it necessary to call FindIdentifiers multiple times, it may be more efficient to use a single call with one or more wildcards ("*") to return all relevant identifiers, and then perform the necessary searches using the returned list.
