Adding Your Own X-Designer Replay Commands

Adding Your Own X-Designer Replay Commands


The command set of X-Designer Replay is intended for replaying user actions and for checking the state of an application with respect to its widget hierarchy and its resource settings. You are not limited to this set of commands. You can extend it to include commands to meet your own needs, for example:

An Example

We will describe how to create a module which contains one command. This command prints a message on standard error and the name of the current shell widget. You can use this example as a template for constructing your own commands.

The source files for the command, together with a Makefile are provided in the $XDROOT/src/examples/replay/usertemplate directory, where $XDROOT is the location of your XDesigner installation.

The contents of this directory are listed below:

The support files provide the framework which allows your extra commands to communicate with the X-Designer Replay engine. You only need to change the xdsResources.h file - the remaining files prefixed with xds should not be altered in any way.

The contents of the interface.c file are shown below:

#include "stdio.h"
#include "X11/Xos.h"
#include "X11/Xlib.h"
#include "X11/Intrinsic.h"

void
exampleHalloWorld( shell, message)
	Widget shell;
	char * message;
{
	if (!message)
		message = "no message";
	(void) fprintf ( stderr, "Widget %s says '%s'\n",XtName(shell), message);
}

As you can see, a user-defined function should have two arguments:

The message is all the text which follows the user command syntax on that line in the script. The example script fragment below shows how a command would be accessed and used:

import usertemplate
in ApplicationShell
	user HalloWorld I'm here

Here the message is "I'm here".

The Interface

The interface between all objects and the X-Designer Replay engine takes place using the standard Xt resource handling routines.


Note - If you would like more information on resource structures, you are advised to consult Chapter 10 in Volume Four of the "X Toolkit Intrinsics Programming Manual" published by O'Reilly and Associates, or any other comparable book.

An entry for the new command is added to the resource list in xdsResources.h, as shown below:

{
	"HalloWorld", XtCCallback, XtRPointer, sizeof(XtPointer),
	XtOffsetOf(data_t,HalloWorld), XtRImmediate,
	(XtPointer)exampleHalloWorld
}

Only three items are of significance within this code:

A pointer to that resource is added to the data structure within this file:

typedef struct {

  int       type;
  XtPointer setValues;
  XtPointer getValues;
  XtPointer engineSetValues;
  XtPointer engineGetValues;
  /*-----------------------*/
  XtPointer HalloWorld;
} data_t;

Entries above the line in the data structure are common to all X-Designer Replay objects.

The last thing to do in this file is to declare the function:

extern void exampleHalloWorld();

Building the Module

You only need to change the OBJECT line in the Makefile in order to build the module. For this example, we change it to:

    OBJECT=usertemplate

and then build the module by typing:

    make solaris

Finally, we copy or link the shared object we have built to the $XDROOT/lib/xds directory:

    cp libusertemplate.so $XDROOT/lib/xds

That is all there is to it.

Summary

To add a new command to the X-Designer Replay command set:

  1. Add the associated function to the interface.c file.

  2. Add an entry to the resource list in xdsResources.h.

  3. Add a function pointer to the data structure in that file.

  4. Add an extern declaration of the function to the same file.

  5. If necessary, change the OBJECT line in the Makefile.

  6. Build the module.

  7. Copy or link it to the XDROOT/lib/xds directory.

You can create as many modules as you wish and load them into a script at any time.

See also: