Some components of a Java GUI, for example trees or tables, are rather complex and can contain an arbitrary number of elements like tree-nodes or table-cells. These elements are not themselves GUI components in the Java sense, but just a graphical representation of some data. This is a purely technical distinction and because it makes sense, from the tester's point of view, to treat these elements as separate entities and possible targets for events, QF-Test has special support for them. The representation for such an element is called an 'Item'.

An 'Item' is defined by two parts, the component it belongs to and an index into this component. The component is identified by the parent node of the 'Item' node. The index can be either numeric or textual. Numeric indexes start with 0. In a JList, for example, the element with index 1 is the second element from the top. Plain numeric indexes are not very useful for tree-nodes, because only the visible nodes are counted. Expanding or collapsing a tree node changes the numeric indexes of all nodes below it.

A textual index refers to the element by the text that is shown in the GUI. A list-item shown as "item1" in a JList component would be recorded with at textual index of "item1". The textual representation is more flexible but can cause problems if the names of the elements in a component are not unique. A textual index can also be given as a regular expression (see section 36.4). In this case, the first element found that matches the regular expression will be used.

The option Sub-item format controls the format for recording indexes.

Almost all kinds of 'Items' have only one index. The exception is the table-cell in a JTable component. Since tables are two-dimensional structures, two indexes are required to refer to a table-cell. The first one, the 'Primary index', defines the column of the table and the 'Secondary index' the row.

		Figure 7.1:  An 'Item' for a table cell

Tree-nodes are also special. The hierarchic structure of a tree doesn't map well to a linear one. One reason is the dependence of the numeric index on the current expansion state of the nodes. Another reason is that many kinds of trees have nodes with non-unique names. However, when the direct and indirect parent-nodes are taken into account to work with paths instead of names, uniqueness is often restored.

QF-Test uses a special syntax to represent tree nodes. An index that starts with a '/' character is considered to be a path index. Imagine a tree that shows a file-system hierarchy. The file "/tmp/file1" could be represented flat as just "file1", possibly colliding with another "file1" in some other directory, or as the full, unique path "/tmp/file1". QF-Test also supports numeric indexes with this syntax. As a numeric index "/2/3" designates the fourth child node of the third child of the root. A mixed-format index like "/tmp/2" to get the third child of the node named "tmp" is currently not possible.

Note This special syntax makes '/' a special character for elements of tree components, so it needs to be escaped when a literal '/' character is required. See section 36.6 for details about escaping and quoting special characters.

Everything that was said about the 'Id' attribute of 'Components' in section 6.3 also applies to an 'Item's' 'Id'. It has to be unique and can be referred to by events and similar kinds of nodes that require a component target.

When assigning an 'Item's' 'Id' automatically, QF-Test creates it by concatenating the containing 'Component's' 'Id' and the index (or indexes) of the element. These kinds of 'Ids' are expressive and typically easy to recognize. However, they are also the source of a common misunderstanding: If you want to change the index of a recorded 'Item' to point to some other element, you must not change the 'Component id' attribute of the node that refers to it (unless you use the special syntax described in the following section). Change the 'Primary index' of the 'Item' node instead.

There is an alternative way to target an event on an element of a complex component that does not require creation of an 'Item' node. By using a special syntax you can specify the index of the element directly in the 'Component id' attribute of the respective node. Instead of the 'Id' of an 'Item' node specify the 'Id' of the containing 'Component' and follow it with a special separator character and the index of the element. The character that separates the 'Id' and the index designates the format for the index:

To address a table-cell with 'Primary index' and 'Secondary index' simply append another separator character and the second index. That way, the 'Primary index' and 'Secondary index' can be of different format.

Example: If your test-suite contains a 'Component' node for a JTable component with the 'Id' table and you want to simulate a click on table-cell in the 6th row of the column with the title "Name", create a 'Mouse event' node and set its 'Component id' attribute to table@Name&5.

Almost all internal ItemResolver implementations (cf. section 39.2) allow of negative indices to start counting from the end. For example, table&-1&-1 addresses the last cell in the rightmost table column.

Whether it is preferable to use an 'Item' node or the special syntax depends on the situation. You can use either method as you see fit and mix them as you like. As a rule of thumb, 'Item' nodes are better suited to components with a few more or less constant elements, the columns of a JTable for example, or the tabs of a JTabbedPane. The special syntax is generally preferable for indexes with variable values and for elements with varying or editable values. The option Sub-item type determines whether 'Item' nodes are created or the special syntax is used when recording. With the default value "Intelligent" QF-Test will follow the rules outlined above.

Note The special meaning of the separator characters implies that literal '@', '&' or '%' characters in element indexes need to be escaped. See section 36.6 for details about escaping and quoting special characters.

Last update: 01/27/2012 Copyright © 1999-2012 Quality First Software GmbH