Understanding iTool Identifiers and IGETID
Although iTools visualizations are in reality hierarchies of IDL objects, the iTools framework uses identifiers rather than actual object references to refer to the individual components of visualizations. Identifiers are simple strings that uniquely identify an object reference in the iTools system. The iTools procedural interface uses identifiers to specify which item in a visualization you want to modify. (For a more detailed discussion of iTool identifiers, see iTool Object Identifiers (iTool Developer's Guide).)
Because the hierarchy of objects required to display an iTool visualization is complex, a representative iTool identifier for a plot visualization might look something like this:
This is a rather long string to have to remember (much less type) when what you want is the identifier for the plot line in the current iTool.
The IGETID function makes the process of finding and using iTool identifiers much easier. For example, to specify the identifier for the plot line in the current iTool, you would substitute
for the full identifier shown above. You can supply any string as the argument to IGETID; IDL will attempt to find an iTool identifier that matches.
By default, IGETID returns the first identifier that matches the specified string. To retrieve identifiers for multiple items, such as axes, use an asterisk at the end of the identifier. For example:
IPLOT, INDGEN(10)
axis_ids = IGETID('axis*')
PRINT, axis_ids
IDL Prints:
/TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/AXES/AXIS0 /TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/AXES/AXIS1 /TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/AXES/AXIS2 /TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/AXES/AXIS3
The '*' character in the argument to the IGETID function is a wildcard that matches all of the numbered axes; see Pattern Matching Rules Used by IGETID for details on how patterns are used.
Pattern Matching Rules Used by IGETID
The IGETID function is intended to make it easy to find the full iTool identifier of any part of an iTool visualization by specifying a small part of the identifier. This section describes how IGETID interprets the value you provide when trying to find a match with a full identifier.
Partial Identifiers
The argument to the IGETID function is a string value containing a portion of the full identifier. IGETID will attempt to locate a full identifier that ends with the partial identifier you supplied.
Identifier Segments
iTool identifiers are divided into segments by the '/' character. The following identifier:
consists of four segments: TOOLS, PLOT TOOL, WINDOW, and VIEW_1.
Matches Proceed from Left to Right
Matching of identifiers proceeds from left to right. This means that the partial identifier 'ax' would match
before it could match
Default Identifier Segments
The first three identifier segments: TOOLS, the name of the current tool (PLOT TOOL in the above example), and WINDOW are the same for every identifier associated with the current tool. These segments are included in the search by default; you do not need to specify them.
Matching of Numbered Identifier Segments
Because an iTool might contain more than one of a given type of visualization, identifiers for individual visualizations of the same type are numbered. Numbering for most visualization identifiers starts at zero; numbering for view identifiers starts at one.
Some numbered identifiers include an underscore between the text of the identifier and its number; for example, the second plot in an iTool is 'plot_1'. Similarly, some numbered identifiers include a space between the text and the number. Other numbered identifiers add the number onto the end of the text with no space or underscore.
When interpreting partial identifiers, the IGETID function makes the following assumptions about numbered items:
- A partial identifier that does not include a number will match the first item of that type found in the iTool.
- A partial identifier that includes a number will match any of the numbering forms (underscore, space, or neither). This means that the partial identifier
'plot 1'will match full identifiers that end with'plot 1','plot1', or'plot_1'.
Relaxed Matching
If the partial identifier you supply does not contain the '/' character, the IGETID function will return the first identifier it finds that ends with the pattern you specify. If, however, the partial identifier contains one or more '/' characters, IGETID will return the first identifier that matches the relative positions of the specified identifier segments.
For example, suppose the current iTool has text annotations in both the Annotation layer and the Visualization layer. Using the partial identifier 'text*' would match both annotations:
IDL prints:
/TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/TEXT /TOOLS/PLOT TOOL/WINDOW/VIEW_1/ANNOTATION LAYER/TEXT
To find the identifier of the text annotation in the Annotation layer, we could use the partial identifier 'Annotation Layer/text':
PRINT, IGETID('Annotation Layer/text*')
IDL prints:
The partial identifier need not contain all of the text within the identifier segment; specifying the partial identifier 'Ann/text*' produces the same result.
The partial identifier can omit identifier segments in the middle of the pattern. For example, the following partial identifier matches both text items in the first view:
IDL prints:
/TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/TEXT /TOOLS/PLOT TOOL/WINDOW/VIEW_1/ANNOTATION LAYER/TEXT
Wildcards
The asterisk character ('*') can be included at the end of an identifier segment. It has the following distinct uses:
For example, the following prints the identifiers for all of the axis visualizations in the iPlot tool:
IPLOT, INDGEN(10)
PRINT, IGETID('axis*')
The following prints the identifiers of all items one segment to the right of the 'Data Space' segment:
IPLOT, INDGEN(10)
PRINT, IGETID('data space/*')
Search the Current iTool by Default
Unless you explicitly specify the TOOL keyword, the IGETID function will search for an identifier that matches your search string in the current iTool.
The current iTool is the iTool that was most recently created or selected. If multiple iTool windows exist, you can determine which one is current in the following ways:
- Visually, by noting which iTool window appears in front of all the others on screen.
- Visually, by noting which iTool is highlighted in the IDL Workbench Existing Visualizations view.
- Programmatically, using the IGETCURRENT function.
For example, suppose we create plot visualizations in two iTools:
IPLOT, INDGEN(10)
IPLOT, RANDOMU(s, 10)
The following call to the IGETID function will locate the plot line in the second iTool, which is "current" because it was created most recently:
IDL Prints:
If we specify the wildcard '*' for the value of the TOOL keyword, IGETID will find the identifiers for plot lines in both tools:
PRINT, IGETID('plot', TOOL='*')
IDL Prints:
/TOOLS/PLOT TOOL/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/PLOT /TOOLS/PLOT TOOL_1/WINDOW/VIEW_1/VISUALIZATION LAYER/DATA SPACE/PLOT
