reduce-historical/psl-1983/windows/vscreen.t

          SPECIFICATION OF THE VIRTUAL-SCREEN DATATYPE
                           Cris Perdue
                             10/1/82
                       File: pw:vscreen.t


VIRTUAL-SCREEN		Flavor

A virtual screen is an object that can be used as independent
rectangular character display, but in fact shares a physical
screen with other objects.  The coordinate system is based at
(0,0) with the origin at the upper left-hand corner of the
screen.  A virtual-screen has an associated virtual cursor
position.  Each character on a virtual screen has a specific
associated display enhancement, such as inverse video or
underlining.

A virtual screen object maintains a stored representation of the
image on the virtual screen, which is used to update the physical
screen when new areas of the virtual screen become "exposed".  A
virtual screen does not itself maintain any information about
changes to its contents.  It informs the physical screen of all
changes as they are made, and sends the entire screen contents to
the physical screen upon its request.

In contrast with LISP Machine "windows" (the equivalent of these
virtual-screens), a program may write onto a virtual screen at
any time.  Whether the virtual screen is exposed, covered, or
partially covered by virtual screens makes no difference.  In all
cases any change to a virtual screen that shows is permitted and
sent to the shared-physical-screen as soon as it is made.  The
change is visible to the user as soon as a refresh operation is
done.

The following initialization options exist:

screen (required)

The shared-physical-screen on which this screen may become
exposed.

height, width (optional)

The height and width of this screen, in characters.  These
default to the height and width of the shared-physical-screen of
this screen.

row-origin, column-origin (optional)

Offset of the upper left-hand corner (origin) of this screen from
the upper left-hand corner of the associated
shared-physical-screen.  These may be negative. (?)

default-enhancement (optional)

Display enhancement(s) to be applied to characters written into
this screen by the "write" method.  Display enhancements include
inverse video and underlining.  Defaults to the value of the
normal-enhancement of the associated shared-physical-screen.
Enhancement values may be legally generated by the function
dc-make-enhancement, not documented here.  (Defined in the file
pw:display-char.sl.)  Note: Characters written to this screen by
write-display-character do not have the default enhancement
applied.

Note on clipping:

All operations that modify the contents of the virtual screen
effectively clip.  If any or all of the coordinates to be
modified lie outside the screen, any part of the operation
applying to those coordinates is ignored and no warning is given.
Attempts to move the cursor off the virtual screen just move it
to the nearest border point.

(CREATE-VIRTUAL-SCREEN SHARED-PHYSICAL-SCREEN)

Creates a virtual-screen associated with the specified
shared-physical-screen.  All the rest of the virtual-screen's
attributes are defaulted.

(=> VIRTUAL-SCREEN SET-CURSOR-POSITION ROW COLUMN)

Sets the virtual-screen's (virtual) cursor position.  It is
intended that virtual screens will be shown on actual screens
that have at least one actual cursor.  At certain times there
will be an actual cursor displayed at the position of the
virtual-screen's cursor.

If the position is out of range, the nearest in-range values will
be used instead without complaint.

(=> VIRTUAL-SCREEN WRITE CH ROW COLUMN)

Write a single character, represented as an integer, at the given
coordinates.  The character is written with the virtual-screen's
default enhancements.

(=> VIRTUAL-SCREEN WRITE-RANGE CH ROW LEFT-COLUMN RIGHT-COLUMN)

Writes the same character to a range of positions within a line
of the virtual-screen.  The left-column and right-column
coordinates are inclusive.  The default-enhancements are used.

(=> VIRTUAL-SCREEN WRITE-DISPLAY-CHARACTER DC ROW COLUMN)

A single character is written to the virtual-screen with explicit
enhancements.  The DC argument is a character-with-enhancements
object, not documented here.

(=> VIRTUAL-SCREEN CLEAR)

The entire contents of the virtual-screen is set to blanks with
the default enhancement.  All clearing operations set the cleared
portion of the screen to blanks with the default enhancement.

(=> VIRTUAL-SCREEN CLEAR-TO-END FIRST-ROW)

Clears the entire contents of the rows from first-row to the end
of the screen.

(=> VIRTUAL-SCREEN CLEAR-TO-EOL ROW FIRST-COLUMN)

Clears the given row from first-column to the end.

(=> VIRTUAL-SCREEN EXPOSE)

Causes the select-primary-owner method to be invoked on the
shared-physical-screen of the virtual screen.  The effect of this
should be to guarantee that the virtual screen is exposed in
front of all other virtual screens associated with the same
shared-physical-screen (until this operation is invoked on some
other virtual-screen).  Also guarantees that the actual screen's
cursor is displayed at the position of this virtual-screen's
cursor.

(=> VIRTUAL-SCREEN DEEXPOSE)

Causes the remove-owner method to be invoked on the
shared-physical-screen of this virtual screen.  The effect should
be to entirely remove this virtual screen from display on the
shared-physical-screen.

SEMI-PRIVATE METHODS

These methods are invoked by the shared-physical-screen.  They
are not intended for public use.  Shared-physical-screens require
their "owner" objects to supply these methods.

(=> VIRTUAL-SCREEN SEND-CHANGES BREAKOUT-ALLOWED)

An "owner" object is permitted to delay sending changes to the
shared-physical-screen.  When the shared-physical-screen is to be
brought up to date, it invokes this operation on its owners,
which must write onto the shared-physical-screen to bring it up
to date.  Virtual-screens do not buffer or delay any updating, so
this operation is a no-op.

(=> VIRTUAL-SCREEN SEND-CONTENTS BREAKOUT-ALLOWED)

This method is invoked by the shared-physical-screen to force an
owner to write its entire contents out to the
shared-physical-screen.

(=> VIRTUAL-SCREEN ASSERT-OWNERSHIP)

This method is invoked by the shared-physical-screen with the
expectation that it in turn will invoke the
shared-physical-screen's set-owner-region operation with
parameters specifying what area is to be occupied by the owner.

(=> VIRTUAL-SCREEN SCREEN-CURSOR-POSITION)

This method is expected to return the coordinates of the
virtual-screen's cursor, in the coordinate system of the
shared-physical-screen.