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