/* $XConsortium: README /main/4 1996/07/15 14:25:32 drk $ */
3.  OSF/Motif Toolkit Tests

This README describes the OSF/Motif Toolkit tests.  It pro-
vides 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/Toolkit to
identify the top directory of the Toolkit 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/Toolkit
translates to /source/Motif/tests/Toolkit at your site.

3.1  Overview and Directory Structure

The OSF/Motif Toolkit test directory, ./tests/Toolkit, con-
sists 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 subdirectory ./tests/Toolkit/bitmaps contains bit-
     maps used by some of the Toolkit tests.

   * The Buttons subdirectory contains the toolkit tests of
     Button widgets and gadgets.  This test subdirectory
     contains the following tests.

     ArrowBGad1   ArrowBtn4   PushBtn2
     ArrowBGad2   DrawnBtn1   ToggleBGad1
     ArrowBGad3   DrawnBtn2   ToggleBGad2
     ArrowBGad4   PushBGad1   ToggleBGad3
     ArrowBGad5   PushBGad2   ToggleBGad4
     ArrowBtn1    PushBGad3   ToggleBtn1
     ArrowBtn2    PushBGad4   ToggleBtn2
     ArrowBtn3    PushBtn1

   * The Constraint subdirectory contains the toolkit tests
     of Form and PanedWindow constraints.  This test sub-
     directory contains the following tests.

     Form1    Form16      PanedWin1
     Form2    Form17      PanedWin2
     Form3    Form18      PanedWin3
     Form4    Form19      PanedWin4
     Form5    Form20      PanedWin5
     Form6    Form21      PanedWin6
     Form7    Form22      PanedWin7
     Form8    Form23      PanedWin8
     Form9    Form24      PanedWin9
     Form10   Form25      PanedWin10
     Form11   Form26      PanedWin11
     Form12   Form27      PanedWin12
     Form13   Form28      PanedWin13
     Form14   FormDia1    PanedWin14
     Form15   PanedWin1

   * The CutPaste subdirectory contains the toolkit tests of
     the cut and paste mechanisms.  This test subdirectory
     contains the following tests.

     Cutpaste1    Cutpaste3    icccm
     Cutpaste2a   Cutpaste4a   multi
     Cutpaste2b   Cutpaste4b

   * The List subdirectory contains the toolkit tests of the
     List widget.  This test subdirectory contains the fol-
     lowing tests.

     List1   List5         ScrollList2
     List2   List6         ScrollList3
     List3   List7         ScrollList4
     List4   ScrollList1

   * The Manager subdirectory contains the toolkit tests of
     the various manager widgets.  This test subdirectory
     contains the following tests.

     BBoard1   BBoard7     Frame1
     BBoard2   DrawArea1   Frame2
     BBoard3   DrawArea2   Frame3
     BBoard4   RowCol1     Frame4
     BBoard5   RowCol2
     BBoard6   RowCol3

   * The Menus subdirectory contains the toolkit tests of
     Menus and Menu systems.  This test subdirectory con-
     tains the following tests.

     Menu1   MenuBar1      PopupMenu1
     Menu2   MenuGad1      PopupMenu2
     Menu3   OptionMenu1   RowCol1
     Menu4   OptionMenu2   RowCol2
     Menu5   OptionMenu3   Simple1
     Menu6   OptionMenu4   WindowMenu1

   * The Message subdirectory contains the toolkit tests of
     MessageBoxes.  This test subdirectory contains the fol-
     lowing tests.

     ErrorDia1     MessageBox5   QuestionDia1
     InfoDia1      MessageBox6   QuestionDia2
     MessageBox1   MessageBox7   WarningDia1
     MessageBox2   MessageBox8   WorkingDia1
     MessageBox3   MessageDia1
     MessageBox4   MessageDia2

   * The Other subdirectory contains the toolkit tests of
     miscellaneous toolkit functions.  This test subdirec-
     tory contains the following tests.

     Color1        Navigation5    Navigation11
     Grab1         Navigation6    ResPartOff
     Navigation1   Navigation7    TrackingLoc1
     Navigation2   Navigation8    Conversion1
     Navigation3   Navigation9    Conversion2
     Navigation4   Navigation10

   * The Primitive subdirectory contains the toolkit tests
     of primitive Motif widgets and gadgets.  This test sub-
     directory contains the following tests.

     Label1      Scrollbar1   Scrollbar8
     Label2      Scrollbar2   Scrollbar9
     Label3      Scrollbar3   Scrollbar10
     Label4      Scrollbar4   Scrollbar11
     Label5      Scrollbar5   Separ1
     Label6      Scrollbar6   SeparGad1
     LabelGad1   Scrollbar7

   * The Select subdirectory contains the toolkit tests of
     selection dialogs and Scale.  This test subdirectory
     contains the following tests.

     Command1      Scale1   Scale7
     Command2      Scale2   Scale8
     Command3      Scale3   Scale9
     FileSelect1   Scale4   Scale10
     FileSelect2   Scale5   SelectBox1
     PromptDia1    Scale6

   * The Shells subdirectory contains the toolkit tests of
     shells.  This test subdirectory contains the following
     tests.

     DiaShell1   DiaShell2

   * The Text subdirectory contains the toolkit tests of the
     Text and TextField widgets.  This test subdirectory
     contains the following tests.

     ScrollText1   Text3   Text8
     ScrollText2   Text4   Text9
     ScrollText3   Text5   TextField1
     Text1         Text6   TextField2
     Text2         Text7

   * The Windows subdirectory contains the toolkit tests of
     MainWindows and ScrolledWindows.  This test subdirec-
     tory contains the following tests.

     MainWin1     ScrollWin2   ScrollWin5
     MainWin2     ScrollWin3
     ScrollWin1   ScrollWin4

