/* $XConsortium: README /main/5 1996/07/15 14:36:34 drk $ */
6.  User Interface Language Tests

This README describes the OSF/Motif User Interface Language
tests.  It provides information about the individual tests,
and offers instructions for running and interpreting the
tests and test output.

                            Note

Throughout this README, we use the path ./tests/uil to
identify the top directory of the User Interface Language
tests.  The ./ indicates the testing tree root and is not an
actual path designation.  For example, if you installed the
Motif 1.1 release software at /source/Motif, then
./tests/uil translates to /source/Motif/tests/uil at your
site.

6.1  Overview and Directory Structure

The OSF/Motif User Interface Language test directory,
./tests/uil, consists of several files and subdirectories:

   * The file Imakefile is used to build Makefile, which in it's turn
	is used to build the tests.

   * The Callbacks subdirectory contains the test of UIL
     multiple callbacks, multC.  This test is noninterac-
     tive, and prints result messages to the standard out-
     put.  The script run_multC runs the test and redirects
     the output to the file multC.out.

   * The EnumVal subdirectory contains tests of Enumerated
     Values within UIL.  They are designed to be user
     interactive, with on-line user instructions for each
     part of the test.  This test subdirectory contains the
     following tests.

     EnumVal1   EnumVal3   EnumVal5
     EnumVal2   EnumVal4   EnumVal6

   * The ForRef subdirectory contains a tests of forward
     references within UIL.  The test ForRef is not user
     interactive, but the tests ForRef2, ForRef3 and ForRef4
     are designed to be user interactive, with on-line user
     instructions for each part of the test.  The results of
     the ForRef test is placed in the file for_ref.out.

   * The NL subdirectory contains the test of the UIL
     national language extensions, NL.  This test is nonin-
     teractive, and prints result to the standard output.

   * The Syntax subdirectory contains tests of general syn-
     tax within UIL.  They are designed to be user interac-
     tive, with on-line user instructions for each part of
     the test.  This test subdirectory contains the follow-
     ing tests.

     Case       GSyntax2   Names
     GSyntax1   Minimal    NamesU

   * The callUil subdirectory contains a test of the call-
     able Uil compiler portion of UIL, Uil.  It is designed
     to be user interactive, with on-line user instructions
     for each part of the test.  The test invokes the call-
     able Uil compiler on three different uil files; one
     with errors, one with warnings, and one that compiles
     successfully.  The results of the compiles are
     presented in the MessageBox used for the instructions.

   * The dataStructs subdirectory contains tests of UIL data
     structures.  These tests are noninteractive, and each
     test prints result messages to the standard output.
     The script run_all runs all the tests and redirects the
     result messages to the file dataStruct.out.

     This test subdirectory contains the following tests.

     CompoundS   Pixmap   Simple
     Font        Tables

   * The matrix subdirectory contains a test designed to
     test the Widget Meta Language (WML) within UIL Test.
     The testing scheme is to add the facility for more
     widgets to the currently built UIL and then test all
     possible combinations of Motif Resource Manager (MRM)
     interfaces and UID files to make sure that the interac-
     tions between MRM and UIL are consistent and compati-
     ble.  For these tests we use newly created widgets: The
     Browse widget using the Motif toolkit and the ALabel
     widget using the MIT Athena Toolkit.  When these new
     widgets are added to WML, a new UIL compiler is built
     for testing.

   * The validator subdirectory contains a test of the UIL
     error and warning mechanism.  The testing scheme is to
     compile a UIL file, validator.uil, with the -v flag to
     generate a listing file that also lists errors and
     warnings.  The listing file is then compared against an
     preexisting listing file to show differences.

   * The widgets subdirectory contains tests for displaying
     all the Motif widgets created with UIL.  It it designed
     to be user interactive, with on-line user instructions
     accompanying each test widget.  This test subdirectory
     contains the following tests.

     BBoard      labelGad     scaleHorz
     BBoardDia   listBs       scaleVert
     arrowBGad   listEs       scrollLis2
     arrowBtn    listMs       scrollList
     cascBGad    listSs       scrollText
     cascBtn     menuBar      scrollWin
     command     mesBox       scrollbarH
     drawArea    mesDia       scrollbarV
     drawnBtn    optionMenu   selectBox
     errorDia    panedWin     selectDia
     form        popupMenu    textMl
     formDia     promptDia    textSl
     frame       pulldown     toggleBGad
     fsBox       pushBGad     toggleBtn
     fsDia       pushBtn      warningDia
     infoDia     radioBox     workingDia
     label       rowCol

