Man Page visu_replay.1

NAME

     visu_replay - simulate user input for Motif/Xt program

SYNOPSIS

     visu_replay [-x] [-f testscript] [-lang  locale]  [-pOvVwiI]
     [-exit-on-error|-user-on-error|-skip-on-error]	[-ignore-
     server-time] [-interval ms] [-use n] program [args...]

INPUTS

     testscript	the name of the	script file (default stdin)
     locale	the name of a language locale
     program	the executable you want	to run
     args	arguments passed to the	executable

DESCRIPTION_KEYWORD

     visu_replay takes control of an X Application and executes	a
     sequence  of  actions  as if they were done by a user at the
     keyboard.

FLAGS

     -x	   Display a summary of	the command-line usage
	   of visu_replay.

     -f	   Use replay commands in 'testscript'.	Cannot
	   be used with	-i flag.

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

     -p	   Preprocess script with C preprocessor before
	   replaying.

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

     -v	   Echo	replay commands	as they	are being executed.

     -V	   Print visu_replay version information.

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

     -i	   Display the visu_replay graphical user
	   interface.

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

     -exit-on-error
	  Terminate the	visu_replay script and the application
	  if a command cannot be replayed.

     -user-on-error
	  Terminate the	visu_replay script if a	command	cannot
	  be replayed but remain in the	application.

     -skip-on-error
	  Jump to the next sequence in the visu_replay script
	  if a command cannot be replayed.

     -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  configura-
     tion
	  at startup.

     The -exit-on-error, -user-on-error	and -skip-on-error  flags
     can also be set using the XDSOPTIONS environment variable or
     the X Resource "xdsOptions".

     When using	-skip-on-error,	ensure that the	sequence to which
     you skip has commands to allow you	to return the application
     to	a consistent state.

EXAMPLES

     To	record a user session with a program  (e.g.  visu_config)
     into 'scriptfile':


     $ visu_record -f scriptfile visu_config

     To	replay this script:


     $ visu_replay -f scriptfile visu_config

     To	use a generated	script as standard input to visu_replay:


     $ gen_test_script | visu_replay visu_config

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

     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
     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.

     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 informa-
     tion.  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_capture(1)