Digital PDFs

AA-GH76A-TE

May 1986

252 pages

Original

54MB

view download

OCR Version

56MB

view download

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

OCR Text

VAX LISP/VMS

Graphics Programming Guide

Order Number: AA-GH76A-TE

May 1986

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

Operating System and Version:

VAX/VMS Version 4.2

Software Version:

VAX LISP/VMS Version 2.0

digital equipment corporation
maynard, massachusetts

First

The

information

and

should

Corporation.

for

any

The

software

and

this

Equipment

that

appear

may

described

document

used

construed

Digital

errors

may

not

this

subject

this

only

assumed

for

the

May

without

by Digital

assumes

1986

notice

Equipment

responsibility

document.

document

copied

change

commitment

Corporation

Printing

furnished

accordance

under

with

the

license

terms

such

license.
No

responsibility

equipment

that

affiliated

not

supplied

Digital

reliability

Equipment

Equipment Corporation

All

Rights

Printed
postage-paid

this

software

Corporation

its

READER’S

document.

Your

COMMENTS

page

U.S.A.

form

comments

1986.

Reserved.

will

included

assist

wus

the

last

preparing

documentation.
The

companies.
©

use

by Digital

following

are

trademarks

Digital

Equipment

Corporation:

DEC

UNIBUS

PDP

DECUS

VAX

VMS

MicroVAX

VAXstation

DECnet

ULTRIX

ULTRIX-32

ULTRIX-32m

I1I

MicroVMS
I1I

mflgfluum

VAXstation

ULTRIX-11

future

CONTENTS
PREFACE

PART

CHAPTER

GUIDE

SYSTEM

1.1

INTRODUCTION

1.1.1

GRAPHICS

PROGRAMMING

OVERVIEW

1-1

Relationship

MicroVMS

Workstation

Graphics

Software
1.1.2

1.2
1.2.1

VIRTUAL

Considerations

DISPLAYS

Creating

1-2

AND WINDOWS

Virtual

1.2.2

Creating Windows

1.2.3

Windows

1.2.4

Other

1.3

1-3

Display

1-3
1-4

and Viewports

1-5

Operations

GRAPHICS

1-9

OPERATIONS
and

1-9

1.3.1

Drawing

Lines

1.3.2

Writing

Text

1.3.3

Using Attributes

1.3.4

Other

Operations

1-15

POINTER

OPERATIONS

1-15

1.4

CHAPTER

1-2

Programming

Circles

1-10
1-11

INPUT

1-13

1.5

KEYBOARD

1.6

WINDOW OUTPUT

FROM WINDOWS

VIRTUAL

2.1

HOW AND WHEN GRAPHIC

2.2

COORDINATE

1-16

STREAMS

DISPLAYS,

1-16

WINDOWS,

AND

TRANSFORMATIONS

INFORMATION

DISPLAYED

SYSTEMS

2-1

2-2

2.2.1

World

2.2.2

Device

Coordinates

2-5

2.2.3

Screen

Coordinates

2-8

2.3

Coordinates

2-4

CREATING AND MAINTAINING VIRTUAL

2.3.1

Creating

and Accessing

2.3.2

Deleting

2.3.3

Arguments

2.4
2.4.1

2.4.1.1
2.4.1.2

Virtual

DISPLAYS

a Virtual

2-8
2-9

CREATE-DISPLAY

2-9

CREATING AND MANIPULATING WINDOWS
Creating

Display

2-8

AND VIEWPORTS

and Accessing Windows

2-10
2-10

Controlling Window Coordinates

2-11

Controlling Viewport

2-12

Characteristics

2.4.2

Deleting Windows

2-14

2.4.3

Moving

and

2-14

2.4.4

Moving

Viewports

Resizing Windows
and

2-16

2.4.5

Determining

2.4.6

Handling User Actions

Controlling

Viewport

Occlusion

2-16

2-17

2.4.6.1

Responding

to Viewport

2.4.6.2

Responding

to Viewport

Resizing

2-18

2.4.6.3

Responding

to Viewport

Deletion

2-20

2.5

TRANSFORMATIONS

Movement

INTO VIRTUAL

iii

DISPLAYS

2-17

2-21

Using

OPERATIONS

BLOCKS

Attribute

Blocks
[

:WRITING-MODE
LINES

AND

and

Lines

Points

Circles,
-

SHAPES

Ellipses,

Attributes

and Arcs

Used with

Line-Drawing

Functions

:FILL-PATTERN

:ARC-TYPE
:LINE-STYLE
c:LINE-WIDTH

OPERATIONS

Positioning
The

Text

Changing

and

Text

and

the

Position

Measuring

Text

Reference

Points

Text

Affect

: FONT

: CHARACTER-SPACING
: LEFT-MARGIN

that

Attributes

Measuring

Position

:LEFT-MARGIN-PIXEL

Text

SEGMENTS
ERASING

AND

SCREEN

IMAGES

AND

CREATING A BITMAP
STORING

BITMAP

CREATING,
ALTERING

BITMAP

ARRAY
ARRAY

ARRAYS

COMPARING,
BITMAPS

ARRAYS

FROM A
TO

IN
AND

THE

SCREEN

IMAGE

SCREEN

FILES
TESTING

BITMAP

ARRAYS

WRITING A

BITMAPS
b

IMAGES

INFORMATION

SCREEN

GRAPHIC

AND

MOVING

wNo
e

00
O
=

:CLIP-PIXEL

Wi
o

:WRITING-INDEX

0Oy Ul W

DEVICE-COORDINATE

:CLIP

MDD

and

Writing

Wwwww

AND

ATTRIBUTE

: BACKGROUND-INDEX

wwwwwidek

AND

ONOYUT WK

J
@
€&
¢
]
@
e
e

OPERATIONS

LIST

Modifying

Transformations

Attributes

e
e
e
[]

]

wwwww wwwwwwwwwwwwww

UITUTUTUTUITUTUTUT DSWWWwWwWwwwwwiNek

[]
e

&
e

wwwww

ATTRIBUTES

TEXT

OUTPUT

DISPLAY

DRAWING

wwwwww

THE

Accessing

Transformation

WORLD-COORDINATE

COLOR

CHAPTER

and
a

GRAPHICS

JdOA

CHAPTER

Creating
Deleting

KEYBOARD

6.1

VIRTUAL

INTERPRETING

Window Text

WINDOW OUTPUT

Vertical
Display

STREAMS

AND

Position

N
N B

the Viewing Area

OTHER GRAPHICS

Erasing

Scrolling and
List

GRAPHICS

BEGIN-SEGMENT

SYSTEM

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
COPY-BITBLT

Function

CREATE-DISPLAY

FUNCTIONS

Function

CREATE-KB Function
CREATE-TERMINAL Function

Changing Overflow Behavior
Changing the Attribute Block

Changing

PART

STREAMS

OUTPUT

WINDOW

DWW

STREAMS

CREATING AND USING WINDOW OUTPUT
ALTERING

Functions

OUTPUT

wWwwwwihhNhhbdh
N e

WINDOW

Interrupt

KEYSTROKES

Reading Keyboard Input Synchronously
Characters Generated by Keys

Keyboard Attributes

CAPTURING AND

Setting

the

Keyboard

6.2.2
6.2.3

Keyboards: An Overview
Creating and Deleting Virtual Keyboards
Associating Keyboards with Viewports and

Keyboard

KEYBOARDS

Using Virtual

6.2.1

CHAPTER

INPUT

OUT O

6.2

Input

Physical

6.1.4

Position

SENSITIVITY

6.1.2
6.1.3

Pointer

Input

Ul O

Button

Setting

Movement
POINTER

6.1.1

FUNCTIONS

Obtaining and

COMPONENTS
OO0 ~JOhUTLH
W WD

POINTER-RELATED

Uil U
U
v

CHAPTER

POINTER OPERATIONS
P

5
Ul

CHAPTER

CREATE-TRANSFORMATION
CREATE-UIS-STRUCTURE
CREATE-WINDOW

Function

DELETE-DISPLAY
DELETE-KB

Function
Function

Function

15
15

DELETE-TRANSFORMATION

Function

DELETE-WINDOW Function
DISABLE-DISPLAY-LIST

Type

DISPLAYP

DUMP-BITMAP
ELLIPSE

Function

ENABLE-DISPLAY-LIST

Function

ERASE-PIXEL

22
23

ENABLE-VIEWPORT-KB
END-SEGMENT

18
18

Function

ENABLE-KB

17
17

Specifier

ELLIPSE-PIXEL

ERASE

Function

DISPLAY-WINDOWS

Function

DISABLE-VIEWPORT-KB
DISPLAY

Function

DISABLE-KB

Function

ERASE-VIEWING-AREA

Function

GET-ABS-POINTER-POSITION

Function

26
26

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
Function

GET-KB-ATTRIBUTE-LIST

GET-KB-ATTRIBUTE

Function

GET-POINTER-POSITION Function

GET-POINTER-POSITION-PIXEL
Function

32
34

36
37

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

40
41
41

43
44

Function

IMAGE-PIXEL

38
39

Function

KEYBOARD Type Specifier
Function

KEYBOARDP

K-TRM-xxx Constants
LIST-ALL-DISPLAYS Function

LIST-ALL-WINDOWS Function
- LOAD-BITMAP Function

48
48

MAKE-BITBLT Function
MAKE-BITMAP Function

MEASURE-TEXT Function

MOVE-AREA Function
MOVE-AREA-PIXEL Function
MOVE-VIEWPORT Function
MOVE-WINDOW Function
NEW-TEXT-LINE Function

MAKE—WINDOW—OUTPUT—STREAM Function

MEASURE-TEXT-PIXEL 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

58
59

60
60
61

62
63

65
65
66

66
67

69
70
71

SET—BUTTON-ACTION—PIXEL Function
SET-CLOSE-ACTION Function

SET-GAIN-KB-ACTION Function
SET-INTENSITY Function

SET-COLOR 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

76
17

78
79

82
83
83

85
86

87
88

SET-POINTER-PATTERN-PIXEL Function
SET-POINTER-POSITION Function
SET-POINTER-POSITION-PIXEL Function

SET-POSITION-PIXEL Function
SET-RESIZE-ACTION Function
SHOW-FILL-PATTERNS Function

SET-POSITION Function

SHOW-FONTS Function
SOUND-BELL Function
SOUND-CLICK Function

vii

90
91

95
96
97

TEST-KB

TEXT

Function

TEXT-PIXEL

Function

TRANSFORMATION

Type

TRANSFORMATIONP

UIS-ID

98
Specifier

Function

WINDOW-DISPLAY

WINDOW

Type

WINDOWP

100
Function

100

Specifier

101

Function

WINDOW-STREAM-ATTRIBUTE-BLOCK

101
Function

WINDOW~-STREAM-HORIZONTAL-OVERFLOW

WINDOW~-STREAM-VERTICAL-OVERFLOW

WINDOW-STREAM-VIEWING-AREA
WINDOW-STREAM-WINDOW

101

Function

102

Function

102

Function

103

Function

104

WINDOW-STREAM-X~-POSITION

Function

104

WINDOW-STREAM-Y-POSITION

Function

105

WITH-OUTPUT-TO-WINDOW

Macro

105

INDEX

RN
|

WN
P OYUT D

~NOUOOUTUT
T U U WwW W N

EXAMPLES

The

Immovable

Boxed

Viewport

2-18

Using

3-33

Text

Reversing

3-29

Text

Segments

Rubber-Banding
with GET-POINTER-POSITION
Rubber-Banding with

Setting the Cursor Pattern
|
Controlling Rubber-Banding with Pointer Buttons
Using Structures to Eliminate Special Variables
A

Simple

Resizing

the

5-3

SET-POINTER-ACTION

System

5-6
5-9
5-11

5-13
5-16

Viewing Area

Automatically

7-3

Windows,

