DEFINITION MODULE DMEntryForms;
(*******************************************************************
Module DMEntryForms ('Dialog Machine' DM_V3.0)
Copyright (c) 1986-2006 by Andreas Fischlin and ETH Zurich.
Purpose Manage entry forms for data entry in a
modal dialog.
Remarks Entry forms allow the user to enter data to an
application program. The entering of
values for all elementary data types, characters,
strings, numbers (integers, cardinals, reals),
and so-called controls (pushbuttons, radio buttons,
checkboxes, scroll bars) are supported.
Method: The content of entry forms are defined
by means of declarative procedure calls. They
define size and position of editing
fields associated with a variable of the specifed
data type. Fields may be used for the entry
of characters, strings, integers, cardinals, reals,
and other input (e.g. pushbuttons, analog input by
means of scroll bars, checkboxes, and radio
buttons). Positions within the dialog window are
specified by a grid. Each cell has the
average width of a character of the currently used
font. Once the specifications of the dialog window
have been made, it may be activated anytime in
order to request the actual input. A
standard set of push-buttons is
added automatically to allow the user to signal his
acceptance or to abort the input.
This module belongs to the 'Dialog Machine'.
Programming
o Design
Andreas Fischlin 23/01/1986
o Implementation
Andreas Fischlin 23/01/1986
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 20/04/1991 AF
*******************************************************************)
FROM DMConversions IMPORT RealFormat;
(*************************************************)
(*##### Declarations of editable fields #####*)
(*************************************************)
TYPE
FormFrame = RECORD x,y: INTEGER; lines,columns: CARDINAL END;
(*
(x,y) defines the position of lower left corner relative to
background (see module DMWindows). (Any attempt to position
a portion of the entry form outside the screen results in
the positioning of the form in the centre of the screen;
not only does this avoid an inaccessable entry form, but it
has also offers the possibility to position the entry form
automatically in the middle of the screen, e.g. by passing
negative values for x and y, where the user will recognize
it most easily). The size of the form is specified in
character cells, i.e. the width of the form in columns and
height in lines.
*)
DefltUse = (useAsDeflt, noDeflt);
RadioButtonID;
VAR
FieldInstalled: BOOLEAN; (*returns success of any declaration*)
notInstalledRadioButton: RadioButtonID;
(*
Read only variable which may be used for variables of type
RadioButtonID to denote that the item has not yet been
installed. It is a good programming practice to assign this
value to all variables of type RadioButtonID during the
initialization phase of your program or after returning from
editing an entry form (see below procedure UseEntryForm).
*)
PROCEDURE WriteLabel(line,col: CARDINAL; text: ARRAY OF CHAR);
(*may be used to display any additional textual information*)
(*****************************************************************
The following procedures support the entry of elementary data
types. Data is entered by defining fields with width fw (in char
cells). The data entry field will be displayed by enclosing it
with a rectangular frame. When declaring a field, a variable of
the corresponding type has to be provided which will contain the
value entered during the dialog after the entry form has been
activated by procedure UseEntryForm. Note, that the declaration
of the result variable has to be made on a scope level above or
equal to the one on which the dialog window is activated, i.e.
the variable must of course exist at the time of data entry. Data
entries are automatically tested for correct syntax and their
values. The syntax is that of Modula-2 and the ranges of the
accepted values may be provided by entering appropriate values
for the interval boundaries (the interval boundaries are legal
values). An open interval may be created by assigning to either
of the boundary values the system dependent values MIN(Type) or
MAX(Type). In case one wishes to provide default values, they may
be passed into the edit field by assigning the default values to
the result variable before activating the entry form. Note that
in the latter case, the field declaration must use useAsDeflt as
actual value for the formal parameter du (default use).
*****************************************************************)
PROCEDURE CharField(line,col: CARDINAL; VAR ch: CHAR; du: DefltUse;
legalCharset: ARRAY OF CHAR);
(*
The character ch is only accepted if its value is equal to
one of the characters contained in the string legalCharset
(tests are made case sensitive, hence to allow for case
insensitive entry you must specify in legalCharset all
possibilities, e.g. "AaBbCcDd..." etc.). If any character is
acceptable, pass an empty legalCharset (""). Normally
exactly one character must be entered by the user, i.e. not
none nor more than one character are acceptable. There can
be made an exception to this rule so that no entry becomes
acceptable too, by listing the character ASCII DEL (177C) as
the very first in legalCharset.
*)
PROCEDURE StringField(line,col: CARDINAL; fw: CARDINAL;
VAR string: ARRAY OF CHAR; du: DefltUse);
(*any string may be entered*)
PROCEDURE CardField(line,col: CARDINAL;
fw: CARDINAL; (*maximum number of digits expected*)
VAR card: CARDINAL; du: DefltUse;
minCard,maxCard: CARDINAL);
PROCEDURE LongCardField (line,col: CARDINAL; fw: CARDINAL;
VAR longCard: LONGCARD; du: DefltUse;
minLCard,maxLCard: LONGCARD);
(*
card resp. longCard are only accepted if the syntax is legal
and if the value falls within the range [minCard..maxCard]
*)
PROCEDURE IntField(line,col: CARDINAL;
fw: CARDINAL; (*max number of digits+1 expected*)
VAR int: INTEGER; du: DefltUse;
minInt,maxInt: INTEGER);
PROCEDURE LongIntField (line,col: CARDINAL; fw: CARDINAL;
VAR longInt: LONGINT; du: DefltUse;
minLInt,maxLInt: LONGINT);
(*
int resp. longInt are only accepted if the syntax is legal
and if the value falls within the range [minInt..maxInt]
*)
PROCEDURE RealField(line,col: CARDINAL;
fw: CARDINAL; (*max number of digits+4 expected*)
VAR real: REAL; du: DefltUse;
minReal,maxReal: REAL);
PROCEDURE LongRealField (line,col: CARDINAL;
fw,dig: CARDINAL; fmt: RealFormat;
VAR longReal: LONGREAL; du: DefltUse;
minLReal,maxLReal: LONGREAL);
(*
real resp. longReal are only accepted if the syntax is legal
and if the value falls within range [minReal..maxReal]. dig
allows to specify the number of decimal digits, fmt the
notation which will be used when displaying the number.
*)
(*****************************************************************
The usual Macintosh data entry facilities, the so-called controls,
are supported by the following objects.
*****************************************************************)
PROCEDURE PushButton(line,col: CARDINAL; buttonText: ARRAY OF CHAR;
buttonWidth: CARDINAL; (*in char cells*)
pushButtonAction: PROC);
(*
The pushbutton labelled with the text buttonText (displayed
in the middle of the pushbutton) is placed with its left
side starting at char cell (line,col). If the pushbutton
is pressed (mouse click within the button), the associated
procedure pushButtonAction is called.
*)
PROCEDURE DefineRadioButtonSet(VAR radioButtonVar: RadioButtonID);
PROCEDURE RadioButton(VAR radButt: RadioButtonID;
line,col: CARDINAL; text: ARRAY OF CHAR);
(*
The radio button is placed in char cell (line,col),the text
is written to the right of the button. The initially
selected button is defined by the value assigned to variable
radioButtonVar before calling procedure UseEntryForm
*)
PROCEDURE CheckBox(line,col: CARDINAL; text: ARRAY OF CHAR;
VAR checkBoxVar: BOOLEAN);
(*
the check box is placed in char cell (line,col), the text is
written to the right of the check box. The initial selection
is determined by the value assigned to variable checkBox
before calling procedure UseEntryForm.
*)
(***************************************)
(*##### Entry Form Activation #####*)
(***************************************)
(*****************************************************************
The following procedures serve the activation of an entry form.
Note, that any declarations made before the actual activation
will be interpreted only at this moment. Hence, any assignments
of default values to an editingfield will be done just before
displaying the form. All forms will be displayed automatically
with a "OK" pushbutton as well as a "Cancel" pushbutton. Values
entered are considered to be valid only if the data entering
dialog has been terminated by issuing any of these two commands,
i.e. in the latter case, the values returned for individual items
should be considered undefined and should not be used for any
subsequent computations. Note that the proper treatment of this
situation is entirely the programmers responsibility. Only in the
case that the form is accepted ("OK" return) is it guaranteed
that the values of the individual dialog items confine to the
specifications made during their declarations. Returning from a
dialog implies the dismissal of its associated entry form, i.e.
any items to be reused have to be redeclared again before another
entry form may be requested.
Note: Entry forms together with Alerts, belong to the class
of so-called modal dialogs. A modal dialog forces the
user to finish the dialog by at least one answer
(activating the "OK"- pushbutton by clicking the mouse
on it (or its keyboard equivalents, hitting the "Return"
or "Enter" key) corresponds to the final acceptance of
all entries made during the dialog. A second minimal
answer may consist of the dismissal of all entries
made during the dialog, i.e. the activation of the
"Cancel"-pushbutton, respectively its keyboard
equivalent, which is pressing the "Command"-key
(Cloverleaf-key) simultaneously with the backspace key).
Also, a modeless dialog allows the user to make his entries
any time he wishes, i.e. he may turn his attention in the
middle of data entries to other activities before he
actually terminates the dialog by requesting the system to
do something with his data entered during the dialog.
*****************************************************************)
PROCEDURE UseEntryForm(bf: FormFrame; VAR ok: BOOLEAN);
(*
Use the entry form defined sofar by displaying its window
containing all the declared fields ready for data entry.
Pushing the "OK"-pushbutton or the "Cancel"-pushbutton
dismisses the form and terminates the associated modal dialog.
*)
END DMEntryForms.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib