Programmer 7500/MAX_PROGRAMMERS.iso/CLIPPER/MISC/MENUSPCS.ZIP/MENUS.REF

Text File | 1987-12-27 | 26.3 KB | 684 lines

     Copyright (c) 1987 by Morton Goldberg, All Rights Reserved

                        Menus for Scheme (tm)
                    Programmer's Reference Manual

                                 by

                           Morton Goldberg
                           3268 Alpine Dr.
                        Ann Arbor, MI  48108

                           [phone]
                        CompuServe: 72346,565

This is the programmer's reference manual for the shareware product
Menus for Scheme, an object-oriented implementation of menus.  It
uses the SCOOPS (Scheme Object Oriented Programming System) language
extension supplied with your copy of PC Scheme.  The file SCOOPS.FSL
must be loaded into the Scheme workspace before MENUS.FSL if Menus
for Scheme is to function.

The author's intent is to convey all the information that a
programmer will need to incorporate menus into an application
successfully.  The manual describes the procedures you will use to
construct instances of menus and other objects provided by Menus for
Scheme and the messages that your applications may send to control
the their behavior.  A glossary of the special terminology of object
oriented programming as it applies to SCOOPS is included.  You will
also find it helpful to be familiar with the chapter on SCOOPS in the
TI Scheme Language Reference Manual.


THE FACILITIES PROVIDED BY MENUS FOR SCHEME

A menu is a window that pops-up on the screen and presents the user
with two or more choices, called menu items.  When one of the menu
items is selected, it determines the next action taken by the
program.  The user may decide to cancel the menu without selecting
any of the menu items.

Menus for Scheme provides application programs with two classes of
menus, horizontal menus and vertical menus.  The two classes differ
only in their appearance on the screen.  Horizontal menus present all
their menu items on one line of the screen.  Vertical menus present
each of their menu items on a separate line of the screen.

Menu Item Selection by Means of the Bar-Cursor

A bar-cursor can be moved to cover a menu item.  The bar is moved by
the arrow keys,  but a selection is not made until the enter key is
pressed.

Menu Item Selection by Means of a Selector Key

Selection can also be made by pressing a selector key, which can be
any key on the keyboard that generates a single ASCII character.  The
selector is usually the first capitalized letter of the text
describing a menu item on the screen, but Menus for Scheme allows
arbitrary association between a selector and a menu item.  It even
allows for multiple selector keys to be associated with a single menu
item.

Item Selection Abort Forced by the Esc-Key

Pressing the Esc-key will always force a return from menu processing
without making a selection.

Secondary Popup Windows

When selecting a menu item results in an action that generates a user
message requiring no response from the user, a popup text window is
used to display the message.  The text window is erased when the user
presses the Esc-key.

When selecting a menu item results in an action requiring additional
input from the user, this may be solicited by means of a subsidiary
menu or by a popup query window, which is a popup window containing a
query message and an input field for receiving the user's response.
The input field is a string of spaces which may be displayed with
text attributes that differ from the text attributes of the rest of
the query window.  A cursor appears within the input field, signaling
its readiness to receive input.  Destructive backspace is supported
so the user can perform simple editing.  A query window is erased
when the user's response satisfies the query, or when the user
presses the Esc-key.


NOTATION

Symbols enclosed in angle brackets denote syntactic variables and
indicate the type of the actual expressions that they stand for.  For
example,

     (foo <integer>)

means

     (foo (+ 2 2))

is a valid expression.  Further, ellipses are used to indicate when
one or more expressions of the same type may appear.  Thus,

     #(string1 string2 ... )

means a vector of one or more expressions, each evaluating to a
string.


WINDOW PROPERTIES

The TI Scheme screen coordinate system is a zero-based, (row, column)
system with its origin (0, 0) at the top, left corner of the screen.
The position of a window is the position of its top, left-most text
character; borders are not considered by the positioning logic.
Placing a bordered window at (0, 0) will cause the both the top and
the left-hand side of the border to be clipped.  Consequently, to put
a window at the top, left corner of the screen, place it at (0, 0) if
it doesn't have a border, and place it at (1, 1) if it does.

A window created by Menus for Scheme is a popup text window.  This
means that it uses the same zero-based coordinate system as the
screen, but local to the window itself and that the origin of window
lies inside the border if there is one.  It also means that any test
underlying a window is saved before the window is displayed and
restored when the window is erased.

A window in Menus for Scheme is automatically sized to fit its
contents.  The application never has to tell Menus for Scheme how big
to make a menu or a secondary popup window.  On the other hand, if an
application needs to know the size of a window, it can get that
information from Menus for Scheme.


CONSTRUCTORS

Classes in Menus for Scheme are abstractions and can not be used
directly by applications.  An application must first construct
instances of any class it wants to use.  To make constructing
instances relatively easy, Menus for Scheme provides a constructor
for each of the classes described in this manual.  Constructors have
been named by adhering to the convention of prefixing the class name
with "make-" (e.g., the constructor for instances of class horizontal
menu is the procedure make-horizontal-menu).


MAKE-POPUP-TEXT-WINDOW

To create a popup text window, an application program evaluates an
expression of the form:

     (make-popup-text-window <init-list> <text>)

where <init-list> is a list of quoted symbols alternating with
initial values:

     ('w-top <integer>
      'w-left <integer>
      'n-attr <integer>
      'border? <boolean>)

The entries in <init-list> are:

'w-top <integer>

                The row position of the window on the screen.

'w-left <integer>

                The column position of the window on the screen.

'n-attr <integer>

                The window text attributes; see WINDOW-SET-ATTRIBUTE
                in the TI Scheme Language Reference Manual for
                further information.

'border? <boolean>

                If <boolean> evaluates to #t the window will have a
                border; if it evaluates to #f, it won't.

The <text> argument is a vector of strings

     #(<string1> <string2> ... )

which form the contents of the window; each element of the vector
will appear as a separate line of text when the window pops onto the
screen.

The <init-list> argument can viewed as a table with one line per
instance variable and two entries per line, the variable name (a
quoted symbol) and the value to be assigned to the variable.  The
quoting of the variable name must not be overlooked.


POPUP TEXT WINDOW EXAMPLES

The Scheme source code file MENEX.S, included with Menus for Scheme,
contains two examples of popup text windows.  The first of these is
the "quick brown fox" window.  It uses the global variable *fox-data*
to hold its <init-list> and the global variable *fox-text* to hold
its <text> vector.  In this case, the text is static; it does not
change each time the window pops onto the screen.

Note how the value of the text attributes paired with n-attr is
fetched from the *text-colors* environment.  A simple integer could
have been used, but fetching the value form *text-colors* is less
error-prone.

The other example of a popup text window is the window that pops onto
screen when the "report Free space" menu item is selected from either
the horizontal menu example or the vertical menu example.  In this
case, the text is dynamic because free space must be determined anew
each time the user selects "report Free space".  Consequently, the
freesp-rpt popup text window is created with a dummy text argument
consisting of only one space.  The actual text is generated by the
do-freesp procedure and passed to the freesp-rpt window as the text
argument of a set-text message.


MAKE-POPUP-QUERY-WINDOW

To create a popup query window, an application program evaluates an
expression of the form:

     (make-popup-query-window <init-list> <text>)

where <init-list> is a list of quoted symbols alternating with
initial values:

     ('w-top <integer>
      'w-left <integer>
      'cursor-row <integer>
      'cursor-col <integer>
      'input-width <integer>
      'n-attr <integer>
      'hl-attr <integer>
      'border? <boolean>)

The entries in <init-list> are:

'w-top <integer>

                The row position of the window on the screen.

'w-left <integer>

                The column position of the window on the screen.

'cursor-row <integer>

                The row of the popup query window in which the input
                field will appear and on which the cursor will be
                placed when the query window pops onto the screen.
                Note: the input field is appended to the string which
                the <text> argument  assigns to the cursor-row.

'cursor-col <integer>

                The column of the popup query window at which the
                cursor will be placed when the query window pops onto
                the screen.  Normally this should be the first column
                of the input field.

'input-width <integer>

                The number of spaces allocated to the input field
                receiving the user's response to the query.

'n-attr <integer>

                The query normal attributes; the text attributes for
                the area outside the input field.  See WINDOW-SET-
                ATTRIBUTE in the TI Scheme Language Reference Manual
                for further information.

'hl-attr <integer>

                The query highlight attributes; the text attributes
                of the window for the area inside the input field.

'border? <boolean>

                If <boolean> evaluates to #t the window will have a
                border; if it evaluates to #f, it won't.

The <text> argument is a vector of strings as described above for
make-popup-text-window.



POPUP QUERY WINDOW EXAMPLE

MENEX.S contains a single example of a popup query window.  This is
the window that pops onto screen when the "Do a DOS command" menu
item is selected from either of the menus of the menu example.  It
uses the global variable *query-data* to hold its <init-list> and the
global variable *query-text* to hold its <text> vector.  In this
case, the input field appears on the second line of the window.
Since no prompting text is wanted on the line with the input field,
an empty string is used as a place holder in the <text> vector.

As in examples discussed above, the *text-color* environment is
accessed to get text attributes.  The query window text appears as
white against a blue background, and the input field text appears as
black against a white background.  These color choices give good
contrast on most color monitors.


MAKE-VERTICAL-MENU

To create a vertical menu, an application program evaluates an
expression of the form:

     (make-vertical-menu <init-list> <item-list>)

where <init-list> is a list of quoted symbols alternating with
initial values:

     ('w-top <integer>
      'w-left <integer>
      'n-attr <integer>
      'hl-attr <integer>
      'border? <boolean>)

The entries in <init-list> are:

'w-top <integer>

                The row position of the window on the screen.

'w-left <integer>

                The column position of the window on the screen.

'n-attr <integer>

                The menu normal attributes; the text attributes of
                the menu for the area outside the bar cursor.  See
                WINDOW-SET-ATTRIBUTE in the TI Scheme Language
                Reference Manual for further information.

'hl-attr <integer>

                The menu highlight attributes; the text attributes of
                the menu for the area inside the bar cursor.

'border? <boolean>

                If <boolean> evaluates to #t the window will have a
                border; if it evaluates to #f, it won't.

and <item-list> is

     ((label selector action) ... )

or when multiple selector keys are to be assigned

     ((label (selector ... ) action) ... )

where

action

                The action taken when this item is selected, a
                function with no arguments.

selector

                A character.  The user may type this character as one
                way to select this menu item.

label

                A text string describing the menu item; by
                convention, the first uppercase letter in the string
                should be the uppercase form of the selector.

The <item-list> argument can be viewed as a table with one line per
menu item and three entries per line.  The table as a whole is a list
and each line is a list; i.e., an <item-list> is a list of lists.


MAKE-HORIZONTAL-MENU

To create a horizontal menu, an application program evaluates an
expression of the form:

     (make-horizontal-menu <init-list> <item-list>)

and <init-list> is and <item-list> are as described above for the
constructor make-vertical-window, except that <init-list> has the
additional pair of entries:

'label-spacing <integer>

                The number of spaces to insert between labels.


MENU EXAMPLES

In MENEX.S, both the horizontal menu and vertical menu use the <item-
list> held in the global variable *item-list*.  This gives both menus
the same five menu items.  On the other hand, the vertical menu is
passed the <init-list> held in the global variable *vertical-menu-
data*, while the horizontal menu is passed the <init-list> held in
the global variable *horizontal-menu-data*.  In this case, the two
<init-list>s differ only by the addition of the pair: 'label-spacing
2, but this is not the usual case.

Again the *text-color* environment is accessed to get text attributes
for the <init-list>s.  On a color monitor, normal menu text appears
as white against a blue background, and the text under the bar cursor
appears as white against a red background.

Also note how the <item-list> assigned to the global variable *item-
list* is specified by quasi-quoting the outer list and splicing in
the actions in the inner lists with commas.  An alternative and
completely equivalent way of specifying *item-list* is:

     (define *item-list*
       (list ("Do a DOS Command" #\d do-dos)
               ...
             ( ... do-exit)))


COMMON PROTOCOLS

Applications request services from Menus for Scheme by sending
messages to instances of the constituent classes.  Message names need
not be unique.  Indeed, more often than not they are shared between
two or more classes.

In Menus for Scheme, restrictions have been placed on messages
sharing names with other messages: any two messages with the same
name also take the same arguments and, in the case where the returned
value is of importance, the returned value is of same type.  When two
classes share message names under this more restrictive convention,
they are said to share a common protocol.  Common protocols make life
easier for the applications programmer by reducing the amount of
detail that must be mastered to use Menus for Scheme.

Consequently, wherever possible, common protocols have been used in
Menus for Scheme. Adherence to this design goal has produced the
benefit that most of the messages used by applications are understood
by all four classes.


MESSAGES UNDERSTOOD BY ALL FOUR CLASSES

(send <instance> get-w-top)

                Returns the screen row-coordinate of the top row of a
                popup window or menu (an integer).

(send <instance> get-w-left)

                Returns the screen column-coordinate of the left-most
                column of a popup window or menu (an integer).

(send <instance> get-w-rows)

                Returns the vertical size (number of rows) of a popup
                window or menu (an integer).

(send <instance> get-w-cols)

                Returns the horizontal size (number of columns) of a
                popup window or menu (an integer).

(send <instance> get-border?)

                Returns #t if the window has a border; returns #f
                otherwise.

(send <instance> set-w-top <integer>)

                Takes an integer and makes it the position of the top
                row of a popup window or menu.  Used for effect; it
                returns nothing useful.

(send <instance> set-w-left <integer>)

                Takes an integer and makes it the position of the
                left-most column of a popup window or menu.  Used for
                effect; it returns nothing useful.

(send <instance> popup)

                This is the releasing message.  Sending this message
                causes the window or menu receiving it to pop onto
                the screen.  Used for effect; it returns nothing
                useful.



MESSAGE UNDERSTOOD BY BOTH OF THE POPUP WINDOW CLASSES

(send <instance> set-text <text>)

                Assigns a new text vector to the popup text or query
                window.  The argument <text> is a vector of the form

                     #(<string1> <string2> ... )

                Each string appears on a separate line when the
                window pops onto the screen.  The size of window is
                automatically adjusted to contain the new text.  Used
                for effect; it returns nothing useful.


MESSAGE UNDERSTOOD BY CLASS POPUP QUERY WINDOW

(send <instance> get-response)

                Returns the string typed-in by the user in response
                to the query made by the window.


MESSAGE UNDERSTOOD BY BOTH OF THE MENU CLASSES

(send <instance> set-item-index <integer>)

                Assigns <integer> to the menu instance variable item-
                index.  Item-index determines which item description
                is highlighted by the bar cursor when the menu is
                released.  This message can be used to pre-select a
                menu item other than the first one.  The argument,
                <integer>, is reduced modulo the number of items in
                the menu, so a valid menu item will always be pre-
                selected.


MESSAGE EXAMPLES

The procedures h-justify and v-justify found in file MENUS.S are
good examples of how to use of the get-w-rows, get-w-cols, get-
border?, set-w-top, and set-w-left messages to position a popup
window or menu.  The do-dos procedure in MENEX.S shows how to use of
the get-response message, which an application must send to get the
response the user makes to a popup query window, and the do-freesp
procedure shows how to use the set-text message to change the
contents of a popup text window.  The do-v procedure shows how the
set-item message is used to pre-select a menu item other than the
first.

And, of course, there are many examples of the popup message since
this is the one message that must always be sent by an application
using Menus for Scheme.


BUGS

The following are the known bugs of Menus for Scheme:

  1.  Nothing prevents the user from typing in a string too large for
      the input field of a popup query window.

  2.  No check is made that the instances of popup windows and menus
      created by Menus for Scheme actually fit on the screen.


APPENDIX -- GLOSSARY OF SCOOPS TERMS

This appendix may be of help to you if you decide to modify MENUS.S.

ACTIVE VALUE.  A instance variable has an active value if its SET-
METHOD (q.v.) calls a procedure rather than performing its normal
function of assigning a new value to the instance variable.  The
procedure gets passed the argument of the SET-METHOD, and whatever is
returned by the procedure is assigned to the instance variable.
Similarly, an instance variable also has an active value if its GET-
METHOD (q.v.) calls a procedure rather than merely retrieving the
current value of the instance variable.  In this case, the procedure
is passed the current value, and the GET-METHOD returns whatever the
procedure returns.  An instance variable that is both GETTABLE and
SETTABLE can be doubly active.  Active values can transform the
relatively tame operations of getting or setting into monsters with
really hairy side-effects.

CLASS.  A collection of private variables (class variables and
instance variables) and procedures (methods) that together function
as an abstract data type.  The methods comprise the set of operations
applicable to any object belonging to the class.  The private
variables are visible to the methods, but not elsewhere, while the
methods are generally visible.  The class concept in object-oriented
languages has much in common to the package concept found  Modula-2
or Ada.  However, in object-oriented languages, not only may
programmers define their own classes, they may also add their own
methods to any existing class.  Further, when a class is defined, it
may incorporate the private variables and methods of an existing
class, in which case the new class is said to inherit from the
existing class.  SCOOPS provides a defining form, DEFINE-CLASS, for
the creation of new classes, and a debugging tool, DESCRIBE, to
permit examination of a class or an instance of a class.  Unlike
Smalltalk-80, it does not provide any pre-defined classes for
programmers to build on.

CLASS VARIABLE.  A variable that is private to a class, but shared by
all the instances of the class.  In SCOOPS, class variables must be
declared as members of the CLASSVARS list of a class definition.
Class variables may have options declared for them.  See the glossary
entry "instance variable" for a discussion of options.

COMPONENT CLASS.  A class defined to serve as a prefabricated
subassembly from which other, more elaborate classes can be built.
Contrast this with the glossary entry "instantiable class."
Sometimes a class can be both a component class and an instantiable
class.

GET-METHOD.  A method automatically generated by SCOOPS for an
instance variable in response to a GETTABLE declaration in the
options list of its class definition.  A GET-METHOD returns the value
of its instance variable.  For example, if JOHN is an instance of
some class which has the GETTABLE instance variable NAME and the copy
of NAME belonging to JOHN has the string "John Q. Public" as its
value, the message

     (SEND JOHN GET-NAME)

returns "John Q. Public".

INHERITANCE.  When a class inherits from a mixin (q.v.), it absorbs
all the class variables, instance variables, and methods of the mixin
as if they were defined in the inheriting class itself.  Permitting
multiple mixins adds a complication to SCOOPS which doesn't come up
in object-oriented languages permitting only a single mixin (e.g.,
Smalltalk-80).  In SCOOPS, it is possible for two or more mixins to
define methods or variables with conflicting names.  Even worse,
mixins can have mixins, and some of these could also define methods
or variables with conflicting names.  SCOOPS resolves such conflicts
by giving priority to the first object (method or variable) it sees
as it makes a depth-first search up through the class inheritance
network.  Any other objects with the same name are shadowed.

INSTANCE.  Conceptually an instance is a data object which derives
its type from its class.  The class imposes a structure and a set of
operations on it.  In SCOOPS, instances are represented by
environments and are created by calling the special form MAKE-
INSTANCE with a class name and (optional) initial values for the
inittable instance variables.

INSTANCE VARIABLE.  A variable that is private to instance of class.
An instance variable may have options declared for it.  In SCOOPS,
instance variables must be declared as members of the INSTVARS list
of a class definition, and may have any of the options GETTABLE,
SETTABLE, or INITTABLE (spelled thus in SCOOPS; other object-oriented
programming system spell it INITABLE).  If an instance variable is
declared GETTABLE, it becomes accessible to an application by means
of a GET-METHOD (q.v.), which is automatically generated by SCOOPS.
Similarly, if it is SETTABLE, it is modifiable by means of a SET-
METHOD (q.v.), and if it is INITTABLE, it may be initialized by an
application by means of SCOOPS-provided initialization code.

INSTANTIABLE CLASS.  A class from which useful instances can be
constructed are said to be instantiable.  Contrast this with the
glossary entry "component class."

MESSAGE.  A special kind of procedure call.  It passes an instance
and possibly other arguments to a method.  In SCOOPS, messages are
special forms distinguished by the initial keyword SEND.  Examples of
messages can be found under the glossary entries "GET-METHOD" and
"SET-METHOD."

METHOD.  An operation that an application may perform on an instance
of a class.  Methods are represented in SCOOPS by procedures.  A
defining form, DEFINE-METHOD, is provided.

MIXIN.  When a class is used as a component of another class, the
first class is said to be a mixin of the second.  See the glossary
entry "inheritance" for more information.

SET-METHOD.  A method automatically generated by SCOOPS for an
instance variable in response to a SETTABLE declaration in the
options list of its class definition.  A SET-METHOD assigns its
argument to its instance variable.  For example, if JOHN is an
instance of some class which has the SETTABLE instance variable NAME,
then the message

     (SEND JOHN SET-NAME "John Q. Public")

assigns the string "John Q. Public" to the copy of NAME belonging to
JOHN.  SET-METHODs are used for effect, nothing useful is returned.