## Extending the WorkShop Visual Replay Widget Set

### Background

WorkShop Visual 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. WorkShop Visual Replay provides interfaces which allow you to register converters that allow testers to make use of your routines.

You need to provide WorkShop Visual 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

- widget - the widget that will use the routine
- x - the x co-ordinate of the event
- y - the y co-ordinate of the event
- name_p - (return) pointer to a string that identifies the part of the widget
- attribute_p - (return) pointer to a string that adds to the name, e.g. center, left, right

#### 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 WorkShop Visual 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

- widget - the widget that will use the routine
- name - a string that identifies the part of the widget
- I>attribute - a string that adds to the name, e.g. center, left, right
- x_p - (return) pointer to the x co-ordinate result
- y_p - (return) pointer to the y co-ordinate result

#### 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:

- Extending the WorkShop Visual Replay Widget Set - An Example
- Adding Your Own WorkShop Visual Replay Commands
- Getting the Most from WorkShop Visual Replay