Using and Developing Locators: An NCL Example


This section steps through the locators designed for the JClass toolkit (from the KL Group). Unlike the Bongo toolkit, the JClass toolkit does not use a common base class, and so it needs a locator for each base class.

The three classes that make up the KL Group locators are:

JCOutliner is the locator for objects that extend JCOutlinerComponent. MultiColumn is the locator for objects that extend JCMultiColumnListComponent. klgroup is actually a delegating class for all objects from the JClass toolkit--it determines whether the object in question is a JCOutliner or a JCMultiColumnListComponent, then calls the appropriate locator. This locator does not cover the entire KL Group widget set; it serves as an example for two types of widgets within the JClass toolkit.

Here you'll step through JCOutliner and klgroup in detail. MultiColumn is a variation on JCOutliner and is not shown in this chapter, but you can find the source in the \javastar\contrib\locator\klgroup directory and examine it on your own.

JCOutliner

The JCOutliner locator, designed for the KL Group JClass toolkit, provides an example of a NCL that's a little complicated. The toolkit does not use a common class, so this locator is specific to one of the base classes (JCOutliner). The tutorial includes it as an example because all toolkits are different, and showing an example of a simple, straightforward NCL might not help you in creating a more challenging NCL.

Note - For an example of an NCL for a toolkit where all classes extend a common object, see the Bongo NCL located in the \contrib\locators directory.

The header for the JCOutliner locator imports several libraries:

At minimum, your NCL needs to import:

The class declaration is also included above--it implements the JavaStar API's JSNonComponentLocator class.

JCOutliner.findObject()

The first method defined in this NCL is findObject(), the method JavaStar uses when recording. This method needs to return a reference within a JSNCLData object that JavaStar can use to insert into the test code.

The findObject() method:

  1. Makes the assumption that the object needed is a JCOutlinerComponent. If it is, the code formally casts the Component passed in to be a JCOutlinerComponent object. If the Component passed in is not a JCOutlinerComponent, the method returns null.

  2. Gets the x-y coordinates, making the assumption that the AWTevent passed in is a MouseEvent.

  3. Creates a old dummy event. This is specific to the toolkit; the KL Group event is an old-style event.

  4. Assigns the x-y coordinates retrieved from the incoming event to the newly-created, old-style event.

  5. Creates a JCOutlinerNode and calls JCOutliner.eventToNode, passing in the using the old event type. In the KL Group J Class structure, JCOutliner objects contain JCOutlinerNodes. You determine where the event occurred by calling eventToNode() and assigning the result to the node.

  6. Returns a JSNCLData object. JSNCLData takes a name, a point, and an object reference. findObject() supplies these as:

    1. Name is the label of the JCOutlinerNode followed by a comma, with the x-coordinate added.

    2. The point is the x and y coordinates from the old-style event.

    3. The object reference is the JCOutliner.

JCOutliner.getNamedObjectData()

Next, the code defines the playback side of the locator by implementing the getNamedObjectData method. The name passed as an argument is the name variable from the JSNCLData object, as created by the findObject() method, so the format is expected as whatever was defined in findObject().

The task of getNamedObjectData() is to turn this information back into a component that JavaStar can then act upon.

The getNamedObject() method:

  1. Assumes the Component passed in is a JCOutlinerComponent (just as findObject() did).

  2. Declares two variables to use to calculate the x- and y- offsets. The x offset is actually stored

  3. Gets the x-coordinate that findObject() appended to the name, and assign this to the x offset.

  4. Removes the x-coordinate from the name string.

  5. Gets a list of visible nodes for this JCOutlinerComponent and initialize a node, in preparation to traverse the list.

  6. Initializes a standard incrementer (stdincr) that equals the height and spacing of the JCOutlinerComponent, plus two. The value of two was arrived at through testing the locator; you might find a different way to determine the exact spacing.

  7. Walks the list of visible nodes. The loop:

    1. Puts each node into a readable node form

    2. Increments the y offset by the standard incrementer

    3. Ends the loop when the getLabelString for the node matching the name of the component passed into getNamedObjectData().

  8. Returns a JSNCLData object containing:

    1. The non-component name.

    2. A Point that uses the x- and y-offsets. (The y-offset is the value obtained by getNamedObjectData)

    3. The Component originally passed into this method.

klgroup

As mentioned before, the klgroup class is a delegating class. JavaStar calls either klgroup.findObject or klgroup.getNamedObject. The methods then determine which component time is being passed in, and calls the same method in either JCOutliner or MultiColumn.

klgroup.findObject()

For klgroup, findObject():

  1. Checks to see if the component passed in is an instance of JCMultiColumnListComponent. If it is, the code instantiates a MultiColumn object and calls the objects findObject() method.

  2. If the object is not a JCMultiColumnListComponent, the code checks to see if it is a JCOutlinerComponent. If so, it instantiates a JCOutliner and calls the objects findObject() method.

  3. If the object is neither a JCMultiColumnListComponent nor a JCMultiColumnListComponent, findObject() returns null.

klgroup.getNamedObjectData()

This method works the same as klgroup.findObject(), except that it calls the getNamedObjectData() methods of the classes it instantiates.




Send feedback to JavaStar-feedback@suntest.com
Copyright © 1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303. All rights reserved.