Each test subdirectory contains the following common files.
Each test subdirectory may not contain all of the different
files.

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

   * The README file contains information specific to that
     test directory's build and run procedure.  A README
     file will only exist if the test subdirectory has a
     nonstandard build or run procedure, or if a bug exists
     in one of the tests.

   * The file RUN is used to run all the Toolkit tests in
     series.  In some instances the RUN script also initial-
     izes a test before running it.

   * Test source files consisting of the suffixes .c, .h,
     and .uil.

   * The file allheaders.h contains declarations used by
     most of the tests.

3.2  Compiling the Tests

All the tests 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/Toolkit
     directory.

   * You can build just the tests in one test subdirectory
     using the make all command from the specific test sub-
     directory.  For example, to build the tests in the List
     subdirectory, enter the make all command from the
     ./tests/Toolkit/List test subdirectory.

The compiled tests use a large amount of disk space.  You
may prefer to build each test separately if disk space is
limited at your site. You can build each test individually
using the make command for each test.  For example, to build
the Text4 test in the Text test subdirectory, enter the com-
mand make Text4 from the ./tests/Toolkit/Text test subdirec-
tory.

3.3  Running the Toolkit Tests

The tests in this section are interactive tests.  They
include a MessageBox with instructions for running and
interpreting the test.  The MessageBox provides step-by-step
instructions for running each test.  The instructions assume
you have a general knowledge of Motif behavior, and often
omit simple descriptions of what to expect after each step.
For example, if the instructions say that you should resize
a window, they assume that you know to look for problems in
resizing, such as improper layout after the resize, or
visual corruption of the elements.

The instructions also often omit repetitive instructions or
results.  For example, if the instructions say that you
should press the button marked Clear and that this should
clear a text area, they assume that you will look for the
text area to clear every time you are instructed to press
the Clear button in that test.

You can run all the tests in a test subdirectory in series
with the RUN script in the specific test subdirectory.  In
some cases the RUN script initializes a test or cleans up
after a test is executed.  These initialization and cleanup
procedures are described where appropriate in the following
information about running the tests individually.

To run most of the tests individually, simply enter the name
of the compiled test in the appropriate test subdirectory.
For example, enter PushBtn1 in the ./tests/Toolkit/Buttons
test subdirectory to run the PushBtn1 test.

