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.
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.
typedef int (*xdsXYToNameProc) ( Widget widget, int x, int y, char** name_p, char** attribute_p )
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.
typedef int (*xdsNameToXyProc) ( Widget widget, char* name, char* attribute, int* x_p, int* y_p )
The routine should return 0 on failure, 1 on success.
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: