/* $XConsortium: README /main/4 1996/07/15 14:12:36 drk $ */

		    README for Automation libCommon.a
		    ---------------------------------


The following is information about what is contained in the Automated
version of libCommon. Basically libCommon is a library which will contain
functions that are commonly called with test programs contained in the Motif
test suite. It also contains a new mechanism that will read user instructions
from a separate ascii file on test startup time instead of reading the
instructions from a header file at compile time. The difference between this
version on libCommon and the version in tests/Manual/lib/Common is that
when this library creates the applicationShell it is for Automation. It
also initializes structures for Automation and reads in special flags for 
Automation.

For more information on the Automation commands, see the man pages for 
Automation.


Command Line Options:
--------------------

/* Common Flags - Automation and non-Automation */

-l 	     :	Disable displaying of the MessageBox for user 
		instructions (Ignore CommonPause())

-w #	     :	Specify width of MessageBox for user instructions. 
		Default is 60.

-u <string>  :	Specify a string which will be available to the 
		test writer as the global variable UserData.

-I <file>    :	Read an alternative instruction file. The default is
		<test_name>.dat.

-f <font>    :	Use <font> as the font that will be used when your
		requested font is not available. Default is fixed.

-p <font>    :	Specify the font to be used in the MessageBox for user
		instructions. Default is fixed.

-h	     : 	Print the usage message.


/* Automation only Flags */


-a	     :	Dump to the report file (<TestName>.prt) information on all
		the specific pixel failures. When run without this flag, 
		the message on a CompareVisual failure will be 
		a one line message that the CompareVisual failed.
		Only useful when running in comparison mode.

-r	     :	Record mode. In this mode, Automation will record and save
		the image currently on the screen and place it in
		<TestName>.vis.

-b	     :	Batch mode. In this mode visuals on the screen will be 
		compared against the visuals stored in <TestName.vis>
		This is the default mode.

-m	     :  Interactive comparison mode. In this mode, a CompareVisual
		command when run in compare mode (default), will do the 
		following. It will bring up a another window located at
		(500,500) which will be a BulletinBoardDialog with a 
		Drawing Area as its only child. What will be contained in
		the DrawingArea after a CompareVisual will be any pixels
		that failed between the comparison of the image on the screen
		and the saved image in the <TestName.vis>. a black pixel
		signifies failure, a white pixel signifies a pass. When
		you want to dismiss this window, simply click on the 
		interactive window and the Automation process will continue.

-c	     :	Ignore comparisons. In this mode all calls to CompareVisual
		will be ignored.

-D <time>    :	Delay mode. In this mode, a Delay cycle will be executed 
		after each command has been executed. This valuable on slow
		servers when creating and comparing visuals.

-W	     :	Produce xwd style window dumps of the failed image. This
		is triggered when a CompareVisual call fails in its comparison.
		This will produce files in the current directory with the
		format <TestName>_fail<n> where <n> starts at 0 and will
		go up to the number of failures in the test. You then can use
		xwud to display the failure images.

-S <filename>:	Specify an alternative will for the script file. By default
		the file Automation reads for the script commands is
		<TestName>.Scr. This will allow the user to override this
		convention.

-O <filename>:	Specify an alternative will for the output file. By default
		the file Automation dumps all STDOUT and STDERR information
		is <TestName>.prt. This will allow the user to override this
		convention.

-V <filename>:	Specify an alternative will for the visual files. By default
		the file Automation dumps visuals (in record mode) is 
		<TestName>.vis. This will allow the user to override this
		convention.

-T	     :	Trace mode. In this mode, all script command, with their
		command number, will be echo into the .prt file. This way
		the user can tell which command triggered a failure or
		print statement of any kind (XtWarning, Callback information).

		

New Callable Functions:
----------------------


void CommonGetOptions( int argc, char **argv )

Input  	: 	argc, argv
Output 	: 	None

Purpose : 	This function will read the command line options and 
		set the appropriate flags to represent those options.
		Called from CommonTestInit() always.




void CommonTestInit( int argc, char **argv )

Input	:	argc, argv
Output	:	None

Purpose :	This function will do the following:	

			1) Will set up SIGNAL handlers "popular" signals
			   (SIGHUP, SIGINT, SIGQUIT, SIGKILL, and others).
			   The signal handler will print a message about
			   the termination and which signal happened. It will
			   then exit the test.
			2) Will call CommonGetOptions() which will get all the
			   command line options including Automation
			   options.
			3) Will call XtToolkitInitialize() which will 
			   initialize the Intrinsics.
			4) Will create a Application context.
			4) Will make a connection to the display by calling
			   XtOpenDisplay(). Display variable is display.
			5) Will create an ApplicationShell with
			   XmNallowShellResize set to true. The name of
			   this variable is Shell1. This shell will be 
			   created for Automation.
			6) Set the global variables screen to the Toplevel
			   screen and rootWindow to the TopLevel window.
			7) Initialize Automation structures.

Globals :	display, Shell1, rootWindow, and screen are initialized.




XtCallbackProc CommonGenericCB( Widget w, caddr_t client_data, 
			  XmAnyCallbackStruct *call_data )

Input	:	Normal callback parameters
Output	:	None

Purpose	:	This is a "generic" callback routine that will simply
		print to STDOUT the reason why the callback was triggered.
		To be used when you want to verify that a particular
		callback has been triggered.




Pixel CommonGetColor( char *ColorString )

Input	:	A character string corresponding to a valid color in
		the rgb.txt file on your system. 
Output	:	A color cell entry corresponding to the passed color
		string. If the color does not exist, NULL will be
		returned.

Purpose	:	This routine will convert a string representation of
		a color into a Pixel value.




XmFontList CommonGetFontList( char *FontString )

Input	:	A character string corresponding to a font. 
Output	:	A XmFontList corresponding to the character input.

Purpose	:	This routine will convert a string representation of
		a font into a XmFontList. If the font you specify does
		not exist on your system then default_font is used.
		default_font is either read from the command line or
		is defined in testlib.h (fixed).



char *CommonCsToRs( XmString cs )

Input	:	A XmString.
Output	:	A character string representation of that XmString.

Purpose	:	This function will convert a simple one segment compound
		string into a regular character string.




void CommonPause()

Input	:	None
Output	:	None

Purpose	:	This function will place on the screen at (500, 0)
		an MesageBox contained in a PopupShell will contains 
		instructions that the test writer wants the user to execute.
		One call to CommonPause() corresponds to one screen of
		information.  The CommonPause() function will read it's
		instructions from a data file (default: <test_name>.dat)
		and format that information for display in the MessageBox.
		The MessageBox that is created will have its help button set
		insensitive. If you have tied any callbacks to this button,
		you must set the help button on the MessageBox to sensitive
		via SetValues().

Globals :	Global InstructionBox (MessageBox) is initialized.



void CommonDumpHierarchy(Widget w, FILE *fp)

Input	:	A Widet, and a FILE pointer.
Output	:	None

Purpose	:	This function will "dump" all the widget names (XtName)
		underneath the inputed widget. The output will be written
		to the FILE specified in the argument list.


void CommonExtraResources(Arg args[], Cardinal n)

Input	:	An argument list and the number of arguments in that list.
Output	:	None

Purpose:	This function will allow the user to pass resource values
		to the creation of the Application Shell instead of having 
		to do SetValues() after the Shell has been created. It also
		will allow the user to pass a different ApplicationClass to
		XtOpenDisplay(). This is special cased. When you pass
		"CommonAppClass" as the args[i].name then args[i].value will
		be used as the ApplicationClass.



Writing Instruction Files for CommonPause() Instructions:
--------------------------------------------------

Writing instruction files for Toolkit tests are now done by creating
a file with the name <Test_Name>.dat or using the command line option
-I and specifying another file name to read as your instructions. This
file will contain special formatting characters that will be used to
determine the format of the MessageBox's  message string. This file
will be read by the test program and displayed in the MessageBox when
the CommonPause() function is called. The following is a list of the 
special formatting characters that can be used in the instruction file:

#)	- Format the associated data as one single line of instructions.
	  The # character will be substituted with an instruction number
	  after all lines of instructions for that Panel have been
	  read in. The line will formatted to a specified width.
	  (determined either from the command line of from testlib.h)

@)	- Extended format. Format data by first placing a a newline
	  into the data stream, followed by the associated data formatted
	  5 characters in from the left margin, followed by another
	  newline. Data will be formatted to a specified width as in
	  #) case. No instruction numbers will be inserted into the
	  data stream.

!)	- No Format. Associated data will not be formatted. Use of this
	  format should be limited whenever possible. When it is not
	  possible, try to keep the width of the non formatted line to
	  60 characters.

C)	- End of one "Panel". Specifies the end of one panel of 
	  instructions. When this format is read, the test program
	  knows that it needs to display the Information Dialog with
	  all data between the last panel and these format characters.
	  Will append to the data stream a message that the user
	  should Continue for more testing.

E)	- End of instructions. Tells the test program that it is done
	  with all the user instructions. Will print a Test Finished
	  message so that the user knows that the test is finished.


\<char>	- Escape the next character. This a way of allowing all 
	  combinations of characters in the data stream.


The format stream will be determined by reading the instruction file
until a end of panel format is found ( C) ). While the data is being
read, newlines (unless in the no format area ( !) ), tabs, and multiple
spaces (substituted with one space) will be stripped. When special
formatting characters are read ( #), !), @) ), the data stream will be
modified to insert characters to produce whatever format is asked for.
Once the data stream is filled in, a second pass is run on that
data, formatting it to a uniform length for display in the Information
Dialog.



Example of a instruction file for test foo:
------------------------------------------

foo.dat:

#) Move the pointer to the scrollbar's slider area and press Mouse
button1.\n\n #) Drag the slider to the top of the scrollbar (with key \#).
@) Note the slider will not take any input because it is insensitive
C)
#) The Scrollbar will change orientation
to\t\t\n\n
XmVERTICAL.
!)

Try the following translations:
      1) BSelect Press:		Select()
      2) BDrag Press  :		Select()

E)

Will produce the following screens:

Screen 1:

	1) Move the pointer to the scrollbar's slider area
	   and press Mouse button1.
	2) Drag the slider to the top of the scrollbar (with
	   key #).

	   Note the slider will not take any input because 
	   it is insensitive.

        Press the Continue Button for more testing.

Screen 2:

	1) The Scrollbar will change orientation to XmVERTICAL.

	Try the following translations:
	      1) BSelect Press:         Select()
              2) BDrag Press  :         Select()

	Test Finished -- Exit Please.