/* $XConsortium: README /main/4 1996/07/15 14:14:23 drk $ */
README for libCommon.a
++++++++++++++++++++++
The following is information about what is contained in libCommon.a.
Basically libCommon.a 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.
Command Line Options:
--------------------
-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.
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 for four "popular"
signals (SIGHUP, SIGINT, SIGQUIT, and SIGKILL).
The signal handler will print a message as to which
signal happended and then exit the program.
2) Will call CommonGetOptions() which will get all the
command line 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.
6) Set the global variables screen to the Toplevel
screen and rootWindow to the TopLevel window.
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 exsist, 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 inputted 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.