/* $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.