Extending the X-Designer Replay Widget Set

Extending the X-Designer Replay Widget Set


Background

X-Designer Replay is based on the principle that the actions which are recorded in a script must be immediately recognizable as user actions.

Most actions which take place within a Motif application are described in terms of how a user interacts with its widgets (e.g. by clicking with one of the mouse buttons) or what is typed from the keyboard. This makes recording and replaying a Motif application very straightforward. It also makes it easy for a tester to understand, program and maintain scripts. The same must be true of any non-standard widget used in an application.

There are a number of Motif widgets (those for which the position in the widget is important) for which this approach does not immediately work. For most, e.g. Scales, ScrollBars, etc, a single mechanism will work for all instances of that widget. In a DrawingArea, or other custom widget, each instance of a widget may behave quite differently.

For example, although the recording software may observe a click in a drawing area, the user sees this action quite differently. He is interacting with objects that have been drawn in the drawing area by the application. But these objects only appear within the code of the application - they are not part of the interface.

Since you, as an application programmer, will know exactly what a click in a particular custom widget or drawing area actually means, you can easily provide routines which describe these actions so that they can be understood and used by people who wish to record and replay your widget.

If you are programming a drawing-area, or some other customized widget, you will already have written code to convert from an event at a particular (x,y) coordinate in that widget to a particular action in the application. X-Designer Replay provides interfaces which allow you to register converters that allow testers to make use of your routines.

You need to provide X-Designer Replay with two converters: one for recording, which converts an event at a particular (x,y) coordinate into an action and another, for replaying which converts that action to an (x,y) coordinate.

The conversion routine allows you to map the (x,y) coordinate to something which makes sense both to the user and to the widget itself.


Note - Some widgets provide an easy way to convert between (x,y) coordinates and the internal structure of the widget, e.g. the XmListYToPos function. This is the preferred method. Other widgets provide ways of determining and changing the state of a widget. For example you use XmScrollBarGetValues to record a user action on a scroll bar and XmScrollBarSetValues to replay that action. You can use the converters to program a widget directly if the event strategy is difficult to implement.

The same mechanism is used both for widget classes (e.g. third party widgets) and for custom widgets (e.g. the Motif XmDrawingArea widget).

The next two sections describe the converter routines. We then give an example which shows the creation of converters for the Motif XmList widget class.

Event to Name/Attribute Conversion Routine

Name

xdsXyToNameProc - interface definition for procedure used to convert from an event to a name/attribute description

Synopsis

    typedef int (*xdsXYToNameProc) (
      Widget widget,
      int    x,
      int    y,
      char**  name_p,
      char** attribute_p )

Inputs

Usage

The routine should return 0 on failure, 1 on success. The strings that you assign to name_p and attribute_p are not freed by X-Designer Replay. Since copies are taken, you can use static storage.

If the routine fails, an error is reported.

Name/Attribute To Event Conversion Routine

Name

xdsNameToXYProc - interface definition for procedure used to convert from a name/attribute description to an event

Synopsis

    typedef int (*xdsNameToXyProc) (
      Widget widget,
      char*  name,
      char* attribute,
      int*  x_p,
      int*  y_p )

Inputs

Usage

The routine should return 0 on failure, 1 on success.

Notes

Sometimes it is very easy to program the effect you need to replay directly onto the widget, e.g. by setting a resource value or calling a convenience function, but extremely difficult to mimic the event sequence precisely. In these circumstances, you can handle it yourself in the routine.

You should still return success, but set the (x,y) co-ordinates to negative values. The standard mechanism simulates a single click within a widget and expects positive coordinates.

See also: