xwChoice:
---------

XwChoice is a little help programm, I have created  for the installation
of the XW_TOOLS ( a printer driver for photo printing).

XwChoice is a powerfull GUI programm for building of interactive
scripts with an graphical interface.

You may generate choice list, message and error boxes as well as
a wait box which will disappear as soon as xwChoice will be called
again. Further more you will be able to open a log window which allow
to shown the contents of a log file (similar to the tail -f command).

The program xwChoice was deliberatelly write for use of the
Athena Widget Set, which is not very power full but is available
for all plattforms and can be considered as stable (no new versions
which may be incompatible with previous versions). The Gtk++ or
the Qt libs are not installed on each UNIX / Linux computer. Motif /
Lesstif will normally not be installed for Linux Systems.

Provision is also foreseen for displaying of help messages which
can be taken from a file or from the command line.

Syntax:
-------
   xwChoice [-title titelString]                     \
            -message okButtonText messageFile        \
            [-geometry geometry]


   xwChoice [-title titelString]                     \
            -error   okButtonText errorFile
   
   
   xwChoice [-title titelString]                     \
            [-geometry geometry]                     \
            -question questionString                 \
            -choice choice1 answer1                  \
            -choice choice2 answer2                  \
            ...                                      \
            -choice choiceN answerN                  \
            [[-input | -Input] [-both]]              \
            [-defChoice choice?]                     \
            [-lines #]                               \
            [-columns #]                             \
            [-help   helpButtonText helpFile]        \
            [-cancel cancelButtonText cancelAnswer]  \
            [-noReturn]                              \
            -ok     okButtonText

   xwChoice [-title titelString] 
            -log okButtonText logFile                \
            [-lines #]                               \
            [-columns #]                             \


   xwChoice [-title titelString]                     \
            -wait okButtonText  waitMessageText

   xwChoice [-title titelString]                     \
            -log okButtonText  logFile

   xwChoice [-title titelString]                     \
            -tail okButtonText  logFile|-

answerN  = "" -> on OK return choiceN
answerN <> "" -> on OK return answerN
If the -noReturn option is set no item must be selected. If this
option is not set an item must be selected in order to return.
Normally xwChoice return the choice on standard output.
With the -defChoice option the given choice will be preselected in
the choice list.

The columns and the lines option allow you to specify howmany 
columns and lines will be dispkaywd at a time in the choice list.
If there are more choices as lines a scrollbar will be set appair
at the rigtht side of the list.

the message or error file may also be a string instead of a file.
xwChoice look first if ther is a file as passed by the message/error-File
argument and if such a file is not found the argument will be taken
as the message which is to be displayed.

if the cancel button is pressed xwChoice print the cancelAnswer
if the argument ist not a zero length string. Further more
xwChoice exit with the return code 3

   xwChoice [-title titelString]                     \
            [-geometry geometry]                     \
            -question questionString                 \
            -input                                   \
            [-help    helpButtonText helpFile]       \
            [-cancel  cancelButtonText cancelAnswer] \
            -ok       okButtonText

The value entered into the input field is returned, white space at
the beginning of string are deleted. a valid input (non white space
string) is required

   xwChoice [-title titelString]                     \
            [-geometry geometry]                     \
            -question questionString                 \
            -choice choice1 answer1                  \
            -choice choice2 answer2                  \
            ...                                      \
            -choice choiceN answerN                  \
            -input                                   \
            -both                                    \
            [-help   helpButtonText helpFile]        \
            [-cancel cancelButtonText cancelAnswer]  \
            -ok      okButtonText

The user can perform a choice or enter a value.
xwChoice return the value contained in the input field if any or
the selected item.
if the option both is given the item selected and then the value of the
input field are returned.

The help file may also be replaced by a message to be displayed.

   xwChoice [-title titleString]                     \
             -wait OkButtonString "waitFile"

The wait file may also be replaced by a message to be displayed.

xwChoice will be poped up and if an other instance of xwChoice
is started it will be stopped.

The -log option allow to display the wohl content of a file within
a scrolled text widget.

The -tail option allow to display the wohl content of a file within
a scrolled text widget. The difference is that you may pass data via
stdin to xwChoice and may also write to an file and see immedialtly
the new textes.

Translation for the text widget (option -input)
----------------------------------------------
The <Return> and <Tab> key cant be enterred.

The <Space> is only allowed if you pass the option -Input instead of -input
to xwChoice.

Further printable characters may be deleted from the allowed characters
The option -deny  '*;!^<>:/\"'\' make that the characters *, !, ^, ;,
<, >, :, /, \, ", and ' generate a Bell while pressing the return pushbutton,
the window will not been closed until the error was eliminated.


Keyboard handling
-----------------

The <RETURN>, <TAB>, <SHIFT>+<TAB>, and the cursor key may be used
to change the active widget and or select an item in the chouice list.

With <TAB> / <SHIFT>+<TAB> the selected widget is changed. The input
widget and the choice list will be surrounded by a blue frame if actif.
The button will be repesented with a balck inner border as usual with
libXaw.

The <RETURN> key is only valid if a button is selected. This is alway
the case for the message, error and log boxes.

The cursor key will only work within the choice list, the right and left
cursor only in multi columns mode.

BUG
---

Release of the mouse button outside a previously activated button
dont work correctly (input are alway directed to the selected widget),
in this case the button which was activated by pressing the left
mouse button, so that releasing of the mouse button will always 
produce the action affected to the pressed button.

Multiple choice is not implemented.

 
Return value:
-------------

- 0 OK
- 1 error (OS)
- 2 wrong option
- 3 cancel was pressed