(WY

a World

Making

The

Device

Square

Image

the

Screen

Coordinate

System

from Pixels

Coordinate

and Nonsquare

Arguments

the

System
Pixels

CREATE-DISPLAY

Specifying Window Coordinates
Viewport Components

Moving

a Window

Transformations

Modifying

an Attribute

Block

CREATE-WINDOW

Clipping

Function

with

NS BN LS I LSRN (O B S

Information

Example

Displaying
of

and Viewports

Circle

ONdFRUTWMNOJOUITO
WY

Displays,

Drawing

Virtual

(Ve
(NI VO I SO I (O I\
W
§
i
N

W WMNOMNMNNNDODNDNNDNODNDNDDNDRE
U
D
D
D
R
R
R
R
R
D
R
NP R OOJOUIH
WK
D

FIGURES

viii

3-3
3-4
3-5
3-6
3-7
3-8
3-9
3-10
3-11
4-1
4-2
5-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
Specifying Overlapping Areas for

SET-POINTER-ACTION

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-1

Creating and Attaching Virtual Keyboards

6-3

3-1
3-2
6-1

Attributes
Writing Modes
LISP Constants Corresponding to LK201 Keys

3-9
3-13
6-7

TABLES

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 wuser
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. 1In such
sections, you are directed to the appropriate manual(s) for additional
information.

Structure of This Document

chapter

An outline of the organization and

content

this

manual

follows:

PART I:

GUIDE TO GRAPHICS PROGRAMMING

Part I presents the VAX LISP graphics system in tutorial
subject

area.

You

may

want

fashion,

system

and

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.

PREFACE

Chapter

"Graphic

operations

changing
@

the
4,

images

from
it

Chapter

6,
by

Part

contains

alphabetical

the

well

various

ways

Bitmaps,"
an

shows

array,

how you

modify

the

can

read

array,

and

explains

tablet)

1Input,"

describes

from

the

how

input

wuse

the

device.

virtual

physical

keyboards,

keyboard

can

window.

window

SYSTEM

VAX

and

describes

text,

output.

Operations,”

(mouse

keystrokes

order.

wuse

and

screen.

shows

VAX

the functions,
graphics system.

LISP

Each
shows

Streams,"

through

how you

LISP

can

perform

stream.

COMPONENTS

definitions

the

into

"Window Output

output

GRAPHICS

specific
macro’s

and

"Keyboard

captured

1lines

Images

"Pointer

device

Operations,"

screen

to the

which

text

II:

the

through

Chapter

PART

"Screen

back

pointing

Output

display

appearance

Chapter
write

that

description
1its

format,

macros,

and data
descriptions

The

explains

applicable

the

types
are in

function’s

arguments,

and

return

value.

Associated
The

Documents

following

The

documents

VAX

about

are

LISP/VMS User’s
using

VAX

generally-helpful
@

COMMON

LISP:

COMMON

LISP

The
how
to

relevant

The

Guide

LISP,

VMS

using VAX

LISP

provides

general

and

the

VAX
VMS

Functions"

information
a

guide

the

documentation.

Language

provides

definition

language.

VAX LISP/VMS System Access
a

serves

graphics:

LISP programmer
operating
1is

system.

especially

Programming

can use
The

the

chapter

important

Guide

describes

programming
for

entitled
wusers

interface
"Interrupt

VAX

LISP

graphics.

The

VAX LISP/VMS Editor Programming

extend

the

information

<capabilities

the

VAX

on workstation-specific

X111

Guide
LISP

Editor

explains
Editor

and

how

includes

functionality.

PREFACE

Conventions Used in This Document

The following conventions are used in this manual:
Convention

Meaning

()

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

UPPERCASE

italics

LISP)

defined LISP
and
qualifiers,
and
commands
DCL
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

lowercase

the

characters.

Lowercase italics in function and macro descriptions
supply;
and in text indicate arguments that you

however, you can enter them in lowercase, uppercase,

a combination of lowercase and uppercase characters.

In LISP examples, a horizontal ellipsis indicates
not pertinent to the example and not shown.

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.

{

}

braces
In function and macro format specifications,
of
unit
one
be
to
d
considere
are
that
elements
enclose
code.

For example:

{keyword value}

{

braces
In function and macro format specifications,
followed by an asterisk enclose elements that are
considered to be one unit of code, which <can be
For example:
repeated zero or more times.
{keyword value}*

&OPTIONAL

In function and macro format specifications,

SOPTIONAL

indicates

that

defined to be optional.

the

word

it are
arguments after

For example:

UIS:SET-BUTTON-ACTION display window action
&OPTIONAL x1 yl x2 y2

Do not specify &OPTIONAL when you invoke a function

macro whose definition includes &OPTIONAL.

xiii

PREFACE

Convention
&KEY

Meaning

function

&KEY
For

and

macro

1indicates

that

format

specifications,

keyword

arguments

are

the

word

accepted.

example:

UIS:MOVE-VEIWPORT
&KEY

window

:GENERAL-PLACEMENT

:CENTER

:ABSOLUTE-POSITION-X
:ABSOLUTE-POSITION-Y

not

macro
<RET>

specify

whose

&KEY when

definition

symbol

with

indicates

that

you

invoke

includes

to
press

the

function

&KEY.

3-character
a

key

returns

are

abbreviation

the

terminal.

For

example:
<RET>

examples,

each

<ESC>

carriage

line.

examples
CTRL/x

CTRL/x

However,
emphasize

indicates

hold

down

key.

For

the

<RET>

carriage

implied

symbol

control

key

labeled

CTRL while

CTRL/Y

Xiv

the

used

end

some

returns.

key

example:

CTRL/C

the

sequence

where

you

press

must

another

PART |

GUIDE TO GRAPHICS PROGRAMMING

CHAPTER 1

SYSTEM OVERVIEW

This chapter provides an overview of the VAX LISP/VMS graphics system.
After a brief introduction to the system, the major sections of the
chapter demonstrate how the parts of the system operate and relate to
This demonstration is given by means of a continuing
each other.

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.
this system to do the following from LISP code:

You

can

use

Create a virtual display that can collect graphic information

Create one or more windows into the virtual display

Draw lines and text in the virtual display

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

Get input from windows by means of virtual keyboards

Use standard LISP output functions to send output

to make the graphic information appear on the screen

order

and to pointer buttons

windows

through window output streams

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.

SYSTEM

1.1.1
The

Relationship to
VAX

LISP/VMS

MicroVMS

graphics

workstation

graphics

functions

the

routines

graphics

VAX

has

LISP/VMS

workstation
graphics

with

This

Part

added

capabilities.

use

VAX

LISP

Version
MicroVvMS.

2.0

Most

the

system

are

directly

equivalent

2.0

the

MicroVMS

workstation

1is

noted

the

function

the

basic

MicroVMs

are

intended

manual.
of

features

These

code

and

provides

to
the

types:

DISPLAY,

streams,

allowing

features
provide

some

make

higher-level

following:
WINDOW,

TRANSFORMATION,

and

KEYBOARD

Window

output

normal

LISP

facility

and

The

for

BITBLT

text

output

using

the

windows

functions

operating

bitmaps,

BITBLT

objects

using

function

MicroVMS

MicroVMS
be

I/0

the

graphics

number

LISP

on
with

Version

this

LISP/VMS

object

based

provided

software.
in

Graphics Software

equivalence

of
a

graphics

easy

system

LISP/VMS

software.

Workstation

software

provided

descriptions

VAX

OVERVIEW

useful

However,

workstation
graphics
software
is
described
in
the
Workstation Graphics Programming Guide.
It may occasionally
to refer to this
manual
for
more
detail
on
a
subject.
the

VAX

LISP/VMS

description

and

examples

demonstrate

1.1.2

Programming

With

the

gain

access
®

this
to

Preface

the

Programming

LISP

Guide

graphics

gives

system,

complete

wusing

LISP

software.

the

manual

these
the

are

objects
name

BITBLT-related
located
in

one

each

in
of

objects,

package

all

called UIS.

(UIS:PLOT

Use

the

you

without

objects
You

can

two ways:

object

with

the

package

UIS:

Considerations

exception

described

Graphics

definition

specifier

...)

USE-PACKAGE
the

function

make

the

objects

available

preface:

(USE-PACKAGE

"UIS")

(PLOT...)

Although

the

fir st method
symbols.

second method
in

This

order

convenient,

avoid

real

and

particularly

true

1-2

DIGITAL

potential

you

are

recommends

conflicts

writing

the

with

other

program

that

SYSTEM OVERVIEW

uses

both

symbol

the

names

graphics

appear

system

and the VAX LISP Editor,

since

in both packages.

some

In this chapter, all
examples
use
the
explicit
preface
UIS
with
graphics
system
objects.
In the remaining chapters, the preface 1is
not used in the interest of readability. The object
descriptions
1in
Part
II
use the explicit preface to show which package the object is
in.

1.2

VIRTUAL DISPLAYS AND WINDOWS

The fundamental unit in which graphic
displayed
1is
the
wvirtual
display.
following

characteristics:

It has
system,

a
coordinate
system,
called
the
world
coordinate
which is appropriate for the graphic information to be

written

it.

It has a width and height
windows

information
1is
collected
and
Each
wvirtual
display has the

the

that

determine

It can collect graphic information by
list.

size

1its

means

1its

display

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

1.2.1

the

screen.

the

screen.

Creating a Virtual Display

You create
function.
coordinate

a virtual display object by
means
of
the
CREATE-DISPLAY
This
function
creates
and
returns a display having the
system, width, and height that you request.

If you would like to follow along with the examples in
this
create a virtual display now by means of the following forms:
(SETF

chapter,

*DEMO-DISPLAY*
(UIS:CREATE-DISPLAY

-10.0 -10.0
10.0 10.0
15.0 15.0))
(UIS:ENABLE-DISPLAY-LIST

;
;
;

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

*DEMO-DISPLAY*)

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

SYSTEM OVERVIEW
However,

nothing

1tself

display
You

have

points

not

make

that

given

coordinates

1.2.2
Now,

appeared

display

your

virtual

width

screen

yet.

display

coordinate

and

must

height

virtual

create

square.

10.0,10.0.

This

system.

You

coordinate

and

your

you

<corners

-10.0,-10.0
world

anything;

display

windows

into

the

happen.

opposite

display’s
default

has

does

centimeters

system

The

square
have

for

defined

points

two

the

establishes

the

also

the

have

established

display.

Creating Windows
create

window

into

the

virtual

display:

(SETF *DEMO-WINDOW-1%*
(UIS:CREATE-WINDOW

A window

appears

emulator

window,

except

icon.

The

window
fills

area

maps
the

your

inside

into

coordinate

Sscreen.

that

the

*DEMO-DISPLAY*))

border

entire

system

resembles

square

1is

virtual

that

you

one

that

and

has

a
no

VT100
title

centimeters

display;

that

specified

when

maps

only

terminal

keyboard

square.

is,

vyou

This

completely

created

the

display.
Now

create

second

window,

into

portion

the

display:
(SETF

*DEMO-WINDOW-2*
(UIS:CREATE-WINDOW

first window’s
0.0,0.0

window
virtual

lines

appears;

and

note

that

its

sides.

The

four

10.0,10.0,

maps.

These

display.

circle

the

that

points

make

The

two windows

now

look

only

optional

arguments
rectangle

specify

the

upper-right

-8.0
0

0.0

this:

apparent,

follows:

-8.0

- 8.0
e

0.0

8.
-8.

)

half

the

relationship

display,

are

into

define

this

( UIS:PLOT *DEMO-DISPLAY* 0
( UIS:PLOT *DEMO-DISPLAY* 0
( UIS:CIRCLE *DEMO-DISPLAY*

sides

window

Sages®

the

rectangle

this

map

the

Corners

10.0))

points,

Display

;

10.0

second

;

0.0

O OO

*DEMO-DISPLAY*

0.0

display

the

1length

specify
into

two

which

quadrant

draw

two

"
Nz

SYSTEM OVERVIEW

You can see
quadrant of

that the smaller window reproduces the wupper-right
the larger window. You could create other windows 1into

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.
(SETF

Create a third window:

*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

now

that

the

given

entire

You

have

created

but

does

the

picture

This

looks

not

exercise

window

and

use

display.

The
that

This

and

Figure
windows,

the

1-1
and

viewport
is

case

the
with

the

CREATE-WINDOW

are

window

requires

that

you

keyword-argument

pairs

you wish

entire

virtual

display

LISP

into

the

lengthwise,

display.

mapped

supply

distinction,

The

1is

window

corresponding

the

virtual

window’s
the

contents

same

viewport.
aspect

the

that

the

all

use. )

ratio

viewport

the

will

result,

in height.

the

area

However,
(that

between

rectangle

display

compressed

important

the
in

that
have

maps

dimensions

stretched

drawn

viewport

to width),

that

default

viewport.

the window appears

height

any

arguments

that

this:

window

the

brings

Anything

window

before

requests

COMMON

distorted:

the

coordinate

This

display.

arguments

window

optional

NIL.

virtual

optional

This

four

is,

screen.

covered

unless
the

the

virtual

ratio

the
of

distorted.

*DEMO-WINDOW-3*,

illustrates

the

relationship

viewports.

1-6

among

wvirtual

displays,

SYSTEM OVERVIEW

LINE DRAWN IN
VIRTUAL DISPLAY

10.0,10.0

~\\\\

{

|
|
'l

f
N

|
|
|
|
|

B
|
i
1
1

/\’

\\\_

Y S

"/"—‘ . "‘\\

i
|

i
|
i
|
|
|
|
|
|
|
|
|
|
|
|

WINDOWS

ilV4

T~es

\\‘\
“~

" VIEWPORTS

)

‘

DISPLAY SCREEN

ML0O-190-86

VIRTUAL DISPLAY'S

WORLD-COORDINATE SPACE

Figure 1-1:

Virtual Displays, Windows, and Viewports

When you create a window, you also create 1its associated viewport.
Some functions
You always refer to a viewport by means of its window.
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 wvirtual
This has
display and an associated viewport that is relatively large.
example:
For
window.
the
in
the effect of magnifying the image
(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))

The new window looks like this:

: Small window in display
;:

Large viewport on screen

SYSTEM OVERVIEW

This

image

windows.
of

the

"magnified"

wvirtual

coordinate

the

virtual

default

can

Separating

system

could

world

create

this

the

not
the

that

virtual

for

the

1978.0

the

other

coordinate

system

particular
you

physical

specified

physical

size,

when

you

and

this

from

the

a window.

the

wvirtual

data

set

you

something

=size

-100.0

physical

default

any
size

you

images

display

a world

are

coordinate

presenting.

between

1980

and

For

1988,

you

display:

allow you

some

imply

create

the

the world

default

implies

production of

that

window allows

left and bottom edges

specify

does
only

convenient

graph

display would

transform

relation

coordinates

the

(UIS:CREATE-DISPLAY

This

realize

overridden when you

the

display

size

that

example,

display

system.

created

physical

only

important

plot

1988.0

raw data

coordinate

for
of

30.0

without

system.

1labels.)
a

1000.0

The

window mapped

15.0)

first

(The

having

extra

last

two

into

this

space

arguments
display

centimeters.
This
to

concludes

stop

here,

the

demonstration

delete

the

virtual

portion

display

and

Section
its

1.2.

you

wish

associated windows

follows:
(UIS:DELETE-DISPLAY

Otherwise,
with

the

windows

leave

the

display and

demonstrations

with

the

*DEMO-DISPLAY*)

*DEMO-WINDOW-1*

Section

1.3.

DELETE-WINDOW function:

(UIS:DELETE-WINDOW

*DEMO-WINDOW-2*)

1-8

You

can

place

get
|

rid

and
of

continue
the

other

SYSTEM OVERVIEW

1.2.4

Other Operations

manipulate

In addition to what you have seen in this section, you can

displays,

@
@

windows,

and viewports in the following ways:

Keyword arguments to CREATE-WINDOW allow you

~appearance

control

change

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

You

can

the

and location of a viewport.

move

MOVE-VIEWPORT

viewport

function.

the

around

The

screen

with

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

program attempts to delete,

resize,

wuser

or move a window.

yoUr

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

display.

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
you wuse various line-drawing and text-writing functions to
windows,
These functions are directed into the
on the screen.
images
create
display "remembers" what has been
wvirtual
the
and
virtual display,
screen
appears on the
image
An
list.
done by means of its display
of
more
or
one
under
falls
display
when 1its ©position in the virtual
the windows that are mapped into the display.

This
You can create and manipulate screen images in several ways.
line-drawing functions and text-writing
section introduces two:
The section also introduces the wuse of attributes and
functions.
attribute blocks to modify the appearance of screen images.

The demonstrations in this section assume the existence of the virtual
created in Section 1.2, and its associated
display *DEMO-DISPLAY*,
If you wish to try the examples 1in this
window *DEMO-WINDOW-1*.
section, create these objects if they do not already exist.

1-9

SYSTEM OVERVIEW

1.3.1
The

Drawing
PLOT

lines.

Lines

function

You

have

(UIS:PLOT

The

first

directs
of

its

The

output

PLOT

just

than

the

two

points.
point.

points

points.

Try

4.0

-4.0

4.0

-4.0

4.0)

-4.0

-4.0)

function

call

Note

that

coordinates

plots

Coordinates

are

always

floating-point

You

have

seen

(UIS:CIRCLE

the

specifies
coordinate
You

all

block.

center

the

following:

The

the

radius

draw

the

1is

pairs
the

case,

point

had

PLOT

draws

the

define

point

draws

been

rest

discussed

that

first

PLOT

a
supplied,

connected

line
PLOT

lines

complete
are

specified

virtual

draw a

pairs

world

arc

beginning

floating-point

coordinate

0.0

drawing

two

the

0.0

and

two

text

arguments

circle

5.0)

functions

arquments

0.0,0.0

with

and

CIRCLE

end

system

circle:
0

first

circle,
of

display’s

numbers.

other

the

square.

are

specify

this

the

using

two

the

arc.

Try

1-10

operate

display and
coordinates
of

the

case.

units

that

the
The

the

systenmn.

can also

specify

supplied,

the

how

displays),

attribute

only one

*DEMO-DISPLAY*

(and

example,

this

are

numbers.

PLOT

block.

coordinate

the

1In

that

argument

causes

-4.0

This

also

*DEMO-DISPLAY*

-4.0

are
1In

8.0,8.0.

that

two

the

PLOT

This

display.

attribute

8.0)

the

connected

line:

and

display.

single

display.

PLOT

arguments

series

display

section.

(UIS:PLOT

with

virtual

particular

those

virtual

8.0

argument

second

the

-8.0

context

the

-8.0

draw

the

-8.0,-8.0;

can

virtual

between

line,

used

the

draw

how PLOT

this

between

point,

seen

would

remaining

points

draws

*DEMO-DISPLAY*

arguments

second

later

Circles

already

argument

the

and

final

optional

the

argument

display’s world

arguments

following:

SYSTEM OVERVIEW

(UIS:CIRCLE

*DEMO-DISPLAY*
0.0

0.0

(/ PI

7.0

PI)

This draws an arc consisting of a quarter-circle,

as shown here:

Henu,,; ‘* -

Figure 1-2
to

the

illustrates the

circle

that

relationship of CIRCLE’s various

arguments

is drawn.

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

1.3.2

and vertical axes.

Writing Text

The TEXT function writes a specified string of text into
display.

Try the

following:

(UIS:TEXT *DEMO-DISPLAY* (0

"This is text" 0.0 0.0)

1-11

the

wvirtual

SYSTEM OVERVIEW

*DEMO-DISPLAY*

(UIS:CIRCLE

; CENTER

7:\\\\\ 0.0 0.0
7.0
(/ PI

-—

PI)

;

RADIUS

;

START

AND

END

RADIANS

37T2

Figure 1-2:

Drawing a Circle

The

string
of

The

first

block.
be

any

The

LISP

last

are

text

two

The

display

arguments

two

are

the

There

the

again

the

middle
the

the

virtual

text

virtual
display

string

display.
and

attribute

displayed;

can

string.

arguments

1last

argument

character

at which
the

appears

third

optional.

where

MLO-191-86

are

coordinates

text
is

text

should
default

operation

for

start.
starting

left

the

point

However,

off.

position
To

the

these

two

for

text,

illustrate

wvirtual

arguments
which

try

the

this,

following:

(UIS:TEXT
The

new

text

*DEMO-DISPLAY*

string

appears

"More text")

right

the

end

®1TMore

The

NEW-TEXT-LINE

margin

text.

for

text

Thus,

typewriter.

function

these

(UIS:NEW-TEXT-LINE

the

and moves

NEW-TEXT-LINE

Try

(UIS:TEXT

returns

operations,

analogous

position

down

the

Y-

*DEMO-DISPLAY*

LTM
LY

"New line

1-12

one:

text")

the

height

carriage

functions:
*DEMO-DISPLAY*

text

text
it

the

left
a

return

line

SYSTEM OVERVIEW

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

1.3.3

Using Attributes

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

among others:

solid, dotted, dashed, and so on

The appearance of lines:

The way in which arcs are treated:

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

what

they

The font in which text is written, and

1left

margin

for

chord,

are

text

or made into a pie

not closed, closed with

segment

filled with

the

operations

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

while some attributes are common to both drawing and text.

Attribute block 0 contains a collection of default attribute values
To use a different value
that are appropriate for many operations.
block so that it
attribute
an
modify
first
must
you
for an attribute,
then supply the
You
attribute.
that
for
has the appropriate value
or text
drawing
the
to
modified attribute block as an argument
function.

SET-ATTRIBUTE

To modify an attribute block, use the

function.

This

modifying

this

its values to an
function takes an attribute block and copies
in the process.
attribute
one
of
value
the
changing
block,
attribute
that it causes
so
1
block
attribute
modifies
example
The following

lines to be

drawn

dashed

instead

solid.

attribute block, and then draw a line using it:

Try

(UIS:SET-ATTRIBUTE *DEMO-DISPLAY* 0 1 :LINE-STYLE :DASHED)
(UIS:PLOT *DEMO-DISPLAY* 1 -5.0 0.0 5.0 0.0)

SYSTEM OVERVIEW

The

PLOT

function

call

draws

dashed

{

SET-ATTRIBUTE

attribute

block

attribute

blocks

which

now

Note

that

virtual

0
0

associated
next.

You

can use

that

has

modifies

it.

attribute

addition

indicates

the
of

block

:LINE-STYLE

blocks

are

display

Dblock

may

change

has

i1s

256

the

different

one

value

simply

output.

from

between

attribute,

display

associated with
attribute

same

for

from one

virtual

all

following

:ARC-TYPE

virtual

display

attribute

specifying

The

blocks

block

the

example

same

further

1:
*DEMO-DISPLAY*

specifying

any

values

only difference

requires

and

modify

The
the

function

input

arcs

1.
of

copies

attribute

modified,

that

example

:SOLID.

been
block

the

value

virtual

SET-ATTRIBUTE

for

Attribute

(UIS:SET-ATTRIBUTE

Now,

because

attribute

block

attribute

Each

already

attribute

call

instead

with
but

the

to
and

displays.

ffi}hifi iz textMore text

SET-ATTRIBUTE

This

displays,

function

:DASHED

the

argument.

line:

-R\ ffj
of texdt

The

horizontal

should

a dashed

closed

line

style,

by drawing

:CHORD)

attribute
line

block

between

their

endpoints.
You

can

Attribute

One
A

block

attribute

can

only be

block

type

consists

style

logical

and

name

attribute

block

read.

frequently-changed attribute

font

except

collection

size.

Fonts

are

SYSSFONT;

each

file

is
of

the

font

printing

contained

this

in which

text

characters
in a

1in

directory

the

each

extra

point

has

and

SHOW-FONTS

space

number

appearance

system,

the

and

the

are

the

indicated

first

size

files

SYSSFONT.

contents

the

<collection

graphics

The

between

NEW-TEXT-LINE
add

proportion

The

the

functions

expressed

second

points

The

style.

These

attribute

1is

left

You
can
add
extra
create an airy effect or

used

attribute

lines.

indicating

:FONT

font

centimeters.
bold,

should

:CHARACTER-SPACING

It
The

expressed

space

size.

numbers.

character.

lines,

output.

: CHARACTER-SPACING

extra

1is

the

characters.

between

3.6.3.2

larger

attributes
that
affect
for
a
descripticn
of

3.3.2

graphic

:CHARACTER-SPACING

the

two

various

The

any)

functions.

leave

and

between
you
want

between

indicated

the

Section

and

if
to

use

text

(if

string

NEW-TEXT-LINE-PIXEL

space

both

much

characters
of

height

to
See

:CHARACTER-SPACING

determines

string

how

only.

the

fonts

default

value.
You

can

specify

You

use

that

can

value

the

pathname

contains

pointing

for

the

file

font

:FONT

the

name

1is

one

font

file,

one

specification

two

ways:

character

string

1logical

name

where

each

file.

You can also use a list of
keyword

attribute

the

keyword-value

field-specification

3-30

pairs,

keywords

displayed

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
cSPACING
*TYPE-SIZE
cWEIGHT

"TABERO"
wT"
"O3W"
"G"

specified

One font file, specified by the system logical name UISSFILL_PATTERNS,
not
contains the patterns used to fill in figures. This font file 1isusing
on
ation
inform
for
useful for text output. (See Section 3.5.3.2
fill

patterns.)

You can use the GET-FONT-SIZE function to find out the physical , size
1in
GET-FONT-SIZE returns the width and height
font.
a
of
centimeters, of a specified text string in a specified font.the Text
size
characters are never scaled on the screen; therefore,
a
if
even
valid,
be
always
will
information returned by GET-FONT-SIZE
viewport is scaled.

to
You specify the font to GET-FONT-SIZE the same way you specify 1tthose
only
I1f you supply a keyword-value list, supply
SET-ATTRIBUTE.
field specifiers whose values differ from the default font.

to
3.6.3.3 s:LEFT-MARGIN - The :LEFT-MARGIN attribute sets up a marginon.
positi
text
y’s
displa
which the NEW-TEXT-LINE function sets the
number,
You specify the :LEFT-MARGIN attribute as a floating-point XT-LIN
E
NEW-TE
which indicates an X value in world coordinate space.
line
new
the
function calls that use this attribute block will cause
to start at that horizontal position.

The default value for :LEFT-MARGIN is the left

edge

window you specified when you created the virtual display.
3-31

the

default

GRAPHICS OUTPUT OPERATIONS

3.6.3.4
a

:LEFT-MARGIN-PIXEL

margin

text

which

viewport

calls

that

The

the

You

specify

position.

integer,

which

indicates

The

:LEFT-MARGIN-PIXEL

the

offset

device-coordinate

units.

block

this

value

attribute

position

for

the

value

:LEFT-MARGIN.

the

other.

Changing

The

:LEFT-MARGIN-PIXEL,

and

segment

Within
are

edge

cause

the

new

the

function

line

start

completely

one

the

left

edge

independent

has

function

effect

uses

the

value

the

value

the

value

the NEW-TEXT-LINE function uses the value of

grouping

function

segment,

temporary.

segment,

you

atttribute

blocks
can

called

blocks.

Segments

been

the

that

beglnnlng

the

you make
you

before
that

This

can

program and

delimited

and

you

attribute
available

The

that

point.

all

the

began

the

portion

that must

set

string,

and
that

the

that
a

attribute

use

takes

coordinate
it

attempts

block

that

calls

any

1is,

segment

inherits
that

the

all
outer

segments,

a virtual
pair.
to

the

modify

work

the

code

output

for.

Thus,

just

the

text

defined.

3-32

segment

3-2

have

special

contain

may

you

blocks
can

another

attribute blocks

consider

display,

Example

the

can

have

attribute

that

these

you

attribute

one

blocks

Within

segment.

the

state

previously-modified

useful

segment

including

example

except

nested;

inner

all

blocks.
may

call

have

function

segment,

cancelled,

was
be

that

segment,

SET-ATTRIBUTE

end

to ensure

the

modified

anywhere

REVERSE-TEXT

might be

wuse

to what

segment,

have

the

ruined.

segment.
outer

end.

begin

blocks

segments

attribute

operations

function

the

you

that

can

returns

not

graphic

anymodifications

attribute

use

When

blocks

done

BEGIN-SEGMENT

attribute

the

left

the

END-SEGMENT

For

attribute

the

window

SEGMENTS

call

are

value

NEW-TEXT-LINE-PIXEL

:LEFT-MARGIN.

3.7

the

sets

the

viewport.

:LEFT-MARGIN-PIXEL

from

sets

NEW-TEXT-LINE-PIXEL

will

viewport.

The

attribute

function

:LEFT-MARGIN-PIXEL

horizontal

wuse

horizontal

default

NEW-TEXT-LINE-PIXEL

of the

modified.

function

called

an attribute block, a text
1like
the
TEXT
function
in

the

shows

reverse

whatever

how such

function

GRAPHICS OUTPUT OPERATIONS

Example 3-2:

(DEFUN

Reversing Text Using Segments

REVERSE-TEXT

(BEGIN-SEGMENT

(LET

STR

((MODE

;

Get AB's writing mode

;
;
;

Modify block 1
Copy block AB except
for new writing mode

;

Output

(GET-ATTRIBUTE

:WRITING-MODE)))

(SET-ATTRIBUTE
D AB 1 :WRITING-MODE
(CASE MODE
( :OVERLAY

:OVERLAY-NEGATE)

( :OVERLAY-NEGATE

( :REPLACE

( :REPLACE-NEGATE
( tERASE

:REPLACE)

:ERASE-NEGATE)

(:ERASE-NEGATE
(OTHERWISE

(TEXT D 1

:OVERLAY)

:REPLACE-NEGATE)

:ERASE)

MODE))))

STR X Y)

(END-SEGMENT

reversed text

D))

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
1is
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 modification
of
attribute
block

3.8

the

end

the

function.

MOVING AND ERASING GRAPHIC INFORMATION

The VAX LISP graphics system provides a function that moves a
portion
of
a
wvirtual display to a different part of the virtual display, and
another function that erases a portion
of
a
wvirtual
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

TEXT.

GRAPHICS

the

display

movement

the

there

list

that

moved
are

has

occurred.

graphic

any windows

the

immediately

reflect

effect

MOVE-AREA

viewport

through

the

will

the

another,

all

1ts

the

portion

although

create

see

that

the

line

The

ERASE

function

any windows

the

1list.

list,

new window on

the

new

location.

time

vyou

wuse

not

viewport,

the

from one
1f

part

the

none

line

the

1line

line within
virtual

the

windows
a

Thus,

the

reflect

representation

the

those

contents.

display

rectangle

the
cuts

rectangle
has

display,

been

you will

intact.

erases

display

into

the

deletions

move

indicate

display

with

you

from the

virtual

objects

display-list

corresponding

moved.

the

modified

updated

rectangle,

moved,

1is,

into

viewports

MOVE-AREA updates

That

objects

MOVE-AREA,
of

enabled,

OUTPUT OPERATIONS

within

list.
wvirtual

virtual

display

by deleting

As with MOVE-AREA,
display does

display

1list.

not
a

the

effect

immediately

viewport,

the

graphic

ERASE

reflect
rectangle

specified with ERASE is simply blanked out.
If the
display
1list
re-executed
at
a
later
time, objects that were not deleted will

1is
be

redisplayed.

The

MOVE-AREA-PIXEL

display

viewport,

specified
contents
that
In

are

the

there

moves

does

concept

not
of

area

from one

affect

"graphic

the

part

objects";

rectangle
is
simply
picked
wup
and
moved
another location.
Fragments of drawings and
contained within the rectangle are relocated.

way,
a

the

ERASE-PIXEL

function

viewport.

3-34

blanks

display

same

rectangle

function

another.

out

wvirtual

list.

1instead,

with
text

the

1In

the

all its
strings

specified

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:

4.1

bitmap

explains

arrays,

Section

Section 4.2 shows how you can read images

representations of screen images 1n memory.

bitmap

and

explains

the

windows

1into

screen,

the

how various attributes can alter the appearance
|

image.

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

store

arrays.

Section 4.3 shows how to write bitmap arrays

from

which

arrays.

test

Section 4.5 presents functions that create, compare, and
bitmaps.

4.1

Section 4.6 describes the BITBLT facility, by means

which

you can alter bitmaps in various ways.

SCREEN IMAGES AND B

An image on the workstation screen is made up of individual pizxels.
In a monochrome system, each pixel is either illuminated or dark. 1In

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
1In the VAX LISP graphics system, a bitmap is represented by a
screen.
specialized two-dimensional array of unsigned bytes. An array used in
this way is called a bitmap array.

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

SCREEN IMAGES AND BITMAPS
each

pixel

such

single

bit,

whereas

several

bits.

by n bits
colors,

VAX

II,

color
a

each

system,

where

screen.

pixel

each

pixel

workstation
is

whose

2**n

equal

graphics

screen,

and

color.

writes

bit with

bit

with

Figure

4-1

the

bitmap

value

illustrates

#2A(

monochrome

are

the

screen.

represents

For

display

a
a

represented

can

represents

this

represented

screen

array

pixels

colors
1,

represented

and white.

color,

background

workstation

simultaneously display

LISP

workstation

the

general,

system,

black

writing

VAXstation

1In

can

monochrome

When

the

two

monochrome
pixel

pixel

the

relationship.

represent
system

MLO-213-86

Figure 4-1:

4.2

Bitmaps and Screen Images

CREATING A BITMAP ARRAY FROM A SCREEN IMAGE

The

READ-IMAGE-PIXEL

a viewport.

array

image
pixels
It

that

the

that

you

contain

make

and
images

the

graphic

supply

contents.

it.

the

contents

from two

sources:

the

viewport
is

that

display
in

from
a

specified

bitmap array

READ-IMAGE-PIXEL

modifies

does not

READ-IMAGE-PIXEL uses
of

virtual

portion
modifies

affect

array based

the

contents

display.

the

A viewport

the

a
can

world-coordinate

on which

based,

viewport

graphic
operations
and device-coordinate

itself.
READ-IMAGE-PIXEL does
not
from these two sources; anything that is
included in the bitmap array.

images
is

partially
off the

viewport,

image

returns

image.

note

between

the

viewport

another

the

simply makes

operations

reads
either

not

wvirtual

discriminate
visible

function
function

screen;

important

viewport

The

workstation

READ-IMAGE-PIXEL

still

screen

has

access

occluded

all

its

SCREEN IMAGES AND BITMAPS

The

format

the

READ-IMAGE-PIXEL

function

is:

UIS:READ-IMAGE-PIXEL window bitmap &OPTIONAL x1 yl x2 y2
For bitmap, you can supply either a
bitmap
array
or
NIL.
If
vyou
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,
returns
that
array.
When you supply a

the
function
modifies
and
bitmap, you should not supply

the optional arguments x2 and yZ2; the function ignores
them
1if
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 0
(READ-IMAGE-PIXEL WINDOW-1 MAP 30 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 1is
specified
by
the
four
coordinate
arguments
in
the
call
to
READ-IMAGE-PIXEL.
The
array
represents
an
area at the lower left
corner

of WINDOW-1.

The second READ-IMAGE-PIXEL call receives the same bitmap array as its
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
workstation screen.
They differ in several

a
bitmap
respects:

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

1location

array

the

the
1image
1in
display;
the
1in

terms

BITMAPS

The

IMAGE

function

corresponding
location
causes

The

the

IMAGE

function

If you

area,

size

IMAGE

the

size

size
of

The

only

the

IMAGE

one

any

viewport -

over

the

IMAGE-PIXEL

image
'

function

viewport.

display list;

that

functions

the

IMAGE-PIXEL

larger
wup

the

function

will

<c¢lip

array

virtual

than

the

bitmap

image

does

not

the

fit

image

the

scale

the

image.

bitmap
the

relation

image

scales

IMAGE-PIXEL

than

the

into

display.

size

rectangle,

image

the

of
or

specified

Depending

the

may

viewport

world-coordinate

IMAGE

clips

size
by

the

off

the

scales

rectangle

least

the

image

rectangle

horizontal,

vertical,

scaled

1image

image.

bitmap

scale

rectangle

right

the

nearly
and

the

array,

the

larger

and/or

larger

integer
on

image

than

appears

bottom

per-pixel

rectangle

Any

room

appears

IMAGE

arrays.

\LED
CLIPPED
MLO-214-86

Bitmap Arrays with IMAGE

the

edge(s)

size

either

basis

fill

scaling

left

over

above

and

<clip

of
out

the

may

Dbe

between

the

and

the

dimension,

The

ORIGINAL

Writing

than

multiple

possible.

both.

Figure 4-2 shows the results of‘using

Figure 4-2:

mapped

image.

image

bitmap

appear

rectangle:

viewport,

the

Both
smaller

places

the

1is

the

area

the

rectangle

clip

out

1is

rectangle

may

fill

function

whereas

function

the

target

1image.

world-coordinate

display.

appear

1IMAGE

area

image
that

not.

specify a

target

IMAGE

the

window

function modifies
does

the

virtual

image

the

target
The

the

array,
up

causes

the

right

scale

SCREEN IMAGES AND

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-PIXEL determines the size of the displayed image from
image.
the dimensions of the bitmap array that you supply. 1If 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

The functions wuse the :WRITING-INDEX and
their second argument.
- BACKGROUND-INDEX attributes to determine how to represent each array
element on the screen. A 0 is represented in the background color and
a 1 is represented in the writing color.

If you are using windows with a 1light background and dark writing
color, you will notice that 1images 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 0 for a dark pixel and a 1 for an illuminated pixel,
without regard for writing or background colors. The IMAGE functions
interpret the 0 as background (light) and the 1 as writing color
(dark). Thus, what was background becomes writing color, and vice
This phenomenon does not occur in windows that have a dark
versa.
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 0 always darkens 1it.

4.4

STORING BITMAP ARRAYS IN FILES

Two functions allow you to store a bitmap
retrieve

from a

array

1in

file

and

file:

DUMP-BITMAP creates a file containing a bitmap array.

LOAD-BITMAP returns a bitmap array from a

file

created

with

DUMP-BITMAP.

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.

SCREEN

4.5

CREATING,

One

way

Another

create

way

returns

COMPARING,

bitmap

arguments

allow

each

pixel,

function
The

and

bitmap

you

the

dimensions
values

space

and

function

also

BITMAP-P

array

and

the

This

section

bitmap

describes

You

may

back

array

from

some

write

dimensions

you

the

want

number

the

compares

T
it

function.

This

function

specify.

bits

array

used

1is

the
to

the

two

the

arrays

returns

Optional

represent

allocated.

This

means

which

same

nonimage

source,

additional

difference.

return
See

the

information.

both

wvalid

This

bitmap

package

image

location;

given

identical

argument
is
LISP.

too

read

arrays

are

the

for

its

bitmap

NIL,

about

in Part
LISP.

returns

otherwise.

ALTERING BITMAPS

and

the

which

package

4.6

array.

READ-IMAGE-PIXEL

function.

information

function

NIL

the

MAKE-BITMAP

returns

function

using

ARRAYS

LISP.

BITMAP

the

contents.

description

TESTING

specify

function

provide

package

arguments.

AND

wusing

array

COMPARE-BITMAPS

its

The

1is

IMAGES AND BITMAPS

you

can

alter

bitmap

array,

alter

into

you

may wish

modify

it,

and write

bitmap
it,

create

the

operating

screen.

alter

bitmap

BITBLT

objects.

BITBLT

objects

array,
contain

operation

(with

MAKE-BITBLT

the

you

(BITBLT

arguments.

argument

the

stands

bitmap

function)

BITBLT
for

function,

BIT

Block

specifications

array.
you

When

provide

you
these

Logical

Transfer.)

for

particular

make

BITBLT

object

specifications

as
supply the BITBLT object as the single
function; this actually causes the operation to

You

BITBLT

the

complete

particular

keyword

use

then

happen.
As

simple

viewport

example,

with

Create

imagine

pattern

that

you

want

overlay

vertical

bars.

One

way

follows:
1.

you wish

bitmap

(SETF

array

from

the

portion

the

part

viwport

overlay:
BARS-BITMAP

(READ-IMAGE-PIXEL

WIN-1

4-6

NIL

120

this

150))

that

SCREEN IMAGES AND BITMAPS

Create a BITBLT object that describes the operation you
to

wish

perform:

(SETF

BARS

(MAKE-ARRAY

' (1

- ELEMENT-TYPE

4)
'BIT

- INITIAL-CONTENTS
(SETF

BARS-BITBLT

’'((1

0))))

(MAKE-BITBLT

: SOURCE BARS-BITMAP
: DESTINATION

BARS-BITMAP

: SRC-OP BOOLE-IOR
: TEXTURE

This BITBLT
should
be

function.
replace

BARS)
)

object
specifies
that
the
BARS-BITMAP
array
combined with the array BARS, using the BOOLE-IOR
The result of
this
operation
1is
then
wused
to

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 MAKE-BITBLT, you may
specify:

@ A source bitmap array.
specified

source bitmap array.

use ,a

array.

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

Keyword arguments allow you to

the

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

rectangle of

function.

the destination
In the example,
A destination bitmap array.
bitmap
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.

SCREEN IMAGES AND BITMAPS

destination

specifies
should

supply

gener al

The

can

BOOLE

function.

The

default

BOOLE-1,

source-texture

BITBLT

operation

trimmed

right

can

For

each

the

element

the

bitmap
of

result

which

result

elements

array

the

constants

that

you

operation,

used

the

destination

bitmap

array.

proceeds
out

(by

that

follows:

horizontal

combining

the

destination

the

according

with

destination

replaces

replication)

elements

wide.

to
the

the

source

This

and

(It

specified

the

element

source
in

the

operation.
texture

element,

result

(or

element

<corresponding

destination

operation.

bitmap

corresponding

combined with

result

combined

filled

example),

height.)

thereof),

texture
The

any

corresponding

which

bitmap

portion

the

These

texture

1in

source-texture

with

the

array.

the

terms,

shown

1in

bitmap

example,

array with

(not

elements

combined

destination

the

operation

how

elements

according

replaces

1is

the

destination

BITBLT

operation,

element.
For

see

the

information

description

and

exact

the

specifications

MAKE-BITBLT

manual.

4-8

the

function

Part

this

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

Selecting portions of a program,
have

screen or an item from a menu

been made

a document,

or a drawing that

pointer-sensitive

Providing positional

input for a graphics editing application

The VAX LISP
graphics
program
to
make
use
describes the various

system
provides
functions
that
allow
your
of
the
pointer in various ways.
Section 5.1
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 1is
divided

follows:

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

control.

POINTER OPERATIONS

Section 5.1.2 describes
pointer
movement
functions.
functions
allow
vyour application to react to movement
pointer cursor within defined areas of a viewport.

Section

5.1.3

functions

pointer

describes

allow your

buttons

and

released.

button

application

react

this

section,

reference

functions.

interrupt

function

some

execution.
because the

button

unknown

time,

will
is

interrupting

the

The

VAX LISP System Access Programming Guide

when

functions

convenient

and

how

for

to use

the

being

the

pressed

that

normal

1is

interrupt
meant

flow of

program

input
time,

program.

contains

information

them.

Obtaining and Setting Pointer Position

Three functions return the position of
one
function
for
each
of the three
have

These

state

Interrupt functions are necessary to handle pointer
user can move the pointer and press buttons at
any

just

5.1.1

the

made

function

not

interrupt

functions.

to determine

Throughout

invoked

input

These
of the

the pointer cursor.
There
1is
coordinate systems to which you

access:

The GET-POINTER-POSITION function returns
pointer

in world

the position of

the

pointer

cursor

the

coordinates.

The GET-POINTER-POSITION-PIXEL function returns
of

cursor

in device

the

position

coordinates.

The
GET-ABS-POINTER-POSITION
returns
pointer
cursor
on
the
screen

the
position
of
the
in
screen
coordinates

(centimeters).

All

three
value
1is
The first
pointer

the functions return multiple
values,
where
the
first
the
X coordinate and the second value is the Y coordinate.
two functions return
NIL
for
their
first
wvalue
if
the

cursor

not

the

specified window.

The pointer cursor has one particular pixel, called the active
that
is
wused
default pointer

pixel,

to
calculate
the
pointer
cursor position.
For the
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
1line
1is
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.)
1In
a graphics editor program, the user

5-2

POINTER OPERATIONS

would indicate the final position for the line by pressing a button.
simply loops until the pointer cursor
example
the
in
function
The
leaves the viewport,

Rubber-Banding with GET-POINTER-POSITION

Example 5-1:

@Wp

causing GET-POINTER-POSITION to return NIL.

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

operation.

(DEFUN RUBBER-BAND (DISPLAY WINDOW)
(DISABLE-DISPLAY-LIST DISPLAY)
(BEGIN-SEGMENT

DISPLAY)

(SET-ATTRIBUTE DISPLAY 0 1
cWRITING-MODE :COMPLEMENT)

(MULTIPLE-VALUE-BIND (ANCHORED-X ANCHORED-Y)

s Use :COMPLEMENT to
draw and erase lines
:

; Get start position

(GET-POINTER-POSITION DISPLAY WINDOW)

(DO*

( (NEW-X ANCHORED-X)
(NEW-Y ANCHORED-Y)
o

(OLD-X NEW-X NEW-X)

Coordinates for erasing

(OLD-Y NEW-Y NEW-Y))

old line

WEe

Check for out-of-bounds
|
( (NOT NEW-X)
cancel block 1
Done;
\
(END-SEGMENT DISPLAY)
disp. list
Re-enable
;
(ENABLE-DISPLAY-LIST DISPLAY))
position
s» Draw the line from start position to pointer
(PLOT

DISPLAY

ANCHORED-X ANCHORED-Y
NEW-X NEW-Y)

;;

Get new pointer position
(MULTIPLE-VALUE-SETQ

:»

Erase

|
(NEW-X NEW-Y)
(GET-POINTER-POSITION DISPLAY WINDOW))

old line
(PLOT DISPLAY 1
|
ANCHORED-X ANCHORED-Y OLD-X OLD-Y))))

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

specify.

5-3

POINTER OPERATIONS
By

contrast,

window

coordinate
Two

the

you
is

program

has

takes

returned

only

the

and

pointer
to

SET-POINTER-POSITION-PIXEL,

cursor

specified

GET-ABS-POINTER-POSITION,

workstation

screen

allow your

program

outside

viewport.
since

you

that

your

viewports

created.

functions

pointer

cursor

within

specified

respond

viewport.

following:

The

SET-POINTER-ACTION

the

pointer

portion

The

the

movement

functions

are

The

specify
cursor

and

SET-POINTER-ACTION-PIXEL

interrupt

moves

function

exits

functions

executed when

viewport

specified

viewport.

SET-POINTER-PATTERN

functions

allow

cursor.

The

pointer

cursor

you

pointer

and

SET-POINTER-PATTERN-PIXEL

specify

cursor

will

the

new

change

specified

image
to

for

that

viewport

the

image

pointer
when

portion

SET-POINTER-ACTION

display

designates

the

movement.

For

display,

arguments

as
on

world

the

pointer

all

actions

can

(1if-id),
or

NIL,

you

taken
be

one

designating

use

let

the

take

supplied

functions

two

that

pointer

cursor

moves.

function

nothing

the

often

5-4

which

arguments

are

coordinates,

display

action

exits

done.

the

cursor

the

taken

and

area.

the

executes

moves

graphics

The

when

separate

area

viewport.

function

interrupt

function

area,

executed when

set

pointer

interrupt

the

virtual

Optional

rectangle

virtual

rectangle

optional

specified

should

movement,

executes

cursor

things:

window’s

display.

window
pointer

specified

function

transformation

establish

within

the

specify

The

respond

that

The

argument.

the

give

you

coordinates

moves

can

into

functions

arguments.

action.

vyou

two

want

you

mapped

SET-POINTER-ACTION

interrupt

first

you

first

a viewport

indicating

respond

pointer

cursor

their

argument,

function

SET-POINTER-ACTION

action
be

SET-POINTER-PATTERN

which

trigger

whether

transformation

the

display

each

interpreted

The

the

and

window

viewport

should

depending

transformation

movement

and

the

viewport.

virtual

the

allow you to

The

device

window.

equivalent
the

function

information

Movement Input

number

the

that

relocate

SET-

affect

position

SET-POINTER-POSITION

cannot

5.1.2

The

system

functions,

allow
There

GET-POINTER-POSITION-PIXEL

argument.

can
The

identifier

cursor

moves;

function
every

time

continuocusly,

system

can

to
the

the

invoke

POINTER OPERATIONS

you only
Sometimes this is the intended behavior; other times,
it.
that the
indicate
to
once,
execute
to
function
interrupt
the
want
is the
this
If
rectangle.
or
viewport
the
entered
has
pointer cursor
the
resetting
by
off
itself
turn
can
function
interrupt
the
case,
which
5.2,
Section
in
seen
be
can
An example of this
action to NIL.
discusses pointer

sensitivity.

should
function
Even in applications in which a pointer movement
1is a good idea to set the movement action to
it
repeatedly,
execute
NIL at the beginning of the function, and then re-establish it at the
This prevents requests for the movement function
end of the function.
from queueing up while the movement function is executing.

Example 5-2 shows the use of SET-POINTER-ACTION to implement the
that in Example 5-1 this function was
Recall
function RUBBER-BAND.
implemented as a loop that continuously erased and replotted the line,
In Example 5-2, the
whether or not the pointer cursor was moving.
line is only

RUBBER-BAND
*POINTER-X*

erased

and

plotted

when

the

pointer

cursor

moves.

initial wvalues for the special variables
establishes
function
interrupt
establishes the
and *POINTER-Y*,

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

the

interrupt

function,

and

returns.

Every time the pointer cursor moves in the

viewport

associated

with

DRAW-RUBBER-BAND.
invokes
system
graphics
the
WINDOW,
DRAW-RUBBER-BAND first uses SET-POINTER-ACTION to turn off movement
It then erases
interrupt functions for the duration of its execution.

the old line, obtains the current pointer position, and plots the new
itself as the movement interrupt
re-establishes
it
Finally,
line.
viewport,
the
moves out of
cursor
the
I1f
function and exits.
the
re-enters
cursor
the
until
again
execute
DRAW-RUBBER-BAND does not

viewport.

The function STOP-RUBBER-BAND stops the drawing action by disabling
It also uninstates the
the pointer movement interrupt function.
interrupt

function.

UNINSTATE-INTERRUPT-FUNCTION
no longer needed;

otherwise,

important

use

to clean up interrupt functions that are

they consume system resources.

Note that- DRAW-RUBBER-BAND uses special variables to retain the
Since interrupt
for one endpoint of the line last drawn.
coordinates
unpredictable
in
functions execute at unpredictable times and
you cannot count on the binding of special variables during
contexts,
1In this case, you must be
the execution of an interrupt function.
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.

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

(BEGIN-SEGMENT

DISPLAY)

(SET-ATTRIBUTE

DISPLAY

(MULTIPLE-VALUE-SETQ

WINDOW)

:WRITING-MODE

(*POINTER-X*

:COMPLEMENT)

*POINTER-Y*)

(GET-POINTER-POSITION

(SET-POINTER-ACTION

DISPLAY

WINDOW)
)

DISPLAY

WINDOW
(SETF

*DRAW-IIF-ID*
(INSTATE-INTERRUPT-FUNCTION

# ' DRAW-RUBBER-BAND
: ARGUMENTS

(LIST

DISPLAY

WINDOW

*POINTER-X*
*POINTER-Y*)))
NIL))

DRAW-RUBBER-BAND

;75

line

new

(DEFUN

and

plots

the

interrupt

one

when

the

function

that

pointer

moves.

WINDOW ANCHORED-X

DISPLAY

Erase
(PLOT

WINDOW

existing
DISPLAY

;
NIL

Get

Turn

ANCHORED-X

ANCHORED-Y

*POINTER-Y*)

position,

(MULTIPLE-VALUE~-SETQ

plot

(*POINTER-X*

new

line

*POINTER-Y*)

(GET-POINTER-POSITION
DISPLAY

interrupts

line

new pointer

(PLOT

off

NIL)

*POINTER-X*

ANCHORED-X ANCHORED-Y

*POINTER-X*

DISPLAY WINDOW))

;

Draw

new

;

Turn

line

*POINTER-Y*)

(SET-POINTER-ACTION

interrupts

DISPLAY
WINDOW

;77

Use

(DEFUN

old

ANCHORED-Y)

(SET-POINTER-ACTION

the

DRAW-RUBBER-BAND

(DISPLAY

;;

erases

*DRAW-IIF-ID*

STOP-RUBBER-BAND
STOP-RUBBER-BAND

(SET-POINTER-ACTION

NIL))

turn

off

the

rubberbanding

(DISPLAY WINDOW)

DISPLAY WINDOW

(UNINSTATE-INTERRUPT~-FUNCTION

NIL

NIL)

*DRAW-IIF-ID%*))

5-6

action

POINTER OPERATIONS
The call to INSTATE-INTERRUPT-FUNCTION function in RUBBER-BAND

causes

the display, the
four arguments to be passed to DRAW-RUBBER-BAND:
Every time the
window, and the coordinates of the starting point.
it passes these four
system invokes DRAW-RUBBER-BAND,
graphics
to an interrupt
information
passing
of
This method
arguments.
and should be
variables,
special
of
use
the
than
function is safer
time that
the
at
information can be determined
used when the
INSTATE-INTERRUPT-FUNCTION is evaluated.

To establish an action to be taken when the pointer cursor exits an
iif-id for the exit-action argument of the
an
supply
area,
Once you have established an interrupt
SET-POINTER-ACTION functions.
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

Each pair
that specify a rectangle in which the action is effective.
of arguments supplies the coordinates of one corner of the rectangle.
the coordinates are world or transformation
For SET-POINTER-ACTION,
coordinates. For SET-POINTER-ACTION-PIXEL, the coordinates are device
coordinates.

for a
You can use the SET-POINTER-ACTION functions more than once
once
-ACTION
SET-POINTER
use
could
you
For example,
area.
particular
then
and
window,
particular
a
to specify a movement action anywhere in
1in
action
use it again with optional arguments to request a different
action
the
For any point in the window,
a rectangle in that window.
So, for
will be the one that was last requested for that point.
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
If you issued the functions in the reverse
in the second function.

order, the effect of the second function would wipe out the effect of
Figure 5-1
the first, and only the second action could be obtained.
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 wuseful 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 1is

used in calculating the actual cursor position.

POINTER

OPERATIONS

(SET-POINTER-ACTION
DISPLAY

/777,

579/7 4%%30
Ny

/7 7 /1

5?/' \\Q¢/

WINDOW

ACTION-A

NIL)

(SET-POINTER-ACTION

DISPLAY WINDOW ACTION-B NIL
2.0 2.0 3.0 3.0)

(SET-POINTER-ACTION
DISPLAY

WINDOW

2.0

3.0

2.0

ACTION-B

NIL

3.0)

(SET-POINTER-ACTION
DISPLAY

WINDOW

ACTION-A

NIL)

Z%Z{fi@T@N~A
MLO-215-86

Figure 5-1:

Example

that

the
the

5-3

shows

used

end

Specifying

the

how you

active

pixel.
based

bitmap,

not

You

can

the

use

array

should

world

active

0,0

are

the

functions,

you

cursor

and

numbers

specify
pixel

the

and

not

viewport,

wuse

you

four

want

can

For

use

SET-POINTER-PATTERN

example,

the

cursor

window,

you

should

and

rectangle

that

changed

So,

for

example,

window

first

take

the

portion
in

the

wuse

first

specified
reverse

window.

the

and

use

change

then

will

could

given

must

pattern

you

only

you

pattern

order,

the
the

for

was

last

the

effect

window

function.
of

5-8

the

area.

specify

that

particular
pattern

window,

window

1If you

second

different

afterward,

For

specify

particular

once

requested

the

and

coordinates.

SET-POINTER-PATTERN

everywhere

second

a
the

to
Use

anywhere

request

portion

wish

coordinates,

arguments

once

coordinates.

device

point

that

issued

portion

any

the

you want

use

«crosshair

again
For

device
of

whether

world

SET-POINTER-PATTERN

using

corner

that

decide

wuse

than

change.

optional

coordinates
of

rectangle.
You

specify

and

SET-POINTER-PATTERN-PIXEL

device

want

the

lower-left

specifying

you

SET-POINTER-PATTERN-PIXEL

two

cursor

coordinates
if

The

function

the
of

you

the

crosshair

window.

reference.

cause

SET-POINTER-PATTERN

both

that

origin

long

rectangle

use

set

SET-POINTER-PATTERN

viewport

specify

might

particular

Notice
on

interchangeably,

SET-POINTER-PATTERN

coordinates

and

Overlapping Areas for SET-POINTER-ACTION

the

cursor

for

that

point.

for

entire

the

cursor

except

issued

the

would

the

functions

function would wipe

out

POINTER OPERATIONS

the

effect

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

(¢000O0O0O0CO01000O00O00O0O0O0)
0000001000O0COCOO0D0)
(0
000O00O0210000O00O0O0O0D0)
(0
00O0O0CO010000O0O0OCDO0)
(00
0000010000000 DO0)
(00
0000001000000O0O0D0)
(0
000000100000O00O0O0CO0)
(0
(1111111111111110)
(00 0000010000000 0)
00O0O0O00100000O0O0DO0)
(0
(00 0000010000000 D0)
0000010000000 O0)
(00
(00000001 000000O0O0O0)
(000000010000O0O0O0O0)
(00 000002120000000O0DO0)
(0000000O0O0O0O0OCOCOOCDO0)))

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

5.1.3

Button Input

Three functions allow your program to accept input
buttons.

from

the

pointer

The functions are:

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

the

buttons
|

the

equivalent,
device-coordinate
its
SET-BUTTON-ACTION and
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 1s an
1in
integer that encodes the state of the buttons. (See GET-BUTTONS
return
this
ret
interp
to
part II for an explanation and example of how
value.) The second value is T or NIL, indicating whether the cursor 1is
visible in the window you supply as an argument.

5-9

POINTER

The

two

SET-BUTTON-ACTION

interrupt

button

function

specify

released

NIL,

interrupt

the

code
the

the

function
was

buttons

the

meaningful

function.

the

look

two

test

the

NIL

also

the

system:

direction

released).

button

your

The

button

it.

code

corresponds

example,

can

ignored.)

particular

about

the

constants

any

graphics

and
if

the

when

(You

should

released,

pressed,
what

For

establish

invoke

viewport.

whether

so,

these

one

interrupt

the

function

this:
(BUTTON

TRANSITION

(CASE

was

buttons

arguments

decide

constants

Each

the

pressed

you

system will

particular
that

button

and,

BUTTON-ACTION

(WHEN

pointing device.

(DEFUN

was

must

POINTER-BUTTON-n

interrupt

passed

that

allow

graphics

meaning

button

transition

might

function

the

interrupt

Use

the

action

The
of

functions

which

pressed

OPERATIONS

TRANSITION

;

...)

Ignore

transitions

BUTTON

(#.POINTER-BUTTON-1

...)

(#.POINTER-BUTTON-2

...)

cee)))
Example

5-4

shows

RUBBER-BAND

connected

lines.

pressing

the

new

line,

the

function

Example

pointer

pressing

Moving

the

operation;

instead,

pointer

cursor

returns,

important

SET-BUTTON-ACTION

the

viewport,

One

problem with

required.
to

values.
One

way

can

reproduces

track

5-4

the

have

one

slot

Example

5-4,

but

passed

the

and with

successive

are

for

each

uses

sets

calls

two

5-10

the

cursor

leaves

the

wvariables

variables

iif-id.

might

returns.

have

are

A more

multiple

three

four

solution.

the

for

interrupt

functions.

The

information

that

Example

functionally

5-5

instead

structure

and

must

communicate

by making

special

then

causes

DRAW-RUBBER~-BAND

functions

themselves

structure.

the

special

information

the

not

wuntil

cursor

special

and

structure
up

drawing
does

pointer

cursor

practical

«call.

argument
Those

system,

the

idle

the

five

argument

piece

function
it

which

starts

resume.

specified

not

window

pointer

until

coordinates

sit

the

drawing

and

established

number

line

the

when

the

maintaining

DRAW-CONNECTED-LINES

RUBBER-BAND-BUTTON-HANDLER.

other

interrupt

the

structure

action

situation

terminates

effective

soon

extend

method

current

out

inactive

each

variables

window will

the

line

such

problem

button

crude

drawing will

only

the

application,

that would

pass

each

the

simple
of

special

solve

structure

variables.

this

application,

Example

viewport

Thus,

the

that
is

sets

cursor

action becomes

keep

functions
passed

note

functions

the

Even

complicated

areas

then

specified viewport.

that

required

and

into

ends

rightmost

pointer

5-2

button

the

terminate

SET-BUTTON-ACTION

DRAW-CONNECTED-LINES

leftmost

and

operation.

wuse

with

and
each

alterations

POINTER OPERATIONS

Example 5-4:

Controlling Rubber-Banding with Pointer Buttons

(DEFVAR

*ANCHORED-X*)
*ANCHORED-Y*)
*POINTER-X*)

(DEFVAR

*POINTER-Y*)

(DEFVAR

*RUBBER-IIF*)

(DEFVAR
(DEFVAR

:++ The user calls DRAW-CONNECTED-LINES to draw a series of
++: lines. The left button starts each new line and the right
:+: button finishes the series.

(DEFUN DRAW-CONNECTED-LINES
(BEGIN-SEGMENT DISPLAY)

(SET-ATTRIBUTE DISPLAY 0 1

(DISPLAY WINDOW)

:WRITING-MODE : COMPLEMENT)

;s Set up the interrupt function that draws and erases lines
(SETQ

*RUBBER-IIF*

(INSTATE-INTERRUPT-FUNCTION
#’'DRAW-RUBBER-BAND

« ARGUMENTS

(LIST DISPLAY WINDOW)))

;: Set up the interrupt function that handles button transitions.
.+ LINE-DONE and DRAWING-DONE are flags that will be manipulated
;3

by button handler.

(LET*

((LINE-DONE (CONS NIL NIL))
(DRAWING-DONE (CONS NIL NIL))
(BUTTON-IIF

(INSTATE-INTERRUPT-FUNCTION
4 ' RUBBER-BAND-BUTTON-HANDLER

. ARGUMENTS (LIST LINE-DONE DRAWING-DONE))))
(SET-BUTTON-ACTION DISPLAY WINDOW BUTTON-IIF)

.+ Wait for user to press left button to start first line
(WAIT "Waiting for start of drawing” #'CAR LINE-DONE)

; Get start position

(MULTIPLE-VALUE-SETQ
(* ANCHORED-X*

*ANCHORED-Y*)

(GET-POINTER-POSITION DISPLAY WINDOW) )

(SETQ *POINTER-X* * ANCHORED-X* *POINTER-Y* *ANCHORED-Y*)

.. Execute the following loop once for each line that is drawn
;; permanently in the display.
(LOOP

(DISABLE-DISPLAY-LIST DISPLAY)

(SET-POINTER-ACTION

DISPLAY WINDOW *RUBBER-IIF* NIL)

¢ Start rubberbanding

(WAIT "for end of rubberbanding” #’CAR LINE-DONE)
5-11

POINTER

Example

5-4

(cont.)

(SET-POINTER-ACTION
DISPLAY

WINDOW

.
NIL

(ENABLE-DISPLAY-LIST
(PLOT

DISPLAY

DISPLAY)

*ANCHORED-X*

(SETQ

*ANCHORED-X*

*POINTER-X*)

*ANCHORED-Y*

*POINTER-Y*))

(CAR

DRAWING-DONE)

(SETF

(CAR

LINE-DONE)

(RETURN) )

DISPLAY

(DISABLE-DISPLAY-LIST

7 77

DRAW-RUBBER-BAND

pointer

Right
No,

NIL)

;

Yes,

BUTTON-IIF))

;

DISPLAY

(PLOT

permanently

button?

loop

again

dismantle

the

machinery

DISPLAY)

draws

and

*RUBBER-IIF*))
erases

lines

response

(DISPLAY

WINDOW)

(SET-POINTER-ACTION

Erase

line

movement.

DRAW-RUBBER-BAND

contains

Draw

DISPLAY)

;77

;

WINDOW

(UNINSTATE-INTERRUPT-FUNCTION

rubberbanding

;

NIL))

(UNINSTATE-INTERRUPT-FUNCTION
(END-SEGMENT

Stop

*ANCHORED-Y*

(SETQ

(SET-BUTTON-ACTION

;

NIL)

(WHEN

(DEFUN

OPERATIONS

WINDOW

existing

;
NIL

line.

Attribute

:WRITING-MODE

DISPLAY

Turn

off

interrupts

NIL)

*ANCHORED-X*

*POINTER-X*

block

:COMPLEMENT
*ANCHORED-Y*

*POINTER-Y*)

;; Get new position and plot line
(MULTIPLE-VALUE-SETQ

(*POINTER-X%*

*POINTER-Y*)

(GET-POINTER-POSITION
(PLOT

DISPLAY

*ANCHORED-X*

*POINTER-X*

*ANCHORED-Y*

*POINTER-Y*)

(SET-POINTER-ACTION
DISPLAY

WINDOW

;
*RUBBER-IIF*

RUBBER-BAND-BUTTON-HANDLER

handles

all

except

down

;3;

right buttons.

(DEFUN

all

transitions

Restore interrupts

NIL))

77+

ignores

WINDOW) )

button

transitions.

transitions

left

TRANSITION

(CASE

(WHEN

DRAWING-DONE)

Args.

TRANSITION

LINE-DONE

Args.

(BUTTON

Ignore

A
X

RUBBER-BAND-BUTTON-HANDLER

Left

from

supplied
up

graphics
when

system
instated

transitions

BUTTON

(#.UIS::POINTER-BUTTON-1
(SETF

(CAR

LINE-DONE)

T))

5-12

button;:;

start

new

line

and

POINTER OPERATIONS

Example

(cont.)

5-4

(#.UIS: :POINTER-BUTTON-3
(SETF

Example 5-5:

(CAR

LINE-DONE)

; Right button; end line and terminate
T

(CAR DRAWING-DONE)

T)))))

Using Structures to Eliminate Special Variables

s+ 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)

; Start position for
line
:
¢ Current line endpoint
;
;

Flags for button
handler

RUBBER-IIF)

(DISPLAY WINDOW)

(DEFUN DRAW-CONNECTED-LINES
(BEGIN-SEGMENT

DISPLAY)

(SET-ATTRIBUTE DISPLAY 0

(LET*

((DI

:WRITING-MODE

:COMPLEMENT)

(MAKE-DRAW-INFO
:DISPLAY DISPLAY
)
:WINDOW WINDOW)

. Make structure to
hold drawing
;
information
:

; Set up button handler

(BUTTON-IIF

(INSTATE-INTERRUPT-FUNCTION

«ARGUMENTS

(LIST DI))))
c

(SETF (DRAW-INFO-RUBBER-IIF DI)

A
X

# ' RUBBER-BAND-BUTTON-HANDLER
;

; Set up move handler

(INSTATE-INTERRUPT-FUNCTION
# ' DRAW-RUBBER-BAND

s
: ARGUMENTS (LIST DI)))
(SET-BUTTON-ACTION DISPLAY WINDOW BUTTON- IIF)
(WAIT "Waiting for start of drawing”

(MULTIPLE-VALUE-BIND (X Y)

(GET-POINTER-POSITION DISPLAY WINDOW)

(DRAW-INFO-ANCHORED-X DI)

Pass structure

; Use slot as flag

# ' DRAW-INFO-LINE-DONE DI)

(SETF

Pass structure to
interrupt function

(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

+ Put line coords.

;

in structure

POINTER OPERATIONS

Example

5-5

(cont.)

(SET-POINTER-ACTION
DISPLAY

(DRAW-INFO-RUBBER-IIF

(WAIT

"for

end

DI)

# 'DRAW-INFO-LINE-DONE

DISPLAY

NIL

;

Check

struc.

Plot

permanent

DISPLAY)

;

from

(DRAW-INFO-ANCHORED-Y

DI)

;

Right

(DRAW-INFO-ANCHORED-X

DI)

(DRAW-INFO-POINTER-X

DI))

(DRAW-INFO-ANCHORED-Y

DI)

(DRAW-INFO-POINTER-Y

DI)))

(DRAW-INFO-DRAW-DONE

DI)

(DRAW-INFO-LINE-DONE

(SET-BUTTON-ACTION
(END-SEGMENT

DISPLAY

(RETURN))

DI)

structure

WINDOW

NIL)

(UNINSTATE-INTERRUPT-FUNCTION

(DRAW-INFO-RUBBER-IIF

BUTTON-IIF)

(DEFUN

now

DRAW-RUBBER-BAND

(DI)

NIL

passed

(DRAW-INFO-WINDOW

(DRAW-INFO-DISPLAY

DI)

one

argument,

structure

NIL

NIL)

(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

(PLOT

(DRAW-INFO-DISPLAY

DI)

(DRAW-INFO-WINDOW

DI))

(DRAW-INFO-DISPLAY

DI)

(DRAW-INFO-ANCHORED-X

DI)

(DRAW-INFO-ANCHORED-Y

DI)

(SETF

(DRAW-INFO-POINTER-X

DI)

(SETF

(DRAW-INFO-POINTER-Y

DI)

Y)))

(SET-POINTER-ACTION

NIL
(DRAW-INFO-WINDOW

DI)

(DRAW-INFO-RUBBER-IIF

DI)

NIL))
7 7+

DI))

DISP)))

(SET-POINTER-ACTION
(PLOT

button?

(UNINSTATE-INTERRUPT-FUNCTION

DRAW-RUBBER-BAND

coords.

NIL))

DISPLAY)

(DISABLE-DISPLAY-LIST

slot

NIL)

DI)

(SETF

i + 7

WINDOW

(DRAW-INFO-ANCHORED-X

(SETF

(IF

rubberbanding

NIL)

DI)

DISPLAY

(ENABLE-DISPLAY-LIST

(SETF

Start

rubberbanding"

(SET-POINTER-ACTION
(PLOT

;

WINDOW

RUBBER-BAND-BUTTON-HANDLER

passed

5-14

structure

and

line

left

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)
(CASE

; Ignore up transitions

(WHEN TRANSITION
BUTTON

(#.UIS::POINTER-BUTTON-1 ; Left button; start new line
(SETF

(DRAW-INFO-LINE-DONE DI)

T))

(SETF

(DRAW-INFO-LINE-DONE DI)
(DRAW-INFO-DRAW-DONE DI)

T
T)))))

(#.UIS::POINTER-BUTTON-3 ; Right button; terminate

- 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 1initiates
some action when the user presses a pointer button while the pointer
cursor is in the region. 1In the standard VAXstation wuser 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

ways

making

region

viewport

pointer-sensitive:

You can use the SET-POINTER-ACTION or SET-POINTER-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

each

region.

channels.

pointer-sensitive

region

consumes

system

I/0

for
1In addition, data structures must be maintained

use
to
is
A simpler and more economical alternative
the
for
once
just
SET-POINTER-ACTION and SET-BUTTON-ACTION

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

5-15

time

the

pointer

movement

POINTER OPERATIONS

interrupt

function

pointer

in,

already

been

executes,

occupies
Example

5-6

shows

implement

and

displays

one

simply

the

column,

use

the

(USE-PACKAGE

"UIS")

button
to

region

the

has

not

interrupt

indicate

the

function
region

method

function

that

function.

functions

vertical

either

had

above

constructs

previously

Since

can

location

outlined

the

determine

the

pointer

cursor

the

need

remember

has

(DEFSTRUCT

been

(MENU

the

made

menu’s

window

the

cases

invisible.

(:PREDICATE

MENUP))

WINDOW

(RETURN~-VALUE

NIL)

)
;i Here's

our

function

;;

(highlighting

1ts

height

the

(DEFUN

the

box

window

around

entry

entry,

and width.

MENU-BOX-PIXEL

(W ATTR

ENTRY

ENTRY-HEIGHT

ENTRY-WIDTH)

(

ENTRY-WIDTH)
(+

;;

need

menu,

left

position

Lower

left

position

Upper

right

position

Upper

right

position

LLX

URY

@TMe

ENTRY

LLY
W

ENTRY-HEIGHT))

ENTRY-HEIGHT)))

ATTR

find

LONGEST

(REDUCE

(URX
(URY

Lower

(LLY

(LLX

(PLOT-PIXEL

;;

drawing

wWe

(LET*

for

given

(DEFUN

it),

LLX

out

that
(&REST

#'’ (LAMBDA

LLY

the

URX

size

LLY

viewport

URX

the

size

URY

longest

can

string

LLX

computed.

ENTRIES)

(LOCAL-MAX
(MAX

THIS-ENTRY)

LOCAL-MAX

ENTRIES

: INITIAL-VALUE

0))

5-16

(LENGTH

THIS-ENTRY)))

been

contains

A Simple

when

the

interrupt

Example 5-6:

the

second

The

redisplays

the

which

region

structure

system.

viewport.

;;

When

data

returned

finding

determines

that

moment.

menu,

and

highlighted.

that

highlights

alters

simple

constructed

only

executes,

and

LLY)))

region

the

POINTER OPERATIONS

(cont.)

5-6

Example

(DEFUN GET-POINTER-POSITION-Y-PIXEL (WINDOW)
(MULTIPLE-VALUE-BIND

(X Y)

(GET-POINTER-POSITION-PIXEL WINDOW)
(DECLARE

(IGNORE X))

Y))

e )

A
X

=me

We
Wy

WwWe

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

Passing a old menu means you want to use it.
Passing NIL means make a new menu (that can be
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”

(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")
Else make 1t visible
;
(PROGN

(MOVE-VIEWPORT (MENU-WINDOW OLD-MENU) :INVISIBLE NIL)
(SETF (MENU-RETURN-VALUE OLD-MENU) NIL)))

(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 ?EXT—ATTRwBLK c: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

Example

5-6

OPERATIONS

(cont.)

(LET*

(

(COMPLEMENT-ATTR-BLK

;;

currently

;;

will

use

entry

last-entry

highlighted
is

(LAST-ENTRY

(ONE-TIME

keep

entry.

trace
A

value

the

-1

means

highlighted.

-1)

(NOT

(THIS-MENU

200
)

(EQ

OLD-MENU)))

(MAKE-MENU

(WINDOW-RIGHT-MARGIN

:WINDOW

WINDOW))

MENU-WIDTH-CHARS

TMWEg

wWe

the
they

®wWe

Wma

The

viewport,

CHAR-SIZE-X-PIXELS))

movement

action

what

current
are

finds

entry

where

that

are

corresponds

and unhighlights

the

to,

the

highlights

last

entry

different.

(MOVEMENT-IIF
(INSTATE-INTERRUPT-FUNCTION

4’ (LAMBDA
(LET

((Y

(WHEN

()

(GET-POINTER-POSITION-Y-PIXEL

WINDOW)))

(SETF

(WHEN

(FLOOR
(NOT

(WHEN

(EQ

(NOT

ENTRY-HEIGHT))
Y

LAST-ENTRY))

(EQ

LAST-ENTRY

-1))

(MENU-BOX-PIXEL

WINDOW

COMPLEMENT-ATTR-BLK

LAST-ENTRY

ENTRY-HEIGHT

WINDOW-RIGHT-MARGIN)
)
(MENU-BOX-PIXEL

WINDOW
Y

h X ]
9

WY
WE

- @

The
By

movement

(SETF

exit

action

racing

the

see

LAST-ENTRY

unhighlights

pointer

action

any

COMPLEMENT-ATTR-BLK

ENTRY-HEIGHT

may

very

entries

(EXIT-IIF

WINDOW-RIGHT-MARGIN)

Y)))))))

the

current

quickly

recieved.

are

entry.

across
So

the

need

highlighted.

menu,
to

(INSTATE-INTERRUPT-FUNCTION

¥’ (LAMBDA

()

(WHEN

(NOT

(EQ

LAST-ENTRY

-1))

(MENU-BOX-PIXEL

WINDOW

COMPLEMENT-ATTR-BLK

LAST-ENTRY

ENTRY-HEIGHT

WINDOW-RIGHT-MARGIN)
(SETF

LAST-ENTRY

5-18

-1)

check

POINTER OPERATIONS

Example

(cont.)

5-6

"We

‘we

))))

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
If this menu is to be used only once,
test this case.
or the "Exit menu" entry is selected, then we uninstate
the various actions and delete the display.

(BUTTON-IIF

(INSTATE-INTERRUPT-FUNCTION

' (LAMBDA (BUTTON-NUMBER TRANSITION)
(DECLARE

(IGNORE BUTTON-NUMBER))

(WHEN (EQ TRANSITION NIL)
(LET

; Button released

((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
s+ selection "Exit menu"
(IF (OR ONE-TIME (EQ THIS-ENTRY 0))
( PROGN

(UNINSTATE-INTERRUPT-FUNCTION
MOVEMENT-IIF)

(UNINSTATE-INTERRUPT-FUNCTION
EXIT-IIF)

(SETF

(MENU-WINDOW THIS-MENU) NIL)

(DELETE-DISPLAY DISPLAY))

(MOVE-VIEWPORT WINDOW :INVISIBLE T))
))))

wme

)

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

COMPLEMENT-ATTR-BLK

:WRITING-MODE

(SET-ATTRIBUTE

DISPLAY

:FONT
(SET-ATTRIBUTE

The

(DO*

entries

COMPLEMENT-ATTR-BLK

:FILL-PATTERN

:FOREGROUND)

are

the

put

ENTRIES

ENTRY-HEIGHT

( (NULL

(CDR THIS-ENTRY))
Y

ENTRY-HEIGHT)))

THIS-ENTRY))

(*
The

COMPLEMENT-ATTR-BLK

screen

(TEXT-PIXEL WINDOW TEXT-ATTR-BLK

COMPLEMENT-ATTR-BLK

"UISSFILL_PATTERNS")

DISPLAY

((THIS-ENTRY
(Y

:COMPLEMENT)

COMPLEMENT-ATTR-BLK

action

routines

are

set

(SET-POINTER-ACTION-PIXEL
(SET-BUTTON-ACTION

And

the

structure

you

get

the

;;

this

;;

screen

function
1f

for

return
was

again
made

MOVEMENT-IIF

WINDOW

this

value.

put

invisible

EXIT-IIF)

BUTTON-IIF)

Passing

will

Y))

up,

WINDOW

DISPLAY

(CAR THIS-ENTRY)

CHAR-SIZE-X-PIXELS)

returned,
the

the

last

letting
structure

back

the

time.

THIS-MENU

)))))))
;Another

;just

possiblity

make

the

; DESTROY-MENU

;and

for

the

"exit

invisible.

function

that

menu"

cleaned

that
up

actions.

5-20

entry would

case
the

one

have

would

add

structure

The VAX LISP graphics system provides a

means

for

your

program

toO

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

This chapter treats keyboard input in the following sections:

Section 6.1 describes

virtual

keyboards

create them and attach them to windows.

Section 6.2 explains how to capture and
from a

and

shows

interpret

how

keystrokes

keyboard.

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

RTUAL

type.

KEYB OARDS

A virtual keyboard is a LISP object that you create with the CREATE-KB
1t forms the link between the physical keyboard and your
function.

keyboard
physical
one
Although there 1is only
program.
.
keyboards
virtual
of
workstation, you can have any number

per

KEYBOARD

6.1.1
The

Using Virtual
first

step

CREATE-KB

using

function

(SETF

The

Keyboards:

*KB*

step

you

This

associate
in

icon

the

virtual

creates

and

virtual

right

corner

viewport

the

added
to an

keyboard

the

user

it.

The

viewport.

The

keyboard

viewport,

the

physical

the

software

them.
to

keyboard
point

of viewports
The

each

physical

keyboard

attached

indicates

CYCLE

viewport

key
on

that

can

the

can have

the

(function

the

view,

key

assignment

F5)
list

keyboard

keystrokes

associated with

the

viewport,

the

a call

associated

icon.

will

this

CREATE-WINDOW
viewport

can

still,

associated with

6-1

illustrates

now

directed

through

viewport.

includes

will

however,

:NOKB-ICON T,

wunable

have

acquire

virtual

the
a

keyboard

it.

the

icon

«s

]

