iTool Object Identifiers

iTool object identifiers are simple strings that uniquely identify individual objects within the hierarchy of iTool objects in much the same way that a computer file system identifies files within a hierarchy of files. The object hierarchy (and, by extension, the object identifiers) also describe where information about objects is made visible in the iTool user interface; see iTool Object Hierarchy for additional discussion of the iTool hierarchy and the iTool system object.

Besides providing a familiar, user-readable way to identify objects in the iTool system, object identifiers also allow iTool developers to refer to an object without having to maintain an actual object reference to that object. This ability to use a lightweight string object to refer to a potentially "heavy" object in the iTool system makes it possible to maintain a very loose coupling between the objects that implement an iTool's functionality and those that implement its user interface. This allows for object access that can cross process and machine boundaries, paving the way for the use of the iTool system in more distributed environments.

Note
Object identifiers are not to be confused with object descriptors. See Object Descriptors for details.

Object identifier strings are assigned when an object class is registered with either an individual iTool or with the iTool system object. See Registering Components for a discussion of the registration process.

Fully-Qualified vs. Relative Identifiers

Identifiers can either be fully qualified, meaning that they depict the entire path from the root iTool system object to the object being identified, or relative, meaning they depict the path from the root of the current iTool. Fully qualified identifiers begin with the "/" character, and refer to objects that are accessible to all iTools that become active during the lifetime of the iTool system object. Relative identifiers do not begin with a "/" and refer to objects that are accessible only within a specified container object.

For example, the identifier string

/DATA MANAGER/MY DATA

refers to an object named MY DATA, located in the system-level DATA MANAGER container. Because the identifier is fully qualified, the MY DATA object is visible to any iTool that is active during the iTool session.

Similarly, the identifier string

OPERATIONS/FILTERS/MY FILTER

refers to an object named MY FILTER, located in a sub-container of the iTool-level OPERATIONS container named FILTERS. Because the identifier is relative, the MY FILTER object is visible only to the current iTool.

Note
Object identifiers are stored as upper-case strings. Spaces are allowed.

Using Identifiers

Numerous methods defined by iTools object classes accept object identifiers as arguments to uniquely identify an object instance. This frees you as a developer from the need to obtain and keep track of an actual object reference for each object you wish to refer to or modify.

For example, the DoSetProperty method of the IDLitTool object class allows you to change the value of an object property by supplying the identifier for the object whose property is to be changed, as well as the identifier for the property itself. Similarly, the DoAction method of the IDLitTool class allows you to initiate an operation simply by supplying its identifier.

Retrieving Identifiers

At times, you may know the identifier of the object you wish to affect. This is the case when your own code registers an operation, for example; you must supply the identifier when calling the IREGISTER routine or Register method. (See Registering Components for additional details.)

Other times, you may not know the identifier of the object you wish to affect. In these cases, you have two options:

If your code has access to the actual object reference to the object whose identifier you need, you can use the GetFullIdentifier method of the IDLitComponent object class. See "IDLitComponent::GetFullIdentifier" (IDL Reference Guide) for details.

If your code does not have access to an object reference, you can use the FindIdentifiers method of the IDLitTool object class to retrieve a list of identifiers that match a specified pattern. See "IDLitTool::FindIdentifiers" (IDL Reference Guide) for details.

If your code does not have access to an object reference, you may be able to use the IGETID procedure. See "IGETID" (IDL Reference Guide) for details.

Proxy Identifiers

Because the location of an object in the iTool object hierarchy corresponds to the place that object is made visible to iTool users, you may at times want an object to be located in multiple places in the iTool object hierarchy. For example, the Undo operation appears in two places in the standard iTool user interface: under the Edit menu and on the toolbar. Rather than duplicating the Undo operation object in each of those places in the iTool object hierarchy, we can use a proxy mechanism to register the same object instance with multiple object identifiers. In the case of the Undo operation, the operation itself is located in the EDIT subcontainer of the iTool's OPERATIONS container, which implies that the operation appears under the iTool's Edit menu. A proxy (or alias) to this object is created in the EDIT subcontainer of the iTool's TOOLBAR container, which places the operation on the toolbar. Only one instance of the Undo object is created, but its action can be invoked from both the menu and the toolbar.

Proxy identifiers are assigned by the Register method for the object being proxied. See Registering Components for additional details.

Object Descriptors

Object descriptors are iTool objects that contain enough information about a given object class to create an object of that class when necessary. In many cases, object descriptors, rather than instances of the objects they create, are stored in the iTool hierarchy; this approach allows object instances to be created only when needed. Object descriptors also manage instances of objects that can be re-used by the system, avoiding the need to create a new instance of an object (such as an operation) each time it is used.

Cases in which an iTool developer will need to know about or use object descriptors rather than object identifiers are very rare. We mention object descriptors here because they are used extensively in the iTool object hierarchy to expose the functionality of objects that are created as needed, rather than being created automatically when the iTool is created.