visu_record(1)

NAME
visu_record - record user actions from a Motif/Xt program

SYNOPSIS

SYNOPSIS
visu_record [-x] [-f script] [-lang locale] [-wViIO] [-use n] program [args...]

INPUTS
script     output is written to script (default stdout)
program    the executable you want to run
args       arguments required by the executable

DESCRIPTION
visu_record monitors a running Motif/Xt application and records a log of what the user did. visu_record interprets the event stream as it comes off the wire from the X Server, and translates it into a very high level description of a user's interaction with the application's widgets.

FLAGS
-x Displays a summary of the command-line usage
      of visu_record.

-f Save the recorded information to 'script' Cannot
      be used with -i flag.

-lang Run visu_record (including the graphical user
      interface and all error messages) in locale and
      ignore any LANG settings.

-w Print summary information about the display,
      server and window manager.

-V Print visu_record version information.

-i Display the visu_record graphical user
      interface.

-I Force the display of the visu_record
      graphical user interface if the application
      will not load the dialog.

-O Override visu_record exiting when attempting
      to record an application which has not been
      linked with Motif.

-use n
     Use the nth Application Shell as the real one.
     This is intended for applications that begin
     with a 'splash' or use an Application Shell
     for configuration at startup.

USAGE
visu_record records a script, by default, to standard-output. -i starts up an interactive record/replay session using the WorkShop Visual Replay interface. Alternatively -f script records the data to the named file script. visu_record will not allow you to overwrite an existing script file.

-O overrides program exit for non-motif applications. If an application has not been linked with motif, many of the motif routines used by visu_record will dump core. By default visu_record will not attempt to work with a non-motif application. This can be overridden, and much useful debugging information can still be accessed if you use the -O flag, but you should not try to do anything that requires motif.

EXAMPLES
To display the visu_record dialog:

$ visu_record -i my-application

To record usage of my-application in a script file:

$ visu_record -f myscript my-application

To record usage of my-application and display the recorded information to standard-out:

$ visu_record my-application

TIPS and HINTS
The following section answers frequently asked questions about visu_replay, visu_record and visu_capture.

1. Why is it not possible to record and replay certain applications (e.g. Netscape)?

Typical reasons are:

 The application may be statically linked with the Xt
a library rather than dynamically linked with it.

 The application may have its own multi-threading
b scheme that disallows Xt Work Procedures.

 The product may have multiple application shells. (See
c Question 4 below.)

If you experience difficulties in recording and replaying your own software, simply relink it so that it uses libXt.so.

2. Why is the click position in a text widget not recorded?

All of the "position sensitive" motif widgets are recorded/replayed through special visu_replay routines. You will find the source code for these routines in the src/examples/replay/libcvtXm directory.

The conversion routines for XmText and XmTextField are not built by default because, for most testing purposes, it is reasonable to treat the text field as a simple data entry field whose contents you wish to replace. It is a lot simpler to do the following:

	doubleclick mytextwidget
	type halloworld

than it is to do this:

	doubleclick mytextwidget( position, 25)
	type halloworld

It would also be difficult to check that doubleclicking at a particular character position did select all the text.

Different test runs may involve replacing the contents of a text field with different values. The name of the text widget is the most important item - not the values which are to be placed in it.

If you wish to test the editing facilities provided in an XmText widget within an application, you should rebuild the libcvtXm directory with -DHANDLE_TEXT added to the cc command line. Then copy the libcvtXm.so shared object to lib/xds so overwriting the standard version.

3. The visu_replay copyright message appears but then it exits

This commonly occurs when visu_replay has determined that you are attempting to replay a non-Motif application.

The -O flag can be used to force the application to be invoked and allows you to replay any non-Motif application functionality.

NB: This situation can also arise for Motif applications which have multiple application shells (see below).

4. visu_replay is invoked successfully but appears not to be working

Typical reasons are:

 The application has a "splash" or creates one or more
a temporary ApplicationShell widgets on startup. By default, visu_replay registers the first ApplicationShell widget and uses it as a point of reference. Usually it "takes" the first applicationShell it sees, but you can change it to take the 4th by adding:

	  -use 4

on the command line, or set the XDSUSESHELL environment variable:

	  setenv XDSUSESHELL 4

NB: To check that you are using the "real" application shell, try recording. You should see:

	in ApplicationShell
		......

If you see:

	in myapp
		.....

then it may not be using the correct application shell. (If your application has an unmapped application shell, and multiple toplevel shells, then this is the correct behavior).

The solution is to keep incrementing the -use count. The worst that can happen is that you tell it to ignore ALL you application shells, so it won't record, replay or capture.

 Your application has reworked or subverted Xt event
b handling.

You know that this is the problem, if:

the -i flag is used and the application appears, but the visu_replay dialog does not, or

the -I flag is used and the visu_replay dialog is displayed before the application appears.

In these circumstances, all you will be able to do is capture designs.

 Your application has not been linked with Motif.

c In this situation, the default behavior is for visu_replay to abort. This may be overridden using the -O flag. Note however that you will not be able to record or replay any application functionality which relies upon Motif.

5. My application has 3rd party widgets in it. How can I capture them properly?

The capture mechanism creates capture files in the visu .xd format and assumes that you are using the standard version of visu, i.e. not one supplemented with non-Motif widgets. By default, all non-Motif widgets are represented in the capture file as Motif DrawingArea widgets.

If you are using a version of visu which supports the 3rd party widgets you wish to capture, you need to set the following resource:

*xdsCaptureUserWidgets:true

6. Can visu_replay handle japanese (and other) text and input methods?

Yes. It records the composed text that has been inserted in the text field and replays by inserting the text directly.

It has been configured for the Motif Text and Textfield widgets. The configuration software is in:

src/examples/replay/motif/motif4.c

and the mechanism for registering the software is in:

src/examples/replay/motif/register.c

The configuration involves a get/put routine of the data. Some input methods will allow you to access this information. The default fallback is to access the string in the widget itself.

It has hard-wired control-space as an input method compose request, and has an alternative "compose" keysym resource, which is set by default to Henkan_Mode.

If you are using the recording software with an input method that takes, e.g. F3 as the compose key, you should run your software with:

	-xrm *xdsImComposeKeySym:F3

or set this resource from a defaults file, or with xrdb.

7. Can my customers record/replay my applications?

To permit users to use visu_replay to record and replay your application, you must have the following line in your code:

xdsAllowUserAccess()

and link the application with the libxdsclient.a library.

SEE ALSO
visu_replay(1) visu_capture(1)