Digital PDFs

AA-GH76A-TE

May 1986

248 pages

Original

14MB

Document:	VAX LISP/VMS Graphics Programming Guide
Order Number:	AA-GH76A-TE
Revision:	000
Pages:	248
Original Filename:

OCR Text

VAX LISP/VMS
Graphics Programming Guide
Order Number: AA-GH76A-TE

0
May 1986
This document contains Information required by a LISP language
programmer to write programs that use the VAX LISP interface to
VAXstation graphics.

0
Operating System and Version:

VAXNMS Version 4.2

Software Version:

VAX LISPNMS Version 2.0

digital equipment corporation
maynard, massachusetts

First Printing

May 1986

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment
Corporation. Digital Equipment Corporation assumes no responsibility
for any errors that may appear in this documP.nt.

The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for t~e use or reliability of software on
equipment that is not supplied by Digital Equipment Corporation or its
affiliated companies.
©

Digital Equipment Corporation 1986.
All Rights Reserved.
Printed in U.S.A.

A postage-paid READER'S COMMENTS form is included on the last page of
this document.
Your comments will assist us in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:

0
DEC
DECOS
MicroVAX
VAXstation
DECnet
ULTRIX-32
ULTRIX-32m

UNIBUS
VAX
MicroVAX II
VAXstation II
ULTRIX

PDP
VMS
MicroVMS
AI VAXstation
ULTRIX-11

CONTENTS

O PREFACE
PART I
CHAPTER 1.
1.1
1.1.1

1.1.2
1.2
1.2.1
1.2.2
1.2.3
1.2.4
1.3
1.3.1
1.3.2
1.3.3

1.3.4
1.4
1.5
1.6
CHAPTER 2

GUIDE TO GRAPHICS PROGRAMMING

SYSTEM OVERVIEW
INTRODUCTION
Relationship to MicroVMS Workstation Graphics
Software
Programming Considerations
VIRTUAL DISPLAYS AND WINDOWS
Creating a Virtual Display
Creating Windows
Windows and Viewports
Other Operations
GRAPHICS OPERATIONS
Drawing Lines and Circles
Writing Text
Using Attributes
Other Operations
POINTER OPERATIONS
KEYBOARD INPUT FROM WINDOWS
WINDOW OUTPUT STREAMS

1-1
1-2
1-2
1-3
1-3

1-4
1-5
1-9
1-9
1-10
1-11
1-13
1-15
1-15
1-16
1-16

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

2.1
HOW AND WHEN GRAPHIC INFORMATION IS DISPLAYED
2.2
COORDINATE SYSTEMS
2.2.1
World Coordinates
2.2.2
Device Coordinates
2.2.3
Screen Coordinates
2.3
CREATING AND MAINTAINING VIRTUAL DISPLAYS
2.3.1
Creating and Accessing a Virtual Display
2.3.2
Deleting a Virtual Display
2.3.3
Arguments to CREATE-DISPLAY
2.4
CREATING AND MANIPULATING WINDOWS AND VIEWPORTS
2.4.1
Creating and Accessing Windows
2.4.1.1
Controlling Window Coordinates
2.4.1.2
Controlling Viewport Characteristics
2.4.2
Deleting Windows
2.4.3
Moving and Resizing Windows
2.4.4
Moving Viewports
2.4.5
Determining and Controlling Viewport Occlusion
2.4.6
Handling User Actions
2.4.6.1
Responding to Viewport Movement
2.4.6.2
Respondin~ to Viewport Resizing
2.4.6.3
Responding to Viewport Deletion
2.5
TRANSFORMATIONS INTO VIRTUAL DISPLAYS

iii

2-1
2-2
2-4
2-5
2-8
2-8
2-8
2-9
2-9
2-10
2-10
2-11
2-12
2-14
2-14
2-16
2-16
2-17
2-17
2-18
2-20
2-21

2.5.1
2.5.2
CHAPTER 3

Creating and Accessing Transformations
Deleting a Transformation

2-21
2-22

GRAPHICS OUTPUT OPERATIONS

3.1
THE DISPLAY LIST
3-1
3.2
WORLD-COORDINATE AND DEVICE-COORDINATE OPERATIONS 3-3
ATTRIBUTES AND ATTRIBUTE BLOCKS
3.3
3-5
3.3.1
Modifying and Using Attribute Blocks
3-6
3.3.2
Attributes
3-8
3.3.2.1
:BACKGROUND-INDEX
3-8
3.3.2.2
:CLIP
3-10
:CLIP-PIXEL
3.3.2.3
3-11
3.3.2.4
3-11
:WRITING-INDEX
:WRITING-MODE
3.3.2.5
3-11
3.4
COLOR
3-13
DRAWING LINES AND SHAPES
3.5
3-16
3.5.1
Points and Lines
3-17
3.5.2
Circles, Ellipses, and Arcs
3-19
3.5.3
Attributes Used with Line-Drawing Functions
3-20
3.5.3.1
:ARC-TYPE
3-20
:FILL-PATTERN
3.5.3.2
3-21
:LINE-STYLE
3.5.3.3
3-22
:LINE-WIDTH
3.5.3.4
3-23
TEXT OPERATIONS
3.6
3-23
3.6.1
Writing Text
3-23
3.6.2
Positioning and Measuring Text
3-26
'3-26
3.6.2.1
The Text Position and Text Reference Points
Changing the Text Position
3.6.2.2
3-27
Measuring Text
3.6.2.3
3-29
Attributes that Affect Text
3.6.3
3-30
3.6.3.1
:CHARACTER-SPACING
3-30
3.6.3.2
:FONT
3-30
3.6.3.3
:LEFT-MARGIN
3-31
:LEFT-MARGIN-PIXEL
3.6.3.4
3-32
3.7
SEGMENTS
3-32
3.8
MOVING AND ERASING GRAPHIC INFORMATION
3-33
CHAPTER 4
4.1
4.2
4.3
4.4
4.5
4.6

SCREEN IMAGES AND BITMAPS
SCREEN IMAGES AND BITMAP ARRAYS
CREATING A BITMAP ARRAY FROM A SCREEN IMAGE
WRITING A BITMAP ARRAY TO THE SCREEN
STORING BITMAP ARRAYS IN FILES
CREATING, COMPARING, AND TESTING BITMAP ARRAYS
ALTERING BITMAPS

4-1
4-2
4-3
4-5
4-6
4-6

0
iv

5
O CHAPTER 5.1
5.1.1
5.1.2
5.1.3
5.2
CHAPTER 6
6.1
6.1.1
6.1.2
6.1.3

6.1.4
6.2
6.2.1
6.2.2
6.2.3
CHAPTER 7

7.1
7.2
7.2.1
7.2.2
7.2.3
7.3
7.3.1
7.3.2
7.3.3

POINTE~ OPERATIONS
POINTER-RELATED FUNCTIONS
Obtaining and Setting Pointer Position
Movement Input
Button Input
POINTER SENSITIVITY

5-1
5-2
5-4
5-9
5-15

KEYBOARD INPUT
VIRTUAL KEYBOARDS
Using Virtual Keyboards: An Overview
Creating and Deleting Virtual Keyboards
Associating Keyboards with Viewports and the
Physical Keyboard
Setting Keyboard Attributes
CAPTURING AND INTERPRETING KEYSTROKES
Keyboard Interrupt Functions
Reading Keyboard Input Synchronously
Characters Generated by Keys

6-1
6-2
6-4
6-4
6-5
6-6
6-6
6-6
6-7

WINDOW OUTPUT STREAMS
CREATING AND USING WINDOW OUTPUT STREAMS
7-1
ALTERING WINDOW OUTPUT STREAMS
7-3
Changing the Viewing Area
7-3
Changing Overflow Behavior
7-4
Changing the Attribute Block
7-4
WINDOW OUTPUT STREAMS AND OTHER GRAPHICS FUNCTIONS 7-5
Window Text Position
7-5
Vertical Scrolling and Erasing
7-5
Display List
7-6
PART II

GRAPHICS SYSTEM COMPONENTS

BEGIN-SEGMENT Function
BITBLT Function
BITBLT Type Specifier
BITBLT Accessor Functions
BITBLT Accessor Functions
BITBLT-P Function
BITMAP-P Function
CIRCLE Function
CIRCLE-PIXEL Function
COMPARE-BITMAPS Function
COPY-BITBLT Function
CREATE-DISPLAY Function
CREATE-KB Function
CREATE-TERMINAL Function
v

1
1

2
2
2
3
3
4

5
6
7
7

8
8

CREATE-TRANSFORMATION Function
CREATE-UIS-STRUCTURE Function
CREATE-WINDOW Function
DELETE-DISPLAY Function
DELETE-KB Function
DELETE-TRANSFORMATION Function
DELETE-WINDOW Function
DISABLE-DISPLAY-LIST Function
DISABLE-KB Function
DISABLE-VIEWPORT-KB Function
DISPLAY Type Specifier
DISPLAYP Function
DISPLAY-WINDOWS Funct~on
DUMP-BITMAP Function
ELLIPSE Function
ELLIPSE-PIXEL Function
ENABLE-DISPLAY-LIST Function
ENABLE-KB Function
ENABLE-VIEWPORT-KB Function
END-SEGMENT Function
ERASE Function
ERASE-PIXEL Function
ERASE-VIEWING-AREA Function
GET-ABS-POINTER-POSITION Function
GET-ALIGNED-POSITION Function
GET-ALIGNED-POSITION-PIXEL Function
GET-ATTRIBUTE Function
GET-ATTRIBUTE-LIST Function
GET-BUTTONS Function
GET-COLOR Function
GET-DISPLAY-SIZE Function
GET-FONT-SIZE Function
GET-INTENSITY Function
GET-KB-ATTRIBUTE Function
GET-KB-ATTRIBUTE-LIST Function
GET-POINTER-POSITION Function
GET-POINTER-POSITION-PIXEL Function
GET-POSITION Function
GET-POSITION-PIXEL Function
GET-VIEWPORT-POSITION Function
GET-VIEWPORT-SIZE Function
GET-VISIBILITY Function
GET-VISIBILITY-PIXEL Function
GET-WINDOW-ATTRIBUTE-LIST Function
GET-WS-COLOR Function
GET-WS-INTENSITY Function
IMAGE Function
IMAGE-PIXEL Function
KEYBOARD Type Specifier
KEYBOARDP Function
K-TRM-xxx Constants
LIST-ALL-DISPLAYS Function

10
11
12
15
15
16
16
17
17
18
18
18
19
19

20
21
22
23
23

24
24
25
26
26
27
28
28

0
0

31
32
32
33

34
35
35
36
37
37

38
38
39

40
41
41
42
43

44
45
46
46
46
48

0
0

LIST-ALL-WINDOWS Function
LOAD-BITMAP Function
MAKE-BITBLT Function
MAKE-BITMAP Function
MAKE-WINDOW-OUTPUT-STREAM Function
MEASURE-TEXT Function
MEASURE-TEXT-PIXEL Function
MOVE-ARgA Function
MOVE-AREA-PIXEL Function
MOVE-VIEWPORT Function
MOVE-WINDOW Function
NEW-TEXT-LINE Function
NEW-TEXT-LINE-PIXEL Function
PLOT Function
PLOT-ARRAY Function
PLOT-ARRAY-PIXEL Function
PLOT-PIXEL Function
POINTER-BUTTON-n Constants
POP-VIEWPORT Function
PUSH-VIEWPORT Function
READ-IMAGE-PIXEL Function
READ-KB-CHAR Function
RESIZE-WINDOW Function
SET-ALIGNED-POSITION Function
SET-ALIGNED-POSITION-PIXEL Function
SET-ATTRIBUTE Function
SET-BUTTON-ACTION Function
SET-BUTTON-ACTION-PIXEL Function
SET-CLOSE-ACTION Function
SET-COLOR Function
SET-GAIN-KB-ACTION Function
SET-INTENSITY Function
SET-KB-ACTION Function
SET-KB-ATTRIBUTES Function
SET-KB-COMPOSE2 Function
SET-KB-COMPOSE3 Function
SET-KB-KEYTABLE Function
SET-LOSE-KB-ACTION Function
SET-MOVE-INFO-ACTION Function
SET-POINTER-ACTION Function
SET-POINTER-ACTION-PIXEL Function
SET-POINTER-PATTERN Function
SET-POINTER-PATTERN-PIXEL Function
SET-POINTER-POSITION Function
SET-POINTER-POSITION-PIXEL Function
SET-POSITION Function
SET-POSITION-PIXEL Function
SET-RESIZE-ACTION Function
SHOW-FILL-PATTERNS Function
SHOW-FONTS Function
SOUND-BELL Function
SOUND-CLICK Function
vii

48
48
49
53

54
55
56
56
57
58
59
60
60
61
62
63
64

65
65
66
66
67
68
69
70
71
73
74
76
77
78
78
79
80
82
83
83
84
85
86
87
88
89
90
91
92
92
93
95
95

96
97

TEST-KB Function
TEXT Function
TEXT-PIXEL Function
TRANSFORMATION Type Specifier
TRANSFORMATIONP Function
UIS-ID Function
WINDOW-DISPLAY Function
WINDOW Type Specifier
WINDOWP Function
WINDOW-STREAM-ATTRIBUTE-BLOCK Function
WINDOW-STREAM-HORIZONTAL-OVERFLOW Function
WINDOW-STREAM-VERTICAL-OVERFLOW Function
WINDOW-STREAM-VIEWING-AREA Function
WINDOW-STREAM-WINDOW Function
WINDOW-STREAM-X-POSITION Function
WINDOW-STREAM-Y-POSITION Function
WITH-OUTPUT-TO-WINDOW Macro

97
98
98
99
99
100
100
101
101
101
102
102
103
104
104
105
105

The Immovable Viewport
Boxed Text
Reversing Text Using Segments
Rubber-Banding with GET-POINTER-POSITION
Rubber-Banding with SET-POINTER-ACTION
Setting the Cursor Pattern
Controlling Rubber-Banding with Pointer Buttons
Using Structures to Eliminate Special Variables
A Simple Menu System
Resizing the Viewing Area Automatically

2-18
3-29
3-33
5-3
5-6
5-9
5-11
5-13
5-16
7-3

INDEX
EXAMPLES

2-1
3-1
3-2
5-1
5-2
5-3
5-4
5-5
5-6
7-1

FIGURES

1-1
1-2
2-1
2-2
2-3
2-4
2-5
2-6
2-7
2-8
2-9
2-10
3-1
3-2

Virtual Displays, Windows, and Viewports
Drawing a Circle
Displaying Information on the Screen
Example of a World Coordinate System
Making an Image from Pixels
The Device Coordinate System
Square and Nonsquare Pixels
Arguments to the CREATE-DISPLAY Function
Specifying Window Coordinates with CREATE-WINDOW
Viewport Components
Moving a Window
Transformations
Modifying an Attribute Block
Clipping
viii

1-7
1-12
2-3
2-4
2-5
2-6
2-7
2-10
2-12
2-13
2-15
2-21.
3-7
3-10

6-1

Writing Modes
Writing Through the Color Map
Filling Plotted Shapes
Drawing Arcs
Line Styles
Text and Scaling
Text Reference Points
Using Different Fonts on the Same Line
Setting the Aligned Position
Bitmaps and Screen Images
Writing Bitmap Arrays with IMAGE
Specifyi~g Overlapping Areas for
SET-POINTER-ACTION
Creating and Attaching Virtual Keyboards

3-1
3-2
6-1

Attributes
Writing Modes
LISP Constants Corresponding to LK201 Keys

3-3
3-4
3-5
3-6
3-7
3-8
3-9

3-10
3-11
4-1
4-2
5-1

3-14
3-15
3-19

3-20
3-22
3-25
3-26
3-27
3-28
4-2
4-4

5-8
6-3

O TABLES

0
ix

3-9
3-13
6-7

0
x

0
PREFACE

Manual Objectives

The VAX LISP/VMS Graphics Programming Guide describes the VAX LISP/VMS
graphics system.
This graphics system provides an interface to, and
is intended for use on, the VAXstation family of workstations.
Intended Audience

This manual is designed for programmers who are already familiar with
VAX LISP and who need to use VAX LISP'S programming interface to
VAXstation graphics. You should also be familiar with the user
interface to the VAXstation, as described in the MicroVMS Workstation
User's Guide.
Some sections of this manual require detailed understanding of the
operating system or of VAX LISP'S interaction with it. In such
sections, you are directed to the appropriate manual(s) for additional
information.

Q Structure of This Document
An outline of the organization and
follows:
PART I:

chapter

content

this

manual

GtJIDB 'rO GRAPHICS PROGRAMMIRG

Part I presents the VAX LISP graphics system in tutorial fashion, by
subject area.
You may want to read through these chapters once,
initially, and then refer to them afterward as necessary.

•

Chapter 1, "Overview," introduces the graphics
provides a demonstration of its capabilities.

•

Chapter 2, "Virtual Displays, Windows, and Transformations,"
explains the mechanisms by which graphic information is stored
and displayed on the screen.

system

and

PREFACE

•

Chapter 3, "Graphic Output Operations," describes the various
operations that display lines and text, as well as ways of
changing the appearance of the output.

•

Chapter 4, "Screen Images and Bitmaps," shows how you can read
images from the screen into an array, modify the array, and
write it back to the screen.

•

Chapter 5, "Pointer Operations," explains how to use
pointing device (mouse or tablet) as an input device.

•

Chapter 6, "Keyboard Input," describes virtual keyboards,
through which keystrokes from the physical keyboard can be
captured by a window.

•

Chapter 7, "Window Output Streams," shows how you can
text output to a window through a VAX LISP stream.

PART II:

the

perform

GRAPHICS SYSTEM COMPONENTS

Part 11 contains definitions of the functions, macros, and data types
specific to the VAX LISP graphics system. The descriptions are in
alphabetical order.
Each description explains the function's or
macro's use and shows its format, applicable arguments, and return
value.

Associated Documents

The following documents are relevant to using VAX LISP graphics:
The VAX LISP/VMS User's Guide provides general information
• about
using
VAX
LISP,
and
serves
as a guide to

0
• COMMON LISP: The Language provides a definition of the
generally-helpful VMS documentation.

COMMON LISP language.
,e

The VAX LISP/VMS System Access Programming Guide describes
how a VAX LISP programmer can use the programming interface
to the VMS operating system. The chapter entitled "Interrupt
Functions" is especially important for users of VAX LISP
graphics.

•

The VAX LISP/VMS Editor Programming Guide explains how to
extend the capabilities of the VAX LISP Editor and includes
information on workstation-specific Editor functionality.

0
xii

PREFACE

Q Conventions Used in Thi.s Document
The following conventions are used in this manual:
Convention

Meaning

(

Parentheses used in examples of LISP code indicate
beginning and end of a LISP form. For example:

)

the

(SETQ NAME LISP)
UPPERCASE

0 lowercase
italics

DCL
commands
and
qualifiers, and
defined LISP
functions, macros, variables, and constants are printed
in uppercase characters; however, you can enter them in
uppercase, lowercase, or a combination of uppercase and
lowercase characters.
Lowercase italics in function and macro descriptions
and in text indicate arguments that you
supply;
however, you can enter them in lowercase, uppercase, or
a combination of lowercase and uppercase characters.
In LISP examples, a horizontal ellipsis indicates
not pertinent to the example and not shown.

o·
{ }

0 { }*

code

A vertical ellipsis indicates that all the information
that the system would display in response to the
particular function call is not shown; or, that all the
information a user is to enter is not shown.
In function and macro format specifications, braces
enclose elements that are considered to be one unit of
code. For example:
{keyword value}
In function and macro format specifications, braces
followed by an asterisk enclose elements that are
considered to be one unit of code, which can be
repeated zero or more times. For example:
{keyword value}*

&OPTIONAL

In function and macro format specifications, the word
&OPTIONAL indicates that the arguments after it are
defined to be optional. For example:
UIS:SET-BUTTON-ACTION display window action
&OPTIONAL xl yl x2 y2

Do not specify &OPTIONAL when you invoke a function
macro whose definition includes &OPTIONAL.
xiii

PREFACE

Convention

Meaning

&KEY

In function and macro format specifications, the word
&KEY indicates that keyword arguments are accepted.
For example:

UIS:MOVE-VEIWPORT window
&KEY :GENERAL-PLACEMENT :CENTER
:ABSOLUTE-POSITION-X
:ABSOLUTE-POSITION-Y
Do not specify &KEY-when you invoke the
macro whose definition includes &KEY.
<RET>

A symbol
indicates
example:

with
that

function

a 1- to
3-character
abbreviation
you press a key on the terminal. For

In examples, carriage returns are implied at the end of
each line.
However, the <RET> symbol is used in some
examples to emphasize carriage returns.
CTRL/x

CTRL/x indicates a control key sequence where you must
hold down the key labeled CTRL while you press another
key. For example:

CTRL/C or CTRL/Y

0xiv

PART I
GUIDE TO GRAPHICS PROGRAMMING

CHAPTER 1
SYSTEM OVERVIEW

This chapter provides an overview of the VAX LISP/VMS graphics system.
O After
a brief introduction to the system, the major sections of the
chapter demonstrate how the parts of the system operate and relate to
each other.
This demonstration is given by means of a continuing
example that you can reproduce on your VAXstation. You can start with
the examples in Section 1.2, then continue through the remainder of
the chapter, using the display and window objects you created.

1.1

INTRODUCTION

The VAX LISP/VMS graphics system is a collection of functions and
other objects that provide an interface to the bitmap graphics
capability of the VAXstation II family of workstations. You can use
this system to do the following from LISP code:

•

Create a virtual display that can collect graphic information

•

Create one or more windows into the virtual display in
to make the graphic information appear on the screen

•

Draw lines and text in the virtual display

•

Respond to the movement of a pointing device, such as a mouse,
and to pointer buttons

•

Get input from windows by means of virtual keyboards

·•

Use standard LISP output functions to send output
through window output streams

order

windows

These capabilities are available only when you are working on a
VAXstation supported by VAX LISP/VMS, such as the VAXstation II. They
are not supported on the VT100 or VT2xx families of terminals.

1-1

SYSTEM OVERVIEW
1.1.1

Relationship to MicroVMS Workstation Graphics Software

The VAX LISP/VMS graphics system is based on Version 2.0 of the
workstation graphics software provided with MicroVMS. Most of the
functions in the VAX LISP/VMS graphics system are directly equivalent
to routines provided with Version 2.0 of the MicroVMS workstation
graphics softwazte.
This equivalence is noted in the
function
descriptions in Part II of this manual.

VAX LISP/VMS has added a number of features to the basic MicroVMS
workstation graphics software.
These features are intended to make
graphics easy to use in LISP code ·and to provide some higher-level
capabilities. VAX LISP/VMS provides the following:
types:

DISPLAY,

WINDOW,

TRANSFORMATION,

and

•

LISP object
KEYBOARD

Window output streams, allowing text output to
normal LISP I/0 functions

•

A facility for operating on bitmaps, using the BITBLT function
and BITBLT objects

windows

using

The MicroVMS workstation graphics software is described in the
MicroVMS Workstation Graphics Programming Guide. It may occasionally
be useful to refer to this manual for more detail on a subject.
However, the VAX LISP/VMS Graphics Programming Guide gives a complete
description and definition of the LISP graphics system, using LISP
examples to demonstrate the software.

1.1.2

Programming Considerations

With the exception of the BITBLT-related objects, all
described in this manual are located in a package called UIS.
gain access to these objects in one of two ways:
•

Preface the name of each object
UIS:

with

the

package

objects
You can

specifier

(UIS:PLOT ••• )
•

Use the USE-PACKAGE function to make the objects available
you without the preface:
(USE-PACKAGE "UIS")
(PLOT ••• )

Although the second method is more convenient, DIGITAL recommends the
first method in order to avoid real and potential-conflicts with other
symbols. This is particularly true if you are writing a program that

1-2

SYSTEM OVERVIEW

uses both the graphics system and the VAX LISP Editor, since some
symbol names appear in both packages.
In this chapter, all examples use the explicit preface UIS with
graphics system objects.
In the remaining chapters, the preface is
not used in the interest of readability. The object descriptions in
Part II µse the explicit preface to show which package the object is
in.

1.2

VIRTUAL DISPLAYS AND WINDOWS

The fundamental unit in which graphic
displayed is the virtual display.
following characteristics:

0
1.2.1

information is collected and
Each virtual display has the

•

It has a coordinate system, called the world coordinate
system, which is appropriate for the graphic information to be
written to it.

•

It has a width and height
windows on the screen.

•

It can collect graphic information by
list.

•

It has a number of attributes, collected in one or more
attribute blocks, that determine how its graphical information
appears on the screen.

that

determine
means

the

size

its

display

Creating a Virtual Display

OYou create a virtual display object by means of the CREATE-DISPLAY
function.
This fun'ction creates and returns a display having the
coordinate system, width, and height that you request~
If you would like to follow along with the examples in this chapter,
create a virtual display now by means of the following forms:
(SETF *DEMO-DISPLAY*
(UIS:CREATE-DISPLAY
-10.0 -10.0
10.0 10.0
15.0 15.0))

; Lower left corner coordinates
; Upper right corner coordinates
; Default viewport size in cm

(UIS:ENABLE-DISPLAY-LIST *DEMO-DISPLAY*)
QYou now have an object named *DEMO-DISPLAY* whose value is a virtual
display.
The virtual display has been made capable of recording
graphic information by means of the ENABLE-DISPLAY-LIST function.
1-3

SYSTEM OVERVIEW

However, nothing has appeared on your screen yet. A virtual display
by itself does not display anything; you must create windows into the
display to make that happen.

You have given your virtual display a coordinate system defined by two
points at opposite corners of a square.
The points have the
coordinates -10.0,-10.0 and 10.0,10.0. This square establishes the
display'.s world coordinate system.
You have also established a
default width and height of 15 centimeters for the display.

1.2.2

Creating Windows

Now, create a window into the virtual display:

(SETF *DEMO-WINDOW-1*
(UIS:CREATE-WINDOW *DEMO-DISPLAY*))
A window appears on your screen.
It resembles a VT100 terminal
emulator window, except that it is square and has no title or keyboard
icon. The area inside the border is 15 centimeters square.
This
window maps into the entire virtual display; that is, it completely
fills the coordinate system that you specified when you created the
display.
Now create a second window, one that maps into only a portion
display:
(SETF *DEMO-WINDOW-2*
(UIS:CREATE-WINDOW
*DEMO-DISPLAY*
0.0 0.0 10.0 10.0))

the

; Display to map into
; Corners of rectangle in display

A second window appears; note that its sides are only half the length
of the first window's sides. The four optional arguments specify two
points, 0.0,0.0 and 10.0,10.0, that define the rectangle into which
this window maps.
These points specify the upper-right quadrant of
the virtual display. To make this relationship apparent, draw two
lines and a circle in the display, as follows:

(UIS:PLOT *DEMO-DISPLAY* 0 -8.0 -8.0 8.• 0 8.0)
(UIS:PLOT *DEMO-DISPLAY* 0 8.0 -8.0 -8.0 8.0)
(UIS:CIRCLE *DEMO-DISPLAY* 0 0.0 0.0 5.0)
The two windows now look like this:

0
1-4

SYSTEM OVERVIEW
n11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111n1111111

0
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIUIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIUUUIIIIIIIIIIIIUIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII

You can see that the smaller window reproduces the upper-right
quadrant of the larger window. You could create other windows into
other parts of the display •

1.2.3

Windows and Viewports

Both windows you have created so far depend on the default width and
height of 15 centimeters that you specified when you created the
virtual display. *DEMO-WINDOW-1*, which maps into the entire display,
is 15 centimeters square; *DEMO-WINDOW-2*, which maps into one-quarter
of the display, is 7.5 centimeters square. You can also specify the
dimensions explicitly when you create the window, overriding the
default dimensions. Create a third window:

(SETF *DEMO-WINDOW-3*
(UIS:CREATE-WINDOW
*DEMO-DISPLAY*
NIL NIL NIL NIL
:VIEWPORT-WIDTH 20.0
:VIEWPORT-HEIGHT 10.0))
1-5

; Coordinate arguments
; Width in centimeters
; Height in centimeters

SYSTEM OVERVIEW

(Note that the four optional coordinate arguments to CREATE-WINDOW are
now given as NIL.
This requests that the window be mapped to the
entire virtual display. COMMON LISP: requires that you supply all
optional arguments before any keyword-argument pairs you wish to use.)

This window looks like this:
~lll!l"'l""""'llllllill""""'llllllill""""'lllllllll""""'llllllillllllllllllllllllllllllllllllllllllll~IIIIIIIIIIIIIUIIIIIIIIHllllllltlllllllllllllfllllllllllfllltlltllllllllUltlltllltlllllllHlllltllllltt

You have created a window that maps into the ·entire virtual display
but does not use the default dimensions of the display. As a result,
the picture is distorted: stretched lengthwise, compressed in height.
This exercise brings up an important distinction, that between the
window and the viewport.
The window is a rectangle in a virtual
display. The viewport is the corresponding rectangle on the screen.
Anything that is drawn in the virtual display in the area covered by
the window appears in that window's viewport.
However, unless the
window and viewport have the same aspect ratio (that is, the ratio of
height to width), the contents of the viewport will be distorted.
This is the case with *DEMO-WINDOW-3*.
Figure 1-1 illustrates
windows, and viewports.

the

relatio~ship

among

virtual

displays,

0
1-6

SYSTEM OVERVIEW

LINE DRAWN IN
VIRTUAL DISPLAY

-------------, ,---- -----......... .. _
''
10.0.10.0

r--------

M.0.0

' , , ------ ...,8

--r-------

,,""

.... .....

.....

,//

1
VIEWPORTS

,,
,, ,
,,
,, ,

WINDOWS

_...

...............

,/
DISPLAY SCREEN

,/
L-------------I-------------

ML0·1110-B6

·10.0,10.0

VIRTUAL DISPLAY'S
WORLD·COORDINATE SPACE

Figure 1-1:

Virtual Displays, Windows, and Viewports

When you create a window, you also create its associated viewport.
You always refer to a viewport by means of its window. Some functions
affect windows and other functions affect viewports; both types of
functions take window objects as arguments.

You can create a window that maps into a small part of a virtual
display and an associated viewport that is relatively large. This has
the effect of magnifying the image in the window. For example:
(SETF *DEMO-WINDOW-4*
(UIS:CREATE-WINDOW
*DEMO-DISPLAY*
2.0 2.0 5.0 5.0
:VIEWPORT-WIDTH 10.0
:VIEWPORT-HEIGHT 10.0))

Q The new window looks like this:
1-7

; Small window in display
; Large viewport on screen

SYSTEM OVERVIEW

0
This image is "magnified" only in relation to the images in the other
windows.
It is important to realize that the world coordinate system
of the virtual display does not imply any particular physical
coordinate system. It is only the default size you specified when you
created the virtual display that implies a physical size, and this
default can be overridden when you create a window.

Separating the world coordinates of the virtual display from the
physical size of the window allows you to set up a world coordinate
system that is convenient for the data you are presenting.
For
example, to graph production of something between 1980 and 1988, you
could create this virtual display:
(UIS:CREATE-DISPLAY 1978.0 -100.0 1988.0 1000.0 30.0 15.0)
This display would allow you to plot raw data without first having to
transform it to some physical coordinate system. (The extra space on
the left and bottom edges is for labels.) The last two arguments
specify the default size of a window mapped into this display in
centimeters.

This concludes the demonstration portion of Section 1.2. If you wish
to stop here, delete the virtual display and its associated windows as
follows:
(UIS:DELETE-DISPLAY *DEMO-DISPLAY*)
Otherwise, leave the display and *DEMO-WINDOW-1* in place and continue
with the demonstrations in Section 1.3. You can get rid of the other·
windows with the DELETE-WINDOW function:
(UIS:DELETE-WINDOW *DEMO-WINDOW-2*)
1-8

SYSTEM OVERVIEW

Other Operations .

1.2.4

0 In addition to what you have seen in this section, you can manipulate
displays, windows, and viewports in the following ways:

•

Keyword arguments to CREATE-WINDOW allow you
appearance and location of a viewport.

control

the

•

You can move a window around in a virtual display, and
the size of the window, with the MOVE-WINDOW function.

•

You can move a viewport around the
screen
with
the
MOVE-VIEWPORT function.
The POP-VIEWPORT and PUSH-VIEWPORT
functions allow you to arrange viewports in front of or behind
one another.

•

You can establish an action to be taken if the user of
program attempts to delete, resize, or move a window.

•

You can create a transformation into a virtual display.
A
transformation allows you to superimpose a second coordinate
system on a virtual display.

change

your

All of these subjects are covered in Chapter 2 of this manual.

1.3

GRAPHICS OPERATIONS

Once you have created a virtual display and one or more associated
windows, you use various line-drawing and text-writing functions to
create images on the screen. These functions are directed into the
virtual display, and the virtual display "remembers" what has been
done by means of its display list. An image appears on the screen
when its position in the virtual display falls under one or more of
the windows that are mapped into the display.
You can create and manipulate screen images in several ways.
This
section introduces two:
line-drawing functions and text-writing
functions. The section also introduces the use of attributes and
attribute blocks to modify the appearance of screen images.
The demonstrations in this section assume the existence of the virtual
display *DEMO-DISPLAY*, created in Section 1.2, and its associated
window *DEMO-WINDOW-1*. If you wish to try the examples in this
section, create these objects if they do not already exist.

0
1-9
····--··-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

SYSTEM OVERVIEW

1.3.1

Drawing Lines and Circles

The PLOT function draws a point, a line, or a series of connected
lines. You have already seen how PLOT can draw a single line:

(UIS:PLOT *DEMO-DISPLAY* 0 -8.0 -8.0 8.0 8.0)
The first argument to PLOT is the virtual display.
This argument
directs the output of PLOT to a particular display and causes the rest
of its arguments to be used in the context of that display.
The second argument to PLOT is the· attribute block.
later in this section.

discussed

The remaining arguments to PLOT are coordinate pairs that define
points in the virtual display. In the example, the first point is at
-8.0,-8.0; the second at 8.0,8.0. In this case, PLOT draws a line
between those two points. If only one point had been supplied, PLOT
would draw just that point.
If more than two points are supplied,
between the points. Try the following:

PLOT

draws

connected

lines

(UIS:PLOT *DEMO-DISPLAY* 0
-4.0 -4.0
4.0 -4.0
4.0 4.0
-4.0 4.0)
-4.0 -4.0)

This function call plots a complete square.
Note that the coordinates are specified as pairs of floating-point
numbers.
Coordinates in a virtual display'& world coordinate system
are always floating-point numbers.

You have also seen how to draw a circle:
(UIS:CIRCLE *DEMO-DISPLAY* 0 0.0 0.0 5.0)
As with PLOT (and all other drawing and text functions that operate in
virtual displays), the first two arguments are the display and
attribute block. The next two arguments specify the coordinates of
the center of the circle, 0.0,0.0 in this case. The final argument
specifies the radius of the circle in the units of the display's world
coordinate system.
You can also draw an arc with CIRCLE by using two optional arguments
to specify the beginning and end of the arc. Try the following:

0
1-10

SYSTEM OVERVIEW

(UIS:CIRCLE *DEMO~DISPLAY* 0
0.0 0.0 7.0
(/ PI 2) PI)

This draws an arc consisting of a quarter-circle, as shown here:
111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111m11

.'·~:...:., . .~·........f.-

•'

~·

f,.-.,.~ ... , .

~ .. ,,.:.;

0
Figure 1-2 illustrates the relationship of CIRCLE'S various
to the circle that is drawn.

arguments

The ELLIPSE function draws an ellipse. Its operation and arguments
are analogous to CIRCLE, except that it has two radius arguments -one each for the horizontal and vertical axes.

1.3.2

Writing Text

The TEXT function writes a specified string of text into
display. Try the following:
(UIS:TEXT *DEMO-DISPLAY* 0 "This is text• o.o 0.0)
1-11

the

virtual

SYSTEM OVERVIEW

(UIS:CIRCLE *DEMO-DISPLAY* 0

0.0 0.0
,1.0

(/ PI 2) PI)

CENTER
RADIUS
START AND END RADIANS

ML0-191·86

Figure 1-2:

Drawing a Circle

The string of text appears at the middle of the virtual display.

The first two arguments are again the virtual display and attribute
block.
The third argument is the text string to be displayedi it can
be any LISP character string.
The last two arguments are coordinates for the point in the virtual
display at which the text should start. However, these two arguments
are optional. There is a default starting position for text, which is
where the last text operation left off. To illustrate this, try the
following:

(UIS:TEXT *DEMO-DISPLAY* o· "More text")
The new text string appears right at the end of the previous one:

The NEW-TEXT-LINE function returns the text position to the left
margin for text operations, and moves it down by the height of a line
of text. Thus, NEW-TEXT-LINE is analogous to the carriage return on a
typewriter. Try .these functions:
(UIS:NEW-TEXT-LINE *DEMO-DISPLAY* 0)
(UIS:TEXT *DEMO-DISPLAY* 0 "New line of text")
1-12

SYSTEM OVERVIEW

that the new line .of text appears at the left edge of the window.
O Note
This is the default left margin.
You can change this margin by
modifying an attribute block, as described in the next section.

1.3.3

Using Attributes

Each of the functions in this section has taken an attribute block as
its second argument. Until this point, the attribute block argument
has been 0. Almost all functions that can produce something visible
require an attribute block argument.
An attribute block is a
collection of attributes, each of which specifies the appearance of
one aspect of window output.
Attributes control the following
characteristics, among others:

• The appearance of lines: solid, dotted, dashed, and so on
•

The way in which arcs are treated:
chord, or made into a pie segment

not closed, closed with

•

Whether or not line figures are filled~ and if so,
are filled with

what

they

•

The font in which text is written, and
text operations

margin

for

the

left

0 Every function that requires an attribute block uses the values of
some attributes from the specified block to influence the appearance
of the output. No single function uses all the attributes in a block.
Drawing functions use some attributes and text functions use others,
while some attributes are common to both drawing and text.

Attribute block O contains a collection of default attribute values
that are appropriate for many operations. To use a different value
for an attribute, you must first modify an attribute block so that it
has the appropriate value for that attribute. You then supply the
modified attribute block as an argument to the drawing or text
function.
To modify an attribute block, use the SET-ATTRIBUTE function.
This
function takes an attribute block and copies its values to an
attribute block, changing the value of one attribute in the process.
The following example modifies attribute block 1 so that it causes
lines to be drawn dashed instead of solid.
Try modifying this
attribute block, and then draw a line using it:
(UIS:SET-ATTRIBUTE *DEMO-DISPLAY* 0 1 :LINE-STYLE :DASHED)
(UIS:PLOT *DEMO-DISPLAY* 1 -5.0 0.0 5.0 0.0)

0
1-13

SYSTEM OVERVIEW

The PLOT function call draws a dashed horizontal line:

(
e text
of te

The SET-ATTRIBUTE function call in the example copies values from
attribute block Oto attribute block 1. The only difference between
attribute blocks O and 1 is the value of the :LINE-STYLE attribute,
which is now :DASHED instead of :SOLID.
Note that the SET-ATTRIBUTE function requires a virtual display
argument.
This is because attribute blocks are associated with
virtual displays. Each virtual display has 256 attribute blocks
associated with it.
Attribute block O is the same for all virtual
displays, but attribute block 1 may be different from one display to
the next.
You can use SET-ATTRIBUTE to change one value in an attribute block
that has already been modified, simply by specifying the same
attribute block for input and output. The following example further
modifies attribute block 1:

(UIS:SET-ATTRIBUTE *DEMO-DISPLAY* 1 1 :ARC-TYPE :CHORD)
Now, in addition to specifying a dashed line style, attribute block 1
indicates that arcs should be closed by drawing a line between their
endpoints.
You can modify any attribute block
Attribute block O can only be read.

except

attribute

block

One frequently-changed attribute is the font in which text is written.
A font consists of a collection of printing characters in a particular
type style and size. Fonts are contained in a directory with the
logical name SYS$FONT; each file in this directory represents a single
font.
For a detailed discussion of attributes, see
discussions of various graphic operations in
information on individual attributes.

Section
Chapter

The
contain

3. 3.

0
1-14

SYSTEM OVERVIEW

1.3.4

Other Operations .

0 In addition to what you have seen in this section, the following
graphic operations are available to you:

•

The PLOT-ARRAY function plots lines using entries
vectors as the X and Y coordinates of each point.

•

A number of functions allow you to measure strings of text in
a specified font and to precisely position text on the screen.

•

The READ-IMAGE-PIXEL and IMAGE functions store a screen image
in memory and write an image from memory to a virtual display,
respectively. The BITBLT family of functions and objects
perform various operations on screen images stored in memory.

•

The ERASE function removes
display .

•

The BEGIN-SEGMENT and END-SEGMENT functions allow the use of
temporary attribute blocks over specified groups of graphic
operations.

•

Device coordinate counterparts to most of
the
graphic
functions allow you to operate at the pixel level, offering
potential gains in speed and accuracy.

graphic

objects

from

two

virtual

0 All of these subjects are treated in greater detail in Chapters 3 and
4.

1.4

POINTER OPERATIONS

supported by the VAX LISP graphics system come equipped
O Workstations
with a pointing device, typically a mouse. The pointing device serves
two functions: it directs a pointer cursor around the screen, and it
has one or more buttons that allow you to make requests of the
workstation. Working together, the pointer and its buttons allow you
to select items from menus, move windows around the screen, and so on.
A number of functions allow your programs to make use of the
device in various ways. You can:

pointing

•

Determine the position of the pointer cursor in the coordinate
system of a virtual display

•

Move the
control

pointer

cursor

around

the

screen

under

• Determine the state of the pointing device buttons
1-15

program

SYSTEM OVERVIEW

•

Specify a function to be invoked when the pointer cursor moves
within or exits a specified area of a display

•

Specify a function to be invoked when a button on the pointing
device is pressed or released

For information and examples on pointer operations, see Chapter 5.

1.5

KEYBOARD INPUT FROM WINDOWS

You can capture keystrokes directed at a particular window by means of
a virtual keyboard. A virtual keyboard is a virtual input device that
you create with the CREATE-KB function.
Various functions let you
associate a virtual keyboard with one or more windows. When the user,
or your program, makes a particular virtual
keyboard
active,
keystrokes at the physical keyboard are ' transmitted through the
virtual keyboard to your program.
Your program can use these
keystrokes in one of two ways:
•

Synchronously, by means of the READ-KB-CHAR function.
This
function returns each character from a particular virtual
keyboard in turn.

•

Asynchronously, by means of the SET-KB-ACTION function.
This
function establishes an action, such as an interrupt function,
to execute each time a character is typed through a particular
virtual keyboard.

Chapter 6 describes the use of virtual keyboards.

1.6

WINDOW OUTPUT STREAMS

You can establish an output stream to a window. Output sent to that
stream by any of the standard COMMON LISP output functions appears in
the window. This facility includes the following features:
•

Choice of horizontal text wrapping or truncation

•

Choice of vertical text scrolling or wrapping

•

Control over the part of the window in which text appears

•

Control over the size and style of text

Chapter 7 describes window output streams.

1-16

CHAPTER 2
VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

chapter describes the various objects and concepts involved in
O This
the display of graphic information on a workstation screen. The
actual graphic operations are described in Chapter 3; this chapter
defines the framework within which those operations occur. You need
an understanding of the material presented in this chapter before you
can use the information in subsequent chapters.
This chapter consists of the following:

overview of how graphic information appears on the screen

•

A description of transformations, which
allow
you
to
superimpose alternate coordinate systems on a virtual display

description of the coordinate
access
description of virtual
graphic information

systems

displays,

which

you

have

and

store

description of windows and viewports, which allow graphic
information stored in virtual displays to appear on the screen

If you are completely unfamiliar with these topics, you may wish to
read Section 1.2, which provides an elementary introduction to them.

2.1

HOW AND WHEN GRAPHIC INFORMATION IS DISPLAYED

In order to display graphic information on the workstation screen, you
must do three things:

Create a virtual display.

Create a window into the virtual display.

2-1

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS
3.

Draw lines or write text into the virtual display, within the
area covered by the window.

The virtual display is the fundamental unit of the VAX LISP graphics
system.
It is a two-dimensional space that can store graphic
information. All graphic operations are performed with respect to
some virtual display.
Thus the first step in any graphics program
must be to create at least one virtual display.
When you create a window, you define a rectangle in the virtual
display and a corresponding re~tangle (the viewport) on the screen.
Anything in the virtual display that falls within the bounds of the
window rectangle appears in the viewport. You can create many windows
of various sizes that map into the same virtual display. Windows can
overlap one another.
When you use a function that draws a line or writes text, you cause
that information to be stored in the virtual display. (This assumes
that the virtual display's display list has been enabled
see
Section 3.1. The display list is disabled by default.) Conceptually,
that information is stored
at
a
certain
location
in
the
two-dimensional space of the display. If a window happens to include
that location, the information will also appear on the screen.
If a
window is later created that includes that location, the information
will appear in the associated viewport. If two windows include that
location, the information will appear in both corresponding viewports.

Figure 2-1 shows how graphic information is displayed.

2.2

COORDINATE SYSTEMS

The VAX LISP graphics system
three different purposes:

employs

three

coordinate

systems

•

World coordinates specify locations in a virtual display

•

Device coordinates specify locations in a viewport

•

Screen coordinates specify locations on the display screen

for

Each of these coordinate systems is a two-dimensional Cartesian
system.
In a Cartesian coordinate system, the location of a point is
expressed as a pair of numbers. The first number in the pair, the X
value, specifies the horizontal displacement of the point from an
origin point. The second number, the Y value, specifies the vertical
displacement.
The coordinates of the origin are expressed as 0.0,0.0
(for world and screen coordinates) or 0,0 (for device coordinates).

0
2-2

VIRTUAL DISPLA VS, WINDOWS, AND TRANSFORMATIONS

VIRTUAL DISPLAY

SCREEN

(SETF DISPLAY (CREATE-DISPLAY
0.0 o.o
10.0 10.0
s.o 5.0))

10.0.10.0

r--------------

(ENABLE-DISPLAY-LIST DISPLAY)

.. _____________ _

o.o.o.o
STEP 1: CREATE A VIRTUAL DISPLAY

0
10.0,10.0

""r""--==-"=-==--==-==--==-=··=-=-,•-- -

._ _____________ _

--o

-----

(SETF WINDOW (CREATE-WINDOW
DISPLAY))

--- --- --

o.o.o.o

STEP 2: CREATE A WINDOW

--- ---

10.0.10.0

•r --------

I
I
I
I
I

I
I
I
I

-----·-1a

--------------l' - - - o.o.o.o

(PLOT DISPLAY O
o.o 2.0 10.0 8.0)

-----l

STEP 3: DRAW IN THE DISPLAY

ML0.112·81

QFigure 2-1: Displaying Information on the Screen
2-3

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS
World Coordinates

2.2.1

Each virtual display that you create has .'its own world coordinate
system.
The characteristics of a world coordinate system are the
following:
•

You can set up a world coordinate system so that
appropriate for the data you are trying to present.

•

The world coordinate system establishes
which your data points should not fall.

•

You specify world coordinate values as pairs of floating-point
numbers.

bounds

outside

Conceptually, a virtual display's world coordinate system is a
two-dimensional space in which points are specified by pairs of
floating-point coordinates. When you create a virtual display, you
specify a rectangle in the world coordinate space that you intend to
contain all of your graphic information. You select the bounds of
this rectangle to be appropriate for the data you wish to display.
For example, suppose you wish to graph chemical activity, measured by
the amount of gas released in cubic centimeters per second, against
temperature measured in degrees Celsius. The amount of gas ranges
from 10 to 100 cubic centimeters per second, while the temperature
ranges from 30 to 80 degrees. When you create your virtual display,
you specify a rectangle as shown in Figure 2-2.

80.0,100.0
~

--------------------------------------,

(SETF TEMP-GRAPH (CREATE-DISPLAY

30.0 10.0
80.0 100.0
27.0 15.0))

L------···-···••••••••···-----------·-~
WORLD-COORDINATE SPACE

30.0,10.0

- - - - BOUNDS OF WORLD-COORDINATE SPACE
··---------· DEFAULT WINDOW

Figure 2-2:

ML0·183-86

Example of a World Coordinate System

The rectangle indicates where a default window wiil be located in the
virtual display and how large it will appear on ~e screen. You may
2-4

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

also request that graphic information lying outside the
made invisible, or clipped.

rectangle

Every virtual display has its own world coordinate space.
Thus,
graphic information written in one virtual display can never appear in
another virtual display, even though both virtual displays may map the
same portion of their world coordinate spaces to the screen.

2.2.2

Device Coordinates

A display device, such as a display screen or a laser printer, forms
an image by selectively activating thousands of tiny points in a grid.
These points are called picture elements, or pixels for short. Figure
2-3 shows how individual pixels make up an image. When the pixels are
small enough, the human eye blends them into a smooth form .

••••••
•••
••
••
••••••
•••
••••••••••••
•••
••••
•••
•••• •••
••••••
••

ML0-194-86

Figure 2-3:

Making an Image from Pixels

VAX LISP graphics system provides direct access to the display's
O The
pixels through the device coordinate system. Each viewport displayed
.

on the screen
has
its
own
device
coordinate
system.
A
device-coordinate pair specifies the location of a pixel in a
particular viewport. A function that gives location information in
the device coordinate system draws directly into the viewport, not
into a virtual display. Figure 2-4 illustrates this.
The origin of the device coordinate system is always at the lower left
corner of the viewport. The upper bounds of the system for a given
viewport are determined by the number of pixels in the viewport's
horizontal and vertical dimensions.
Points that lie outside the
bounds of the system are never displayed.
Since pixels are indivisible
expressed as integers.

units,

0
2-5

device

coordinates

are

always

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

0
100.120

(PLOT-PIXEL
WINDOW-1 0
30 25
100 120)

0
ML0·195-86

Figure 2-4:

The Device Coordinate System

All functions that draw lines or write text into a virtual display
have counterparts that operate in a viewport. These functions have
the suffix "-PIXEL" added to their names.
They have the following
characteristics:
•

They take a window as their first argument instead of a
virtual display. The output occurs in the viewport associated
with the window.

•

They take device-coordinate location arguments (integers)
instead
of
world-coordinate
arguments
·(floating-point
numbers).

•

They do not store graphic information in a virtual display.

•

They can be faster than their world-coordinate counterparts.

In some situations, it is appropriate to use device coordinates
instead of world coordinates.
Chapter 3 covers this subject in
detail.
Since device coordinates specify pixel locations, the size and shape
of an image specified in the device coordinate system depends on the·
size and shape of a display device's pixels. Thus, the same function
may present a different appearance on different devices. A common
2-6

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

problem arises when pixels are not "square," that is,
not the same in width and height.
Figure 2-5
difference between square and nonsquare pixe1s.

when they are
illustrates the

10,35

35,35

10,10

35,10

40
10,35

35,35

15
10
10

10,10

35, 10

o.o

0,0

SQUARE PIXELS

NON-SQUARE PIXELS
ML0·196-86

0 Figure 2-5: Square and Nonsquare Pix~ls

The size of a pixel is expressed in terms of the display's horizontal
and vertical resolution
that is, the number of pixels per
centimeter, measured horizontally and vertically. For example, if a
display has a resolution of 40 pixels/cm both horizontally and
vertically, that display has square pixels.
The following function
will draw a 1-centimeter square on that display:
(PLOT-PIXEL *DEMO-WINDOW-1* 0
40 40 80 40 80 80 40 80 40 40)
Another display device may have a resolution of 40
pixels/cm
horizontally but only 35 pixels/cm vertically. On that device, the
same function would plot a rectangle 1.0 centimeter wide and 1.14
centimeters high.
You can use the GET-DISPLAY-SIZE function to determine the horizontal
and vertical resolution of a display device. This function returns
six values; the third and fourth values are the horizontal and
vertical
resolutions,
respectively.
They
are
expressed
as
pixels/centimeter.

0
2-7

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS
2.2.3

Screen Coordinates

A screen coordinate system is defined for the entire display device.
The units of the screen coordinate system are centimeters, and the
origin of the system is at the lower-left corner of the display
device.
The upper bounds of the system are determined by the size of
the screen. You specify locations on the screen with pairs of
floating-point numbers.

You can use the GET-DISPLAY-SIZE function to determine the size of a
display device, and thus the bounds to its coordinate system.
GET-DISPLAY-SIZE returns six values. The first two are the width and
height of the display screen in centimeters, and the last two are the
width and height in pixels.
Since VAX LISP graphics functions cannot draw directly on the display
screen, the usefulness of screen coordinates is limited to positioning
viewports on the screen. Section 2.4 contains examples of the use of
screen coordinates.

2.3

CREATING AND MAINTAINING VIRTUAL DISPLAYS

This section explains how to create a virtual display, how to gain
access to it, how to delete it, and how to specify its properties.
Other sections of this manual describe other aspects of a virtual
display:

2.3.1

•

Section 2.2.1 describes the coordinate system
virtual display.

used

within

•

Section 3.1 describes the virtual display's display list, by
means of which it stores graphic information. You must enable
the display list if you want the virtual display to store
information.

•

Section 3.3 describes the virtual display's attribute blocks,
by means of which it modifies the appearance of graphic
operations.

•

Section 3.4 describes the virtual ·display's color map, which
controls the display color of objects in the virtual display.

Creating and Accessing a Virtual Display

The CREATE-DISPLAY function creates and returns a virtual display
object.
You should retain the virtual display, for e?Cample by
assigning it to a symbol:

2-8

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

(SETF *DISPLAY-1*. (CREATE-DISPLAY
0.0 0.0 50.0 200.0 20.0 10.0))

You can then use the symbol as an argument to the
that require a virtual display.

numerous

The DISPLAYP function returns T if the value
virtual display object, and NIL otherwise.

its

functions

argument

Each virtual display has an identification number (the vd_id) that is
assigned by the MicroVMS workstation graphics software. You can use
the UIS-ID function to return this number, should you need it for use
with CALL-OUT.

If you do not retain the value returned by CREATE-DISPLAY, you have no
means of access to the virtual display. You will be unable to create
windows into it, to draw in it, or to delete it. (Should you "lose" a
yirtual display, the LIST-ALL-DISPLAYS function returns a list of all
the displays that you have created and have not yet deleted.)
Once you have created a virtual display, you must enable its display
list if you want to store information in the display. Section 3.1
describes the display list.

02.3.2

Deleting a Virtual Display

Virtual displays consume system resources. If you have not explicitly
deleted a virtual display, the garbage collector cannot free the
dynamic memory that it occupies. Therefore, you should take care to
delete
virtual
displays
when
you are done. with them.
The
DELETE-DISPLAY function deletes a virtual display:

(DELETE-DISPLAY *DISPLAY-1*)
DELETE-DISPLAY
function
also
deletes
any
windows
The
transformations associated with the display that it deletes.

2.3.3

and

Arguments to CREATE-DISPLAY

CREATE-DISPLAY takes six arguments. The first four arguments specify
two world-coordinate points that define the lower-left and upper-right
corners of a rectangle. This rectangle serves as a reference when
creating windows into the virtual display.
It also limits the
coordinates of the information you can write into the display.
last two arguments specify default screen dimensions
O CREATE-DISPLAY's
for windows created into the display. They esta.blish the width and
height, in centimeters, of a window that corresponds to the
2-9

rectangle

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

defined by the first four arguments.
Windows that occupy only a
portion of the rectangle will be proportionally smaller.
Figure 2-6 illustrates how CREATE-DISPLAY's arguments
world coordinate system.

relate

the

100.0,50.0

,--------------- ---1 - - -

-- -

L,• ________________
JI
.

- -- - -

---D·}- -· -

20 cm - -

o.o.o.o

(CREATE-DISPLAY
- - - - - - - - 0 . 0 0. 0
- - - - - - - - 1 0 0 . 0 50.0
20.0 12.0))

(SETF WINDOW (CREATE-WINDOW
DISPLAY))

Figure 2-6:

2.4

ML0·197·86

Arguments to the CREATE-DISPLAY Function

CREATING AND MANIPULATING WINDOWS AND VIEWPORTS

This section explains how to create and delete a window into a virtual
display, how to control the appearance of the viewport associated with
the window, and what you can do with windows and viewports after they
are created.

2.4.1

0
Q

Creating and Accessing Windows

The CREATE-WINDOW function creates a window into a virtual display,
and
a
viewport
associated
with
the window on the screen.
CREATE-WINDOW returns the window object it created. If you wish to
manipulate the window or viewport after it has been created, or to
delete the window, you must retain the returned window object.·
For
example:
(SETF *WINDOW-1* (CREATE-WINDOW *DISPLAY-1*))
The window object returned by CREATE-WINDOW is your means of access to
both the window and its associated viewport. The -following functions
2-10

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

provide information about windows:
•

The WINDOWP function returns T if its
object and NIL otherwise.

argument

•

The WINDOW-DISPLAY function returns the display into which its
argument, a window, is mapped.

•

The DISPLAY-WINDOWS function returns a
mapped into a specified display.

the

windows

•

The UIS-ID function returns the MicroVMS workstation
software window ID (wd_id) for the window.

graphics

list

window

If you use the CREATE-WINDOW function without any optional arguments
(as in the example just given), the function creates and returns a
window whose bounds are the world-coordinate rectangle you specified
with CREATE-DISPLAY (see Section 2.3.1). This window is the virtual
display's default window.
The width and height of the viewport associated with a default window
are specified by the last two arguments to the CREATE-DISPLAY function
call that created the virtual display.
The viewport also has the
following default characteristics:

•

It has a border.

•

It has a banner but no title.

•

Its placement on the screen
graphics software.

•

It is immediately visible on the screen.

determined

entirely

the

2.4.1.2 explains how to specify these aspects of a viewport's
appearance when creating a window.
0 Section
2.4.1.1 Controlling Window Coordinates - Four optional arguments to
the CREATE-WINDOW function allow you to create a window that maps into
a world-coordinate rectangle other than the
default
rectangle
established with CREATE-DISPLAY.
The four optional argument·s are
floating-point numbers that specify coordinates of the lower-left and
. upper-right corners of the desired rectangle. Figure 2-7 illustrates
the use of these arguments.

Note that if you want to use keyword arguments with CREATE-WINDOW, you
~ust supply the four optional arguments. You can use values of NIL to
request the default window dimensions.

2-11

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

(SETF DISPLAY (CREATE-DISPLAY

0.0 0.0
100.0 50.0
20.0 12.0))

r-------'E!!:~·~o

- - ...

--of

75.0,40.0
:
__ - - - _.
7.2 cm
Ir----,--,---I
I
I
I
l
I
I
:
I
--'--·
: L_____ ..:--:-1ocm-

____,...•-

2s.o.10.o ____
0.0.0.0

\.-------.......:.---

(SETF WINDOW
( CREATE-WINDOW
DISPLAY

25.0 10.0 75.0 40.0))

MLO 198·86

0
Figure 2-7:

Specifying Window Coordinates with CREATE-WINDOW

Unless you also specify :VIEWPORT-WIDTH or :VIEWPORT-HEIGHT (see
Section 2.4.1.2), the screen dimensions of a viewport associated with
a nondefault-sized window are determined by the virtual display•s
default screen dimensions. When you use the CREATE-DISPLAY function,
you establish a scale between the units of your world coordinate
system and the physical dimensions of the display device. For
example, if your default window is 100 world-coordinate units wide and
your default viewport is 10 centimeters wide, the default horizontal
scale is 10 units/centimeter. The vertical scale may be the same or
different, depending on the arguments to CREATE-DISPLAY. When you
create a window without specifying the viewport size, the graphics
system preserves this scale.
For example, if you use optional
arguments to create a window that is 50 units wide, the corresponding
viewport will be 5 centimeters wide.

2.4.1.2 Controlling Viewport Characteristics - A number of keyword
arguments to the CREATE-WINDOW function allow you to control the size,
appearance, and screen placement of a
viewport.
Figure
2-8
illustrates a typical viewport and identifies its various components.
The :VIEWPORT-WIDTH and :VIEWPORT-HEIGHT arguments allow you to
specify, in centimeters, the width and height of the viewport's
picture area. The picture area is the portion of the viewport that is
mapped to the window in the virtual display.

2-12

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS
MENU ICON

~- 1

TITLE")

•""-"Polar Dear in Dlizzt,\n1

,.·, ·, _.---_ ,__ BANNER

-----·

_ _ _ _ _ _ PICTURE _ _ _ _ _ _

BORDER

111

AREA

0
ML0·199·86

Q Figure 2-8: Viewport Components
You can supply a title for the viewport with the :BANNER-TITLE
argument.
The :NOBANNER and :NOBORDER keywords, when supplied with
values of T, cause the banner and border to be removed from the
viewport.
You can control the placement of a window on the screen in one of two
O ways:
•

Absolutely, by specifying the viewport's screen coordinates

•

Generally, by specifying the area of the screen
place the viewport

wnich

Use the :ABSOLUTE-POSITION-X and :ABSOLUTE-POSITION-Y keywords to
position the viewport at an exact location on the screen. These give
the location, in centimeters, of the viewport's lower-left corner.
'(If you also supply the :CENTER keyword with a non-NIL value, the
viewport will be centered on the specified location rather than having
its lower-left corner at that location.)

Use the :GENERAL-PLACEMENT keyword to specify a general screen
location
for
the
viewport.
The
value
you
supply
with
:GENERAL-PLACEMENT can be :TOP, :BOTTOM, :LEFT, :R.IGHT, or a list of
two of these, such as '(:TOP :RIGHT).
The graphics system will
2-13

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

attempt to place the viewport in the area you request, although
factors such as the proximity of other viewports may prevent it from
doing so.

You can request that a viewport be created off-screen by using the
:INVISIBLE keyword with a non-NIL value. The window and viewport are
created but the viewport does not appear.
You can later use the
MOVE-VIEWPORT function to move the viewport onto the screen (see
Section 2.4.4).

2.4.2

Deleting Windows

The DELETE-WINDOW function deletes a window and causes the window's
associated viewport to disappear from the screen. The function does
not delete the virtual display into which the window is mapped, nor
does it affect any information that is stored in the virtual display.
If there are any window output streams
those streams are closed.

associated

If you have not explicitly deleted a window, the
cannot free the dynamic memory that it occupies.

2.4.3

with

the

garbage

window,
collector

Moving and Resizing Windows

Two functions allow you to alter a window's coordinates in a virtual
display and change its size in the display. The first function,
MOVE-WINDOW, changes the location and/or size of the window without
affecting
the
size
of
the
viewport.
The second function,
RESIZE-WINDOW, can affect both the window and the viewport.
Both
functions can change the scale of objects displayed in the viewport.
The MOVE-WINDOW function shifts a window to a new rectangle in the
virtual display. Any information in the display at that new location
appears in the window's associated viewport. The dimensions (in world
coordinate units) of the new rectangle may be the same as those of the
window's previous rectangle. In this case the information displayed
in the v_iewport is drawn to the same scale as it was previously. If
the new rectangle's dimensions are different, then the scale of the
displayed information will also be different. Figure 2-9 illustrates
two calls to MOVE-WINDOW, one without and one with rescaling.
The RESIZE-WINDOW function allows you to change the size of the window
by specifying a new size for its associated viewport. It also allows
a change of the location of the window in the display and of the
viewport on the screen.
See Section 2.4.6.2 for more information·
about the RESIZE-WINDOW function.

2-14

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS
ENTIRE VIRTUAL DISPLAY

ORIGINAL WINDOW

5.0,5.0

0.0 0.0

(MOVE-WINDOW DISPLAY WINDOW-1

2.5 3.5 7.5 8.5)

0
o.o.o.o

2.5,3.5

(MOVE-WINDOW DISPLAY WINDOW-1

5.0 0.0 10.0 10.0)

0
5.0,0.0
ML0·200.86

Figure 2-9:

Moving a Window
2-15

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

2.4.4

Moving Viewports
.,

The MOVE-VIEWPORT function allows you to move a viewport and its
contents around the screen. The arguments to MOVE-VIEWPORT are the
window associated with the viewport and several keyword arguments to
control placement.
These keyword arguments are the same as the
arguments to CREATE-WINDOW:
•

:ABSOLUTE-POSITION-X and :ABSOLUTE-POSITION-Y, to specify an
absolute position for the viewport, and :CENTER, to specify
that the viewport be centered on that location

•

:GENERAL-PLACEMENT, to request
viewport

•

:INVISIBLE with a non-NIL argument,
viewport be moved off the screen.

general
to

position

for

the

request

that

the

When you use MOVE-VIEWPORT to move a viewport on the screen, all the
graphic information in the viewport moves with it. This includes
information stored in the virtual display associated with
the
viewport's window, and any information that was written directly into
the viewport. For example, if you used the PLOT-PIXEL function to
draw lines in the viewport, those lines would be preserved, even
though they are not stored in the virtual display.

2.4.5

Determining and Controlling Viewport Occlusion

When you create a window, its associated viewport hides, or occludes,
any other viewports that it overlaps. The contents of the occluded
viewports are not lost but they cannot be seen. Four functions allow
you to determine if a particular viewport (or location in a viewport)
is occluded, and to control which viewports are occluded and which are
exposed.

The GET-VISIBILITY function allows you to determine if all or a
specified part of a window is visible on the screen. Depending on the
arguments you supply, GET-VISIBILITY checks to see if a point, a
rectangle, or the window is entirely visibl.e. The coordinates of the
point and rectangle are supplied using the world coordinate system.
The GET-VISIBILITY-PIXEL function performs the same operation except
that it allows you to specify a point or rectangle in the device
coordinate system of the viewport.
Two functions, POP-VIEWPORT and PUSH-VIEWPORT, allow you to control
viewport
visibility.
Each takes a single argument, a window.
POP-VIEWPORT brings the viewport associated with the window to the.
front
so
that
it
occludes any viewports. that it overlaps.
PUSH-VIEWPORT pushes the viewport to t~e rear so that it is occluded
by any viewports that it overlaps. Neither of the~ functions changes
2-16

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

the position of the viewport on the screen.
They only change the
O visibility
relationship between a viewport and other viewports that it
overlaps.

2.4.6

Handling User Actions

The default VAX LISP graphics viewport is similar to the VAXstation's
VT100 viewport in that the user can modify its size and location. For
example, a user can use the pointing device to move a viewport that
you create around the screen. If the viewport has a menu icon, the
user can use the Window Options menu to push or pop the viewport or
change its size.
VAX LISP graphics system provides several functions that allow you
O The
to control and respond to user actions such as these. The VAX LISP
graphics system also provides a default response to these actions.
You can choose to use the default response, and you can reinstate the
default response later should you require your own response for a
while.

A user of your program can use the pointer to manipulate a viewport at
any point in program execution. For this reason, user actions with
regard to viewports must be considered asynchronous activities; that
is, you cannot predict when they will happen. You therefore must
specify interrupt functions to respond to - these actions.
The VAX
LISP/VMS System Access Programming· Guide contains information on
interrupt functions.

2.4.6.1 Responding to Viewport Movement - A user can move
the
viewport on the display screen by moving the pointer to the viewport
border, pressing a button, and moving the outline of the viewport to a
new location. By default, the graphics system does nothing to prevent
this action and makes no response to it.
However,
in
some
applications, movement of one viewport might ruin an important spatial
relationship between viewports.
The SET-MOVE-INFO-ACTION function allows you to specify a response to
movement of any particular viewport. You specify this response in the
form of an interrupt function that is called each time the viewport is
moved.
This function can take the steps necessary to correct any
problems that the viewport movement may have created.
Example 2-1 illustrates a simple use of SET-MOVE-INFO-ACTION.
the function defined in Example 2-1, you could create a window:

(SETF IMMOVABLE-WINDOW
(CREATE-IMMOVABLE-WINDOW DISPLAY 4.0 4.0))

2-17

Using

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

The viewport corresponding to IMMOVABLE-WINDOW would
have
its
lower-left corner at 4.0 centimeters from the bottom and left edges of
the screen. If the user attempted to move the viewport, the interrupt
function would simply return it to the original position on the
screen.
Example 2-1:

The Immovable Viewport

;; Creates and returns a window object, with the viewport at position
; ; X, Y on the screen. The user ca·nnot move the viewport from that
;; location.
(DEFUN CREATE-IMMOVABLE-WINDOW (DISPLAY X Y)
(LET* ((WIN (CREATE-WINDOW
DISPLAY NIL NIL NIL NIL
:ABSOLUTE-POSITION-XX
:ABSOLUTE-POSITION-Y Y))
(IIF-ID (INSTATE-INTERRUPT-FUNCTION
#'ABS-MOVE-VIEWPORT
:ARGUMENTS (LIST WIN X Y))))
(SET-MOVE-INFO-ACTION WIN IIF-ID)
(VALUES WIN IIF-ID)))

(DEFUN ABS-MOVE-VIEWPORT (WINDOW X Y) ; Move viewport to absolute locatio·
(MOVE-VIEWPORT WINDOW
:ABSOLUTE-POSITION-XX
.
:ABSOLUTE-POSITION-Y Y))
informational function, GET-VIEWPORT-POSITION, returns the screen
coordinates of a viewport.
An interrupt function that you specify
with SET-MOVE-INFO-ACTION can use GET-VIEWPORT-POSITION to determine
where the viewport has been moved to.

2.4.6.2 Responding to Viewport Resizing - The user can choose the
"Change the size" entry from the Window Options menu to change the
size of a viewport. When the user selects this option, dots appear at
the edges of the viewport's picture area at each corner and at the
midpoint of each edge. The user then selects one of the dots with the
pointer and moves it. Selecting a dot on an edge allows that edge to
be moved while the opposite edge remains anchored. Selecting a dot on
a corner allows that corner to be moved while the opposite corner
remains anchored.
By default, the VAX LISP graphics system responds to viewport res1z1ng
by altering the window into the virtual display in a corresponding
fashion. For example, if the user selects the top edge ·of the
viewport and moves it up, the top edge of the window will be moved up
2-18

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

in the virtual display.by an appropriate amount. The bottom edge of
the window will remain at the same place in the virtual display.
Thus, the scale of what is shown in the viewport does not change, but
· the viewport now shows a greater amount of information.
You can use the SET-RESIZE-ACTION function to specify a different
response
to window resizing or to prevent it from happening.
SET-RESIZE-ACTION accepts a virtual display (or transformation), a
window, and an action as its arguments. The action can be one of the
following:
•

:DEFAULT or NIL, which requests the default response described
above.

•

:DISALLOW, which prevents the window from being resized by the
user.
The Window Options menu for a viewport on which
resizing has been disallowed will show the "Change the size"
option in grey, indicating that the user cannot change the
viewport size.

•

An interrupt function
interrupt function to
resize the window.

identifier (iif-id), specifying an
be executed when the user attempts to

If you specify an interrupt function to execute when a window is
resized, the interrupt function receives eight arguments from the
graphics system. These are:
the new screen coordinates of the
lower-left corner of the viewporti the new width and height (in
centimeters) of the viewport; and the new location (in world or
transformation coordinates) of the lower-left and upper-right corners
of the window. The window location is given in the form xl yl x2 y2.
The coordinate system (world or transformation) depe~ds on whether you
supplied a virtual display or a transformation as the first argument
to SET-RESIZE-ACTION.

you have specified an interrupt function as the response to window
0 Ifresizing,
the graphics system does not automatically resize the
viewport and window. If you want the viewport and window resized, you
can use the RESIZE-WINDOW function in your interrupt function to
perform that action. For example, you could define your interrupt
function as follows:
(DEFUN RESIZE-ACTION (NEW-SCREEN-X NEW-SCREEN-Y
NEW-WIDTH NEW-HEIGHT
Xl Yl X2 Y2
WINDOW)
; Application-specific code

(RESIZE-WINDOW NIL WINDOW NEW-SCREEN-X NEW-SCREEN-Y
NEW-WIDTH NEW-HEIGHT Xl Y1 X2 Y2))

2-19
·-·-------------------------------------------

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

In this example, the interrupt function RESIZE-ACTION is invoked when
a particular window is resized. The function performs some processing
in response to the resizing, then calls RESIZE-WINDOW to actually
change the size of the viewport and window. Note that the eight
arguments passed to the interrupt function by the graphics system
correspond to the third through tenth arguments to RESIZE-WINDOW.
The function RESIZE-ACTION in the
follows:

example

above

might

used

(LET ((RESIZE-IIF (INSTATE-INTERRUPT-FUNCTION
#'RESIZE-ACTION
:ARGUMENTS (LIST WINDOW))))
(SET-RESIZE-ACTION DISPLAY WINDOW RESIZE-IIF))

2.4.6.3 Responding to Viewport Deletion - The Window Options menu for
a window that you create has a "Delete" option. For a window you
create from LISP, this option is shown in grey, indicating to the user
that the window cannot be deleted. You may choose to allow the user
to delete the window, and you can specify what action is to be taken
should that occur.
The SET-CLOSE-ACTION function establishes whether or not a particular
window can be deleted by the user, and what happens if the user
attempts to delete it.
The SET-CLOSE-ACTION function takes two
arguments, a window and an action. The action can be one of four
things:
•

:DISALLOW, in which case the user is not allowed to delete the
window. This is the default.

•

:DELETE, in which case the user can delete the window.
The
graphics system will call DELETE-WINDOW on the window when the
user deletes it.

•

:DELETE-DISPLAY, in which case the graphics system will call
the DELETE-DISPLAY function on the window's virtual display
when the user deletes the window.

•

interrupt function identifier (iif-id), specifying an
interrupt function to be executed when the user deletes the
window. If you supply an iif-id, your interrupt function is
responsible for taking appropriate action; the graphics-system
takes no action.

0
2-20

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

0 2.5 TRANSFORMATIONS. INTO VIRTUAL DISPLAYS
Sometimes it is useful to have more than one coordinate system
available in a virtual display. For example, you might want to create
a composite graph showing more than one type of information, such as
horsepower and torque.
To allow you to have multiple coordinate
systems in a virtual display, the VAX LISP graphics system provides
transformations.

A transformation is a LISP object that
you
make
with
the
CREATE-TRANSFORMATION function. You specify a virtual display, bounds
for a new coordinate system in the display, and, optionally, a
rectangle in the existing coordinate system to which you want the new
coordinate system mapped.
You
can
then
use
the
resulting
transformation object in place of the display argument for any
function that requires a virtual display.
Figure 2-10 illustrates
this concept.
(SETF DISP-1 (CREATE-DISPLAY
0.0 o.o 100.0 50.0
20.0 10.0))

1990.0,6000.0 I FORTRANS-11
100.0,50.0 (FOR DISP-11

(CREATE-TRANSFORMATION
DISP-1
1975.0 1000.0
1990.0 6000.0))

ML0·201·86

Q Figure 2-10: Transformations
2.5. 1

Creating and Accessing Transformations

The
CREATE-TRANSFORMATI'ON
.function
creates
transformation
object.
You can assign the
CREATE-TRANSFORMATION to.a symbol:

and
value

returns
returned

a
by

(SETF *TRANS-1* (CREATE-TRANSFORMATION *DISPLAY-1*
0.0 o.o 100.0 350.0
10.0 o.o 40.0 200.0))
You can then use the symbol as an argument to the
that require a virtual display.

numerous

functions

TRANSFORMATIONP function returns T if the value of its argument is
0 The
a transformation object, and NIL otherwise.
2-21

VIRTUAL DISPLAYS, WINDOWS, AND TRANSFORMATIONS

Each transformation has an identification number assigned by the
MicroVMS workstation graphics software.
This number is called the
transformation ID or tr_id. You can use the UIS-ID function to return
this number, should you need it for use with CALL-OUT.

You must retain the value
returned
by
CREATE-TRANSFORMATIONi
otherwise, you have no means of access to the transformation. You
will be unable to draw in it or to delete it.

2.5.2

Deleting a Transformation

Transformations consume system resources. Therefore, you should take
care to delete transformations when you are done with them. The
DELETE-TRANSFORMATION function deletes a transformation:
(DELETE-TRANSFORMATION *TRANS-1*)

The DELETE-TRANSFORMATION function does not delete the display into
which a transformation was mapped, nor 'does it delete or alter any
graphic information or windows that
were
created
using
the
transformation in place of the display argument.

0
2-22

0
CHAPTER 3
GRAPHICS OUTPUT OPERATIONS

This chapter describes the various ways you can cause lines, text, and
other graphic information to appear in windows. The major sections in
this chapter and the subjects they cover are as follows:
•

Section 3.1 describes the display list, the means
graphic information is stored in a virtual display.

which

3.2 describes two families of graphic operations:
• Section
those you specify in the world coordinate system of a virtual
display, and those you specify in the device coordinate system
of a viewport.

Section 3.3 describes the use of attributes and attribute
• blocks,
by means of which you can alter the appearance of
graphic information.

3.1

•

Section 3.4 describes color maps and the use. of color.

•

Section 3.5 describes functions that
shapes.

•

Section 3.6 describes functions that write and position text.

•

Section 3.7 describes segments, which allow you to define
attribute blocks that are local to a group of operations.

•

Section 3.8 describes how to move graphic information
virtual display and erase it from the display.

draw

lines

and

filled

THE DISPLAY LIST

~ach virtual display has a display list.
When it is enabled, the
display list records the graphic operations that have been performed
in that display. The VAX LISP graphics software refers to the display
list when it needs to create or refresh a window, and for certain
3-1

GRAPHICS OUTPUT OPERATIONS

operations that affect the contents of a virtual
erasing or moving material within the display.

display,

such

When you first create a virtual display, its display list is disabled;
that is, the display list does not record graphic operations. If you
wish to use the display list, you must use the ENABLE-DISPLAY-LIST
function to turn the display list on. The display list will then
record graphic operations performed in the virtual display until you
use the DISABLE-DISPLAY-LIST function to turn the display list off
again.
The display list can record only those operations that are performed
in a virtual display or in a transformation mapped into a virtual
display. Device-coordinate operations -- those whose names end in
"-PIXEL" -- work directly in a viewport. These functions never add to
the display list.
There are advantages and disadvantages to using a display list.
The
chief advantage. is that operations .recorded in the display list can be
re-executed (played back) when necessary·~
conversely~ information
present in a viewport but not recorded in the display list will
disappear when the display list is re-executed. The display list is
completely or partially re-executed by the following functions and
user operations:
•
•
•
•

CREATE-WINDOW
MOVE-WINDOW
RESIZE-WINDOW
"Change the size" choice on the Window Options menu

Consequently, information that is not recorded in the display list may
not appear on the screen following one of these functions or
operations. For example, if you draw lines into the virtual display
with the display list disabled, and later create a window over those
lines, the lines will not appear in the corresponding viewport.
The functions MOVE~AREA and ERASE alter
they do not re-execute it.

the

display

list,

although

The chief disadvantage of the display list is overhead. It takes time
to update the display list and virtual memory to contain it. It also
takes time to delete the display list. ·A virtual display whose
display list contains .a large amount of information will take
appreciably longer to delete than a virtual display with no display
list.
A reasonable strategy with regard to the display list is to enable it
when you are performing output operations that must survive the
functions listed previously, and leave it
disabled
otherwise.
Disabling is especially useful for applications such as animation,·
where the output operations are plentiful, -time-critical,
and
temporary.
It may also be possible in some applications to use
3-2

GRAPHICS OUTPUT OPERATIONS

device-coordinate operations (that do not update the display list)
when temporary graphic information is required. Section 3.2 contains
more information on device-coordinate operations.
Information in a display list is encoded in a device-independent
fashion; that is, executing the display list will produce the same
appearance on any display device supported by the graphics software.
However, you do not have any direct access to the display list; your
only means of access is through the functions described in this
manual.
A display list is automatically deleted when you
display.

delete

its

virtual

0 3.2 WORLD-COORDINATE AND DEVICE-COORDINATE OPERATIONS

The VAX LISP graphics system allows you to specify graphic operations
in either of two coordinate systems: the world coordinate system and
the device coordinate system.
(Sections 2.2.1 and 2.2.2 describe
these systems.) For each function that accepts world coordinates to
specify an output location, there is a correspon4ing function that
accepts device coordinates. The latter functions have the same name
as the former with the suffix "-PIXEL" added; for example, PLOT and
PLOT-PIXEL.
Other
important
distinctions
between
world-coordinate
device-coord1nate operatons are the following:

and

All world-coordinate output functions take a
• Arguments.
display object as their first argument;. device-coordinate
operations take a window object._

•

Coordinate data type. World-coordinate output functions take
floating-point
arguments
to
specify
coordinates;
device-coordinate functions take integers.

•

Display list. World-coordinate operations place information
on a virtual display's display list (if it is enabled; see
Section 3.1). This information appears on the screen when you
create a window that includes the area in which you placed the
information.
·
Device-coordinate operations, on the other hand, work directly
in a viewport by affecting the viewport's pixels. They never
affect the display list.

•

Longevity.
Information
created
with
world-coordinate
operations and recorded on the display list survives as long
as the virtual display. The only way to eliminate it is with
the ERASE function.
3-3

------------------------------------------------

GRAPHICS OUTPUT OPERATIONS

Lines and text created with device-coordinate operations can
survive only as long as the viewport survives, and may be
erased if the corresponding window is moved or resized.
•

Device
independence.
World-coordinate
operations
are
inherently device-independent; that is, information stored
using world-coordinate operations will appear the same on any
supported display device.
Device-coordinate operations are
inherently device-dependent, since the size and shape of
pixels influence the appearance of the output. (Se·e Section
2.2.2 for more information on this distinction.)

•

Speed.
World-coordinate operations must transform
their
coordinate arguments through several intermediate steps to
device-dependent coordinates that the display device can use.
Some
of these steps use relatively slow floating-point
arithmetic. World-coordinate operations must also take time
to update the display list if it is enabled.

Device-coordinate operations need only perform a
single
translation of their coordinate arguments, using integer
arithmetic, before they can be displayed; and they never incur
the overhead of updating the display list. Consequently,
device-coordinate
operations
are
faster
than
their
world-coordinate counterparts.
•

Accuracy.
The
floating-point
numbers
used
in
world
coordinates are subject to a slight amount of round-off error.
Furthermore, floating-point coordinates must ultimately be
used to address a pixel, which, by its nature, has integer
coordinates. These factors can result in the lines that are
finally drawn in the viewport being off by a pixel from the
anticipated location.
Device-coordinate
operations,
since
they
use
integer
coordinates to address pixels directly, perform with complete
accuracy up to the resolution limits of the display device.

Q
Q

These comparisons suggest the following
guidelines
for
using
world-coordinate operations and device-coordinate operations. Use
world-coordinate operations when:
J

•

You need the
system.

device

independence

•

You need the permanence of information recorded in
list.

•

You do not know when or where windows will be present
virtual display.

3-4

the

world

coordinate
a

display
in

the

GRAPHICS OUTPUT OPERATIONS

•

You do not have any way to correlate the world coordinates of
your virtual display to the device coordinates of a viewport.

•

Speed is not of prime importance.

•

Accuracy to the pixel level is not of prime importance.

Use device-coordinate operations when:

•

You want to display output in one particular
than in any window mapped into a display.

window,

•

The lines and text you wish to output are temporary
not survive if the window is moved or resized.

•

You are not using the world coordinate system.

•

Speed is important, as in animation.

•

Accuracy to the pixel level is important.

and

rather
need

You can intermix world-coordinate and device-coordinate operations
freely in your programs, and there are some situations where that is
appropriate.

For example, consider a graphics editor program.
Typically, such a
program allows the user to create a line, rectangle, or circle, and
then manipulate it, using the pointer·, until satisfied with its size,
shape, and location.
The user then presses a pointer button to
indicate that this particular figure is finished. In writing such a
program,
you
might
use
device-coordinate operations for all
manipulation of the figure (consisting of alternately drawing elements
and then erasing them), and then use world-coordinate operations to
draw the finished figure and record it on the display list.
This
scheme would allow quick and efficient figure manipulation, yet still
record the final figure permanently.

3.3

ATTRIBUTES AND ATTRIBUTE BLOCKS

All functions that can draw lines or write text take an attribute
block specifier as their second argument.
The attribute block
specifier, an integer from O through 255, tells the graphics system
which attribute block to use with a particular operation.
attribute block is a collection of attributes.
Each attribute
controls some aspect of the visual results of an operation. There is,
for example, an attribute that specifies the width of a line; another
that specifies the font in which text should be written; a third that
specifies whether the results of an operation should be clipped at a
certain rectangle.

3-5

GRAPHICS OUTPUT OPERATIONS

This section is divided in the following way:
•

Section 3.3.1
blocks.

describes

how

modify

and

use

attribute

•

Section 3.3.2 describes the three general categories of
attributes, and dP.scribes attributes that are common to all
output operations in detail.

Sections 3.5 and 3.6 contain descriptions of attributes that relate
exclusively
to line drawing and text operations, respectively.
Section 3.7 describes segments, by· means of which you can create
temporary attribute blocks.

3.3.1

Modifying and Using Attribute Blocks

If you want to alter the appearance of a graphic output operation
for example, if you wish to draw a dashed line instead of a solid line
-- you must first modify an attribute block so that it contains the
desired attribute value, and then give that attribute block as the
second argument to the function that draws the line.
Once you have
modified the attribute block, you can reuse it for any other operation
in that virtual display.
The VAX LISP graphics system provides a default attribute block,
numbered 0, when you create a virtual display. This default attribute
block is the same for all virtual displays. You can read from this
attribute block, but you cannot alter it.
To modify an attribute block, you use the SET-ATTRIBUTE function.
This function takes as arguments a virtual display, an input attribute
block, an output attribute block that is to be modified, an attribute
specifier, and a new value for the specified attribute. The action of
this function is to modify the output attribute block so that it is a
copy of the input attribute block, differing only in the value of the
attribute you specify. Thus, the output attribute block inherits all
the values of the input attribute block, with the exception of the
attribute you specify. You can change the value of only one attribute
with each call to SET-ATTRIBUTE.

When you create a virtual display, all 256 of the display's attribute
blocks are initialized to the values contained in attribute block O,
the default attribute block.
Once the virtual display has been
created, you can modifiy the contents of any of the attribute blocks
execpt attribute block 0. It is convenient to use attribute block O
as the basis for most of the attribute blocks you create, because you
can be sure of its contents.
The following example illustrates how you would modify an attribute
block so that it causes lines to be dashed. Figure 3-1 illustrates
3-6

GRAPHICS OUTPUT OPERATIONS

Q the process schematicaily.
(SET-ATTRIBUTE *DEMO-DISPLAY*
0
; Input attribute block
1
; Output attribute block
:LINE-STYLE :DASHED) ; Attribute and value
Following the execution of this function, any line-drawing function
given attribute block 1 as its second argument draws dashed lines
instead of solid lines.

ATTRIBUTE BLOCK O

....
.•

.•
..•
...
•

ATTRIBUTE BLOCK 1

(SET-ATTRIBUTE
*DEMO-DISPLAY*
0 1
:LINE-STYLE :DASHED)

:LINE-STYLE :SOLID

--------------

•

:LINE-STYLE :DASHED

ML0·202·86

Q Figure 3-1: Modifying an Attribute Block
Since you can only change one attribute value per invocation of
SET-ATTRIBUTE, you must make repeated calls to SET-ATTRIBUTE if you
want to create an attribute block that differs from attribute block O
in more than one attribute value. The following e~ample modifies an
attribute block to specify dashed lines, a new line width, and a
method of closing arcs:

(SET-ATTRIBUTE *DEMO-DISPLAY* 0 2 :LINE-STYLE :DASHED)
(SET-ATTRIBUTE *DEMO-DISPLAY* 2 2 :LINE-WIDTH 2.0)
(SET-ATTRIBUTE *DEMO-DISPLAY* 2 2 :ARC-TYPE :CHORD)
The first call to SET-ATTRIBUTE uses attribute block O as input and
modifies attribute block 2. The last two calls to SET-ATTRIBUTE use
the same block, 2, for both input and output. The result of the three
calls to SET-ATTRIBUTE is an attribute block that differs from
attribute block O in three values.
Section 3.3.2 lists the
block 0.

default

attributes

contained

attribute

Two attributes with the suffix -PIXEL only have an effect during a
d·evice-coordinate operation. You set them by using the SET-ATTRIBUTE
function, but at least one window must be mapped into the display you
specify with SET-ATTRIBUTE.
The values that you establish for the
3-7

GRAPHICS OUTPUT OPERATIONS

-PIXEL attributes affect operations in any window that into the
virtual display, including windows created after the attribute is set.

You can retrieve the value of an attribute in a particular attribute
block with the GET-ATTRIBUTE function. The GET-ATTRIBUTE function
takes a virtual display as its first argument, an attribute block as
its second, and an attribute as its third. It returns the value of
the specified attribute. If you want the value of one of the -PIXEL
attributes, there must be a window mapped into the display.
The GET-ATTRIBUTE-LIST function returns attribute
attribute block in the form of a property list.

3.3.2

values

from

Attributes

Attributes fall into three general categories:
•

Those that only-affect line drawing.
Section 3.5.3.

These are

•

Those that only affect text operations.
in Section 3.6.3.

These

described· in
are

described

Those that affect both line and text operations, or the
• virtual
display as a whole.
These are described in this
section.
Table 3-1 lists all the attributes.
The subsections that follow
describe the attributes that affect both line and text operations.

3.3.2.1 :BACKGROUND-INDEX - The :BACKGROUND-INDEX attribute controls
the color that is used for background parts of a graphic object.
Examples of background parts are the spaces between the dots in a
dotted line, the area surrounding and contained by letters in a text
string, and the parts of a fill pattern that are not normally visible
against the background. The value of the :BACKGROUND-INDEX attribute
is an integer that is an index into a color map (see Section 3.4). On
a monochrome (non-grey~scale) workstation~ the value must be O or 1,
with O the default.
The effect of the :BACKGROUND-INDEX attribute depends on the setting
of the :WRITING-MODE attribute.
With the default writing mode
(:OVERLAY), background parts of graphic objects are not written.to the
screen, therefore, the color specified by the :BACKGROUND-INDEX
attribute does not appear.
With other writing modes (such as
:REPLACE), the background parts are written to the screen. See·
Section 3.3.2.5 for information on writing modes.·

3-8

GRAPHICS OUTPUT OPERATIONS

c·:i

Table 3-1:
Name

Possible Values

Default

Cat.

Description

:ARC-TYPE

:CHORD
:OPEN
:PIE

:OPEN

Line

Specifies whether an arc Is left open, closed
by a chord, or made Into a pie segment

:BACKGROUNDINDEX

O or 1 (for

Both

Designates an entry in the display's color
map to use for background parts of output

:CHARACTERSPACING

List of two single
floats

(0.0 0.0)

Text

Specifies extra space between text
characters and text lines, respectively,
as proportions of the character width and
height

:CLIP

NIL or list of four
single floats

NIL

Both

Specifies whether output Is limited to a
portion of a display and, If It Is, gives a
world-coordinate rectangle to clip to

:CLIP-PIXEL

NIL or list of four
flxnums

NIL

Both

Specifies whether output is limited to a
portion of a window and, If It Is, gives a
device-coordinate rectangle to clip to

:FILL-PATTERN

NIL or a keyword
shown by SHOWFILL-PATTERNS
function

NIL

Line

Specifies a pattern with which to fill
drawn figures; the :FONT attribute for this
block must specify the font flie UIS$FILL_
PATTERNS

:FONT

Pathname, character
string specifying a
font file or logical
name pointing
to a font file, or
keyword-value list

NIL

Text

Specifies the font to use for text operations

:LEFT-MARGIN

Single float

X coordinate
of left
edge of
virtual
display

text

Specifies the left margin for text operations,
In world coordinates

:LEFT-MARGINPIXEL

Fixnum

Text

Specifies the left margin for text operations
In windows, in device coordinates

:LINE-STYLE

:DASHED
:DASHED-DOTTED
:DOTTED
:SOLID
bit vector

:SOLID

Line

Specifies how lines are drawn

:LINE-WIDTH

Single float or list
In form (n :WORLDCOORDINATES)

1.0

Line

Specifies the width of a line as a multiple of
the default line width, or In world-coordinate
units

:WRITING-INDEX

O or 1 (for

Both

Designates an entry in the display's color
map to use for writing (foreground) parts of
output

Attributes

monochrome system)

(Continued on next page)

3-9

GRAPHICS OUTPUT OPERATIONS

Table 3-1 (cont.)
Name

Possible Values

Default

Cat.

:WAITING-MODE

:COMPLEMENT
:ERASE
:ERASE-NEGATE
:OVERLAY
:OVEALAY-NEGATE
:REPLACE
:AEPLACE-NEGATE
:TRANSPARENT
:COPY

:OVERLAY Both

Description
Specifies how new graphical output Interacts
with background and existing output

3.3.2.2 :CLIP - The :CLIP attribute controls whether or not graphic
output is truncated at the boundaries of a rectangle defined in the
virtual display. By default, output is clipped only by the edges of a
viewport, not in the .virtual .display.
You can create an attribute block whose :CLIP value is a list of four
floating-point
numbers which define two opposite corners of a
world-coordinate rectangle. Any graphic operations that use this
attribute block· restrict the output to the inside of this rectangle.
Note, however, that this clipping rectangle only affects operations
that use this particular attribute block. Simply defining a clipping
rectangle does not cause the results of previous operations to be
clipped, nor does it affect operations that use an attribute block
with no defined clipping rectangle.

l~
'----"

Figure 3-2 illustrates the use of the :CLIP attribute.

(SET-ATTRIBUTE *DISPLAY* 0 2
:CLIP '(2.0 2.0 5.0 4.0))

r---- --- -----,-------..--------. (PLOT *DISPLAY* 0
.---1
I
I

I
I

I
I
I
I

L---

3.0 0.5 3.0 5.5)

5.0,4.0
---,

NOT CLIPPED

I
I
I
I
I
I

(PLOT *DISPLAY* 2
4.0 0.5 4.0 5.5)

___ ..,

CLIPPED

2.0,2.0

L.----- -- ------J-______. . . . .______...
Figure 3-2:

Clipping

3-10

ML0-203-86

GRAPHICS OUTPUT OPERATIONS

3.3.2.3 :CLIP-PIXEL - .The :CLIP-PIXEL attribute controls whether or
not graphic output is clipped (that is, truncated) at the boundaries
of a rectangle defined in the viewport. By default, output is clipped
only by the edges of a viewport.
You can create an attribute block whose :CLIP-PIXEL value is a list of
four integers which define two-opposite corners of a device-coordinate
rectangle. Graphic operations that use this attribute block will clip
the output at the edges of this rectangle. Note, however, that this
clipping rectangle only affects operations that. use this particular
attribute block. Simply defining a clipping rectangle does not cause
the results of previous operations to be clipped, nor does it affect
operations that use an attribute block with no defined clipping
rectangle.

0 color
3.3.2.4 :WRITING-INDEX - The :WRITING-INDEX attribute controls the
that is used for the writing parts of a graphic object.
Examples of writing parts are lines, the actual letters in a text
string, and the parts of a fill pattern that are normally visible
against the background.

The value of the :WRITING-INDEX attribute is an integer that is an
index
into
a color map (see Section 3.4).
On a monochrome
(non-grey-scale) workstation, the value must be O or 1, with 1 the
default.

3.3.2.5 :WRITING-MODE - The :WRITING-MODE attribute specifies how
lines, fill patterns, text, and bitmap images ar~ displayed on the
screen if they overlap with information already on the screen.
This
section describes the attribute and its values in general terms.
Later sections describe its specific effects on lines, fill patterns,
text, and bitmap arrays.
Every graphic object has a writing part, the part that you normally
see.
It also has a background part that you normally do not see, but
that is part of the object nonetheless. For example:

•

The writing part of a dotted line con~ists of the
background part is the space between the dots.

•

The writing part of a string of text consists of the actual
text characters.
The background part consists of the area
inside and around the characters, called the character cell
box.

•

The writing part of a fill pattern consists of the lines or
dots that you normally see. The background part consists of
the spaces between the lines or dots.
3-11

dots.

The

GRAPHICS OUTPUT OPERATIONS

•

The writing part of a screen image represented as a bitmap
array consists of those pixels for which the corresponding
element in the array is nonzero. The background part consists
of those pixels for which the corresponding array element is
zero. (See Chapter 4 for information about screen images and
bitmap arrays.)

A graphic object, consisting of writing parts and background parts, is
placed .on the workstation screen by some function.
Before the
operation, any particular point of the screen can contain either the
writing color or the background color. The writing color is the color
in which lines and text are normally drawn; the background color is
the color of an empty viewport. For a monochrome display screen with
a light background, the writing color is black and the background
color is white.
The graphic operation deposits the writing color and/or the background
color on the screen. to represent the object. (You can change the
writing and background color by changing the
values
of
the
.... :WRITING-INDEX· and :BACKGROUND-INDEX. ·attributes, respectively.·) The
value of the :.WRITING-MODE attribute for the operation dictates what
happens to pixels that correspond to writing and background parts of
the output. The following list describes each of the nine values of
the :WRITING-MODE attribute:
•

:OVERLAY - Writes the writing color onto the screen to
represent
the writing parts.
Background parts are not
affected; that is, the existing background shows through in
background parts. This is the default.

•

:OVERLAY-NEGATE - Writes the background color onto the screen
to represent the writing parts.
Background areas are not
affected.

•

: COMPLEMENT - In writing parts of .the object, writes the
writing color into areas currently occupied by the background
color, and the background color into areas currently occupied
by the wri~ing color. Bac_kground parts are not affected.

•

:REPLACE - Writes the writing color onto the screen to
represent writing parts, and writes the background color into
background parts of the output.

•

:REPLACE-NEGATE - Writes the background color onto the screen
to represent writing parts, and writes the writing color into
background parts of the output.

•

:ERASE - Writes the background color onto the screen
writing and background parts of the output.

both

•

:ERASE-NEGATE - Writes the writing color onto the
both writing and background parts of the output.

screen

3-12

0
Q

GRAPHICS OUTPUT OPERATIONS

:TRANSPARENT -.Has no effect on the screen.
Operations that
use this attribute do, however, update the display list and
the text position.

:COPY
Copies the bitmap representation of the object
directly to the screen without regard to writing color or
background color. This writing mode is primarily useful for
creating screen images from bitmap arrays (see Chapter 4).

Table 3-2 shows how screen pixels are affected by output operations
using each of the writing modes. The table shows the result when a
pixel of either the writing color or the background color is overlaid
by either the writing part or the background part of the output.

Table 3-2:

Writing Modes

Output pixel
w w B
B
Screen pixel
B
w w B
Mode
:OVERLAY
w w w B
:OVERLAY-NEGATE B
B
w B
:REPLACE
w w B B
:REPLACE-NEGATE B B
w w
:ERASE
B
B
B
B
:ERASE-NEGATE
w w w w
:COMPLEMENT
w B w B
:TRANSPARENT
B
w w B
N/A N/A N/A.N/A
:COPY
Note: W writing B background

Figure 3-3 illustrates the effect of the
line, fill pattern, and text output.

3.4

various

w_ri ting

modes

for

COLOR

A workstation screen can simultaneously display some number of colors.
For a monochrome system, the number is two: black and white. Color
systems may be able to display 16, 256, or more colors simultaneously.

You specify color in an output operation by means of two attributes,
:WRITING-INDEX and :BACKGROUND-INDEX. The values for these attributes
are integers that are indexes into a color map. The color map is a
table that contains the description of a color (or an equivalent
grey-scale intensity level) in each entry. The number of entries is
equal to the number of colors that the system can simultaneously
display. Figure 3-4 shows how an output operation works through an
attribute block and a color map to produce an image on the screen.

3-13

GRAPHICS OUTPUT OPERATIONS

0
Sample
:OVERLAY

•••••••••••••••

Sample
:COMPLEMENT
• • • • • • • • • • • • • • • ,i'ir 1r"ii ii·ir·ir • II' ii'ir'II' •ir·ir·ii' •

:::::::::::::::::::::::::::::::::::::::::=:::::::::::::::::::.·

Sample
:REPLACE

:REP LAC E-N EGAT E

0
:ERASE

:ERASE-NEGATE
ML0-204-86

Figure 3-3:

Writing Modes

3-14

GRAPHICS OUTPUT OPERATIONS

(PLOT *DISPLAY* 2 ...

•
•
•
BACKGROUND
PARTS

WRITING

INDEX O
R=l.O
G=l.O
B=l.O

:BACKGROUNDINDEX

0
:WRITING-INDEX

INDEX 1
R=O.O
G=O.O
B=O.O

PARTS

:WRITING-MODE
:REPLACE

•
•
•
ATTRIBUTE BLOCK

COLOR MAP

PART OF "DISPLAY"

Figure 3-4:

SCREEN

ML0·205·86

Writing Through the Color Map

A workstation system comes with a standard color map built in.
Two
functions, GET-WS-COLOR and GET-WS-INTENSITY, return information about
this color map. Each function takes as arguments a display and an
index
into
the color map.
GET-WS-COLOR returns three values
corresponding to the red, green, and blue components of the color in
that entry.
GET-WS-INTENSITY returns a single floating-point number
that is the equivalent grey-scale intensity for the entry.
Both GET-WS-COLOR and GET-WS-INTENSITY take an optional
window
argument.
When you supply this argument, the return values reflect
the actual realized color or intensity for the specific device on
which the window was created. This difference reflects the fact that
display devices cannot always reproduce exactly the
color
or
grey-scale intensity that is specified in the color map.
For example, imagine that an entry in a color map has an intensity
value of 0.7. If a window is created on a monochrome (non-grey-scale)
monitor, an object written to the window through this entry cannot
actually be displayed in the shade of grey requested. The display
device makes its best approximation, which is 1.0, or white.
Using
GET-WS-INTENSITY with this window specified returns a value of 1.0,
even though the value in the color map is 0.7.

Each virtual display has its own color map, which controls the colors
of objects in that display.
Initially, a display's color map is
identical to the workstation standard color map.
You can change
entries in the display's color map by means of the SET-COLOR and
SET-INTENSITY functions. Each takes a virtual display and an index
into the color map as its first two arguments.
3-15

GRAPHICS OUTPUT OPERATIONS

You specify a color with SET-COLOR by means of three additional
arguments, one each for the red, green, and blue components of the
color. These values are floating-point numbers between 0.0 and 1.0,
inclusive.

SET-INTENSITY takes only one additional argument, the value of the
equivalent grey-scale intensity.
This is a floating-point number
between 0.0 and 1.0. SET-INTENSITY sets the three colors in the color
map entry to produce a grey-scale level corresponding to the value you
specify.
When you change an entry in the color map, there is no immediate
change on the screen. Objects drawn using that entry after the change
has been made will show the effect of the new value.
Also, anything
that causes the display list to be re-executed (such as resizing the
viewport) will change the appearance of objects drawn using an altered
color map entry, whether they were drawn before or after the change
was made to the color map.

Tp~_b~ckground and parts of the border~ of a viewport are drawn using
values stored in the color map. Therefore, alterations to entries O
and 1 in a virtual display•s color map can alter the appearance of
viewports mapped to the display. The changes do not become apparent
in existing windows unless the display list is re-executed.
You can get information about a display•s color map with the GET-COLOR
and GET-INTENSITY functions. These are equivalent to GET-WS-COLOR and
GET-WS-INTENSITY, except that they return information about the
display's color map rather than the standard color map.
Both
functions take an optional window argument.
Without the window
argument, they return values from the color map. With the window
argument, they return the realized values from the device on which the
window was created.

3.5

DRAWING LINES AND SHAPES

This section describes functions and related attributes that allow you
to draw lines and filled-shapes in virtual displays and viewports.
The section is organized as follows:
•

Section 3.5.1 describes functions that draw points, lines, and
series of connected lines.

•

Section 3.5.2 describes functions that draw circles, ellipses,
and arcs.

•

Section 3.5.3 describes attributes that are
functions.

used

with

these

0
3-16

GRAPHICS OUTPUT OPERATIONS

3.5.1

Points and Lines

PLOT family of functions draws single points, lines between two
0 The
points, and two or more connected lines.
There are four PLOT
functions:

PLOT draws a point, a line, or up to 124 connected lines in
virtual display.

•

PLOT-PIXEL draws a point, a line, or up to 124 connected lines
in a viewport.

•

PLOT-ARRAY draws up to 65,534 connected lines in a virtual
display, taking coordinates from two vectors of single-float
numbers.

•

PLOT-ARRAY-PIXEL draws up to 65,534 connected lines in
viewport, taking coordinates from two vectors of integers.

The basic difference between the PLOT functions and the PLOT-ARRAY
functions is in the way you specify coordinates to them. The PLOT
functions accept coordinates as pairs of arguments.
The first two
coordinate arguments are required; if you give just these arguments,
the PLOT functions plot a single point at the specified location. You
can supply up to 124 additional coordinate pairs. The following
example illustrates the PLOT function:
(PLOT *DISPLAY* 0 1.0 1.0)
(PLOT *DISPLAY* 0 1.0 1.0 3.0 1.0)
(PLOT *DISPLAY* 0 1.0 1.0 3.0 1.0
3.0 2.0)
(PLOT *DISPLAY* 0 1.0 1.0 3.0 1.0
3.0 2.0 1.0 2.0 1.0 1.0)

; Plot a point
; Plot a horizontal line
; Plot two lines
; Plot a rectangle

The PLOT-ARRAY functions accept coordinate arguments in the form of
two specialized one-dimensional arrays. For PLOT-ARRAY, the elements
must be of type SINGLE-FLOAT; for PLOT-ARRAY-PIXEL, the elements must
be of type (SIGNED-BYTE 32).
The elements of the first vector
represent the x coordinates for each point; the elements of the second
vector represent the Y coordinates. Thus, to duplicate the rectangle
drawn by the final PLOT function in the preceding example, you could
use this function:
(PLOT-ARRAY
*DISPLAY* 0
(MAKE-ARRAY 5 :ELEMENT-TYPE 'SINGLE-FLOAT
:INITIAL-CONTENTS '(1.0 3.0 3.0 1.0 1.0))
(MAKE-ARRAY 5 :ELEMENT-TYPE 'SINGLE-FLOAT
:INITIAL-CONTENTS '(1.0 1.0 2.0 2.0 1.0)))

matches up elements from the first vector with elements
from the second vector to form each coordinate pair in succession.
0 PLOT-ARRAY
3-17

GRAPHICS OUTPUT OPERATIONS

The PLOT functions and PLOT-ARRAY functions each have strengths and
weaknesses;
thus, PLOT may be appropriate in situations where
PLOT-ARRAY is not, and vice versa. The following suggests when to use
one or the other:
•

PLOT is more convenient for casual line drawing and in
situations where a program draws an indeterminate number of
lines. For example, a recursively-defined function would use
PLOT to draw one line at a time, since it cannot know in
advance how many lines to draw or where to draw them.

•

PLOT-ARRAY may be more convenient and efficient for drawing a
series of similar figures, since the array arguments can be
reused. You can define functions that operate on the vector
elements to shift or resize the figures they represent.

•

The limited number of lines that PLOT can draw with one call
puts a limit on the complexity of a filled shape that you can.
creat.e using PLOT_.

Note that there is no concept of a "current position" when you use the
PLOT functions.
That is, you must explicitly specify the beginning
location for each operation; the graphics system does not "remember"
where the last point was plotted. (Text output does have a "current
position.") Programs that need to retain the position of the last
point plotted must do so explicitly.
Depending on the attributes you specify, lines drawn by the
functions may be solid, dotted, dashed, or dashed-dotted.
Section 3.5.3.3.) You can also specify that lines be heavier
normal. (See Section 3.5.3.4.i

PLOT
(See
than

If an attribute block specifies a fill pattern (see Section 3.5.3.2),
PLOT does not draw lines at all. Instead, it fills in the shape that
the lines would have defined had they been drawn. To draw a filled
shape with an outline, call PLOT twice with identical coordinate
arguments but different attribute blocks.
One attribute
block
specifies a fill pattern and thus draws the filling; the other does
not and thus draws the outline.

To fill in a shape drawn with the PLOT or PLOT-ARRAY functions, the
graphics system first makes an imaginary line between the first point
that was plotted and the last point that was plotted, unless they
coincide.
Then, any area(s) enclosed by the lines drawn by the
function and the imaginary line between the beginning and end points
is filled.
Figure 3-5 illustrates three shapes that have been drawn
with lines, then filled.
All of these figures illustrate the
imaginary line between the beginning and end points.

0
3-18

GRAPHICS OUTPUT OPERATIONS

0
ML0·206·B6

Figure 3-5:

3.5.2

Filling Plotted Shapes

Circles, Ellipses, and Arcs

Four functions allow you to draw ci~cles, ellipses, and arcs. You can
use attributes with these functions to create pie segments and filled
circles and wedges.
•

CIRCLE draws a circle or a portion of a circle
display.

•

CIRCLE-PIXEL draws a circle or a portion
viewport.

ELLIPSE draws an ellipse or a
virtual display.

•

ELLIPSE-PIXEL draws an ellipse or a portion of an ellipse in a
viewport.

portion

of
of

in
a

virtual

circle

ellipse

These functions are very similar. Each one takes the coordinates of a
center position. The CIRCLE functions take a single radius argument,
whereas the ELLIPSE functions take a horizontal radius and a vertical
radius.

0 All four of the functions take optional arguments that specify
starting and ending positions in radians. These arguments, if given,
define an arc which starts at the starting position and proceeds
counterclockwise to the ending position. If the starting position
argument is NIL or omitted, it defaults to 0.0.
If the ending
position argument is NIL or omitted, it defaults to 2*PI. Figure 3-6
illustrates this angular coordinate system and shows several examples
of arcs.
You can use the :ARC-TYPE attribute (see Section 3.5.3.1) to specify
how an arc should be closed. If you specify :OPEN (the default), the
arc is left open. You can also use :PIE to draw a pie segment, or
:CHORD to draw a line between the endpoints of the arc.

0
3-19

GRAPHICS OUTPUT OPERATIONS

0
0

•

ANGULAR COORDINATE
SYSTEM

0.0,0.0

(CIRCLE DISPLAY O 0.0 0.0 1.0
(/ PI 2) PI)

(CIRCLE DISPLAY O 0.0 0.0 1.0
PI(/ PI 2))

0.0,0.0

(CIRCLE DISPLAY O 0.0 0.0 1.0
NIL PI)

(CIRCLE DISPLAY O 0.0 0.0 1.0
PI)
ML0·207·86

0
Figure 3-6:

Drawing Arcs

If you have specified a fill pattern (see Section 3.5.3.2), the lines
that make up the circle, ellipse, or arc are not drawn. The shape is
filled in only if it is a complete circle or ellipse, or if the arc
type is :PIE or :CHORD. This means that if you draw an arc with an
attribute block that has the default arc type (:OPEN) and a fill
pattern in effect, nothing appears on the screen.

3.5.3

Attributes Used with Line-Drawing Functions

The attributes described in this section are useful only with the
functions that draw lines or create shapes. Their values are ignored
by other output functions.

3.5.3.1 :ARC-TYPB - The :ARC-TYPE attribute specifies how a portion
of a circle or an ellipse should be closed. There are three possible
values:
3-20

GRAPHICS OUTPUT OPERATIONS

•

:OPEN, specifying that the arc not be closed at all.
the default value.

This

•

:CHORD, specifying that the endpoints of the arc be joined
a straight line.

•

:PIE, specifying that straight lines be drawn from the
endpoints of the arc to the center of the circle or ellipse.

An arc that is drawn with the :OPEN attribute cannot be filled.
Arcs
drawn with the :CHORD or :PIE attribute are filled in the area
enclosed by the arc and its closure.

3.5.3.2 :FILL-PATTERN - The :FILL-PATTERN attribute specifies two
things:
first, that figures be filled, and second, the pattern with
which to fill them. The values you can give for :FILL-PATTERN are
either NIL (requesting the default behavior, which is that figures are
not filled), or any of a number of keywords representing specific fill
patterns.
The SHOW-FILL-PATTERNS function displays all the fill
patterns available and the keyword that corresponds to each one.
By default, figures are drawn with lines and are not filled.
If you
specify a fill pattern keyword for the :FILL-PATTERN attribute, you
first of all request that figures not be drawn with lines.
Instead,
the shapes specified by output operations are filled with the pattern
you specify.
·
To be filled, a figure must meet the following criteria:
be created with a single function ca.11. For example,
• aIt must
rectangle that you draw with a single call to PLOT can be

filled, but an identical rectangle drawn
calls to PLOT cannot be.

with

four

separate

If it is an arc, it must be drawn with an :ARC-TYPE attribute
• of
:CHORD or :PIE.
(Full circles and ellipses are filled
regardless of the :ARC-TYPE value.)
Figures drawn with any of the PLOT functions are filled by making an
imaginary line between the first and last points plotted, then filling
any area(s) enclosed by the lines that the function created and the
imaginary line.

To modify an attribute block to result in a fill pattern, you must
specify both the :FONT and the :FILL-PATTERN attributes.
Fill
patterns are stored as character glyphs in a font file.
The system
logical name UIS$FILL_PATTERNS points to this file.
Therefore,
modifying an attribute block to specify a fill pattern is a two-step
process:

3-21

GRAPHICS OUTPUT OPERATIONS

Create an attribute block whose :FONT attribute is the string
"UIS$FILL_PATTERNS".

Modify the same attribute block so that its :FILL-PATTERN
attribute is a keyword associated with one of the patterns.

For example:
(SET-ATTRIBUTE *DISPLAY* 0 1 :FONT "UIS$FILL_PATTERNS")
(SET-ATTRIBUTE *DISPLAY* 1 1 :FILL-PATTERN :GRID4)
Figures drawn with attribute block·l after execution of these two
functions will be filled with a grid pattern. Note, however, that you
can no longer use attribute block 1 to write text, because its :FONT
attribute does not point to a font file that contains legible
characters.
(See Section 3.6.3.2 for information on the :FONT
attribute.)
block

3.5.3.3 :LINE-STYLE - The
:LINE-STYLE
attribute
specifies
the
appearance of lines drawn on the screen. It can have one of four
keyword values: :SOLID, :DOTTED, :DASHED, and :DASHED-DOTTED. :SOLID
is the default. Figure 3-7 illustrates the appearance of each of the
standard line styles.

You can turn off filling and reset line drawing in an attribute
by specifying a value of NIL for the :FILL-PATTERN attribute.·

:SOLID

: DOTTED
:DASHED
: DASHED-DOTTED
ML0·208-B6

Figure 3-7:

Line Styles

You can also supply the value of :LINE-STYLE as a bit vector, using
bits with values of 1 and O to specify the writing color and
background color, respectively. The bit vector must be 32 or fewer
bits in length. If it is less than 32 bits long, SET-ATTRIBUTE fills
it out to a length of 32 by replicating it. For example:
{SET-ATTRIBUTE *DISPLAY* 0 1 :LINE-STYLE #*11111100)
3-22

GRAPHICS OUTPUT OPERATIONS

Since the, length of this bit vector divides exactly into 32, it will
be replicated exactly four times and will produce an even dashed line.
If the length of the bit vector does not exactly divide into 32, it
will be only partially replicated at the end and will not produce an
even pattern.

3.5.3.4 :LINE-WIDTH - The :LINE-WIDTH attribute specifies the width
(weight) of lines drawn on the screen.
Its value is normally a
floating-point number that expresses line width as a multiple of the
default value, which is 1.0. For example, to draw a line three times
heavier than normal, use an attribute block whose :LINE-WIDTH value is
3.0.

You can also supply a value
for
:LINE-WIDTH
in
the
form
'(n :WORLD-COORDINATES), where n is a floating-point number specifying
the width of the line in world-coordinate units.
Line width is
subject to scaling when a line drawn with this attribute block is
displayed in a viewport.
The GET-ATTRIBUTE function
used
with
:LINE-WIDTH
returns
a
floating-point number representing the line width, unless you have
specified world coordinate line width. In this case, GET-ATTRIBUTE
returns the list (n :WORLD-COORDINATES).

3.6

TEXT OPERATIONS

The VAX LISP graphics system provides functions that write text into a
virtual display or viewport, and that allow precise control over the
appearance and position of the text on the screen.
This section
describes these facilities. The section is divided as follows:

3.6.1

to particular
describes the

•

Section 3.6.1 shows how to write text strings
locations in the display or viewport and
properties of text and text operations.

•

Section 3.6.2 describes functions that allow more
positioning of text and measurement of text strings.

•

Section 3.6.3 describes the
text.

various

attributes

that

flexible
affect

Writing Text

~wo functions, TEXT and TEXT-PIXEL, write text. TEXT writes text into
a virtual display; TEXT-PIXEL writes text directly into a viewport.
Optional arguments to both functions allow you to specify the positi9n
of the text in the display or viewport. Attribute values in the
3-23

GRAPHICS OUTPUT OPERATIONS

attribute block you specify
appearance of the text.

with

the

TEXT

functions

affect

the

The first argument to TEXT is a virtual display.
The TEXT function
places the text in the specified virtual display and updates the
display list, if the display list is enabled.

The first argument to TEXT-PIXEL is a window. The TEXT-PIXEL function
places the text in the viewport associated with the window. As with
the other device-coordinate functions, TEXT-PIXEL does not update the
display list.
The second argument to both TEXT and TEXT-PIXEL is an attribute block.
The values of the following attributes affect the appearance of the
text:

• ~!~~ (see Section 3.6.3) determines the size and style of the Q
e

:WRITING-MODE (see Section 3.3.2.5) determines
characters of the text are written on the~screen

•

:CHARACTER-SPACING (see Section 3.6.3) indicates whether extra
space is added between characters and lines

how

the

A fourth
attribute,
:LEFT-MARGIN
(and
its
device-coordinate
counterpart, :LEFT-MARGIN-PIXEL), sets up a left margin for text
operations. This attribute is discussed in Section 3.6.2.

The third argument to each of the TEXT functions is the text that you
wish to write, in the form of a single character or a character
string. The string can be a literal quoted string:
(TEXT *DISPLAY* 0 "This is your life!")
Or, you can use any form that evaluates to a character string:
(TEXT *DISP* 0 (FORMAT NIL "This is your life, -A" NAME))

There are several ways to position text in the display or viewport.
The TEXT functions take two optional arguments that specify the
coordinates of the beginning position for the text.
If you do not
supply these arguments, the output begins at the end of the last text
that was output. So, for example, the two function calls in the
following example would output a single line of text:
(TEXT *DISP* 0 "Mary had a" 0.0 3.0)
(TEXT *DISP* 0 "little lamb.")
The first function call begins a line of text at (0.0,3.0) in world
coordinate space.
The second function call appends its text to the·
end of the line created by the first. Any subsequent call. to TEXT
will append text to this line, unless a different position is
3-24

GRAPHICS OUTPUT OPERATIONS

specified explicitly in the call to TEXT or the current text position
is
altered
in some other way.
Section 3.6.2 describes text
positioning in more detail.
If you specify a position with TEXT, you are indicating where the
upper left corner of the first character should be placed (the
"aligned position"). There are other ways of specifying position;
they are described in Section 3.6.2.
The appearance of the text on the screen depends on two attributes:
the font and the writing mode. A font is a particular size and style
of type. The VAX LISP graphics system provides a number of fonts;
they differ from the default font in both size and style. Section
3.6.3.2 describes how to use the :FONT attribute.

Text of a given font always appears the same size on the screen, even
if scaling has taken place between the window and the viewport. For
example, if you have a default window and viewport displaying some
lines and text, and another window and viewport that magnify a portion
of the display, text will be the same size in both viewports, although
the lines are magnified in the second. Figure 3-8 illustrates this.

!Text in a boxl

Text in a box

ML0·209·86

Q Figure 3-8: Text and Scaling

The writing mode attribute (described in Section 3.3.2.2) has four
values that are particularly useful for text. They are :REPLACE,
:REPLACE-NEGATE, :ERASE, and :ERASE-NEGATE. Each text character has a
character cell around it; an imaginary rectangle that outlines it.
For a line of text, the character cells form a long horizontal· box.
The :REPLACE writing mode causes the entire character cell box to be
placed on the screen, not just the characters themselves. If the text
is entirely over the background, there is no difference between the
:REPLACE and :OVERLAY writing modes;
either
will
result
in
writing-color letters on a featureless background. If, however, the
text crosses a line or an area of fill, the background-color
character-cell box provided by :REPLACE guarantees that the text will
be visible. The :REPLACE-NEGATE writing mode is similar, except that
it writes background-color text in a writing-color box.
3-25

GRAPHICS OUTPUT OPERATIONS

The :ERASE and :ERASE-NEGATE writing modes are similar to :REPLACE and
:REPLACE-NEGATE, except that they write only the character-cell box
that the text would occupy; they do not write text. You can use them
to erase a line of text that you previously wrote.

Figure 3-3 illustrates the effect of the various writing modes with
text.
Note that :OVERLAY can cause text to disappear against a
writing-color
background.
The
writing
modes
:OVERLAY,
:OVERLAY-NEGATE,
and :COMPLEMENT do not work well over a textured background.

3.6.2 _Positioning and Measuring Text

A number of VAX LISP graphics functions allow you to
precisely
within a virtual display or. viewport.
describes how to use them.

position text
This section

3.6.2.1 The Text Position and Text Reference Points - Each virtual
display maintains a text position.
This is the position in the
virtual display at which the next text output operation will begin. A
separate device-coordinate text position is also maintained for all
windows into a virtual display.

0
Q

To position text on the screen, you must know the various ways in
which you can affect the text position. You must also know how the
text position relates to the image of text on the screen; that is,
which point in the text image corresponds to the text position.
Figure 3-9 illustrates a text image with the various reference points
and lines pointed out. Each of these is discussed in detail in the
following paragraphs.
OFFSET BETWEEN
ALIGNED POSITION
AND TEXT POSITION

....u.,

ALIGNED POSITION
AFTER OPERATION

--------. -)Graphics __ :tex:t~ALIGNED POSITION

..)

(

TEXT POSITION

TEXT POSITION
AFTER OPERATION
ML0·210.86

Figure 3-9:

Text Reference Points

The text baseline is an imaginary line upon which the characters sit •.
Some letters, such as j and q, have descenders that dip below the
baseline.
3-26

GRAPHICS OUTPUT OPERATIONS

A call to TEXT that does not specify a

starting position explicitly
will place the text image so that the left end of the baseline
coincides with the virtual display's text position.
Following the
execution of the function, the text position will be at the right end
of the baseline. This means that you can use fonts of different sizes
in successive calls to TEXT and know that they will all line up on a
common baseline. Figure 3-10 illustrates this.

- _ .Fee._ r: ier _

Eoe, ___ and __ Euml ___ .
ML0-211-86

Figure 3-10:

Using Different Fonts on the Same Line

you give an explicit text position in a call to TEXT, you are
0 When
specifying the aligned position at which the text should begin. The

aligned position is at the upper left corner of the text image's
character-cell box.
Since the aligned position is offset vertically
from the text position by a portion of the 'text's height, aligned
position can only be determined with reference to a particular font.
Therefore, an aligned position can only be specified with reference to
an attribute block.
The value of the attribute block's :FONT
attribute is used to determine the aligned position.

3.6.2.2 Changing the Text Position - There are several ways to change
the text position. Some of them are implicit, others are explicit.

In all cases, it is important to note that a virtual display's text
position
is
separate from the device-coordinate text position
maintained for windows into the virtual display.
A world-coordinate
operation that affects the text position in a display does not affect
the text position for device-coordinate operations on windows into
that display.
Similarly, a device-coordinate operation that affects
the window text position does not affect the virtual display's text
position.
(However, changing the device-coordinate text position in
one window does affect the device-coordinate text position in all
other windows that map into that virtual display.)
A call to TEXT implicitly changes the virtual display's text position
to the right end of the text image's baseline. A call to TEXT-PIXEL
changes the device-coordinate text position in the same way.
Thus,
successive calls to TEXT or to TEXT-PIXEL will concatenate the output
from left to right on a common baseline.
A call to the NEW-TEXT-LINE function changes the virtual display's
text position to the left margin specified in the attribute block
supplied in the function call.
NEW-TEXT-LINE also moves the text
3-27

--------- · - - - - - -

GRAPHICS OUTPUT OPERATIONS

position down from its previous setting by an amount that depends on
the font specified in the attribute block.
Thus, NEW-TEXT-LINE is
like the RETURN key on a terminal. NEW-TEXT-LINE-PIXEL operates
similarly in a viewport.

A call to the SET-POSITION function sets the virtual display's text
position to an absolute world-coordinate location. The first argument
to SET-POSITION is the display; the second and third arguments are the
X and Y coordinates. The Y coordinate establishes the baseline for
the next text operation, and the X coordinate establishes the left
edge
of
the output.
The SET-POSITION-PIXEL function operates
similarly in a viewport.
The SET-ALIGNED-POSITION function also sets the virtual display's text
position, but not directly. With SET-ALIGNED-POSITION, you specify
where you want the aligned position (the upper left corner) of the
next text output to fall. You must supply an attribute block with
SET-ALIGNED-POSITION. The function calculates the text position from
the aligned position you specify and the size of the font. Figure
3-11 illustrates this process.

ALIGNED POSITION
SPECIFIED AT
0
2.0,3.0
}
•
/
TEXT POSITION
SETAT2.0,2.17

(SET-ATTRIBUTE *DISPLAY*
0 3 :FONT "FONT_6")
OFFSET BETWEEN
ALIGNED POSITION
AND BASELINE
FOR "FONT_6",
SCALED TO WORLD
COORDINATE UNITS

(SET-ALIGNED-POSITION
*DISPLAY* 3 2.0 3.0)

ML0·212·86

Figure 3-11:

Setting the Aligned Position

You must be sure to use the same font that you specified with
SET-ALIGNED-POSITION in the call to TEXT that is to use the aligned
position. If you use a different font, the aligned position of the
output may be above or below the position you specified with
SET-ALIGNED-POSITION.

The
SET-ALIGNED-POSITION-PIXEL
function
is
similar
to
SET-ALIGNED-POSITION except that it operates in a viewport instead of
a virtual display.
All of the SET- functions mentioned in this section have corresponding
GET- functions.
These GET- functions return the location either of
the text position or of the aligned text position with respect· to a
specified font.

0
3-28

GRAPHICS OUTPUT OPERATIONS

3.6.2.3 Measuring Text - The MEASURE-TEXT function measures a string
of text in a specified font, and returns the width and height of the
text string's character-cell box in world-coordinate units.
Since
MEASURE-TEXT does not actually place any text on the screen, it allows
you to preview the text and then place it according to its size. This
capability is useful in the following situations:
•

You can use MEASURE-TEXT to determine if a text string will
fit between the text position and a right-hand limit that you
have established. If the text string will not fit,. you can
call NEW-TEXT-LINE to start a new line.

•

If you want to center an arbitrary line of text, you can use
the width value returned by MEASURE-TEXT as shown in the
following example:
(DEFUN CENTER-TEXT (DISPLAY ATT-BLOCK TXT X Y)
(TEXT DISPLAY ATT-BLOCK TXT
(- X (/ (MEASURE-TEXT
DISPLAY ATT-BLOCK TXT)
2. 0))
Y))

The function CENTER-TEXT accepts the same arguments as TEXT,
but centers the text string on the specified x position
instead of beginning it there. You could define a similar
function to position the right edge of a text string at a
specified point.
If you want to write a string of text with a box around it,
• you
can use the values returned by MEASURE-TEXT to determine
the dimensions of the box.
this.

Example 3-1 shows one

way

Q Example 3-1: Boxed Text
(DEFUN BOXED-TEXT (DISPLAY ATT-BLOCK TXT X Y)
(MULTIPLE-VALUE-BIND (W H) (MEASURE-TEXT DISPLAY ATT-BLOCK TXT)
(TEXT DISPLAY ATT-BLOCK TXT X Y)
(RECTANGLE DISPLAY OX Y (+ X W) (- Y H))))
(DEFUN RECTANGLE (DISPLAY ATT-BLOCK X1 Y1 X2 Y2)
(PLOT DISPLAY ATT-BLOCK X1 Y1 X2 Y1 X2 Y2 X1 Y2 X1 Y1))

The MEASURE-TEXT-PIXEL function is similar to MEASURE-TEXT, except
that it returns the dimensions of the text string in terms of device
coordinates instead of world coordinates.

3-29

GRAPHICS OUTPUT OPERATIONS

3.6.3

Attributes that Affect Text

This section describes how to use the various attributes that affect
text operations only.
See Section 3.3.2 for a description of
attributes that affect both text and graphic output.

3.6.3.1 :CHARACTER-SPACING - The
:CHARACTER-SPACING
attribute
determines how much (if any) extra space should be left between
characters in a string and between lines. You can add extra space
between characters if you want· to create an airy effect or fill a
string of text out to a larger size.
The spacing between lines is used by
the
NEW-TEXT-LINE
and
NEW-TEXT-LINE-PIXEL functions.
These functions add the interline
space indicated by :CHARACTER-SPACING to the space indicated by the
height of the font.
The value you specify for the :CHARACTER-SPACING attribute is a list
of two floating-point numbers. The first number is the extra space to
leave between characters. It is expressed as a proportion of the
width of a character. The second number is the extra space to leave
between lines, expressed as a proportion of the font height.
The
default for both is 0.0, indicating no extra space.

0
3.6.3.2 :FONT - The :FONT attribute determines the font in which text
is written.
A font is a collection of graphic characters in a
particular size and style. The size of the font is its height in some
physical unit, such as points (a point is equal to 1/72 of an inch) or·
centimeters. The style is the appearance of the font:
for example,
italic, bold, or roman.
In the VAX LISP graphics system, fonts are stored in files, one font
to a file. The files are in a directory for which there is a logical
name, SYS$FONT. Each file has a coded name that indicates the
contents of the font, and the type .FNT. The file name is divided
into several fields, with each field indicating one characteristic of
the font.
The SHOW-FONTS function displays all the available fonts
and shows the value .for each field that that differs from the default
value.

You can specify a value for the :FONT attribute in one of two ways:
•

You can use a pathname to the font file, or a character ·string
that contains a file name specification or logical name
pointing to the font file.

•

You can also use a list of keyword-value. pairs, where each
keyword is one of the field-specification keywords displayed
3-30

GRAPHICS OUTPUT OPERATIONS

by the SHOW-FONTS function and the value is a character string
containing the value of that field for the font you want. If
you do not mention a field, SET-ATTRIBUTE fills in the value
of that field from the default font specification.
As an example of the second method, consider the following example:
(SET-ATTRIBUTE *DISPLAY* 0 1
:FONT '(:TYPE-FAMILY "TERMIN" :SPACING "M"
:TYPE-SIZE "03C" :WEIGHT "P"))
This function sets up a :FONT attribute whose value differs from the
value of the default :FONT attribute in four fields. The rest of the
fields are taken from the default font values.

The values of each field for the default font (the font
attribute block 0) are as follows:
Field

Value

:TYPE-FAMILY
:SPACING
:TYPE-SIZE
:WEIGHT

"TABER0 11
II

specified

I II

03W"
"G"
11

One font file, specified by the system logical name UIS$FILL_PATTERNS,
contains the patterns used to fill in figures. This font file is not
useful for text output. (See Section 3.5.3.2 for information on using
fill patterns.)
You can use the GET-FONT-SIZE function to find out the physical size
of
a
font.
GET-FONT-SIZE returns the width. and height, in
centimeters, of a specified text string in a specified font.
Text
characters are never scaled on the screen; therefore, the size
information returned by GET-FONT-SIZE will always be valid, even if a
viewport is scaled.
You specify the font to GET-FONT-SIZE the same way you specify it to
SET-ATTRIBUTE.
If you supply a keyword-value list, supply only those
field specifiers whose values differ from the default font.

3.6.3.3 :LEFT-MARGIN - The :LEFT-MARGIN attribute sets up a margin to
which the NEW-TEXT-LINE function sets the display's text position.
You specify the :LEFT-MARGIN attribute as a floating-point number,
which indicates an X value in world coordinate space. NEW-TEXT-LINE
function calls that use this attribute block will cause the new line
to start at that horizontal position.
The default value for :LEFT-MARGIN is the left edge of the default
0 window
you specified when you created the virtual display.
3-31

GRAPHICS OUTPUT OPERATIONS

3.6.3.4 :LEFT-MARGIN-PIXEL - The :LEFT-MARGIN-PIXEL attribute sets up
a margin to which the NEW-TEXT-LINE-PIXEL function sets the window
text position. You specify the :LEFT-MARGIN-PIXEL attribute as an
integer, which indicates a horizontal offset from the left edge of the
viewport in device-coordinate units.
NEW-TEXT-LINE-PIXEL function
calls that use this attribute block will cause the new line to start
at that horizontal position in the viewport.
The default value for :LEFT-MARGIN-PIXEL is 0, the left
viewport.

edge

the

The value of :LEFT-MARGIN-PIXEL is completely independent of the value
of :LEFT-MARGIN. Changing the value of one has no effect on the value
of the other. The NEW-TEXT-LINE-PIXEL function uses the value of
:LEFT-MARGIN-PIXEL, and the NEW-TEXT-LINE function uses the value of
:LEFT-MARGIN.

3.7

SEGMENTS·

A segment is a grouping of graphic operations that is delimited by a
call to the BEGIN-SEGMENT function at the beginning and a call to the
END-SEGMENT function at the end.
Within a segment, any modifications that you make to attribute blocks
are temporary. When you begin the segment, you have available all the
attribute blocks that have been modified up to that point. ·within the
segment, you can use the SET-ATTRIBUTE function to modify these
atttribute blocks. At the end ·of the segment, all the work you have
done on attribute blocks is cancelled, and the state of the attribute
blocks returns to what it was before you began the segment. Thus, you
can use segments to ensure that previously-modified attribute blocks
are not ruined. This can be useful in a portion of code that can be
called anywhere in a program and that must set up one or more special
attribute blocks.

Segments may be nested; that is, a segment can contain another
segment.
The inner segment inherits all the attribute blocks of the
outer segment, including any that the outer segment may have modified.
For an example of the use of segments, consider a function called
REVERSE-TEXT that takes ·a virtual display, an attribute block, a text
string, and a coordinate pair. It is just like the TEXT function
except that it attempts to output the text in the reverse of whatever
the attribute block calls for. Example 3-2 shows how such a function
might be defined.

0
3-32

GRAPHICS OUTPUT OPERATIONS

,,
;

Q Example 3-2: Reversing Text Using Segments

(DEFUN REVERSE-TEXT (DAB STR X Y)
(BEGIN-SEGMENT D)
(LET ( (MODE
,
(GET-ATTRIBUTE
DAB :WRITING-MODE)))
(SET-ATTRIBUTE
DAB 1 :WRITING-MODE
(CASE MODE
(:OVERLAY :OVERLAY-NEGATE)
(:OVERLAY-NEGATE :OVERLAY)
(:REPLACE :REPLACE-NEGATE)
(:REPLACE-NEGATE :REPLACE)
(:ERASE :ERASE-NEGATE)
(:ERASE-NEGATE :ERASE)
(OTHERWISE MODE))))
(TEXT D 1 STR X Y)
( END-SEGMENT D) )

Get AB's writing mode
; Modify block 1
; Copy block AB except
; for new writing mode

; Output reversed text

The function REVERSE-TEXT in Example 3-2 uses the same attribute block
that was passed to it, except that it attempts to use a writing mode
that will reverse the text compared to the writing mode that is
supplied.
It must modify an attribute block to have the desired new
value for :WRITING-MODE. However, it.cannot modify an attribute block
arbitrarily, because any attribute block might already be used by the
program. Therefore, it begins a segment, then modifies attribute
block 1 from the contents of the input attribute block, specifying a
new writing mode. END-SEGMENT cancels the modificat~on of attribute
block 1 at the end of the function.

0 3.8

MOVING AND ERASING GRAPHIC INFORMATION

The VAX LISP graphics system provides a function that moves a portion
of a virtual display to a different part of the virtual display, and
another function that erases a portion of a virtual display.
Two
device-coordinate functions perform the same general operations in
windows •

. The MOVE-AREA function moves all the graphic objects within a
specified rectangle from one location in a virtual display to another.
A graphic object in this instance is any graphic output that was
created with a single function. Thus, a circle is a graphic object,
as is a line or a rectangle created with a single call to PLOT.
A
line of text is a graphic object only if it was created with a single
call to TEXT.

3-33

GRAPHICS OUTPUT OPERATIONS

If the display list is enabled, MOVE-AREA updates it to reflect the
movement that has occurred. That is, the display-list representation
of the moved graphic objects is modified to indicate the new location.

If there are any windows into a virtual display at the time you use
MOVE-AREA, the viewports corresponding to those windows do not
immediately reflect the updated display list.
In a viewport, the
effect of MOVE-AREA is to move the rectangle from one part of the
viewport to another, with all its contents.
Thus, if a line cuts
through the rectangle, the portion of the line within the rectangle
will be moved, although in the display list, none of the line has been
moved.
If you create a new window on the virtual display, you will
see that the line is intact.
The ERASE function erases within a virtual display by deleting graphic
objects from the display list. As with MOVE-AREA, the effect of ERASE
on any windows into the virtual display does not immediately reflect
the deletions in the display list.
In a viewport, the rectangle
specified with ERASE is simply blanked out. If the display list, is
-re-executed-~-a~ ~--~later time, objects that were not deleted will be
redisplayed.
The MOVE-AREA-PIXEL function moves an area from one part of a virtual
display to another.
It does not affect the display list. In a
viewport, there is no concept of "graphic objects"; instead, the
specified rectangle is simply picked up and moved with all its
contents to another location. Fragments of drawings and text strings
that are contained within the rectangle are relocated.
In the same way, the ERASE-PIXEL function
rectangle in a viewport.
·

blanks

out

the

specified

0
3-34

0
CHAPTER 4
SCREEN IMAGES AND BITMAPS

This chapter explains how you can read screen images into an array,
write arrays to the screen, and store, retrieve, and manipulate the
array. The chapter is divided as follows:

0
4.1

•

Section
4.1
explains
bitmap
arrays,
representations of screen images in memory.

which

store

•

Section 4.2 shows how you can read images
bitmap arrays.

windows

into

•

Section 4.3 shows how to write bitmap arrays to the screen,
and explains how various attributes can alter the appearance
of the image.

•

Section 4.4 explains how to create and read files that contain
bitmap arrays.

•

Section 4.5 presents functions that create, ~ompare, and
bitmaps.

test

•

Section 4.6 describes the BITBLT facility, by means
you can alter bitmaps in various ways.

which

from

SCREEN IMAGES AND BITMAP ARRAYS

image on the workstation screen is made up of individual pixels.
In a monochrome system, each pixel is either illuminated or dark. In
a color system, each pixel is one of a number of colors.

A bitmap is a representation in memory of a portion of the workstation
screen. In the VAX LISP graphics system, a bitmap is represented by a
specialized two-dimensional array of unsigned bytes. An array used in
~his way is called a bitmap array.

Each element of a bitmap array represents a pixel on the screen.
T~e
number of bits in each byte equals the number of bits used to
4-1

SCREEN IMAGES AND BITMAPS

represent each pixel on the workstation screen.
In a monochrome
system such as the VAXstation II, each pixel is represented by a
single bit, whereas in a color system, each pixel is represented by
several bits. In general, a workstation whose pixels are represented
by n bits can simultaneously display 2**n colors on the screen. For a
monochrome system, where n is equal to 1, the screen can display two
colors, black and white.

When VAX LISP graphics writes a bitmap array to a monochrome
workstation screen, a bit with a value of 1 represents a pixel of the
writing color, and a bit with a value of O represents a pixel of the
background color. Figure 4-1 illustrates this relationship.

••

t2A( ( 0
(0
(0
(0
(0
(0
(0
(0
(0
(0
(0

•
•
IIIIEIIII
•••
•
Figure 4-1:

4.2

0
0
0
0
0
l
0
0
0
0
0

0
l
l
l
l
l
l
l
l
l
0

0
0
0
0
0
l
0
0
0
0
0

0 0
0 0
0 0
0 0
0 0
l l
0 0
0 0
0 0
0 0
0 0

0 0)
0 0)
0 0)
0 0)
0 0)
l 0)
0 0)
0 0)
0 0)
0 0)
0 0))

ML0-213-86

Bitmaps and Screen· Images

CREATING A BITMAP ARRAY FROM A SCREEN IMAGE

The READ-IMAGE-PIXEL function reads an image from a specified portion
of a viewport. The function either returns a bitmap array or modifies
an array that you supply to it. READ-IMAGE-PIXEL does not affect the
image on the screen; it simply makes or modifies an array based on the
pixels that make up the image.

It is important to note that READ-IMAGE-PIXEL uses the contents of a
viewport and· not the contents of a virtual display. A viewport can
contain images from two sources: world-coordinate graphic operations
in the virtual display on which it is based, and device-coordinate
graphic operations in the viewport itself. READ-IMAGE-PIXEL does not
discriminate between images from these two sources; anything that is
visible in the viewport is included in the bitmap array.
If a viewport is partially off the workstation sc~een or is occluded
by another viewport, READ-IMAGE-PIXEL still has access to all its
contents.
4-2

SCREEN IMAGES AND BITMAPS

The format of the READ~IMAGE-PIXEL function is:

UIS:READ-IMAGE-PIXEL window bitmap &OPTIONAL x1 y1 x2 y2
For bitmap, you can supply either a bitmap array or NIL.
If you
supply NIL, the function creates and returns a bitmap array. The size
of the image read, and thus the size of the bitmap created, depends on
the rectangle you specify with the four coordinate arguments.
If you supply a bitmap array for bitmap, the function modifies and
returns that array. When you supply a bitmap, you should not supply
the optional arguments x2 and y2; the function ignores them if they
are present. The size of the bitmap you supply determines the size of
the image that is read.
Consider the following two forms:

(SETQ MAP (READ-IMAGE-PIXEL WINDOW-1 NIL O O 30 30))
(READ-IMAGE-PIXEL WINDOW-1 MAP 30 30)
The first form sets the value of MAP to be the 30x30 bitmap array
created and returned by READ-IMAGE-PIXEL. The size of the array is
in
the
call
to
specified by the four coordinate arguments
READ-IMAGE-PIXEL.
The array represents an area at the lower left
corner of WINDOW-1.

second READ-IMAGE-PIXEL call receives the same bitmap array as its
0 The
second argument.
It modifies this array to reflect the portion of
WINDOW-1 with one corner at 30,30 and the other at 59,59.
In this
call, the dimensions of MAP determine the size of the image read, and
the last two arguments determine the lower left corner of the image.

READ-IMAGE-PIXEL returns information about the image without regard to
writing and background colors or a color map. In a monochrome system,
this means that pixels that are dark are always represented as 0, and
pixels that are illuminated are always represented as 1. This can
cause the image to be complemented when you write the bitmap array
back to the screen. Section 4.3 explains this phenomenon.

4.3

WRITING A BITMAP ARRAY TO THE SCREEN

The IMAGE and IMAGE-PIXEL functions write a bitmap
. workstation screen. They differ in several respects:

array

the

The IMAGE function specifies the location for the image in
terms
of
world coordinates in a virtual display; the
IMAGE-PIXEL function specifies image location in terms of
device coordinates in a viewport.

0
4-3

SCREEN IMAGES AND BITMAPS

IMAGE function causes the image to appear in any viewport
• The
corresponding to a window that is mapped over the image
location in the virtual display.
The IMAGE-PIXEL
causes the image to appear in only one viewport.

function

•

The IMAGE function modifies the display list; the
function does not.

•

If you specify a target area that is larger than the bitmap
array, the IMAGE function scales up the image to fit the
target area, whereas the IMAGE-PIXEL function does not scale
up the image.
Both functions will clip the image if the
target area is smaller than the image.

IMAGE-PIXEL

The IMAGE function places a bitmap
array
into
a
specified
world-coordinate rectangle in the virtual display. Depending on the
size of the rectangle in relation to the size of the bitmap array,
IMAGE may clip the image at the rectangle, or may scale up the image
to fill out the rectangle:
•

If the size of the image in the viewport is larger than the
size of the world-coordinate rectangle as it appears in the
viewport, IMAGE clips off the right and/or bottom edge(s) of
the image.

•

If the size of the rectangle is larger than the size of the
image by at least an integer multiple in either dimension,
IMAGE scales up the image on a per-pixel basis to fill out the
rectangle
as
nearly as possible.
The scaling may be
horizontal, vertical, or both. Any room left over between the
scaled image and the rectangle appears above and to the right
of the image.

Figure 4-2 shows the results of using
bitmap arrays.

IMAGE

clip

and

scale

R ~ Ill
ORIGINAL
IMAGE

t~
SCALED

CLIPPED
ML0·214-86

Figure 4-2:

Writing Bitmap Arrays with IMAGE

0
4-4

SCREEN IMAGES AND BITMAPS

IMAGE-PIXEL, in contrast to IMAGE, never scales or otherwise increases
the size of a bitmap array. With IMAGE-PIXEL, you need supply only a
single coordinate, the location for the lower-left corner of the
image.
IMAGE-PIXEL determines the size of the displayed image from
the dimensions of the bitmap array that you supply. If you supply a
second coordinate, and the rectangle so defined is smaller than the
image, IMAGE-PIXEL clips the image on the right and/or bottom edge(s).
Both the IMAGE and IMAGE-PIXEL functions take an attribute block as
their second argument.
The functions use the :WRITING-INDEX and
:BACKGROUND-INDEX attributes to determine how to represent each array
element on the screen. AO is represented in the background color and
a 1 is represented in the writing color.

If you are using windows with a light background and dark writing
color, you will notice that images read from the window (with
READ-IMAGE-PIXEL) and then written back to the window (with IMAGE or
IMAGE-PIXEL) are complemented -- that is, the dark parts become light
and the light parts become dark. This occurs because READ-IMAGE-PIXEL
always returns a O for a dark pixel and a 1 for an illuminated pixel,
without regard for writing or background colors. The IMAGE functions
interpret the O as background (light) and the 1 as writing color
(dark). Thus, what was background becomes writing color, and vice
versa.
This phenomenon does not occur in windows that have a dark
background.
You can use an attribute block with the :WRITING-MODE attribute set to
:OVERLAY-NEGATE to counteract the complementing of an image taken from
a light-background window. Or, you can use the :COPY writing mode,
which causes the image to be written to the screen without regard to
writing color or background color. That is, with :COPY, a 1 always
illuminates the pixel and a O always darkens it.

4.4

STORING BITMAP ARRAYS IN FILES

Two functions allow you to store a bitmap
retrieve it from a file:

array

file

•

DUMP-BITMAP creates a file containing a bitmap array.

•

LOAD-BITMAP returns a bitmap array from a
DUMP-BITMAP.

file

and

created

with

Unlike most of the functions documented in this manual, these two
functions are both in package LISP and are therefore available to you
without a package specification.

0
4-5

SCREEN IMAGES AND BITMAPS
4.5

CREATING, COMPARING, AND TESTING BITMAP ARRAYS

One way to create a bitmap is by using the READ-IMAGE-PIXEL function.
Another way is by using the MAKE-BITMAP function. This function
returns a bitmap array of the dimensions you specify.
Optional
arguments allow you to specify the number of bits used to represent
each pixel, and the space in which the array is allocated.
This
function is in package LISP.

The COMPARE-BITMAPS function compares the two bitmap arrays given as
its arguments.
It returns T if the arrays are identical in both
dimensions and contents. If it returns NIL, the additional return
values provide more information about the difference.
See the
description of the function in Part II for more information.
This
function is also in package LISP.
bitmap

This section describes the means by which you can alter a bitmap
array.
You may want to read an image into a bitmap array, alter it,
and write it back to the same location; or you may wish to create a
bitmap array from some nonimage source, modify it, and write it to the
screen.

The BITMAP-P function returns T if its argument is
array and NIL otherwise. It too is in package LISP.

4.6

valid

ALTERI NG BITMAPS

To alter a bitmap array, you use the BITBLT function, operating on
BITBLT objects.
(BITBLT stands for BIT Block Logical Transfer.)
BITBLT objects contain complete specifications for a particular
operation on a particular bitmap array. When you make a BITBLT object
(with the MAKE-BITBLT function) you provide these specifications as
keyword arguments.
You then supply the BITBLT object as the single
argument to the BITBLT function; this actually causes the operation to
happen.
As a simple example, imagine that you want
viewport with a pattern of vertical bars.
follows:
1.

to overlay part of a
One way to do this is as

Create a bitmap array from the portion of
you wish to overlay:

the

viwport

that

(SETF BARS-BITMAP (READ-IMAGE-PIXEL
WIN-1 NIL SO SO 120 150))

0
4-6

SCREEN IMAGES AND BITMAPS

Create a BITBL.T object that describes the operation you
to perform:

wish

(SETF BARS (MAKE-ARRAY '(1 4)
:ELEMENT-TYPE 'BIT
:INITIAL-CONTENTS '((1 1 0 0))))
(SETF BARS-BITBLT (MAKE-BITBLT
:SOURCE BARS-BITMAP
:DESTINATION BARS-BITMAP
:SRC-OP BOOLE-IOR
:TEXTURE BARS))
)

This BITBLT object specifies that the BARS-BITMAP array
should be combined with the array BARS, using the BOOLE-IOR
function. The result of this operation is then used to
replace the BARS-BITMAP array.

Pass the BITBLT object you created to the BITBLT function:
(BITBLT BARS-BITBLT)
This has the effect of altering the bitmap array specified by
BARS-BITBLT so that it has vertical bars running down it, but
is otherwise the same as the original.

Write the altered bitmap array back to the screen:
(IMAGE-PIXEL WIN-1 0 BARS-BITMAP 50 50 120 150)

This example illustrates most of the features of the BITBLT facility,
although much more control is available. With MA~E-B~TBLT, you may
specify:

•

A source bitmap array. Keyword arguments allow you to
specified rectangle of the source bitmap array.

use ~a

•

A texture bitmap array, which will be combined with the source
bitmap array.

•

A source operation (:SRC-OP), which specifies the result when
elements
of the source bitmap array are combined with
corresponding elements of the texture bitmap array.
The
source operation can be any of the constants that you can
supply to the BOOLE function.

destination bitmap array • In the example, the destination
• Abitmap
array was the same as the source bitmap array, but it

could be a different array. Keyword arguments allow you to
specify which part of the destination bitmap array should be
altered.

4-7

SCREEN IMAGES AND BITMAPS

•

A destination operation (not shown in the example), which
specifies how elements in the source-texture result array
should be combined with corresponding elements
in
the
destination bitmap array.
These can be constants that you
supply to the BOOLE function. The default operation, used in
the example, is BOOLE-1, which replaces the destination bitmap
array with the source-texture result array.

In general terms, a BITBLT operation proceeds as follows:
1.

The texture bitmap is filled out (by horizontal replication)
or trimmed on the right so that it is 32 elements wide. (It
can be of any height.)

For each element in the destination bitmap (or specified
portion thereof), the corresponding element in the source
bitmap is combined with the corresponding element in the
texture bitmap according to the source operation.

- 3~

The result of combining the source and texture elements is
combined with the destination element, according to the
destination operation. This result replaces the destination
element.

For more information and exact specifications of the BITBLT operation,
see the description of the MAKE-BITBLT function in Part 11 of this
manual.

0
4-8

0
CHAPTER 5
POINTER OPERATIONS

Every VAXstation is equipped with some sort of a pointer input device.
The pointer may be a mouse, a graphics tablet, or some other device.
All pointer input devices have in common the ability to move the
pointer cursor around the screen, and all have one or more buttons to
allow the user to request that some action take place.
Typical uses for the pointer are:

• Selecting an icon on the screen or an item from a menu
Selecting portions of a program, a document, or a drawing that
• have
been made pointer-sensitive

• Providing positional input for a graphics editing application
The VAX LISP graphics system provides functions that allow your
program to make use of the pointer in various ~ays. Section 5.1
describes the various functions.
Section 5.2 shows how you can
establish and make use of pointer sensitivity. When you make part of
a viewport pointer-sensitive, you request that the graphics system
alert you when the pointer cursor enters that region. Pointer
sensitivity is used to implement menus, icons, and other workstation
features.

5.1

POINTER-RELATED FUNCTIONS

This section describes the functions that allow you to get input from
the pointer and to control it from your program. The section is
divided as follows:
•

Section 5.1.1 describes pointer positional functions.
These
functions provide information on the location of the pointer
cursor, and allow you to relocate the pointer cursor under
program control.

5-1

-----------------------·-~··--

POINTER OPERATIONS

5.1.2 describes pointer movement functions.
These
• Section
functions allow your application to react to movement of the
pointer cursor within defined areas of a viewport.

5.1.3 describes button input
functions.
These
• Section
functions allow your application to determine the state of the

pointer buttons and to react to
released.

button

being

pressed

Throughout this section, reference will be made
to
interrupt
functions.
An interrupt function is a function that is meant to be
invoked at some unknown time, interrupting the normal flow of program
execution.
Interrupt functions are necessary to handle pointer input
because the user can move the pointer and press buttons at any time,
not just when it is convenient for the program.
The VAX LISP System Access Programming Guide contains
interrupt functions and how to use them.

5.1.1

information

Obtaining and Setting Pointer Position

Three functions return the position of the pointer cursor.
There is
one function for each of the three coordinate systems to which you
have access:
•

The GET-POINTER-POSITION function returns the position of
pointer cursor in world coordinates •

•

The GET-POINTER-POSITION-PIXEL function returns
of the pointer cursor in device coordinates.

the

position

GET-ABS-POINTER-POSITION returns the position of the
• Th'e
pointer
cursor
on
the
screen
in screen coordinates
(centimeters).

All three of the functions return multiple values, where the first
value is the X coordinate and the second value is the Y coordinate.
The first two functions return NIL for their first value if the
pointer cursor is not in the specified window.
The pointer cursor has one particular pixel, called the active pixel,
that is used to calculate the pointer cursor position. For the
default pointer cursor, the active pixel is at the tip of the arrow.
Example 5-1 illustrates the use of the GET-POINTER-POSITION function
to implement a very simple form of "rubber-banding." In this· familiar
graphics editing technique, one end of a line is anchored and the
other end of the line tracks the pointer cursor. (You can imagine a
rubber band with a tack through one end and a stylus in the other end,
stretching and moving it.) In a graphics editor program, the user
5-2

POINTER OPERATIONS

would indicate the final position for the line by pressing a button.
The function in the example simply loops until the pointer cursor
leaves the viewport, causing GET-POINTER-POSITION to return NIL.
Example 5-1:

Rubber-Banding with GET-POINTER-POSITION

;;; Do rubber-banding in WINDOW starting at the pointer position
;;; when the function is called and ending when the pointer leaves
;;; the window. DISPLAY's display list is disabled during the
;;; operation.

(DEFUN RUBBER-BAND (DISPLAY WINDOW)
(DISABLE-DISPLAY-LIST DISPLAY)
(BEGIN-SEGMENT DISPLAY)
(SET-ATTRIBUTE DISPLAY O 1
; Use :COMPLEMENT to
:WRITING-MODE :COMPLEMENT)
; draw and erase lines
(MULTIPLE-VALUE-BIND (ANCHORED-X ANCHORED-Y)
; Get start position
(GET-POINTER-POSITION DISPLAY WINDOW)
(DO* ((NEW-X ANCHORED-X)
(NEW-Y ANCHORED-Y)
(OLD-X NEW-X NEW-X)
; Coordinates for erasing
(OLD-Y NEW-Y NEW-Y))
; old line
( (NOT NEW-X)
; Check for out-of-bounds
(END-SEGMENT DISPLAY)
; Done; cancel block 1
(ENABLE-DISPLAY-LIST DISPLAY))
; Re-enable disp. list
Draw the line from start position to pointer position
I I

0 ..

(PLOT DISPLAY 1
ANCHORED-X ANCHORED-Y
NEW-X NEW-Y)
;; Get new pointer position

(MULTIPLE-VALUE-SETQ (NEW-X NEW-Y)
(GET-POINTER-POSITION DISPLAY WINDOW))
;; Erase old line
(PLOT DISPLAY 1
ANCHORED-X ANCHORED-Y OLD-X OLD-Y))))

No.te that the GET-POINTER-POSITION function takes a virtual display
and a window as its first two arguments. The window designates the
viewport from which you want to get the pointer position.
For the
display argument, you can give the window's virtual display, or a
transformation mapped into that display. The position information is
returned in the coordinate system of the display or the transformation
ohat you specify.

5-3

POINTER OPERATIONS

By contrast, the GET-POINTER-POSITION-PIXEL function takes only a
window argument.
The position information is returned in the device
coordinate system of that window.

Two functions, SET-POINTER-POSITION and SET-POINTER-POSITION-PIXEL,
allow you to relocate the pointer cursor in a specified viewport.
There is no SET- equivalent to GET-ABS-POINTER-POSITION, since you
cannot affect the workstation screen outside of viewports that your
program has created.

5.1.2

Movement Input

A number of functions allow your program to respond to the movement of
the pointer cursor within a specified viewport. The functions are the
following:
•

The SET-POINTER-ACTION and SET-POINTER-ACTION-PIXEL functions
allow you to specify an interrupt function to be executed when
the pointer cursor moves in or exits a viewport or specified
portion of a viewport •

•

The
SET-POINTER-PATTERN
and
SET-POINTER-PATTERN-PIXEL
functions allow you to specify a new image for the pointer
cursor. The pointer cursor will change to that image when the
pointer cursor is in _the specified viewport or portion of the
viewport.

The SET-POINTER-ACTION and SET-POINTER-PATTERN' functions take
a
virtual display and a window as· their first two arguments. The window
designates the viewport in which you want to respond to pointer
movement. For the display argument, you can give the window's virtual
display, or a transformation mapped into that display.
Optional
arguments to each function let you specify a rectangle in which
movement should trigger an action.
The optional arguments are
interpreted
as world coordinates or transformation coordinates,
depending on whether you supplied
a
virtual
display
or
a
transformation as the first argument.

The SET-POINTER-ACTION functions establish an action to be taken when
the pointer cursor moves within a specified area, and a separate
action to be taken if the pointer cursor exits the area. The area can
be all of a viewport or a specified rectangle in the viewport. The
actions can be one of two things: an interrupt function identifier
(iif-id), designating a function to be executed when the cursor moves;
or NIL, indicating that nothing should be done.
If you use SET-POINTER-ACTION to set up an interrupt function to
respond to pointer movement, the function executes every time the
pointer cursor moves. If the pointer cursor move& continuously, the
interrupt function executes as often as the graphics system can invoke

5-4

POINTER OPERATIONS

it. Sometimes this is.the intended behavior; other times, you only
want the interrupt function to execute once, to indicate that the
pointer cursor has entered the viewport or rectangle. If this is the
case, the interrupt function can turn itself off by resetting the
action to NIL. An example of this can be seen in Section 5.2, which
discusses pointer sensitivity.
Even in applications in which a pointer movement function should
execute repeatedly, it is a good idea to set the movement action to
NIL at the beginning of the function, and then re-establish it at the
end of the function. This prevents requests for the movement function
from queueing up while the movement function is executing.

Example 5-2 shows the use of SET-POINTER-ACTION to implement the
function RUBBER-BAND.
Recall that in Example 5-1 this function was
implemented as a loop that continuously erased and replotted the line,
whether or not the pointer cursor was moving. In Example 5-2, the
line is only erased and plotted when the pointer cursor moves.
RUBBER-BAND establishes initial values for the special variables
*POINTER-X* and *POINTER-Y*, establishes the interrupt
function
DRAW-RUBBER-BAND as the action to take when the pointer cursor moves,
sets the value of the special variable *DRAW-IIF-ID* to the iif-id of
the interrupt function, and returns.
Every time the pointer cursor moves in the viewport associated with
WINDOW,
the
graphics
system
invokes
DRAW-RUBBER-BAND.
DRAW-RUBBER-BAND first uses SET-POINTER-ACTION to turn off movement
interrupt functions for the duration of its execution. It then erases
the old line, obtains the current pointer position, and plots the new
line.
Finally, it re-establishes itself as the movement interrupt
function and exits.
If the cursor moves out of the viewport,
DRAW-RUBBER-BAND does not execute again until the cursor re-enters the
viewport.
The function STOP-RUBBER-BAND stops the drawing action by disabling
the pointer movement interrupt function.
It also uninstates the
interrupt
function.
It
is
important
to
use
UNINSTATE-INTERRUPT-FUNCTION to clean up interrupt functions that are
no longer needed; otherwise, they consume system resources.
Note that DRAW-RUBBER-BAND uses special variables to retain the
coordinates for one endpoint of the line last drawn. Since interrupt
functions execute at unpredictable times and
in
unpredictable
contexts, you cannot count on the binding of special variables during
the execution of an interrupt function. In this case, you must be
careful not to permit more than one function to alter the values of
*POINTER-X* and *POINTER-Y* at a time. An example in Section 5.1.3
shows how special variables can be eliminated in this situation.

0
5-5

POINTER OPERATIONS
Example 5-2:

Rubber-Banding with SET-POINTER-ACTION

(DEFVAR *POINTER-X*)
(DEFVAR *POINTER-Y*)
(DEFVAR *DRAW-IIF-ID*)
(DEFUN RUBBER-BAND (DISPLAY WINDOW)
(BEGIN-SEGMENT DISPLAY)
(SET-ATTRIBUTE DISPLAY O 1 :WRITING-MODE :COMPLEMENT)
(MULTIPLE-VALUE-SETO (*POINTER-X* *POINTER-Y*)
(GET-POINTER-POSITION DISPLAY WINDOW))
(SET-POINTER-ACTION
DISPLAY
WINDOW
(SETF *DRAW-IIF-ID*
(INSTATE-INTERRUPT-FUNCTION
#'DRAW-RUBBER-BAND
:ARGUMENTS (LIST DISPLAY WINDOW
*POINTER-X*
*POINTER-Y*)))
NIL))

;;; DRAW-RUBBER-BAND is the interrupt function that erases the old
;;; line and plots a new one when the pointer moves.
(DEFUN DRAW-RUBBER-BAND
(DISPLAY WINDOW ANCHORED-X ANCHORED-Y)

; Turn off interrupts

(SET-POINTER-ACTION
DISPLAY WINDOW NIL NIL)
;; Erase existing line
(PLOT DISPLAY 1 ANCHORED-X ANCHORED-Y
*POINTER-X* *POINTER-Y*)

;; Get new pointer position, plot a new line
(MULTIPLE-VALUE-SETO (*POINTER-X* *POINTER-Y*)
(GET-POINTER-POSITION DISPLAY WINDOW))
(PLOT DISPLAY 1 ANCHORED-X ANCHORED-Y
;- Draw new line
*POINTER-X* *POINTER-Y*)
(SET-POINTER-ACTION
; Turn on interrupts
DISPLAY
WINDOW *DRAW-IIF-ID* NIL))

... Use STOP-RUBBER-BAND to turn off the rubberbanding action
I I I

(DEFUN STOP-RUBBER-BAND (DISPLAY WINDOW)
(SET-POINTER-ACTION DISPLAY WINDOW NIL NIL)
(UNINSTATE-INTERRUPT-FUNCTION *DRAW-IIF-ID*))

5-6

POINTER OPERATIONS

The call to INSTATE-INTERRUPT-FUNCTION function in RUBBER-BAND causes
four arguments to be passed to DRAW-RUBBER-BAND: the display, the
window, and the coordinates of the starting point.
Every time the
graphics
system invokes DRAW-RUBBER-BAND, it passes these four
arguments.
This method of passing information to an interrupt
function is safer than the use of special variables, and should be
used when the information can be determined at the time that
INSTATE-INTERRUPT-FUNCTION is evaluated.
To establish an action to be taken when the pointer cursor :exits an
area,
supply
an
iif-id for the exit-action argument of the
SET-POINTER-ACTION functions. Once you have established an interrupt
function as an exit action, the graphics system invokes that interrupt
function every time the pointer cursor exits the specified viewport or
viewport rectangle.

The SET-POINTER-ACTION functions both take four optional arguments
that specify a rectangle in which the action is effective. Each pair
of arguments supplies the coordinates of one corner of the rectangle.
For SET-POINTER-ACTION, the coordinates are world or transformation
coordinates. For SET-POINTER-ACTION-PIXEL, the coordinates are device
coordinates.
·
You can use the SET-POINTER-ACTION functions more than once for a
particular area.
For example, you could use SET-POINTER-ACTION once
to specify a movement action anywhere in a particular window, and then
use it again with optional arguments. to request a different action in
a rectangle in that window. For any point in the window, the action
will be the one that was last requested for that point. So, for
example, if you issued SET-POINTER-ACTION for an entire window first
and a portion of the window afterward, cursor movement would cause the
first action everywhere in the window except in the portion specified
in the second function. If you issued the functions in the reverse
order, the effect of the second function would wipe out the effect of
the first, and only the second action could be obtained. ·Figure 5-1
illustrates this.
The SET-POINTER-PATTERN and SET-POINTER-PATTERN-PIXEL functions allow
you to specify that the pointer cursor should be changed in appearance
whenever it enters a specified viewport or portion of a viewport.
These functions can be useful when you have an application with a
number of different windows, and you wish to help indicate the use of
each window by the appearance of the cursor when it is in that window.
For example, a window in which graphics editing takes place can have a
crosshair cursor.

You specify the desired cursor appearance in the form of a 16x16
bitmap, that is, a two-dimensional array of bits. You must also
specify the active pixel for the cursor, that is, the pixel which is
used in calculating the actual cursor position.

5-7

POINTER OPERATIONS

(SET-POINTER-ACTION
DISPLAY WINDOW ACTION-A NIL)
(SET-POINTER-ACTION
DISPLAY WINDOW ACTION-8 NIL
2.0 2.0 3.0 3.0)

~-ACTION-A
-

-ACTION-B

(SET-POINTER-ACTION
DISPLAY WINDOW ACTION-B NIL
2.0 2.0 3.0 3.0)
(SET-POINTER-ACTION
DISPLAY WINDOW ACTION-A NIL)
--ACTION-A
ML0·215·86

Figure 5-1:

Specifying Overlapping Areas for SET-POINTER-ACTION

Example 5-3 shows how you might set up a crosshair cursor and specify
that it,be used in a particular window. The two numbers (7 and 8) at
the end of the SET-POINTER-PATTERN function specify the coordinates of
the active pixel. Notice that the active pixel is given using device
coordinates based on an origin of 0,0 at the lower-left corner of the
bitmap, and not as an array reference.
You can
use
SET-POINTER-PATTERN
and
SET-POINTER-PATTERN-PIXEL
interchangeably, as long as you are not specifying that only a portion
of the viewport should cause the cursor to change.
If you wish to
specify a rectangle in the viewport, you must decide whether you want
to
use
world
coordinates
or
device
coordinates.
Use
SET-POINTER-PATTERN
if you want to use world coordinates, and
SET-POINTER-PATTERN-PIXEL if you want to use device coordinates.
For
both
functions, you use four optional arguments to specify a
rectangle.
You can use SET-POINTER-PATTERN more than once for a particular area.
For example, you could use SET-POINTER-PATTERN once to specify that
the cursor should change to a crosshair anywhere in a particular
window, and then use it again to request a different pattern in a
rectangle in that window. For any point in the window, the cursor
will be changed to the pattern that was last requested for that· point.
So, for example, if you issued SET-POINTER-PATTERN for an entire
window first and a portion of the window afterward, the cursor would
take on the first pattern everywhere in the window except in the.
portion specified in the second function. If you. issued the functions
in the reverse order, the effect of the second function would wipe out

5-8

POINTER OPERATIONS

the

effect

Q obtained.

Example 5-3:

the

first,

and

only

the

second

pattern could be

Setting the Cursor Pattern

(DEFCONSTANT CROSSHAIR-CURSOR
(MAKE-ARRAY '(16 16)
:ELEMENT-TYPE 'BIT
:INITIAL-CONTENTS
'((0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 o o·o o o o o 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0)
(0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0))))

(SET-POINTER-PATTERN NIL *EDITING-WINDOW* CROSSHAIR-CURSOR 7 8)

5.1.3

Button Input

functions allow your program to accept input from the pointer
O Three
buttons. The functions are:
•

GET-BUTTONS, which returns the state of
time that it is called.

the

buttons

the

•

SET-BUTTON-ACTION - and
its
device-coordinate
equivalent,
SET-BUTTON-ACTION-PIXEL, which establish an action to perform
when a button is pressed or released while the pointer cursor
is in a specified viewport or portion of a viewport.

The GET-BUTTONS function returns two values. The first value is an
integer that encodes the state of the buttons. (See GET-BUTTONS in
Part II for an explanation and example of how to interpret this return
v•lue.) The·second value is Tor NIL, indicating whether the cursor is
visible in the window you supply as an argument.

0
5-9

POINTER OPERATIONS

The two SET-BUTTON-ACTION functions allow you to establish
an
interrupt function which the graphics system will invoke when any
button is pressed or released in a particular viewport. (You can also
specify an action of NIL, meaning that the buttons should be ignored.)
The interrupt function is passed two arguments by the graphics system:
the code of the button that was pressed or released, and the direction
of the transition (T if the button was pressed, NIL if released). The
interrupt
function
must
decide whether the particular button
transition was meaningful and, if so, what to do about it.

o·

Use the POINTER-BUTTON-n constants to test the button code in the
interrupt function. Each of these constants corresponds to one of the
buttons on the pointing device. For example, your interrupt function
might look like this:
(DEFUN BUTTON-ACTION (BUTTON TRANSITION .•. )
(WHEN TRANSITION
; Ignore up transitions
(CASE BUTTON
(#.POINTER-BUTTON-1 ••• )
(#.POINTER-BUTTON-2 ••• )

... ) ) )

Example 5-4 shows the use of SET-BUTTON-ACTION to extend
the
RUBBER-BAND function of Example 5-2 into a crude method of drawing
connected lines. DRAW-CONNECTED-LINES sets up a situation in which
pressing the leftmost pointer button ends the current line and starts
a new line, and pressing the rightmost button terminates the drawing
operation.
Moving the pointer cursor out of the window does not
terminate the operation; instead, the window will sit idle until the
pointer cursor returns, and th~n the drawing will resume.
It is important to note that the action established
by
the
SET-BUTTON-ACTION functions is only effective when the pointer cursor
is in the specified viewport. As soon as the pointer cursor leaves
that viewport, the action becomes inactive until the cursor returns.
One problem with Example 5-4 is the number of special variables
required. Even in this simple application, five special variable~ are
required to keep track of the line coordinates and the iit-id. A more
complicated application, such as a menu system, might have multiple
areas in a viewport that would each be specified by three or four
values. Thus, special variables are not a practical solution.
One way to solve the problem of maintaining information for interrupt
functions is to pass a structure as an argument to the functions. The
structure can have one slot for each piece of information that must be
passed to each interrupt function call. Example 5-5 functionally
reproduces Example 5-4, but it uses a structure instead of special
variables. DRAW-CONNECTED-LINES sets up the structure and then causes
it to be
passed
as
an
argument
to
DRAW-RUBBER-BAND
and
RUBBER-BAND-BUTTON-HANDLER. Those two functions ·communicate with each
other and with successive calls to themselves by making alterations to
the structure.
5-10

POINTER OPERATIONS

Example 5-4:

Controllin.g Rubber-Banding with Pointer Buttons

()
(DEFVAR *ANCHORED-X*)
(DEFVAR *ANCHORED-Y*)
(DEFVAR *POINTER-X*)
(DEFVAR *POINTER-Y*)
(DEFVAR *RUBBER-IIF*)
iii The user calls DRAW-CONNECTED-LINES to draw a series of
iii lines. The left button starts each new line and the right
iii button finishes the series.

(DEFUN DRAW-CONNECTED-LINES (DISPLAY WINDO~)
(BEGIN-SEGMENT DISPLAY)
(SET-ATTRIBUTE DISPLAY O 1 :WRITING-MODE :COMPLEMENT)
()

ii Set up the interrupt function that draws and erases lines

(SETQ *RUBBER-IIF*
(INSTATE-INTERRUPT-FUNCTION
#'DRAW-RUBBER-BAND
:ARGUMENTS (LIST DISPLAY WINDOW)))

()

ii Set up the interrupt function that handles button transitions.
ii LINE-DONE and DRAWING-DONE are flags that will be manipulated
ii by button handler.

(LET* ((LINE-DONE (CONS NIL NIL))
(DRAWING-DONE (CONS NIL NIL))
(BUTTON-I IF
(INSTATE-INTERRUPT-FUNCTION
#'RUBBER-BAND-BUTTON-HANDLER
:ARGUMENTS (LIST LINE-DONE DRAWING-DONE))))
(SET-BUTTON-ACTION DISPLAY WINDOW BUTTON-IIF)
ii Wait for user to press left button to start first line

(WAIT "Waiting for start of drawing" #'CAR LINE-DONE)
(MULTIPLE-VALUE-SETO
i Get start position
(*ANCHORED-X* *ANCHORED-Y*)
(GET-POINTER-POSITION DISPLAY WINDOW))
(SETQ *POINTER-X* *ANCHORED-X* *POINTER-Y* *ANCBORED-Y*)
ii Execute the following loop once for each line that is drawn
ii permanently in the display.

()

(LOOP
(DISABLE-DISPLAY-LIST DISPLAY)
(SET-POINTER-ACTION
; Start rubberbanding
DISPLAY WINDOW *RUBBER-IIF* NIL)
(WAIT "for end of rubberbanding" #'CAR LINE-DONE)
5-11

POINTER OPERATIONS

Example 5-4 (cont.)
(SET-POINTER-ACTION
DISPLAY WINDOW NIL NIL)
(ENABLE-DISPLAY-LIST DISPLAY)
(PLOT DISPLAY O *ANCHORED-X* *ANCHORED-Y*
(SETQ *ANCHORED-X* *POINTER-X*)
(SETQ *ANCHORED-Y* *POINTER-Y*))
(WHEN (CAR DRAWING-DONE) (RETURN))
(SETF (CAR LINE-DONE) NIL))
(SET-BUTTON-ACTION DISPLAY WINDOW NIL)
(UNINSTATE-INTERRUPT-FUNCTION BUTTON-IIF))
(DISABLE-DISPLAY-LIST DISPLAY)
(END-SEGMENT DISPLAY)
(UNINSTATE-INTERRUPT-FUNCTION *RUBBER-IIF*))

; Stop rubberbanding

; Draw line permanently

Right button?
; No, loop again
; Yes, dismantle the
; machinery

;;; DRAW-RUBBER-BAND draws and erases lines in response to
;;; pointer movement.

(DEFUN DRAW-RUBBER-BAND (DISPLAY WINDOW)
; Turn off interrupts

(SET-POINTER-ACTION
DISPLAY WINDOW NIL NIL)
;; Erase existing line. Attribute block 1
;; contains :WRITING-MODE :COMPLEMENT
(PLOT DISPLAY 1 *ANCHORED-X* *ANCHORED-Y*
*POINTER-X* *POINTER-Y*)

;; Get new position and plot line _
(MULTIPLE-VALUE-SETO (*POINTER-X* *POINTER-Y*)
(GET-POINTER-POSITION DISPLAY WINDOW))
(PLOT DISPLAY 1
*ANCHORED-X* *ANCHORED-Y*
*POINTER-X* *POINTER-Y*)
(SET-POINTER-ACTION
; Restore interrupts
DISPLAY WINDOW *RUBBER-IIF* NIL))

,.., ,. RUBBER-BAND-BUTTON-HANDLER handles all button transitions •
•

•

I I I

It ignores all transitions except down transitions of left and

, , , right buttons.
0

••

(DEFUN RUBBER-BAND-BUTTON-HANDLER
(BUTTON TRANSITION
; Args. from graphics system
LINE-DONE DRAWING-DONE) ; Args. supplied when instated
(WHEN TRANSITION
; Ignore up transitions
(CASE BUTTON
(#.UIS::POINTER-BUTTON~1
; Left button; start new line(SETF (CAR LINE-DONE) T))

5-12

POINTER OPERATIONS

QExample 5-4 (cont.)
(#.UIS::POINTER-BUTTON-3
; Right button; end line and t,•rminate
(SETF (CAR LINE-DONE) T
(CAR DRAWING-DONE) T)))))
Example 5-5:

Using Structures to Eliminate Special Variabh::5

;;; DRAW-INFO is a structure that holds all information necessary
;;; for line-drawing and button-handling interrupt functions.

(DEFSTRUCT DRAW-INFO
DISPLAY
WINDOW
(ANCHORED-X 0.0 :TYPE SHORT-FLOAT)
(ANCHORED-Y 0.0 :TYPE SHORT-FLOAT)
(POINTER-X 0.0 :TYPE SHORT-FLOAT)
(POINTER-Y 0.0 :TYPE SHORT-FLOAT)
(LINE-DONE NIL)
(DRAW-DONE NIL)
RUBBER-I IF)

C).

; Start position for
; line
; Current line endpoint
; Flags for button
; handler

(DEFUN DRAW-CONNECTED-LINES (DISPLAY WINDOW)
(BEGIN-SEGMENT DISPLAY)
(SET-ATTRIBUTE DISPLAY O 1 :WRITING-MODE :COMPLEMENT)
(LET* ((DI (MAKE-DRAW-INFO
; Make structure to
:DISPLAY DISPLAY
; hold drawing
:WINDOW WINDOW))
; information
(BUTTON-IIF
; Set.up button handler
(INSTATE-INTERRUPT-FUNCTION
#'RUBBER-BAND-BUTTON-HANDLER
:ARGUMENTS (LIST DI))))
; Pass structure to
interrupt function
;
(SETF (DRAW-INFO-RUBBER-IIF DI)
; Set up move handler
(INSTATE-INTERRUPT-FUNCTION
#'DRAW-RUBBER-BAND
:ARGUMENTS (LIST DI)))
; Pass structure
(SET-BUTTON-ACTION DISPLAY WINDOW BUTTON-llF)
(WAIT "Waiting for start of drawing"
#'DRAW-INFO-LINE-DONE DI)
; Use slot as flag
(MULTIPLE-VALUE-BIND (X Y)
(GET-POINTER-POSITION DISPLAY WINDOW)
(SETF
; Put line coords.
(DRAW-INFO-ANCHORED-X DI) X
in structure
;
(DRAW-INFO-ANCHORED-Y DI) Y
(DRAW-INFO-POINTER-X DI) X
(DRAW-INFO-POINTER-Y DI) Y))
(LOOP
(DISABLE-DISPLAY-LIST DISPLAY)

5-13

POINTER OPERATIONS

Example 5-5 (cont.)
; Start rubberbanding
(SET-POINTER-ACTION
DISPLAY WINDOW
(DRAW-INFO-RUBBER-IIF DI) NIL)
(WAIT "for end of rubberbanding"
#'DRAW-INFO-LINE-DONE DI)
; Check struc. slot
(SET-POINTER-ACTION DISPLAY WINDOW NIL NIL)
(ENABLE-DISPLAY-LIST DISPLAY)
; Plot permanent line
(PLOT DISPLAY O
, from coords. left
(DRAW-INFO-ANCHORED-X DI)
;
in structure
(DRAW-INFO-ANCHORED-Y DI)
(SETF (DRAW-INFO-ANCHORED-X DI)
(DRAW-INFO-POINTER-X DI))
(SETF (DRAW-INFO-ANCHORED-Y DI)
(DRAW-INFO-POINTER-Y DI)))
; Right button?
(IF (DRAW-INFO-DRAW-DONE DI) (RETURN))
(SETF (DRAW-INFO-LINE-DONE DI) NIL))
··-·· -- - -(-SET-BUT-TON-ACTION DISPLAY .WINDOW NIL)
(END-SEGMENT DISPLAY)
(UNINSTATE-INTERRUPT-FUNCTION (DRAW-INFO-RUBBER-IIF DI))
(UNINSTATE-INTERRUPT-FUNCTION BUTTON-IIF)
(DISABLE-DISPLAY-LIST DISP)))

...
, , , DRAW-RUBBER-BAND is now passed one argument, a structure
(DEFUN DRAW-RUBBER-BAND (DI)
(SET-POINTER-ACTION
NIL (DRAW-INFO-WINDOW DI.) NIL NIL)
(PLOT (DRAW-INFO-DISPLAY DI) 1
(DRAW-INFO-ANCHORED-X DI)
(DRAW-INFO-ANCHORED-Y DI)
(DRAW-INFO-POINTER-X DI)
(DRAW-INFO-POINTER-Y DI))
(MULTIPLE-VALUE-BIND
(X Y)
(GET-POINTER-POSITION
(DRAW-INFO-DISPLAY DI)
(DRAW-INFO-WINDOW DI))
(PLOT (DRAW-INFO-DISPLAY DI) 1
(DRAW-INFO-ANCHORED-X DI)
(DRAW-INFO-ANCHORED-Y DI)
(SETF (DRAW-INFO-POINTER-X DI) X)
(SETF (DRAW-INFO-POINTER-Y DI) Y)))
(SET-POINTER-ACTION
NIL
(DRAW-INFO-WINDOW DI)
(DRAW-INFO-RUBBER-IIF DI)
NIL))

... RUBBER-BAND'-BUTTON-HANDLER is passed a structure and
I I

5-14

POINTER OPERATIONS

Example 5-5 (cont.)

;;; modifies two of its slots to show which button was pressed.
(DEFUN RUBBER-BAND-BUTTON-HANDLER
(BUTTON TRANSITION DI)
(WHEN TRANSITION
; Ignore up transitions
(CASE BUTTON
(#.UIS::POINTER-BUTTON-1; Left button; start new line
(SETF (DRAW-INFO-LINE-DONE DI) T))
(#.UIS::POINTER-BUTTON-3; Right button; terminate
(SETF (DRAW-INFO-LINE-DONE DI) T
(DRAW-INFO-DRAW-DONE DI) T)))))

0 5.2 POINTER SENSITIVITY

In various applications it is useful to make a region of a viewport
pointer-sensitive. A pointer-sensitive region is an area that visibly
responds to the presence of the pointer cursor, and that initiates
some action when the user presses a pointer button while the pointer
cursor is in the region. In the standard VAXstation user interface,
menu choices are pointer-sensitive; they change appearance when the
pointer cursor enters them and they cause an action when the user
presses a button over them.
There are two possible
pointer-sensitive:
•

ways

making

region

viewport

You can use the SET-POINTER-ACTION or SET-POJNTER-ACTION-PIXEL
function to define a rectangle within a viewport. Within this
rectangle, pointer movement triggers an interrupt function.
The first time the interrupt function executes, it changes the
appearance of the contents of the rectangle. You also need to
use SET-BUTTON-ACTION to establish an interrupt function to
execute if a pointer button is pressed while in the rectangle.
A second interrupt function executes when the pointer cursor
leaves the rectangle, restoring the original appearance.
A disadvantage of this method occurs when a viewport contains
many pointer-sensitive regions, as is the case with a large
menu.
Each pointer-sensitive region consumes system l/0
channels. In addition, data structures must be maintained for
each region.

•

A simpler and more economical alternative
is
to
use
SET-POINTER-ACTION and SET-BUTTON-ACTION just once for the
entire viewport. In your program, you lay out a number of
areas in the viewport, each containing an item.that you wish
to be pointer-sensitive.
Each time the pointer movement
5-15

POINTER OPERATIONS

interrupt function executes, it determines which region the
pointer is in, and highlights that region if it has not
already been highlighted. When the button interrupt function
executes, it alters a data structure to indicate the region it
occupies at that moment.

Example 5-6 shows the use of the second method outlined above to
implement a simple menu system. The function MENU either constructs
and displays a menu, or redisplays a menu that had previously been
constructed and returned by the function. Since the menu contains
only one column, the interrupt functions can determine the region
simply by finding the vertical location of the pointer cursor in the
viewport.
Example 5-6:

A Simple Menu System

(USE-PACKAGE "UIS")
'
,, We need
to remember the menu's window in the cases
;; when it has been made invisible.

(DEFSTRUCT (MENU
(:PREDICATE MENUP))
WINDOW
(RETURN-VALUE NIL)
)

;; Here's our function for drawing a box around an entry
;; (highlighting it), given th~ window entry,
;; its height and width.
(DEFUN MENU-BOX-PIXEL (W ATTR ENTRY ENTRY-HEIGHT ENTRY-WIDTH)
(LET* (
(LLX 0)
;; Lower left x position
(LLY (* ENTRY ENTRY-HEIGHT)) ;; Lower lefty position
(URX ENTRY-WIDTH)
;; Upper right x position
(URY (+ LLY ENTRY-HEIGHT))) '' Upper right y position
(PLOT-PIXEL W ATTR LLX LLY URX LLY URX URY LLX URY LLX LLY)))

;; We need to find out the size of the longest string in
;; the menu, so that the viewport size can be computed.
(DEFUN LONGEST (&REST ENTRIES)
(REDUCE #'(LAMBDA (LOCAL-MAX THIS-ENTRY)
(MAX LOCAL-MAX (LENGTH THIS-ENTRY)))
ENTRIES
:INITIAL-VALUE 0))
;; The different action functions use this function to get
;; the distance from the bottom of the menu.

5-16

POINTER OPERATIONS

Example 5-6 (cont.)

0 (DEFUN GET-POINTER-POSITION-Y-PIXEL (WINDOW)
(MULTIPLE-VALUE-BIND (X Y)
(GET-POINTER-POSITION-PIXEL WINDOW)
(DECLARE (IGNORE X))
Y))

; ; ;
; ; ;
; ;;
; ;i

The arguments to MENU will be an existing menu
structure, Tor NIL, and a number of strings.

;;i
;;i
; ; ;
;i ;

used but once).
Passing T means make a new menu that is made
invisible once selected from.
The strings will be the elements of the menu
along with "Exit menu"

Passing a old menu means you want to use it.
., ., ,. Passing
NIL means make a new menu (that can be

0 ,..., ,

(DEFUN MENU (OLD-MENU &REST GIVEN-ENTRIES)
(IF (MENUP OLD-MENU)
(IF (NOT (WINDOWP (MENU-WINDOW OLD-MENU)))
(ERROR "The given menu has been exited,
you must make a new menu")
(PROGN; Else make it visible
(MOVE-VIEWPORT (MENU-WINDOW OLD-MENU) :INVISIBLE NIL)
(SETF (MENU-RETURN-VALUE OLD-MENU) NIL)))
N

(LET*
((ENTRIES (CONS "Exit menu" GIVEN-ENTRIES))
(TEXT-ATTR-BLK 2)
(DISPLAY (CREATE-DISPLAY 0.0 0.0 4.0 5.0 4.0 5.0)))
;; Boldface text looks nice in menus
(SET-ATTRIBUTE DISPLAY O TEXT-ATTR-BLK :FONT '(:WEIGHT "p"))
(MULTIPLE-VALUE-BIND (CHAR-SIZE~X-CM CHAR-SIZE-Y-CM)
(MEASURE-TEXT DISPLAY TEXT-ATTR-BLK" ")
(LET*
;; Leave 2 characters of space on each side of the
;; longest entry
((MENU-WIDTH-CHARS(+ 4 (APPLY #'LONGEST ENTRIES)))
(MENU-WIDTH{* CHAR-SIZE-X-CM MENU-WIDTH-CHARS))
{MENU-HEIGHT{* CHAR-SIZE-Y-CM (LENGTH ENTRIES)))
{WINDOW {CREATE-WINDOW DISPLAY NIL NIL NIL NIL
:VIEWPORT-WIDTH MENU-WIDTH
:VIEWPORT-HEIGHT MENU-HEIGHT
:NOBANNER T)))
(MULTIPLE-VALUE-BIND (CHAR-SIZE-X-PIXELS ENTRY-HEIGHT)
{MEASURE-TEXT-PIXEL WINDOW
TEXT-ATTR-.BLK " ")

5-17

POINTER OPERATIONS

Example 5-6 (cont.)
(LET* (
(COMPLEMENT-ATTR-BLK 200)

;; We will use last-entry to keep trace of the
;; currently highlighted entry. A value of -1 means
;; no entry is highlighted.
(LAST-ENTRY -1)
(ONE-TIME (NOT (EQT OLD-MENU)))
(THIS-MENU (MAKE-MENU :WINDOW WINDOW))
(WINDOW-RIGHT-MARGIN(* MENU-WIDTH-CHARS
CHAR-SIZE-X-PIXELS))

;; The movement action finds where we are in the
;; viewport, what entry that corresponds to, highlights
;; the current entry and unhighlights the last entry if
;; they are different.
(MOVEMENT-I IF
(INSTATE-INTERRUPT-FUNCTION
# ' ( LAMBDA ( )
(LET ((Y (GET-POINTER-POSITION-Y-PIXEL WINDOW)))
(WHEN Y
(SETF Y (FLOOR Y ENTRY-HEIGHT))
(WHEN (NOT (EQ Y LAST-ENTRY))
(WHEN (NOT (EQ LAST-ENTRY -1))
(MENU-BOX-PIXEL
WINDOW COMPLEMENT-ATTR-BLK
LAST-ENTRY ENTRY-HEIGHT
WINDOW-RIGHT-MARGIN))
(MENU-BOX-PIXEL
WINDOW COMPLEMENT-ATTR-BLK
Y ENTRY-HEIGHT WINDOW-RIGHT-MARGIN)
(SETF LAST-ENTRY Y)))))))

;; The exit action unhighlights the current entry.
;; By racing the pointer very quickly across the menu, no
;; movement action may be recieved. So we need to check
;; to see if any entries are highlighted.
(EXIT-I IF
(INSTATE-INTERRUPT-FUNCTION
i ' ( LAMBDA ( )
(WHEN (NOT (EQ LAST-ENTRY -1))
(MENU-BOX-PIXEL
WINDOW COMPLEMENT-ATTR-BLK
LAST-ENTRY ENTRY-HEIGHT
WINDOW-RIGHT-MARGIN)
(SETF LAST-ENTRY -1)

5-18

POINTER OPERATIONS

Example 5-6 (cont.)
)) ))

;; If the mouse is moved very quickly, the button action
;; may try to get the current pointer position after we
; ; leave the menu's viewport. WHERE-WE-ARE is used. to
;; test this case. If this menu is to be used only once,
;; or the "Exit menu" entry is selected, then we uninstate
;; the various actions and delete the display.

(BUTTON-I IF
(INSTATE-INTERRUPT-FUNCTION
#'(LAMBDA (BUTTON-NUMBER TRANSITION)
(DECLARE (IGNORE BUTTON-NUMBER))
(WHEN (EQ TRANSITION NIL) ; Button released
(LET ((WHERE-WE-ARE
(GET-POINTER-POSITION-Y-PIXEL
WINDOW)))
(WHEN WHERE-WE-ARE
(LET ((THIS-ENTRY
(FLOOR WHERE-WE-ARE
ENTRY-HEIGHT)))
(WHEN(> THIS-ENTRY 0)
( SETF. (MENU-RETURN-VALUE THIS-MENU)
(ELT ENTRIES THIS-ENTRY)))

;; An alternative here would be to

;; not destroy the menu give the
;; selection "Exit menu"
(IF (OR ONE-TIME (EQ THIS-ENTRY 0))
(PROGN
(UNINSTATE-INTERRUPT-FUNCTION
MOVEMENT-I IF)
(UNINSTATE-INTERRUPT-FUNCTION
EXIT-I IF)
(SETF (MENU-WINDOW THIS-MENU) NIL)
(DELETE-DISPLAY DISPLAY))
(MOVE-VIEWPORT WINDOW :INVISIBLE T))

)) )
)))}
)

;; We use the complement-attr-blk for highlighting entries.
;; The :COMPLEMENT writing mode will both highlight an entry,
;; and unhighlight a highlighted entry.
(SETF (MENU-WINDOW THIS-MENU) WINDOW)

5-19

POINTER OPERATIONS

Example 5-6 (cont.)
(SET-ATTRIBUTE DISPLAY O COMPLEMENT-ATTR-BLK
:WRITING-MODE :COMPLEMENT)
(SET-ATTRIBUTE DISPLAY COMPLEMENT-ATTR-BLK COMPLEMENT-ATTR-BLK
:FONT "UIS$FILL_PATTERNS")
(SET-ATTRIBUTE DISPLAY COMPLEMENT-ATTR-BLK COMPLEMENT-ATTR-BLK
:FILL-PATTERN :FOREGROUND)

;; The entries are put up on the screen
(DO* ((THIS-ENTRY ENTRIES (CDR THIS-ENTRY))
(Y ENTRY-HEIGHT(+ Y ENTRY-HEIGHT)))
((NULL THIS-ENTRY))
(TEXT-PIXEL WINDOW TEXT-ATTR-BLK (CAR THIS-ENTRY)
(* 2 CHAR-SIZE-X-PIXELS) Y))

· ;; The action routines are set up,
(SET-POINTER-ACTION-PIXEL WINDOW MOVEMENT-IIF EXIT-IIF)
(SET-BUTTON-ACTION DISPLAY WINDOW BUTTON-IIF)
;; And the structure for this menu is returned, letting
;; you get the return value. Passing the menu structure
;; to this function again will put the menu back on the
;; screen if it was made invisible last time.

THIS-MENU
))))})}

;Another possiblity for the "exit menu" entry would have it
;just make the menu invisible. In that case one would add a
;DESTROY-MENU function that cleaned up the menu structure
;and actions.

0
5-20

0
CHAPTER 6
KEYBOARD INPUT

The VAX LISP graphics system provides a means for your program to
receive characters representing individual keystrokes from a keyboard
attached to a viewport.
The physical keyboard sends input to a
program through a virtual keyboard which is associated with a
viewport. From the user's point of view, the viewport to which the
keyboard is attached shows the keyboard icon indicating that it is the
active viewport. From the program's point of view, a particular
virtual keyboard is generating keystrokes. The program can either
define an interrupt function to receive keystrokes asynchronously, or
can read the keystrokes in a synchronous fashion.

0 This chapter treats keyboard input in the following sections:

•

Section 6.1 describes virtual keyboards
create them and attach them to windows.

and

shows

•

Section 6.2 explains how to capture and
from a keyboard.

int~rpret

how

keystrokes

For the purposes of this chapter, the term keyboard refers to a
virtual keyboard.
The term physical keyboard refers to the keyboard
on which you type.

6.1

VIRTUAL KEYBOARDS

A virtual keyboard is a LISP object that you create with the CREATE-KB
function.
It forms the link between the physical keyboard and your
program.
Although there is only
one
physical
keyboard
per
workstation, you can have any number of virtual keyboards.

0
6-1

KEYBOARD INPUT
6.1.1

Using Virtual Keyboards:

An Overview

The first step in using a virtual keyboard is creating
CREATE-KB function creates and returns a virtual keyboard:

it.

Theo

{SETF *KB* {CREATE-KB))
The next step is to associate the keyboard
ENABLE-VIEWPORT-KB function does this:

with

viewport.

The

{ENABLE-VIEWPORT-KB *KB* *INPUT-WINDOW*)
When you associate a virtual keyboard with a viewport,
appears in the right corner of the viewport's-banner:

icon

0
Th_i_s icon ind_icates to the user that the _physical keyboard .can_ .be
attached to this viewport.
From the software point of view, the
viewport is added to an assignment list of viewports that can have the
physical keyboard attached to them. The CYCLE key (function key FS)
attaches the physical keyboard to each viewport on the assignment list
in turn.
When the physical keyboard is attached to the viewport, the KB icon i s Q
highlighted:

This indicates that keystrokes will now be directed
virtual keyboard associated with this viewport.

through

the

NOTE

If a call to CREATE-WINDOW includes :NOKB-ICON T, the
associated viewport will be unable to acquire a KB
icon. It can still, however, have a virtual keyboard
associated with it.
Figure 6-1 illustrates the sequence of events just described.

0
6-2

KEYBOARD INPUT

1NPUTWINDoW•

•1NPUTWINDOW"

·Ks·----:r---- ---,

~------"

(SETF *KB* (CREATE-KEYBOARD))

,,,

"JNPUTWINDOW"

:-- ....... _

•Ks·~

--- .....

"--------J

,._

•Ks·~

............... _,.

L-------..1

(ENABLE-VIEWPORT-KB
*KB* *INPUT-WINDOW*)

0
(ENABLE-KB *KB*)
ML0·216-B6

Figure 6-1:

Creating and Attaching Virtual Keyboards

A virtual keyboard associated with a viewport to which the physical
keyboard is attached is said to be active.
This implies the
following:

•

Keyboard characteristics of the virtual keyboard (established
with the SET-KB-ATTRIBUTES function) are imposed on the
physical keyboard.

Keystrokes on the physical keyboard are delivered through the
virtual keyboard to your program.
That isq an interrupt
function specified for this virtual keyboard
with
the
SET-KB-ACTION function will execute every time a key is
struck. (See Section 6.2 for information on capturing and
interpreting keystrokes.)

The ENABLE-KB function makes a particular virtual keyboard the active
keyboard.
It is equivalent to the user associating the physical
keyboard with a viewport by pressing the CYCLE key or by pressing a
pointer button. Use ENABLE-KB when you want to control which viewport
the physical keyboard is connected to. Otherwise, let the user select
the viewport with the CYCLE key or pointer.
virtual keyboard can be associated with more than one viewport.
(A
viewport cannot, however, have more than one keyboard associated with
it.) Consider this extension of the example presented above:.

(ENABLE-VIEWPORT-KB *KB* *WINDOW-2*)
6-3

KEYBOARD INPUT

Now both *INPUT-WINDOW* and *WINDOW-2* are associated with the
keyboard *KB*. Whenever *KB* becomes the active keyboard, through any
means, the KB icon in both viewports will be highlighted.
Both
viewports have entries on the assignment list; that is, the CYCLE key.
will assign the physical keyboard to first one, then the other.
However, whenever the physical keyboard is assigned to either, the KB
icons in both will be highlighted.

It is important to note that the association of a virtual keyboard
with a viewport makes no provision for the echoing of characters typed
through that virtual keyboard, or for a cursor in the viewport. It is
the responsibility of your program to take the appropriate response to
input. Unless you set up an interrupt function to receive the
keystrokes, they will be lost. Section 6.2 contains more information
about this.

6.1.2

Creating and Deleting Virtual Keyboards

The CREATE-KB function creates and returns a virtual keyboard object.
The keyboard returned by CREATE-KB is not associated with any viewport
when it is created; you must do that later.
The DELETE-KB function deletes a virtual keyboard object.
Since
virtual keyboard objects consume system resources, you should take
care to delete them when you no longer need them.

If you delete a keyboard that is currently associated with a viewport
or with the physical keyboard, those associations are terminated.

6.1.3

Associating Keyboards with Viewports and the Physical Keyboard

Before you can receive any input from a virtual keyboard,
associate it with a viewport. Two functions do this:

you

must

•

The ENABLE-VIEWPORT-KB function associates the keyboard named
in its first argument with the viewport corresponding to the
window named in its second argument.

•

The ENABLE-KB function's primary purpose is to make a keyboard
the active keyboard.
However, it takes an optional window
argument which, if supplied, associates the keyboard with the
corresponding viewport.

Associating a keyboard with a viewport causes any keyboards that were
previously associated with that viewport to become dissociated. You
can also use the DISABLE-VIEWPORT-KB function to explicitly dissociate.
a viewport and keyboard.

6-4

KEYBOARD INPUT

Once associated with. a viewport, a keyboard can become active
(associated with the physical keyboard) through user action or under
program control:
•

The user can make a keyboard active either by pressing the
CYCLE key repeatedly, or hy moving the pointer cursor into a
viewport and pressing the left pointer button.
(The second
method does not work if the default button action has been
superseded for that window; see Chapter 5.)

•

The program can use the ENABLE-KB function to make a
keyboard active.

specific

Either the user or the program can make a virtual keyboard inactive.
The user can press the CYCLE key or use the pointer to make another
keyboard active; or the program can use the DISABLE-KB function.
functions let you find out if a virtual keyboard is active, and
0 Three
respond to a keyboard's becoming active and inactive:
•

The TEST-KB function returns T if the keyboard named
argument is connected to the physical keyboard,
otherwise •

•

The SET-GAIN-KB-ACTION
and
SET-LOSE-KB-ACTION
functions
specify actions to take when a specified virtual keyboard
becomes active and inactive, respectively. The action can be
an interrupt function or NIL to specify no action.

Setting Keyboard Attributes

6.1.4

in its
and NIL

Each virtual keyboard has associated with it a set of keyboard
attributes.
These attributes are imposed on the physical keyboard
when the virtual keyboard becomes active.
The attributes are the
following:
•

Autorepeat controls whether keys on the
generate a character when held down.

keyboard

repeatedly

•

Two keyclick attributes control whether,
click sounds when a key is pressed.

and

loudly,

•

Seven key group enabling and disabling attributes control
whether keys in the following groups can generate keystrokes:
Function keys F6 through F10
Function keys F11 through F14
Function keys F17 through F20
The HELP and DO keys

6-5

how

KEYBOARD INPUT

The six editing keys below the HELP and DO keys
The arrow keys
The numeric keypad keys

You set virtual keyboard attributes with the
SET-KB-ATTRIBUTES
function.
The first argument to SET-KB-ATTRIBUTES is a virtual
keyboard; the remaining arguments are keyword-value pairs
that
identify the attribute and its setting.
The GET-KB-ATTRIBUTE function returns the value of a particular
attribute, and the GET-KB-ATTRIBUTE-LIST function returns a list of
all the keyboard attributes and their settings for a specified virtual
keyboard.

6.2

CAPTURING AND INTERPRETING KEYSTROKES

This section explains how to receive and interpret input from a
virtual keyboard.
Section 6.~.lshows how to establish an interrupt
function to handle keystrokes.
Section 6. 2 .-2 shows how to read
keystrokes from a virtual keyboard synchronously.
Section 6.2.3
describes the values that VAX LISP uses to designate each key.

0
To receive asynchronous input from a virtual keyboard, you must
6.2.1

Keyboard Interrupt Functions

establish an interrupt function that will execute each time a keyboard
key is pressed.
The SET-KB~ACTION function establishes such an
interrupt function for a specified virtual keyboard. The interrupt
function receives at least two arguments:
a character or integer
designating the key that was struck,and a state flag. (The state flag
is reserved for future use; you can ignore it.) You can supply
additional arguments with the call to INSTATE-INTERRUPT-FUNCTION that
defines the interrupt function.

Section 6.2.3 explains the first argument that is passed to a keyboard
interrupt function.

6.2.2

Reading Keyboard Input Synchronously

You can also read individual keystrokes from a virtual keyboard in a
synchronous fashion by using the READ-KB-CHAR function. This function
returns the next character or integer from a specified keyboard.
If
no keystroke is available, READ-KB-CHAR does not return until one
becomes available.

0
6-6

KEYBOARD INPUT

Section 6.2.3
function.

6.2.3

explains

the

value

returned

the

READ-KB-CHAR

Characters Generated by Keys

For all the printing and control keys, the character received by a
keyboard interrupt function is the LISP character corresponding to
that key. However, some keys on the LK201 keyboard do not transmit
single characters.
These keys include the function keys, the arrow
keys, the editing and numeric keypad keys, and the HELP and DO keys.
Pressing these keys causes an integer to be generated by the virtual
keyboard instead of a character. VAX LISP defines constants for each
of these integers.
Table 6-1 lists the constants corresponding to
each key. Note that these constants are in a package called SMG.

Table 6-1:

LISP Constants Corresponding to LK201 Keys

Constant

Key

Numeric Keypad Keys

keypad 0
keypad 1
keypad 2
keypad 3
keypad 4
keypad 5
keypad 6
keypad 7
keypad 8
keypad 9
keypad keypad,
keypa,d
keypad Enter
keypad PFl
keypad PF2
keypad PF3
keypad PF4

SMG:K-TRM-KPO
SMG:K-TRM-KPl
SMG:K-TRM-KP2
SMG:K-TRM-KP3
SMG:K-TRM-KP4
SMG:K-TRM-KPS
SMG:K-TRM-KP6
SMG:K-TRM-KP7
SMG:K-TRM-KP8
SMG:K-TRM-KP9
SMG:K-TRM-MINUS
SMG:K-TRM-COMMA
SMG:K-TRM-PERIOD
SMG:K-TRM-ENTER
SMG:K-TRM-PF1
SMG:K-TRM-PF2
SMG:K-TRM-PF3
SMG:K-TRM-PF4

Function, Help, and Do Keys
F6
F7
F8

F10
F11
F12

SMG:K-TRM-F6
SMG:K-TRM-F7
SMG:K-TRM-F8
SMG:K-TRM-F9
SMG:K-TRM-F10
SMG:K-TRM-F11
SMG:K-TRM-F12

6-7

KEYBOARD INPUT

Table 6-1 (cont.)

Key

Constant

Fl3
Fl4
F15 (Help)
Fl6 (Do)
Fl7
F18
F19
F20

SMG:K-TRM-Fl3
SMG:K-TRM-F14
SMG:K-TRM-HELP
SMG:K-TRM-DO
SMG:K-TRM-F17
SMG:K-TRM-F18
SMG:K-TRM-F19
SMG:K-TRM-F20

Editing and Arrow Keys
El (Find)
E2 (Insert Here)
E3 (Remove)
E4 (Select)
E~ (Prev Screen)
E6 (Next Screen)
Up Arrow
Down Arrow
Right Arrow
Left Arrow

SMG:K-TRM-FIND
SMG:K-TRM-INSERT-HERE
SMG:K-TRM-REMOVE
SMG:K-TRM-SELECT
SMG:K-TRM-PREV-SCREEN
SMG:K-TRM-NEXT-SCREEN
SMG:K-TRM-UP
SMG:K-TRM-DOWN
SMG:K-TRM-RIGHT
SMG:K-TRM-LEFT

0
6-8

0
CHAPTER 7
WINDOW OUTPUT STREAMS

The VAX LISP graphics system allows you to create a LISP output stream
to a window. Output directed to this stream by any of the normal LISP
output functions is displayed in the window's associated viewport.
You can control the portion of the viewport in which output is
displayed, and the way in which horizontal and vertical overflow are
treated.
You can also specify an attribute block to be used with the
stream, allowing you to control the font and writing mode.
This chapter is divided as follows:

0 7.1

•

Section 7.1 shows how to create and use window output streams.

•

Section 7.2 shows how to alter the characteristics of a window
output stream.

•

Section 7.3 explains interactions between window
output
streams and other parts of the VAX LISP grap~ics system.

CREATING AND USING WINDOW OUTPUT STREAMS

One function and one macro create window output streams.
The
MAKE-WINDOW-OUTPUT-STREAM function creates and returns a window output
stream. The WITH-OUTPUT-TO-WINDOW macro creates a window output
stream and binds a variable to it while the forms in the macro's body
execute. When the body terminates, WITH-OUTPUT-TO-WINDOW closes the
window output stream.
Neither MAKE-WINDOW-OUTPUT-STREAM nor WITH-OUTPUT-TO-WINDOW creates a
window object.
Both take window objects as arguments and create a
stream associated with that window. When the stream is closed, the
window is not affected.

Once you have created a window output stream, you can use it with apy
of the COMMON LISP output functions that take a stream argument.
7-1

WINDOW OUTPUT STREAMS

Characters output to the stream will appear in the window's viewport.
The first output to the stream appears in the upper-left corner of the
viewport,-with subsequent output appended to the first output or on a
line below it, depending on the LISP output function used.

MAKE-WINDOW-OUTPUT-STREAM and WITH-OUTPUT-TO-WINDOW both take keyword
arguments that control the characteristics of the window output
stream. The keywords, and the characteristics they control, are:
•

:VIEWING-AREA -- controls the area of the viewport in which
output text is displayed. By default, the entire viewport is
used. To specify the viewing area, supply a list in the form
(xl yl x2 y2), giving the device coordinates of a rectangle in
the viewport. If you specify a viewing area, initial text
output takes place in the upper-left corner of the viewing
area.
You can create multiple streams to the same window, with each
stream having its own viewing area. __This provides a facility
similar to scrolling areas on a video terminal.

•

:HORIZONTAL-OVERFLOW -- controls the behavior when an output
operation attempts to write text beyond the right edge of the
viewing area. The value can be :TRUNCATE, causing characters
to be dropped, or :WRAP, causing characters to be wrapped onto
the next line. Excess characters are wrapped by default.
Text is truncated or wrapped until the stream encounters a
#\NEWLINE character.

:VERTICAL-OVERFLOW -- ·controls the behavior when an output
operation attempts to write text below the bottom of the
viewing area. The value can be :SCROLL, indicating that lines
be scrolled upwards to accomodate the new line, or :WRAP,
indicating that text be vertically wrapped, with the new line
replacing the line at the top of the screen. Text is scrolled
by default.
.

:ATTRIBUTE-BLOCK -- designates the attribute block used for
text output. By default, text is written with attribute block
0. However, if you have created a new attribute block for the
display· associated with the output window, you can specify
that attribute block with this keyword.
By specifying a
different attribute block, you can change the font and writing
mode used to output text.

The ERASE-VIEWING-AREA function erases anything within the .viewing
area of a window output stream, and resets the text position to the
upper-left corner of the viewing area.

0
7-2

WINDOW OUTPUT STREAMS
7 .2

ALTERI NG WINDOW OUTPUT STREAMS

0 Once
a window output stream has been created, you can alter any of the
characteristics that you established when you created it.
The
following sections show how to do this:

7.2.1

•

Section 7.2.1 shows how to change the viewing area.

•

Section
7.2.2
characteristics.

•

Section 7.2.3 shows how to change the attribute block used
write output through the stream.

shows

how

change

the

· overflow
to

Changing the Viewing Area

0 The WINDOW-STREAM-VIEWING-AREA function returns the viewing area for a
particular window output stream. You can use SETF with this function
to change the viewing area. Use the same format that you would with
the :VIEWING-AREA keyword to MAKE-WINDOW-OUTPUT-STREAM; that is, a
list of device coordinates in the form (x! y! x2 y2).

Whenever you change a window output stream's viewing area, the
stream's current writing position (that is, where the next text will
be written) is set to the upper-left corner of the new viewing area,
and the new viewing area is erased.
·

The viewing area of a window output stream is not automatically
resized when the user resizes the associated viewport. For example,
if you set up a window output stream without a speci~ic viewing area
that is, the viewing area consists of the entire viewport -- and
the user enlarges the viewport, your window output stream still
displays and scrolls within the bounds of the original viewport.
Similarly, if the user shrinks the viewport, text can be lost beyond
the upper and right borders of the viewport. To avoid this problem,
you can use the SET-RESIZE-ACTION function to establish an interrupt
function to be called when the user resizes the viewport. The
interrupt function can resize the viewing area appropriately. Example
7-1 shows how you can do this.
Example 7-1:

Resizing the Viewing Area Automatically

(DEFUN MAKE-RESIZABLE-WINDOW-OUTPUT-STREAM (WINDOW)
(LET* ((STR (MAKE-WINDOW-OUTPUT-STREAM WINDOW))
(RESIZE-IIF (INSTATE-INTERRUPT-FUNCTION
#'RESIZE-VIEWING-AREA
:ARGUMENTS (LIST STR))))
(SET-RESIZE-ACTION NIL WINDOW RESIZE-IIF)
STR))
7-3

WINDOW OUTPUT STREAMS

Example 7-1 (cont.)
(DEFUN RESIZE-VIEWING-AREA (NEW-SCREEN-X NEW-SCREEN-Y
NEW-WIDTH NEW-HEIGHT
Xl Yl X2 Y2
STR)
(MULTIPLE-VALUE-BIND (JUNK-1 JUNK-2 H-RES V-RES)
(GET-DISPLAY-SIZE)
(DECLARE (FLOAT H-RES V-RES)
(IGNORE JUNK-1 JUNK-2))
(SETF (WINDOW-STREAM-VIEWING-AREA STR)
(LIST O O
(FLOOR(* H-RES NEW-WIDTH))
; New viewport size
(FLOOR(* V-RES NEW-HEIGHT)))))) ; in pixels
(RESIZE-WINDOW NIL (WINDOW-STREAM-WINDOW STR)
NEW-SCREEN-X NEW-SCREEN-Y NEW-WIDTH NEW-HEIGHT
·xl Yl X2 Y2 ) )

7 .2.2

Changing Overflow Behavior

You can change the way a window output stream behaves when text
overflows either the right or bottom edge of the viewing area. The
WINDOW-STREAM-HORIZONTAL-OVERFLOW
function
returns
the
current
horizontal overflow behavior of a window stream in the form of a
keyword, either :TRUNCATE or :WRAP. Use SETF with this function to
change the behavior, specifying the appropriate keyword as the new
value.
Similarly,
WINDOW-STREAM-VERTICAL-OVERFLOW
returns
the
vertical overflow behavior, either :SCROLL or :WRAP. You can also use
SETF with this function to change the behavior.

7.2.3

Changing the Attribute Block

A window output stream writes text to a window through an attribute
block.
The significant attributes are :FONT and :WRITING-MODE. (Two
other attributes, :LEFT-MARGIN-PIXEL and :CHARACTER-SPACING,
are
ignored.) You can specify an attribute block at the time the stream is
created. You can also change the attribute block used by an existing
stream.

The WINDOW-STREAM-ATTRIBUTE-BLOCK function returns the attribute block
used by a window output stream. You can use SETF with this function
to specify a new attribute block. The new attribute block must be
associated with the window stream's virtual display.

0
7-4

WINDOW OUTPUT STREAMS
NOTE

Changing the size of the font in which text is written
may cause vertical interference between characters on
consecutive lines.
You should use caution when making changes (using SET-ATTRIBUTE) to an
attribute block used by a window output stream. Changing an attribute
block in this way can cause unpredictable results in the window output
stream.
If you make changes to an attribute block, use SETF with the
WINDOW-STREAM-ATTRIBUTE-BLOCK function immediately afterwards.
This
allows the window output stream to adjust to the changes in the
attribute block.

0 7.3

WINDOW OUTPUT STREAMS AND OTHER GRAPHICS FUNCTIONS

This section contains information on how window output
interact with other features of the VAX LISP graphics system.

7 .3.1

streams

Window Text Position

Owindow output streams write text to. windows using the TEXT-PIXEL
function.
Each use of TEXT-PIXEL moves the window text position for
all windows into a virtual display to the end of the text just
written.
Therefore, if you have several windows into a virtual
display, and one of those windows has a window output stream
associated with it, use of that stream will cause the window text
position to be changed for all windows into the virtual display.
O

However, each window output stream maintains its own current writing
position. Therefore, you can have multiple window output streams into
a single window or into multiple windows on the same virtual display
without interference.

7.3.2

Vertical Scrolling and Erasing

Window output streams use MOVE-AREA-PIXEL to scroll text upward.
MOVE-AREA-PIXEL moves everything in the viewport, no matter how it got
there. This means that graphic information, such as lines, that you
may have placed in the viewport will be scrolled along with the text.
If the graphic information is encoded in the display list, it will
reappear the next time the display list is executed, for example when
the user resizes the viewport.

,:;

7-5

... ,

WINDOW OUTPUT STREAMS

In the same way, ERASE-VIEWING-AREA uses ERASE-PIXEL to
viewing area. Everything in the viewing area is erased.

7 .3.3

erase

the

Display List

Since window output streams write text with TEXT-PIXEL,
modify the display list.

they

not

0
7-6

PARJ II
GRAPHICS SYSTEM COMPONENTS

GRAPHICS SYSTEM COMPONENTS
BEGIN-SEGMENT Function

0 Begins
a new segment.
The contents of all attribute blocks are
propagated to the new segment.
Changes to attribute blocks made
during segment creation are cancelled when the segment ends, and the
original settings are restored. A segment is terminated by a call to
END-SEGMENT.
See Section 3.7 for more information on segments.
Format
UIS:BEGIN-SEGMENT display

Arguments

display
A virtual display

Return Value
Undefined

Corresponding MicroVMS Routine

UIS$BEGIN_SEGMENT
BITBLT Function

Performs the operation specified by its argument, which must be a
BITBLT object. See the description of the MAKE-BITBLT function for a
description of the operation.

Q This function is in package LISP.
Format
LISP:BITBLT bitblt

Arguments

bitblt
An object of type BITBLT

Return Value

Undefined

GRAPHICS, SVSTEM"<-COIViPONENTS

Corresponding MicroVMS Routine

None
BITBLT Type Specifier

Designates objects of type BITBLT; these objects represent specific
cases of moving and modifying a block of bits. When supplied as the
argument to the BITBLT function, an object of type BITBLT causes a
specific operation to be performed on a specific bitmap. BITBLT
objects can be created as needed with the MAKE-BITBLT function.
To
perform identical or similar operations on different bitmaps, a BITBLT
object can be modified with any of a number of accessor functions and
reused.
The various parameters and operations specified by an object
BITBLT are described with the MAKE-BITBLT function.

type

BITBLT Accessor Functions

BITBLT-DESTINATION
BITBLT-DST-W
BITBLT-SOURCB
BITBLT-SRC-W

BITBLT-DST-X
BITBLT-DST-H
BITBLT-SRC-X
BITBLT-SRC-H
BITBLT-TBXTURB

BITBLT-DST-Y
BITBLT-DST-OP
BITBLT-SRC-Y
BITBLT-SRC-OP

0
These accessor functions return the indicated component of their
argument, which must be a BITBLT argument. They can also be used with
SETF to modify that component bf their argument. See the description
of MAKE-BITBLT for descriptions of these components.
These functions are in package LISP.

Format
LISP:BITBLT-xxx bitblt

Arguments
bitblt
An

object of type BITBLT

Return Value
The indicated component of the BITBLT object

Corresponding MicroVMS Routines

None
2

· ·GR·APHICS SYSTEM· COMPONENTS
BITBLT-P Function

Returns T if its argument is a BITBLT object and NIL otherwise.
function is in package LISP.

This

Format
LISP:BITBLT-P object

Arguments
object

Any LISP object

Return Value

Tor NIL

Corresponding KicroVMS Routine
None
BITMAP-P Function

Returns T if its argument is a two-dimensional array of unsigned
bytes, suitable for use with the BITBLT and IMAGE functions, and NIL
otherwise.
This function is in package LISP.

Format

LISP:BITMAP-P object

Arguments
object
Any LISP object

Return Value
Tor NIL

Corresponding KicroVMS Routine
None

0
3

GRAPHICS SYSTEM COMPONENTS
CIRCLE Function

Draws a circle or arc in a virtual display. Calls to this function
draw a full circle unless the optional start-radians and end-radians
arguments are specified. If these arguments are included, CIRCLE
draws an arc from start-radians counterclockwise to end-radians. The
radian start and end positions are measured from the right-hand
intersection of the circle and its horizontal diameter.

For more information on drawing circles, see Section 3.5.2.
Format
UIS:CIRCLE display att-block center-x center-y radius
&OPTIONAL start-radians end-radians
Arguments

display
A virtual display or transformation
att-block
A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

center-x center-y
Two single floats designating, in world coordinates,
of the circle or arc
·

the

center

arc

radius
A single float designating the radius of the
world-coordinate units

circle

start-radians
single float designating the starting position of the circle in
radians. If this argument is NIL or omitted, it defaults to 0.0.

end-radians
A single float designating the end position of the circle in
radians. If this argument is NIL or omitted, the end position is
at 2*PI.

Return Value
Undefined

0
4

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS.Routine

UIS$CIRCLE
CIRCLE-PIXEL Function

Draws a circle or arc in a window. Calls to this function draw a full
circle unless the optional start-radians and end-radians arguments are
specified. If these arguments are included, CIRCLE-PIXEL draws an arc
from start-radians counterclockwise to end-radians. The radian start
and end positions are measured from the right-hand intersection of the
circle and its horizontal diameter.
For more information on drawing circles, see Section 3.5.2.

Format
UIS:CIRCLE-PIXEL window att-block center-x center-y radius
&OPTIONAL start-radians end-radians
Arguments
window
A window

0 att-block

A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

center-x center-y

Two fixnums designating, in device coordinates, the center of the
circle or arc
radius
A fixnum designating the
device-coordinate units

radius

the

circle

arc

start-radians
A single float designating the starting position of the circle in
radians. If this argument is NIL or omitted, it defaults to 0.0.
end-radians

A single float designating the end position of the circle in
radians. If this argument is NIL or omitted, the end position is
at 2*PI.
5

--------------------------------------------

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding MicroVMS Routine
UISDC$CIRCLE
COMPARE-BITMAPS Function

Returns T as its first value if the two bitmap arrays given as its
arguments are identical in dimensions and contents, and NIL otherwise.
If the two arrays are not identical, the function's second and third
return values give more information about the differences. The two
bitmaps are compared in row-major order, that is, with the rightmost
index varying the most quickly.
This function is in package LISP.
Format
LISP:COMPARE-BITMAPS bitmap! bitmap2
Arguments

bitmap! bitmap2
Two bitmap arrays
Return Value
Three values:
1.

T if the two bitmap arrays are identical
contents, and NIL otherwise

dimensions

T if the two bitmap arrays differ in dimensions, and the
index number of the row containing the first different bit
otherwise

The index number of the column containing the first different
bit

and

Corresponding MicroVMS Routine
None

0
6

GRAPHICS SYSTEM COMPONENTS
COPY-BITBLT Function

0 Creates
and returns a new BITBLT object that has the same effect as
the function's argument.
The new BITBLT object shares destination,
source, and texture bitmap arrays with its argument, but the remaining
components of the argument are copied. Thus, destructive changes to
the new object do not affect the original object.
This function is in package LISP.
Format
LISP:COPY-BITBLT bitblt
Arguments

bitblt
An object of type BITBLT

Return Value
A new object of type BITBLT
Corresponding MicroVMS Routine

None
CREATE-DISPLAY Function

Creates a UIS virtual display and returns the display object.
more informatin about virtual displays, see Section 2.3.

For

Format
UIS:CREATE-DISPLAY x1 y1 x2 y2 width height
Arguments
x1 y1
Single floats specifying the lower left
display's world coordinate space

corner

the

virtual

Single floats specifying the upper right corner
display's world coordinate space

the

virtual

x2 y2

0
7

GRAPHICS SYSTEM COMPONENTS

width height
Single floats specifying, in centimeters, the default width and
height of the virtual display when it appears on the output
device

Return Value
An object of type DISPLAY

Corresponding HicroVMS Routine
UIS$CREATE_DISPLAY
CREATE-KB Function

Creates and returns a virtual keyboard.
on using virtual keyboards.

See Chapter 6 for information

Format
UIS:CREATE-KB &OPTIONAL device
Arguments

device
A character string specifying the device on which the virtual
keyboard is to be created.
lf this argument is omitted, the
device defaults to SYS$WORKSTATION.
Return Value
A keyboard

Corresponding HicroVMS Routine
UIS$CREATE_KB
CREATE-TERMINAL Function

Creates a terminal emulation window of the specified type and
its device name string.

returns

0
8

GRAPHICS SYSTEM COMPONENTS

Format
UIS:CREATE-TERMINAL
&KEY :TYPE :BANNER-TITLE
:GENERAL-PLACEMENT :CENTER
:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
:NOBANNER :NOBORDER :NOKB-ICON
:NOMENU-ICON :ALIGNED
Arguments
:TYPE

A character string indicating the terminal type. The string
be "WT", indicating a VT100, or "TK", indicating a TEK4014.
default is a VT100 terminal emulator window.

can
The

:BANNER-TITLE
A character string specifying the terminal emulator
default depends on the terminal emulator type.

title.

The

:GENERAL-PLACEMENT

Either :TOP, :BOTTOM, :LEFT, or :RIGHT, indicating a general
preference for terminal emulator position on the screen; or a
list of two of these, for e~ample (:TOP :RIGHT); or NIL,
indicating no preference for general placement. The default is
NIL.
:CENTER

Tor NIL. If T, the terminal emulator will be centered at the
position
specified
by
:ABSOLUTE-POSITION-X
and
:ABSOLUTE-POSITION-Y. If NIL, the emulator's lower-left corner
will be aligned on that position. The default is NIL.
:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
Two single floats indicating, in centimeters, the terminal
emulator's displacement from the left and bottom edges of the
display screen. The value provided with the :CENTER keyword
determines
the placement of the emulator relative to the
:ABSOLUTE-POSITION values.
By default, the emulator is not
placed in an absolute screen location.
:NOBANNER

Tor NIL (the default), disabling or enabling a banner above
terminal emulator

the

GRAPHICS SYSTEM COMPONENTS

:NOBORDER
Tor NIL (the default), disabling or enabling a border around the
terminal emulator.
If :NOBORDER Tis specified, :NOBANNER is
forced to T.

:NOKB-ICON
Tor NIL (the default), specifying that the terminal emulator
should or should not be created without a KB icon in the upper
right-hand corner
:NOMENU-ICON
Tor NIL (the default), specifying that the terminal emulator
should or should not be created without a menu icon in the upper
left-hand corner
:ALIGNED

T (the default) or NIL, specifying that the terminal emulator's
left inner edge should or should not be aligned on byte
boundaries in video memory.
:ALIGNED T allows text drawing
optimizations.
Return Value
A character string that
emulator window

the

device

name

the

terminal

Corresponding MicroVMS Routine
UIS$CREATE_TERMINAL

CREATE-TRANSFORMATION Function

Creates a transformation into a virtual display and returns the
transformation object.
A transformation allows a program to write
into a virtual display using a coordinate system other than that
defined when the virtual display was created. A transformation object
can be used in place of the display argument for any function that
requires a virtual display as input.
See Section 2.5 for information on using transformations.
Format
UIS:CREATE-TRANSFORMATION display x1 y1 x2 y2
&OPTIONAL vd-x1 vd-y1 vd-x2 vd-y2

0
10

GRAPHICS SYSTEM COMPONENTS

Arguments

0 display

A display object
x1 y1 x2 y2
Four single floats designating two opposite corners
coordinate space

the

new

vd-x1 vd-y1 vd-x2 vd-y2
Four single floats designating, in the display's world coordinate
system, a rectangle that the new coordinate space will be mapped
onto. If these arguments are omitted, the new coordinate space
is mapped onto the entire virtual display.

0 Return Value

An object of type TRANSFORMATION

Corresponding HicroVHS Routine
UIS$CREATE_TRANSFORMATION

CREATE-UIS-STRUCTURE Function

Creates and returns the LISP representation for a virtual display, a
window, a virtual keyboard, or a transformation that has been created
outside of LISP. You can use CALL-OUT to call a Mic~oVMS workstation
graphics software routine or a routine written in another language.
Such a routine can create a display, window, transformation, or
virtual
keyboard,
and return the identifying integer to you.
CREATE-UIS-STRUCTURE takes this identifying integer and creates from
it the LISP representation of the object. This allows you to use
graphics objects created outside of LISP in a LISP program.
This function takes one keyword-value pair as its arguments, where the
keyword specifies the type of object you want to create and the value
is the identifying integer for that object. The exception is :WINDOW.
If you specify :WINDOW, you must also specify :DISPLAY with the
identifying integer for the display that the window maps into.
NOTE

Using this function can place LISP in an inconsistent
state.
Graphic objects created using the normal VAX
LISP CREATE- functions maintain some information-about
other graphic objects; for example, virtual displays
11

GRAPHICS SYSTEM COMPONENTS

keep a list of windows that map into them.
Objects
created with CREATE-UIS-STRUCTURE cannot maintain this
information correctly. They may behave unpredictably
with some functions.

Foll:'mat

UIS:CREATE-UIS-STRUCTURE
&KEY :WINDOW :DISPLAY :KEYBOARD :TRANSFORMATION
Arguments
:WINDOW
An integer that is the wd_id of the window you want to represent.
You must also use the :DISPLAY keyword when you use· :WINDOW.

:DISPLAY
An

integer that is the vd_id of the display you want to represent

:KEYBOARD
An integer that
represent

the

kb_id

the

keyboard ,you

want

:TRANSFORMATION
integer that is the tr_id of the transformation
represent

you

want

Return Value
The LISP representation of the specified object
Corresponding HicroVMS Routine

None
CREATE..WINDOW Function

Creates a window into a virtual display and a corresponding viewport
on the physical device, and returns the window. see Section 2.4 for
more information about windows.

0
12

GRAPHICS SYSTEM COMPONENTS

Format
UIS:CREATE-WINDOW display
&OPTIONAL x1 y1 x2 y2
&KEY :BANNER-TITLE :NOBANNER :NOBORDER
:NOKB-ICON :NOMENU-ICON :ALIGNED
:INVISIBLE :VIEWPORT-WIDTH :VIEWPORT-HEIGHT
:GENERAL-PLACEMENT :CENTER
:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
:DEVICE
Arguments
display
A virtual display into which the window is to be opened

0 xl yl x2

Four single floats, specifying (in world coordinates) the portion
of the virtual display to be mapped into.the viewport. If these
arguments are omitted or NIL, the window is mapped to the default
rectangle specified when the virtual display was created.
:BANNER-TITLE

A character string specifying a ~ame to be inserted into the
border of the viewport; the default is no title. If :NOBANNER T
is specified, :BANNER-TITLE is ignored.
:NOBANNER
Tor NIL (the default), disabling or enabling a banner above
viewport

the

0 :NOBORDER
Tor NIL (the default), disabling or enabling a border around the
viewport. If :NOBORDER Tis specified, :NOBANNER is forced to T.
:NOKB-ICON
Tor NIL (the default), specifying whether or not the viewport
will be able to acquire a KB icon at a later time. Even if a
viewport cannot acquire a KB icon, its window can still be
associated with a virtual keyboard. (See Chapter 6.)
:NOMENU-ICON

Tor NIL (the default), specifying that the viewport should or
should not be created without a menu icon in the upper left-hand
corner
13

GRAPHICS SYSTEM COMPONENTS

:ALIGNED
T (the default) or NIL, specifying that the viewport's left inner
edge should or should not be aligned on byte boundaries in video
memory. :ALIGNED Tallows text drawing optimizations.

:INVISIBLE
Tor NIL (the default), specifying whether the viewport should be
made visible on the display device when it is created. An
"invisible" viewport can be moved onto the display device with
MOVE-VIEWPORT at a later time.
:VIEWPORT-WIDTH
A single float specifying (in centimeters) the width of the
viewport on the display device.
If this argument is NIL or
omitted, viewport width is based on the width argument supplied
when the virtual display was created.

:VIEWPORT-HEIGHT
A single float specifying (in centimeters) the height of the
viewport on the display device.
If this argument is NIL or
omitted, viewport height is based on the height argument supplied
when the virtual display was created.
:GENERAL-PLACEMENT
Either :TOP, :BOTTOM, :LEFT, or :RIGHT, indicating a general
preference for viewport position on the screen; or a list of two
of these, for example (:TOP:RIGHT); or NIL, indicating no
preference for general placement. The default is NIL.
:CENTER
NIL (the default) or T. If T, the viewport will be centered over
the
position
specified
by
:ABSOLUTE-POSITION-X
and
:ABSOLUTE-POSITION-Y. If NIL, the viewport's lower-left corner
will be aligned on the position.

:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
Two single floats indicating, in centimeters, the viewport's
displacement from the left and bottom edges of the display
screen. The value provided with the :CENTER keyword determines
the placement of the viewport relative to the ABSOLUTE-POSITION
values. If these arguments are omitted or NIL, the viewport is
not placed in an absolute location.

0
14

GRAPHICS SYSTEM COMPONENTS

:DEVICE
A character string identifying the device on which the
is to be created. The default is "SYS$WORKSTATION".

viewport

Return Value
A window object
Corresponding MicroVMS Routine
UIS$CREATE_WINDOW
DELETE-DISPLAY Function

Deletes a virtual display. All associated windows and
also deleted, as are transformations into the display.

viewports

are

Format
UIS:DELETE-DISPLAY display
Arguments

display
A display object
Return Value
Undefined
Corresponding KicroVMS Routine

None
DELETE-KB Function

Deletes a virtual keyboard. If the specified keyboard is bound to
window or to the physical keyboard, those bindings are terminated.
Format
UIS:DELETE-KB keyboard
Arguments

keyboard
A keyboard
15

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding MicroVMS Routine
UIS$DELETE_KEYBOARD
DELETE-TRANSFORMATION Function

Deletes a transformation into a virtual display.
is not a_f f ected.

The virtual

display

Format
UIS:DELETE-TRANSFORMATION transformation

Arguments
transformation
A transformation object
Return Value

Undefined
Corresponding MicroVMS Routine
UIS$DELETE_TRANSFORMATION
DELETE-WINDOW Function

Deletes a window and removes its viewport from the screen.
The
associated virtual display is not affected. Any window output streams
that place text in the window are closed.

Format
UIS:DELETE-WINDOW window
Arguments
window
A window object
Return Value

Undefined
16

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS ~outine

UIS$DELETE_WINDOW
DISABLE-DISPLAY-LIST Function

Disables further additions to the display list for the specified
display until ENABLE-DISPLAY-LIST is executed. By default, a virtual
display's display list is disabled.
See Section 3.1 for more information about the display list.
Format
UIS:DISABLE-DISPLAY-LIST display

0 Arguments
display
A virtual display
Return Value
Undefined

0 Corresponding MicroVMS Routine
UIS$DISABLE_DISPLAY
DISABLE-KB Function

Disconnects the physical keyboard from the specified virtual keyboard.
Any
connections
between the virtual keyboard and windows are
unaffected.
Format
UIS:DISABLE-KB keyboard
Arguments
. keyboard

A keyboard
Return Value

Undefined

GRAPHICS SYSTEM COMPONENTS

Corresponding KicroVHS Routine

UIS$DISABLE_KB
DISABLE-VIEWPORT-KB Function

Disables the specified window from being assigned a keyboard.

Format
UIS:DISABLE-VIEWPORT-KB window

Arguments
window

A window

Return Value
Undefined

Corresponding KicroVHS Routine
UIS$DISABLE_VIEWPORT_KB

DISPLAV Type Specifier

Designates objects of type
function.

DISPLAY,

created

the

CREATE-DISPLAY

DISPLAVP Function

Returns T if
otherwise.

its

argument

virtual

display

object

and

NIL

Format
UIS:DISPLAYP object

Arguments
object
Any LISP object

Return Value

T or NIL
18

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVKS.Routine

None
DISPLAY-WINDOWS Function

Returns a list of the windows that map into a specified display.
Format
UIS:DISPLAY-WINDOWS display
Arguments
display

A virtual display
Return Value
A list of the windows that map into display
Corresponding MicroVKS Routine

None
DUMP-BITMAP Function

Writes a binary file containing the size and contents of a bitmap
array. The file may later be retrieved with the LOAD-BITMAP function.
This function is in package LISP.

Format
LISP:DUMP-BITMAP bitmap pathname
Arguments

bitmap
A bitmap array

pathname
A pathname, string, stream, or symbol
Return Value

Undefined
19

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

None
ELLIPSE Function

Draws an ellipse or a partial ellipse in a virtual display. Calls to
this function draw a full ellipse unless the optional start-radians
and end-radians arguments are specified.
If these arguments are
included,
ELLIPSE
draws
a partial ellipse from start-radians
counterclockwise to end-radians. The radian start and end positions
are measured from the right-hand intersection of the ellipse and its
horizontal axis.
For more information on drawing ellipses, see Section 3.5.2.

Format
UIS: ELLIPSE display att-block center-x center-y x-radi-us y-radius
&OPTIONAL start-radians end-radians
Arguments
display

A virtual display or transformation
att-block
A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

center-x center-y
Two single floats designating, in world coordinates,
of the ellipse

the

center

Two single floats designating, in the world coordinate
the
radius
of the ellipse along its x-axis and
respectively

system,
Y-axis,

x-radius y-radius

start-radians
A single float designating the starting postion of the ellipse in
radians. If this argument is NIL or omitted, the default is 0.0.

0
20

GRAPHICS SYSTEM COMPONENTS

end-radians

A single float designating the end position of the ellipse
radians. If this argument is omitted, the default is 2*PI.

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$ELLIPSE
ELLIPSE-PIXEL Function

Draws an ellipse or a partial ellipse in a window.
Calls to this
function draw a full ellipse unless the optional start-radians and
end-radians arguments are specified. If these arguments are included,
ELLIPSE-PIXEL
draws
a
partial
ellipse
from
start-radians
counterclockwise to end-radians. The radian start and end positions
are measured from the right-hand intersection of the ellipse and its
horizontal axis.
For more information on drawing ellipses, see Section 3.5.2.

Q Format
UIS:ELLIPSE-PIXEL window att-block center-x center-y
x-radius y-radius
&OPTIONAL start-radians end-radians
Argwnents

window
A window

att-block
A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

center-x center-y
Two fixnums designating, in device coordinates, the center of the
ellipse
x-radius y-radius

Two fixnums designating, in device-coordinate units, the
of the ellipse along its x-axis and Y-axis, respectively

radi~s

-------------------------------

GRAPHICS SYSTEM COMPONENTS

start-radians
A single float designating the starting postion of the ellipse in
radians. If this argument is NIL or omitted, the default is 0.0.

end-radians
A single float designating the end position of the ellipse
radians. If this argument is omitted, the default is 2*PI.

Return Value
Undefined

Corresponding KicroVMS Routine
UISDC$ELLIPSE

ENABLE-DISPLAY-LIST Function

Commences or resumes additions to the display list for the specified
display.
By default, a virtual display's display list is disabled.
(See also DISABLE-DISPLAY-LIST.)
Calls to device-coordinate functions (whose names end in -PIXEL) never
add to the display list, even if it is enabled.

See Section 3.1 for more information about the display list.

Format
UIS:ENABLE-DISPLAY-LIST display

Arguments

display
A virtual display

Return Value
Undefined

Corresponding KicroVMS Routine
UIS$ENABLE_DISPLAY_LIST

0
22

, GRAPHICS SYSTEM COMPONENTS
ENABLE-KB Function

Connects the physical keyboard to the specified virtual keyboard.
If
a window argument is also given, this function additionally executes
the ENABLE-VIEWPORT-KB function; that is, it enables the specified
window to be assigned a keyboard, then connects the virtual keyboard
to the window.
Format
UIS:ENABLE-KB keyboard &OPTIONAL window
Arguments

keyboard

A keyboard

window
A window. If this argument is omitted, the virtual keyboard is
not connected to any new window, although·it remains connected to
any window(s) to which it was previously connected •
. Return Value

Undefined
Corresponding MicroVMS Routine
UIS$ENABLE_KB
ENABLE-VIEWPORT-KB Function

the specified window to be assigned a keyboard, then connects
0 Enables
the specified virtual keyboard to the window.
Format
UIS:ENABLE-VIEWPORT-KB keyboard window
Arguments

keyboard
A virtual keyboard to be connected to the window
window

A window

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding MicroVMS Routine
UIS$ENABLE_VIEWPORT_KB
END-SEGMENT Function

Ends the segment most recently begun in the specified virtual display.
The values of attributes in all attribute blocks are restored to what
they were when the segment was begun. (See also BEGIN-SEGMENT.)
See Section 3.7 for information about segments.

Format
UIS:END-SEGMENT display
Arguments

display
A virtual display

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$END_SEGMENT

ERASE Function

Erases a virtual display or a specified portion of a virtual display.
The display list is updated by removing all primitives that were
completely erased.
See Section 3.8 for
display.

information

about

erasing

virtual

Format
UIS:ERASE display &OPTIONAL xl yl x2 y2

0
24

GRAPHICS SYSTEM COMPONENTS

Arguments

0 display

A virtual display or transformation
xl yl x2 y2
Four single floats designating the world coordinates of two
opposite corners of a rectangle. Everything within the rectangle
is erased. If these arguments are omitted, the entire virtual
display is erased.
Return Value
Undefined

0 Corresponding KicroVKS Routine
UIS$ERASE
ERASE-PIXEL Function

Erases a viewport or a specified portion of a viewport.
list is not affected by this operation.

The

display

See Section 3.8 for more information about erasing in a viewport.
Format
UIS:ERASE-PIXEL window &OPTIONAL x1 y1 x2 y2
Arguments

Q window
A window
x1 y1 x2 y2
Four fixnums designating the device coordinates of two opposite
corners of a rectangle.
Everything within the rectangle is
erased. If these arguments are omitted, the entire window is
erased.
Return Value
Undefined

0
25

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

UISDC$ERASE
ERASE-VIEWING-AREA Function

Erases the viewing area of a window output stream.
information about window output streams.

See Chapter 7

for

Format
UIS:ERASE-VIEWING-AREA window-output-stream
Arguments
window-output-stream
A
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return Value
Undefined
Corresponding HicroVMS Routine
None
GET-ABS-POINTER-POSITION Function

Returns the absolute position of the pointer on the display screen
centimeters relative to the lower left corner of the screen.

Format
UIS:GET-ABS-POINTER-POSITION &OPTIONAL device
Arguments

device
A character string designating the device for
If omitted,
information is to be returned.
defaults to SYS$WORKSTATION.

which pointer
this argument

0
26
--·-· .:_______________________________________

GRAPHICS SYSTEM COMPONENTS

Return Value

Two values:
1.

A single float designating the X position of the
centimeters

pointer

A single float designating the Y position of the
centimeters

pointer

Corresponding MicroVMS Routine
UIS$GET_ABS_POINTER_POSITION
GET-ALIGNED-POSITION Function

the aligned text position for a specified virtual display.
0 Returns
See SET-ALIGNED-POSITION for a description of the aligned position.
Format
UIS:GET-ALIGNED-POSITION display att-block
Arguments

Q display
The virtual display or transformation
position is to be returned.

for

which

the

aligned

att-block
A fixnum in the range 0-255, designating an attribute block
which a font will be taken

from

0 Return Value

Two values:
1.

A single float
coordinates

designating

the

position

world

A single float
coordinates

designating

the

position

world

Corresponding MicroVMS Routine
UIS$GET_ALIGNED_POSITION

0
27

GRAPHICS SYSTEM COMPONEN1S
GET-ALIGNED-POSITION-PIXEL Function

Returns the aligned text position for all windows mapped into a
particular virtual display. Although the argument to this function is
a single window, the aligned text position is the same for all windows
mapped into that window's display. See SET-ALIGNED-POSITION-PIXEL for
a description of the aligned position.

Format
UIS:GET-ALIGNED-POSITION-PIXEL window att-block

Arguments
window
The window for which the aligned position is to be returned

att-block
A fixnum in the range 0-255, designating an attribute block
which a font will be taken

from

Return Value
Two values:

·-

A fixnum designating the X position in device coordinates

A fixnum designating the Y position in device coordinates

Corresponding KicroVMS Routine
UISDC$GET_ALIGNED_POSITION

GET-ATTRIBUTE Function

Returns the value for the specified attribute in the specified
attribute block. You can supply a display or a window mapped into the
display as the first argument to GET-ATTRIBUTE.
If you supply a
window, you can get the value of any attribute. If you supply a
display and you want ·to get
the
value
of
:CLIP-PIXEL
or
:LEFT-MARGIN-PIXEL, at least one window must be mapped into the
display or the function will fail.
The value returned by GET-ATTRIBUTE is informational only; you ·cannot
modify an attribute block by using SETF with this function. Use the
SET-ATTRIBUTE function to modify an attribute block.
See Section 3.3 for information about attributes.·

GRAPHICS SYSTEM COMPONENTS

Format

UIS:GET-ATTRIBUTE display-or-window att-block attribute
Arguments
display-or-window
A virtual display, or a window
att-block
A fixnum in the range 0-255,
associated with the display

representing

attribute

block

attribute

One of the attribute keywords :ARC-TYPE, :BACKGROUND-INDEX,
:CHARACTER-SPACING, :CLIP, :CLIP-PIXEL, :FILL-PATTERN, :FONT,
:LEFT-MARGIN,
:LEFT-MARGIN-PIXEL,
:LINE-STYLE,
:LINE-WIDTH,
:RIGHT-MARGIN, :WRITING-INDEX, :WRITING-MODE
Return Value

The value of the specified attribute (see the list of attribute
keywords and their possible arguments in the description of
SET-ATTRIBUTE).
For :FONT, the return value is a list of keyword-value pairs,
• where
each keyword is one of the font specification keywords
displayed by the SHOW-FONTS
whose values differ from
included in the list.

function.
those of

Only those
the 'default

:LINE-STYLE, the return value is one of the line style
• For
specification keywords if the line style is one of the
DIGITAL-supplied line styles, or a bit vector of length 32
specifying a nonstandard line style. (See Section 3.5.3.3.)
•

For :LINE-WIDTH, the return value is a floating-point number
unless you have specified line width in world coordinate
units, in which case the return value is a list of the form
'(n :WORLD-COORDINATES), where n is a floating-point number.

Corresponding MicroVIIS Routines

keywords
font are

Attribute

Routine

:ARC-TYPE
:BACKGROUND-INDEX
:CHARACTER-SPACING
:CLIP

UIS$GET_ARC_TYPE
UIS$GET_BACKGROUND_INDEX
UIS$GET_CHAR_SPACING
UIS$GET_CLIP
29

GRAPHICS SYSTEM COMPONENTS

Attribute

Routine

:CLIP-PIXEL
:FILL-PATTERN
:FONT
:LEFT-MARGIN
:LEFT-MARGIN-PIXEL
:LINE-STYLE
:LINE-WIDTH
:WRITING-INDEX
:WRITING-MODE

UISDC$GET_CLIP
UIS$GET_FILL_PATTERN
UIS$GET_FONT
UIS$GET_LEFT_MARGIN
UISDC$GET_LEFT_MARGIN
UIS$GET_LINE_STYLE
UIS$GET_LINE_WIDTH
UIS$GET_WRITING_INDEX
UIS$GET_WRITING_MODE

GET-ATTRIBUTE-LIST Function

Returns a property list of all the attributes and their values for a
specified attribute block.
You can supply a display or a window
mapped into the display as the first argument to GET-ATTRIBUTE-LIST.
If you supply a window, the list includes the values of all
attributes. If you supply a display, the list includes the values of
all attributes except :CLIP-PIXEL or :LEFT-MARGIN-PIXEL.

See Section 3.3 for information about attributes.

Format

UIS:GET-ATTRIBUTE-LIST display-or-window att-block

Arguments

display-or-window
A virtual display or a window

att-block
A fixnum in the range 0-255,
associated with the display

representing

attribute

block

Return Value
A list in the form (attr1 value! attr2 value2 ••• )

Corresponding KicroVMS Routine
None

0
30

_ _l

GRAPHICS SYSTEM COMPONENTS
GET-BUTTONS Function

Returns two values representing the state of the pointer buttons. The
first value is an integer that encodes the actual button state; the
second indicates whether the pointer cursor was visible in the window
you supply as an argument.
The integer returned
follows:

GET-BUTTONS

encodes

the

button

state

•

When one (and only one) button is down, the integer equals the
value of the POINTER-BUTTON-n constant corresponding to that
button.

•

When more than one button is down, the integer equals the
result of calling the COMMON LISP LOGAND function with the
corresponding POINTER-BUTTON~n constants as arguments.

For example:
(CASE (GET-BUTTONS WINDOW)
(#.POINTER-BUTTON-1
)
(#.POINTER-BUTTON-2 ••• )
(#.(LOGAND
POINTER-BUTTON-!
POINTER-BUTTON-2) ••• ))

; Ignore second return value
; Only button 1 down
; Only button 2 down
; Buttons 1 and 2 down

This example shows how you can test for single
combinations of buttons in a call to the CASE macro.

buttons

and

Format
UIS:GET-BUTTONS window

Arguments
window
A window

Return Value
Two values:
1.

An integer that encodes the button state as described above

Tor NIL, indicating whether or not the pointer cursor is
window

Corresponding MicroVMS Routine

UIS$GET_BUTTONS
31

GRAPHICS SYSTEM COMPONENTS
GET-COLOR Function

Returns as multiple values the R (red), G (green), and B (blue) values
for an entry in the color map associated with a virtual display. See
Section 3.4 for information about color.

Format
UIS:GET-COLOR display color-id &OPTIONAL window

Arguments
display
A virtual display
color-id
An integer specifying an entry in the color map
display

associated

with

window
A window. If this argument is supplied, the return values are
the realized colors for the specific device on which the window
was created.

Return Value

Three values:
1.

The red value

The blue value

The green value

Each return value is a floating-point number in the range
1.0, inclusive.

0.0

Corresponding MicroVMS Routine
UIS$GET_COLOR
GET-DISPLAY-SIZE Function

Returns the size and resolution of the display screen.

Format
UIS:GET-DISPLAY-SIZE &OPTIONAL device
32

GRAPHICS SYSTEM COMPONENTS

Arguments

device
A string specifying the device for which information
returned. The default is SYS$WORKSTATION.

Return Value
Six values:

A single float giving the width of the screen in centimeters

A single float giving the height of the screen in centimeters

A single float g1v1ng the horizontal resolution of the screen
in pixels/centimeter

A single float giving the vertical resolution of
in pixels/centimeter

A fixnum giving the width of the screen in pixels

A fixnum giving the height of the screen in pixels

the

screen

Corresponding MicroVHS Routine
UIS$GET_DISPLAY_SIZE
GET-FONT-SIZE Function

Returns the height and width of a text string
specified font.

centimeters

for

Q Format
UIS:GET-FONT-SIZE font-id text-string
Arguments

font-id
A pathname, string, stream, or symbol specifying a font file; or,
a list of keyword-value pairs specifying a font. ( See the
description of the SET-ATTRIBUTE function, :FONT attribute, for
an explanation of this list.)

text-string

A string to be measured

GRAPHICS SYSTEM COMPONENTS

Return Value

Two values:
1.

A single float designating the width of the character
in centimeters

string

A single float designating the height of the character string
in centimeters

Corresponding MicroVMS Routine
UIS$GET_FONT_SIZE
GET-INTENSITY Function

Returns the equivalent monochrome intensity value for an entry in the
color map associated with a virtual display. See Section 3.4 for
information about color maps.

Format
UIS:GET-INTENSITY display color-id &OPTIONAL window

Arguments

display
A virtual display

color-id
An integer specifying an entry in the color map
display

associated

with

window

A window. If this argument is specified, the return value is the
realized intensity for the specific device on which the window
was created.
Return Value
A floating-point number in the range 0.0 - 1.0, inclusive
Corresponding MicroVMS Routine
UIS$GET_INTENSITY

0
34

GRAPHICS SYSTEM COMPONENTS
GET-KB-ATTRIBUTE Function

Returns the value of a single keyboard attribute for a specified
virtual keyboard. You cannot modify the value of a keyboard attribute
by using SETF with this function. Use the SET-KB-ATTRIBUTES function
to modify a virtual keyboard.
See Section 6.1.4 for information about keyboard attributes.
Format
UIS:GET-KB-ATTRIBUTE keyboard attribute
Arguments

keyboard

A virtual keyboard

attribute
One of the keyboard attribute
description of SET-KB-ATTRIBUTES

keywords

listed

under

the

Return Value

The value of the specified attribute for the specified keyboard
Corresponding MicroVMS Routine
None
GET-KB-ATTRIBUTE-LIST Function

Returns a list of keyword-value pairs indicating the value of each
attribute for the specified keyboard.
This list is. informational
only; you cannot modify a virtual keyboard by using SETF with this
function.
Use the SET-KB-ATTRIBUTES function to modify a virtual
keyboard.
See Section 6.1.4 for information about keyboard attribues.
Format
UIS:GET-KB-ATTRIBUTE-LIST keyboard
Arguments

keyboard
A keyboard
35

GRAPHICS SYSTEM COMPONENTS

Return Value
A list of keyword-value pairs, where the keyword is one of the
keyboard
attribute
keywords listed in the description of
SET-KB-ATTRIBUTES, and the value is its value for this keyboard

Corresponding MicroVMS Routine
UIS$GET_KB_ATTRIBUTES
GET-POINTER-POSITION Function

Returns the world coordinate position of the pointer cursor, or NIL if
the pointer cursor is not in the visible portion of the viewport.
Format

UIS:GET~POINTER-POSITION display window
Arguments
display
A virtual display, transformation, or NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to interpret the return values as transformation coordinates
rather than world coordinates.

window
A window

Return Value
Two values:
1.

A single float designating the X position of the pointer
cursor in world or transformation coordinates, or NIL if the
pointer cursor is not in the viewport

A single float designating the Y position of
cursor in world or transformation coordinates

the

pointer

Corresponding MicroVHS Routine
UIS$GET_POINTER_POSITION

0
36

GRAPHICS SYSTEM COMPONENTS
GET-POINTER-POSITION-PIXEL Function

0 Returns the device-coordinate position of the pointer cursor, or NIL
if the pointer cursor is not in the visible portion of the viewport.
Format
UIS:GET-POINTER-POSITION-PIXEL window
Arguments

window
A window

Return Value
Two values:
1.

A fixnum designating the X position of the pointer cursor in
device coordinates, or NIL if the pointer cursor is not in
the viewport

A fixnum designating the Y position of the pointer cursor
device coordinates

0 Corresponding HicroVMS Routine
UISDC$GET_POINTER_POSITION
GET-POSITION Function

Returns the current text position for a specified virtual
See Section 3.6.2.1 for information about the text position.

display.

0 Format

UIS:GET-POSITION display
Arguments

display
The virtual display or transformation for which the text position
is to be returned
Return value

Two values:

GRAPHICS SYSTEM COMPONENTS

A single float representing
world-coordinate text position

the

portion

the

single float representing
world-coordinate text position

the

portion

the

Corresponding MicroVMS Routine
UIS$GET_POSITION
GET-POSITION-PIXEL Function

Returns the current device-coordinate text position for windows mapped
into a virtual display.
The device-coordinate text position is
independent of the display text position; however, all windows mapped
into a virtual display share the same device-coordinate text position.
See Section 3.6.2.1 for information about the
position.

device-coordinate

text

Format
UIS:GET-POSITION-PIXEL window

Arguments

window
The window for which the text position is to be returned
Return Value
Two values:
1.

A fixnum representing the X portion of the
text position

device-coordinate

A fixnum representing the Y portion of the
text position

device-coordinate

Corresponding HicroVMS Routine
UISDC$GET_POSITION
GET-VIEWPORT-POSITION Function

Returns the position of the lower-left corner of a display viewport in
relation to the lower-left corner of the physical display, in
centimeters.

GRAPHICS SYSTEM COMPONENTS

Q Format
UIS:GET-VIEWPORT-POSITION window

Arguments
window

The window associated with the viewport whose position is
returned

Return Value
Multiple values:

A single float representing the X position of the viewport in
centimeters

A single float representing the Y position of the viewport in
centimeters

Corresponding HicroVMS Routine
UIS$GET_VIEWPORT_POSITION

GET-VIEWPORT-SIZE Function

Returns the width and height of a display viewport in centimeters.
Format
UIS:GET-VIEWPORT-SIZE window

O Arguments
window
The window associated with the
returned

viewport

whose

size

Return Value
Multiple values:
1.

A single float representing the width of the viewport

A single float representing the height of the viewport

0
39

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

UIS$GET_VIEWPORT_SIZE
GET-VISIBILITY Function

Returns T if an entire viewport or all of a specified portion thereof
is unoccluded by other viewports, and NIL if any part of it is
occluded. If no optional arguments are given, the entire vi~wport is
checked for ·visibility. If a single world-coordinate pair is given,
then that single point is checked. If two world-coordinate pairs are
given, then the rectangle they define is checked. If the point or
rectangle falls outside the window, then GET-VISIBILITY returns NIL.
Format

UIS:GET-VISIBILITY display window &OPTIONAL xl yl x2 y2
Arguments

display
A virtual display, transformation, or NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of world coordinates.

window
The window whose associated viewport (or portion thereof)
be checked for visibility.

x1 y1

Two single floats defining a point in world or transformation
coordinate space; this point is checked for visibility if no more
arguments are given
x2 y2
Two single floats defining
another
point
in
world
or
transformation coordinate space; the rectangle defined by the two
points is checked for visibility
Return Value
Tor NIL

0
40

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS.Routine

UIS$GET_VISIBILITY
GET-VISIBILITY-PIXEL Function

Returns T if an entire viewport or all of a specified portion thereof
is unoccluded by other viewports, and NIL if any part of it is
occluded. If no optional arguments are given, the entire viewport is
checked for visibility. If a single device-coordinate pair is given,
then that single point is checked. If. two device-coordinate pairs are
given, then the rectangle they define is checked. If the point or
rectangle falls outside the window, then GET-VISIBILITY-PIXEL returns
NIL.

Format
UIS:GET-VISIBILITY-PIXEL window &OPTIONAL x1 y1 x2 y2
Arguments

window

The window whose associated viewport (or portion thereof)
be checked for visibility.

x1 y1

Two fixnums defining a pixel in the window; this pixel is checked
for visibility if no more arguments are given
x2 y2

Two fixnums defining another pixel in the window; the
defined by the two points is checked for visibility

rectangle

Return Value
Tor NIL
Corresponding MicroVMS Routine
UISDC$GET_VISIBILITY
GET-WINDOW-ATTRIBUTE-LIST Function

Returns a disembodied property list of the attributes of a viewport.
This list is informational only; you cannot modify a viewport by using
SETF with this function. Each of these attributes is established by
the call to CREATE-WINDOW that creates the viewport. The attributes,
41

GRAPHICS SYSTEM COMPONENTS

and the values of their meanings, are:
:NOBANNER -- T indicates that the viewport has no banner; NIL
indicates that the viewport has a banner.
:NOBORDER -- T indicates that the viewport has no border; NIL
indicates that the viewport has a border.
:NOMENU-ICON -- T indicates that the viewport has no menu icon in its
banner; NIL indicates that the viewport has a menu icon.
:NOKB-ICON -- T indicates that the viewport cannot acquire a keyboard
icon in its banner; NIL indicates that the viewport can acquire a
keyboard icon. A viewport that cannot acquire a keyboard icon
can still have a virtual keyboard associated with it.
:ALIGNED -- T indicates that the viewport's left inner edge is aligned
on byte boundaries in video memory; NIL indicates that the
viewport is not so aligned.
Format
UIS:GET-WINDOW-ATTRIBUTE-LIST window

Arguments
window
A window

Return Value
A disembodied property list
Corresponding MicroVMS Routine
UIS$GET_WINDOW_ATTRIBUTES

GET-WS-COLOR Function

Returns as multiple values the R {red), G {green), and B {blue) values
for a specified workstation standard color that was in effect at the
time the virtual display was created.
See Section 3.4 for information about color.
Format
UIS:GET-WS-COLOR display color-id &OPTIONAL window
Arguments

display
A virtual display
42

GRAPHICS SYSTEM COMPONENTS

color-id
An integer specifying an entry in the workstation standard
map that was in effect when display was created

color

window
A window. If this argument is specified, the return values are
the realized colors for the specific device on which the window
was created.
Return Value
Three values:

The red value

The blue value

The green value

Each return value is a floating-point number in the range
1.0, inclusive.

0.0

Corresponding MicroVKS Routine

·UIS$GET_WS_COLOR
GET-WS-INTENSITV Function

Returns the equivalent monochrome intensity value. for a specified
workstation standard color that was in effect at the time the virtual
display was created. See Section 3.4 for information about color.

Q Format
UIS:GET-WS-INTENSITY display color-id &OPTIONAL window
Arguments

display
A virtual display

color-id
An integer specifying an entry in the workstation standard

map that was in effect when display was created

0
43

color

GRAPHICS SYSTEM COMPONENTS

window
A window.

If this argument is specified, the return value is the
realized intensity for the specific device for which the window
was created.

Return Value
A floating-point number in the range O.J - 1.0, inclusive

Corresponding KicroVMS Routine
UIS$GET_WS_INTENSITY
IMAGE Function

Writes a bitmap to a rectangle in a virtual display. If the
list is enabled, IMAGE adds the bitmap to the display list.

display

The bitmap is displayed in viewports as follows:
•

If the size of the bitmap is larger than the corresponding
rectangle in a viewport, the bitmap is clipped at the top and
right to fit the rectangle.

•

If.the size of the bitmap is smaller than the corresponding(\
rectangle in a viewport, the bitmap is scaled up to the
largest integral multiple .that will still fit within the
rectangle.
If the rectangle is not an exact integer multiple
of the bitmap, the excess on the top and right of the
rectangle is left unchanged.

The horizontal and vertical dimensions of the bitmap are scaled or
clipped independent of each other. That is, a bitmap may be scaled by
different factors in the horizontal and vertical dimensions, or may be
clipped in one dimension and scaled in the other.

See Chapter 6 for information about bitmaps and screen images.
Format
UIS:IMAGE display att-block bitmap xl yl x2 y2
Arguments
display
A virtual display

0
44

GRAPHICS SYSTEM COMPONENTS

att-block

A fixnum in the range 0-255,
associated with display

designating

attribute

block

bitmap

An array of unsigned bytes
xl yl x2 y2

Four single floats specifying, in world coordinates, two opposite
corners of the rectangle in which the image is to be placed
Return Value

Undefined
Corresponding HicroVMS Routine
UIS$IMAGE

IMAGE-PIXEL Function

Writes a bitmap to a viewport.
screen images and bitmaps.

See Chapter 4

for

information

about

attribute

block

Format
UIS:IMAGE-PIXEL window att-block bitmap x y

Arguments

window

A window
att-block

A fixnum in the range 0-255, designating
associated with window's display

bitmap
An array of unsigned bytes

Two fixnums specifying, in device coordinates, the lower left
corner of the rectangle in which the image is to be placed. The
size of the bitmap determines the size of the rectangle.

GRAPHICS SYSTEM COMPONENTS

Return Value
Undefined
Corresponding MicroVMS Routine
UISDC$IMAGE
KEYBOARD Type Specifier

Designates
function .

objects

type

KEYBOARD,

created

the

CREATE-KB

KEYBOARDP Function

Returns T if its argument is a keyboard and NIL otherwise.

Format
UIS:KEYBOARDP object
Arguments

object

A LISP object
Return Value
Tor NIL
Corresponding MicroVMS Routine

None
K-TRM-xxx Constants

These constants have integer values, each of which represents one of
the function, numeric _keypad, editing, or arrow keys. The return
value of of READ-KB-CHAR and the first argument passed to an interrupt
function established with SET-KB-ACTION can be compared with these
values. Note that all of these constants are in a package called SMG.

0
46

GRAPHICS SYSTEM COMPONENTS

Constant

Rumeric Keypad Keys
keypad O
keypad 1
keypad 2
keypad 3
keypad 4
keypad 5
keypad 6
keypad 7
keypad 8
keypad 9
keypad keypad
keypad.
keypad Enter
keypad PF1
keypad PF2
keypad PF3
keypad PF4

Function, Delp, and Do Keys

F6
F7
F8
F9
FlO
Fll
F12
F13
F14
FlS (Help)
F16 (Do)
F17
F18
F19.
F20

SMG:K-TRM-F6
SMG:K-TRM-F7
SMG:K-TRM-F8
SMG:K-TRM-F9
SMG:K-TRM-F10
SMG:K-TRM-Fll
SMG:K-TRM-F12
SMG:K-TRM-F13
SMG:K-TRM-F14
SMG:K-TRM-BELP
SMG:K-TRM-DO
SMG:K-TRM-F17
SMG:K-TRM-F18
SMG:K-TRM-F19
SMG:K-TRM-F20

Bditing and Arrow Keys

El (Find)
E2 .( Insert Here)
E3 (Remove)
E4 (Select)
ES (Prev Screen)
E6 (Next Screen)
Up Arrow
Down Arrow
Right Arrow
Left Arrow

SMG:K-TRM-FIND
SMG:K-TRM-INSERT-BERE
SMG:K-TRM-REMOVE
SMG:K-TRM-SELECT
SMG:K-TRM-PREV-SCREEN
SMG:K-TRM-NEXT-SCREEN
SMG:K-TRM-UP
SMG:K-TRM-DOWN
SMG:K-TRM-RIGHT
SMG:K-'l'RM-LEFT
47

GRAPHICS SYSTEM COMPONENTS
LIST·ALL-DISPLAYS Function

Returns a list of all user-created displays and
have not been deleted.

transformations

that

Format
UIS:LIST-ALL-DISPLAYS
Arguments.
None
Return Value
A list

Corresponding KicroVIIS Routine
None
LIST-ALL-WINDOWS Function

Returns a list of all user-created windows that have not been deleted.

Format
UIS:LIST-ALL-WINDOWS
Arguments
None
Return Value

A list
Corresponding KicroVIIS Routine
None
LOAD-BITMAP Function

Returns a bitmap array read from a file.that was previously written by
the DUMP-BITMAP function.
This function is in package LISP.

0
48

GRAPHICS SYSTEM COMPONENTS

Format
LISP:LOAD-BITMAP pathname
Arguments
pathname
A pathname, string, stream, or symbol; the file
written previously by the DUMP-BITMAP function

must

have

been

Return Value
A bitmap array
Corresponding MicroVMS Routine

None
MAKE-BITBLT Function

Creates and returns an object of type BITBLT.
When used as an
argument to the BITBLT function, a BITBLT object causes a specific
operation to be performed on a specific bitmap. A BITBLT object has
the following components:
•

A destination bitmap, that is, the bitmap to which the
operation is applied. The destination bitmap can be an entire
bitmap array or a specified rectangle of a bitmap array.

•

A source bitmap, that is, the bitmap that is. applied to the
destination bitmap. The source bitmap can be an entire bitmap
array or can extend upward and to the right from a specified
pixel in a bitmap array. The source bitmap is not-altered by
BITBLT, unless it happens to overlap with the destination
bitmap.

•

Source and destination operations.
These specify how the
texture bitmap is combined with the source bitmap, and the
texture-source result with the destination, respectively.
They can be any of the operations that can be specified with
BOOLE.

texture bitmap. The texture bitmap is combined with the
source bitmap before the source bitmap is applied to the
destination bitmap. It is constrained to be a bitmap array
that is up to 32 bits wide; it can have any height. A texture
bitmap wider than 32 bits is trimmed on the right to fit. The
texture bitmap itself is not altered by BITBLT.

GRAPHICS SYSTEM COMPONENTS

The operation described by a BITBLT object
BITBLT function is the following:

combination

The destination, source, and texture bitmaps are
They must all have elements of the same type.

For each pixel in the destination bitmap:

with

the

evaluated.

The corresponding pixel in the source bitmap is combined
with the corresponding pixel in the texture bitmap
according to the source operation, with the source pixel
as the first argument and the texture pixel as the second
argument. If the pixel coordinates exceed the limits of
the texture bitmap, the texture pixel is located by
wrapping around to the left and/or upper edge of the
texture bitmap.
This has the effect of replicating the
texture bitmap across the source bitmap.

The result of combining the source and texture pixels is
combined with the destination pixel according to the
destination operation, with the source-texture result as
the first argument and the destination pixel as the
second argument.

The result of combining the source-texture result with
the destination pixel is used to modify the destination
pixel.

0
A BITBLT operation is described by the following algorithm (ignoring
array bounds, and assumin9 heights and widths are the same):
(DO ((dj dst-y (1+ dj))
(sj src-y (1+ sj)))
((• dj (+ dst-y dst-h)))
(DO ((di dst-x (1+ di))
(si src-x (1+ si)))
((= di (+ dst-x dst-w)))
(SETF (AREF destination dj di)
(BOOLE dst-op
(BOOLE src-op
(AREF source sj si)
(AREF filled-texture
(REM dj texture-height)
(REM di 32)))
(AREF destination dj di)))))

This function is in package LISP.
See Section 4.6 for more information on using this function.

0
so

GRAPHICS SYSTEM COMPONENTS

Format

LISP:MAKE-BITBLT
&KEY :DESTINATION :DST-X :DST-Y :DST-W :DST-H :DST-OP
:SOURCE :SRC-X :SRC-Y :SRC-W :SRC-H :SRC-OP
:TEXTURE
Arguments
:DESTINATION
A bitmap array. If none of the next four arguments are
the entire array is used as the target of the operation.

given,

:DST-X :DST-Y

Two integers specifying the array reference (not the device
coordinates)
of
a pixel in the destination bitmap.
The
destination rectangle of the operation extends downward and to
the right from this point. If these arguments are NIL or omitted
they default to O (the upper-left corner of the destination
bitmap).
:DST-W :DST-H

Two integers specifying the width and height of the destination
rectangle in pixels. If these arguments are NIL or omitted, they
default to the full width and height of the destination bitmap,
minus the values given with :DST-X and :DST-Y.
:DST-OP

BOOLE-1 - replaces the destination with the source
BOOLE-IOR - "paints" the destination with the source
BOOLE-XOR
inverts any destination pixel that is also
occupied by a source pixel
BOOLE-ANDC1 - erases any destination pixel that corresponds to
an illuminated pixel in the source

If this argument is NIL or
BOOLE-1.

omitted,

the

default

operation

:SOURCE

A bitmap array. Its elements must have the same type (that is,
number of bits per element) as those of the :DESTINATION bitmap.

GRAPHICS SYSTEM COMPONENTS

If this argument is
destination bitmap.

NIL

omitted,

defaults

the

:SRC-X :SRC-Y
Two integers specifying the array reference (not the device
coordinates) of a pixel in the source bitmap.
The source
rectangle for the operation extends downward and to the right
from this point.
If these arguments are NIL or omitted they
default to O (the upper-left corner of the source bitmap).
:SRC-W :SRC-H
Two integers specifying the width and height of the source
rectangle in pixels. If these arguments are NIL or omitted they
default to the full width and height of the destination bitmap,
minus the values given with :SRC-X and :SRC-Y.
:SRC-OP

Any of the operations that can be specified with the BOOLE
function (see Section 12.7 of COMMON LISP: The Language). The
operation specifies how each pixel in the source bitmap is
combined with the corresponding pixel in the texture bitmap. The
following operations are particularly useful with :SRC-OP:
- ignores the texture bitmap and uses the source
• BOOLE-1
0
bitmap
- ignores the source bitmap and uses the texture
• BOOLE-2
bitmap
- merges the source and texture bitmaps by only
• BOOLE-AND
setting pixels in the result that are set in both the source
and texture
If this argument is NIL or omitted, it defaults to BOOLE-1.
:TEXTURE

A bitmap array. Its elements must have the same type (that is,
number of bits per element) as those of the :DESTINATION bitmap.
If the specified :TEXTURE bitmap is narrower than 32 bits, it is
replicated horizontally to fill out a rectangle 32 bits wide. If
the bitmap is wider than 32 bits, it is trimmed on the right to
fit.
The graphics system copies the bitmap .array you specify with
:TEXTURE.
Therefore, if you later modify this array, you must
use SETF on the BITBLT-TEXTURE function to make that change
effective in a particular ~ITBLT object.
If you do not specify a texture bitmap, it defaults to all ls.

GRAPHICS SYSTEM COMPONENTS

Return Value

An object of type BITBLT
Corresponding MicroVMS Routine
None
MAKE-BITMAP Function

Creates and returns a two-dimensional array of
the
specified
dimensions, each of whose elements is an unsigned byte. The length of
each unsigned byte is given by the bits-per-pixel argument, which
defaults to 1. This function has the same effect as:
(MAKE-ARRAY (LIST height width)
:ELEMENT-TYPE '(UNSIGNED-BYTE ,bits-per-pixel)
:ALLOCATION space)

This function is in package LISP.
See Chapter 4 for information about creating and altering bitmaps.

Format
LISP:MAKE-BITMAP width height &OPTIONAL bits-per-pixel space
Arguments

width height
Two integers specifying the width and
bitmap in pixels

height

the

requested

bits-per-pixel
An integer specifying how many bits represent each pixel.
If
this argument is omitted, one bit is used to represent each
pixel. This argument is currently limited to 1.
space
Either :DYNAMIC (the default) or :STATIC, indicating in which
space the array should be created.
(See the description of
MAKE-ARRAY in the VAX LISP/VMS User's Guide.)

Return Value
An array of unsigned bytes

0
53

· GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

None
MAKE-WINDOW-OUTPUT-STREAM Function

Creates a window output stream and returns the stream object.
The
stream can be used as an argument to COMMON LISP output functions.
See Chapter 7 for information about window output streams.
Format
UIS:MAKE-WINDOW-OUTPUT-STREAM window
&KEY :ATTRIBUTE-BLOCK :VIEWING-AREA
:HORIZONTAL-OVERFLOW :VERTICAL-OVERFLOW

Arguments

window
A window
:ATTRIBUTE-BLOCK
A fixnum designating the attribute block to be used for
output operations; the default is attribute block 0.
attribute
block
can
be
changed
later
by
using
WINDOW-STREAM-ATTRIBUTE-B.LOCK function.

all
The
the

:VIEWING-AREA
A list of four integers in the form (x1 y1 x2 y2) that specifies
the lower-left and upper-right corners of a rectangle within
which text is written. If this argument is NIL or omitted, text
is written into the entire window.
The viewing area can be
changed later by using the WINDOW-STREAM-VIEWING-AREA function.

:HORIZONTAL-OVERFLOW
Either :WRAP, the default, indicating-that text be wrapped onto
the next line, or :TRUNCATE, indicating that text be truncated at
the right margin.
The horizontal overflow behavior can be
changed later by using the WINDOW-STREAM-HORIZONTAL-OVERFLOW
function.
:VERTICAL-OVERFLOW
Eitehr :SCROLL, the default, indicating that text be scrolled
upwards to accomodate new text at the bottom of the viewing area;
:WRAP, indicating that text be vertically wrapped; or :TRUNCATE,
54

GRAPHICS SYSTEM COMPONENTS

indicating that .text below the bottom of the viewing area be
discarded until the viewing area is erased.
The vertical
overflow
behavior
can
be
changed
later
by using the
WINDOW-STREAM-VERTICAL-OVERFLOW function.
Return Value
A window output stream
Corresponding MicroVMS Routine
None
MEASURE-TEXT Function

Returns the width and height of a text string in the world
system of a virtual display.

coordinate

Format
UIS:MEASURE-TEXT display att-block text-string

Arguments

display
A virtual display or transformation

att-block
A fixnum in the range 0-255, designating an attribute block
which font and character spacing attributes will be taken

from

text-string
A character string to be measured
Return Value
Two values:
1.

A single float designating the width of the
world coordinates

text

string

A single float designating the height of the text
world coordinates

string

~orresponding MicroVMS Routine

UIS$MEASURE_TEXT

GRAPHICS SYSTEM COMPONENTS
MEASURE-TEXT-PIXEL Function

Returns the width and height of a
units.

text

string ·in

device-coordinate

Format
UIS:MEASURE-TEXT-PIXEL window att-block text-string

Arguments
window

A window
att-block

fixnum in the range 0-255, designating an attribute block
which font and character spacing attributes will be taken
A

from

text-string

A character string to be measured

Return Value

Two values:
1.

fixnum designating the
device-coordinate units

width

the

text

string

fixnum designating the
device-coordinate units

height

the

text

string

Corresponding KicroVMS Routine

UISDC$MEASURE_TEXT
MOVE-AREA Function

Shifts a portion of a virtual display from one place to another in the
display. The display list is updated to reflect the alteration.
See Section 3.8 for information about moving
display.

portions

virtual

Format
UIS:MOVE-AREA display xl yl x2 y2 dest-x dest-y

GRAPHICS SYSTEM COMPONENTS

Arguments

0 display
A virtual display or transformation
x1 y1 x2 y2

Four single floats designating
opposite corners of a rectangle

the

world

coordinates

two

dest-x dest-y

Two single floats designating the world coordinates of the
lower-left corner of the destination rectangle. The size of the
destination rectangle is taken from the size of the source
rectangle.
Return Value

Undefined
Corresponding MicroVKS Routine
UIS$MOVE_AREA

0 MOVE-AREA-PIXEL Function
Shifts a rectangle in a viewport to another
The display list is not affected.

place

the

viewport.

See Section 3.8 for information about moving portions of a viewport.

Format
UIS:MOVE-AREA-PIXEL window xl yl x2 y2 dest-x dest-y
Arguments
window

A window
. xl yl x2 y2

Four fixnums designating the device coordinates of
corners of a rectangle

0
57

two

opposite

GRAPHICS SYSTEM COMPONENTS

dest-x dest-y
Two fixnums designating the device coordinates of the lower-left
corner of the destination rectangle. The size of the destination
rectangle is taken from the size of the source rectangle.

Return Value
Undefined
Corresponding MicroVMS Routine
UISDC$MOVE_AREA
MOVE-VIEWPORT Function

Moves a display viewport on the physical display.

Format
UIS:MOVE-VIEWPORT window
&KEY :GENERAL-PLACEMENT :CENTER
:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
:INVISIBLE

Arguments

window
The window whose associated viewport is to be moved
:GENERAL-PLACEMENT
Either :TOP :BOTTOM, :LEFT, or :RIGHT, indicating a general
preference for viewport position on the screen; or a list of two
of these, for example (:TOP :RIGHT); or NIL, indicating no
preference for viewport placement

:CENTER
NIL (the default) or T. If T, the viewport will be centered over
the
position
specified
by
:ABSOLUTE-POSITION-X
and
:ABSOLUTE-POSITION-Y. If NIL, the viewport's lower left corner
will be aligned on the position.
:ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
Two single floats indicating, in centimeters, the viewport's new
displacement from the left- and bottom edges of the display.
screen. The value provided with the :CENTER- keyword determines
the placement of the viewport relative to the ABSOLUTE-POSITION

GRAPHICS ·SYSTEM COMPONENTS

values.

0 :INVISIBLE

Either Tor NIL (the default). If T, the viewport is moved to
location off the screen; it becomes invisible.

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$MOVE_VIEWPORT
MOVE-WINDOW Function

0 Moves a window within a virtual display, optionally allowing the
window to change size and/or aspect ratio.
information about using this function.

See Section 2.4.3 for

Format
UIS:MOVE-WINDOW display window x1 y1 x2 y2
QArguments

display

A virtual display, transformation, or NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of worl~ coordinates.

window
A window object
x1 y1 x2 y2

Four/ single
coordinates)
window

floats specifying (in world or
transformation
the lower-left and upper-right corners of the new

Return Value
Undefined

0
59

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVIIS Routine

UIS$MOVE_WINDOW
NEW-TEXT-LINE Function

Moves the current text position to the left margin
height of one line.

and

down

the

operation

Format
UIS:NEW-TEXT-LINE display att-block

Arguments

display
The virtual display or transformation in which the
to be performed

att-block
A fixnum in the range 0-255, designating an attribute block from
which font, left margin, and line spacing attributes are taken

Return Value
Undefined
Corresponding MicroVMS Routine·
UIS$NEW_TEXT_LINE

NEW-TEXT-LINE-PIXEL Function

Moves the current text position to the left margin
height of one line.

and

down

the

Format
UIS:NEW-TEXT-LINE-PIXEL window att-block

Arguments

window
The window in which the operation is to be performed

0
60

GRAPHICS SYSTEM COMPONENTS

att-block

A fixnum in the range 0-255, designating an attribute block from
which font, left margin, and line spacing attributes are taken
Return Value
Undefined
Corresponding HicroVHS Routine
UISDC$NEW-TEXT_LINE
PLOT Function

Draws a point, a single line, or up to 124 lines, depending on the
number of positions specified. Use the PLOT~ARRAY function to draw
more than 124 lines in a single operation.
If the attribute block
specifies a fill pattern, the PLOT function does not draw lines, but
instead fills the area that the lines contain.
See Section 3.5.1 for information about drawing lines.
3.5.3.2 for information about specifying a fill pattern.

See

Section

For~t

UIS:PLOT display att-block x1 y1
&OPTIONAL x2 y2 x3 y3 ••• x125 y125
Arguments
display

A virtual display or transformation
att-block

A fixnum in the range 0-255, designating an attribute block
which the graphics attributes will be taken

from

x1 yl
Two single floats designating a world coordinate. If this is the
only point specified, this single point will be plotted.
x2 y2 x3 y3 •••

x125 y125

Single floats designating additional world coordinates.
A line
is drawn between each point specified and the previous point.

0
61

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding KicroVMS Routine
UIS$PLOT
PLOT-ARRAY Function

Draws a point, line, or multiple connected lihes, depending on the
number of points specified. It differs from PLOT in that you specify
the points in the form of two vectors, one for the X value and one for
the Y value.
If the attribute block specifies a fill pattern, the PLOT-ARRAY
function does not draw lines, but instead fills the area that the
lines contain.
See Section 3.5.1 for information about drawing lines.
3.5.3.2 for information about specifying a fill pattern.

See

Section

Format
UIS:PLOT-ARRAY display att-block x-vector y-vector
&OPTIONAL count

Arguments

display
A virtual display or transformation

att-block
A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

x-vector y-vector
Two specialized vectors with elements ef type SINGLE-FLOAT.
(If
you supply general vectors, VAX LISP creates specialized vectors,
with a resulting loss of efficiency.) If a count argument is
supplied, each vector must be of length count or greater. Points
are specified by taking an element from x-vector and y-vector and
interpreting them as the x and Y values of a world coordinate.
Successive points are joined by lines.

0
62

GRAPHICS SYSTEM COMPONENTS

count
A fixnum designating the number of points to be drawn.

If this
argument is not supplied, it defaults to the minimum of the
number of elements in x-vector and y-vector.

Return Value
Undefined
Corresponding KicroVMS Routine
UIS$PLOT_ARRAY
PLOT-ARRAY-PIXEL Function

O Draws
a point, line, or multiple connected lines, depending on the
number of points specified. It dif.fers from PLOT in that you specify
the points in the form of two vectors, one for the X value and one for
the Y value.
If the attribute block specifies a fill pattern, the PLOT-ARRAY-PIXEL
function does not draw lines, but instead fills the area that the
lines contain.

Q See
Section 3.5.1 for information about drawing lines.
See Section
3.5.3.2 for information about specifying a fill pattern.
Format
UIS:PLOT-ARRAY-PIXEL window att-block x-vector y-vector
&OPTIONAL count

Q Arguments
window
A window
att-block
A fixnum in the range 0-255,·designating an attribute block
which graphics attribu~es will be taken

from

x-vector y-vector

Two specialized vectors with elements· of type (SIGNED-BYTE 32).
If a count argument is supplied, ·each vector must be of length
count or greater. Points are specified by taking an element from
x-vector and y-vector and interpreting them as the X and Y values
of a device coordinate. Successive points are joined by lines.·
63

GRAPHICS SYSTEM COMPONENTS

count
A fixnum designating the number of points to be drawn.
If this
argument is not supplied, it defaults to the minimum of the
number of elements in x-vector and y-vector.

Return Value
Undefined
Corresponding MicroVJIS Routine
UISDC$PLOT_ARRAY

PLOT-PIXEL Function

Draws a point, a single line, or up to 124 lines, depending on the
number of positions specified. Use the PLOT-ARRAY-PIXEL function to
draw more than 124 lines in a single operation.
If the attribute block specifies a fill pattern, the PLOT-PIXEL
function does not draw lines, but instead fills the area that the
lines contain.
See Section 3.5.1 for information about drawing lines.
3.5.3.2 for information about specifying a fill pattern.

See

SectionQ

Format
UIS:PLOT-PIXEL window att-block xl yl
&OPTIONAL x2 y2 x3 y3 ••• x125 y125
Arguments

window
A window

att-block
A fixnum in the range 0-255, designating an attribute block
which graphics attributes will be taken

from

xl yl
Two fixnums designating a device coordinate. If this is the only
point specified, this single point will be plotted.

0
64

GRAPHICS SYSTEM COMPONENTS

·.~

x2 y2 x3 y3 •••

x125 y125

Fixnums designating additional device coordinates.
A line
drawn between each point specified and the previous point.

Return Value
Undefined
Corresponding MicroVMS ~outine
UISDC$PLOT
POINTER-BUTTON-n Constants

Have values that specify a button on the pointing device.
An
interrupt
function
that
is given as the action argument in
SET-BUTTON-ACTION or SET-BUTTON-ACTION-PIXEL receives, as its first
argument, the code of the button whose transition invoked the
function. Use these constants to compare with that code.
You also
use these constants to interpret the value returned by the GET-BUTTONS
function. The constants start with POINTER-BUTTON-1 and go to an n 'as
high as required for the supported pointing device with the greatest
number of buttons.

See Section 5.1.3 for information about
buttons.

getting

input

from

pointer

Format
UIS:POINTER-BUTTON-n

POP-VIEWPORT Function

Pops a display viewport to the forefront of the display screen,
front of any other viewports which may have been occluding it.
Format
UIS:POP-VIEWPORT window
Arguments
window
A window whose associated display viewport is to be popped.

Return Value

Undefined
65

. GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

UIS$POP_VIEWPORT
PUSH-VIEWPORT Function

Pushes a display viewport to the back of the display screen,
of any other viewports which may have been occluded by it.

back

Format
UIS:PUSH-VIEWPORT window
Arguments
window

The window whose associated display viewport is to be pushed

Return Value
Undefined
Corresponding KicroVIIS Routine

UIS$PUSH_VIEWPORT
READ-IMAGE-PIXEL Function

Reads a bitmap from a rect~ngle in a window on the screen and either
creates a new bitmap representing that image or alters an existing
bitmap. In either case, the function returns the bitmap.
If the bitmap argument to READ-IMAGE-PIXEL is NIL, the function
creates a new bitmap that is the size of the screen rectangle you
specify. If you do not specify a rectangle, the bitmap is taken from
the entire viewport.

If the bitmap argument is a valid bitmap, the function alters the
bitmap and returns it. In this case, the function determines the size
of the screen image from the size of the supplied bitmap.
Therefore,
if you supply a bitmap, the function ignores the second coordinate
pair if you give it.
See Chapter 4 for information about screen images and bitmaps. ·
Format
UIS:READ-IMAGE-PIXEL window bitmap &OPTIONAL·xl yl x2 y2

GRAPHICS SYSTEM COMPONENTS

Arguments

0 window
A window

bitmap
Either an array of unsigned bytes, or NIL.
If you supply an
array, the function determines the size of the screen image from
the size of the array, then modifies the array with the bits of
the screen image.
If you specify NIL, the function creates an
array of size x2-x1,y2-y1 whose bits correspond to the bits of
the screen image.
xl yl

Two fixnums specifying, in device coordinates, the lower-left
corner of the rectangle containing the image. If these arguments
are omitted or NIL, they default to 0, specifying the lower-left
corner of the viewport.
If you supply a bitmap array for the
bitmap argument, the bitmap array determines the size of the
rectangle.
x2 y2

Two fixnums specifying, in device coordinates, the upper-right
corner
of the rectangle containing the image.
These are
exclusive bounds; the image extends up to, but does not include,
the bounds specified by x2 y2. These arguments are ignored if
you supply a bitmap array for the bitmap argument. If you supply
NIL for bitmap, x2 and y2 default to the upp~r-right corner of
the viewport in such a way that the topmost row and rightmost
column of pixels are included in the returned bitmap.

Q Return Value
A bitmap array

Corresponding HicroVMS Routine
UISDC$READ_IMAGE
READ-KB-CHAR Function

Reads the next keystroke from a virtual keyboard and returns either a
character or an integer to represent the keystroke. If the key was a
printing or control key, the return value is a character; otherwise,
it is an integer. (See Chapter 6 and the description of the KEY-xxx
constants for more information about this return value.) If no
character is available, the function does not return until one becomes
67

GRAPHICS SYSTEM COMPONENTS

available.
See Chapter 6 for information
interpreting keystrokes.

about

using

virtual

keyboards

ando

Format
UIS:READ-KB-CHAR keyboard
Arguments

keyboard
A virtual keyboard
Return Value

A character or integer
Corresponding MicroVMS Routine
UIS$READ_CHAR
RESIZE-WINDOW Function

Changes the specified window to have the specified viewport size andO
location.
You can optionally change the size. and location of the
window within the virtual display as well. The function re-executes
the virtual display's display ·list, if one exists.
You can use this function by itself to alter the size and location of
windows and viewports. RESIZE-WINDOW is also useful in an interrupt
function supplied as the action for the SET-RESIZE-ACTION function.
See Section 2.4.6.2 and the description of SET-RESIZE-ACTION.

Format
UIS:RESIZE-WINDOW display window x y width height
&OPTIONAL xl yl x2 y2
Arguments

display
A virtual display, transformation, or NIL. The virtual .display
must be the one into which window is mapped; NIL is equivalent to
specifying this display.· A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of world coordinates.

GRAPHICS SYSTEM COMPONENTS

window

A window object
x y

Two single floats specifying the position of the lower-left
corner of the window's viewport in centimeters, relative to the
lower-left corner of the display screen
width height

Two single floats specifying the width and height of the window's
viewport in centimeters
xl yl x2 y2

Four single floats specifying the lower-left and upper-right
corners of a rectangle in world or transformation coordinates.
The resized window is mapped to this rectangle.
If these
arguments are omitted, the existing window coordinates are used.
Return Value
Undefined

Qcorresponding KicroVIIS Routine
UIS$RESIZE_WINDOW
SET-ALIGNED-POSITION Function

O
·

Sets the aligned position for text output in a specified virtual
display.
The aligned position differs from the position established
with SET-POSITION in .that it refers to the upper-left corner of the
next character to be output, rather than the leftmost point on the
character's baseline. For this reason, the function requires an input
attribute block from which to take the font.
See Section 3.6.2.1
position.

for

information

about

Format
UIS:SET-ALIGNED-POSITION display att-block x y

0
69

the

aligned

text

GRAPHICS SYSTEM COMPONENTS

Arguments

display

The virtual display or
position is to be set

transformation

for

which

the

aligned

att-block ·

A fixnum in the range 0-255, designating an attribute block
which font information will be taken

from

x y

Two single floats designating the world
the new aligned text position

coordinate

position

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_ALIGNED_POSITION

SET-ALIGNED-POSITION-PIXEL Function

Sets the aligned position for text output in a specified window.
The
aligned
position
differs
from
the position ,established with
SET-POSITION-PIXEL in that it ·refers to the upper-left corner of the
next character to be output, rather than the leftmost point on the
character's baseline. For this reason, the function requires an input
attribute block from which to take the font.
See Section 3.6.2.1
position.

for

information

about

the

aligned

Format
UIS:SET-ALIGNED-POSITION-PIXEL window att-block x y
Arguments
window
The window for which the aligned position is to be set
att-block
A fixnum in the range 0-255, designating an.attribute block
which font information will be taken
70

textc:=)

GRAPHICS SYSTEM COMPONENTS

x y

Two fixnums designating the world coordinate position of the
aligned text position

new

Return Value
Undefined
Corresponding MicroVMS Routine
UISDC$SET_ALIGNED_POSITION
SET-ATTRIBUTE Function

Modifies an output attribute block by changing the value of one
attribute from an input attribute block. The input attribute block is
not modified. After the call to SET-ATTRIBUTE, the output attribute
block has the same values as the input attribute block, with the
exception of the attribute that was changed: The output attribute and
input attribute block may be the same, resulting in modification of
the input attribute block.
You can supply a display or a window mapped into the display as the
first argument to SET-ATTRIBUTE. If you supply a window, you can set
the value of any attribute. If you s~pply a display and you want to
set the value of :CLIP-PIXEL or :LEFT-MARGIN-PIXEL, at least one
window must be mapped into the display or the function will fail.
See Section 3.3 for more information about attributes.
Format

UIS:SET-ATTRIBUTE display-or-window input-ab output-ab
attribute new-value
Arguments

display-or-window
A virtual display, or a window

input-ab
A fixnum in the range 0-255,
associated with the display

representing

attribute

block

output-ab

A fixnum in the range 1-255, representing an attribute block that
will be modified
71

GRAPHICS SYSTEM COMPONENTS

attribute new-value

An attribute to be set and its new value:
:ARC-TYPE - :OPEN (the default), :PIE, or :CHORD.
:BACKGROUND-INDEX - An integer specifying an entry in a color
map. The integer must be in the range of the entries in the
virtual display's color map. The default is 0.
:CHARACTER-SPACING - A list of two single floats, specifying the
extra space to leave between characters (horizontally) and
lines (vertically). The default is (0.0 0.0). The numbers
specify fractions of the character width and font height,
respectively.
:CLIP - NIL (the default), to indicate that clipping in the
virtual display is turned off in this attribute block; or a
list of four single floats in the form (xl yl x2 y2) to
designate the clipping rectangle in world coordinates.
:CLIP-PIXEL - NIL (the default), to indicate that clipping in
viewports is turned off in this attribute block; or a list
of four fixnums in the form (xl yl x2 y2) to designate the
clipping rectangle in device coordinates.
:FILL-PATTERN
One of
the
keywords
displayed
by
the
SHOW-FILL-PATTERNS function.
:FONT
Either a character
string
containing
the
file
specification of a font file (or a logical name equated to a
font file), a pathname to a font file, or a list containing
keyword-value pairs.
If you supply a list, each keyword
must be one of the font specification keywords displayed by
the SHOW-FONTS function, and its value must be a character
string. Supply only those keyword-value pairs displayed by
SHOW-FONTS for the font you want.
:LEFT-MARGIN - A single-float numb~r specifying the left margin
for text operations.
The default is the left edge of the
virtual display's default window.
:LEFT-MARGIN-PIXEL - A fixnum specifying the left margin for text
operations in all windows mapped into a particular virtual
display. The default is O.
:LINE-STYLE - Either one of the line style specification keywords
(:DASHED, :DOTTED, :DASHED-DOTTED, or :SOLID), or a bit
vector that specifies the line style through the value of
its bits.
The default is :SOLID.
If you supply a bit
vector, it must be of length 32 or less; if less, it will be
replicated to form a 32-bit vector.
:LINE-WIDTH - Either a single float number specifying the width
of a line in multiples of the normal line width, or a list
in the form (n :WORLD-COORDINATES), where n is a single
float that specifies the width in world coordinates. The
default is 1.0. If you use the list form to specify world
coordinates, the width of lines drawn with that attribute
block is subject to scaling when displayed in a viewport •.
Lines whose width is specified as a multiple of the normal
width are not scaled.
72

GRAPHICS SYSTEM COMPONENTS

:WRITING-INDEX - An integer specifying an entry in a color map.
The integer must be in the range of the entries in the
virtual display's color map. The default is 1.
:WRITING-MODE
:OVERLAY
(the
default),
:TRANSPARENT,
:OVERLAY-NEGATE,
:COMPLEMENT, :REPLACE, :REPLACE-NEGATE,
:ERASE, :ERASE-NEGATE, or :COPY.
Return Value
Undefined
Corresponding MicroVMS Routines

Attribute

Routine

:ARC-TYPE
:BACKGROUND-INDEX
:CHARACTER-SPACING
:CLIP
:CLIP-PIXEL
:FILL-PATTERN
:FONT
:LEFT-MARGIN
:LEFT-MARGIN-PIXEL
:LINE-STYLE
:LINE-WIDTH
:WRITING-INDEX
:WRITING-MODE

UIS$SET_ARC_TYPE
UIS$SET_BACKGROUND_INDEX
UIS$SET_CHAR_SPACING
UIS$SET_CLIP
UISDC$SET_CLIP
UIS$SET_FILL_PATTERN
UIS$SET_FONT
UIS$SET_LEFT_MARGIN
UISDC$SET_LEFT_MARGIN
UIS$SET_LINE_STYLE
UIS$SET_LINE_WIDTH
UIS$SET_WRITING_INDEX
UIS$SET~WRITING_MODE

SET-BUTTON-ACTION Function

Specifies the action to be performed when a pointer button is pressed
or released. The action can be specified for an entire window or for
a specified rectangle in a window.
The action can be either an
interrupt
function
identifier
(iif-id) previously returned by
INSTATE-INTERRUPT-FUNCTION, or NIL, in which case no
interrupt
function will be invoked. If a function is specified, it will receive
two arguments: the button code, and an indication of whether the
button was pressed (T) or released (NIL). These two arguments precede
any that you specify with INSTATE-INTERRUPT-FUNCTION. You can compare
the button code with the POINTER-BUTTON-n constants.
NOTE

GRAPHICS SYSTEM COMPONENTS

See Section 5.1.3
pointer buttons.

for

information

about

getting

input

from

Format
UIS:SET-BUTTON-ACTION display window action
&OPTIONAL x1 y1 x2 y2
Arguments
display

A window
action
Either an iif-id to specify an
specify no action

interrupt

function,

NIL

x1 y1 x2 y2

Four single floats designating the coordinates of two opposite
corners of a rectangle in world or transformation coordinates.
Button transitions trigger the action only if the pointer is
within the rectangle at the time.
If these arguments are
omitted, the entire window is sensitive to button transitions.

Return Value
Undefined
Corresponding KicroVIIS Routine
UIS$SET_BUTTON_.AST
SET-BUTTON-ACTION-PIXEL Function

Specifies the action to be performed when a pointer button is pressed
or released.
The action can be specified for an entire viewport or
for a rectangle in a viewport specified in device coordinates.
The
action can be either an interrupt function identifier (iif-id).
previously returned by INSTATE-INTERRUPT-FUNCTION., or NIL, in which
case no interrupt function will be invoked.
If a function is

GRAPHICS SYSTEM COMPONENTS

specified, it will receive two arguments: the button code, and an
indication of whether the button was pressed (T) or released (NIL).
These
two
arguments
precede
any
that
you
specify
with
INSTATE-INTERRUPT-FUNCTION.
You can compare the button code with the
POINTER-BUTTON-n constants.
NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-BUTTON-ACTION-PIXEL when the system is
resumed.
See Section 5.1.3 for more information about getting input from
O pointer
buttons.

Format
UIS:SET-BUTTON-ACTION-PIXEL window action
&OPTIONAL xl yl x2 y2

Arguments
Qwindow
A window

action
Either an iif-id to specify an
specify no action

interrupt

function,

NIL

Qx1 yl x2 y2
Four fixnums designating the device coordinates of two opposite
corners of a rectangle in the viewport associated with window.
Button transitions trigger the action only if the pointer is
within the rectangle at the time.
If these arguments are
omitted, the entire viewport is sensitive to button transitions.

Return Value
Undefined

Corresponding MicroVMS Routine

UISDC$SET_BUTTON_AST

GRAPHICS SYSTEM COMPONENTS
SET-CLOSE-ACTION Function

Specifies the action to be performed when the user closes a window via
the Delete selection of the Window Options menu. The action can be
one of the following:

interrupt function identifier (iif-id) previously returned
by INSTATE-INTERRUPT-FUNCTION. No arguments are passed to the
function
unless
you
specified
them
with
INSTATE-INTERRUPT-FUNCTION.

•

:DISALLOW, in which case the user is not allowed to close
window.

•

:DELETE, in which case the DELETE-WINDOW function
for the window when the user closes the window.

the

invoked

:DELETE-DISPLAY, in which case the DELETE-DISPLAY function is 0
• invoked
for the display into which the window is mapped.
Deleting the display automatically deletes the window as well.
The default action taken by VAX LISP is to prohibit the user from
closing the window.
Specifying :DISALLOW as the action argument to
SET-CLOSE-ACTION restores this default.
See the description of
DELETE-WINDOW for information about the :DELETE action.

NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-CLOSE-ACTION when the system is resumed.
See Section 2.4.6.3 for more information about using this function.

Format
UIS:SET-CLOSI-ACTION window action
Arguments
window
Th~ window associated with the viewport for which a close
is to be specified

action

0
76

GRAPHICS SYSTEM COMPONENTS

action

Either an iif-id to specify an interrupt function, or :DISALLOW
to prevent the user from closing the window, or :DELETE to delete
the wiridow, or :DELETE-DISPLAY to delete the window's display
Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_CLOSE_AST
SET-COLOR Function

an entry in the color map associated with a virtual display to
0 Sets
specified color. See Section 3.4 for more information about color.

Format
UIS:SET-COLOR display color-id r g b
Arguments

Q display
A virtual display

color-id
integer specifying an entry in the color map
display

associated

with

g b

Three floating-point numbers in the range 0.0 - 1.0, inclusive,
specifying
the
intensities for the red, green, and blue
components of the color
Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_COLOR

0
77

GRAPHICS SYSTEM COMPONENTS
SET-GAIN-KB-ACTION Function

Specifies the action to be performed when the physical keyboard is
attached to a specified virtual keyboard. The action can be either an
interrupt function identifier (iif-id)
previously
returned
by
INSTATE-INTERRUPT-FUNCTION,
or NIL, in which case no interrupt
function is invoked.
If an interrupt function is specified, no
arguments are passed to it upon invocation unless you specified them
with INSTATE-INTERRUPT-FUNCTION.

NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-GAIN-KB-ACTION when the system is resumed.

See Section 6.1 for more information about using virtual keyboards.
Format
UIS:SET-GAIN-KB-ACTION keyboard action
Arguments

keyboard
A virtual keyboard
action
Either an iif-id to specify an
specify no action

interrupt

function,

NIL

Return Value
Undefined
Corresponding KicroVMS Routine
UIS$SET_GAIN_KB_AST
SET-INTENSITY Function

Sets an entry in the color map associated with a virtual display to a
specified equivalent monochrome intensity. See Section 3.4 for more
information about color and intensity.

0
78

GRAPHICS SYSTEM COMPONENTS

Format
UIS:SET-INTENSITY display color-id i
Arguments
display

A virtual display
color-id
An integer specifying an entry in the color map

associated

with

display
i

A floating-point number in the range 0.0 - 1.0, inclusive
Return Value
Undefined
Corresponding MicroVMS Routine

UIS$SET_INTENSITY
SET-KB-ACTION Function

Specifies the action to be performed when any keyboard key is pressed.
The action can be either an interrupt function iaentifier (iif-id)
previously returned by INSTATE-INTERRUPT-FUNCTION, or NIL, in which
case no interrupt function will be invoked. If an interrupt function
is speciifed, it receives two arguments:
1.

A character if the key was a control or printing key, and an
integer otherwise. (See Chapter 6 and the description of the
K-TRM-xxx constants for more information about this return
value.)

A flag to indicate the key state.
for future use.

This argument is

reserved

, Additional arguments are passed to the function if you specified
with INSTATE-INTERRUPT-FUNCTION.

them

The action is invoked only once for each keystroke.
This is unlike
SET-BUTTON-ACTION, for which the action is invoked once when a pointer
button is pressed and again when it is released.

GRAPHICS SYSTEM COMPONENTS
NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-KB-ACTION when the system is resumed.
See Section 6.2 for more
from virtual keyboards.

information

about

interpreting

keystrokes

Format
UIS:SET-KB-ACTION keyboard action
Arguments

keyboard
The virtual keyboard for which the function is to be returned
action
Either an iif-id to specify an
specify no action

interrupt

function,

NIL

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_KB_AST

0
Enables or disables one or more attributes for a specified virtual
SET-KB-ATTRIBUTES Function

keyboard.
Each virtual keyboard maintains its own set of attributes,
which take effect only when the virtual keyboard is connected to the
physical keyboard.
Unless the keyword specifying an attribute is specifically mentioned
in the function call, the current setting of the attribute remains
unaffected. In other words, a default of NIL is not assumed for those
keywords not included in the argument list.
See Section 6.1.4 for more information about keyboard attributes.

0
80

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-KB-ATTRIBUTES keyboard
&KEY :AUTOREPEAT :KEYCLICK :FUNCTION-KEYS-6-10
:FUNCTION-KEYS-11-14 :FUNCTION-KEYS-17-20
:HELP-DO-KEYS :EDITING-KEYS-1-6 :ARROW-KEYS
:KEYPAD-KEYS :CLICK-VOLUME
Arguments
keyboard
A keyboard
:AUTOREPEAT
Tor NIL, causing keyboard autorepeat to be enabled or disabled

0 :KEYCLICK

Tor NIL, causing keyboard keyclick to be enabled or disabled
:FUNCTION-KEYS-6-10
Tor NIL, enabling or disabling delivery of keys F6-F10

0 :FUNCTION-KEYS-11-14
Tor NIL, enabling or disabling delivery of keys F11-F14
:FUNCTION-KEYS-17-20
Tor NIL, enabling or disabling delivery of keys F17-F20

:HELP-DO-KEYS
Tor NIL, enabling or disabling delivery of HELP and DO keys
:EDITING-KEYS-1-6
Tor NIL, enabling or disabling delivery of editing
E1-E6

keypad

keys

:ARROW-KEYS
Tor NIL, enabling or disabling delivery of arrow keys
:KEYPAD-KEYS
Tor NIL, enabling or disabling delivery of numeric keypad keys

0
81

GRAPHICS SYSTEM COMPONENTS

:CLICK-VOLUME
An integer between
keyclick volume

(quiet)

and

(loud),

specifying

the

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_KB_ATTRIBUTES
SET-KB-COMPOSE2 Function

This function loads a 2-stroke compose sequence table into a virtual
keyboard.
Omitting the table and length arguments returns the
keyboard to the system default state.

A keyboard table can be implemented in LISP as an alien structure.
The MicroVMS workstation Video Device Driver Manual contains a
description of a keyboard table.
Two-stroke compose sequences can be used on all keyboards
North American keyboard.

except

the

Format

UIS:SET-KB-COMPOSE2 keybo~rd &OPTIONAL table length
Arguments

keyboard

A virtual keyboard

table length
appropriate table, as described in the MicroVMS Workstation
Video Device Driver Manual, and its length in bytes. Omitting
these arguments returns the keyboard to the system default
2-stroke compose sequence table.

Return Value
Undefined

Corresponding HicroVMS Routine
UIS$SET_KB_COMPOSE2

0
82

GRAPHICS SYSTEM COMPONENTS
SET-KB-COMPOSE3 Function

function loads a 3-stroke compose sequence table into a virtual
0 This
keyboard.
Omitting the table and length arguments returns the
keyboard to the system default state.
A keyboard table can be implemented in· LISP as an alien structure.
The MicroVMS Workstation Video Device Driver Manual contains a
description of a keyboard table.
Format
UIS:SET-KB-COMPOSE3 keyboard &OPTIONAL table length
Arguments

keyboard
A virtual keyboard

O Return Value

Undefined
Corresponding BicroVMS Routine
UIS$SET_KB_COMPOSE3

O SET-KB-KEYTABLE Function
This function loads a keyboard equivalence
keyboard.
Omitting the table and length
keyboard to the system default state.

table into a virtual
arguments returns the

A keyboard table can be implemented in LISP as an alien structure.
The MicroVMS Workstation Video Device Driver Manual contains a
description of a keyboard table.
Format
UIS:SET-KB-KEYTABLE keyboard &OPTIONAL table length

0
83

GRAPHICS SYSTEM COMPONENTS

Arguments

keyboard
A virtual keyboard
table length
An appropriate table, as described in the MicroVMS Workstation
Video Device Driver Manual, and its length in bytes. If these
arguments are omitted, the keyboard is returned to the default
keyboard table.
1

Return Value
Undefined

Corresponding MicroVMS Routine
UIS$SET_KB_KEYTABLE
, SET-LOSE-KB-ACTION Function

Specifies the action to be performed when the physical keyboard is
disconnected from a specified virtual keyboard. The action can be
either an interrupt function identifier (iif-id) previously returned
by INSTATE-INTERRUPT-FUNCTION, or NIL, in which case no interrupt
function is invoked.
If an interrupt function is specified, no
arguments are passed to it upon invocation unless you specified them
with INSTATE-INTERRUPT-FUNCTION.

NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-LOSE-KB-ACTION when the system is resumed.

See Section 6.1 for more information about using virtual keyboards.
Format
UIS:SET-LOSE-KB-ACTION keyboard action
Arguments

keyboard

A keyboard
84

GRA--P-HICS SYSTEM COMPONENTS

action

Either an iii-id to specify an
specify no action

interrupt

function,

NIL

Return Value
Undefined
Corresponding KicroVMS Routine
UIS$SET_LOSE_KB_AST
SET-MOVE-INFO-ACTION Function

Specifies the action to be performed when a specified viewport is
The action can be either an interrupt function identifier
0 moved.
(iif-id) previously returned by INSTATE-INTERRUPT-FUNCTION, or NIL, in
which case no interrupt function is invoked. If an interrupt function
is specified, no arguments are passed to it upon invocation unless you
specified them with INSTATE-INTERRUPT-FUNCTION.
NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and ·all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue
SET-MOVE-INFO-ACTION
when the system is
resumed.
See Section 2.4.3 for information about, and an example of, using this
function.

0 Format

UIS:SET-MOVE-INFO-ACTION window action

Arguments
window
The window associated with the viewport for which a
is to be specified

move

action

NIL

action

Either an iif-id to specify an
specify no action

interrupt

function,

·-----..· - · - - · - - - - - - - - - - - - - - - - - - - - - - - - - -

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding MicroVMS Routine

UIS$SET_MOVE_INFO_AST
SET-POINTER-ACTION Function

Specifies the action to be performed when the pointer cursor moves
within and/or exits a window or a specified world-coordinate rectangle
in a window. The action(s) can be either an interrupt function
identifier (iif-id) previously returned by INSTATE-INTERRUPT-FUNCTION,
or NIL, in which case no interrupt function is invoked.
If an
interrupt function is specified, no arguments are passed to it upon
invocation unless you specified them with INSTATE-INTERRUPT-FUNCTION.

NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-POINTER-ACTION when the system is resumed.
See Section 5.1.2 for information about using this function.
5 contains many examples of its use.

0
Chapter

Format

UIS:SET-POINTER-ACTION display window
move-action exit-action
&OPTIONAL x1 y1 x2 y2

Arguments
display
A virtual display, transformation, or NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of world coordinates.

window
A window

0
86

GRAPHICS SYSTEM COMPONENTS

move-action

Either an iif-id to specify an interrupt function, or NIL
specify no action, when the cursor moves within the rectangle

exit-action

Either an iif-id to specify an interrupt function, or
specify no action, when the cursor exits the rectangle

NIL

x1 y1 x2 y2

Four single floats designating the world or transformation
coordinates of two opposite corners of a rectangle. The actions
are triggered when the pointer cursor moves within or exits the
rectangle.
If these arguments are omitted, the actions are
triggered when the pointer cursor moves within or exits the
specified window.

Return Value
Undefined

Corresponding HicroVHS Routine

UIS$SET_POINTER_AST
SET-POINTER-ACTION-PIXEL Function

Specifies the action to be performed when the pointer cursor moves
within and/or exits a viewport or a specified.device-coordinate
rectangle in a viewport.
The action can be either an interrupt
function
identifier
(iif-id)
previously
returned
by
INSTATE-INTERRUPT-FUNCTION, or NIL, in which case no
interrupt
function is invoked.
If an interrupt function is specified, no
arguments are passed to it upon invocation unless you specified them
with INSTATE-INTERRUPT-FUNCTION.
NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-POINTER-ACTION-PIXEL when the system is
resumed.
See Section 5.1.2 for information about using this function.

0
87

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-POINTER-ACTION-PIXEL window move-action exit-action
&OPTIONAL x1 y1 x2 y2
Arguments
window
A window
move-action
Either an iif-id to specify an interrupt function, or NIL
specify no action, when the cursor moves within the rectangle

exit-action
Either an iif-id to specify an interrupt function, or
specify no action, when the cursor exits the rectangle

NIL

x1 y1 x2 y2

Four fixnums designating the device coordinates of two opposite
corners of a rectangle in the viewport associated with window.
The actions are "triggered when the pointer cursor moves within or
exits the rectangle. If these arguments are NIL or omitted, the
actions are triggered when the pointer cursor moves within or
exits the specified window.

Return Value
Undefined
Corresponding HicroVMS Routine

UISDC$SET_POINTER_AST
SET-POINTER-PATTERN Function

Establishes a new pointer cursor pattern to.be used when the pointer
cursor is within a given window or specified portion of a window.
Once established, the new pattern will be substituted for the current
pointer pattern when the pointer cursor enters that area. This
function can be called as often as desired to establish different
patterns for different rectangles.
See Section 5.1.2 for information about using this
example of its use.

function,

and

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-POINTER-PATTERN display window bitmap
active-x active-y
&OPTIONAL x1 y1 x2 y2
Arguments
display
A virtual display, transformation, or NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of world coordinates.

window
A window

bitmap
The new cursor pattern, in the form of a 16x16 bitmap

active-x active-y

Two fixnums in the range 0-15 designating the active bit in the
cursor pattern, relative to the bit at the lower-left corner
(0,0). The active bit is used to calculate the pointer position.
x1 y1 x2 y2

Four single floats designating the world or transformation
coordinates of two opposite corners of a rectangle. The new
cursor pattern will be used when the cursor enters
this
rectangle.
If these arguments are omitted, the entire window is
used.

Return Value
Undefined

Corresponding KicroVIIS Routine
UIS$SET_POINTER_PATTERN
SET-POINTER-PATTERN-PIXEL Function

Establishes a new pointer cursor pattern to be used when the pointer
is within a given viewport or specified portion of a viewport. On.ce
established, the new pattern will be substituted for the current
89

GRAPHICS SYSTEM COMPONENTS

pointer pattern when the pointer enters that area. This function can
be called as often as desired to establish different patterns for
different rectangles.

See Section 5.1.2 for information about using this function.
Format
UIS:SET-POINTER-PATTERN-PIXEL window bitmap active-x active-y
&OPTIONAL xl yl x2 y2

Arguments
window
A window

bitmap

The new cursor pattern, in the form of a 16x16 bitmap
active-x active-y

Four fixnums designating the device coordinates of two opposite
corners of a rectangle in the viewport associated with window.
The new cursor pattern will be used when the cursor enters this
rectangle.
If these arguments are omitted, the entire viewport
is used.

Return Value
Undefined

Corresponding KicroVMS Routine
UISDC$SET_POINTER_PATTERN
SET-POINTER-POSITION Function

Moves the pointer cursor to a new position, specified in world
coordinates.
The function returns T if the operation was successful,
that is, if the new position is within the specified window and is
visible. If the new position is not within the specified window or is
invisible on the screen, the function returns NIL-and does not move
the pointer cursor.
90

GRAPHICS SYSTEM COMPONENTS

Format
UIS:SET-POINTER-POSITION display window x y
Arguments
display
A virtual display, transformation, or NIL.

The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this 'display. A transformation must be one that is
mapped into that display. Specifying a transformation allows you
to use transformation coordinates instead of world coordinates.

window

A window

x y

Two single
coordinate

fl~ats

designa~ing

world

transformation

Return Value

T if the new position falls within·· the specified window and is
visible; NIL if the new positiQn falls outside the window or if
it is invisible
Corresponding HicroVHS Routine
UIS$SET_POINTER~POSIT10N
SET-POINTER-POSITION-PIXEL Function

0 Moves the pointer cursor to a new position, spe·cifl:'ed· · in device
coordinates.
The function returns T if the operation was·successful,
that is, if the new position is within the specified viewport and is
visible.
If the new posit!on is outside the specified viewport or is
invisible, the function returns NIL and does not move t_he pointer
cursor.
Format
UIS:SET-POINTER-POSITION-PIXEL window x y
Arguments

window
A window
91

GRAPHICS ·SYSTEM COMPONENTS

x y

Two fixnums designating a device coordinate in the window
Return Value
T if the new position falls within the specified viewport and is
visible; NIL if the new position falls outside the viewport or if
it is invisible
Corresponding NicroVIIS Routine
UISDC$SET_POIN?ER_POSITION
SET-POSITION Function

sets the current text position for a virtual display.
The text
position is· the alignment point on the baseline of the next character
to be output.

C)
~

See section 3.6.2 for information about text positioning.
Format
UIS:SET-POSITION display x y

Arguments
display
The virtual display or transformation for which the text position
is to be set.
x y

Two single floats designating the world coordinates of
position.

the

text

Return Value
Undefined
Corresponding NicroVIIS Routine
UIS$SET_POSITION
SET-POSITION-PIXEL Function

Sets the device-coordinate text position for windows mapped· into a ~
virtual display.
The text position is the leftmost point on the\..._)
92

GRAPHICS SYSTEM COMPONENTS

baseline of the next character to be output.
The device-coordinate
text position is independent of the display text position; however,
all windows mapped into a
virtual
display
share
the
same
device-coordinate text position.
See Section 3.6.2 for information about text positioning.
Format
UIS:SET-POSITION-PIXEL window x y
Arguments

window

The window for which the text position is to be set.
x y

Two fixnums
position.

designating

the

device

coordinates

the

text

Return Value
Undefined

0 Corresponding KicroVMS Routine
UISDC$SET_POSITION
SET-RESIZE-ACTION Function

Specifies the action to be performed when the user resizes a window
via the "Change the size" selection of the "Window Options" menu. The
action can be one of the following:
•

interrupt function identifier (iif-id) previously
by
INSTATE-INTERRUPT-FUNCTION.
The
interrupt
receives the following eight arguments:

returned
function

Two floating point numbers indicating the new position, in
screen coordinates (centimeters), of the lower-left corner
of the viewport.
Two floating point numbers indicating the
height, in centimeters, of the viewport.

new

width

and

Four floating point numbers indicating the new coordinates
of the corners of the window, in the form x1 y1 x2 y2. The
coordinates are world
coordinates
or
transformation
coordinates,
depending
on
the
first
argument
to
93

GRAPHICS SYSTEM COMPONENTS

SET-RESIZE-ACTION.
:DISALLOW, in which case the user is not allowed to resize the Q
• window.
•

:DEFAULT or NIL, in which case a default action is invoked
when the user resizes the window. The default action is to
change the size of both the viewport and the window by the
amount and in the direction the user requests. For example,
if the user stretches the viewport to the right, the window
into the virtual display will also stretch to the right,
exposing more of what is in the virtual display.

If you specify an interrupt function as the action, the interrupt
function receives the eight arguments noted above before any arguments
that you specified with INSTATE-INTERRUPT-FUNCTION. Note that if you
specify an interrupt function, the graphics system does not resize the
window and viewport automatically. The interrupt function can resize
the window and viewport by calling the RESIZE-WINDOW function and
passing it the same eight arguments it received when it was invoked.

NOTE

When you suspend a LISP system, all your interrupt
functions are uninstated and all actions are reset to
NIL.
You must reinstate interrupt functions and
reissue SET-RESIZE-ACTION when the system is resumed.
See Section 2.4.6.2 for information about
Section 7.2.1 contains an example of its use.

using

this

function.

Format
UIS:SET-RESIZE-ACTION display window action
Arguments

display
A virtual display, transformation, or .NIL. The virtual display
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that is
mapped into that display.
window
The window for which the function is to be returned

0
94

GRAPHICS SYSTEM COMPONENTS

action

Either an iif-id to specify an interrupt function, or :DISALLOW
to prevent the user from resizing the window, or NIL to specify
no action.
See the description of the function above for
information about arguments received by the interrupt function.
Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SET_RESIZE_AST

SHOW-FILL-PATTERNS Function

Displays all the available fill patterns, along with the keyword that
designates each one. Use this function to select a fill pattern, then
use the corresponding keyword as the value of the :FILL-PATTERN
keyword in the SET-ATTRIBUTE function.
See Section 3.5.3.2 for information about specifying fill patterns.

Format
SHOW-FILL-PATTERNS
Arguments
None
Return Value

Undefined
Corresponding MicroVMS Routine
None
SHOW-FONTS Function

Displays a table of all the available fonts. The table consists of a
row for each font, and a column for each of the font specification
keywords that you can use with the :FONT keyword of the SET-ATTRIBUTE
function. Each table entry is a character string that is the value of
~he font specification keyword for that particular font. No entry in
a column indicates that the font has the default value for that font
specification keyword.

GRAPHICS SYSTEM CUMl-'UNt:N I~

See Section 3.6.3.2 for information about specifying fonts.

Format
SHOW-FONTS

Arguments
None
Return Value
Undefined
Corresponding MicroVMS Routine
None

SOUND-BELL Function

Sounds the keyboard "bell."
Format
UIS:SOUND-BELL &OPTIONAL volume device

Arguments

volume
A fixnum in the range 1-8 specifying the volume of the sound. If
this argument is omitted, the volume is taken from the default
workstation bell volume.

device
A character string specifying the output device.
SYS$WORKSTATION.

The default

Return Value
Undefined
Corresponding MicroVMS Routine
UIS$SOUND_BELL

0
96

GRAPHICS SYSTEM COMPONENTS
SOUND-CLICK Function .

0 Sounds the keyboard keyclick.
Format
UIS:SOUND-CLICK &OPTIONAL volume device
Arguments

volume
A fixnum in the range 1-8 specifying the volume of the sound. If
this argument is omitted, the volume is taken from the default
workstation keyclick volume.

device
A character string specifying the output device.

The default

SYS$WORKSTATION.
Return Value
Undefined

Corresponding MicroVMS Routine
UIS$SOUND_CLICK
TEST-KB Function

Returns T if the specified virtual keyboard
physical keyboard, and NIL otherwise.

0 Format
UIS:TEST-KB keyboard
Arguments

keyboard
A keyboard
Return Value
Tor NIL
Corresponding MicroVMS Routine

UIS$TEST_KB
97

connected

the

GRAPHICS SYSTEM COMPONENTS

TEXT Function

Draws a character string in a virtual display, and moves the display's
text position to the end of the string.
See Section 3.6 for
information on text output operations.

Format
UIS:TEXT display att-block text-string &OPTIONAL x y

Arguments
display

The virtual display or transformation in which the text is to
drawn

att-block

A fixnum in the range 0-255, designating the attribute block from
which font and other text attributes are to be taken
text-string

A character string or a single character
x y

0
Two single floats specifying the world coordinates of the
upper-left corner of t~e text string. If these arguments are
omitted, the string begins at the current text position.

Return Value
Undefined

Corresponding KicroVMS Routine
UIS$TEXT

TEXT-PIXEL Function

Draws a
character
string
in
a
viewport,
and
device-coordinate text position to the end of the string.
3.6 for information on text output operations.

moves
the
See Section

Format
UIS:TEXT-PIXEL window att-block text-string &OPTIONAL x y

0
98

GRAPHICS SYSTEM COMPONENTS

Arguments

0 window
The window in which the text is to be drawn
att-block
A fixnum in the range 0-255, designating the attribute block from
which font and other text attributes are to be taken
text-string
A character string or a single character
x y

Two fixnums specifying the device coordinates of the upper-left
corner of the text string. If these arguments are omitted, the
string begins at the current device-coordinate text position.
Return Value
Undefined

Corresponding NicroVMS Routine
UISDC$TEXT
TRANSFORMATION Type Specifier

Designates objects
of
type
CREATE-TRANSFORMATION function.

TRANSFORMATION,

created

the

object

and

NIL

O TRANSFORMATIONP Function
Returns T
otherwise.

its

argument

Format
UIS:TRANSFORMATIONP object
Arguments
object

Any LISP object

transformation

GRAPHICS SYSTEM COMPONENTS

Return Value

Tor NIL

Corresponding MicroVMS Routine
None
UIS-ID Function

Returns the UIS ID of its argument for use with CALL-OUT.
argument may be a display, tr,nsformation, window, or keyboard.

The

Format
UIS:UIS-ID object

Arguments
object
An object of type DISPLAY, TRANSFORMATION, WINDOW, or KEYBOARD

Return Value
An integer that is the UIS ID of the object

Corresponding MicroVMS Routine
None
WINDOW-DISPLAY Function

Returns the display with which a specified window is associated.

Format
UIS:WINDOW-DISPLAY window

Arguments
window
A window object

Return Value
A display

0
100

GRAPHICS SYSTEM COMPONENTS

Corresponding HicroVMS Routine
None
WINDOW Type Specifier

Designates objects
function.

type

WINDOW,

created

the

CREATE-WINDOW

WINDOWP Function

Returns T if its argument is a window and NIL otherwise.

Format
UIS:WINDOWP object
Arguments
object

Any LISP object

Return Value
Tor NIL
Cor~esponding MicroVMS Routine
None
WINDOW-STREAM-ATTRIBUTE-BLOCK Function

0 Returns the attribute block used to write output in a particular
window output stream.
the attribute block.

You can use this function with SETF to change

See Chapter 7 for information about window output streams.
Format
UIS:WINDOW-STREAM-ATTRIBUTE-BLOCK window-output-stream
Arguments

window-output-stream

A
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW
101

wi~h

GRAPHICS SYSTEM COMPONENTS

Return Value
An integer that designates the
output to window-output-stream

attribute

block

used

write

Corresponding MicroVMS Routine
None
WINDOW-STREAM-HORIZONTAL-OVERFLOW Function

Returns a keyword indicating the behavior of a particular window
output stream when an attempt is made to write text to the right of
the viewing area. The keyword can be either :TRUNCATE or :WRAP.
You
can use this function with SETF to change the horizontal overflow
behavior.
See Chapter 7 for information about window output streams.

Format
UIS:WINDOW-STREAM-HORIZONTAL-OVERFLOW window-output-stream
Arguments
window-output-stream
A
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return Value
A keyword (either :TRUNCATE or :WRAP) that indicates
horizontal overflow behavior of window-output-stream

the

Corresponding MicroVMS Routine
None
WINDOW-STREAM-VERTICAL-OVERFLOW Function

Returns a keyword indicating the behavior of a particular window
output stream when an attempt is made to output text beyond the bottom
of the viewing area. The keyword can be either :SCROLL, :WRAP, or
:TRUNCATE. You can use this function with SETF to change the vertical
overflow behavior.
See Chapter 7 for information about window output streams.

0
102

GRAPHICS SYSTEM COMPONENTS

Format

UIS:WINDOW-STREAM-VERTICAL-OVERFLOW window-output-stream
Arguments
window-output-stream

A
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return Value
A keyword (either :SCROLL, :WRAP, or :TRUNCATE) that
the vertical overflow behavior of window-output-stream

indicates

Corresponding MicroVMS Routine
None
WINDOW-STREAM-VIEWING-AREA Function

Returns a list of integers in the form (xl yl x2 y2) to indicate the
viewing
area
for a specified window output stream in device
coordinates. You can use this function with SETF to change the
viewing area.
When you change the viewing area, the current text
position (the position where text from the stream will next be placed)
is moved to the top left corner of the new viewing area, and the new
viewing area is erased. If you specify a value of NIL when using SETF
with WINDOW-STREAM-VIEWING-AREA, the viewing area is changed to occupy
the entire viewport.
See Chapter 7 for information about window output
7.2.1 contains an example of this function in use.

streams.

Section

0 Format

UIS:WINDOW-STREAM-VIEWING-AREA window-output-stream

Arguments
window-output-stream
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return Value

A list of four integers designating the viewing
for window-output-stream in device coordinates

103

area

rectangle

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine
None
WINDOW-STREAM-WINDOW Function

Returns the window object to which the window output stream given in
its argument sends output. You cannot use SETF with this function to
change a stream's output window.
See Chapter 7 for information about window output streams.
Format
UIS:WINDOW-STREAM-WINDOW window-output-stream

.Arguments

window-output-stream
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return value

A window object

Corresponding KicroVMS Routine
None
WINDOW-STREAM-X-POSITION Function

Returns an integer indicating, in device coordinates, the horizontal
position at which text will be output from a specified window output
stream. You can use SETF with this function to change the horizontal
output position.

See Chapter 7 for information about window output streams.

Format
UIS:WINDOW-STREAM-X-POSITION window-output-stream

window-output-stream
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

104

with

GRAPHICS SYSTEM COMPONENTS

Return Value

An integer indicating the horizontal text position
window output stream in device-coordinate units

for

this

Corresponding MicroVMS Routine
None
WINDOW-STREAM-V-POSITION Function

Returns an integer indicating, in device coordinates, the vertical
position at which text will be output from a specified window output
stream. You can use SETF with this function to change the vertical
output position.

Q See Chapter 7 for information about window output streams.
Format
UIS:WINDOW-STREAM-Y-POSITION window-output-stream
Arguments

window-output-stream
A
window
output
stream
previously
created
MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

with

Return Value
integer indicating the vertical text position for this
output stream in device-coordinate units

window

Q Corresponding MicroVMS Routine
None
WITH-OUTPUT-TO-WINDOW Macro

Creates a window output stream and binds it to a variable. The macro
then executes its forms as an implicit PROGN and returns the value of
the last form. Finally, the stream is closed and unbound from the
variable to which it was bound.
See Chapter 7 for information about window output streams.

0
105

GRAPHICS SYSTEM COMPONENTS

Format

UIS:WITH-OUTPUT-TO-WINDOW (var window &REST options)
{declaration}* {form}*
Arguments

var window
A variable var which is bound to a window output stream into
window. The stream and binding exist only while the forms in the
body of the function are executing.
options
Keyword-value pairs; the allowable keywords are those
specify with the MAKE-WINDOW-OUTPUT-STREAM function
Return Value

you

can

The value of the last form evaluated
Corresponding MicroVMS Routine
None

0
106

INDEX

Page numbers in the Index in the form c-n (for example, 2-13) refer to
a page in Part I. Page numbers in the form n (for example, 25) refer
to a page in Part II.
-A-

-B-

:ABSOLUTE-POSITION arguments
CREATE-WINDOW, 2-13
MOVE-VIEWPORT, 2-16
Active pixel, 5-2
specifying, 5-7
Aligned position, 3-27
changing, 3-28
obtaining, 3-28
:ARC-TYPE attribute, 3-20
Arcs
closing, 3-19
drawing, 3-19
filling, 3-21
Arrow keys
enabling and disabling, 6-6
integers that represent, 6-7
Attribute block 0, 3-6
Attribute blocks, 3-5
creating and modifying, 3-6
default attribute block, 3-6
in segments, 3-32
spec-ifying, 3-5
temporary, 3-32
:ATTRIBUTE-BLOCK keyword
MAKE-WINDOW-OUTPUT-STREAM, 7-2
WITH-OUTPUT-TO-WINDOW, 7-2
Attributes
for device-coordinate
operations, 3-7
in segments, 3-32
line-drawing, 3-20
modifying, 3-6
obtaining value, 3-8
table of attributes, 3-9
temporary, 3-32
text, 3-30
with -PIXEL suffixes, 3-7
Autorepeat
enabling and disabling, 6-5

Background color, 3-12
controlling, 3-8
:BACKGROUND-INDEX attribute, 3-8
and color maps, 3-13
effect of writing modes, 3-8
:BANNER-TITLE argument, 2-13
Baseline, 3-26
BEGIN-SEGMENT function, 1
using, 3-32
BITBLT accessor functions, 2
BITBLT function, 1
using, 4-6
BITBLT objects
creating, 4-6
BITBLT type specifier, 2
BITBLT-DESTINATION function, 2
BITBLT-DST-H function, 2
BITBLT-DST-OP function, 2
BITBLT-DST-W function, 2
BITBLT-DST-X function, 2
BITBLT-DST-Y function, 2
BITBLT-P functi~n, 3
BITBLT-SOURCE function, 2
BITBLT-SRC-H function, 2
BITBLT-SRC-OP function, 2
BITBLT-SRC-W function, 2
BITBLT-S·RC-X function, 2
BITBLT-SRC-Y function, 2
BITBLT-TEXTURE function, 2
Bitmap arrays, 4-1
comparing, 4-6
creating
with MAKE-BITMAP, 4-6
with READ-IMAGE-PIXEL, 4-2
creating files from, 4-5
destination, 4-7
reading from files, 4-5
source, 4-7
storing in files, 4-5
testing for validity, 4-6
texture, 4-7

Index-1

INDEX

BITMAP-P function, 3
using, 4-6
Bitmaps, 4-1
altering, 4-6
reading from screen, 4-2
writing to screen, 4-3

-cCartesian coordinates, 2-2
:CENTER argument
CREATE-WINDOW, 2-13
MOVE-VIEWPORT, 2-16
Character cell, 3-25
:CHARACTER-SPACING attribute,
3-30
:CHORD arc-type, 3-21
CIRCLE function, 4
and :FILL-PATTERN attribute,
3-20
using, 3-19
CIRCLE-PIXEL function, 5
and :FILL-PATTERN attribute,
3-20
using, 3-19
Circles
drawing, 3-19
:CLIP attribute, 3-10
:CLIP-PIXEL attribute, 3-11
Clipping
using :CLIP attribute, 3-10
using :CLIP-PIXEL attribute,
3-11
Color, 3-13
specifying, 3-16
Color map, 3-13
changing entries in, 3-15
getting information about, 3-16
specifying entries in, 3-16
standard, 3-15
getting information about,
3-15
COMPARE-BITMAPS function, 6
using, 4-6
:COMPLEMENT writing mode, 3-12
Coordinate systems, 2-2
alternate, ~-21
device coordinates, 2-5
screen coordinates, 2-8
world coordinates, 2-4
:COPY writing mode, 3-13
and screen images, 4-5

COPY-BITBLT function, 7
CREATE-DISPLAY function, 7
arguments to, 2-9
using, 2-8
CREATE-KB fuqction, 8
using, 6-4
CREATE-TERMINAL function, 8.
CREATE-TRANSFORMATION function,
10
using, 2-21
CREATE-UIS-STRUCTURE function, 11
CREATE-WINDOW function, 12
and display list, 3-2
optional arguments, 2-11
specifying window rectangle,
2-11
using, 2-10
Cursor
see Pointer cursor
CYCLE key
and virtual keyboards, 6-5

·D-

:DASHED line-style, 3-22
:DASHED-DOTTED line-style, 3-22
Default attribute block, 3-6
DELETE-DISPLAY function, 15
invoked through
SET-CLOSE-ACTION, 2-20
using, 2-9
DELETE-KB function, 15
using, 6-4
DELETE-TRANSFORMATION function,
16
using, 2-22
DELETE-WINDOW function, 16
invoked,through
SET-CLOSE-ACTION, 2-20
using, 2-14
Device coordinate system, 2-5
operations using, 3-3
Device coordinates
argument type, 2-5
contrasted to world coordinates,
2-6
Device-coordinate operations, 3-3
accuracy of, 3-4
and display list, 3-2
contrasted to world-coordinate
operations, 3-3
guidelines for using, 3-5

Index-2

INDEX

Device-coordinate operations
(Cont.)
speed of, 3-4
DISABLE-DISPLAY-LIST function, 17
using, 3-2
DISABLE-KB function, 17
using, 6-5
DISABLE-VIEWPORT-KB function, 18
using, 6-4
Display devices
coordinate system, 2-8
determining size, 2-8
resolution, 2-7
determining, 2-7
Display lists, 3-1
advantages and disadantages,
3-2
and ERASE function, 3-34
and MOVE-AREA function, 3-34
and window output streams, 7-6
deletion, 3-3
encoding of information, 3-3
functions that re-execute, 3-2
re-execution, 3-2
when to use, 3-2
DISPLAY type specifier, 18
DISPLAY-WINDOWS function, 19
using, 2-11
DISPLAYP function, 18
using, 2-9
DO key
enabling and disabling, 6-5
integer that represents, 6-7
:DOTTED line-style, 3-22
DUMP-BITMAP function, 19
using, 4-5
-B-

Editing keys
enabling and disabling, 6-5
integers that represent, 6~7
Editor
name conflicts, 1-3
ELLIPSE function, 20
and :FILL-PATTERN attribute,
3-20
using, 3-19
ELLIPSE-PIXEL function, 21
using, 3-19
Ellipses
drawing, 3-19

ENABLE-DISPLAY-LIST function, 22
using, 3-2
ENABLE-KB function, 23
optional window argument, 6-4
using, 6-5
ENABLE-VIEWPORT-KB function, 23
using, 6-4
END-SEGMENT function, 24
using, 3-32
ERASE function, 24
and display list, 3-2, 3-34
effect on viewports, 3-34
using, 3-34
:ERASE writing mode, 3-12
and text, 3-26
:ERASE-NEGATE writing mode, 3-12
and text, 3-26
ERASE-PIXEL function, 25
using, 3-34
ERASE-VIEWING-AREA function, 26
using, 7-2
-F:FILL-PATTERN attribute, 3-21
and CIRCLE functions, 3-20
and ELLIPSE functions, 3-20
and PLOT functions, 3-18
disabling filling, 3-22
displaying fill patterns, 3-21
:FONT attribute, 3-30
and :FILL-P~TTERN attribute,
3-21
and aligned position, 3-27
Font files, 3-30
UIS$FILL_PATTERNS, 3-21
Fonts
and scaling, 3-25
and window output streams, 7-2
obtaining size, 3-31
specifying, 3-30
Function keys
enabling and disabling, 6-5
integers that represent, 6-7
-GGarbage collector
and virtual displays, 2-9
and windows, 2-14
:GENERAL-PLACEMENT argument
CREATE-WINDOW, 2-13

Index-3

INDEX

:GENERAL-PLACEMENT argument
(Cont.)
MOVE-VIEWPORT, 2-16
GET-ABS-POINTER-POSITION function,
26
using, 5-2
GET-ALIGNED-POSITION function, 27
GET-ALIGNED-POSITION-PIXEL
function, 28
GET-ATTRIBUTE function, 28
using, 3-8
GET-ATTRIBUTE-LIST function, 30
using, 3-8
GET-BUTTONS function, 31
using, 5-9
GET-COLOR function, 32
using, 3-16
GET-DISPLAY-SIZE function, 32
determining display size with,
2-8
determining resolution with,
2-7
GET-FONT-SIZE function, 33
using, 3-31
GET-INTENSITY function, 34
using, 3-16
GET-KB-ATTRIBUTE function, 35
using, 6-6
GET-KB-ATTRIBUTE-LIST function,
35
using, 6-6
GET-POINTER-POSITION function, 36
using, 5-2
GET-POINTER-POSITION-PIXEL
function, 37
using, 5-2
GET-POSITION function, 37
GET-POSITION-PIXEL function, 38
GET-VIEWPORT-POSITION function,
38
using, 2-18
GET-VIEWPORT-SIZE function, 39
GET-VISIBILITY function, ·40
using, 2-16
GET-VISIBILITY-PIXEL function, 41
using, 2-16
GET-WINDOW-ATTRIBUTE-LIST
function, 41
GET-WS-COLOR function, 42
using, 3-15
GET-WS-INTENSITY function, 43
using, 3-15

Graphics tablets
see Pointers
-H-

HELP key
enabling and disabling, 6-5
integer that represents, 6-7
:HORIZONTAL-OVERFLOW keyword
MAKE-WINDOW-OUTPUT-STREAM, 7-2
WITH-OUTPUT-TO-WINDOW, 7-2
-I-

IMAGE function, 44
scaling and clipping of images,
4-4
using, 4-3
IMAGE-PIXEL function, 45
using, 4-3
Interrupt functions
and pointer functions, 5-2
passing information to
using arguments, 5-7
using special variables, 5-5
using structures, 5-10
viewport manipulation, 2-17
:INVISIBLE argument
CREATE-WINDOW, 2-14
MOVE-VIEWPORT, 2-16

-K-

K-TRM-xxx constants, 46
KEYBOARD type specifier, 46
KEYBOARDP function, 46
Keyclick
enabling and disabling, 6-5
Keys
characters generated by, 6-7

-L-

:LEFT-MARGIN attribute, 3-31
default value, 3-31
:LEFT-MARGIN-PIXEL attribute,
3-32
default value, 3-32
:LINE-STYLE attribute, 3-22
:LINE-WIDTH attribute, 3-23
LIST-ALL-DISPLAYS function, 48
finding "lost" display, 2-9

Index-4

INDEX

LIST-ALL-WINDOWS fun~tion, 48
LOAD-BITMAP function, 48
using, 4-5

Nonsquare pixels, 2-7
Numeric keypad keys
enabling and disabling, 6-6
integers that represent, 6-7

-M-

MAKE-BITBLT function, 49
using, 4-6
MAKE-BITMAP function, 53
using, 4-6
MAKE-WINDOW-OUTPUT-STREAM
function, 54
using, 7-1
MEASURE-TEXT function, 55
using, 3-29
MEASURE-TEXT-PIXEL function, 56
using, 3-29
Mice
see Pointers
MicroVMS workstation graphics
software, 1-2
relationship to LISP graphics,
1-2
Mouse
see Pointers
MOVE-AREA function, 56
and display list, 3-2, 3-34
effect on viewports, 3-34
using, 3-33
MOVE-AREA-PIXEL function, 57
and window output streams, 7-5
using, 3-34
MOVE-VIEWPORT function, 58
using, 2-16
MOVE-WINDOW function, 59
and display list, 3-2
using, 2-14

NEW-TEXT-LINE function, 60
and :CHARACTER-SPACING, 3-30
and :LEFT-MARGIN, 3-31
effect on text position, 3-27
using, 3-27
NEW-TEXT-LINE-PIXEL function, 60
and :CHARACTER-SPACING, 3-30
and :LEFT-MARGIN-PIXEL, 3-32
effect on text position, 3-28
using, 3-28
:NOBANNER argument, 2-13
:NOBORDER argument, 2-13

-·-

-o:OPEN arc-type, 3-21
output
to window using streams, 7-1
:OVERLAY writing mode, 3-12
:OVERLAY-NEGATE writing mode,
3-12
-P-

Picture elements
see Pixels
:PIE arc-type, 3-21
Pixel coordinates
see Device coordinate system
-PIXEL functions, 3-3
Pixels, 2-5
dimensions, 2-7
determining, 2-7
square and nonsquare, 2-7
PLOT function, 61
and :FILL-PATTERN attribute,
3-18
using, 3-17
PLOT-ARRAY function, 62
and :FILL-P~TTERN attribute,
3-18
using, 3-17
PLOT-ARRAY-PIXEL function, 63
and :FILL-PATTERN attribute,
3-18
using, 3-17
PLOT-PIXEL function, 64
and :FILL-PATTERN attribute,
3-18
using, 3-17
Pointer
making virtual keyboard active
with, 6-5
Pointer buttons
input from, 5-9
obtaining state, 5-9
responding to, 5-10
Pointer cursor, 5-1
active pixel, 5-2
specifying, 5-7

Index-5

INDEX

Pointer cursor (Cont.)
changing appearance, 5-7
overlapping areas, 5-8
obtaining position, 5-2
repositioning, 5-4
responding to exit, 5-7
responding to movement, 5-4
overlapping areas, 5-7
specifying action, 5-4
specifying rectangle, 5-7
specifying appearance, 5-7
Pointer sensitivity, 5-15
POINTER-BUTTON-n constants, 65
using, 5-10
Pointer-sensitive regions, 5-15
Pointers, 5-1
POP-VIEWPORT function, 65
using, 2-16
PUSH-VIEWPORT function, 66
using, 2-16
-R-

READ-IMAGE-PIXEL function, 66
using, 4-2
READ-KB-CHAR function, 67
using, 6-6
Realized color, 3-15
:REPLACE writing mode, 3-12
and text, 3-25
:REPLACE-NEGATE writing mode,
3-12
and text, 3-25
RESIZE-WINDOW function, 68
and display list, 3-2
in interrupt function specified
as resize action, 2-19
using, 2-19
Resolution, 2-7
determining, 2-7

-sScreen coordinate system, 2-8
Screen coordinates
argument type, 2-8
determining bounds, 2-8
Screen images
altering, 4-6
reading from screen, 4-2
storing in f·iles, 4-5
writing to screen, 4-3

Segments, 3-32
nesting, 3-32
SET-ALIGNED-POSITION function, 69
effect on text position, 3-28
using, 3-28
SET-ALIGNED-POSITION-PIXEL
function, 70
effect on text position, 3-28
using, 3-28
SET-ATTRIBUTE function, 71
using, 3-6
in segments, 3-32
SET-ATTRIBUTE-PIXEL function
using, 3-6
SET-BUTTON-ACTION function, 73
arguments passed to interrupt
function, 5-10
using, 5-10
SET-BUTTON-ACTION-PIXEL function,
74
arguments passed to interrupt
function, 5-10
using, 5-10
SET-CLOSE-ACTION function, 76
using, 2-20
SET-COLOR function, 77
using, 3-15
SET-GAIN-KB-ACTION function, 78
using, 6-5
SET-INTENSITY function, 78
using, 3-15
SET-KB-ACTION function, 79
using, 6-6
SET-KB-ATTRIBUTES function, 80
using, 6-6
SET-KB-COMPOSE2 function, 82
SET-KB-COMPOSE3 function, 83
SET-KB-KEYTABLE function, 83
SET-LOSE-KB-ACTION function, 84
using, 6-5
SET-MOVE-INFO-ACTION function, 85
using., 2-17
SET-POINTER-ACTION function, 86
using, 5-4
SET-POINTER-ACTION-PIXEL function,
87
using, 5-4
SET-POINTER-PATTERN function, 88
using, 5-7
SET-POINTER-PATTERN-PIXEL
function,.89
using, 5-7

Index-6

INDEX

SET-POINTER-POSITION.function, 90
using, 5-4
SET-POINTER-POSITION-PIXEL
function, 91
using, 5-4
SET-POSITION function, 92
effect on text position, 3-28
using, 3-28
SET-POSITION-PIXEL function, 92
effect on text position, 3-28
using, 3-28
SET-RESIZE-ACTION function, 93
and window output streams, 7-3
arguments passed to interrupt
function, 2-19
using, 2-19
SHOW-FILL-PATTERNS function, 95
using, 3-21
SHOW-FONTS function, 95
using, 3-31
:SOLID line-style, 3-22
SOUND-BELL function, 96
SOUND-CLICK function, 97
Square pixels, 2-7
Standard color map, 3-15
Streams
output to window, 7-1
SYS$FONT, 3-30
-'1'-

TEST-KB function, 97
Text, 3-23
altering character spacing,
3-30
altering line spacing, 3-30
appearance of, 3-25
boxing, 3-29
centering, 3-29
obtaining dimensions, 3-29
positioning, 3-26
specifying font, 3-30
writing, 3-23
TEXT function, 98
default position, 3-27
effect on text position, 3-27
specifying position with, 3-27
specifying text, 3-24
using, 3-23
Text position, 3-i6
changing, 3-27
device-coordinate, 3-26

Text position (Cont.)
obtaining, 3-28
virtual display, 3-26
windows, 3-26
modified by window output
streams, 7-5
TEXT-KB function
using, 6-5
TEXT-PIXEL function, 98
and window output streams, 7-5
default position, 3-27
effect on text position, 3-27
specifying position with, 3-27
specifying text, 3-24
using, 3-23
Transformation ID, 2-22
TRANSFORMATION type specifier, 99
TRANSFORMATIONP function, 99
using, 2-21
Transformations, 2-21
creating, 2-21
deleting, 2-22
with DELETE-DISPLAY, 2-9
with DELETE-TRANSFORMATION,
2-22
:TRANSPARENT writing mode, 3-13

-uUIS package, 1-2
UIS$FILLPATTERNS, 3-31
UIS-ID function, 100
and transformations, 2-22
and virtual displays, 2-9
and windows, 2-11

-v:VERTICAL-OVERFLOW keyword
MAKE-WINDOW-OUTPUT-STREAM, 7-2
WITH-OUTPUT-TO-WINDOW, 7-2
:VIEWING-AREA keyword
MAKE-WINDOW-OUTPUT-STREAM, 7-2
WITH-OUTPUT-TO-WINDOW, 7-2
:VIEWPORT-HEIGHT argument, 2-12
:VIEWPORT-WIDTH argument, 2-12
Viewports, 2-2
and ERASE function, 3-34
and MOVE-AREA function, 3-34
controlling banner, 2-13
controlling border, 2-13
controlling location, 2-13

Index-7

INDEX

Viewports
controlling location (Cont.)
absolutely, 2-13
creating off-screen, 2-14
generally, 2-13
controlling size, 2-12
controlling visibility, 2-16
coordinate system, 2-5
creating, 2-10
default characteristics, 2-11
deleting, 2-14
by user action, 2-20
determining visibility, 2-16
erasing within, 3-34
moving, 2-16
with RESIZE-WINDOW, 2-14
moving areas within, 3-34
reading images from, 4-2
receiving keyboard input from,
6-1
responding to deletion, 2-20
responding to movement, 2-17
responding to resizing, 2-18
specifying title, 2-13
writing images into, 4-3
writing text into, 3-23
Virtual display ID, 2-9
Virtual displays, 2-2
color map, 3-15
·cbordinate system, 2-4
creating, .. 2"'.'8
deleting, 2-9
as a result of window
deletion, 2-20
erasing within, 3-34
moving areas within, 3-33
writing text into, 3-23
Virtual keyboards, 6-1
active, 6-3
associating with viewport, 6-4
attributes, 6-5
determining, 6-6
setting, 6-6
characters generated by, 6-7
creating, 6-4
deleting, 6-4
determining if active, 6-5
dissociating from viewports,
6-4

making active, 6-5
receiving input from, 6-6
asynchronously, 6-6

Virtual keyboards
receiving input from (Cont.)
synchronously, 6-6

-wWindow ID, 2-11
Window Options menu
Change the size, 2-18
and display list, 3-2
Delete, 2-20
Window output streams, 7-1
altering characteristics, 7-3
and other graphics functions,
7-5
automatic resizing, 7-3
closing
with DELETE-WINDOW, 2-14
controlling font, 7-2
controlling writing mode, 7-2
creating, 7-1
effect on display list, 7-6
erasing viewing area, 7-2
effect on other viewport
contents, 7-6
via SETF of WINDOW-STREAMVIEWING-AREA, 7-3
font
changing, 7-4
determining, 7-4
horizontal text overflow, 7-2
changing behavior, 7-4
determining behavior, 7-4
multiple streams to single
window, 7-2
scrolling, 7-2
and other viewport contents,
7-5
truncating excess text, 7-2
vertical text overflow, 7-2
changing behavior, 7-4
determining behavior, 7-4
vertical text wrapping, 7-2
viewing area, 7-2
changing, 7-3
determining, 7-3
erasing, 7-2
wrapping text horizontally, 7-2
writing mode
changing, 7-4
determining, 7-4
WINDOW type specifier, 101

Index-a

INDEX
WINDOW-DISPLAY functio.n, 100
using, 2-11
·
·WINDOW-STREAM-ATTRIBUTE-BLOCK
function, 101
using, 7-4
with SETF, 7-4
WINDOW-STREAM-HORIZONTALOVERFLOW function, 102
using, 7-4
with SETF, 7-4
WINDOW-STREAM-VERTICAL-OVERFLOW
function, 102
using, 7-4
with SETF, 7-4
WINDOW-STREAM-VIEWING-AREA
function, 103
using, 7-3
with SETF, 7-3
WINDOW-STREAM-WINDOW function,
104
WINDOW-STREAM-X-POSITION function,
104
WINDOW-STREAM-Y-POSITION function,
105
WINDOWP function, 101
using, 2-11
Windows, 2-2
alternate locations, 2-11
controlling visibility, 2-16
coordinate system, 2-5
creating, 2-10
default characteristics, 2-11
deleting, 2-14

Windows
deleting (Cont.)
by user action, 2-20
with DELETE-DISPLAY, 2-9
determining visibility, 2-16
moving, 2-14
resizing
by user action, 2-18
with RESIZE-WINDOW, 2-14
responding to deletion, 2-20
writing text into, 3-21
WITH-OUTPUT-TO-WINDOW macro, 105
using, 7-1
World coordinate system, 2-4
operations using, 3-3
World coordinates
argument type of, 2-4
contrasted to device
coordinates, 2-6
World-coordinate operations, 3-3
accuracy of, 3-4
contrasted to device-coordinate
operations, 3-3
guidelines for using, 3-4
speed of, 3-4
Writing color, 3-12
controlling, 3-11
Writing modes
and :BACKGROUND-INDEX, 3-8
and window output streams, 7-2
:WRITING-INDEX attribute, 3-11
and color map~, 3-13
:WRITING-MODE attribute, 3-11
and text, 3-25

Index-9

- - - -----·--·-

""--