The list of properties that Squish uses to create multi-property (real) names for objects are specified using XML files. For each wrapper which your application uses there can be up to two XML files—called “descriptor files” in Squish terminology—which must follow a particular naming scheme so that Squish can find them:

Exactly the same file format is used for the predefined descriptor files that are supplied with Squish and for the user descriptor files that you can create to customize how Squish generates names.

Every descriptor file contains a list of types together with the names of the properties that can be used when generating names for objects of each particular type. Squish reads its own predefined descriptor files first, and then it reads any user descriptor files. This makes it possible for user descriptor files (those with filenames of the form <wrapper>_user_descriptors.xml), to override the behavior specified in the predefined descriptor files, and to add new type descriptors.

The list of types and the properties that can be used for their objects are specified using a simple XML format. Here's a short example for a fictional application toolkit which has a Button type:

<objectdescriptors>
  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property>caption</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

This descriptor file defines just one <descriptor> which says that for all objects of type Button, caption should be used when generating the real name.

Name Inheritance

This means that not only objects which are instances of the Button class will get the caption property in their real name, but also instances of classes which inherit Button! When deciding which descriptors to use for generating the name for a given object, Squish takes the inheritance hierarchy into account and will use all descriptors whose type name shows up in the inheritance hierarchy of the given object.

In this example, only the name of the type was used for identifying the object. However, it is also possible to apply constraints, so that only those objects of the given type and that meet specified constraints are identified. Here's a slightly longer example to illustrate this:

<objectdescriptors>
  <descriptor>
    <type name="Button">
      <constraint name="visible">false</constraint>
    </type>
    <realidentifiers>
      <property>caption</property>
      <property>tooltip</property>
    </realidentifiers>
  </descriptor>

  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property>caption</property>
      <property>xpos</property>
      <property>ypos</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

Here we have created two separate descriptors, although they both refer to objects of the same type.

The first descriptor applies to objects of type Button—but only when the button's visible property is false, in other words, this descriptor only applies to hidden Buttons. So when the application has a hidden button, this descriptor says that the properties that should be used to identify it when creating real names are caption and tooltip.

The second descriptor applies to objects of type Button, but only visible ones since hidden Buttons are handled by the first descriptor. This descriptor says that when creating real names for Button objects, their caption, xpos, and ypos properties should be used.

Although we have only shown the use of a single constraint, it is possible to use as many as we like. In such cases the descriptor will only be used if all the constraints are met.

In general, when multiple descriptors are specified which apply to the same type, Squish will try to use the one that is the best match for the object it is accessing, essentially working from the descriptor with the most constraints to the one with the least.

So in terms of the second example above, if Squish encounters a Button, it will first try the first descriptor (since that has the most, i.e., one, constraints). If the button is hidden, Squish has a match and will generate a real name that uses the Button's caption and tooltip. However, if the Button is visible, the first descriptor won't match, so Squish will try the next one, and this matches (since it has no constraints, so will match any Button), and generates a real name that uses the Button's caption, xpos, and ypos.

In addition to the normal descriptors, which match an object by the type name (and optionally, by constraints), there's a special descriptor called * (star or asterisk), which matches objects of any type. This special descriptor can also have constraints applied to it, in exactly the same way as for normal descriptors. The toolkit wrappers that support * as a catch-all are Qt, Java, and Mac. For Windows or Android, use WinGUIObject or Control for the type name instead. Here's an example of how it might be used:

<objectdescriptors>
  <descriptor>
    <type name="*"/>
    <realidentifiers>
      <property>id</property>
    </realidentifiers>
  </descriptor>

  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property>caption</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

In this example, a catch-all descriptor is defined. This means that for all objects, no matter what their type name is, id will be used when generating real names. If a particular object does not have an id, the property will be silently ignored and this will not trigger an error.

Harmless Catch-Alls

It is harmless to list properties in a catch-all descriptor which don't exist for some object types. For example, if almost all of our object types have an id that we normally want to use when real names are generated, the best approach is to specify this property using a catch-all descriptor. This will ensure that id is always used for real names for those objects that have it, and yet it is safely and silently ignored for those few that don't.

When real names are generated, the properties used are those for the matching class descriptor, plus those for the matching descriptor of the object's base class, and so on, up the inheritance hierarchy. In addition, any catch-all descriptors are also used.

Given the example descriptors shown above, if a Button object was encountered—and assuming that Buttons have an id, Squish would generate a real name that would use caption (from the Button descriptor) and id (from the * descriptor). And if the Button didn't have an id, Squish would simply use caption and ignore id. If the Button derived from another type, for example, Widget, that had a descriptor that specified, say, hasfocus, then that property would also be included in the generated real name.

Suppose we have a descriptor file that contains the following rule for Button:

<objectdescriptors>
  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property>id</property>
      <property>caption</property>
      <property>tooltip</property>
      <property>enabled</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

This descriptor specifies four properties: id, caption, tooltip and enabled, that will be used to generate the real names for Button objects. Unfortunately, in practice this might lead to less robust real names. This is because we are using too many properties, so our test scripts will be vulnerable if a Button's caption or its tooltip changes. What we really want to say is that if caption has a value, then we should use it, but if caption is empty then we should use tooltip as a fallback.

Squish provides a means of solving this problem. The mechanism is part of the descriptor file format, and it allows us to specify two or more properties such that Squish will only use one of them—the first one which actually has a value. The mechanism is called “property groups”. Here is an example:

<objectdescriptors>
  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property>id</property>
      <group>
        <property>caption</property>
        <property>tooltip</property>
      </group>
      <property>enabled</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

Here we have put caption and tooltip in a <group> together. The effect of this is to tell Squish to use caption if it has a value (i.e., if it isn't an empty string), and to use tooltip otherwise. So when Squish generates a real name for a Button using this descriptor, the name will have id, enabled, and either caption or tooltip—but never both—plus any properties from the matching descriptors of the classes that Button inherits from, plus any properties from any catch-all * descriptor.

In addition to specifying the names and values of properties, real names can also specify references to related objects, and such references can help to uniquely identify an object of a particular type.

For example, we might have a form with several single line editors. In themselves these editors might all have the same properties with nothing to distinguish them, but in all probability they will all have labels beside them so that the user knows what they are expected to type into them. In some toolkits such labels might be identified by their position in relation to the object—left or above—and in other toolkits they are identified by their relationship to the object—for example, they are its buddy.

Here's an example real name for a fictional single line editor which is identified by its own properties, and also by its buddy whose value is a reference to a related object:

{type='LineEdit' maxChars='32' allowDigits='false' buddy={type='Label' text='Last Name:'}}

Normal property values are enclosed in quotes, but when the value is a reference to a related object, quotes are not used and instead the related object's real name is used, enclosed in braces. (So we end up with one real name nested inside another.)

The same object name can of course also be expressed when using Script-Based Object Map (Section 7.11.4):

{"type": "LineEdit", "maxChars": 32, "allowDigits": False, "buddy": {"type": "Label", "text": "Last Name:"}}

{type: 'LineEdit', maxChars: 32, allowDigits: false, buddy: {type: 'Label', text: 'Last Name:'}}

{:type => 'LineEdit', :maxChars => 32, :allowDigits => false, :buddy => {:type => 'Label', :text => 'Last Name:'}}

{'type' => 'LineEdit', 'maxChars' => 32, 'allowDigits' => 'false', 'buddy' => {'type' => 'Label', 'text' => 'Last Name:'}}

ObjectName type LineEdit maxChars 32 allowDigits false buddy [ObjectName type Label text {Last Name:}]

If we want to use a property that refers to another object in a descriptor, we simply name it using the <object> tag instead of the <property> tag, as the following example illustrates:

<objectdescriptors>
  <descriptor>
    <type name="LineEdit"/>
    <realidentifiers>
      <property>maxChars</property>
      <property>allowDigits</property>
      <object>buddy</object>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

What this descriptor says is that when Squish encounters a LineEdit, it should generate a real name that includes maxChars and allowDigits, and also buddy which is an object reference.

In some situations we want a particular property to be used when generating real names for most objects of a type, but not for absolutely all of them. For example, we might have a bunch of objects derived from Widget with a dropEnabled. If most of the derived objects are editing widgets, the property makes sense, but it probably doesn't make sense for a derived Button object. So we want to create a descriptor that includes dropEnabled for all Widgets, except for Button. Squish allows us to do this by using the exclude attribute of <property> as the following example shows:

<objectdescriptors>
  <descriptor>
    <type name="Widget"/>
    <realidentifiers>
      <property>dropEnabled</property>
      <property>text</property>
    </realidentifiers>
  </descriptor>

  <descriptor>
    <type name="Button"/>
    <realidentifiers>
      <property exclude="yes">dropEnabled</property>
    </realidentifiers>
  </descriptor>
</objectdescriptors>

In this example, Widget is the base class of all GUI objects. The first descriptor tells Squish to use dropEnabled and text when generating real names for Widget objects and for all objects that derive from it (such as LineEdit and Button). There is no <descriptor> for LineEdit since they are derived from Widget and we have no properties to add or change. But for Button we have created a <descriptor> so that we can stop dropEnabled from being used for Button names.

If we were to use the descriptor file above with our fictional toolkit, it would change the way that Squish creates real names. For LineEdits (assuming they are derived from Widget) Squish will create real names that have dropEnabled, text (and of course type since that is always included), but for Buttons, Squish will create real names that only use text and type.