/* $XConsortium: README /main/7 1996/07/15 14:19:33 drk $ */
This directory contains the following tests for measuring the performance of
XmText and XmCSText widgets.

CSTextEnter
CSTextScroll
TextScroll
TextWorst

Below is a description of each test along with the instructions for running
the test.

CSTextEnter:
===========

Description:
-----------

CSTextEnter can be used to measure the performance of entering a large
number of text characters into an XmCSText or an XmText widget.
The test should be run automated to allow the automation performance monitor to
measure the time elapsed in the entering of text.
Please note that the automation performance monitor is affected by the
current system load.

The automation script will enter text 9600 characters total into the widget.
The characters will be entered in sets of 50 character long strings. 
There will be six measurements taken. Each measurement will correspond
to a total of 1600 characters entered into the widget.
Ideally, these six measurements should not vary significantly.

Defaults:
--------

By default, this test uses an XmCSText with the XmNwordWrap resource
set to False.

Options:
-------

There are two command line options which can be specified when running the test.
1. -use_word_wrap  - to create a text widget with XmNwordWrap set to True.
2. -regular_text   - to use an XmText widget instead of the default XmCSText.

Required Runs:
-------------

A complete run of this test involves four runs with the following command
line options specified:

1. CSTextEnter                                    - Tests an XmCSText widget 
                                                    with XmNwordWarp = False.
         
2. CSTextEnter -use_word_wrap                     - Tests an XmCSText widget 
                                                    with XmNwordWrap = True.
         
3. CSTextEnter -regular_text                      - Tests an XmText widget with
                                                    XmNwordWarp = False.
         
4. CSTextEnter -regular_text -use_word_wrap       - Tests an XmText widget with
                                                    XmNwordWrap = True.
         
Output:
------
The measurements taken will be reported to the file named CSTextEnter.prt
in the current directory.
Since each run of the test produces a file named CSTextEnter.prt, output
from the previous run should be moved to a file of another name prior
to each new run of the test.


CSTextScroll:
============

Description:
-----------

This test is used to measure the performance of a Scrolled CSText widget
when dealing with a large amount of text.
The Scrolled CSText widget is created with 80 columns and 24 rows.
Measurements are taken for the following actions:
  o Loading a large text file into a buffer.
  o Generating an XmString using the buffered text. 
  o Assigning the XmString to the XmCSText widget.
  o Scrolling to the end of the text.
  o Scrolling to the beginning of the text.

Defaults:
--------

By default, a Scrolled XmCSText widget is created with the resources
XmNresizeHeight, XmNresizeWidth and XmNwordWrap all set to False.
A large text file, ./../DataSpace/RowCol1_1.c, is displayed in the
XmCSText widget.

Options:
-------

There are four command line options which can be specified for this test:
1. -u -show_perf_bug       - Creates XmCSText widget with XmNresizeHeight
                             and XmNresizeWidth set to True.
                             With this option, the XmCSText widget attempts
                             to resize its height and width to accommodate
                             all the text being displayed in the widget.
                             The default text file, ./../DataSpace/RowCol1_1.c
                             is displayed in the widget. This file contains
                             approximately 80 characters per line.

2. -u -use_word_wrap       - Creates XmCSText widget with XmNwordWrap set
                             to True and XmNresizeHeight and XmNresizeWidth set
                             to False.
                             The default text file, ./../DataSpace/RowCol1_1.c
                             is displayed in the widget. This file contains
                             approximately 80 characters per line.

3. -u -test_word_wrap_on   - Creates XmCSText widget with XmNwordWrap set
                             to True.  The text file, 
                             ./../DataSpace/WordWrap.dat is displayed in
                             the widget.  This file contains approximately
                             500 characters per line. When text is
                             displayed, the characters should wrap around
                             to fit within the horizontal boundaries of the
                             widget.
                             
4. -u -test-word_wrap_off  - Creates XmCSText widget with XmNwordWrap set
                             to False. The text file, 
                             ./../DataSpace/WordWrap.dat is displayed in
                             the widget. This file contains approximately
                             500 characters per line. When text is displayed,
                             the characters beyond the 80 column boundary
                             will be clipped at the widget borders. 

5. -u "-f <filename>"      - Loads the text file, <filename>, to be displayed
                             in the widget. NOTE: There is a maximum line
                             length of 1024 characters. The <filename>
                             specified should not exceed this maximum.

Required Runs:
-------------

A complete run of this test involves four runs with the following command
line options specified:

1. CSTextScroll                                  - Tests XmCSText widget with
                                                   XmNwordWrap, XmNresizeWidth,
                                                   and XmNresizeHeight = False.

2. CSTextScroll -u -show_perf_bug                - Tests XmCSText widget with
                                                   XmNwordWrap = False,
                                                   XmNresizeWidth and 
                                                   XmNresizeHeight = True. 

3. TextScroll -u -use_word_wrap                  - Tests XmText widget with
                                                   XmNwordWrap = True and
                                                   XmNresizeWidth and
                                                   XmNresizeHeight = False.

4. CSTextScroll -u -test_word_wrap_on            - Test XmCSText widget with
                                                   XmNwordWrap = True and
                                                   displays a file containing
                                                   approximately 500 characters
                                                   per line. 

5. CSTextScroll -u -test_word_wrap_off           - Tests XmCSText widget with
                                                   XmNwordWrap = False and
                                                   displays a file containing
                                                   approximately 500 characters 
                                                   per line. 

Output:
------
The measurements taken will be reported to the file named CSTextScroll.out
in the current directory. If the file cannot be created in the current directory
it will be created under /tmp. 
Since each run of the test produces a file named CSTextScroll.out, output
from the previous run should be moved to a file of another name prior
to each new run of the test.

TextScroll:
============

Description:
-----------

This test is used to measure the performance of a Scrolled Text widget
when dealing with a large amount of text.
The Scrolled Text widget is created with 80 columns and 24 rows.
Measurements are taken for the following actions:
  o Loading a large text file into a buffer.
  o Assigning the buffered text to the XmText widget.
  o Scrolling to the end of the text.
  o Scrolling to the beginning of the text.

Defaults:
--------

By default, a Scrolled XmText widget is created with the resources
XmNresizeHeight, XmNresizeWidth and XmNwordWrap all set to False.
A large text file, ./../DataSpace/RowCol1_1.c, is displayed in the
XmText widget.

Options:
-------

There are four command line options which can be specified for this test:
1. -u -show_perf_bug       - Creates XmText widget with XmNresizeHeight
                             and XmNresizeWidth set to True.
                             With this option, the XmText widget attempts
                             to resize its height and width to accommodate
                             all the text being displayed in the widget.
                             The default text file, ./../DataSpace/RowCol1_1.c
                             is displayed in the widget. This file contains
                             approximately 80 characters per line.

2. -u -use_word_wrap       - Creates XmCSText widget with XmNwordWrap set
                             to True and XmNresizeHeight and XmNresizeWidth set
                             to False.
                             The default text file, ./../DataSpace/RowCol1_1.c
                             is displayed in the widget. This file contains
                             approximately 80 characters per line.

3. -u -test_word_wrap_on   - Creates XmText widget with XmNwordWrap set
                             to True.  The text file,
                             ./../DataSpace/WordWrap.dat is displayed in
                             the widget.  This file contains approximately
                             500 characters per line. When text is
                             displayed, the characters should wrap around
                             to fit within the horizontal boundaries of the
                             widget.

4. -u -test-word_wrap_off  - Creates XmText widget with XmNwordWrap set
                             to False. The text file,
                             ./../DataSpace/WordWrap.dat is displayed in
                             the widget. This file contains approximately
                             500 characters per line. When text is displayed,
                             the characters beyond the 80 column boundary
                             will be clipped at the widget borders.

5. -u "-f <filename>"      - Loads the text file, <filename>, to be displayed
                             in the widget. NOTE: There is a maximum line
                             length of 512 characters. The <filename>
                             specified should not exceed this maximum.

Required Runs:
-------------

A complete run of this test involves four runs with the following command
line options specified:

1. TextScroll                                    - Tests XmText widget with
                                                   XmNwordWrap, XmNresizeWidth,
                                                   and XmNresizeHeight = False.

2. TextScroll -u -show_perf_bug                  - Tests XmText widget with
                                                   XmNwordWrap = False,
                                                   XmNresizeWidth and
                                                   XmNresizeHeight = True.

3. TextScroll -u -use_word_wrap                  - Tests XmText widget with
                                                   XmNwordWrap = True and
                                                   XmNresizeWidth and
                                                   XmNresizeHeight = False.

4. TextScroll -u -test_word_wrap_on              - Test XmText widget with
                                                   XmNwordWrap = True and
                                                   displays a file containing
                                                   approximately 500 characters
                                                   per line.

5. TextScroll -u -test_word_wrap_off             - Tests XmText widget with
                                                   XmNwordWrap = False and
                                                   displays a file containing
                                                   approximately 500 characters
                                                   per line.

Output:
------
The measurements taken will be reported to the file named TextScroll.out
in the current directory. If the file cannot be created in the current directory
it will be created under /tmp.
Since each run of the test produces a file named TextScroll.out, output
from the previous run should be moved to a file of another name prior
to each new run of the test.



TextWorst:
=========

Description:
-----------

Measures the performance of scrolling an XmText widget when the widget
is large enough to fill the screen.


Defaults:
--------

By default, the XmNwordWrap is False. The widget is filled with the
character 'n'.  The is displayed in a "6x10" font if its available,
otherwise it falls back to a "fixed" font. 

Options:
-------

1. -use_word_wrap                      - Creates XmText widget with 
                                         XmNwordWrap = True.

Required Runs:
-------------

A complete run of this test involves two runs with the following command
line options specified:

TextWorst                              - Tests XmText widget with XmNwordWrap =
                                         False. 

TextWorst -use_word_wrap               - Tests XmText widget with XmNwordWrap =
                                         True. 

Output:
------
The measurements taken will be reported to the file named TextWorst.out
in the current directory. If the file cannot be created in the current directory
it will be created under /tmp. 
Since each run of the test produces a file named TextWorst.out, output
from the previous run should be moved to a file of another name prior
to each new run of the test.