The following tests require special initialization and
cleanup procedures.

CutPaste/CutPaste2*
                  This test requires multiple clients to
                  test cut and paste interaction among mul-
                  tiple clients.  First, two instances of
                  Cutpaste2a should be started up.  Second,
                  Cutpaste2b should be started up.  Then the
                  instructions can be followed correctly.
                  The RUN script simply insures that after
                  the test is completed, all the clients are
                  properly killed.  The script RUN_CP2 runs
                  this test independently.

CutPaste/Cutpaste4*
                  This test requires two clients to test cut
                  and paste interaction between clients.
                  Both Cutpaste4a and Cutpaste4b should be
                  started up, then the instructions can be
                  followed correctly.  The RUN script simply
                  insures that after the test is completed,
                  both clients are properly killed.  The
                  script RUN_CP4 runs this test indepen-
                  dently.

List/List3
                  This test requires special resources
                  located in the file List3DB.  The RUN
                  script saves the current resources, merges
                  in the new resources, runs the test, and
                  then restores the old resources using the
                  following commands.

                  xrdb -e /tmp/$$tmp1
                  xrdb -merge List3DB
                  List3
                  xrdb -load /tmp/$$tmp1

Other/Conversion1 This test is not interactive.  The results
                  of the test are sent to the standard out-
                  put.  The RUN script simply redirects the
                  results to the file conversion1.out.  This
                  test should produce a series of warning
                  messages.

Other/Conversion2 This test is not interactive.  The results
                  of the test are sent to the standard out-
                  put.  The RUN script simply redirects the
                  results to the file conversion2.out.  This
                  test should produce a series of warning
                  messages.

Select/FileSelect* This test relies on the file structure in
                  the directory ./tests/Toolkit/Select/FS
                  being available in the directory /tmp.
                  The RUN script executes the
                  ./tests/Toolkit/Select/setup script, which
                  copies the FS directory structure into
                  /tmp.  The RUN script then executes the
                  tests FileSelect1 and FileSelect2, and
                  finally executes the
                  ./tests/Toolkit/Select/clean script, which
                  removes the FS directory structure from
                  /tmp.

The program icccm is a simple client that is implemented
using the clipboard mechanism described by the ICCCM.  It
does not use any Motif clipboard mechanisms.  It contains
the following six PushButtons:

Request TARGETS   Prints to the standard output the results
                  of XConvertSelection from the clipboard
                  with ICCCM XA_TARGETS atom as the type
                  selected.

Request formats   Prints the results of XConvertSelection
                  through a loop of any data in the clip-
                  board found during the TARGETS request.

Request MULTIPLE  Does the same thing as Request formats
                  except it uses the ICCCM atom XA_MULTIPLE
                  and makes only one XConvertSelection call
                  to get all the TARGETS data.

Request TIMESTAMP Prints the results of XConvertSelection
                  using the ICCCM XA_TIMESTAMP atom.

Own CLIPBOARD     Calls XSetSelectionOwner setting itself as
                  the owner of the clipboard.

Quit              Quits the icccm application.

The program multi is a typical Motif client that uses the
clipboard.  It contains elements that can be cut or pasted
to the clipboard using the applications Popup Menu, which is
usually popped-up using mouse button 3.

Using icccm and multi together we test the interaction
between the Motif clipboard and standard ICCCM clipboards.
Run the test by starting up two multi clients and one icccm
client.  Verify that the clipboard operates properly between
two Motif clients by cutting and pasting between the two
multi clients.  You can then use the icccm client to verify
that the items cut from the Motif application can be prop-
erly recognized by a non-Motif client.  Verify that this
works correctly for regular cutting and cutting by name, and
that it works correctly for cutting strings, integers, pix-
maps, and various combinations of the three.  Also verify
that items cut from the icccm client can be pasted into the
multi clients by choosing Own CLIPBOARD from the icccm
client and then use the Inquire and Paste options in the
multi client.  Inquire should return STRING and INTEGER.
Paste should return ICCCM Clipboard Text and 911.
