/* $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 : Specify a string which will be available to the test writer as the global variable UserData. -I : Read an alternative instruction file. The default is .dat. -f : Use as the font that will be used when your requested font is not available. Default is fixed. -p : 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: .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 .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. \ - 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.