                         The documentation to

                               FORM.PLG

                                 1.2
                          September 16, 1998

                                  by

                           Alexander Clauss
                            Reuterallee 39
                           64297 Darmstadt
                    aclauss@hrzpub.tu-darmstadt.de
                 (English Translation by Mark Wherry)



Contents
========

 1  Introduction

 2  Legal

 3  Installation

 4  Requirements

 5  Features

 6  Functions of the Plugins
    6.1  Form.New
    6.2  Form.Add
    6.3  Form.Do
    6.4  Form.Get
    6.5  Form.Delete
    6.6  Form.Input
    6.7  Form.Note

 7  An Example

 8  Future versions

 9  History

10  TransAction



1  Introduction
***************

FORM.PLG is a plug-in for Scripter from ASH (or Simple Script) which
makes the creation and handling of simple dialog boxes (or forms)
possible. The emphasis here lies on the word simple, because it should
also make adding dialogs to scripts very easy for the programmer.



2  Legal
********

This plugin is freeware, and may be enclosed with any script that you
write, on condition that these instructions (FORM_PLG.TXT or 
FORM_PLG.HYP) are always included.

FORM.PLG was written by Alexander Clauss, Reuterallee 39, 64297
Darmstadt.

Email: Alexander_Clauss@OF2.maus.de



3  Installation
***************

Simply copy the file FORM.PLG into the Scripter (or Simple Script)
PLUGIN folder. There is nothing else to do!



4  Requirements
***************

This Plugin requires either a current version of WDIALOG.PRG or the
MagiC Operating System (version 4+), and naturally a copy of ASH-
Scripter, or Simple Script.



5  Features
***********

    Dialogs in windows.

    Any number of running scripts can create dialogs simultaneously.

    Keyboard shortcuts are automatically assigned.

    Very simple handling of the dialog boxes.

    Because MagiC/WDialog features are used, memory requirements are
     low.

    The operating elements (maximum of about 100 per dialog) can be
     freely placed.



6  Functions of the Plugins
***************************

This plug-in extends Scripter (or Simple Script) with the following
commands:


6.1  Form.New
=============

id = Form.New(title,buttons,width,height);

This function generates a new dialog, which will not yet be visible.

 title     The title of the dialog/form (string).

 buttons   The exit buttons of the dialog (string). The parameter is
           set up like this: "button1|button2|button3|...". If the
           first character of the button name is '@', this button will
           be used as the default button.

 width     The width of the dialog in characters (integer).

 height    The height of the dialog in characters (integer).

 id        This call will return the handle of the dialog that has
           been created. You will need to use this handle with all of
           the following functions, as it allows each dialog to be
           uniquely identified (long).


6.2  Form.Add
=============

obj = Form.Add(id,Type,x,y,label,...);

With this function you can add further objects to the dialog, like
checkboxes, radio-buttons, and so on...

 id      The handle of the dialog (long).

 Type    The type of object you wish to add (string). The use of small
         (initial) letters, as in previous versions, has been
         abandoned. Available Types: 'GroupBox' (or 'Group'),
         'CheckBox' (or 'Check'), 'RadioButton' (or 'Radio'), 'Text',
         'Edit', or 'Button'. If the user clicks on an object which is
         of the type 'button', the dialog exits.

 x,y     The position of the object in characters (integer).

 label   The name of the object (string). With radio-buttons, the
         names of each button are included together and separated by
         the '|' character. If the button name starts with a preceding
         '@' character, this will be the radio-button that is selected
         by default when the dialog is opened.

         With edit fields, the string specified will be the preset
         contents of the input field.

 ...     Further parameters used in this call will depend on which
         type of object you are adding.

          GroupBox

             width     Width of the box in characters (integer).

             height    Height of the box in characters (integer).

          CheckBox

             state     Initial state of the box. The following values
                       will indicate that the checkbox will be
                       selected: 1, 'true', 'selected', 'checked'.
                       Anything else will mean that the checkbox will
                       not be selected when the dialog is displayed.

          Edit

             length    The length of the input field in characters
                       (integer).

             allowed   Defines character by character, the format that
                       is valid in the input field. If there is an
                       error with this paramter, 'X' is assumed by
                       default.

                        '9'  Allow only numbers/digits.

                        'A'  Allow only wild characters/spaces.

                        'a'  Allow only characters/spaces.

                        'N'  Wild characters, digits, space
                             characters.

                        'n'  Characters, digits, space characters.

                        'F'  Characters in filenames are allowed.

                        'P'  Characters in path names are allowed.

                        'p'  Characters in path names, but without '*'
                             and '?'.

                        'm'  Characters in long filenames are allowed.

                        'X'  Allow all characters.

 obj     A handle for the object, which is used in order to inquire
         about its state, or to evaluate its contents (integer).


6.3  Form.Do
============

exitBut = Form.Do(id);

The dialog is displayed. The script only continues when the dialog box
has been closed. The return value will hold the name of the button
that the user clicked on to end the dialog.


6.4  Form.Get
=============

value = Form.Get(id,obj);