that

NOTE

Figure

icon

banner:

the

virtual

with

that

highlighted:

This

From

turn.

When

creating
keyboard:

with

viewport’s

assignment list

attached

physical

keyboard

viewport.

the

virtual

*INPUT-WINDOW* )

this

the

*KB*

indicates

attaches

does this:

attached

physical

keyboard

returns

associate
function

(ENABLE-VIEWPORT-KB

appears

Overview

(CREATE-KB))

ENABLE-VIEWPORT-KB

When

INPUT

sequence

6-2

events

just

described.

the

KEYBOARD

*INPUT—

WINDOWTM

INPUT

*INPUT—

WINDOWTM

*INPUT—

WINDOWTM
.

*—-——-— 1

(SETF *KB* (CREATE-KEYBOARD) )

(ENABLE-VIEWPORT-KB

Cycle

*KB* *INPUT-WINDOW*)

(ENABLE-KB

Figure 6-1:

*KB*)

Creating and Attaching Virtual Keyboards

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

Keyboard characteristics of the virtual keyboard

the

Keystrokes on the physical keyboard are delivered through

the

physical

(established
on

with

SET-KB-ATTRIBUTES

function)

imposed

are

keyboard.

1s, an interrupt
That
keyboard to your program.
virtual
the
with
function specified for this wvirtual keyboard
key 1is
SET-KB-ACTION function will execute every time a

struck.

(See Section 6.2 for

information

capturing

interpreting keystrokes.)

and

The ENABLE-KB function makes a particular virtual keyboard the active
It is equivalent to the wuser associating the physical
keyboard.
a
keyboard with a viewport by pressing the CYCLE key or by pressing
viewport
which
Use ENABLE-KB when you want to control
pointer button.
Otherwise, let the user select
is connected to.
the physical keyboard

the viewport with the CYCLE key or pointer.

A virtual keyboard can be associated with more than one viewport.

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

Now

both

*INPUT-WINDOW*

keyboard
means,

*KB*.

the

viewports

will

However,

icons
It

will

that

Unless

CREATE-KB

The

keyboard

and

set

with

the

keyboard,

through

any

list;
is

highlighted.

that

first

keyboard

the

is,

one,

wup

for

the

cursor

take

Section

echoing

the

interrupt

lost.

delete

with

the

Before

you

associate

you

Keyboards

receive

any

not

typed

response

contains

virtual

resources,

need

currently

from

associated

and

are

the

active

argument

function’s

which,

Associating

previously

associated

viewport

keyboard

the

and

second

keyboard.

corresponding

use

its

with

take

viewport

terminated.

Keyboard

keyboard,

1its

Since

should

you

must

this:

ENABLE-VIEWPORT-KB function associates
the

object.

you

Physical

virtual

functions

with

object.

any viewport

them.

associations

Viewports

Two

argument

with

keyboard

first

the

information

keyboard

associated

system

input

receive

wvirtual

longer

with

keyboard

viewport.

appropriate

The

ENABLE-KB

the

those

viewport.

the

characters

later.

keyboard,

The

key

other.

either,

virtual

function

6.2

returns
is

consume

that

the

that

deletes

keyboard

with

and

you

window named

also

must

them when

Both

CYCLE

Keyboards

CREATE-KB

objects

physical

can

Virtual

creates
by

function

delete

the

then

assigned

association

program

Deleting

created;

provision

your

function

keyboard

If you

can

that

keyboard,

returned

DELETE-KB

virtual
care

associated

will

assignment

physical

are

active

this.

The

the

viewports

the

keyboard

you

*WINDOW-2*

becomes

highlighted.

they will

Creating

when

note

virtual

keystrokes,

about

the

makes

responsibility

input.

viewport

through

the

physical

both

*KB*
both

the

important

entries

whenever

with

icon

have

assign

and

Whenever

INPUT

viewport

the

keyboard

corresponding

named
to

the

argument.

primary purpose

However,

supplied,

make

keyboard

takes an optional window

associates

the

keyboard

with

the

viewport.
with

with

viewport

that

DISABLE-VIEWPORT-KB

keyboard.

causes

viewport

function

any

keyboards

become
to

that

dissociated.

were

You

explicitly dissociate

KEYBOARD INPUT

a keyboard can become active
Once associated with a viewport,
(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 by moving the pointer cursor into a
(The second
viewport and pressing the left pointer Dbutton.
if the default button action has been
method does not work
superseded for that window;

see Chapter 5.)

specific

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

keyboard inactive.
Either the user or the program can make a virtual
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.

Three functions let you find out if a virtual keyboard is active,
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.

and

1in 1its
and NIL

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

Setting Keyboard Attributes

6.1.4

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

the

Autorepeat controls whether keys on

Two keyclick attributes control whether,

Seven key group

generate a character when held down.

click sounds when a key is pressed.

enabling

and

disabling

keyboard
and

how

repeatedly
loudly,

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

KEYBOARD INPUT

You

The

six

The

arrow

The

numeric

set

wvirtual

function.
identify

the

attribute

all

the

and

the

keyboard

the

HELP

and

keys

keys
attributes

argument

remaining

GET-KB-ATTRIBUTE

attribute,

below
|

keypad

first

the

keys

keyboard

The

keyboard;

The

editing

arguments

and

with

are

its

setting.

function

returns

and

SET-KB-ATTRIBUTES

their

keyword-value

the

GET-KB-ATTRIBUTE-LIST

attributes

the

SET-KB-ATTRIBUTES

wvalue

function

settings

for

virtual

pairs

that

particular

returns

list

specified virtual

keyboard.

6.2

CAPTURING AND INTERPRETING

This

section

explains

virtual

keyboard.

function

handle

keystrokes

describes

6.2.1
To

from

the

receive

establish

key

function

interrupt

the

from

that

will

SET-KB-ACTION
a

least

future

two

6.2.2

shows

how

arguments with

the

interrupt

Section

6.2.3

explains

virtual

each

from

interrupt
to

read

Section

6.2.3

key.

function

arguments:

you

the

can

call

keyboard,

execute

virtual

struck,and

wuse;

additional

flag.

it.)

such

The

You

interrupt

(The

must

keyboard

establishes
character

state

you

time

keyboard.

ignore

each

integer

state

can

flag

supply

INSTATE-INTERRUPT-FUNCTION that

function.
the

first

argument

that

passed

keyboard

function.

Reading Keyboard Input Synchronously

can

also

read

individual

synchronous

fashion

returns

specified

that was

defines

You

establish

to designate

input

for

key

reserved
for

6.2.2

input

synchronously.

function

The

receives

interrupt

interpret

how

Section

keyboard

that VAX LISP uses

function

designating

and

shows

Interrupt Functions

pressed.

interrupt

receive

6.2.1

wvirtual

asynchronous

keystrokes.
a

values

Keyboard

how

Section

KEYSTROKES

the

keystroke

becomes

by using

character

1is

available,

keystrokes

the

from

READ-KB-CHAR

integer

from

READ-KB-CHAR

available.

6-6

virtual

keyboard

function.

This

specified

does

not

function

keyboard.

return until

one

6.2.3

Section

explains

KEYBOARD

INPUT

wvalue

returned

the

READ-KB-CHAR

function.

6.2.3

Characters Generated by Keys

For all the printing and control keys, the

character

received

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

Table 6-1:

LISP Constants Corresponding to LK201 Keys
Constant

Key

Numeric Keypad Keys
keypad
keypad
keypad
keypad
keypad
keypad
keypad
keypad
keypad
keypad
keypad

SMG:K-TRM-KPO0
SMG:K-TRM-KP1
SMG: K-TRM-KP2
SMG:K-TRM-KP3
SMG:K-TRM-KP4
SMG:K-TRM-KP5
SMG:K-TRM-KP6
SMG:K-TRM-KP7/
SMG:K-TRM-KP8
SMG:K-TRM-KP9

O
1
2
3
4
5
6
7
8
9
-

SMG:K-TRM-MINUS
SMG:K-TRM~-COMMA
SMG:K-TRM-PERIOD
SMG:K-TRM-ENTER

keypad ,
keypad .
keypad Enter

keypad
keypad
keypad
keypad

Function,

F6
F7
F8
F9
F10
Fl11
F12

SMG:K-TRM-PF1
SMG:K-TRM-PF2
SMG:K-TRM-PF3
SMG:K-TRM-PF4

PF1
PF2
PF3
PF4

Help,

and Do Keys

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

F13

SMG:K-TRM-F13

Fl14

SMG:K-TRM-F14

F15

(Help)

SMG:K-TRM-HELP

F16

(Do)

SMG : K-TRM-DO

F17

SMG:K-TRM-F17

F18

SMG:K-TRM-F18

F19

SMG:K-TRM-F19

F20

SMG:K-TRM-F20
Editing

and Arrow Keys

(Find)

(Insert

(Remove)

SMG:K-TRM-REMOVE

(Select)

SMG:K-TRM-SELECT

(Prev

Screen)

SMG:K-TRM-PREV-SCREEN

(Next

Screen)

Arrow

Down

Right
Left

SMG:K-TRM-FIND

Arrow

Arrow
Arrow

Here)

SMG:K-TRM-INSERT-HERE

SMG K-TRM-NEXT-SCREEN
SMG: K-TRM-UP
SMG: K-TRM-DOWN

SMG: K-TRM-RIGHT
SMG: K-TRM-LEFT

6-8

The VAX LISP graphics system allows you to create a LISP output stream

Output directed to this stream by any of the normal LISP
to a window.
associated viewport.
output functions is displayed in the window’s
in which output 1is
viewport
the
of
portion
the
control
can
You
overflow are
displayed, and the way in which horizontal and vertical
with the
used
You can also specify an attribute block to be
treated.
stream, allowing you to control the font and writing mode.
This

chapter

divided as

follows:

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.

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

One

Y EATING

AND

USING

function

and

one

macro

create

window

streams.

output

The

MAKE-WINDOW-OUTPUT-STREAM function creates and returns a window output
creates a window output
The WITH-OUTPUT-TO-WINDOW macro
stream.

stream and binds a variable to it while the forms in the macro’s body
When the body terminates, WITH-OUTPUT-TO-WINDOW closes the
execute.

window

output

stream.

a
Neither MAKE-WINDOW-OUTPUT-STREAM nor WITH-OUTPUT-TO-WINDOW creates
a
create
take window objects as arguments and
Both
window object.

stream associated with that window.

When the stream

closed,

the

window is not affected.

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

WINDOW

Characters
The

first

viewport,

line

output
output

to
to

the
the

stream will
stream

with

subsequent

it,

depending

below

and

the

stream.
®

The

control

keywords,

and

:VIEWING-AREA

output

text

specify

(x1

y2),

the

viewport.

the

window’s

upper-left
the

first

function

characteristics

they

the

area

viewing

area,

the

specify a

you

device

1in

the

default,

1If

place

output

giving

takes

the

WITH-OUTPUT-TO-WINDOW

controls

output

LISP

displayed.

used.

appended

the

arguments

appear

appears

output

MAKE-WINDOW-OUTPUT-STREAM

that

OUTPUT STREAMS

viewport.

corner

output

both

take

the

window

entire

list

coordinates

viewing

area,

upper-left

corner

output

which

viewport

keyword
are:

wviewport

supply

the

used.

control,

the

form

rectangle

initial
of

the

text

viewing

area.

You

can

create

multiple

stream

having

its

similar

scrolling

operation

the

to write
value

dropped,

:WRAP,

line.

Excess

truncated

:VERTICAL-OVERFLOW

the

text
be

same

This

video

causing

window,

behavior

beyond

the

each

facility

are

until

when

right

edge

causing

characters

wrapped

with

provides

terminal.

:TRUNCATE,

characters

attempts

area.

The

scrolled

indicating
replacing

can

the

characters

be wrapped onto

wrapped
the

output

stream

default.

encounters

character.

operation

viewing

area.

controls

The

#\NEWLINE

area.

Text

attempts

streams

viewing

areas

:HORIZONTAL-OVERFLOW

viewing

own

controls

the

text

value

can be

:SCROLL,

text

line

behavior

write

wupwards

that

the

to
be

accomodate

below

top of

the

new

screen.

the

lines

:WRAP,

the

Text

that

line,

with

output

bottom

indicating

vertically wrapped,

the

when

the

new

1line

scrolled

by default.
®

:ATTRIBUTE-BLOCK

text

default,

output.

However,

display

that

The
area

if you

associated

designates

text

the

attribute

written

with

block

used

attribute

have created a new attribute block
with
the
output window, you can

for

block

for the
specify

attribute

different

block
with
this keyword.
By
specifying
a
attribute block, you can change the font and writing

mode

used

output

ERASE-VIEWING-AREA
of

upper-left

function

window output

corner

text.

the

erases

stream,

viewing

and

area.

7-2

anything
resets

the

within
text

the

position

viewing
to

the

WINDOW OUTPUT STREAMS

7.2

ALTERING WINDOW OUTPUT STREAMS

Once a window output stream has been created, you can alter any of the
characteristics
that
vyou
established
when
you
created
1it.
The
following sections

Section 7.2.1 shows how to change the viewing area.

Section

7.2.2

characteristics.

shows

how

change

the

overflow

Section 7.2.3 shows how to change the attribute block used
write

7.2.1

show how to do this:

output through the

stream.

Changing the Viewing Area

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 (x1 yl1 x2 yZ2).

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
resized
when
the user resizes the associated viewport.
if you set up a window output stream without a specific

automatically
For example,
viewing
area

-that
1is,
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
wuser
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)

WINDOW OUTPUT STREAMS
Example

(DEFUN

7-1

(cont.)

RESIZE-VIEWING-AREA

(NEW-SCREEN-X

NEW-WIDTH

NEW-SCREEN-Y

NEW-HEIGHT

STR)

(MULTIPLE-VALUE-BIND

(JUNK-1

JUNK-2

H-RES

V-RES)

(GET-DISPLAY-SIZE)
(DECLARE

(FLOAT

H-RES

(IGNORE
(SETF

V-RES)

JUNK-1

JUNK-2))

(WINDOW-STREAM-VIEWING-AREA

(LIST

(FLOOR

H-RES

NEW-WIDTH))

(FLOOR

V-RES

NEW-HEIGHT))))))

(RESIZE-WINDOW

NIL

(WINDOW-STREAM-WINDOW

NEW-SCREEN-X

7.2.2
You

STR)

NEW-SCREEN-Y

;

New viewport

;

in pixels

STR)

NEW-WIDTH

NEW-HEIGHT

Y2))

Changing Overflow Behavior
can

change

overflows

the

either

way

when

text

the

right or bottom edge of the viewing area.

window

output

stream

behaves

The

WINDOW-STREAM-HORIZONTAL-OVERFLOW
horizontal
overflow
behavior
of
keyword, either :TRUNCATE or :WRAP.

function
returns
a
window
stream in
Use SETF with
this

change

the

value.

behavior,

Similarly,

vertical
SETF with

7.2.3

size

specifying

function

keyword

WINDOW-STREAM-VERTICAL-OVERFLOW

overflow behavior,
this

appropriate

Changing the Attribute

either
change

:SCROLL or
the

the
current
the form of a
function
to

:WRAP.

the

returns

You

can

new
the

also use

behavior.

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

to specify a new attribute block.

attribute

used

a window output stream.

the attribute block

You can use SETF with this function
The new

associated with the window stream’s virtual

display.

block

must

WINDOW

OUTPUT STREAMS

NOTE

Changing the size of the font in which text is written
cause vertical interference between characters on
may
consecutive

You

should use

lines.

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.

7.3

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

Window output streams write

text

windows

wusing

the

TEXT-PIXEL

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

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

7.3.2

interference.

Vertical Scrolling and Erasing

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

resizes

the viewport.

WINDOW OUTPUT STREAMS

the

same

viewing

7.3.3

way,

area.

ERASE-VIEWING-AREA

Everything

the

wuses

viewing

ERASE-PIXEL

area

erase

the

erased.

Display List

Since window output streams write text with TEXT-PIXEL,
modify

the

display

list.

7-6

they

not

PART Il

GRAPHICS SYSTEM COMPONENTS

GRAPHICS SYSTEM COMPONENTS
BEGIN-SEGMENT Function

The contents of all attribute blocks are
Begins a new segment.
Changes to attribute blocks made
propagated to the new segment.
when the segment ends, and the
cancelled
during segment creation are
is terminated by a call to
segment
original settings are restored. A
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
UISSBEGIN_ 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.
This

function is

1in package LISP.

Format

LISP:BITBLT bitblt
Arguments

bitblt

An object of type BITBLT
Return Value

Undefined

GRAPHICS SYSTEM COMPONENTS

Corresponding

MicroVMS

Routine

None

BITBLT Type Specifier
Designates

objects

cases

moving

and

argument

specific

the

objects

can

perform

identical

object

can

function,

created
or

BITBLT;

modifying

BITBLT

operation

type

block
an

needed with

with

represent

bits.
of

the

operations

any

objects

object

performed

similar

modified

these

When

type

supplied

BITBLT

specific

different

number

BITBLT

function.

bitmaps,

accessor

the

causes

bitmap.

MAKE-BITBLT

specific

BITBLT

functions

and

reused.

The

various

BITBLT

are

parameters
described

and

with

operations
the

specified

MAKE-BITBLT

object

type

function.

BITBLT Accessor Functions
BITBLT-DESTINATION

BITBLT-DST-X

BITBLT-DST-Y

BITBLT-DST-W

BITBLT-DST-H

BITBLT-DST-OP

BITBLT-SOURCE

BITBLT-SRC-X

BITBLT-SRC-Y

BITBLT-SRC-W

BITBLT-SRC-H

BITBLT-SRC-0OP

BITBLT-TEXTURE

These

accessor

argument,
SETF

which

modify

MAKE-BITBLT

These

functions

functions
must

return
a

BITBLT

that

component

for

descriptions

are

package

the

indicated

argument.
their

They

argument.

these

LISP.

bitblt

Arguments

bitblt
An

object

type

BITBLT

Return Value

The

indicated

component

Corresponding MicroVMS Routines
None

the

See

components.

Format

LISP:BITBLT-xxx

component
can

BITBLT

object

also
the

used

their
with

description

GRAPHICS SYSTEM COMPONENTS
BITBLT-P Function

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

in package

This

LISP.

Format

LISP:BITBLT-P object
Arguments

object

Any LISP object
Return Value
T

NIL

Corresponding MicroVMS Routine
None

BITMAP-P Function

Returns T if its argument is a two-dimensional array of wunsigned
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
T

NIL

Corresponding MicroVMS Routine
None

GRAPHICS SYSTEM COMPONENTS
CIRCLE Function
Draws

circle

draw

full

arc

circle

arguments
are

specified.

draws

from

radian

start

arc

and

intersection of
For

virtual

unless

the

optional

these

start-radians
end

display.

Calls

arguments

are

measured

the circle and its horizontal

information

drawing

are

counterclockwise

positions

circles,

start-radians

see

this

and

function

end-radians

included,

CIRCLE

end-radians.

from

the

The

right-hand

diameter.
Section

3.5.2.

Format

UIS:CIRCLE

display att-block

&0OPTIONAL

start-radians

center-x

center-y

radius

end-radians

Arguments

display
A virtual

display

transformation

att-block
A

fixnum

which

the

graphics

range

0-255,

attributes

designating

will

attribute

block

from

taken

center-x center-y

Two single
of

the

floats designating,

circle

in world coordinates,

the

radius

center

arc

radius

A single

float designating the

world-coordinate

the

«circle

arc

units

start-radians

A single'float designating the starting position of the circle in
radians.

this

argument

NIL

omitted,

defaults

0.0.

end-radians
A

single

radians.

at
Return

2*PI.
Value

Undefined

float

designating

this

argument

the

end

NIL

position

omitted,

the

<circle

the

end

position

GRAPHICS SYSTEM COMPONENTS
Corresponding MicroVMS Routine
UISSCIRCLE

CIRCLE-PIXEL Function

Calls to this function draw a full

Draws a circle or arc in a window.

circle unless the optional start-radians and end-radians arguments are
If these arguments are included, CIRCLE-PIXEL draws an arc
specified.
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

att—block

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

center-x

from

center-y

Two fixnums designating, in device coordinates, the center of the
circle

arc

radius

fixnum

designating

device-coordinate units

the

radius

the

circle

arc

start-radians

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

A single £ 1A
radians.
at

2*PI.

nating the end position of the circle i n
gument is NIL or omitted, the end position 1is

GRAPHICS SYSTEM COMPONENTS

Return Value

Undefined
Corresponding MicroVMS Routine

UISDCSCIRCLE

COMPARE-BITMAPS Function
Returns

arguments

the

its

are

two

first

value

identical

arrays

return

values

bitmaps

are

not

give

varying

the

This

function

most

the

two

dimensions

identical,

compared

index

the

information

row-major

bitmap

and

the

that

given

and

function’s

about

order,

arrays

contents,

second

is,

with

the

its

otherwise.

and

differences.

quickly.

package

NIL

third
The

two

rightmost

LISP.

Format

LISP:COMPARE-BITMAPS

bitmapl

bitmap2

Arguments

bitmapl bitmap2
Two

bitmap

arrays

Return Value

Three values:
1.

the

contents,

two
and

bitmap
NIL

arrays

T if the two bitmap arrays
index

number

are

identical

the

row

differ

containing

dimensions,
the

first

otherwise
3.

The

index

number

the

bit
Corresponding MicroVMS Routine
None

dimensions

and

otherwise

column

containing

the

and

different

first

the
bit

different

GRAPHICS SYSTEM COMPONENTS
COPY-BITBLT Function

Creates and returns a new BITBLT object that has the same effect as
The new BITBLT object shares destination,
the function’s argument.
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 yl1 x2 y2 width height
Arguments
x1

corner

the

wvirtual

single floats specifying the upper right corner

the

wvirtual

single floats specifying the lower left

display’s world coordinate space
x2 y2

display’s world coordinate space

width

height
Single

floats

height

specifying,

the

wvirtual

centimeters,

display

when

keyboard.

See

device
Return

the
it

default

appears

width

the

and

output

Value

object

Corresponding

type

DISPLAY

MicroVMS

Routine

UISSCREATE _DISPLAY

Function
Creates

and

using

returns

virtual

Chapter

keyboards.

for

information

Format

UIS:CREATE-KB

&OPTIONAL

device

Arguments

device
A

character

keyboard

deyice
Return

string

defaults

specifying

the

created.

device

this

SYSSWORKSTATION.

which

argument

the

virtual

omitted,

the

Value

keyboard

Corresponding

MicroVMS

Routine

UISSCREATE
KB

CREATE-TERMINAL Function
Creates

its

device

terminal

name

emulation

string.

window

the

specified

type

and

returns

GRAPHICS SYSTEM COMPONENTS
Format

UIS:CREATE-TERMINAL

&KEY

:TYPE :BANNER-TITLE
: GENERAL-PLACEMENT :CENTER

- ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y
:NOBANNER

:NOBORDER

: NOMENU-ICON

:NOKB-ICON

:ALIGNED

Arguments
:TYPE

A character string indicating the terminal type. The string
be "WT", indicating a VT100, or "pK", indicating a TEK4014.

can

The

a VT100 terminal emulator window.
default 1s

:BANNER-TITLE

title.

A character string specifying the terminal emulator
default depends on the terminal emulator type.

The

: GENERAL-PLACEMENT

Fither :TOP, :BOTTOM, :LEFT,

:RIGHT,

indicating

general

preference for terminal emulator position on the screen; or a
list of two of these, for example (:TOP :RIGHT); oOr NIL,

indicating

preference for general placement.

The default 1is

NIL.

: CENTER

T or NIL.
position

If T, the terminal emulator will be

centered

If NIL, the emulator’s

lower-left

corner

specified

- ABSOLUTE-POSITION-Y.

:ABSOLUTE-POSITION-X

will be aligned on that position.

The default 1is NIL.

the

and

: ABSOLUTE-POSITION-X :ABSOLUTE-POSITION-Y

Two single floats indicating, 1in centimeters, the terminal
emulator’s displacement from the left and bottom edges of thed
display screen. The value provided with the :CENTER keywor
the placement
determines
values.
ITION
: ABSOLUTE-POS

of
By

the emulator
default, the

placed in an absolute screen location.

relative
emulator

to
1is

the

not

: NOBANNER

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

the

GRAPHICS SYSTEM COMPONENTS

: NOBORDER

NIL

(the

default),

terminal

emulator.

forced

disabling

enabling

:NOBORDER

border

specified,

around

the

:NOBANNER

:NOKB-ICON
T

NIL

should

(the

default),

should

right-hand

specifying

not

that

the

created without

corner

terminal

icon

emulator

the

upper

: NOMENU-ICON

NIL

should

(the

left-hand

default),

should

not

specifying

that

created without

corner

the

terminal

icon

emulator

the

upper

:ALIGNED

(the

left

default)

inner

boundaries

edge
in

NIL,

specifying

should

video

memory.

the

not

terminal

:ALIGNED T

optimizations.
Return

that

should

emulator’s

aligned

allows

byte

text

drawing

the

terminal

Value

character

emulator

string

that

the

device

name

window

Corresponding

MicroVMS

Routine

UISSCREATE _TERMINAL

CREATE-TRANSFORMATION Function
Creates

transformation

into

virtual

defined when
can

used

requires
See

virtual

place

virtual

Section

2.5

for

wvirtual

coordinate

display was
the

display

display”
and

transformation

display using

the
in

into

object.

display
as

allows

system

created.
argument

UIS:CREATE-TRANSFORMATION

vd-x1

other

for

any

using

vd-yl

transformations.

display

vd-x2

vd-y2

than

function

input.

information

returns

program

transformation

Format

&OPTIONAL

the

write

that

object
that

GRAPHICS SYSTEM COMPONENTS

Arguments

display

A display
x1

object

Four single floats designating two opposite corners
coordinate

vd-x1

vd-yl

the

new

space

vd-x2 vd-y2

Four single floats designating, in the display’s world coordinate
a rectangle that the new coordinate space will be mapped
system,
space
If these arguments are omitted, the new coordinate
onto.
is mapped onto the entire virtual display.

Return Value

An object of

type TRANSFORMATION

Corresponding MicroVMS Routine
UISSCREATE TRANSFORMATION

CREATE-UIS-STRUCTURE Function

a
Creates and returns the LISP representation for a virtual display,
created
been
has
that
n
transformatio
a
or
a virtual keyboard,
window,
You can use CALL-OUT to call a MicroVMS workstation
outside of LISP.
or a routine written in another language.
routine
software
graphics
or
transformation,
window,
Such a routine can create a display,
to you.
integer
identifying
the
return
and
keyboard,
virtual
CREATE-UIS-STRUCTURE takes this identifying integer and creates from
This allows you to use
representation of the object.
LISP
the
it
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
The exception is :WINDOW.
is the identifying integer for that object.
you must also specify :DISPLAY with the
If you specify :WINDOW,
identifying integer for the display that the window maps into.
NOTE

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

keep

list

created with
information
with

some

windows

that

map

CREATE-UIS-STRUCTURE
correctly.

They may

into

them.

cannot
behave

Objects

maintain

this

unpredictably

functions.

Format

UIS:CREATE-UIS-STRUCTURE
S&KEY

:WINDOW

:DISPLAY

:KEYBOARD

:TRANSFORMATION

Arguments
:WINDOW

integer

You must

that

also

use

the
the

wd_id

:DISPLAY

the

window you want

keyword when you

use

represent.

:WINDOW.

:DISPLAY

integer

that

the

vd_id

the

kb_id

tr_id of

the

display you want

represent

: KEYBOARD

integer

that

the

keyboard

vyou

want

transformation

vyou

want

represent
: TRANSFORMATION

integer

that

the

represent

Return Value

The LISP representation of the specified object
Corresponding

None

CREATE-WINDOW Function
Creates
on
more

the

window
physical

information

into

virtual

device,
about

and

display and

returns

windows.

the

corresponding

window.

See

Section

viewport
2.4

for

GRAPHICS SYSTEM COMPONENTS

Format

UIS:CREATE-WINDOW display
&OPTIONAL x1 yl1 x2 yZ
&§KEY :BANNER-TITLE :NOBANNER :NOBORDER
:NOKB-ICON :NOMENU-ICON :ALIGNED
cINVISIBLE :VIEWPORT-WIDTH :VIEWPORT-HEIGHT
:GENERAL-PLACEMENT

:CENTER

e ABSOLUTE-POSITION-X

:ABSOLUTE-POSITION-Y

:DEVICE

Arguments

display

A virtual display into which the window is to be opened
x1

x2 y2

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

A character string specifying a name to be inserted 1into the
TIf :NOBANNER T
border of the viewport; the default is no title.
is specified,

:BANNER-TITLE is ignored.

- NOBANNER

T or NIL (the default), disabling or enabling a banner above

the

viewport
: NOBORDER

T or NIL (the default), disabling or enabling a border around the
If :NOBORDER T is specified, :NOBANNER is forced to T.
viewport.
: NOKB-ICON

T or 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 Dbe
(See Chapter 6.)
associated with a virtual keyboard.
: NOMENU-ICON
9
should or
specifying that the viewport
T or NIL (the default),
left-hand
upper
the
in
icon
menu
not be creat e d without a
should
do

corner

GRAPHICS SYSTEM COMPONENTS

:ALIGNED

(the

default)

edge

should

memory.

NIL,

should

:ALIGNED

specifying

not

allows

that

aligned

text

the

drawing

viewport’s

byte

left

boundaries

inner

in video

optimizations.

