Man Page visu_capture.1
NAME
visu_capture - captures user interface design from a running
Motif/Xt application
SYNOPSIS
visu_capture [-x] [-f file] [-lang locale] [-wViIO] [-use n]
[-static-design] program [args...]
INPUTS
file the name of the file to which the captured interface is written
locale the name of a language locale
program the executable you want to run
args arguments passed to the executable
DESCRIPTION_KEYWORD
visu_capture captures the widget structure of a running
Motif/Xt application and saves it in visu .xd format.
FLAGS
-x Displays a summary of the command-line usage
of visu_capture.
-f Write captured widget structure to 'file'.
Cannot be used with -i flag.
-lang Run visu_capture (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_capture version information.
-i Display the visu_capture graphical user
interface.
-I Force the display of the visu_capture
graphical user interface if the application
will not load the dialog.
-O Override visu_capture exiting when attempting
to capture 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.
-static-design
Non interactive mode. visu_capture captures
all shells available on program startup, then
immediately exits.
USAGE
visu_capture works by inserting a small shared object into
the application. The program appears quite normal - except
that a particular key is trapped. Shells are captured by
pressing this hot-key.
Because the capture software is in a shared object, the
application must be linked with Xt dynamically. A stati-
cally linked application cannot be captured.
As with visu_record(1) and visu_replay(1), you know that the
capture program has been introduced successfully into the
application, when a message and copyright statement are
printed to diagnostic output.
The command-line version of visu_capture writes its data
when the application exits, so it will not work with a pro-
gram that detaches a sub-process and immediately exits.
EXAMPLES
To capture the main WorkShop Visual interface:
$ visu_capture -f /tmp/xdes.xd visu
Press the Hot Key in the WorkShop Visual main dialog.
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:
a) The application may be statically linked with the Xt
library rather than dynamically linked with it.
b) The application may have its own multi-threading scheme
that disallows Xt Work Procedures.
c) The product may have multiple application shells. (See
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 com-
mand 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:
a) The application has a "splash" or creates one or more
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 mul-
tiple 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.
b) Your application has reworked or subverted Xt event han-
dling.
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 cap-
ture designs.
c) Your application has not been linked with Motif.
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 fol-
lowing 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_record(1) visu_replay(1)
Sun WorkShop 6 Man Pages