Ascertains information from the object 'obj' in the dialog with the
handle 'id'. The result differs depending on the type of the object:

 CheckBox        If the checkbox is selected, value will contain
                 'Selected', otherwise if the checkbox was not
                 selected, nothing will be returned.

 RadioButton     The text of the selected button.

 Edit            The text that was entered.

 Anything else   The value or name of the object.


6.5  Form.Delete
================

Form.Delete(id);

Deletes the dialog from memory. No more data can be retrieved from
this dialog.


6.6  Form.Input
===============

RetValue = Form.Input(Prompt,Default_Text);

Displays a simple dialog in which a single text field is provided. The
dialog is made up of a text line, a text input and the 'OK' and 'Cancel'
buttons.

 Prompt           Displays a message which should contain instructions
                  guiding the user with what they have to enter.

 Default_Text     This is the text that will be displayed in the input
                  text field when the dialog is first opened.

 RetValue         The value returned by this function is passed in two
                  parts.

                  RetValue[0] contains 'OK' or 'Cancel', depending on
                  which button the user clicked to close the dialog.

                  RetValue[1] contains the text that was entered by
                  the user.


6.7  Form.Note
==============

exitBut = Form.Note(Title,text,buttons);

Opens a reference dialog which displays the specified text, and any
number of exit buttons.

 title     The title of the box is displayed in the title line of the
           windowed dialog.

 Text      The text that is displayed in the dialog box. This text can
           be almost as long as you like! The '|' character indicates
           a line break, and the following text will be displayed on a
           new line. You should not use more than approximately 18
           lines, as with this number, the dialog can still be
           displayed on a SM124 montor.

 buttons   The exit buttons of the dialog. Different buttons are
           separated with the '|' character. If the '@' character is
           the first character of the button name, this button will be
           used as the default button. If there is an error with this
           parameter, only an 'OK' button will be provided.

 exitBut   The text of the button that was clicked on.



7  An Example
*************


// Create a dialog with space for 37x7 characters.
id     = Form.New("Test-Dialog", "@OK|Cancel", 37, 7);


// Place groups
group1 = Form.Add(id,"Group",0,0," Group 1 ",18,5);
group2 = Form.Add(id,"Group",19,0," Group 2 ",18,5);

// Add a few checkboxes to the dialog.
check1 = Form.Add(id,"Check",1,1,"Choice 1","selected");
check2 = Form.Add(id,"Check",1,2,"Choice 2");
check3 = Form.Add(id,"Check",1,3,"Choice 3");

// Add a few radio-buttons, of which only one can be selected at a time.
radio  = Form.Add(id,"Radio",20,1,"Radio 1|@Radio 2|Radio 3");

// A field for any text input.
edit   = Form.Add(id,"Edit",1,6,"Default-Text",35);


// Display the dialog. Form.Do returns the exit value as soon as a button
// has been clicked on.
exit   = form.Do(id);


// Now we can can evaluate the contents and state of the objects.
print("Dialog was exited by the user clicking [",exit,"]");
print();
print("Text from Groupbox 1   : ",Form.Get(id,group1));
print("Text from Groupbox 2   : ",Form.Get(id,group2));
print("Value from Checkbox 1  : ",Form.Get(id,check1));
print("Value from Checkbox 2  : ",Form.Get(id,check2));
print("Value from Checkbox 3  : ",Form.Get(id,check3));
print("Selected Radio-button  : ",Form.Get(id,radio));
print("Text in the edit field : ",Form.Get(id,edit));


// Now delete the dialog from memory.
Form.Delete(id);

// Finished!



8  Future versions
******************

In future versions popups, list boxes and special fields to handle the
choice from file selectors, characters or colours will be implemented.
Further objects may also be added.

If and when the plug-in is extended, I would like to know what you
think of the new features, and if there is anything else you would
like me to add. I am always interested in your ideas and particularly
in feedback from users or script programmers.



9  History
**********

 V1.0:  First version

 V1.1:  New functions: Form.Input and Form.Note. This adds both of the
   functions from the dialog plug-in. Using both the form and dialog
   plugins is therefore no longer necessary.

 V1.2:  Bugfix: If no input was made in the input field created with
   Form.Input, errors occurred.



10  TransAction
***************

TransAction is the world's first translation crew! We reckoned since
demo coders get together in crews so could we. We take the best
software around and work with the authors to bring you English
releases. We've all been translating software for years so we decided
it was time to pool our efforts. Currently we only translate German
and French software into English but if you want to extend the crew
get in touch! The TransAction crew are:

    [JC:] Joe 'InterActive' Connor: jconnor@cix.co.uk

    [ML:] Mick Lock: mlocka@cix.co.uk

    [PW:] Peter West: xlator@cix.co.uk

    [CW:] Colin Watson: cwatsonb@cix.co.uk

    [MW:] Mark Wherry: mark_wherry@cix.co.uk

    [TransAction:] 12 Portal Road, Aylesbury, Bucks HP22 5PR

    [Telephone:] +44 (0)1296 622400 leave us a message on the
     answerphone!

    [Email:] m.lock@zetnet.co.uk or mlocka@cix.co.uk

    [Home page:]
     http://www.users.zetnet.co.uk/micklock/transact/index.htm