:INVISIBLE

NIL

made

(the

default),

visible

"invisible"

viewport

MOVE-VIEWPORT

specifying

the
a

display

can

later

whether

device

moved

onto

the

viewport

when

the

should

created.

display

device

with

time.

:VIEWPORT-WIDTH

single

float

viewport

specifying

the

omitted,

viewport width

when

virtual

the

(in

display

centimeters)

device.

based

display was

the

this
width

width

argument

the

NIL

supplied

created.

:VIEWPORT-HEIGHT

single

float

viewport

specifying

the

omitted,

viewport

when

virtual

the

(in

display

height

centimeters)

device.

based

display was

the

this

the

height

argument

the

NIL

supplied

created.

: GENERAL-PLACEMENT

Either

:TOP,

:BOTTOM,

:LEFT,

preference

for

viewport

for

example

these,

preference

for

general

:RIGHT,

position

the

(:TOP:RIGHT);

placement.

The

indicating
screen;

NIL,

default

general

list

two

indicating

NIL.

:CENTER

NIL

(the

the

default)

position

1If

the

specified

:ABSOLUTE-POSITION-Y.

will

position.

aligned

:ABSOLUTE-POSITION-X

Two

single

the

values.
not

value

placement
If

placed

these
in

the

indicating,

from

The

the

NIL,

will

centered

:ABSOLUTE~-POSITION-X
viewport’s

lower-left

over

and
corner

:ABSOLUTE-POSITION-Y

floats

displacement
screen.

viewport

the

1left

provided

the

with

viewport

arguments
absolute

and

are

the

omitted

to
or

the

edges

:CENTER

relative

location.

centimeters,

bottom

keyword

viewport’s

the

display

determines

the ABSOLUTE-POSITION
NIL,

the

viewport

GRAPHICS SYSTEM COMPONENTS

+:DEVICE

viewport

A character string identifying the device on which the
The default is "SYSSWORKSTATION".
is to be created.
Return Value

A window object

Corresponding MicroVMS Routine
UISSCREATE_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 MicroVMS 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

'HICS SYSTEM

Return

COMPONENTS

Value

Undefined
Corresponding

Deletes
1s

not

MicroVMS

Routine

transformation

into
a

virtual

display.

The

virtual

display

affected.

Format

UIS:DELETE-TRANSFORMATION

transformation

Arguments

transf&xmatian
A

transformation

object

Undefined
Corresponding

MicroVMS

Routine

UISSDELETE_TRANSFORMATION

Function
Deletes

window

and

removes

associated

virtual

display

that

text

the

place

1its

viewport

not

affected.

window

are

closed.

Format

UIS:DELETE-WINDOW window
Arguments

A
Return

window

object

Value

Undefined

from

the

Any window

screen.

output

The

streams

GRAPHICS SYSTEM CO
Corresponding MicroVMS Routine
UISSDELETE_WINDOW

DISPLAY-LIST Function

Disables further additions to the display 1list for the specified
display until ENABLE-DISPLAY-LIST 1is 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
Arguments

display

A virtual

display

Return Value
Undefined

Corresponding MicroVMS Routine
UISSDISABLE_DISPLAY

rd.
Disconnects the physical keyboard from the specified virtual keyboa
s are
connections

Any

between

the

virtual

unaffected.
Format

UIS:DISABLE-KB keyboard
Arguments

keyboard
A keyboard

Return Value

Undefined

keyboard

and

window

GRAPHICS SYSTEM COMPONENTS

Corresponding

MicroVMS

Routine

UISSDISABLE_KB

DISABLE-VIEWPORT-KB Function
Disables

the

specified window

from being

assigned

keyboard.

Format

UIS:DISABLE-VIEWPORT-KB

window

Arguments
window

A window
Return

Value

Undefined
Corresponding

MicroVMS

Routine

UISSDISABLE_VIEWPORT_
KB

DISPLAY Type Specifier
Designates

objects

type

function.

DISPLAY,

created

the

CREATE-DISPLAY

DISPLAYP Function
Returns

1its

otherwise.

argument

Format

UIS:DISPLAYP

object

Arguments

object
Any

LISP

object

Return Value
T or

NIL

virtual

display

object

and

NIL

GRAPHICS SYSTEM COMPONENTS
Corresponding MicroVMS 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 MicroVMS Routine
None

DUMP-BITMAP Function

bitmap
a
of
contents
and
'a binary file containing the size
Writes
function.
LOAD-BITMAP
the
The file may later be retrieved with
array.
This

function

in package

LISP.

Format

LISP:DUMP-BITMAP bitmap pathname
Arguments

bitmap
A bitmap

array

pathname

A pathname,

string,

stream,

or symbol

Return Value

Undefined

ONENTS

Corresponding

None

Function
Draws

ellipse

this

function

and

end-radians

included,

measured

full

arqguments

ELLIPSE

horizontal

For

partial

draw

counterclockwise
are

from

ellipse

are

draws

virtual

the

optional

these

partial

ellipse

unless

display.

specified.

end-radians.
the

The

right-hand

radian

start-radians

arguments

from

start

intersection

Calls

and

end

the

are

start-radians

positions

ellipse

and

its

axis.

information

drawing

ellipses,

see

Section

3.5.2.

Format

UIS:ELLIPSE display att-block center-x center-y x-radius y-radius
&OPTIONAL start-radians end-radians
Arguments

display
A virtual

display

transformation

att-block
A

fixnum

which
center-x

Two
of

Two

the

range

0-255,

attributes

designating

will

attribute

block

from

taken

center-y

single
the

x-radius

graphics

floats

designating,

in world

designating,

coordinates,

the

center

ellipse

y-radius

single

floats

radius

respectively

the

wellipse

the

world

along

1its

coordinate

X-axis

and

system,

Y-axis,

start-radians

single

radians.

float
If

designating

this

argument

the
is

starting
NIL

postion

omitted,

the

ellipse

default

0.0.

end-radians

ellipse
the
A single float designating the end position of
2*PI.
1is
default
the
omitted,
is
argument
this
If
radians.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSELLIPSE

ELLIPSE-PIXEL Function

Calls to this
Draws an ellipse or a partial ellipse in a window.
function draw a full ellipse unless the optional start-radians and
If these arguments are included,
end-radians arguments are specified.
start-radians
from
ellipse
partial
a
draws
ELLIPSE-PIXEL
positions
end
and
start
radian
The
.
end-radians
to
kwise
countercloc
and its
ellipse
the
of
n
intersectio
right-hand
the
are measured from
horizontal

axis.

For more information on drawing ellipses, see Section 3.5.2.
Format

11IS:ELLIPSE-PIXEL window att-block center-x center-y
x~-radius y-radius

5§OPTIONAL start-radians end-radians

Arguments

window
A window

att-block

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

from

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
21

radius

GRAPHICS SYSTEM COMPONENTS

start-radians
A

single

float

radians.

designating

this

argument

the

starting

NIL

postion

omitted,

the

ellipse

default

0.0.

end-radians

A single float designating the end position
radians.

Return

this

argument

omitted,

the

default

ellipse

2+%PI.

Value

Undefined
Corresponding

MicroVMS

Routine

UISDCSELLIPSE

ENABLE-DISPLAY-LIST Function
Commences

display.
(See

also

Calls

resumes

additions

default,

the

virtual

device-coordinate

See

Section

the

display
3.1

for

list,
more

functions

even

information

Format

UIS:ENABLE-DISPLAY-LIST

display

Arguments

display

Return

list

for

display

DISABLE-DISPLAY-LIST.)

add

display

display’s

virtual

display

Value

Undefined
Corresponding

MicroVMS

Routine

UISSENABLE_DISPLAY
LIST

(whose
is

names

the

list

end

the

display

disabled.

-PIXEL)

enabled.

about

specified

list.

never

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

window

A window.
1If this argument is omitted, the virtual
keyboard
1is
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
UISSENABLE_KB

ENABLE-VIEWPORT-KB Function
Enables the specified window to be assigned a keyboard,
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

then

connects

Return Value

Undefined

C@rresgfinfiing MicroVMS Routine
UISSENABLE_VIEWPORT_KB

GMENT

Ends

the

The

wvalues

segment

they were
See

Function

recently

attributes

when

Section

most

the

3.7

segment

for

begun

all

was

attribute

begun.

information

the

specified
blocks

(See

about

also

are

virtual

display.

restored

what

BEGIN-SEGMENT.
)

segments.

Format

UIS:END-SEGMENT

display

Arguments

display

A virtual display
Return Value

Undefined
Corresponding

MicroVMS Routine

UISSEND_SEGMENT

ERASE

Function

Erases

The

virtual

display

completely
See

Section

display

1list

specified

wupdated

portion

removing

all

virtual

display.

primitives

that were

erased.
3.8

for

information

about

display.
Format

UIS:ERASE

display &OPTIONAL x1 yl1

x2 y2

erasing

virtual

COMPONENTS

Arguments

display

A virtual display or transformation
x1

x2 y2

two
Four single floats designating the world coordinates of
rectangle
the
within
Everything
opposite corners of a rectangle.

is erased.

display

1If these arguments are omitted,

the

entire

wvirtual

The

display

erased.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSERASE

ERASE-P IXEL Function

Erases a viewport or a specified portion of a viewport.
list is not affected by this operation.

See Section 3.8 for more information about erasing in a viewport.
Format

UIS:ERASE-PIXEL window &OPTIONAL x1 yl x2 y2
Arguments

window
A window

x2 y2

Four fixnums designating the device coordinates of

corners
erased.

two

opposite

Everything within the rectangle 1is
of a rectangle.
the entire window 1is
If these arguments are omitted,

erased.
Return Value

Undefined

GRAPHICS SYSTEM COMPONENTS

Corresponding

MicroVMS

Routine

UISDCSERASE

ERASE-VIEWING-AREA Function
Erases

the

viewing

area

about

window

information

window

output

stream.

See

Chapter

for

streams.

Format

UIS:ERASE-VIEWING-AREA

window-output-stream

Arguments

window-output-stream
A

window

output

stream

MAKE-WINDOW-OUTPUT~-STREAM

Return

previously

created

with

WITH-OUTPUT-TO-WINDOW

Value

Undefined

Corresponding MicroVMS Routine
None

GET-ABS-POINTER-POSITION Function
Returns

the

absolute

position

centimeters

relative

the

lower

the

pointer

left

corner

the

display

the

screen

screen.

Format

UIS:GET-ABS-POINTER-POSITION

&OPTIONAL

device

Arguments

device

A character string designating‘ the
information

defaults

1is

returned.

SYSSWORKSTATION.

device

for which pointer

omitted,

this

argument

GRAPHICS SYSTEM COMPONENTS

Return Value
Two

values:

A single float desianating the X position of the

pointer

1in

pointer

1in

centimeters

A single float designating the Y position of the
centimeters

Corresponding MicroVMS Routine
UISSGET_ABS_POINTER_POSITION

GET-ALIGNED-POSITION Function

display.
specified wvirtual
Returns the aligned text position for a
position.
aligned
the
of
description
a
for
ITION
See SET-ALIGNED-POS
Format

UIS:GET-ALIGNED-POSITION display att-block
Arguments

display

The virtual display

position is to be

for

transformation

which

the

aligned
v

returned.

att-block

from

A fixnum in the range 0-255, designating an attribute block

which a

font will be

taken

Return Value
Two

values:

single

float

designating

the

position

world

float

designating

the

position

world

coordinates

single

coordinates

Corresponding MicroVMS Routine
UISSGET_ALIGNED_POSITION

GRAPHICS SYSTEM COMPONENTS

GET-ALIGNED-POSITION-PIXEL Function
Returns

the

particular
a

single

mapped

aligned

virtual

window,

into

the

that

description

text

position

display.
aligned

window’s

the

for

Although
text

See

windows

argument

position

display.

aligned

all

the

mapped

this

same

for

into

function

all

windows

SET-ALIGNED-POSITION-PIXEL

for

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

which

the

font

range

will

0-255,

designating

attribute

block

from

taken

Return Value

Two

values:

A fixnum designating the Y position in device coordinates

fixnum designating

Corresponding MicroVMS

the

position

device

coordinates

Routine

UISDCSGET_ALIGNED_POSITION

GET-ATTRIBUTE Function
Returns

the

attribute
display

wvalue

block.

the

for

You

first

the

can

argument

window,

you

can

get

the

display

and

you

want

:LEFT-MARGIN-PIXEL,

display
The

value

modify

the

Section

attribute

SET-ATTRIBUTE

See

function

3.3

for

wvalue

get

the
one

any

attribute.

value

window

the

specified

window mapped

GET-ATTRIBUTE.

must

you
1If

into

you

mapped

supply

:CLIP-PIXEL
be

the

supply

into

or
the

fail.

GET-ATTRIBUTE
block

attribute

display

least

function will

returned

specified

supply

by using

modify

information

attribute

about

informational

SETF with

this
block.

attributes.

only;

you

function.

cannot
Use

the

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,

representing

associated with the display

attribute

Dblock

attribute

:BACKGROUND-INDEX,
:ARC-TYPE,
keywords
attribute
the
of
One
: FONT,
:FILL-PATTERN,
:CLIP-PIXEL,
:CLIP,
:CHARACTER-SPACING,
:LINE-WIDTH,
:LINE-STYLE,
:LEFT-MARGIN-PIXEL,
:LEFT-MARGIN,
c: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).

pairs,
For :FONT, the return value is a list of keyword-value
where
each
keyword is one of the font specification keywords
keywords
Only those
function.
displayed by the SHOW-FONTS
font are
default
the
of
those
from
differ
values
whose
included

the

1list.

the
of
For :LINE-STYLE, the return value is one
is
style
1line
the
if
keywords
specification

style
1line
of the
one

32
1length
of
wvector
DIGITAL-supplied line styles, or a bit
(See Section 3.5.3.3.)
specifying a nonstandard line style.

number
floating-point
For :LINE-WIDTH, the return value is a
coordinate
world
in
width
1line
specified
you have
unless
form
the
of
units, in which case the return value is a list
number.
'(n :WORLD-COORDINATES), where n is a floating-point

Corresponding MicroVMS Routines

Attribute

Routine

cARC-TYPE
:BACKGROUND-INDEX
cCHARACTER-SPACING
:CLIP

UISSGET_ARC_TYPE
UISSGET_ BACKGROUND_INDEX
UISSGET_CHAR_SPACING
UISSGET _CLIP

GRAPHICS SYSTEM COMPONENTS

Attribute

Routine

:CLIP-PIXEL

UISDCSGET_CLIP

:FILL-PATTERN

UISSGET_FILL_PATTERN

: FONT

UISSGET_FONT

: LEFT-MARGIN

UISSGET_LEFT_ MARGIN

:LEFT-MARGIN-PIXEL

UISDCSGET_LEFT MARGIN

:LINE-STYLE

UISSGET _LINE_STYLE

:LINE-WIDTH

UISSGET _LINE WIDTH

:WRITING-INDEX

UISSGET WRITING_ INDEX

:WRITING-MODE

UISSGET _WRITING_MODE

GET-ATTRIBUTE-LIST Function
Returns

property

specified
mapped
If

into

vyou

list

attribute
the

display

supply

attributes.

all

attributes

See

Section

window,

you

supply

for

the

can

first

the

attributes

You

the

except

3.3

all

block.

argument

1list

display,

:CLIP-PIXEL

information

and

supply

their

a
to

includes

the

list

values

display

for

a window

GET-ATTRIBUTE-LIST.
the

wvalues

includes

the

all

values

:LEFT-MARGIN-PIXEL.

about

attributes.

Format

UIS:GET-ATTRIBUTE-LIST

display-or-window att-block

Arguments

display-or-window
A virtual

display

a window

att-block

fixnum

the

associated with

range

the

0-255,

representing

attribute

display

Return Value

A list

the

form

(attrl

valuel

Corresponding MicroVMS Routine
None

attr2

value2

...)

block

GRAPHICS SYSTEM COMPONENTS
GET-BUTTONS Function

Returns two values representing the state of the pointer buttons. The
first wvalue 1is an integer that encodes the actual button statej the
second indicates whether the pointer cursor was visible in the window

you

supply as an argument.

The integer returned

encodes

GET-BUTTONS

the

button

state

follows:

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:

(#. (LOGAND
POINTER-BUTTON-1

POINTER-BUTTON-2)

example

This

shows

how

you

=Wy

)

...

(4# .POINTER-BUTTON-2

(CASE (GET-BUTTONS WINDOW)
(# .POINTER-BUTTON-1 ... )

...

Ignore second return value

Only button 1 down
Only button 2 down

)) ; Buttons 1 and 2 down

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:

An integer that encodes the button state as described above

T or NIL, indicating whether or not the pointer cursor is
window

Corresponding MicroVMS Routine
UISSGET_BUTTONS

1in

GRAPHICS SYSTEM COMPONENTS
GET-COLOR Function
Returns

for

entry

Section

multiple

3.4

for

values

the

(red),

(green),

color

map associated with
information about color.

and

virtual

(blue)

values

display.

See

Format

UIS:GET-COLOR

display

color-id

&OPTIONAL

window

Arguments

display
A virtual

display

color-id
An

integer

specifying

entry

the

color

map

associated

with

display

window
A window.

the
was
Return

this

realized

argument

colors

for

the

supplied,

specific

the

device

return

are

the window

created.

Value

Three

values:

The

red

The

blue

The

green

value

Each

return

1.0,

inclusive.

value

Corresponding MicroVMS

floating-point

number

the

Routine

UISSGET_COLOR

GET-DISPLAY-SIZE Function
Returns

values

on which

the

size

and

resolution

the

display

Format

UIS:GET-DISPLAY-SIZE

&OPTIONAL

device

screen.

range

0.0

GRAPHICS SYSTEM COMPONENTS

Arguments

device

A string specifying the device for which
returned.

The default is SYSSWORKSTATION.

information

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 giving the horizontal resolution of the screen

in pixels/centimeter

A single float giving the vertical resolution of

the

screen

'in pixels/centimeter

A fixnum giving the width of the screeh in pixels

A fixnum giving the height of the screen in pixels

UISSGE

-3

Corresponding MicroVMS Routine
DISPLAY_SIZE

GET-FONT-SIZE Function

Returns the height and width of a text string
specified

centimeters

for

font.

Format

UIS:GET-FONT-SIZE font-id text-string
Arguments

font-id

A pathname, string, stream, or symbol specifying a font file; or,
(See the
a list of keyword-value pairs specifying a font.

description of the SET-ATTRIBUTE function, :FONT
an explanation of this list.)

text-string

A string to be measured

attribute,

for

GRAPHICS SYSTEM COMPONENTS

Return Value

Two

values:

single

in
2.

float

designating

the

width

designating

the

height

the

character

string

centimeters
single

float

the

character

value

for

string

centimeters

Corresponding

MicroVMS

Routine

UISSGET_FONT_SIZE

GET-INTENSITY Function
Returns

color

the

map

information

equivalent

monochrome

associated

with

about

maps.

color

intensity

virtual

display.

See

&OPTIONAL

window

entry

Section

the

3.4

for

Format

UIS:GET-INTENSITY

display

color-id

Arguments

display
A virtual

display

color-id
An

integer

specifying

entry

the

color

map

associated

with

display
window
A window.

realized
was

this

intensity

argument

for

the

specified,

the

specific

device

range

return

value

on which

the

created.

Return Value

floating-point

number

the

Corresponding MicroVMS Routine

UISSGET_INTENSITY

0.0

1.0,

inclusive

the

window

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

the

keyboard

attribute

description of SET-KB-ATTRIBUTES

keywords

1listed

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 wvalue of each
This list is informational
attribute for the specified keyboard.
only; you cannot modify a virtual keyboard by using SETF with this
Use the SET-KB-ATTRIBUTES function to modify a virtual
function.
keyboard.

See Section 6.1.4 for information about keyboard attribues.
Format

UIS:GET-KB-ATTRIBUTE-LIST keyboard
Arguments

keyboard

A keyboard

GRAPHICS SYSTEM COMPONENTS

Return

Value

list

keyword-value

keyboard

attribute

SET-KB-ATTRIBUTES,

Corresponding

MicroVMS

and

pairs,

where

the

keywords

1listed

the

value

its

keyword
in

the

value

one

the

description

for

this

keyboard

Routine

UISSGET_
KB _ATTRIBUTES

GET-POINTER-POSITION

Function

Returns the world coordinate position of the pointer cursor,
the

pointer

cursor

not

the

visible

portion

the

or NIL if

viewport.

Format

UIS:GET-POINTER-POSITION

display

window

Arguments

display
A virtual

must

display,

the

specifying
mapped

one
this

into

than

display.
display.

the

return

world

window
A

that

interpret

rather

transformation,

into which

NIL.

transformation
Specifying

values

The

mapped;

virtual

NIL

must

is
be

display

equivalent

one

that

1is

allows

you

transformation

coordinates

coordinates.

window
A window

Return Value
Two

values:

single

float

designating

cursor

1n world

pointer

cursor

single

cursor

float

the

transformation

not

the

designating

world

Corresponding MicroVMS

UISSGET_POINTER_POSITION

of the

coordinates,

NIL

pointer

the

viewport

the

transformation

Routine

position

position
coordinates

the

pointer

GRAPHICS SYSTEM COMPONENTS
GET-POINTER-POSITION-PIXEL Function
Returns the device-coordinate position of the pointer cursor,

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:

A fixnum designating the X position of the pointer cursor 1in
or NIL if the pointer cursor is not in
device coordinates,
the

viewport

Y position of the pointer cursor
A fixnum designating the
device

1in

coordinates

Corresponding MicroVMS Routine
UISDCSGET_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.

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

single

float

representing

world-coordinate

single

text

float

representing

world-coordinate
Corresponding MicroVMS

the

portion

the

portion

the

position

text

position

Routine

UISSGET POSITION

GET-POSITION-PIXEL Function
Returns

into

the

current

wvirtual

independent
into
See

virtual

Section

device-coordinate

display.

the

The

display

3.6.2.1

text

for

the

text

position

for

device-coordinate

position;
same

information

however,

windows

text

all

windows

device-coordinate

about

the

mapped

position

text

mapped

position.

device-coordinate

position.

text

Format

UIS:GET-POSITION-PIXEL window

Arguments
window
The
Return

window

for

which

the

text

position

returned

Value

Two

values:

fixnum

text

fixnum

text

representing

the

portion

the

device-coordinate
|

the

Y portion

the

device-coordinate

position

representing

position

Corresponding MicroVMS

Routine

UISDCSGET_POSITION

GET-VIEWPORT-POSITION Function
Returns

relation

the

position

the

lower-left

corner

centimeters.

corner

the

display

physical

viewport

display,

GRAPHICS SYSTEM COMPONENTS

Format

UIS:GET-VIEWPORT-POSITION window
Arguments

window

The window associated with the viewport whose position is

Dbe

returned

Return Value

Multiple values:

A single float representing the X position of the viewport 1in

A single float representing the Y position of the viewport in

centimeters

Corresponding MicroVMS Routine
UISSGET_VIEWPORT_POSITION

GET-VIEWPORT-SIZE Function

Returns the width and height of a display viewport in centimeters.
Format

UIS:GET-VIEWPORT-SIZE window
Arguments

window

The window associated with the

viewport

whose

size

1is

returned

Return Value

Multiple values:

A single float representing the width of the viewport

A single float representing the height of the viewport

GRAPHICS SYSTEM

Corresponding

MicroVMS

COMPONENTS

Routine

UISSGET_VIEWPORT_SIZE

GET-VISIBILITY Function
Returns
1s

entire

wunoccluded

occluded.

checked

then

given,

for

that

viewport

other

the

falls

single

the

they

NIL

given,

the

portion
any

two

then

checked.

pair
If

GET-VISIBILITY

viewport

world-coordinate
is

thereof

part

entire

world-coordinate

define

window,

specified

and

are

checked.

rectangle

outside

all

arguments

wvisibility.

point

viewports,

optional

single

then

rectangle

1is

given,

pairs

the

are

point

returns

NIL.

Format

UIS:GET-VISIBILITY

display

window

&OPTIONAL

Arguments

display
A virtual
must

display,

the

specifying

one

transformation,

into

this

which

display.

mapped

into

transformation

use

that

display.

window
A

or
is

NIL.

The

mapped;

transformation

Specifying

coordinates

virtual

NIL

must

is
be

one

that

allows

you

transformation

instead
of

world

display

equivalent

coordinates.

window

The window whose associated viewpor
(or
t portion thereof)
x1

checked

Two

single

floats

defining

coordinate

space;

this

visibility.

vyl

arguments

for

are

point

checked

world

for

transformation

visibility

given

y2
Two

single

floats

transformation
points

defining

coordinate

checked

for

another

space;

visibility

Return Value
T

NIL

the

point

rectangle

defined

world

the

two

GRAPHICS SYSTEM COMPONENTS
Corresponding MicroVMS Routine
UISSGET_VISIBILITY

GET-VISIBILITY-PIXEL Function

Returns T if an entire viewport or all of a specified portion thereof
is unoccluded by other wviewports, and NIL 1f any part of it 1s
occluded. If no optional arguments are given, the entire viewport 1is
checked for visibility. If a single device-coordinate pair 1s given,
then that single point is checked. 1If 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 yl X2 y2y

Arguments
window

The window whose associated viewport (or portion thereof)

1is

be checked for visibility.

Two fixnums defining a pixel in the window; this pixel is checked
for visibility if no more arguments are given

Two fixnums defining another pixel in the window;

defined by the two points is checked for visibility

the

rectangle

Return Value
T

NIL

Corresponding MicroVMS Routine
UISDCSGET_VISIBILITY

W-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 us.ing

SETF with this function. Each of these attributes is
the call to CREATE-WINDOW that creates the viewport.
41

established by
The attributes,

GRAPHICS SYSTEM COMPONENTS

and

the

values

:NOBANNER

of
T

indicates

:NOBORDER

that

indicates

:NOKB-ICON

icon

the

1indicates

indicates
indicates

banner;

icon.

viewport

that

NIL

not

the

banner;

NIL

has

border;

NIL

icon

its

border.

the

viewport

has

the viewport has a
the viewport cannot
that

the

has

banner.

viewport

that
cannot

keyboard

that

boundaries
1s

has

viewport

indicates

virtual

indicates

byte

that

A viewport

have

the

that

viewport

still

:ALIGNED

viewport

its

keyboard
can

that

NIL

the

are:

that

indicates

banner;

meanings,

1indicates

:NOMENU-ICON

their

keyboard

the viewport can acquire a
acquire
a
keyboard
icon

associated

viewport’s

video

menu icon.
acquire a

left

memory;

with

it.

inner

edge

NIL

indicates

aligned

that

the

aligned.

Format

UIS:GET-WINDOW-ATTRIBUTE-LIST

window

Arguments

window
A window
Return Value

disembodied

Corresponding

property

MicroVMS

list

Routine

UISSGET_WINDOW_ATTRIBUTES

GET-WS-COLOR Function

Returns as multiple values the R (red), G (green),
and B

(blue) values

for

effect

time

the

See

specified workstation
virtual

Section

3.4

display was
for

standard

color

that

was

created.

information

about

color.

Format

UIS:GET-WS-COLOR

display

color-id

Arguments

display
A virtual

display

&OPTIONAL

window

the

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

If this argument is specified, the return values are
A window.
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,

0.0

inclusive.

Corresponding MicroVMS Routine
UISSGET_WS_COLOR

GET-WS-INTENSITY Function

Returns the equivalent monochrome intensity value for a specified
workstation standard color that was in effect at the time the virtual
See Section 3.4 for information about color.
display was created.

‘

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

color

GRAPHICS SYSTEM

COMPONENTS

window
A window.

realized

was
Return

this

argument

1intensity

for

the

specified,

specific

the

device

return

for

value

which

the

window

created.

Value

floating-point

number

the

range

0.0

1.0,

inclusive

Corresponding MicroVMS Routine
UISSGET _WS_INTENSITY

IMAGE

Function

Writes

list
The

bitmap

enabled,
is

IMAGE

the

size
to

the

of
in

fit

size

rectangle
largest

the

horizontal

clipped

different
clipped

See

and

factors

Chapter

one

dimension

for

bitmap

the

display

larger
bitmap

than
is

smaller
the

that

rectangle

the

excess

will

display

<corresponding
at

the

top

and

not

horizontal
and

information

exact

top

display att-block

the

bitmaps

bitmap x1

display
display

and

corresponding

scaled
fit

within

integer

the
the

multiple

right

bitmap

are

That is, a bitmap may be
and vertical dimensions,

scaled
in

about

still
an

the

the
is

the

dimensions

other.

than

bitmap

unchanged.

Arguments

A virtual

the

list.

clipped

scaled

scaled
or may

other.

and

screen

Format

UIS:IMAGE

follows:

multiple

each

the

display.

the

left

viewport,

vertical

independent

virtual

bitmap
to

bitmap

the

bitmap,

rectangle.

a
If

the

viewport,

the
of

viewports

the

integral

rectangle
The

rectangle.

~of

adds

displayed

rectangle
right

rectangle

x2 y2

images.

by
be

GRAPHICS SYSTEM COMPONENTS
att-block

A fixnum in the

range

associated with display

designating

0-255,

attribute

block

bitmap

An array of unsigned bytes
x1

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 MicroVMS Routine
UISSIMAGE

IMAGE-PIXEL Function

Writes a bitmap to a viewport.

See Chapter 4

for

information

about

attribute

block

screen images and bitmaps.

Format

UIS:IMAGE-PIXEL window att-block bitmap x y

Arguments

window
A window

att-block

A fixnum in the

range

0-255,

associated with window’s display

designating

bitmap

An array of unsigned bytes

Two fixnums specifying, in device coordinates, the 1lower left
corner of the rectangle in which the image is to be placed. The
N
i i~

size of the bitmap determines the size of the rectangle.
45

GRAPHICS SYSTEM

Return

COMPONENTS

Value

Undefined
Corresponding

MicroVMS

Routine

UISDCSIMAGE

KEYBOARD Type Specifier
Designates

objects

type

KEYBOARD,

created

the

function.

CREATE-KB

KEYBOARDP Function
Returns

its

argument

keyboard

and

NIL

otherwise.

Format

UIS:KEYBOARDP

object

Arguments
object
A

LISP

Return

object

Value

NIL

Corresponding

MicroVMS

Routine

None

K-TRM-xxx Constants
These

the
value

constants

function,
of

function
values.

have

integer

values, each of which represents
one
of
keypad,
editing,
or arrow keys.
The return

numeric

READ-KB-CHAR

established
Note

that

all

and

the

first

with
of

argument

passed

SET-KB-ACTION
can be
these constants are in a

interrupt

compared with these
package called SMG.

GRAPHICS SYSTEM COMPONENTS
Constant

Key

Numeric Keypad Keys

keypad
keypad
keypad
keypad
keypad

0
1
2
3
4
5
6
7
8
9
|,
.
Enter
PF1
PF2
PF3

keypad
keypad
keypad PF4

F15
F16

F17
F18
F19
F20

SMG:K-TRM-PF4

‘

Function,

F6
F7
F8
F9
F10
F11
F12
F13
Fl4

SMG:K-TRM-KPO
SMG:K-TRM-KP1
SMG:K-TRM-KP2
SMG:K-TRM-KP3
SMG: K-TRM-KP4
SMG:K-TRM-KP5
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

Help,

and Do Keys

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
SMG:K-TRM-F13
SMG:K-TRM-F14

SMG:K-TRM-HELP
SMG : K- TRM-DO

(Help)
(Do)

SMG:K-TRM-F17
SMG:K-TRM-F18
SMG:K-TRM-F19
SMG:K-TRM-F20

Editing and Arrow Keys

(Find)

SMG : K-TRM-FIND

Up Arrow
Down Arrow
Right Arrow
Left Arrow

SMG:K-TRM-UP
SMG: K-TRM~-DOWN
SMG:K-TRM-RIGHT
SMG:K-TRM-LEFT

E2 (Insert Here)
E3 (Remove)
E4 (Select)
E5 (Prev Screen)
E6 (Next Screen)

SMG:K-TRM-INSERT-HERE
SMG : K-TRM-REMOVE
SMG:K-TRM-SELECT
SMG:K-TRM-PREV-SCREEN
SMG:K-TRM-NEXT-SCREEN

GRAPHICS SYSTEM

LIST-ALL-DIS PLAYS

Function

Returns

all

have

not

list

user-created

COMPONENTS

displays

and

transformations

that

been deleted.

Format

UIS:LIST-ALL-DISPLAYS
Arguments

None

Return Valu@
A

list

Corresponding

MicroVMS

Routine

None

Returns

list

Function

all

user-created

windows

that

have

not

been

deleted.

Format

UIS:LIST-ALL-WINDOWS

Aygumenfis
None

Return v&lu@
A

list

Corresponding

None

Returns

bitmap

the

DUMP-BITMAP

This

function

array

read

from a

file

function.

package

LISP.

that was

previously written

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

Dbeen

Return Value
A bitmap

array

Corresponding MicroVMS Routine
None

BLT Function

When wused as an
Creates and returns an object of type BITBLT.
causes a specific
object
BITBLT
a
argument to the BITBLT function,
object has
BITBLT
A
operation to be performed on a specific bitmap.
the

following

components:

@ A destination bitmap,
operation is applied.

that 1is,

the bitmap to which thé

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
The source bitmap can be an entire bitmap
destination bitmap.
array or can extend upward and to the right from a specified
The source bitmap is not altered by
in a bitmap array.
pixel
BITBLT, unless it happens to overlap with the destination
bitmap.

A texture bitmap. The texture bitmap is combined with the
to the
source bitmap before the source bitmap is applied

It is constrained to be a bitmap array
destination bitmap.
A texture
that is up to 32 bits wide; it can have any height.
The
fit.
to
right
the
bitmap wider than 32 bits is trimmed on
texture bitmap itself is not altered by BITBLT.

These specify how the
Source and destination operations.
texture bitmap is combined with the source bitmap, and the
respectively.
texture-source result with the destination,
with
specified
be
can
that
operations
the
of
any
They can be
DMMT

i LW AW

W} oF gy

GRAPHICS SYSTEM

The

operation

BITBLT

described

function

The

For

the

must

each

BITBLT

object

have

pixel

and

the

first

argument.

the

around

texture

Dbitmap.
bitmap

result

combined

pixel

has

the

operation,

The

the
with

texture

combining

destination

(DO

((dj

(DO

assuming

dst-y

(sj
((=

and

the

limits

1is

located

and/or

wupper

effect

the
the

(1+

((=
(SETF

src-x

(AREF

(BOOLE

pixel

heights

di))

(1+

si)))

dst-x

See

Section

4.6

the

bitmap.

and

texture

pixel

pixels

according

source-texture
destination

destination

the
is

source-texture
used

modify

and

result

the

for

is
the

as
the

following

algorithm

widths

the

are

same):

di)

src-op

(AREF

source

(AREF

filled-texture

si)

(REM

texture-height)

(REM

32)))

destination

di)))))

LISP.

information

using

this

with

destination

dst-op

package

result

pixel

dst-w)))

(AREF

function

the

dst-h)))

(1+

(BOOLE

This

sj)))

dst-y

((di dst-x

(s1

edge

replicating

(1+ dj))

src-y

second

A BITBLT operation is described by the
bounds,

pixel

the

pixel

source

with

exceed

source

and

pixel

bitmap

source

texture
the

the

combined

texture
the

pixel.

array

evaluated.

argument.

result

the

destination

argument

are

type.

coordinates

left

the

first

the

combining

with

the

bitmap:

operation,

This

across

bitmaps

same

pixel

the

destination
second

the

with

in the source bitmap is

and

bitmap,

wrapping

The

source

argument

texture

the

destination

corresponding

according

texture

elements

The corresponding pixel

combination
|

source,

all

with

following:

destination,

They

COMPONENTS

function.

(ignoring

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

given,

If none of the next four arguments are
A bitmap array.
the entire array is used as the target of the operation.
:DST-X

:DST-Y

(not the device
Two integers specifying the array reference
The
a pixel in the destination bitmap.
of
coordinates)
to
and
destination rectangle of the operation extends downward
If these arguments are NIL or omitted
the right from this point.
(the wupper-left corner of the destination
they default to 0
bitmap).
:DST-W

:DST-H

Two integers specifying the width and height of the destination
If these arguments are NIL or omitted, they
rectangle in pixels.
default to the full width and height of the destination bitmap,

minus the values given with

:DST-X and

:DST-Y.

:DST-0OP

Any of the operations that can be specified with the BOOLE
The
The Language).
(see Section 12.7 of COMMON LISP:
function
1is
bitmap
source
the
operation specifies how each pixel 1in
bitmap.
combined with the corresponding pixel in the destination
The following constants are particularly useful with :DST-OP:
@
@

BOOLE-1 - replaces the destination with the source
BOOLE-IOR - "paints" the destination with the source

destination

any

inverts

pixel

that

1is

also

BOOLE-XOR

BOOLE-ANDC1 - erases any destination pixel that corresponds to

occupied by a source pixel
an illuminated pixel

in the source

If this arqument is NIL or
BOOLE-1.

omitted,

the

default

operation

is
|

: SOURCE

(that 1is,
Its elements must have the same type
A bitmap array.
N bitmap.
:DESTINATIO
the
of
number of bits per element) as those
51

GRAPHICS SYSTEM

this

argument

destination
:SRC-X

1is

NIL

COMPONENTS

omitted,

defaults

bitmap.

the

:SRC-Y

Two

integers

specifying

the

coordinates)

rectangle

the

operation

point.

from

this

default
:SRC-W

for

(the

pixel

array

reference

the

source

extends

these

upper-left

downward

arguments

corner

and

are

the

(not

the

bitmap.

source

the

right

omitted

they

NIL

source

device

The

bitmap).

:SRC-H

Two

integers

specifying

rectangle

pixels.

default

the

full

minus

the

values

the
If

width

given

width

these

and

with

and

arguments

height

:SRC-X

height

are

the

and

NIL

the

source

omitted

destination

they

bitmap,

:SRC-Y.

:SRC-0P

Any

the

operations

function

(see

operation

specifies

combined

with

following

the

can

12.7

how

each

are

specified

COMMON LISP:
pixel

corresponding

operations

BOOLE-1

that

Section

pixel

the

particularly

the

BOOLE-2

the

texture

ignores

the

source

bitmap

source

and

texture

that

are

BOOLE-AND

setting

with

ignores

and

merges

pixels

the

NIL

result

texture

this

argument

omitted,

defaults

bitmap.

the

The

both

source

the

texture

bitmaps

The

:SRC-OP:

wuses

set

BOOLE

bitmap

uses

and

bitmap

and

source

bitmap

the

Language).

texture

useful

bitmap

with

The

the

only

source

BOOLE-1.

: TEXTURE

bitmap

number
If

the

array.
of

Its

bits

per

specified

elements
element)

:TEXTURE

replicated

horizontally

the

bitmap

wider

fill

out

bits,

fit.
The

graphics

: TEXTURE.
use

SETF

system

the

effective

not

you

copies

Therefore,
a

the

you

BITBLT-TEXTURE

particular

specify

have

those

bitmap

than

must
as

BITBLT

texture

the

same

the

narrower

bitmap

later

than

rectangle

trimmed

array

modify

function

type

(that

:DESTINATION
32

1is,

bitmap.

bits,

bits

wide.

the

right

you

this

specify

array,

make

with

you must

that

change

object.

bitmap,

defaults

all

1s.

GRAPHICS SYSTEM COMPONENTS

Return Value

object

type

BITBLT

Corresponding MicroVMS Routine
None

MAKE-BITMAP Function

specified
the
Creates and returns a two-dimensional array of
of
length
The
byte.
dimensions, each of whose elements is an unsigned
which
,
each unsigned byte is given by the bits-per-pixel argument
defaults to 1.

(MAKE-ARRAY

This function has the same effect as:
(LIST height width)

:ELEMENT-TYPE TM (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

height

the

requested

in pixels

bits-per-pixel

If
An integer specifying how many bits represent each pixel.
each
nt
represe
to
used
1is
this argument is omitted, one Dbit
This argument is currently limited to 1.

pixel.

space

Either :DYNAMIC (the default) or :STATIC, indicating in which
(See the description of
space the array should be created.

MAKE-ARRAY in the VAX LISP/VMS User’s Guide.)
Return Value

An array of unsigned bytes
1

& & Pt obm

GRAPHICS SYSTEM COMPONENTS

Corresponding

MicroVMS

Routine

None

MAKE-WINDOW-OUTPUT-STREAM
Creates

stream

can

See

window

output

used

for

Chapter

Function

stream

and

argument

information

returns

about

COMMON

window

the

stream

object.

LISP

output

functions.

output

The

streams.

Format

UIS:MAKE-WINDOW-OUTPUT-STREAM
&KEY

:ATTRIBUTE-BLOCK

window

:VIEWING-AREA

:HORIZONTAL~-OVERFLOW

:VERTICAL-OVERFLOW

Arguments

window
A window

: ATTRIBUTE-BLOCK
A

fixnum designating

output

operations;

attribute

block

the

attribute

the

default

can

block
1is

changed

WINDOW-STREAM-ATTRIBUTE-BLOCK

attribute

later

used

for

all

block

The

using

the

function.

:VIEWING-AREA

A list of four integers in the form (x1 y1 x2 y2) that
the

lower-left

which

text

written

changed

and

wupper-right

written.

into

later

the

this

entire

by using

the

corners

argument

window.

NIL

The

specifies

rectangle within
or omitted,
text

viewing

WINDOW-STREAM-VIEWING-AREA

area

can

function.

: HORIZONTAL-OVERFLOW

Either

:WRAP,

the

right

the

line,

default,

margin.

changed
later
function.

indicating

:TRUNCATE,
The

horizontal

wusing

the

default,

that

indicating

the

text

that

text

overflow

wrapped

onto

truncated

behavior

can

WINDOW-STREAM-HORIZONTAL-OVERFLOW

:VERTICAL-OVERFLOW

upwards
:WRAP,

€

accomodate

indicating

that

new

indicating

text

the

that

bottom

text

the

vertically wrapped;

scrolled

viewing
or

area;

:TRUNCATE,

GRAPHICS SYSTEM COMPONENTS

indicating that text below the bottom of the viewing area be
The vertical
discarded until the viewing area 1is erased.
using the
by
later
changed
be
can
behavior
overflow

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

coordinate

system of a virtual display.

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:

A single float designating the width of the

text

string

1in

A single float designating the height of the text

string

1in

world

coordinates

world coordinates

Corresponding MicroVMS Routine
UISSMEASURE_TEXT

GRAPHICS SYSTEM

COMPONENTS

MEASURE-TEXT-PIXEL Function
Returns

the

width

and

height

text

string

units.

device-coordinate

Format

UIS:MEASURE-TEXT-PIXEL window att?block text-string
Arguments

window
A window

att-block

fixnum

which

font

the

and

range

0-255,

designating an
spacing attributes

character

attribute block
will be taken

from

text-string
A
Return

character

string

measured

Value

Two

values:

fixnum

designating

device-coordinate
2.

fixnum

designating

device-coordinate
Corresponding

MicroVMS

the

width

the

text

string

height

the

text

string

units
the

units

Routine

UISDCSMEASURE_TEXT

MOVE-AREA Function
Shifts

display.
See

portion
The

Section

display

3.8

for

virtual

display

from

list

updated

information

about

one

place

reflect

moving

the

portions

display.
Format

UIS:MOVE-AREA display

dest-x

dest-y

another

the

alteration.
of

virtual

GRAPHICS SYSTEM COMPONENTS

Arguments

display

A virtual display or transformation
x1

x2 y2

Four single floats

designating

opposite corners of a rectangle
dest-x

the

world

coordinates

two

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 MicroVMS Routine
UISSMOVE_AREA

MOVE-»AREA—PXEL Function

shifts a rectangle in a viewport to another

place

the

viewport.

The display list is not affected.

See Section 3,8 for information about moving portions of a viewport.
Format

UIS:MOVE—AREA~PIXEL window x1 y1 x2 y2 dest-x dest-y
Arguments

window
A window

x1l

x2 y2

Four fixnums designating the device coordinates of
corners of a

rectangle

two

opposite

GRAPHICS SYSTEM

dest-x

dest-y

Two

fixnums

corner

designating

the

rectangle
Return

COMPONENTS

the

destination
taken

from

device

coordinates

rectangle.

the

size

The
the

size

the

lower-left

the

destination

source

rectangle.

Value

Undefined
Corresponding

MicroVMS

Routine

UISDCSMOVE_AREA

MOVE-VIEWPORT Function
Moves

display

viewport

the

physical

display.

Format

UIS:MOVE-VIEWPORT
&KEY

window

:GENERAL-PLACEMENT

:CENTER

:ABSOLUTE-POSITION-X

:ABSOLUTE-POSITION-Y

:INVISIBLE
Arguments

window
The

window whose

associated

viewport

moved

:GENERAL-PLACEMENT

Either

:TOP

:BOTTOM,

preference

these,

for

preference

:LEFT,

viewport

example

for

viewport

:RIGHT,

position

the

(:TOP

:RIGHT);
placement

indicating
screen;

NIL,

general

list

two

indicating

:CENTER

NIL

(the

the

default)

position

the

specified

:ABSOLUTE-POSITION-Y.

will

position.

aligned

:ABSOLUTE-POSITION-X

Two

single

the

The

from
value

placement

the

NIL,

the

will

centered

over

:ABSOLUTE-POSITION-X
viewport’s

lower

1left

corner

:ABSOLUTE-POSITION-Y

floats

displacement
screen.

viewport

indicating,

the

1left

centimeters,

and

provided with

the viewport

the

bottom
:CENTER

relative

the

edges

viewport'’s

keyword

the

display

determines

the ABSOLUTE-POSITION

GRAPHICS SYSTEM COMPONENTS

values.
+INVISIBLE

Either T or NIL

(the default).

location off

screen;

the

If T,

it becomes

the viewport is moved to

invisible.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSMOVE_VIEWPORT

MOVE-WINDOW Function

Moves a window within a
size
<change
to
window
information about using

optionally allowing the
display,
wvirtual
See Section 2.4.3 for
aspect ratio.
and/or
this

function.

Format

UIS:MOVE-WINDOW display window x1 yl x2 yZ2
Arguments

display

display
virtual
The
A virtual display, transformation, or NIL.
must be the one into which window is mapped; NIL is equivalent to
1is
that
one
A transformation must be
specifying this display.
Specifying a transformation allows you
mapped into that display.
to use transformation coordinates instead of world coordinates.
window

A window object
x1

x2 y2

single
Four
coordinates)

transformation
(in world or
specifying
floats
of the new
corners
upper-right
and
lower-left
the

window

Return Value
Undefined

GRAPHICS SYSTEM COMPONENTS

Corresponding MicroVMS Routine

UISSMOVE_WINDOW

NEW-TEXT-LINE
Moves

the

height

Function

current
one

text

position

the

left

margin

and

down

in which

the

operation

the

line.

Format

UIS:NEW-TEXT-LINE

display att-block

Arguments

display
The

virtual

display

transformation

performed

att-block

fixnum

which
Return

the

font,

range

left

0-255,

margin,

and

designating
line

spacing

attribute

attributes

block

from

are

taken

down

Value

Undefined
Corresponding MicroVMS Routine

UISSNEW _TEXT LINE

NEW-TEXT-LINE-PIXEL Function
Moves

the

height

current
one

text

position

the

left

margin

and

line.

Format

UIS:NEW-TEXT-LINE-PIXEL

window att-block

Arguments

window
The

window

in which

the

operation

performed

the

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 MicroVMS Routine
UISDCSNEW_TEXT_LINE

PLOT Function

Draws a point, a single line, or up to 124 1lines, depending on the
number of positions specified. Use the PLOT-ARRAY function to draw
If the attribute block
more than 124 lines in a single operation.
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

Format

UIS:PLOT display att-block x1 yl

§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
x1

from

yl1

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 yl125

A line
single floats designating additional world coordinates.
is drawn between each point specified and the previous point.

GRAPHICS SYSTEM

Return

COMPONENTS

Value

Undefined

Corresponding MicroVMS Routine
UISSPLOT

PLOT-ARRAY Function
Draws

point,

number

the

points

the

See

multiple

connected

specified.

form of

vectors,

the

two

differs

1lines,

from

one

depending

the

PLOT

that

you

specify

the

value

and

one

pattern,

the

for

value.
attribute

function

lines

line,

points

does

block

not

specifies

lines,

but

draw

fill

instead

fills

the

PLOT-ARRAY

area

that

the

contain.

Section

3.5.3.2

for

3.5.1

for

information

about

drawing

specifying

fill

lines.

See

Section

pattern.

Format

UIS:PLOT-ARRAY

display att-block

&OPTIONAL

x-vector y-vector

count

Arguments

display
A virtual

display

transformation

att-block
A

fixnum

which
x-vector

the

graphics

specialized

you

supply
a

vectors

general

resulting

supplied,
are

0-255,

designating

will

attribute

block

from

SINGLE-FLOAT.

(If

taken

y-vector

Two
with

range

attributes

each

specified

interpreting

Successive

vectors,

loss

vector
by

points

are

elements
VAX

LISP

length

element

the

joined

and

type

creates

efficiency.)

must

taking

them

with

count

specialized
count

from x-vector
Y

values

lines

vectors,

argument

greater.

and y-vector
world

1is

Points
and

coordinate.

GRAPHICS SYSTEM COMPONENTS

count

A fixnum designating the number of points to be drawn.
argument

number

elements

not

supplied,
in

x-vector

defaults

the minimum of

this
the

and y-vector.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSPLOT_ARRAY

PLOT-ARRAY-PIXEL Function
Draws a point, line, or multiple connected
1lines,
number
of points specified.
It differs from PLOT

the points in the
the

form of two vectors,

depending
on
the
in that you specify

one for the X value and one for

Y value.

the

attribute

function
lines

does

block

not

specifies

draw

fill

1lines,

but

pattern,

the

instead fills

PLOT-ARRAY-PIXEL

the area that

the

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-PIXEL window att-block x-vector y-vector
&OPTIONAL

count

Arguments

window
A window

att-block

A fixnum in the

range 0-255,

which graphics

attributes will

x-vector

designating an attribute block
be

from

taken

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.

GRAPHICS SYSTEM COMPONENTS

count

fixnum

designating

argument

number

elements

Return

not

the

number

supplied,
in

x-vector

points

defaults

drawn.

the

minimum

this

the

and y-vector.

Value

Undefined

Corresponding MicroVMS Routine
UISDCSPLOT_ARRAY

PLOT-PIXEL Function
Draws

point,

number

draw more
If

the

than

See

single

124

attribute

function

lines

positions

does

line,

lines

block
not

specified.
a

Use

single

1lines,

depending

PLOT-ARRAY-PIXEL

the

function

operation.

specifies

1lines,

but

draw

124

the

fill

pattern,

instead

fills

the
the

PLOT-PIXEL

area

that

the

contain.

Section

3.5.3.2

for

3.5.1

for

information

about

drawing

specifying

fill

lines.

See

Section

pattern.

Format

UIS:PLOT-PIXEL

&OPTIONAL

window att-block

x2 y2

x125 y125

...

Arguments

window
A window

att-block
A

fixnum

which
x1

the

graphics

range

0-255,

attributes

designating

will

attribute

block

from

only

taken

vyl

Two

fixnums

point

designating

specified,

this

device

single

coordinate.

point will

this

plotted.

the

GRAPHICS SYSTEM COMPONENTS
x3 y3

x2 y2

...

x125 yl25

A line
Fixnums designating additional device coordinates.
point.
previous
the
and
d
specifie
point
each
drawn between

Return Value

Undefined

Corresponding MicroVMS Routine
UISDCSPLOT

POINTER-BUTTON-n Constants

An
Have values that specify a button on the pointing device.
1in
argument
action
is given as the
that
function
interrupt
first
1its
as
SET-BUTTON-ACTION or SET-BUTTON-ACTION-PIXEL receives,
argument, the code of the button whose transition invoked the
You also
function. Use these constants to compare with that code.
NS
GET-BUTTO
the
by
returned
value
the
interpret
to
use these constants
as
n
an
to
go
and
UTTON-1
POINTER-B
with
start
function. The constants
greatest
the
with
device
pointing
d
high as required for the supporte
number

of buttons.

See Section 5.1.3 for information about

getting

input

from

pointer

buttons.
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

1in

GRAPHICS SYSTEM COMPONENTS

Corresponding

MicroVMS

Routine

UISSPOP_VIEWPORT

PUSH-VIEWPORT Function
Pushes

other

any

display

viewport

viewports

the

which

back

may have

the

been

display

occluded

screen,

back

it.

Format

UIS:PUSH-VIEWPORT

window

Arguments
window
The
Return

window whose

associated

display viewport

pushed

Value

Undefined
Corresponding

MicroVMS

Routine

UISSPUSH_VIEWPORT

READ-IMAGE-PIXEL Function

Reads a bitmap from a rectangle in a window on the screen

and

creates

new

bitmap.

1In

either

the

bitmap

creates

specify.

the
If

you

bitmap

and

screen

the

pair
See

you
if

Chapter

not

argument

returns

function

READ-IMAGE-PIXEL

that

1is

specify

give
4

for

it.

image

supply
you

bitmap

image

the

returns

size

rectangle,

the

alters

1is

NIL,

the

screen

the

existing

bitmap.

bitmap

the

function

rectangle

taken

you

from

viewport.

bitmap
if

representing
that

case,

argument

new

entire
the

bitmap

either

1In

from

valid

this

the

bitmap,

size
the

bitmap,

case,
of

the
the

function

the

function

function
supplied
ignores

alters

determines
bitmap.

the

second

about

screen

images

and

coordinate

bitmaps.

Format

UIS:READ-IMAGE-PIXEL

window bitmap

&OPTIONAL

the

size

Therefore,

it.
information

the

x2 y2

GRAPHICS SYSTEM COMPONENTS

Arguments

window
A window
bitmap

If you supply an
Either an array of unsigned bytes, or NIL.
screen image from
the
of
the function determines the size
array,
the bits of
with
the size of the array, then modifies the array
If you specify NIL, the function creates an
the screen 1image.
array of size x2-x1,y2-yl whose Dbits correspond to the bits of
the

x1l

screen

1image.

Two fixnums specifying, in

device

coordinates,

corner of the rectangle containing the image.

the

lower-left

1If these arguments

are omitted or NIL, they default to 0, specifying the lower-left
If you supply a bitmap array for the
corner of the wviewport.
bitmap argument, the bitmap array determines the size of the
rectangle.
x2 y2

Two fixnums specifying, in device coordinates, the upper-right
These are
of the rectangle containing the 1image.
corner
include,
not
does
exclusive bounds; the image extends up to, but
1if
ignored
the bounds specified by x2 y2. These arguments are
you supply a bitmap array for the bitmap argument. If you supply
NIL for bitmap, x2 and y2 default to the upper-right corner of
the viewport in such a way that the topmost row and rightmost
column of pixels are included in the returned bitmap.

Return Value
A bitmap

array

Corresponding MicroVMS Routine
UISDCSREAD_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

interpreting

for

information

about

wusing

wvirtual

keyboards

and

keystrokes.

Format

UIS:READ-KB-CHAR kéyboard
Arguments

keyboard
A virtual
Return

keyboard

Value

character

Corresponding

integer

MicroVMS

Routine

UISSREAD CHAR

RESIZE-WINDOW Function
Changes

the

location.

specified

window

You

optionally

window within

the

virtual

You can use

can

the

display’s

this

and

function

supplied

Section

have

display

the

specified

change
as

list,

the

well.

size

The

one

viewports.

2.4.6.2

RESIZE-WINDOW

the
and

action
the

for

the

viewport
and

size

location

function

the

re-executes

also

size and location
useful

interrupt

SET-RESIZE-ACTION

description

and

exists.

function by itself to alter the

windows
See

virtual

function.

SET-RESIZE-ACTION.

Format

UIS:RESIZE-WINDOW
&OPTIONAL

display
y1

window

width

height

NIL.

The

Arguments

display
A virtual
must

display,

the

specifying

one

this

transformation,

into

display.

mapped

into

*"f\

Y\‘i\fll""; N N TR TM
-:f\f\
transformation

use

that

which

display.
4

window

P R 7Y

or
is

mapped;

transformation
Specifying

-.v\-\

A._J

COurdLuatEb

virtual

NIL

must

equivalent

one

transformation

instead

‘.C

'1.:

world

display

7N S

that

allows

you

coordinates.

GRAPHICS SYSTEM COMPONENTS
window

A window object

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
x1

x2 y2

Four single floats specifying the lower-left and upper-right
corners of a rectangle in world or transformation coordinates.
If these
The resized window is mapped to this rectangle.
used.
are
ates
coordin
window
g
arguments are omitted, the existin
Return Value

Undefined

corresponding MicroVMS Routine
UISSRESIZE_WINDOW

SET-ALIGNED-POSITION Function

Sets the aligned position for text output in a specified wvirtual
The aligned position differs from the position established
display.
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 more information about the aligfied text

Format

UIS:SET-ALIGNED-POSITION display att-block x y

GRAPHICS SYSTEM

COMPONENTS

Arguments

display
The

virtual

position

display
to

transformation

for

which

attribute

the

set

aligned

att-block

fixnum

which

font

Two

single

the

new

Return

the

range

0-255,

information

floats

aligned

will

designating
be

designating

text

block

from

taken

the

world

coordinate

position

Value

Undefined
Corresponding

MicroVMS

Routine

UIS$SET_ALIGNED_POSITION

SET-ALIGNED-POSITION-PIXEL Function
Sets

the

aligned

position

SET-POSITION-PIXEL
next

character

character’s
attribute

See

3.6.2.1

output

that

refers

output,

For

this

from which

position.

text

from

baseline.

block

Section

for

differs

for

rather

reason,

take the

the

specified

position

the

window.

The

established

with

upper-left

than

the

corner

leftmost

function

point

requires

the

input

aligned

text

font.

information

about

the

Format

ULS:SET-ALIGNED-POSITION-PIXEL

window

att-block

Arguments

window
The

window

for

which

the

aligned

position

set

att-block

fixnum

which

font

the

range

information

0-255,

will

designating

taken

attribute

block

from

GRAPHICS SYSTEM COMPONENTS

Two fixnums designating the world coordinate position of the

new

aligned text position

Return Value

Undefined

Corresponding MicroVMS Routine
UISDCSSET_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

the

If you supply a window, you can set
first argument to SET-ATTRIBUTE.
If you supply a display and you want to
the value of any attribute.

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

representing

0-255,

associated with the display

attribute

block

output-ab

A fixnum in the range 1-255, representing an attribute block that
will be modified

GRAPHICS SYSTEM

attribute
An

COMPONENTS

new-value

attribute

:ARC-TYPE

set

:OPEN

:BACKGROUND-INDEX

map.

The

virtual

default),
integer

color

list

(vertically).

map.

:CHORD.
entry

default

single

color

(0.0

character

in the

floats,

characters

default

the

range of the entries

The

two

between

The

fractions

:PIE,

in the

leave

value:

specifying

integer must be

space

specify

new

(the

display’s

extra

its

: CHARACTER-SPACING

lines

and

specifying

the

(horizontally)

0.0).

width

and

The

numbers

font

height,

respectively.

:CLIP

NIL

(the

virtual
list

four

designate
:CLIP-PIXEL

four

this

single

floats

the

form

clipping
(the

turned

One

Either

off

in the
in

world

attribute

(x1 yl x2 y2)
coordinates.
keywords

character

font

pathname

font

string

file
to

(or

file,

you

supply a

pairs.

the

specification

the

SHOW-FONTS

SHOW-FONTS
:LEFT-MARGIN

for

for
A

text

virtual

display’s

display.

The

replicated
:LINE-WIDTH

one

number

mapped

the

line

line
is

length
32-bit

single

style

float

:WORLD-COORDINATES),

Lines
width

whose
are

the

subject
not

use

width

the

each keyword

pairs
the

1left

left

displayed

margin

edge

for

particular

the
text

virtual

specification

keywords

:SOLID),

the

where

world

list

lines

line

form

drawn

specified

bit

supply

bit

will

the

width

single

1is

coordinates.

specify

with

displayed

wvalue

width,

scaling when

scaled.

the

specifying

normal

the width

you

list,

through

number

1If

file

containing

less,

form

specifies

list

you

the

coordinates,

the

block

equated

multiples

1.0.

the

32 or less;
wvector.

designate

:SOLID.

1line
that

the

style

float

the

into

default

:DASHED-DOTTED,

form a
a

list

the

default

Either

name

specifying

default
window.

specifying

specifies
must

its

keyword-value

windows

default

The

a
to

keywords displayed
by
value must be a character

The

fixnum

all

: DOTTED,

Dbits.

font you want.

default

Either

that

vector,

( :DASHED,

its

the

and

those

single-float

operations

vector

only

operations.

:LEFT-MARGIN-PIXEL

:LINE-STYLE

font

function,

Supply

displayed

font

string.

y2)

«c¢lipping

block;

logical

must

containing

keyword-value
one

that

form

the

coordinates.

indicate

this

the

(x1

block;

function.

specification
file),

<clipping

attribute

device

SHOW-FILL-PATTERNS

:FONT

rectangle

default),

rectangle
-

that

off

:FILL-PATTERN

indicate

turned

fixnums

clipping

the
NIL

viewports

default),

display

that

multiple

list
The

world

attribute

viewport.
the

normal

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.

(the
:OVERLAY
:WRITING-MODE
: COMPLEMENT,
:OVERLAY-NEGATE,
:ERASE,

:ERASE-NEGATE,

:COPY.

default),
:REPLACE,

: TRANSPARENT,
: REPLACE-NEGATE,

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

UISSSET ARC_TYPE
UISSSET BACKGROUND_INDEX
UISSSET CHAR_SPACING
UISSSET_CLIP
UISDCSSET_CLIP
UISSSET FILL_PATTERN
UISSSET_FONT
UISSSET LEFT_MARGIN
UISDCSSET LEFT_MARGIN
UISSSET LINE_STYLE
UISSSET LINE_WIDTH
UISSSET WRITING_INDEX
UISSSET WRITING_MODE

UTTON-ACTION Function

d
Specifies the action to be performed when a pointer button is presse
for
or
window
or released. The action can be specified for an entire
The action can be either an
a specified rectangle in a window.
(iif-id) previously returned by
identifier
function
interrupt
interrupt
INSTATE-INTERRUPT-FUNCTION, or NIL, in which <case no
receive
will
1t
ied,
specif
is
on
functi
a
1If
function will be invoked.
r the
whethe
of
tion
indica
an
two arguments: the button code, and
e
preced
nts
argume
two
These
button was pressed (T) or released (NIL).
any that you specify with INSTATE-INTERRUPT-FUNCTION.
the button code with the POINTER-BUTTON-n constants.

You can compare

When you suspend a LISP system, all your interrupt
ed all actions are reset to
functions are uninstatand
You must reinstate interrupt functions and
NIL.
reissue SET-BUTTON-ACTION when the system 1s resumed.
e
R
e

GRAPHICS SYSTEM

See

Section

pointer

5.1.3

for

COMPONENTS

information

about

getting

input

buttons.

from

Format

UIS:SET-BUTTON-ACTION

&OPTIONAL

yl1

display

window

action

Arguments

display
A virtual
must

display,

the

specifying

one

transformation,

into

this

which

display.

mapped

into

transformation

use

that

window

display.

or
is

NIL.

The

mapped;

transformation
Specifying

coordinates

wvirtual

NIL

must

one

that

allows

you

transformation

instead

world

display

equivalent

coordinates.

window
A window

action
Either

specify
x1

yl1

specify

interrupt

function,

action

NIL

Four

single

corners
Button

floats

designating

rectangle

transitions

within

the

omitted,
Return

iif-id

trigger

rectangle

the

entire

the

window

the

world

the
is

coordinates
or

two

transformation

action

only

time.

sensitive

button

coordinates.

the

these

opposite

pointer

arguments

are

transitions.

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET_BUTTON_AST

SET-BUTTON-ACTION-PIXEL Function
Specifies

the

action

released.

The

for

rectangle

action

can

previously
case

interrupt

performed
can

viewport

either

returned

action

when

specified

specified
interrupt

pointer
for

device

function

INSTATE-INTERRUPT-FUNCTION,

function

will

invoked.

button

entire

viewport

pressed

coordinates.
identifier
or
If

NIL,
a

The

(1if-1id)
in

which

function

GRAPHICS SYSTEM COMPONENTS

the button code, and an
specified, it will receive two arguments:
(T) or released (NIL).
pressed
was
button
the
indication of whether
with
specify
you
that
any
precede
arguments
two
These
the
with
code
button
the
compare
You can
INSTATE-INTERRUPT-FUNCTION.

POINTER-BUTTON-n constants.

NOTE

When you suspend a LISP
functions

system,

all

your

interrupt

are uninstated and all actions are reset to

reinstate interrupt
You must
NIL.
reissue SET-BUTTON-ACTION-PIXEL when

functions and
system is
the

resumed.

See Section 5.1.3
pointer

for

information

about

getting

input

from

buttons.

Format

UIS:SET-BUTTON-ACTION-PIXEL window action
&OPTIONAL x1 yl1 x2 y2

Arguments

window

A window
action

Either an iif-id to specify an

function,

interrupt

NIL

specify no action

x1l

yl1

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 1is

within

the

rectangle

the

time.

these

arguments are

omitted, the entire viewport is sensitive to button transitions.

Return Value

Undefined

Corresponding MicroVMS Routine
UISDCSSET_BUTTON_ ! \ST

GRAPHICS SYSTEM COMPONENTS
SET-CLOSE-ACTION
Specifies

the
one

the

Delete

Function

action

selection

performed

the

when

Window

the

Options

the

interrupt

INSTATE-INTERRUPT-FUNCTION.

user

closes

menu.

The

window

action

can

via

following:

function

identifier

unless

(iif-id)

you

previously

arguments

are

specified

returned

passed

them

the
with

INSTATE-INTERRUPT-FUNCTION.

:DISALLOW,

which

case

the

user

not

allowed

the

window.
:DELETE,
for
@

The

1in

the

which

:DELETE-DISPLAY,

invoked

for

Deleting

the

default

closing

action

the

case

window when
in

the

taken

which

VAX

restores

information

you

suspend

functions
NIL.

You

reissue

See

Section

are

for

the

DELETE-DISPLAY

reinstate

the

information

function

window
the

action

the

vyour

actions

1is

mapped.
as

well.

wuser

from

argument

description

to
of

interrupt

are

reset

functions

system

about

invoked

action.

interrupt

when

the

See

all

1is

window

prohibit

:DELETE

all

the

deletes

system,
and

function
window.

which

default.

LISP

the

:DISALLOW

about

uninstated

must

the

into

LISP

this

SET-CLOSE-ACTION

2.4.6.3

case

Specifying

DELETE-WINDOW

When

closes

automatically

SET-CLOSE-ACTION

for

DELETE-WINDOW

user

display

window.

the

using

to
and

resumed.

this

function.

Format

UIS:SET-CLOSE-ACTION

window

action

Arguments

window
The

window

associated with

the

specified

viewport

for

which

action

GRAPHICS SYSTEM COMPONENTS

action

Either an iif-id to specify an interrupt function,

:DISALLOW

to prevent the user from closing the window, or :DELETE to delete
the window, or :DELETE-DISPLAY to delete the window’s display

Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET CLOSE_AST

SET-COLOR Function

Sets an entry in the color map associated with a virtual display to
specified color. See Section 3.4 for more information about color.

Format

UIS:SET-COLOR display color-id r g b
Arguments

display

A virtual

display

color-id

An integer specifying an entry in the color map

associated

with

display
r

Three floating-point numbers in the range 0.0 - 1.0, inclusive,
intensities for the red, green, and Dblue
the
specifying
components of the color

Return Value
Undefined

Corresponding MicroVMS Routine

UISSSET COLOR

GRAPHICS SYSTEM COMPONENTS

SET-GAIN-KB-ACTION Function
Specifies

attached

the

interrupt

action

function

performed

when

the

virtual

keyboard.

The

identifier

(iif-id)

previously

returned

NIL,

which

specified

INSTATE-INTERRUPT-FUNCTION,

function

arguments

with

invoked.
are

passed

interrupt
upon

physical

action

case

function

invocation

can

unless

INSTATE-INTERRUPT-FUNCTION.

keyboard

either

interrupt

specified,

you

specified

no
them

NOTE
When

you

suspend

functions
NIL.

You

reissue

~See

Section

are

LISP

system,

uninstated

must

and

reinstate

for more

vyour

actions

interrupt

SET-GAIN-KB-ACTION when

6.1

all

the

are

interrupt

reset

functions

system

to
and

resumed.

information about using virtual

keyboards.

Format

UIS:SET-GAIN-KB-ACTION

keyboard

action

Arguments

keyboard
A virtual

keyboard

action
Either

specify
- Return

iif-id

specify

interrupt

function,

virtual

display

action

NIL

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET_GAIN_KB_AST

SET-INTENSITY Function
Sets

entry

specified

the

color

equivalent

information about

color

map

associated

monochrome

and

with

1nten51ty

intensity.

See

Section

3.4

for

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

A floating-point number in the range 0.0 - 1.0,

inclusive

Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET_INTENSITY

SET-KB-ACTION Function

Specifies the action to be performed when any keyboard key 1is pressed.
The action can be either an interrupt function identifier (iif-id)
1in which
previously returned by INSTATE-INTERRUPT-FUNCTION, or NIL,
1If an interrupt function
case no interrupt function will be invoked.
is

speciifed,

receives

two arguments:

A character if the key was a control or printing key, and. an
(See Chapter 6 and the description of the
integer otherwise.
K-TRM-xxx constants for more information

about

return

this

value.)

A flag to indicate the key state.
for

future

This argument is

reserved

use.

Additional arguments are passed to the function if you specified
with

them

INSTATE-INTERRUPT-FUNCTION.

This 1is unlike
The action is invoked only once for each keystroke.
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

functions

NIL.,

You

reissue

See

Section

from

are

LISP

system,

must

and

reinstate

SET-KB-ACTION when

6.2

virtual

uninstated

for

all

your

actions

interrupt
the system

information

reset

functions
is

about

interrupt

are

and

resumed.

interpreting

keyboards.

keystrokes

Format

UIS:SET-KB-ACTION

keyboard

action

Arguments

keyboard
The

virtual

keyboard

for

which

the

function

returned

action
Either

specify
Return

iif-id

specify

interrupt

function,

action

NIL

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET_KB_AST

RIBUTES

Enables

disables

keyboard.
which

Unless
in

Each

take

physical

one

virtual

effect

attributes

keyboard

only when

keyword

function

the

maintains

virtual

specifying

<call,

current

unaffected.

1In

keywords

included

See

or more

for

its

own

keyboard

specified
set

wvirtual

attributes,

connected

keyboard.

the

Function

not

Section

other

6.1.4

for

the

attribute

words,

argument

the

default

information

setting

NIL

specifically

mentioned

the

attribute

not

assumed

remains

for

list.
about

keyboard

the

attributes.

those

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-KB-ATTRIBUTES keyboard
&KEY

: KEYCLICK

:AUTOREPEAT

: FUNCTION-KEYS-11-14

: FUNCTION-KEYS-6-10
: FUNCTION-KEYS-17-20

:HELP-DO-KEYS :EDITING-KEYS-1-6
: KEYPAD-KEYS :CLICK-VOLUME

: ARROW-KEYS

Arguments

keyboard

A keyboard
: AUTOREPEAT

or disabled
T or NIL, causing keyboard autorepeat to be enabled
:KEYCLICK

T or NIL, causing keyboard keyclick to be enabled or disabled
: FUNCTION-KEYS-6-10
T or NIL,

disabling delivery of

keys

F6-F10

disabling delivery of

keys

F11-F14

enabling

disabling delivery of

keys

F17-F20

enabling

disabling delivery of

HELP and DO keys

enabling

disabling delivery of

editing

enabling

disabling delivery of

arrow keys

enabling

e FUNCTION-KEYS-11-14
T or NIL,

enabling

: FUNCTION-KEYS-17-20
T or NIL,
:HELP-DO-KEYS

T or NIL,

c:EDITING-KEYS-1-6

T or NIL,

keypad

keys

E1-E6
:ARROW-KEYS

T or NIL,

enabling
& & Gl Suf adn

S &
oitn

delivery

T or NIL,

: KEYPAD-KEYS

numeric keypad keys

GRAPHICS SYSTEM COMPONENTS

:CLICK-VOLUME
An

integer

keyclick
Return

between

(quiet)

and

(loud),

volume

specifying

the

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET_KB_ATTRIBUTES

SET-KB-COMPOSE2 Function
This

function

keyboard.

keyboard

A keyboard
The

loads

the

description
Two-stroke

2-stroke

the

can be

keyboard

compose

American

and

sequence

length

table

into

arguments

Video

Device

Driver

alien
Manual

table.

sequences

virtual

returns

state.

implemented in LISP

Workstation

compose

table

system default

table

MicroVMS

North

Omitting

can

used

all

keyboards

the

structure.
contains

except

keyboard.

the

Format

UIS:SET-KB-COMPOSE2

keyboard

&OPTIONAL

table

length

Arguments

keyboard

A virtual‘keyboard
table

length
An

appropriate

Video

Device

these

arguments

2-stroke

table,

Driver

described

Manual,

returns

the

compose

sequence

table.

MicroVMS

Routine

the

its

length

the

keyboard

Return Value

Undefined
Corresponding

and

UISSSET_KB_COMPOSE?2

MicroVMS

Workstation

bytes.
system

Omitting
default

GRAPHICS SYSTEM COMPONENTS
SET-KB-COMPOSE3 Function

This function loads a 3-stroke compose sequence table into a wvirtual
the
table and length arguments returns
Omitting the
keyboard.
keyboard to the

system default

state.

structure.
alien
an
as
A keyboard table can be implemented in LISP
a
contains
Manual
Driver
The MicroVMS Workstation Video Device
description of a keyboard table.
Format

UIS:SET-KB-COMPOSE3 keyboard &OPTIONAL table length
Arguments

keyboard

A virtual
table

keyboard

length

An appropriate table, as described in the MicroVMS Workstation
video Device Driver Manual, and its length in bytes. Omitting
returns the keyboard to the system default
these arguments
three-stroke compose key table.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET_KB_COMPOSE3

SET-KB-KEYTABLE Function

This function loads a keyboard
table
Oomitting the
keyboard.
keyboard to the

equivalence
and 1length

table into a wvirtual
returns the
arguments

system default state.

structure.
d LISP as an alien
A keyboard table can be implementein
The MicroVMS Workstation Video Device Driver Manual contains a
description of a keyboard table.
Format

UIS:SET-KB-KEYTABLE keyboard &OPTIONAL table length

GRAPHICS SYSTEM

COMPONENTS

Arguments

keyboard

A virtual
table

keyboard

length
An

appropriate

Video

table,

Device

arguments

are

keyboard

table.

Return

Driver

described

Manual,

omitted,

the

and

the

its

length

keyboard

MicroVMS

Workstation

bytes.

returned

1If

the

these

default

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET
KB KEYTABLE

KB-ACTION Function
Specifies

the

action

disconnected
either

to be performed when
a

an interrupt

specified

function

arguments

invoked.
are

passed

wvirtual

identifier

INSTATE-INTERRUPT-FUNCTION,

function

with

from

physical

(iif-id)

NIL,

interrupt
upon

the

keyboard.
in

action

previously

which

function

invocation

keyboard

The

unless

case

can

returned

interrupt

1is

specified,

you

specified

no
them

INSTATE-INTERRUPT-FUNCTION.

NOTE
When

you

suspend

functions
NIL.

You

reissue

See

Section

6.1

are

LISP

uninstated

must

system,
and

reinstate

all

information

actions

the

about

Format

UIS:SET-LOSE-KB-ACTION

keyboard

Arguments

keyboard

vyour

interrupt

SET-LOSE-KB-ACTION when

for

all

action

are

system

using

interrupt
reset

functions
is

to
and

resumed.

virtual

keyboards.

GRAPHICS SYSTEM COMPONENTS
action

Either an iif-id to specify an

interrupt

function,

NIL

specify no action

"Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET LOSE_KB_AST

SET-MOVE-INFO-ACTION Function

Specifies the action to be performed when a specified viewport 1s
The action can be either an interrupt function identifier
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

system,

When you suspend a LISP

your

all

interrupt

are uninstated and all actions are reset to

functions
vYou must reinstate interrupt functions and
NIL.
when the system 1is
SET-MOVE-INFO-ACTION
reissue
resumed.

See Section 2.4.3 for information about, and an example of, using this
function.

Format

UIS:SET-MOVE-INFO-ACTION window action
Arguments

window

The window associated with the viewport for which a

move

action

NIL

is to be specified

specify no action

—

3
O
rt

‘e

c
O

|
w
)

}..J

o))
3

Either an iif-id to specif

action

GRAPHICS SYSTEM COMPONENTS

Return

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET_MOVE_INFO_AST

SET-POINTER-ACTION Function
Specifies

within

the

and/or

window.

action

The

(iif-id)

which

performed

window

action(s)

identifier
NIL,

exits

function

invocation

unless

you

when

interrupt

specified,

pointer

cursor

world-coordinate

an
interrupt
function
INSTATE-INTERRUPT-FUNCTION,

function

1is

invoked.

arguments

are

passed

them with

moves

rectangle

either

returned

specified

the

specified

can

previously

case

interrupt

upon

INSTATE-INTERRUPT-FUNCTION.

NOTE
When

you

suspend

functions
NIL.

You

reissue

See

Section

contains

are

LISP

system,

must

and

reinstate

for

information

examples

its

all

your

actions

interrupt

SET-POINTER-ACTION when

5.1.2

many

uninstated

about

the

reset

functions

system

using

interrupt

are

this

to
and

resumed.

function.

Chapter

use.

Format

UIS:SET-POINTER-ACTION

display

window

move-action
&OPTIONAL

exit-action

Arguments

display
A virtual
must

display,

the

specifying

one
this

transformation,

into

display.

mapped

into

transformation

use

that

which

display.

window
A

NIL.

Specifying

coordinates

window

The

mapped;

transformation

window
A

or
is

NIL

must

virtual
is
be

one

that

allows

you

transformation

instead

world

display

equlivalent

coordinates.

GRAPHICS SYSTEM COMPONENTS

move-action

Either an iif-id to specify an
1interrupt
function,
or
NIL
specify no action, when the cursor moves within the rectangle

¢to

exlit-action

Either an iif-id to specify an
1interrupt
function,
or
specify no action, when the cursor exits the rectangle
x1l

yl1

NIL

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 MicroVMS Routine
UISSSET 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
1interrupt
function
identifier
(iif-1id)
previously
returned
by
INSTATE-INTERRUPT-FUNCTION,
or
NIL,
in
which
<case
no
interrupt
function
1is
invoked.
If
an
interrupt
function
1is 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
are uninstated and all actions are reset to
functions
NIL.
You
must
reinstate
interrupt
functions
and
the system is
when
SET-POINTER-ACTION-PIXEL
reissue
resumed.

GRAPHICS SYSTEM

COMPONENTS

Format

UIS:SET-POINTER-ACTION-PIXEL

&OPTIONAL

yl1

window

move-action

exit-action

Arguments

window
A window

move-action

Either

specify

11f-1d

action,

specify
when

the

interrupt

cursor

moves

function,
within

the

NIL

rectangle

exit-action
Either

specify
x1

fixnums

corners

specify
when

the

actions
exits

designating

actions

exits

Return

action,

interrupt

cursor

exits

function,
the

NIL

rectangle

Four

The

1if-id

are

device

the

triggered when

rectangle.

are

the

rectangle

1If

these

triggered when

the

coordinates

viewport

the

pointer

arguments

pointer

two

associated

cursor

are

NIL

cursor

opposite

with

moves

window.

within

omitted,

the

within

moves

specified window.

Value

Undefined
Corresponding

MicroVMS

Routine

UISDCSSET POINTER_AST

SET-POINTER-PATTERN Function
Establishes

cursor

within

Once

new

established,

pointer

a
the

pointer

pattern

function

can

patterns

for

different

when
called

5.1.2

for

cursor

given

pattern

window

new pattern

the
as

pointer

often

will
as

used

specified
be

when

the

portion

substituted

cursor
desired

enters
to

for

the

that

pointer

window.
current

area.

establish

This

different

rectangles.

information

about

using

this

function,

and

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-POINTER-PATTERN display window bitmap
active-x active-y

&OPTIONAL x1 yl x2 yZ2
Arguments

display

display
The wvirtual
A virtual display, transformation, or NIL.
must be the one into which window is mapped; NIL is equivalent to
specifying this display. A transformation must be one that 1is
Specifying a transformation allows you
mapped into that display.
s instead of world coordinates.
coordinate
tion
transforma
to use
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
relative to the Dbit at the lower-left corner
cursor pattern,
(0,0). The active bit is used to calculate the pointer position.
x1

x2 y2

Four single floats designating the world or transformation
The new
coordinates of two opposite corners of a rectangle.
this
enters
cursor
the
when
wused
be
cursor pattern will
is
window
entire
the
omitted,
are
If these arguments
rectangle.
used.

Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET_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. Once
established, the new pattern will be substituted for the current
89

pointer
be

pattern

called

different
See

when

often

GRAPHICS SYSTEM

COMPONENTS

the

that

pointer

desired

enters

area.

establish

This

different

function
patterns

can
for

rectangles.

Section

5.1.2

for

information

about

using

this

function.

Format

UIS:SET-POINTER-PATTERN-PIXEL
&OPTIONAL

yl1

pattern,

window

bitmap

active-x

active-y

Arguments

window
A window

bitmap
The

new

active-x

fixnums

the

cursor

pattern,

(0,0).

The

form

16x16

bitmap

range

0-15

relative

active

bit

designating

used

the

bit

the

active

bit

the

lower-left

calculate

the

pointer

the

corner

position.

Four

fixnums

corners

The

designating

new

the

rectangle

cursor

rectangle.

the

active-y

Two

cursor

pattern

will

these

device

the

coordinates

viewport

used when

arguments
are

two

opposite

associated with

the

omitted,

cursor
the

window.

enters

entire

this

viewport

used.

Return Value

Undefined
Corresponding

MicroVMS

Routine

UISDCSSET_POINTER_PATTERN

SET-POINTER-POSITION Function
Moves

the

pointer

coordinates.

that

is,

cursor

The

the

function

new position

visible.

TIf

the

new position

invisible

the

screen,

the

pointer

the

new

returns

is
is

position,

within
not

function

cursor.

the

within

specified

operation was

specified
the

returns

world

successful,

window

and

specified window

NIL

and

does

not

move

GRAPHICS SYSTEM COMPONENTS

Format

UIS:SET-POINTER-POSITION display window X ¥y
Arguments

display

display
virtual
The
A virtual display, transformation, or NIL.
must be the one into which window is mapped; NIL. is equivalent to
is
that
one
A transformation must be
specifying this display.
you
allows
transformation
a
Specifying
display.
that
into
mapped
to use transformation coordinates instead of world coordinates.
window
A window

X Y

single

Two

floats

designating

world

transformation

coordinate
Return Value

1is
T if the new position falls within the specified window and
if the new position falls outside the window or if
NIL
visible;
it

invisible

Corresponding MicroVMS Routine
UISSSET_POINTER_POSITION

SET-POINTER-POSITION-PIXEL Function

device
1in
specified
new position,
a
to
Moves the pointer cursor
successful,
was
operation
the
if
T
returns
function
The
coordinates.
1is
that is, if the new position is within the specified viewport and
1is
or
viewport
specified
the
If the new position is outside
visible.
invisible, the function returns NIL and
does
not
move
the
pointer
cursor.

Format

UIS:SET-POINTER-POSITION-PIXEL window X Yy
Arguments

window
A window

GRAPHICS SYSTEM COMPONENTS

Two
Return

fixnums

designating

device

coordinate

the

window

Value

the

new position

visible;
it

NIL

the

falls within

new

position

the

invisible

Corresponding

specified viewport

falls

outside

the

and

viewport

1is

MicroVMS

Routine

UISDCSSET_POINTER_POSITION

SET-POSITION
Sets

the

current

position
to

Function

1is

text

the

position

alignment

for

point

wvirtual

the

baseline

display.
of

the

The

text

character

be. output.

See Section 3.6.2 for information about text positioning.
Format

UIS:SET-POSITION

display

Arguments

display
The

i1s

virtual

Two

display

transformation

for

which

the

text

position

set.

single

floats

designating

the

world

coordinates

the

text

position.
Return

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSET POSITION

SET-POSITION-PIXEL Function
Sets

the

virtual

device-coordinate
display.

The

text

position
position

for
1s

windows
tne

mapped

leftmost

point

into
on

a
the

GRAPHICS SYSTEM COMPONENTS

The device-coordinate
e the next character to be output.
baselinof
text position 1is independent of the display text position; however,
same
the
share
display
virtual
all windows mapped 1into a
device-coordinate text position.

See Section 3.6.2 for information about text positioning.
Format

UIS:SET-POSITION-PIXEL window X Yy
Arguments

window

The window for which the text position is to be set.
Xy

Two fixnums

designating

device

the

<coordinates

the

text

position.
Return Value

Undefined

Corresponding MicroVMS Routine
UISDCSSET_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:

An interrupt function identifier (iif-id) previously
interrupt
The
INSTATE-INTERRUPT-FUNCTION.
by
receives the following eight arguments:

returned
function

1in
Two floating point numbers indicating the new position,
corner
t
lower-lef
the
of
ers),
(centimet
es
screen coordinat
of

the viewport.

the

new

width

and

Two floating point numbers indicating

Four floating point numbers indicating the new coordinates
of the corners of the window, in the form x1 yl x2 y2. The
transformation
or
coordinates
coordinates are world
to
argunent
first
the
on
g
dependin
coordinates,

height,

in centimeters, of the viewport.

GRAPHICS SYSTEM COMPONENTS

SET-RESIZE-ACTION.

:DISALLOW,
in which

case

the

user

not

allowed

resize

the

window.

:DEFAULT
when
change

the

you

specify

function

that

you

the

will

the

and

viewport

window

and

the

action,

above

viewport
eight

The

calling

arguments

the

RESIZE-WINDOW

received

when

right,

arguments

that

not

function

window

interrupt

any

Note

to
the

example,

the

before

system does

interrupt

invoked

For

right,

stretch

graphics

automatically.

same

requests.
the

INSTATE-INTERRUPT-FUNCTION.

function,

1is

action

window

display.

window

the

also

noted

with

action
default

virtual

function

eight

and

user

viewport

display

what

The

viewport

direction
the

default

arguments

interrupt

the

window.

interrupt

specified

the

case
the

the

passing

both

wvirtual

specify

the

stretches

receives

which

resizes

user

exposing
If

size

and

the

into

NIL,
wuser

the

amount
1f

the

resize
can

the

resize

function

was

vyou

and

invoked.

NOTE
When

you

suspend

functions
NIL.

You

reissue

See

Section

are

7.2.1

LISP

system,

uninstated

must

and

reinstate

for

contains

the

information
example

your

actions

interrupt

SET-RESIZE-ACTION when

2.4.6.2

all

interrupt
reset

functions

system

about

its

are

to
and

resumed.

wusing

this

The

virtual

function.

use.

Format

UIS:SET-RESIZE-ACTION

display

window

action

Arguments

display
A virtual
must

display,

the

specifying
mapped

into

one

transformation,

into

this

which

display.

that

window

or
is

NIL.
mapped;

transformation

NIL

must

display.

window
The

window

for

which

the

function

returned

display

equivalent

one

1is

that

GRAPHICS SYSTEM COMPONENTS

action
Either an iif-id to specify an interrupt function,

:DISALLOW

to prevent the user from resizing the window, or NIL to specify
See the description of the function above for
no action.
information about arguments received by the interrupt function.
Return Value

Undefined

Corresponding MicroVMS Routine
UISSSET _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
the font specification keyword for that particular font. No entry 1in
a column indicates that the font has the default value for that font
specification keyword.

GRAPHICS SYSTEM COMPONENTS
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

this

argument

workstation

bell

omitted,

the

volume

taken

from

device.

The

sound.
the

default

volume.

device
A

character

string

specifying

the

SYSSWORKSTATION.
Return

Value

Undefined
Corresponding

MicroVMS

Routine

UISSSOUND_BELL

output

default

1is

GRAPHICS SYSTEM COMPONENTS
SOUND-CLICK Function
Sounds the keyboard keyclick.
Format

UIS:SOUND-CLICK &OPTIONAL volume device
Arguments

volume

If
A fixnum in the range 1§8 specifying the volume of the sound.
default
this

argument

omitted, the volume is taken from the

workstation keyclick volume.
device

A character string specifying the output device.

The default

SYSSWORKSTATION.

1is

Return Value

Undefined

Corresponding MicroVMS Routine
UISSSOUND_CLICK

TEST-KB Function

Returns T if the

physical keyboard,

specified

virtual

and NIL otherwise.

Format

UIS:TEST-KB keyboard
Arguments

keyboard

A keyboard
Return Value
T

NIL

Corresponding MicroVMS Routine
UISSTEST_KB

keyboard

1is

connected

the

GRAPHICS SYSTEM

COMPONENTS

TEXT Function
Draws

Lext

position

character

information

string

the

end

text

output

virtual
of

display,

the

and

string.

moves

See

the

display’s

Section

3.6

operations.

for

Format

UIS:TEXT

display

att-block

text-string

&OPTIONAL

Arguments
display
The

virtual

display

transformation

drawn

which

the

text

att-block
A

fixnum

which

font

the

and

range

other

0-255,

text

designating

attributes

the

are

attribute

block

from

taken

text-string

character

Two

single

upper-left

omitted,
Return

the

string

floats
corner

character

specifying
of

string

single

the

begins

the

world

coordinates

text

string.

the

current

text

these

arguments

the
are

position.

Value

Undefined
Corresponding

MicroVMS

Routine

UISSTEXT

TEXT-PIXEL Function
Draws

character

device-coordinate
3.6

for

text

information

string

position

the

text

output

viewport,

end

the

and

string.

moves

See

operations.

Format

UIS:TEXT-PIXEL

window

att-block

text-string

&OPTIONAL

the

Section

GRAPHICS SYSTEM COMPONENTS

Arguments

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
XY

Two fixnums specifying the device coordinates of the upper-left
corner of the text string. 1If these arguments are omitted, the
string begins at the current device-coordinate text position.
Return Value

Undefined

Corresponding MicroVMS Routine
UISDCSTEXT

TRANSFORMATION Type Specifier

Designates

objects

TRANSFORMATION,

type

CREATE-TRANSFORMATION function.

created

the

object

and

NIL

TRANSFORMATIONP Function

Returns

its

argument

otherwise.
Format

UIS:TRANSFORMATIONP object

Arguments
object

Any LISP object

transformation

GRAPHICS SYSTEM

COMPONENTS

Return Value
T

NIL

Corresponding

MicroVMS

Routine

None

UIS-ID Function
Returns

the

argument

UIS

may

its

display,

argument

for

transformation,

wuse

with

window,

CALL-OUT.
keyboard.

Format

UIS:UIS-ID

object

Arguments

object
An
Return

object

type

DISPLAY,

TRANSFORMATION,

WINDOW,

KEYBOARD

Value

integer

Corresponding

that

MicroVMS

the

UIS

the

object

Routine

None

WINDOW-DISPLAY Function
Returns

the

display

with

which

specified

Format

‘

UIS:WINDOW-DISPLAY window

Arguments

window
A window
Return

object

Value

A display

100

window

associated.

The

GRAPHICS SYSTEM COMPONENTS
Corresponding MicroVMS Routine
None

WINDOW Type Specifier

Designates objects

type

WINDOW,

created

the

CREATE-WINDOW

function.

WINDOWP Function

Returns T if its argument is a window and NIL otherwise.
Format

UIS:WINDOWP object
Arguments

object

Any LISP object
Return Value

T or NIL
Corresponding MicroVMS Routine
None

M-ATTRIBUTE-BLOCK Function

t in a particular
Returns the sttribute block used to write outpu
to change
window output stream. You can use this function with S ETF
the attribute block.

ms.

See Chapter7 for information about window output strea
Format

UIS:WINDOW-STREAM-ATTRIBUTE-BLOCK window-output-stream
Arguments

window-output-stream

window

output

stream

previously

created

MAKE-WINDOW-OUTPUT-STREAM oOr WITH-OUTPUT-TO-WINDOW
101

with

GRAPHICS SYSTEM COMPONENTS

Return

Value

integer

output

Corresponding

that designates the
window-output-stream

MicroVMS

attribute

block

wused

write

Routine

None

WINDOW-STREAM-HORIZONTAL-OVERFLOW Function
Returns

output

stream

the
can

keyword

viewing
use

indicating

when

area.

this

The

the

attempt

keyword

function

behavior
is

can

with

made

SETF

Chapter

for

information

about

particular

window

text

the

:TRUNCATE

:WRAP.

change

window

write

either

behavior.
See

the

output

horizontal

right

You

overflow

streams.

Format

UIS:WINDOW-STREAM-HORIZONTAL-OVERFLOW

window-output-stream

Arguments

window-output-stream
A

window

output

stream

MAKE-WINDOW-OUTPUT-STREAM

Return

previously

created

with

WITH-OUTPUT-TO-WINDOW

Value

keyword

horizontal
Corresponding

(either

:TRUNCATE

overflow behavior

MicroVMS

or
:WRAP)
that
indicates
window-output-stream

the

Routine

None

WINDOW-STREAM-VERTICAL-OVERFLOW Function
Returns

keyword

output

stream when

viewing

the

:TRUNCATE.

indicating
an

area.

You

can

attempt

The
use

the
is

keyword

this

behavior
made

can

function

output

with

either
SETF

Chapter

for

information

about

102

window

beyond

: SCROLL,
to

overflow behavior.
See

particular

text

output

change

streams.

window

the

bottom

:WRAP,
the

vertical

GRAPHICS SYSTEM COMPONENTS
Format

UIS:WINDOW-STREAM-VERTICAL-OVERFLOW window—output-stream
Arguments

window-output-stream

window

output

stream

with

created

previously

MAKE-WINDOW-OUTPUT-STREAM or WITH-OUTPUT-TO-WINDOW

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

to indicate the
Returns a list of integers in the form (x1 yl x2 ty2) stream
in device
for a specified window outpu
viewing area
the
change
to
SETF
with
ion
coordinates. You can use this funct
text
t
curren
the
area,
ng
viewi
When you change the
viewing area.
)
ion where text from the stream will next be placed
posit
(the
position
new
the
and
area,
ng
is moved to the top left corner of the new viewi NIL when using SETF
viewing area is erased. If you specify a value of
ed to occupy
with WINDOW-STREAM-VIEWING-AREA, the viewlng area is chang
the entire viewport.

See Chapter 7 for information about window output
7 2.1 contains an example of this function in use.

Section

streams.

Format

UIS:WINDOW-STREAM-VIEWING-AREA window-output-stream
Arguments

window-output-stream

window

output

stream

previously

created

MAKE-WINDOW-OUTPUT~-STREAM oOr 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

i1ts

change
See

the

window

argument
a

stream’s

Chapter

object

sends

for

output.

output

which

You

the

window

cannot

use

output

SETF

stream

given

this

function

with

window.

information

about

window

output

streams.

Format

UIS:WINDOW-STREAM-WINDOW

window-output-stream

Arguments

window-output-stream
A

window

output

stream

MAKE-WINDOW-OUTPUT-STREAM

Return

previously

created

WITH-OUTPUT-TO-WINDOW

device

with

Value

A window
Corresponding

object
MicroVMS

Routine

None

Returns

integer

position

stream.

You

output

See

indicating,

which
can

text

use

will

SETF

with

output

this

position.

Chapter

for

information

about

coordinates,

from

function

window

the

specified

change

output

horizontal

window

the

output

horizontal

streams.

Format

UIS:WINDOW-STREAM-X-POSITION

window-output-stream

Arguments

window-output-stream

window

output

MAKE-WINDOW-OUTPUT-STREAM

stream
or

previously

created

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-Y-POSITION Function

the wvertical
Returns an integer indicating, in device coordinates,
w output
windo
fied
speci
a
from
t
position at which text will be outpu
wvertical
the
change
to
stream. You can use SETF with this function
output position.

See Chapter 7 for information about window output streams.
Format

UIS:WINDOW-STREAM-Y-POSITION window-output-stream
Arguments

window-output-stream

created

with

An integer indicating the vertical text position for this

window

output

stream

previously

MAKE-WINDOW-OUTPUT-STREAM oOr WITH-OUTPUT-TO-WINDOW

Return Value

output stream in device-coordinate units

corresponding MicroVMS Routine
None

WITH-OU

Macro

ble. The macro
Creates a window output stream and binds it to a varia
returns the value of

then executes its forms as an implicit PROGNd and
the last form. Finally, the stream is close and wunbound

variable to which it was bound.

See Chapter 7 for information about window output streams.

105

from the

GRAPHICS SYSTEM

COMPONENTS

Format

UIS:WITH-OUTPUT-TO-WINDOW

{declaration}*

(var

window

&REST

{form}*

options)

Arguments

var

window
A

variable

window.
body

var

The
the

which

stream

and

function

bound

binding

are

exist

executing.

window

output

only while

the

stream

forms

into

the

options
Keyword-value

specify
Return

with

pairs;

the

the allowable keywords
are
those
MAKE-WINDOW-OUTPUT-STREAM function

the

last

Value

The

value

Corresponding

MicroVMS

form

evaluated

Routine

None

106

you

can

INDEX

Page numbers in the Index in the form c-n (for example, 2-13) refer to
Page numbers in the form n (for example, 25) refer
a page in Part I.
to

page

Part

II.
-B

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

: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,

Baseline, 3-26
BEGIN-SEGMENT function,
using, 3-32

BITBLT accessor functions,
BITBLT function,
using, 4-6
BITBLT objects
creating, 4-6

3-20

Arcs

closing,

3-19

drawing,
filling,

3-21

Arrow

3-19

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
specifying, 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,

temporary, 3-32
text, 3-30
with -PIXEL suffixes,
Autorepeat

BITBLT type specifier, 2
BITBLT-DESTINATION function,
2
BITBLT-DST-H function,
2
function,
BITBLT-DST-OP
2
,
BITBLT-DST-W function
BITBLT-DST-X function, 2
BITBLT-DST-Y function, 2
BITBLT-P function, 3
BITBLT-SOURCE function, 2
BITBLT-SRC-H function, 2
BITBLT-SRC-OP function, 2
BITBLT-SRC-W function, 2
BITBLT-SRC-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,

3-9

reading from files,

source,

4-5

4-7

storing in files, 4-5
testing for validity, 4-6

3-7

enabling and disabling,

4-7

6-5

texture,

Index-1

4-7

INDEX

BITMAP-P

function,

COPY-BITBLT

function,

using,

4-6

CREATE-DISPLAY

Bitmaps,

4-1

arguments

alterin4-6
g,
reading

from

writing

using,
screen,

screen,

4-2

to,

~using,

function,

6-4

CREATE-TERMINAL
e O

2-9

2-8

CREATE-KB

4-3

function,

CREATE-TRANSFORMATION

function,

10
Cartesian
:CENTER

coordinates,

2-2

using,

argument

CREATE-WINDOW,

2-13

MOVE-VIEWPORT,

2-16

Character

cell,

and

display

optional

attribute,

list,

3-2

arguments,

specifying

3-30

window

2-11

rectangle,

2-11

:CHORD

arc-type,

3-21

CIRCLE

function,

using,

:FILL-PATTERN

attribute,

see

using,

CYCLE

3-19

CIRCLE-PIXEL

2-10

Cursor

3-20

and

function,

CREATE-WINDOW function,

3-25

:CHARACTER-SPACING

and

2-21

CREATE-UIS-STRUCTURE

and
function,

:FILL-PATTERN

Pointer

cursor

key

virtual

keyboards,

6-5

attribute,

=)
o=

3-20

using,

3-19

:DASHED

Circles

drawing,
:CLIP

3-19

Default

attribute,

:CLIP-PIXEL

3-10

attribute,

:CLIP-PIXEL

3-10

using,

attribute,

using,

3-13
map,

using,

entries

in,

information

specifying
standard,

entries

3-15
about,

in,

3-16

function,

Device

systems,

alternate,

:COPY

and

mode,

coordinate

2-21

system,

using,

type,

2-5

mode,

screen

images,

coordinates,

2-6

accuracy

and

writing

2-5

3-3

world

Device-coordinate

coordinates,

2-20

coordinates

contrasted

2-2

coordinates,
coordinates,

3-12

2-14

argument

Coordinate

screen

Device

4-6
writing

world

function,

through

operations

: COMPLEMENT

function,

SET-CLOSE-ACTION,

using,

3-15

device

2-22

invoked

3-16

getting information about,

using,

function,

6-4

DELETE-WINDOW

3-15

COMPARE-BITMAPS

2-20

2-9

3-13

changing
getting

3-16

3-6

function,
15

DELETE-TRANSFORMATION

specifying,

3-22

through

DELETE-KB

3-11

Color

block,

SET-CLOSE~-ACTION,

using :CLIP

Color,

attribute

invoked

3-11

3-22

1ine~style,

DELETE~-DISPLAY

Clipping
using

line-style,

:DASHED-DOTTED

of,

display

contrasted

list,
to

Index-2

3-3

for

3-2

world-coordinate

operations,

guidelines

operations,

3-4

3-3

using,

3-5

INDEX

using,

(Cont.)

speed

of,

3-4

DISABLE-DISPLAY-LIST function,
3-2

using,

DISABLE-KB function,
using, 6-5

3-34

re-execution, 3-2
when to use, 3-2

DISPLAY type specifier, 18
DISPLAY-WINDOWS function, 19

using,

2-9

key

enabling and disabling, 6-5
integer that represents, 6-7

:DOTTED line-style, 3-22
DUMP-BITMAP function, 19
using,

name conflicts,
ELLIPSE function,

2-19

Ellipses

drawing,

3-26

and text,

3-26

ERASE-PIXEL function,
using,

3-34

using,

7-2

3-19

3-12

FRASE-VIEWING-AREA function,

o o=

- 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-PATTERN attribute,
3-21

and aligned position,
files,

3-30

3-27

3-21

3-25

obtaining size, 3-31
specifying, 3-30

Function

keys

enabling and disabling, 6-5
integers that represent, 6-7

1-3
20

ELLIPSE-PIXEL function,
using
U&-&&j,

and text,

3-12

and window output streams, 7-2

:FILL-PATTERN attribute,
|
3-20
3-19

: ERASE-NEGATE writing mode,

and scaling,

Editor

using,

3-34

Fonts

keys

UISSFILL PATTERNS,

enabling and disabling, 6-5
integers that represent, 6-7

and

6-4

Font

4-5
= I

Editing

using,

-ERASE writing mode,

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

2-11

6-5

using,

advantages and disadantages,

using,

6-4

and display list, 3-2, 3-34
effect on viewports, 3-34

resolution, 2-7
determining, 2-7
Display lists, 3-1

DISPLAYP function,

optional window argument,

using, 3-32
ERASE function,

coordinate system, 2-8
determining size, 2-8

and ERASE function,

ENABLE-KB function,

END-SEGMENT function,

using, 6-4
Display devices

3-2

ENABLE-VIEWPORT-KB function,

DISABLE-VIEWPORT-KB function,

ENABLE-DISPLAY-LIST function,

Device-coordinate operations

Garbage

collector

and virtual displays,

2-9

and windows, 2-14
:GENERAL-PLACEMENT argument
CREATE-WINDOW, 2-13

Index-3

INDEX

:GENERAL-PLACEMENT

argument

Graphics

(Cont.)

see

MOVE-VIEWPORT,

tablets

Pointers

2-16

GET-ABS-POINTER-POSITION

function,

26
using,

5-2

HELP

GET-ALIGNED-POSITION

function,

GET-ALIGNED-POSITION-PIXEL

function,
GET-ATTRIBUTE

using,

28
function,

GET-ATTRIBUTE-LIST

~using,

using,

IMAGE

function,

display

size

using,

with,

using,

resolution with,

Interrupt

using

structures,

3-16
function,

6-6

using

arguments,

5-7

using

special

variables,

5-5

5-10

manipulation,

2-17

argument

CREATE-WINDOW,

2-14

MOVE-VIEWPORT,

2-16

|
function,

=K
-

5-2

GET-POINTER-POSITION-PIXEL

function,

K-TRM-xxXxX

KEYBOARD

5-2

GET-POSITION

constants,
type

KEYBOARDP

function,

GET-POSITION-PIXEL

function,

enabling

function,

and

characters

2-18

GET-VIEWPORT-SIZE

function,

39
:LEFT-MARGIN

function,

2-16

function,

default

3-15

GET-WS-INTENSITY

generated

by,

6-7

3-31

3-31
attribute,

3-32

default
42

|
function,

attribute,

value,

:LEFT-MARGIN-PIXEL

41
function,

6-5

GET-WINDOW-ATTRIBUTE-LIST
GET-WS-COLOR

disabling,

-]
=

2-16

GET-VISIBILITY-PIXEL

Keys

GET-VISIBILITY

specifier,

Keyclick

function,

GET-VIEWPORT-POSITION

using,

:INVISIBLE

function,

5-2

information

viewport

6-6

functions,

function,

3-31

GET-POINTER-POSITION

using,

images,

functions

pointer

passing

using,

function,

GET-KB-ATTRIBUTE-LIST

using,

4-3

function,

GET-KB-ATTRIBUTE

using,

clipping

4-3

IMAGE-PIXEL

and

GET-INTENSITY

and

4-4

2-7
GET-FONT-SIZE

function,

scaling

3-16

determining

using,

7-2

2-8

using,

6-7

keyword

determining

using,

6-5

MAKE-WINDOW-OUTPUT-STREAM,

function,

GET-DISPLAY-SIZE

using,

represents,

WITH-OUTPUT-TO-WINDOW,

5-9

GET-COLOR

using,

disabling,

that

3-8

GET-BUTTONS

using,

and

integer

:HORIZONTAL-OVERFLOW

3-8

using,

key

enabling

value,

3-32

:LINE-STYLE

attribute,

3-22

:LINE-WIDTH

attribute,

3-23

LIST-ALL-DISPLAYS

3-15

finding

Index-4

"lost"

function,

display,

2-9

INDEX

LIST-ALL-WINDOWS function,
LOAD-BITMAP function, 48
using,

Nonsquare

Numeric

pixels,

keypad

enabling
integers

4-5

2-7

keys

and disabling,
6-6
that represent, 6-7

- M -

using,

MAKE-BITMAP
using,

function,

Output

to window using

4-6

function,

55
-

using, 3-29

MEASURE-TEXT-PIXEL function,

56
Picture

3-29

see

Mice

see

:PIE

Pointers

MicroVMS workstation graphics
software, 1-2
relationship to LISP graphics,
1-2
Mouse

see

Pointers

MOVE-AREA

function,

coordinates

using,

7-5

3-18

2-14

3-18

using,

making virtual
with,

3-27

Pointer

input

keyboard active

6-5

buttons

from,

5-9

obtaining state, 5-9
responding to, 5-10
Pointer cursor, 5active pixel, 5specifying, 5~

2-13
2-13

3-17

Pointer

NEW-TEXT-LINE-PIXEL function, 60
"and :CHARACTER-SPACING, 3-30
and :LEFT-MARGIN-PIXEL, 3-32
effect on text position, 3-28
: NOBANNER argument,
:NOBORDER argument,

3-17

PLOT-PIXEL function, 64
and :FILL-PATTERN attribute,

NEW-TEXT-LINE function, 60
and :CHARACTER-SPACING, 3-30
and :LEFT-MARGIN, 3-31
effect on text position, 3-27

3-28

3-17

PLOT-ARRAY-PIXEL function, 63
and :FILL-PATTERN attribute,
using,

using,

3-17

PLOT-ARRAY function, 62
and :FILL-PATTERN attribute,
using,

2-16

o= [ =

using,

system

3-18

MOVE-WINDOW function, 59
and display list, 3-2
using,

3-21

arc-type,

see Device coordinate
-PIXEL functions, 3-3
Pixels, 2-5
dimensions, 2-7
determining, 2-7

3-33

MOVE-AREA-PIXEL function, 57
and window output streams,
using, 3-34
MOVE-VIEWPORT function, 58
using,

Pixel

elements

Pixels

square and nonsquare, 2-7
PLOT function, 61
and :FILL-PATTERN attribute,

and display list, 3-2, 3-34
effect on viewports, 3-34

using,

7-1

3-12

/-1

MEASURE-TEXT

using,

streams,

:OVERLAY writing mode, 3-12
:OVERLAY-NEGATE writing mode,

MAKE-WINDOW-OUTPUT-STREAM

using,

3-21

arc-type,

:OPEN

4-6

MAKE-BITBLT

Index-5

INDEX

Pointer

cursor

changing

(Cont.)

Segments,

appearance,

overlapping

obtaining

5- 7

areas,

position,

repositioning,

5- 8

5-4

exit,

responding

movement,

3-32

SET-ALIGNED-POSITION

5-2

responding

3-32

nesting,

5-7

effect

using,

3-28

5-4

function,

areas,

5-7

effect

specifying

action,

5-4

using,

3-28

specifying

rectangle,

Pointer

appearance,

sensitivity,

POINTER-BUTTON-n

using,

in
65

function,

5-15

segments,

function,

using,

color,

:REPLACE

writing

3-15

:REPLACE-NEGATE

mode,

3-12

using,

writing

using,

mode,

RESIZE-WINDOW

using,

function,

and display list,
interrupt
as

using,

function,

function

resize

action,

using,

function,

6-6
function,

SET-KB-COMPOSEZ

function,

SET-KB-KEYTABLE

function,

SET-LOSE-KB~-ACTION

using,

function,

using,

coordinate

Screen

coordinates

argument

type,

determining
Screen

system,

using,

2-8

using,

4-6

using,

from
in

files,

writing

screen,

function,

5-4

SET-POINTER-PATTERN

storing

function,

bounds,

reading

5-4

SET-POINTER-ACTION-PIXEL

2-8

images

altering,

2-8

function,

2-17

SET-POINTER-ACTION
Screen

6-5

SET-MOVE-INFO-ACTION
-5
=

6-6

SET-KB-COMPOSE3

2-7

3-15

specified

2-7

determining,

function,

2-19

Resolution,

SET-KB-ATTRIBUTES

3-2

6-5

SET-KB-ACTION

3-25

3-15

SET-INTENSITY

3-12
text,

function,

SET-GAIN-KB-ACTION

3-25

interrupt

2-20

SET-COLOR

6-6

5-10

using,

Realized

and

function,

5-10

SET-CLOSE-ACTION

4-2

text,

passed

function,

using,

and

5-10

READ-IMAGE~PIXEL

using,

interrupt

5-10

arguments

READ-KB-CHAR

SET-BUTTON-ACTION-PIXEL

using,

function

function,

passed

function,

3-6

using,

2-16

3-28

3-32

SET-BUTTON-ACTION

2-16
function,

function,

SET-ATTRIBUTE-PIXEL

using,
regions,

position,

3-6

arguments

PUSH-VIEWPORT

using,

5-1

POP-VIEWPORT

3-28

text

SET-ATTRIBUTE

5-15

constants,

Pointer-sensitive

using,

5-7
5-7

5-10

Pointers,

function,

position,

SET-ALIGNED-POSITION-PIXEL

overlapping

specifying

text

screen,

4-2

function,

5-7

SET-POINTER-PATT ERN-PIXEL

4-5

function,

4-3

using,

Index-6

5-7

INDEX

SET-POINTER-POSITION function,

using, 5-4
SET-POINTER-POSITION-PIXEL
function, 91
using,

5-4

using,

3-28

SET-POSITION function, 92
effect on text position,

3-28

92
SET-POSITICON-PIXEL function,
effect on text position, 3-28
using,

using,

3-21

using,

3-31

2-22

3-23

altering character spacing,
appearance of,

obtaining dimensions,

positioning,

3-26

specifying font,

writing,

and windows,

3-30

- VERTICAL-OVERFLOW keyword
MAKE-WINDOW-OUTPUT-STREAM, 7-2

3-29

WITH-OUTPUT-TO-WINDOW, 7-2

- VIEWING-AREA keyword

3-30

MAKE-WINDOW-OUTPUT-STREAM, 7-2
WITH-OUTPUT-TO-WINDOW, 7-2

3-23

function,

3-27

default position,

effect on text position, 3-27
specifying position with, 3-2 7
specifying text,
3-23

Text position,
changing,

3-24

- VIEWPORT-HEIGHT argument, 2-12
- VIEWPORT-WIDTH argument, 2-12

|
Viewports, 2-2
3-34
on,
functi
and ERASE
3-34
ion,
funct
and MOVE-AREA

controlling banner, 2-13
controlling border, 2-13
controlling location, 2-13

3-26

3-27

device-coordinate,

2-11

o= Y =

3-25

boxing, 3-29
centering, 3-29

3-31
100

UIS-ID function,
and transformations, 2-22
and virtual displays, 2-9

altering line spacing,

3-13

—J-

UIS package, 1-2
UISSFILLPATTERNS,

3-30

2-9

- TRANSPARENT writing mode,

3-30

TEST-KB function,

using,

2-22

with DELETE-TRANSFORMATION,

TEXT

Transformation ID,

7-1

output to window,

SYSSFONT,

Text,

3-24

3-23

with DELETE-DISPLAY,

3-15

Streams

- specifying text,

using, 2-21
Transformations, 2-21
creating, 2-21
deleting, 2-22

color map,

3-27

TRANSFORMATION type specifier, 99
TRANSFORMATIONP function, 99

:SOLID line-style, 3-22
SOUND-BELL function, 96
SOUND-CLICK function, 97
Sguare pixels, 2-7
Standard

3-27

using,

2-19

SHOW-FONTS function,

default position,

specifying position with, 3-27

arguments passed to interrupt

SHOW-FILL-PATTERNS function,

effect on text position,

SET-RESIZE-ACTION function, 93
and window output streams, 7- 3
function,
2-19

TEXT-PIXEL function,

and window output streams, 7-5

3-28

using,

Text position (Cont.)
obtaining, 3-28

3-26
Index-7

INDEX

Viewports

Virtual

controlling

location

absolutely,
creating

size,

controlling

visibility,

2-16

2-5

2-11

and

2-14

2-20

Window

visibility,

within,

2-16

3-34

and

areas

reading

2-14

within,

images

receiving

output

4-2

other

with

input

deletion,

from,

effect

2-18

specifying

erasing

title,

2-13

text

into,

ID,

Virtual

displays,

color

map,

creating,

2-8

deleting,

2-9

attributes,

6-5

determining,

scrolling,

3-23

and

6-1

creating,

6-4

determining
dissociating

6-4

input

by,

active,

7-2

contents,

excess

text

text,

7-2

overflow,

7-2

behavior,

7-4

determining behavior,
vertical text wrapping,

6-7

viewing

area,

erasing,
wrapping

6-5

7-3

7-2

text

asynchronously,

6-6

changing,

6-6

horizontally,

7-4

determining,
WINDOW

Index-8

type

7-2

7-3

~determining,

6-5

7-4

7-2

writing mode
from,

7-4

single

7-2

changing

6-6

from viewports,

active,

7-2

7-4

behavior,

other viewport

vertical

6-4
receiving

overflow,

behavior,

changing,

7-4

text

7-5

viewport,

generated

deleting,

7-3

7-4

window,
3-33

6-6

characters

viewport

7-6

streams

truncating
with

7-6

7-2

of WINDOW-STREAM-

determining

multiple

6-3

setting,

SETF

determining,

3-34

associating

making

Vvia

changing,
2-4

window

into,

other

7-2

font

within,

text

2-14

list,

area,

VIEWING-AREA,

2-20

keyboards,

active,

changing

within,
areas

writing

Virtual

3-23

2-2

deletion,
erasing

horizontal

result

moving

viewing

contents,

2-9

system,

effect

4-3

3-15

coordinate

7-3

7-2

display

2-17

resizing,

display

font,

7-1

movement,

into,

resizing,

creating,

Virtual

7-3

functions,

controlling writing mode,
2-20

writing

7-1

DELETE-WINDOW,

responding

images

graphics

controlling

responding

writing

streams,

characteristics,

closing

6-1
responding

3-2

2-20

automatic

3-34

from,

keyboard

2-18

list,

7-5

RESIZE-WINDOW,

moving

size,

display

altering

2-16

with

2-11

the

Delete,

by user action,
determining
moving,

ID,

Options

Change

characteristics,

erasing

Window

2-10

deleting,

(Cont.)

6-6

-W-

2-12

system,

from

2-14

2-13

controlling

creating,

input

synchronously,

off-screen,

coordinate

keyboards

receiving

2-13

generally,

default

(Cont.)

7-4

specifier,

101

7-2

INDEX

WINDOW-DISPLAY function,
using,

100

Wwindows

by user action, 2-20
with DELETE-DISPLAY,

WINDOW-STREAM-ATTRIBUTE-BLOCK
function, 101

“determining visibility,

using, 7-4
with SETF, 7-4
WINDOW-STREAM-HORIZONTAL-

OVERFLOW function,

using,
with

moving,

7-4

WITH-OUTPUT-TO-WINDOW macro, 105
using, 7-1
World coordinate system, 2-4

function, 102
using, 7-4
with SETF, 7-4
WINDOW-STREAM~-VIEWING-AREA
function, 103
7-3
SETF,

2-14

by user action, 2-18
with RESIZE-WINDOW, 2-14
responding to deletion, 2-20
writing text into, 3-23

102

WINDOW-STREAM-VERTICAL-OVERFLOW

using,
with

2-9
2-16

resizing

7-4

SETF,

(Cont.)

deleting

2-11

operations using,

3-3

World coordinates

7-3

WINDOW-STREAM-WINDOW function,
104

WINDOW-STREAM-X-POSITION function,

argument type of, 2-4
contrasted to device
coordinates, 2-6
World-coordinate operations,
accuracy of, 3-4

3-3

104

contrasted to device-coordinate

105

guidelines for using,

WINDOW-STREAM-Y-POSITION function,
WINDOWP function,
using, 2-11
Windows, 2-2

101

alternate locations,

creating,

2-10

deleting,

2-14

default characteristics,

3-3

speed of, 3-4
Writing color, 3-12
controlling, 3-11
Writing modes

2-11

controlling visibility,
coordinate system, 2-5

operations,

2-16

2-11

3-4

and :BACKGROUND-INDEX, 3-8
and window output streams, 7-2
:WRITING-INDEX attribute, 3-11
and color maps, 3-13
-WRITING-MODE attribute, 3-11
and text,

Index-9

3-25

From

Call

Chicago

312—-640-5612
815amM to 500pPm CT

Digital Equipment Corporation
Accessories & Supplies Center
1050 East Remington Road
Schaumburg, IL 60195

San Francisco

408-734—-4915

Alaska, Hawaii

603—-884-6660

815amM to 500pmMm PT

830AaM to 600 pPM ET

Digital Equipment Corporation
Accessories & Supplies Center
632 Caribbean Drive
Sunnyvale, CA 94086

408-734-4915
‘815amM t0500pm PT

New Hampshire

603—884-6660

Rest of U.S.A.,
Puerto Rico”

1-800-258-1710

830AamM toB6:00pPM ET

830 AM to6:00pPM ET

Digital Equipment Corporation
Accessories & Supplies Center
P.O. Box C52008
Nashua, NH 03061

*Prepaid orders from Puerto Rico must be placed with the local DIGITAL subsidiary (call 809-754-7575)
Canada

British Columbia

1-800-267-6146
8:00 aM to 5:00prmMm ET

Ottawa—Hull

613—-234-7726

Elsewhere

112-800-267—6146

Elsewhere

8:00 AmM to 500 PMm ET

Digital Equipment of Canada Ltd

940 Belfast Road

Ottawa, Ontario K1G 4C2
Attn: A&SG Business Manager

8:00 Am to 5:00 M ET

Digital Equipment Corporation
A&SG Business Manager”

*c/o DIGITAL's local subsidiary or approved distributor

VAX LISP/VMS Graphics

Programming Guide
AA-GH76A-TE

READER’S

COMMENTS

W’

Note: This form is for document comments only. DIGITAL will use comments

submitted on this form at the company’s discretion. If you require a written reply and

are eligible to receive one under Software Performance Report (SPR) service, submit

your comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent:
Assembly language programmer

Higher-level language programmer

Occasional programmer {experienced)
User with little programming experience
Student programmer

Other (please specify)

Name

Date

Organization

Street

City

State _

Zip Code

or Country

Do Not Tea
— Fold
r Here and Tape

=~ —

—

NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

FIRST CLASS PERMIT NO.33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

CORPORATE USE

LICATIONS

MLO5-5/E45
REET

—_—

Cut Along Dotted Line

— Fold Here

Do Not Tear