Each test subdirectory contains the following common files.
Each test subdirectory may not contain all of the different
files.  Some test subdirectories may also contain additional
files.  These are most commonly used as data for one or more
of the tests.

   * The file Imakefile is used to build Makefile, which in it's turn
	is used to build the tests.

   * The README file, or variants, contains information
     specific to that test directory's build and run pro-
     cedure.  The README file in a test subdirectory
     describes any nonstandard build or run procedure.
     There should be no information in the README files that
     is not in this document.

   * The file run_all or run is used to run all the Toolkit
     tests in series.  In some instances the run_all script
     also initializes a test before running it.

   * Files with the suffixes .c, .h, and .uil contain source
     code for the tests.

   * The file displayUid.c contains a MRM interface for
     displaying UID files, reporting callbacks.

   * The header file reasons.h contains an array of reasons
     for reporting callbacks.

   * Some directories, such as Widgets, contain .msg files
     that contain the text of instructions for the test.

6.2  Compiling the Tests

All the tests, except validator, must be compiled before you
can run them.

   * If you used the global build process after installing
     the software, the tests should already be built.  We do
     not recommend building the tests with global build pro-
     cess because of the size of the test suite.  (This
     assumes that you did not move the test suite files
     prior to invoking the make commands.)

   * If you did not include the test suite files in your
     initial global build process, you can build the tests
     now using the make all command from the ./tests/uil
     directory.

   * You can build just the tests in any one test subdirec-
     tory, except the matrix test subdirectory, using the
     make all command from the specific test subdirectory.
     For example, to build the tests in the ForRef subdirec-
     tory, enter the make all command from the
     ./tests/uil/ForRef test subdirectory.

You should not generally build tests by whole subdirectories
in the ./tests/uil test directorie, since there are many
dependencies among files and the testing mechanisms vary
widely among test subdirectories.

Two special compile notes are required here.  First, in the
test subdirectory ./tests/uil/Callbacks, part of this test
involves specifying a reason more than once in the same
callback list.  This is a valid operation, but will cause
seven informational messages while compiling the file
multC.uil.  These messages are expected, and the file
multC.uid is still generated.

Second, in the test subdirectory ./tests/uil/matrix, the
build is accomplished by running the shell script
./tests/uil/matrix/Build instead of using the Makefile.
Also, in order for the MIT Athena Toolkit widget, which is
in the AA directory, to compile correctly, the MIT Athena
widget set, including libraries and header files, must be
installed on your machine.  If the Athena widgets are not
installed, testing can only be performed using on the base
tree, and with the WML technology with a new Motif widget
added, which is in the directory MA.

6.3  Running the User Interface Language Tests

The tests in this section fall into two types.

Interactive       These include a MessageBox with instruc-
                  tions for running and interpreting the
                  test.  The instructions describe what you
                  should see on the screen.  You should try
                  all the actions described in the instruc-
                  tions.  The tests in the test subdirec-
                  tories EnumVal, ForRef, Syntax, CallUil,
                  matrix, and widgets are interactive tests.

Noninteractive    These run without input from the user and
                  print their results out to the standard
                  output or to a file.  The tests in the
                  test subdirectories Callbacks, NL, dataS-
                  tructs, and validator, and the test ForRef
                  in the ForRef subdirectory are noninterac-
                  tive tests.

You should generally run the uil section tests from the run
scripts provided.  To have tests appear in the top left
corner of the root window the resource Mwm*clientAutoPlace
should be set to false in you .Xdefaults file.

The matrix tests should be run using the script
./tests/uil/matrix/Test

In the widgets test subdirectory, callbacks are handled by
printing to the name of the callback that has been trig-
gered, and the reason for what callback to the standard out-
put.  To find out how to trigger a callback, refer to the
appropriate page in the OSF Motif Programmers Reference
Manual.  A callback is active when it is defined as ON in
the message portion of the test.
