Digital PDFs

AA-MK71A-TE

July 1989

558 pages

Original

241MB

Document:	VAX LISP/VMS DECwindows Programming Guide
Order Number:	AA-MK71A-TE
Revision:	000
Pages:	558
Original Filename:

OCR Text

VAX LISP/VMS DECwindows Programming Guide
Order Number: AA-MK71A-TE

This manual is a guide to programming with the DECwindows Toolkit and Common LISP X
VAX LISP.

Revision/Update Information:

This is a new manual.

Operating System and Version: VMS 5.1
Software Version:

digital equipment corporation
maynard, massachusetts

VAX LISP 3.0

July 1989
The information in this document is subject to change without notice and should not be
construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation
assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be used or
copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not
supplied by Digital Equipment Corporation or its affiliated companies.
© Digital Equipment Corporation, Massachusetts Institute of Technology, and Texas
Instruments Incorporated. 1989.
All rights reserved.
Printed in U.S.A.
The postpaid Reader’s Comments form at the end of this document requests your critical
evaluation to assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
AI VAXstation
DEC
DECnet
DECUS
DECwindows
MicroVAX
MicroVAX II
MicroVMS

PDP
ULTRIX
ULTRIX—11
ULTRIX-32
UNIBUS
VAX
VAX LISP
VAX LISP/VMS

VAX LISP/ULTRIX
VAXstation
VAXstation II
VMS
XU I

X Window System and its derivations (X, X II, X Version 11, X Window System) are trade
marks of the Massachusetts Institute of Technology.

M LO-S837

T his docum ent was prepared using VAX DOCUMENT, Version 1.2.

Contents
P reface.....................................................................................................................................................

Part I

xxiii

Guide to the DECwindows ToolKit

Chapter 1

Overview of the DECwindows Toolkit

1.1

DECwindows Toolkit Components...........................................................................

1-2

1.2

User Interface W id g ets..............................................................................................

1-3

1.3

Creating a User In te rfa c e .........................................................................................

1-7

1.4

Calling Back to ApplicationFunctions.....................................................................

1-7

Chapter 2

Creating a User Interface

2.1

A Sample DECwindowsApplication..........................................................................

2-1

2.2

The User Interface Language ..................................................................................

2-3

2.3

High-Level Functions................................................................................................

2-7

2.4

Low-Level Functions ................................................................................................

2—9

Chapter 3

Building a DECwindows Application

3.1

Accessing the User Interface ..................................................................................
3.1.1
Initialization................................................................................................
3.1.2
Creating W idgets......................................................................................
3.1.3
Realizing the Top-Level Widget ...............................................................
3.1.4
Calling the Main Loop...............................................................................

3-1
3-1
3-2
3—3
3-4

3.2

Writing a Callback Function ....................................................................................
3.2.1
Declaring Callback Functions...................................................................
3.2.2
Accessing the Callback Argument L is t......................................................
3.2.2.1
Accessing the Widget ID ........................................................
3.2.2.2
Accessing the User-Defined Data (Tag)................................
5.2.2.3
Accessing the Callback S tructure.........................................

3-4
3-4
3-6
3-6
3-7
3-9

Part II

Reference to the DECwindows ToolKit
DWTADD-ACTIONS INTRINSIC FUNCTION............................................................
DWT:ADD-CALLBACK INTRINSIC FUNCTION..........................................................
DWTADD-CALLBACKS INTRINSIC FUNCTION.......................................................
DWTADD-CONVERTER INTRINSIC FUNCTION .....................................................
DWTADD-EVENT-HANDLER INTRINSIC FUNCTION..............................................
DWT:ADD-EXPOSURE-TO-REGION INTRINSIC FUNCTION ..................................
DWTiADD-FONT-LIST COMPOUND STRING FUNCTION.........................................
DWTADD-GRAB INTRINSIC FUNCTION...................................................................
DWTADD-INPUT INTRINSIC FUNCTION .................................................................
DWT:ADD-RAW-EVENT-HANDLER INTRINSIC FUNCTION ....................................
DWT:ADD-TIME-OUT INTRINSIC FUNCTION............................................................
DWT.ADD-WORK-PROC INTRINSIC FUNCTION .....................................................
DWTAPP-ADD-INPUT INTRINSIC FUNCTION..........................................................
DWTAPP-ADD-TIME-OUT INTRINSIC FUNCTION..................................................
DWT:APP-ADD-WORK-PROC INTRINSIC FUNCTION..............................................
DWT.-APP-CREATE-SHELL INTRINSIC FUNCTION..................................................
DWTAPP-MAIN-LOOP INTRINSIC FUNCTION..........................................................
DWTAPP-NEXT-EVENT INTRINSIC FUNCTION.......................................................
DWTAPP-PEEK-EVENT INTRINSIC FUNCTION .....................................................
DWT:APP-PENDING INTRINSIC FUNCTION............................................................
DWTAPP-PROCESS-EVENT INTRINSIC FUNCTION..............................................
DWT:ATTACHED-DB HIGH-LEVEL FUNCTION..........................................................
DWT:ATTACHED-DB-CREATE LOW-LEVEL FUNCTION .........................................
DWTATTACHED-DB-POPUP-CREATE LOW-LEVEL FUNCTION.............................
DWTiAUGMENT-TRANSLATIONS INTRINSIC FUNCTION.......................................
DWT:BEGIN-COPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTION........................
DWT:BUILD-EVENT-MASK INTRINSIC FUNCTION..................................................
DWTCALL-ACCEPT-FOCUS INTRINSIC FUNCTION ..............................................
DWT:CALL-CALLBACKS INTRINSIC FUNCTION .....................................................
DWT:CALLBACK-EXCLUSIVE INTRINSIC FUNCTION..............................................
DWT:CALLBACK-NONE INTRINSIC FUNCTION.......................................................
DWT:CALLBACK-NONEXCLUSIVE CONVENIENCE FUNCTION.............................
DWT:CALLBACK-POPDOWN INTRINSIC FUNCTION..............................................
DWT:CALLOC INTRINSIC FUNCTION .....................................................................
DWT:CANCEL-COPY-FORMAT CUT-AND-PASTE FUNCTION..................................
DWT:CANCEL-COPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTION......................
DWT:CAUTION-BOX HIGH-LEVEL FUNCTION..........................................................
DWT:CAUTION-BOX-CREATE LOW-LEVEL FUNCTION...........................................
DWT:CHILDREN CONVENIENCE FUNCTION ..........................................................
DWTCLASS INTRINSIC FUNCTION..........................................................................
DWT:CLIPBOARD-LOCK CUT-AND-PASTE FUNCTION...........................................
DWT:CLIPBOARD-UNLOCK CUT-AND-PASTE FUNCTION.......................................
DWT:CLOSE-DISPLAY INTRINSIC FUNCTION..........................................................
DWT:CLOSE-HIERARCHY DRM FUNCTION............................................................
DWT:COMMAND-APPEND HIGH-LEVEL FUNCTION ..............................................
DWT:COMMAND-ERROR-MESSAGE HIGH-LEVEL FUNCTION...............................
DWT:COMMAND-SET HIGH-LEVEL FUNCTION.......................................................
DWT:COMMAND-WINDOW HIGH-LEVEL FUNCTION..............................................
DWT:COMMAND-WINDOW-CREATE LOW-LEVEL FUNCTION...............................
DWT:CONFIGURE-WIDGET INTRINSIC FUNCTION................................................
DWT:CONVERT INTRINSIC FUNCTION...................................................................
DWT:GONVERT-CASE INTRINSIC FUNCTION..........................................................

DWT-1
DWT-1
DWT-1
DWT-2
DWT-2
DWT-2
DWT-3
DWT-3
DWT-3
DWT-4
DWT-^t
DWT-4
DWT-5
DWT-5
DWT-5
DWT-8
DWT-8
DWT-6
DWT-7
DWT-7
DWT-7
DWT-8
DWT-8
DWT-8
DWT-9
DWT-9
DWT-10
DWT-10
DWT-10
DWT-11
DWT-11
DWT-11
DWT-12
DWT-12
DWT-12
DWT-13
DWT-13
DWT-14
DWT-14
DWT-14
DWT-15
DWT-15
DWT-15
DWT-16
DWT-16
DWT-16
DWT-17
DWT-17
DWT-17
DWT-18
DWT-18
DWT-18

DWT:COPY-FROM-CLIPBOARD CUT-AND-PASTE FUNCTION...............................
DWT:COPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTION....................................
DWT:CREATE-APPLICATION-CONTEXT INTRINSIC FUNCTION.............................
DWT:CREATE-APPLICATION-SHELL INTRINSIC FUNCTION..................................
DWT:CREATE-FONT-LIST COMPOUND STRING FUNCTION..................................
DWT:CREATE-MANAGED-WI DGET INTRINSIC FUNCTION....................................
DWT:CREATE-POPUP-SHELL INTRINSIC FUNCTION ...........................................
DWT:C REATE-Wl DG ET INTRINSIC FUNCTION.......................................................
DWT:CREATE-WlNDOW INTRINSIC FUNCTION .....................................................
DWT:CSBYTECMP COMPOUND STRING FUNCTION.............................................
DWTCSEMPTY COMPOUND STRING FUNCTION..................................................
DWT:CS-STRING COMPOUND STRING FUNCTION................................................
DWT:CSTRCAT COMPOUND STRING FUNCTION..................................................
DWT:CSTRCPY COMPOUND STRING FUNCTION..................................................
DWT:CSTRLEN COMPOUND STRING FUNCTION..................................................
DWT:CSTRNCAT COMPOUND STRING FUNCTION................................................
DWT:CSTRNCPY COMPOUND STRING FUNCTION................................................
DWT:DATABASE INTRINSIC FUNCTION...................................................................
DWT:DESTROY-APPLICATION-CONTEXT INTRINSIC FUNCTION ........................
DWT:DESTROY-GC INTRINSIC FUNCTION..............................................................
DWT:DESTROY-WIDGET INTRINSIC FUNCTION....................................................
DWT:DIALOG-BOX HIGH-LEVEL FUNCTION............................................................
DWT.DIALOG-BOX-CREATE LOW-LEVEL FUNCTION.............................................
DWT:DIALOG-BOX-POPUP-CREATE LOW-LEVEL FUNCTION...............................
DWT:DIRECT-CONVERT INTRINSIC FUNCTION.....................................................
DWT:DISOWN-SELECTION INTRINSIC FUNCTION ................................................
DWT:DISPATCH-EVENT INTRINSIC FUNCTION.......................................................
DWT:DISPLAY INTRINSIC FUNCTION.....................................................................
DWT:DISPLAY-CS-MESSAGE CONVENIENCE FUNCTION ....................................
DWT:DISPLAY-INITIALIZE INTRINSIC FUNCTION ..................................................
DWT:D ISP LAY-VMS-M ESSAG E CONVENIENCE FUNCTION.................................
DWT:DRM-FREE-RESOURCE-CONTEXT DRM FUNCTION....................................
DWT:DRM-GET-RESOURCE-CONTEXT DRM FUNCTION......................................
DWT:DRM-HGET-INDEXED-LITERAL DRM FUNCTION...........................................
DWT:DRM-RC-BUFFER DRM FUNCTION.................................................................
DWT:DRM-RC-SET-TYPE DRM FUNCTION..............................................................
DWT:DRM-RC-SIZE DRM FUNCTION........................................................................
DWT:DRM-RC-TYPE DRM FUNCTION.....................................................................
DWT:DWTHELP HIGH-LEVEL FUNCTION.................................................................
DWT:DWTWINDOW INTRINSIC FUNCTION ............................................................
DWT:END-COPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTION ..........................
DWT:ERROR-MSG INTRINSIC FUNCTION..............................................................
DWT:FETCH-INTERFACE-MODULE DRM FUNCTION.............................................
DWT:FETCH-SET-VALUES DRM FUNCTION............................................................
DWT:FETCH-WIDGET DRM FUNCTION...................................................................
DWT:FETCH-WIDGET-OVERRIDE DRM FUNCTION................................................
DWT:FILE-SELECTION HIGH-LEVEL FUNCTION.....................................................
DWT:FILE-SELECTION-CREATE LOW-LEVEL FUNCTION......................................
DWT:FILE-SELECTION-DO-SEARCH HIGH-LEVEL FUNCTION...............................
DWT:FREE INTRINSIC FUNCTION ..........................................................................

DWT-19
DWT-19
DWT-20
DWT-20
DWT-21
DWT-21
DWT-21
DWT-22
DWT-22
DWT-22
DWT-23
DWT-23
DWT-23
DWT-24
DWT-24
DWT-24
DWT-25
DWT-25
DWT-25
DWT-26
DWT-26
DWT-26
DWT-27
DWT-27
DWT-27
DWT-28
DWT-28
DWT-28
DWT-29
DWT-29
DWT-30
DWT-30
DWT-31
DWT-31
DWT-32
DWT-32
DWT-32
DWT-33
DWT-33
DWT-33
DWT-34
DWT-34
DWT-35
DWT-35
DWT-36
DWT-36
DWT-37
DWT-37
DWT-38
DWT-38

DWT:GET-APPLICATION-RESOURCES INTRINSIC FUNCTION.............................
DWT:GET-DISPLAY CONVENIENCE FUNCTION.....................................................
DWT:GET-ERROR-DATABASE INTRINSIC FUNCTION...........................................
DWT:GET-ERROR-DATABASE-TEXT INTRINSIC FUNCTION..................................
DWT:GET-GC INTRINSIC FUNCTION........................................................................
DWT.'GET-NEXT-SEGMENT COMPOUND STRING FUNCTION .............................
DWT:GET-RESOURCE-LIST INTRINSIC FUNCTION................................................
DWT:GET-SCREEN CONVENIENCE FUNCTION.....................................................
DWT:GET-SELECTION-TIMEOUT INTRINSIC FUNCTION......................................
DWT:GET-SELECTION-VALUE INTRINSIC FUNCTION...........................................
DWT:GET-SELECTION-VALUE-INCR INTRINSIC FUNCTION.................................
DWT:GET-SELECTION-VALUES INTRINSIC FUNCTION.........................................
DWT:GET-SELECTION-VALUES-INCR INTRINSIC FUNCTION...............................
DWT:GET-SUBRESOURCES INTRINSIC FUNCTION ..............................................
DWTGET-SUBVALUES INTRINSIC FUNCTION.......................................................
DWT:GET-VALUES INTRINSIC FUNCTION..............................................................
DWT:HAS-CALLBACKS INTRINSIC FUNCTION................... ...................................
DWT:HELP HIGH-LEVEL FUNCTION........................................................................
DWT:HELP-CREATE LOW-LEVEL FUNCTION.........................................................
DWTINIT-GET-SEGMENT COMPOUND STRING FUNCTION..................................
DWTINITIALIZE INTRINSIC FUNCTION...................................................................
DWT:INITIALIZE-DRM DRM FUNCTION...................................................................
DWT:INQUIRE-NEXT-PASTE-COUNT CUT-AND-PASTE FUNCTION......................
DWT:INQUIRE-NEXT-PASTE-FORMAT CUT-AND-PASTE FUNCTIO N...................
DWT:INQUIRE-NEXT-PASTE-LENGTH CUT-AND-PASTE FUNCTION ...................
DWTINSTALL-ACCELERATORS INTRINSIC FUNCTION.........................................
DWT:INSTALL-ALL-ACCELERATORS INTRINSIC FUNCTION.................................
DWT:IS-COMPOSITE INTRINSIC FUNCTION............................................................
DWT:IS-MANAGED INTRINSIC FUNCTION..............................................................
DWT:IS-REALIZED INTRINSIC FUNCTION..............................................................
DWT:IS-SENSITIVE INTRINSIC FUNCTION..............................................................
DWT:IS-SUBCLASS INTRINSIC FUNCTION..............................................................
DWT:LABEL HIGH-LEVEL FUNCTION .....................................................................
DWT:LABEL-CREATE LOW-LEVEL FUNCTIO N .......................................................
DWT:LABEL-GADGET-CREATE GADGET FUNCTION..............................................
DWT:LATIN1-STRING COMPOUND STRING FUNCTION.........................................
DWT:LIST-BOX HIGH-LEVEL FU N C TIO N .................................................................
DWT1IST-BOX-ADD-ITEM HIGH-LEVEL FUNCTION................................................
DWT1IST-BOX-CREATE LOW-LEVEL FUNCTION..................................................
DWT1IST-BOX-DELETE-ITEM HIGH-LEVEL FUNCTION.........................................
DWT1IST-BOX-DELETE-POS HIGH-LEVEL FUNCTIO N.........................................
DWT1IST-BOX-DESELECT-ALL-ITEMS HIGH-LEVEL FUNCTION..........................
DWT1IST-BOX-DESELECT-ITEM HIGH-LEVEL FUNCTION....................................
DWT1IST-BOX-DESELECT-POS HIGH-LEVEL FU NCTIO N....................................
DWT:LIST-BOX-ITEM-EXISTS HIGH-LEVEL FUNCTION .........................................
DWT:LIST-BOX-SELECT-ITEM HIGH-LEVEL FUNCTION.........................................
DWT1IST-BOX-SELECT-POS HIGH-LEVEL FUNCTION .........................................
DWT1IST-BOX-SET-HORIZ-POS HIGH-LEVEL FUNCTION....................................
DWT1IST-BOX-SET-ITEM HIGH-LEVEL FUNCTION................................................
DWT1IST-BOX-SET-POS HIGH-LEVEL FUNCTIO N ....... ........................................
DWT:LIST-PENDING-ITEMS CUT-AND-PASTE FUNCTION ....................................
DWT:MAIN-LOOP INTRINSIC FUNCTION.................................................................
DWT:MAIN-WINDOW HIGH-LEVEL FUNCTION.......................................................
DWT:MAIN-WINDOW-CREATE LOW-LEVEL FUNCTION.........................................
DWT:MAIN-WINDOW-SET-AREAS HIGH-LEVEL FUNCTION ..................................

DWT-38
DWT-39
DWT-39
DWT-39
DWT-40
DWT-40
DWT-41
DWT-41
DWT-41
DWT-41
DWT-42
DWT-42
DWT-43
DWT-43
DWT-44
DWT-44
DWT-44
DWT-45
DWT-45
DWT-45
DWT-46
DWT-46
DWT-46
DWT-47
DWT-47
DWT-48
DWT-48
DWT-49
DWT-49
DWT-49
DWT-49
DWT-50
DWT-50
DWT-50
DWT-51
DWT-51
DWT-51
DWT-52
DWT-52
DWT-53
DWT-53
DWT-53
DWT-54
DWT-54
DWT-54
DWT-55
DWT-55
DWT-55
DWT-56
DWT-56
DWT-56
DWT-57
DWT-57
DWT-57
DWT-58

DWT:MAKE-GEOMETRY-REQUEST INTRINSIC FUNCTION....................................
DWT:MAKE-RESIZE-REQUEST INTRINSIC FUNCTION...........................................
DWT:MALLOC INTRINSIC FUNCTIO N......................................................................
DWT:MANAGE-CHILD INTRINSIC FUNCTION..........................................................
DWT:MANAGE-CH!LDREN INTRINSIC FUNCTION..................................................
DWTMAP-WIDGET INTRINSIC FUNCTION..............................................................
DWT:MENU HIGH-LEVEL FUNCTION........................................................................
DWTMENU-BAR HIGH-LEVEL FUNCTION..............................................................
DWT:MENU-BAR-CREATE LOW-LEVEL FUNCTION................................................
DWT:MENU-CREATE LOW-LEVEL FUNCTION.........................................................
DWT:MENU-POPUP-CREATE LOW-LEVEL FUNCTION...........................................
DWT:MENU-POSITION HIGH-LEVEL FUNCTION.....................................................
DWT:MENU-PULLDOWN-CREATE LOW-LEVEL FUNCTION....................................
DWT:MERGE-ARG-LISTS INTRINSIC FUNCTION.....................................................
DWT:MESSAGE-BOX HIGH-LEVEL FUNCTION.......................................................
DWT:MESSAGE-BOX-CREATE LOW-LEVEL FUNCTION.........................................
DWT:MOVE-WIDGET INTRINSIC FUNCTION............................................................
DWT:NAME-TO-WlDGET INTRINSIC FUNCTION.....................................................
DWT:NEXT-EVENT INTRINSIC FUNCTION..............................................................
DWT:NUMBER-CHILDREN CONVENIENCE FUNCTION .........................................
DWTOPEN-DISPLAY INTRINSIC FUNCTION ..........................................................
DWT:OPEN-HIERARCHY DRM FUNCTION..............................................................
DWT:OPTION-MENU HIGH-LEVEL FUNCTION .......................................................
DWT:OPTION-MENU-CREATE LOW-LEVEL FUNCTIO N.........................................
DWT:OVERRI DE-TRANSLATIONS INTRINSIC FUNCTION......................................
DWT:OWN-SELECTION INTRINSIC FUNCTION.......................................................
DWT:OWN-SELECTION-INCREMENTAL INTRINSIC FUNCTION.............................
DWT:PARENT INTRINSIC FUNCTION........................................................................
DWT:PARSE-ACCELERATOR-TABLE INTRINSIC FUNCTION..................................
DWT:PARSE-TRANSLATION-TABLE INTRINSIC FUNCTION ..................................
DWT:PEEK-EVENT INTRINSIC FUNCTION..............................................................
DWTPENDING INTRINSIC FUNCTION.....................................................................
DWT:POPDOWN INTRINSIC FUNCTION...................................................................
DWTPOPUP INTRINSIC FUNCTION........................................................................
DWT:PROCESS-EVENT INTRINSIC FUNCTION.......................................................
DWT:PULL-DOWN-M ENU-ENTRY HIGH-LEVEL FUNCTION....................................
DWT:PULL-DOWN-MENU-ENTRY-CREATE LOW-LEVEL FUNCTION......................
DWT:PULL-DOWN-MENU-ENTRY-HILITE HIGH-LEVEL FUNCTION........................
DWT:PUSH-BUTTON HIGH-LEVEL FUNCTION.......................................................
DWT:PUSH-BUTTON-CREATE LOW-LEVEL FUNCTION.........................................
DWT:PUSH-BUTTON-GADGET-CREATE GADGET FUNCTION...............................
DWT:QUERY-GEOMETRY INTRINSIC FUNCTION..................................................
DWT:RADIO-BOX HIGH-LEVEL FUNCTION..............................................................
DWT:RADIO-BOX-CREATE LOW-LEVEL FUNCTION................................................
DWT:REALIZE-WIDGET INTRINSIC FUNCTION.......................................................
DWT:REALLOC INTRINSIC FUNCTION ...................................................................
DWT:RECOPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTION...............................

DWT-58
DWT-59
DWT-r59
DWT-59
DWT-60
DWT-60
DWT-60
DWT-61
DWT-61
DWT-61
DWT-62
DWT-62
DWT-62
DWT-63
DWT-63
DWT-64
DWT-64
DWT-64
DWT-65
DWT-65
DWT-65
DWT-66
DWT-66
DWT-66
DWT-67
DWT-67
DWT-68
DWT-68
DWT-68
DWT-69
DWT-69
DWT-69
DWT-70
DWT-70
DWT-70
DWT-71
DWT-71
DWT-71
DWT-72
DWT-72
DWT-73
DWT-73
DWT-73
DWT-74
DWT-74
DWT-74
DWT-75

DWT:REGISTER-CASE-CONVERTER INTRINSIC FU N C TIO N ...............................
DWT:REGISTER-CLASS DRM FUNCTION ..............................................................
DWT:REGISTER-DRM-NAMES DRM FUNCTION.....................................................
DWT:REMOVE-ALL-CALLBACKS INTRINSIC FUNCTION ......................................
DWT:REMOVE-CALLBACK INTRINSIC FUNCTION..................................................
DWT:REMOVE-CALLBACKS INTRINSIC FUNCTION................................................

DWT-75
DWT-76
DWT-76
DWT-76
DWT-77
DWT-77

DWT:REMOVE-EVENT-HANDLER INTRINSIC FUNCTION......................................
DWT:REMOVE-GRAB INTRINSIC FU NCTIO N .........................................................
DWTREMOVE-INPUT INTRINSIC FUNCTION.........................................................
DWT:REMOVE-RAW-EVENT-HANDLER INTRINSIC FUNCTION.............................
DWT:REMOVE-TIM E-OUT INTRINSIC FUNCTIO N ..................................................
DWT:REMOVE-WORK-PROC INTRINSIC FUNCTION..............................................
DWTRESIZE-WIDGET INTRINSIC FUNCTION.........................................................
DWT:RESIZE-WINDOW INTRINSIC FUNCTION.......................................................
DWTrSCALE HIGH-LEVEL FUNCTION......................................................................
DWT:SCALE-CREATE LOW-LEVEL FUNCTION.......................................................
DWT:SCALE-GET-SLIDER HIGH-LEVEL FUNCTION................................................
DWT:SCALE-SET-SLIDER HIGH-LEVEL FUNCTION................................................
DWTrSCREEN INTRINSIC FUNCTIO N......................................................................
DWT:SCROLL-BAR HIGH-LEVEL FUNCTION .........................................................
DWT:SCROLL-BAR-CREATE LOW-LEVEL FUNCTION ...........................................
DWT:SCROLL-BAR-GET-SLIDER HIGH-LEVEL FUNCTION....................................
DWT:SCROLL-BAR-SET-SLIDER HIGH-LEVEL FUNCTION....................................
DWT:SCROLL-WINDOW HIGH-LEVEL FUNCTION..................................................
DWT:SCROLL-WINDOW-CREATE LOW-LEVEL FUNCTION....................................
DWT:SCROLL-WINDOW-SET-AREAS HIGH-LEVEL FUNCTION.............................
DWTSELECTION HIGH-LEVEL FUNCTION..............................................................
DWT:SELECTION-CREATE LOW-LEVEL FUNCTION ..............................................
DWT:SEPARATOR HIGH-LEVEL FUNCTION............................................................
DWT:SEPARATOR-CREATE LOW-LEVEL FUNCTION..............................................
DWT.SEPARATOR-GADGET-CREATE GADGET FUNCTION ..................................
DWT:SET-ERROR-HANDLER INTRINSIC FUNCTION.............................................
DWTSET-ERROR-MSG-HANDLER INTRINSIC FUNCTION....................................
DWT:SET-KEYBOARD-FOCUS INTRINSIC FUNCTION...........................................
DWT:SET-KEY-TRANSLATOR INTRINSIC FUNCTION.............................................
DWT:SET-MAPPED-WHEN-MANAGED INTRINSIC FUNCTION...............................
DWT:SET-SELECTION-TIMEOUT INTRINSIC FUNCTION ......................................
DWT:SET-SENSITIVE INTRINSIC FUNCTION .........................................................
DWT:SET-SUBVALUES INTRINSIC FUNCTIO N.......................................................
DWT:SET-VALUES INTRINSIC FUNCTION ..............................................................
DWT:SET-WARNING-HANDLER INTRINSIC FUNCTION.........................................
DWT:SET-WARNING-MSG-HANDLER INTRINSIC FUNCTION ...............................
DWTS-TEXT HIGH-LEVEL FUNCTION.....................................................................
DWT:S-TEXT-CLEAR-SELECTION HIGH-LEVEL FUNCTIO N..................................
DWT:S-TEXT-CREATE LOW-LEVEL FUNCTION.......................................................
DWT:S-TEXT-GET-EDITABLE HIGH-LEVEL FUNCTION...........................................
DWT:S-TEXT-GET-MAX-LENGTH HIGH-LEVEL FUNCTION....................................
DWT:S-TEXT-GET-SELECTION HIGH-LEVEL FUNCTIO N ......................................
DWT.'S-TEXT-GET-STRING HIGH-LEVEL FUNCTION..............................................
DWT:S-TEXT-REPLACE HIGH-LEVEL FU N C TIO N ..................................................
DWT:S-TEXT-SET-EDITABLE HIGH-LEVEL FUNCTION...........................................
DWT:S-TEXT-SET-MAX-LENGTH HIGH-LEVEL FUNCTION....................................
DWT:S-TEXT-SET-SELECTION HIGH-LEVEL FUNCTION ......................................
DWT:S-TEXT-SET-STRING HIGH-LEVEL FU NCTIO N..............................................
DWTSTRING COMPOUND STRING FUNCTION.....................................................
DWT:SUPERCLASS INTRINSIC FUNCTION ............................................................
DWT:TOGGLE-BUTTON HIGH-LEVEL FUNCTION..................................................
DWT:TOGGLE-BUTTON-CREATE LOW-LEVEL FUNCTION....................................
DWT:TOGGLE-BUTTON-GADGET-CREATE GADGET FUNCTION..........................
DWT:TOGGLE-BUTTON-GET-STATE HIGH-LEVEL FUNCTION...............................

DWT-77
DWT-78
DWT-78
DWT-78
DWT-79
DWT-79
DWT-79
DWT-80
DWT-80
DWT-81
DWT-81
DWT-81
DWT-82
DWT-82
DWT-83
DWT-83
DWT-84
DWT-84
DWT-84
DWT-85
DWT-85
DWT-86
DWT-86
DWT-86
DWT-87
DWT-87
DWT-87
DWT-88
DWT-88
DWT-88
DWT-89
DWT-89
DWT-89
DWT-90
DWT-90
DWT-90
DWT-91
DWT-91
DWT-91
DWT-92
DWT-92
DWT-92
DWT-93
DWT-93
DWT-93
DWT-94
DWT-94
DWT-94
DWT-95
DWT-95
DWT-95
DWT-96
DWT-96
DWT-96

DWT:TOGGLE-BUTTON-SET-STATE HIGH-LEVEL FUNCTION................................. DWT-97
DWT:TOOLKIT-INITIALIZE INTRINSIC FU NCTIO N .................................................... DWT-97
DWT:TRANSLATE-COORDS INTRINSIC FUNCTION.................................................. DWT-97
DWT:TRANSLATE-KEYCODE INTRINSIC FUNCTION................................................ DWT-98
DWT:UNDO-COPY-TO-CLIPBOARD CUT-AND-PASTE FUNCTIO N.......................... DWT-98
DWT:UNINSTALL-TRANSLATIONS INTRINSIC FUNCTION ...................................... DWT-98
DWT:UNMANAGE-CHILD INTRINSIC FUNCTION....................................................... DWT-99
DWT:UNMANAGE-CHILDREN INTRINSIC FUNCTION................................................ DWT-99
DWT:UNREALIZE-WIDGET INTRINSIC FUNCTION.................................................... DWT-99
DWT:VMS-CLEAR-STRING CONVENIENCE FUNCTION........................................... DWT-100
DWT:VMS-FREE-ARGNAMES CONVENIENCE FUNCTION...................................... DWT-100
DWT:VMS-SET-ARG CONVENIENCE FUNCTION....................................................... DWT-100
DWT:VMS-SET-CALLBACK-ARG CONVENIENCE FUNCTION.................................... DWT-101
DWT:VMS-SET-DESC-ARG CONVENIENCE FUNCTION........................................... DWT-101
DWT:WARNING INTRINSIC FUNCTIO N......................................................................DWT-101
DWT:WARNING-MSG INTRINSIC FUNCTION ............................................................ DWT-101
DWT:WIDGET-TO-APPLICATION-CONTEXT INTRINSIC FUNCTION........................ DWT-102
DWT:WINDOW INTRINSIC FUNCTION........................................................................ DWT-102
DWT:WINDOW-CREATE LOW-LEVEL FUNCTION ..................................................... DWT-102
DWT:WINDOW-TO-WIDGET INTRINSIC FUNCTION.................................................. DWT-103
DWT:WORK-BOX HIGH-LEVEL FUNCTION.................................................................DWT-103
DWT:WORK-BOX-CREATE LOW-LEVEL FUNCTION.................................................. DWT-104
DWT:XTERROR INTRINSIC FUNCTION......................................................................DWT-104
DWT:XTSTRING COMPOUND STRING FUNCTIO N .................................................. DWT-104
DWT:XTWARNING INTRINSIC FUNCTION ................................................................. DWT-105

Part III

Guide to Programming CLX

Chapter 4

Programming Overview of CLX

4.1

Overview of C L X .......................................................................................................

4-1

4.2

CLX Data Types

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

4-2

4.3

A Sample CLX P ro g ram ...........................................................................................

4—5

Chapter 5

Managing the Client-Server Connection

5.1

Opening the Display

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

5-1

5.2

Getting Information About theDisplay and S c re e n ...............................................

5-2

5.3

Sending Requests to the S e rv e r.............................................................................

5-4

5.4

Closing the D is p la y ...................................................................................................

5-4

Chapter 6
6.1

Creating W in d o w s.....................................................................................................

6-1

6.2

Destroying Windows ...................................................................

6-3

6.3

Mapping and Unmapping W in dow s........................................................................

6-4

6.4

Associating Properties with Windows ...................................................................
6.4.1
Communicating with the Window Manager ...........................................
6.4.2
Exchanging Properties Between Clients ................................................

6-5
6-7
6-9

6.5

Stacking W indow s.....................................................................................................

6- 10

6.6

Changing Window Attributes

6-10

Chapter 7

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

Defining Graphics Characteristics

7.1

Creating a Graphics Context

7.2

Querying and Setting GContextComponents

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

7-4

7.3

Copying and Freeing G C ontexts.............................................................................

7-5

7.4

Using GContexts Efficiently ....................................................................................

7-6

Chapter 8

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

7-1

Using Color

8.1

Pixels and Colormaps .....................................................................

8-1

8.2

Matching Color Requirements to Screen Types ..................................................

8-2

8.3

Sharing Color R esources.........................................................................................
8.3.1
Using Named Colors ...............................................................................
8.3.2
Specifying Exact Color V a lu e s.................................................................

8-3
8-3
8-4

8.4

Allocating Colors for ExclusiveUse .......................................................................
8.4.1
Specifying a C olorm ap.............................................................................
8.4.2
Allocating Color Cells .............................................................................

8-4
8-5
8-5

8.5

Storing Color Values ................................................................................................

8-6

8.6

Freeing Color Resources .........................................................................................

8-7

8.7

Querying Colormap Entries

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

8-8

9.1

Drawing Points ..........................................................................................................

9-1

9.2

Drawing L in e s ............................................................................................................

9-4

9.3

Drawing and Filling Rectangles

9-6

Chapter 9

Working with Windows

Graphics Functions

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

9.4

Drawing and Filling Arcs .........................................................................................

9-7

9.5

Clearing and Copying Areas

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

9-9

9.6

Creating C u rs o rs .......................................................................................................

9-10

Chapter 10

Using Pixmaps and Images

10.1

Creating and Freeing Pixmaps ................................................................................

10-1

10.2

Creating and Managing Bitmap Files

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

10-2

10.3

Working with Im a g e s .................................................................................................
10.3.1
Getting Images from the Server ............................................................
10.3.2
Displaying Im a g e s....................................................................................

10-3
10—6
10-6

Chapter 11

Writing Text

11.1

Characters and Fonts

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

11-1

11.2

Specifying F o n ts .......................................................................................................

11-3

11.3

Computing Text Size ................................................................................................

11-5

11.4

Drawing Text on the S c re e n ....................................................................................

11-6

Chapter 12

Event Functions

12.1

Selecting Events .......................................................................................................
12.1.1
Constructing Event Masks ......................................................................
12.1.2
Specifying an Event Mask ......................................................................
12.1.3
Changing an Event M a s k ........................................................................

12.2

Processing Events

12-1
12-2
12-4
12-4

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

12-5

12.2.1

Locking the Event Q u e u e ..................................................................................

12—6

12.2.2
12.2.3
12.2.4
12.2.5

Finding the Length of the Event Queue ................................................
Handling Events in the Queue ..............................................................
Adding an Event to the Queue ..............................................................
Removing an Event from the Queue .....................................................

12-6
12-6
12-9
12-9

12.3

Controlling Events ...................................................................................................
12.3.1
Grabbing the Pointer ...............................................................................
12.3.2
Grabbing the Keyboard ..........................................................................
12.3.3
Grabbing the Server ...............................................................................
12.3.4
Allowing Events ......................................................................................

12-9
12-11
12-12
12-14
12-14

12.4

Sending E v e n ts ..........................................................................................................

12-15

12.5

Event K e y s .................................................................................................................

12-16

Chapter 13

Window and Session Management

13.1

Reparenting Windows

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

13-1

13.2

Customizing the Keyboardand the Pointer ...........................................................
13.2.1
Ringing the Bell ......................................................................................
13.2.2
Keyboard and Pointer Mappings ............................................................
13.2.3
Keycode Mapping ....................................................................................
13.2.4
Keyboard and Pointer Controls ..............................................................
13.2.5
Setting Pointer Controls ..........................................................................

13—1
13-2
13-2
13—3
13-5
13-6

13.3

Using the Screen S a v e r ...........................................................................................
13.3.1
Querying the Screen Saver ...................................................................
13.3.2
Setting the Screen Saver ........................................................................
13.3.3
Enabling the Screen S a v e r.....................................................................

13-7
13-7
13—7
13—8

13.4

Controlling Network A c c e s s ....................................................................................
13.4.1
Adding and Removing H o s ts ...................................................................
13.4.2
Getting Information About Hosts ............................................................

13-8
13—9
13—9

13.5

Closing the Connection ............................................................................................
13.5.1
Deallocating Resources ..........................................................................
13.5.2
Disconnecting Other Clients ...................................................................
13.5.3
Saving W in d o w s ......................................................................................

13-10
13—10
13—10
13-11

13.6

Finding Extensions ..................................................................................................

13-11

Part IV

Reference to Common LISP X
CLX:ACCESS-CONTROL FUNCTION...........................................................................
CLX-1
CLX:ACCESS-HOSTS FUNCTION................................................................................
CLX-1
CLX:ACTIVATE-SCREEN-SAVER FUNCTION............................................................
CLX-2
CLX:ADD-ACCESS-HOST FUNCTION .....................................................................
CLX-2
CLX:ADD-TO-SAVE-SET FUNCTION ........................................................................
CLX-3
CLX:ALIST TYPE SPECIFIER....................................................................................
CLX-3
CLX:ALLOC-COLOR FUNCTION...............................................................................
CLX-3
CLX:ALLOC-COLOR-CELLS FUNCTION...................................................................
CLX-4
CLX:ALLOC-COLOR-PLANES FUNCTION.................................................................
CLX-5
CLX:ALLOW-EVENTS FUNCTION.............................................................................
CLX-6
CLX:ANGLE TYPE SPECIFIER.................................................................................
CLX-7
CLX-.ARC-SEQ TYPE SPECIFIER .............................................................................
CLX-7
CLX:ARRAY-INDEX TYPE SPECIFIER......................................................................
CLX-7
CLX:ATOM-NAME FUNCTION....................................................................................
CLX-7
CLX:BELL FUNCTIO N................................................................................................
CLX-8
CLX:BIT-GRAVITY TYPE SPECIFIER........................................................................
CLX-8
CLX:BITMAP TYPE SPECIFIER.................................................................................
CLX-9
CLX:BITMAP-FORMAT STRUCTURE........................................................................
CLX-9
CLX:BITMAP-FORMAT-LSB-FIRST-P FUNCTION.....................................................
CLX-9
CLX:BITMAP-FORMAT-P FUNCTION........................................................................ CLX-10
CLX:BITMAP-FORMAT-PAD FUNCTION................................................................... CLX-10
CLX:BITMAP-FORMAT-UNIT FUNCTION..................................................................... CLX-11
CLX:BOOLEAN TYPE SPECIFIER..............................................................................
CLX-11
CLX:CARD8 TYPE SPECIFIER...................................................................................
CLX-11
CLX:CARD16 TYPE S PEC IFIER.................................................................................. CLX-11
CLX:CARD29 TYPE S P E C IFIER ............................................................................... CLX-12
CLX:CHANGE-ACTIVE-POINTER-GRAB FUNCTION................................................ CLX-12

CLX:CHANGE-KEYBOARD-CONTROL FUNCTION..................................................
CLX:CHANGE-KEYBOARD-MAPPING FUNCTION..................................................
CLX:CHANGE-POINTER-CONTROL FUNCTION .....................................................
CLX:CHANGE-PROPERTY FUNCTION......................................................................
CLX:CHARACTER->KEYSYMS FUNCTION...............................................................
CLX:CHAR-ASCENT FUNCTION...............................................................................
CLX:CHAR-ATTRIBUTES FUNCTION........................................................................
CLXrCHAR-DESCENT FUNCTION.............................................................................
CLX:CHAR-LEFT-BEARING FUNCTIO N ...................................................................
CLX:CHAR-RIGHT-BEARING FUNCTIO N.................................................................
CLX:CHAR-WIDTH FUNCTION..................................................................................
CLX:CIRCULATE-WINDOW-DOWN FUNCTION.......................................................
CLX:CIRCULATE-WINDOW-UP FUNCTION..............................................................
CLX:CLEAR-AREA FU NCTIO N..................................................................................
CLX:CLOSE-DISPLAY FUNCTION.............................................................................
CLX:CLOSE-DOWN-MODE FUNCTION......................................................................
CLX:CLOSE-FONT FUNCTION..................................................................................
CLX:COLOR STRUCTURE.........................................................................................
CLX:COLOR-BLUE FUNCTION..................................................................................
CLX:COLOR-GREEN FUNCTION...............................................................................
CLX:COLORMAP STRUCTURE..................................................................................
CLX:COLORMAP-DISPLAY FUNCTION......................................................................
CLX:COLORMAP-EQUAL FUNCTION........................................................................
CLX:COLORMAP-ID FU N C TIO N ...............................................................................
CLX:COLORMAP-P FUNCTION..................................................................................
CLX:COLOR-P FUNCTION.........................................................................................
CLX:COLOR-RED FUNCTION....................................................................................
CLX'.COLOR-RGB FUNCTION....................................................................................
CLX:CONVERT-SELECTION FUNCTION...................................................................
CLX:COPY-AREA FUNCTION....................................................................................
CLX:COPY-COLORMAP-AND-FREE FUNCTION .....................................................
CLX:COPY-GCONTEXT FUNCTION...........................................................................
CLX:COPY-GCONTEXT-COMPONENTS FUNCTION................................................
CLX:COPY-IMAGE FUNCTION ..................................................................................
CLX:COPY-PLANE FUNCTION ..................................................................................
CLX:CREATE-COLORMAP FUNCTION......................................................................
CLX:CREATE-CURSOR FUNCTION...........................................................................
CLX:CREATE-GCONTEXT FUNCTION......................................................................
CLX:CREATE-GLYPH-CURSOR FUNCTION ............................................................
CLX:CREATE-IMAGE FUNCTION...............................................................................
CLX:CREATE-PIXMAP FUNCTION.............................................................................
CLX:CREATE-WINDOW FUNCTION...........................................................................
CLX:CURSOR-DISPLAY FUNCTION...........................................................................
CLX:CURSOR-EQUAL FUNCTION.............................................................................
CLX:CURSOR-ID FUNCTION ....................................................................................
CLX:CURSOR-P FUNCTION.......................................................................................
CLX:DELETE-PROPERTY FU NCTIO N......................................................................
CLX:DESTROY-SUBWINDOWS FUNCTION..............................................................
CLX:DESTROY-WINDOW FUNCTION........................................................................
CLX:DEVICE-EVENT-MASK TYPE SPECIFIER .......................................................
CLX:DEVICE-EVENT-MASK-CLASS TYPE SPECIFIER...........................................
CLX:DISCARD-GURRENT-EVENT FUNCTION..........................................................
CLX:DISCARD-FONT-INFO FUNCTION...............................
CLX:DISPLAY STRUCTURE......................................................................................
CLX:DISPLAY-AFTER-FUNCTION FUNCTION..........................................................
CLX:DISPLAY-BITMAP-FORMAT FUNCTION............................................................
CLX:DISPLAY-DEFAULT-SCREEN FUNCTION..........................................................

CLX-12
CLX-13
CLX-14
CLX-15
CLX-16
CLX-16
CLX-17
CLX-17
CLX-18
CLX-18
CLX-19
CLX-19
CLX-20
CLX-20
CLX-21
CLX-21
CLX-22
CLX-22
CLX-23
CLX-23
CLX-23
CLX-24
CLX-24
CLX-25
CLX-25
CLX-26
CLX-26
CLX-26
CLX-27
CLX-28
CLX-28
CLX-29
CLX-29
CLX-30
CLX-30
CLX-31
CLX-32
CLX-32
CLX-34
CLX-35
CLX-36
CLX-36
CLX-38
CLX-39
CLX-39
CLX-40
CLX-40
CLX-41
CLX-41
CLX-42
CLX-42
CLX-42
CLX-43
CLX-43
CLX-44
CLX-44
CLX-45

CLX:DISPLAY-FINISH-OUTPUT FUNCTION..............................................................
CLX:DISPLAY-FORCE-OUTPUT FUNCTION ............................................................
CLX:DISPLAY-IMAGE-LSB-FIRST-P FUNCTION.......................................................
CLX:DISPLAY-MAX-KEYCODE FUNCTION..............................................................
CLX:DISPLAY-MAX-REQUEST-LENGTH FUNCTION................................................
CLX:DISPLAY-MIN-KEYCODE FUNCTION.................................................................
CLX:DISPLAY-MOTION-BUFFER-SIZE FUNCTION..................................................
CLX:DISPLAY-P FUNCTIO N......................................................................................
CLX:DISPLAY-PIXMAP-FORMATS FUNCTION..........................................................
CLX:DISPLAY-PROTOCOL-MAJOR-VERSION FUNCTION......................................
CLX:DISPLAY-PROTOCOL-MINOR-VERSION FUNCTION......................................
CLX:DISPLAY-RELEASE-NUMBER FUNCTION .......................................................
CLX:DISPLAY-ROOTS FUNCTION.............................................................................
CLX: DISPLAY-VENDOR-NAME FUNCTION..............................................................
CLX:DRAWABLE TYPE SPECIFIER..........................................................................
CLX:DRAWABLE-BORDER-WIDTH FUNCTIO N .......................................................
CLX:DRAWABLE-DEPTH FUNCTION........................................................................
CLXrDRAWABLE-DISPLAY FUNCTION......................................................................
CLX:DRAWABLE-EQUAL FUNCTION........................................................................
CLX:DRAWABLE-HEIGHT FUNCTION ......................................................................
CLX:DRAWABLE-ID FUNCTION..................................................................................
CLX:DRAWABLE-P FUNCTION..................................................................................
CLX:DRAWABLE-ROOT FUNCTION..........................................................................
CLX:DRAWABLE-WIDTH FUNCTION........................................................................
CLX:DRAWABLE-X FUNCTION..................................................................................
CLX:DRAWABLE-Y FUNCTION..................................................................................
CLX:DRAW-ARC FUNCTION......................................................................................
CLX:DRAW-ARCS FUNCTION....................................................................................
CLX:DRAW-DIRECTION TYPE SPECIFIER...............................................................
CLX:DRAW-GLYPH FUNCTION..................................................................................
CLX:DRAW-GLYPHS FUNCTION...............................................................................
CLX:DRAW-IMAGE-GLYPH FUNCTION......................................................................
CLX:DRAW-IMAGE-GLYPHS FUNCTION...................................................................
CLX:DRAW-LINE FUNCTION......................................................................................
CLX:DRAW-LINES FUNCTION....................................................................................
CLX:DRAW-POINT FUNCTION ..................................................................................
CLX:DRAW-POINTS FUNCTION...............................................................................
CLX:DRAW-RECTANGLE FUNCTION........................................................................
CLX:DRAW-RECTANGLES FUNCTION......................................................................
CLX:DRAW-SEGMENTS FUNCTION ........................................................................
CLX:EVENT-CASE MACRO.........................................................................................
CLX:EVENT-KEY TYPE SPECIFIER...........................................................................
CLX:EVENT-LISTEN FUNCTION...............................................................................
CLX:EVENT-MASK TYPE SPECIFIER........................................................................
CLX:EVENT-MASK-CLASS TYPE SPECIFIER..........................................................
CLX:FIND-ATOM FUNCTION.......................................................................................
CLX:FONT STRUCTURE...........................................................................................
CLX:FONTABLE TYPE SPECIFIER ...........................................................................
CLX:FONT-ALL-CHARS-EXIST-P FUNCTION............................................................
CLX-.FONT-ASCENT FUNCTION...............................................................................
CLX:FONT-DEFAULT-CHAR FUNCTION...................................................................
CLX:FONT-DESCENT FUNCTION.............................................................................
CLX:FONT-DIRECTION FUNCTION..........................................................................
CLX:FONT-DISPLAY FUNCTION...............................................................................
CLX:FONT-EQUAL FUNCTIO N..................................................................................
CLX:FONT-ID FUNCTION........................................................................................ .
CLX:FONT-MAX-BYTE1 FUNCTION...........................................................................

CLX-45
CLX-46
CLX-46
CLX-47
CLX-47
CLX-48
CLX-48
CLX-49
CLX-49
CLX-49
CLX-50
CLX-50
CLX-51
CLX-51
CLX-52
CLX-52
CLX-52
CLX-53
CLX-53
CLX-54
CLX-54
CLX-55
CLX-55
CLX-56
CLX-56
CLX-57
CLX-57
CLX-58
CLX-59
CLX-59
CLX-60
CLX-61
CLX-62
CLX-63
CLX-64
CLX-64
CLX-65
CLX-66
CLX-66
CLX-67
CLX-68
CLX-69
CLX-69
CLX-70
CLX-70
CLX-70
CLX-71
CLX-71
CLX-72
CLX-72
CLX-72
CLX-73
CLX-73
CLX-74
CLX-74
CLX-75
CLX-75

CLX:F0NT-MAX-BYTE2 FUNCTtON............................................................................. CLX-75
CLX:FONT-MAX-CHAR FUNCTION ............................................................................. CLX-76
CLX:FONT-MIN-BYTE1 FUNCTION ............................................................................. CLX-76
CLX:FONT-MIN-BVTE2 FUNCTION ............................................................................. CLX-77
CLX:FONT-MIN-CHAR FUNCTION............................................................................... CLX-77
CLX:FONT-NAME FUNCTION...................................................................................... CLX-78
CLX:FONT-P FUNCTION ............................................................................................. CLX-78
CLX:FONT-PATH FUNCTION......................................................................................... CLX-79
CLX:FONT-PROPERTIES FUNCTION.......................................................................... CLX-79
CLX:FONT-PROPERTY FUNCTION............................................................................. CLX-80
CLX:FONT-PROPS TYPE SPECIFIER ........................................................................ CLX-80
CLX:FORCE-GCONTEXT-CHANGES FUNCTION....................................................... CLX-80
CLX:FREE-COLORMAP FUNCTION............................................................................. CLX-81
CLX:FREE-COLORS FUNCTION.................................................................................
CLX-81
CLX:FREE-CURSOR FUNCTION................................................................................. CLX-82
CLX:FREE-GCONTEXT FUNCTION............................................................................. CLX-82
CLX:FREE-PIXMAP FUNCTION.................................................................................... CLX-83
CLX:GCONTEXT STRUCTURE.................................................................................... CLX-83
CLX:GCONTEXT-ARC-MODE FUNCTION................................................................... CLX-84
CLX:GCONTEXT-BACKGROUND FUNCTION ............................................................ CLX-85
CLX:GCONTEXT-CACHE-P FUNCTION .....................................................................
CLX-85
CLX:GCONTEXT-CAP-STYLE FUNCTION................................................................... CLX-86
CLX:GCONTEXT-CLIP-MASK FUNCTION................................................................... CLX-86
CLX:GCONTEXT-CLIP-X FU NCTIO N.......................................................................... CLX-87
CLX:GCONTEXT-CLIP-Y FU NCTIO N.......................................................................... CLX-87
CLX:GCONTEXT-DASHES FUNCTION........................................................................ CLX-88
CLX:GCONTEXT-DASH-OFFSET FUNCTION..............................................................
CLX-88
CLX:GCONTEXT-DISPLAY FUNCTION........................................................................ CLX-89
CLX:GCONTEXT-EQUAL FUNCTION.......................................................................... CLX-89
CLX:GCONTEXT-EXPOSURES FUNCTION................................................................. CLX-90
CLX:GCONTEXT-FILL-RULE FUNCTION.....................................................................
CLX-90
CLX:GCONTEXT-FILL-STYLE FUNCTION................................................................... CLX-91
CLX:GCONTEXT-FONT FUNCTION............................................................................. CLX-91
CLX:GCONTEXT-FOREGROUND FUNCTION............................................................ CLX-92
CLX:GCONTEXT-FUNCTION FUNCTION ................................................................... CLX-92
CLX:GCONTEXT-ID FUNCTION.................................................................................... CLX-93
CLX:GCONTEXT-JOIN-STYLE FUNCTION ................................................................. CLX-93
CLX:GCONTEXT-KEY TYPE SPECIFIER ................................................................. CLX-94
CLX:GCONTEXT-LINE-STYLE FUNCTION................................................................. CLX-94
CLX:GCONTEXT-LINE-WIDTH FUNCTION ............................................................... CLX-94
CLX:GCONTEXT-P FUNCTION.................................................................................
CLX-95
CLX:GCONTEXT-PLANE-MASK FUNCTION ............................................................ CLX-95
CLX:GCONTEXT-STIPPLE FUNCTION...................................................................... CLX-96
CLX:GCONTEXT-SUBWINDOW-MODE FUNCTION ................................................ CLX-96
CLX:GCONTEXT-TILE FUNCTION............................................................................. CLX-97
CLX:GCONTEXT-TS-X FUNCTION............................................................................. CLX-97
CLX:GCONTEXT-TS-Y FUNCTION............................................................................. CLX-98
CLX:GET-IMAGE FUNCTION...................................................................................... CLX-98
CLX:GET-PROPERTY FUNCTION............................................................................. CLX-99
CLX:GET-RAW-IMAGE FUNCTION............................................................................... CLX-100
CLX:GET-WM-CLASS FU NCTIO N............................................................................... CLX-101
CLX:GLOBAL-POINTER-POSITION FUNCTION.......................................................... CLX-101
CLX:GRAB-BUTTON FUNCTION..................................................................................CLX-102
CLX:GRAB-KEY FUNCTION.........................................................................................CLX-103
CLX:GRAB-KEYBOARD FUNCTION............................................................................. CLX-104
CLX:GRAB-POINTER FUNCTION ............................................................................... CLX-104
CLX:GRAB-SERVER FUNCTION.................................................................................. CLX-105
xv

CLX:GRAB-STATUS TYPE SPECIFIER........................................................................ CLX-106
CLX:ICON-SIZES FUN C TIO N ...................................................................................... CLX-106
CLX:IMAGE STRUCTURE..............................................................................................CLX-106
CLX:IMAGE-BIT-LSB-FIRST-P FUNCTION................................................................... CLX-107
CLXrlMAG E-BITS-PER-PIXEL FUNCTION................................................................... CLX-108
CLXrlMAGE-BLUE-MASK FUNCTION...........................................................................CLX-108
CLX:IMAGE-BYTE-LSB-FIRST-P FUNCTION...............................................................CLX-109
CLX:IMAGE-BYTES-PER-LINE FUNCTION................................................................. CLX-109
CLXrlMAG E-DEPTH FUNCTION ............................................................................... CLX-110
CLXrlMAG E-DEPTH TYPE SPECIFIER..................................................................... CLX-110
CLX:IMAGE-FORMAT FUNCTION ................................................................................CLX-110
CLX:IMAGE-GREEN-MASK FUNCTION ................................................................... CLX-111
CLX:IMAGE-HEIGHT FUNCTION............................................................................... CLX-111
CLXrlMAGE-P FUNCTION........................................................................................... CLX-112
CLXrlMAG E-RED-MASK FUNCTION.......................................................................... CLX-112
CLX:IMAGE-SCANLINE-PAD FUNCTION................................................................... CLX-112
CLXrlMAGE-WIDTH FUNCTION................................................................................. CLX-113
CLXrINDEX-SIZE TYPE SPECIFIER............................................................................. CLX-113
CLXrINPUT-FOCUS FUNCTION................................................................................. CLX-114
CLXrINSTALL-COLORMAP FUNCTION........................................................................ CLX-114
CLXrINSTALLED-COLORMAPS FUNCTION................................................................. CLX-115
CLXrINTERN-ATOM FUNCTION.................................................................................... CLX-115
CLXrKEYBOARD-CONTROL FUNCTION...................................................................... CLX-116
CLXrKEYBOARD-MAPPING FUNCTION................................................................... CLX-116
CLX:KEYCODE->CHARACTER FUNCTION.............................................................. CLX-117
CLX:KEYCODE->KEYSYM FUNCTION.........................................................................CLX-118
CLXrKEYSYM TYPE SPECIFIER............................................................................... CLX-119
CLX:KEYSYM->CHARACTER FUNCTION....................................................................CLX-119
CLX:KEYSYM->KEYCODES FUNCTION..................................................
CLX-120
CLXrKILL-CLIENT FUNCTION.......................................................................................CLX-120
CLXrKILL-TEMPORARY-CLIENTS FUNCTION............................................................ CLX-121
CLXrLIST-EXTENSIONS FUNCTION............................................................................. CLX-121
CLXrLIST-FONT-NAMES FUNCTION ...........................................................................CLX-122
CLXrLIST-FONTS FUNCTIO N...................................................................................... CLX-122
CLXrLIST-PROPERTIES FUNCTION............................................................................. CLX-123
CLX:LOGICAL-OP TYPE SPECIFIER...........................................................................CLX-124
CLXrLOOKUP-COLOR FUNCTION............................................................................... CLX-124
CLXrMAKE-COLOR FUNCTION.................................................................................... CLX-125
CLXrMAKE-COLORMAP FUNCTION............................................................................. CLX-125
CLXrMAKE-CURSOR FUNCTION.................................................................................. CLX-126
CLXrMAKE-DRAWABLE FUNCTION............................................................................. CLX-126
CLXrMAKE-EVENT-KEYS FUNCTION...........................................................................CLX-127
CLXrMAKE-EVENT-MASK FUNCTION ........................................................................ CLX-127
CLXrMAKE-FONT FUNCTION.......................................................................................CLX-128
CLXrMAKE-GCONTEXT FUNCTION............................................................................. CLX-128
CLXrMAKE-PIXMAP FUNCTION .................................................................................. CLX-129
CLXrMAKE-STATE-KEYS FUNCTION...........................................................................CLX-129
CLXrMAKE-STATE-MASK FUNCTION...........................................................................CLX-130
CLXrMAKE-VISUAL-INFO FUNCTION...........................................................................CLX-130
CLXrMAKE-WINDOW FUNCTION.................................................................................. CLX-130
CLX:MAKE-WM-HINTS FUNCTION ............................................................................. CLX-131
CLX:MAKE-WM-SIZE-HINTS FUNCTION...................................................................... CLX-131
CLXrMAP-SUBWINDOWS FUNCTION ........................................................................ CLX-132
CLX:MAP-WIN DOW FUNCTION.................................................................................... CLX-132
CLXrMASKI 6 TYPE SP E C IFIER ..................................................................................CLX-133
CLX:MASK32 TYPE SP E C IFIER .................................................................................. CLX-133
CLXrMAX-CHAR-ASCENT FUNCTION........................................................................ CLX-133

CLX:MAX-CHAR-ATTRIBUTES FUNCTION.................................................................CLX-134
CLX:MAX-CHAR-DESCENT FUNCTION......................................................................CLX-134
CLX:MAX-CHAR-LEFT-BEARING FUNCTION.............................................................. CLX-135
CLX:MAX-CHAR-RIGHT-BEARING FUNCTION............................................................ CLX-135
CLX:MAX-CHAR-WIDTH FUNCTION .......................................................................... CLX-135
CLX:MIN-CHAR-ASCENT FUNCTION.......................................................................... CLX-136
CLX:MIN-CHAR-ATTRIBUTES FUNCTION................................................................... CLX-136
CLX:MIN-CHAR-DESCENT FUNCTION........................................................................ CLX-137
CLX:MIN-CHAR-LEFT-BEARING FUNCTION.............................................................. CLX-137
CLX:MIN-CHAR-RIGHT-BEARING FUNCTION............................................................ CLX-138
CLX:MIN-CHAR-WIDTH FUNCTION.............................................................................CLX-138
CLX:MODIFIER-KEY TYPE SPECIFIER ......................................................................CLX-138
CLX:MODIFIER-MAPPING FUNCTION........................................................................ CLX-139
CLX:MODIFIER-MASK TYPE SPECIFIER................................................................... CLX-139
CLX:MOTION-EVENTS FUNCTION .............................................................................CLX-140
CLX:OPEN-DISPLAY FUNCTION................................................................................. CLX-140
CLX:OPEN-FONT FUNCTION...................................................................................... CLX-141
CLX:PIXARRAY TYPE SPECIFIER............................................................................... CLX-141
CLX:PIXEL TYPE SPECIFIER...................................................................................... CLX-142
CLX:PIXMAP STRUCTURE........................................................................................... CLX-142
CLX:PIXMAP-DISPLAY FUNCTION .............................................................................CLX-142
CLX:PIXMAP-EQUAL FUNCTION..................................................................................CLX-143
CLX:PIXMAP-FORMAT STRUCTURE.......................................................................... CLX-143
CLX:PIXMAP-FORMAT-BITS-PER-PIXEL FUNCTION ................................................ CLX-144
CLX:PIXMAP-FORMAT-DEPTH FUNCTION.................................................................CLX-144
CLX:PIXMAP-FORMAT-P FUNCTION.......................................................................... CLX-145
CLX:PIXMAP-FORMAT-PAD FUNCTION..................................................................... CLX-145
CLX:PIXMAP-ID FUNCTION.........................................................................................CLX-146
CLX:PIXMÄP-P FUNCTION........................................................................................... CLX-146
CLX:POINTER-CONTROL FUNCTION ........................................................................ CLX-146
CLX:POINTER-EVENT-MASK TYPE SPECIFIER ....................................................... CLX-147
CLX:POINTER-EVENT-MASK-CLASS TYPE SPECIFIER........................................... CLX-147
CLX:POINTER-MAPPING FUNCTION.......................................................................... CLX-147
CLX:POINTER-POSITION FUNCTION.......................................................................... CLX-148
CLX:POINT-SEQ TYPE SPECIFIER.............................................................................CLX-149
CLX:PROCESS-EVENT FUNCTION.............................................................................CLX-149
CLX:PUT-IMAGE FUNCTION.........................................................................................CLX-150
CLX:PUT-RAW-IMAGE FUNCTION............................................................................... CLX-151
CLX:QUERY-BEST-CURSOR FUNCTION ................................................................... CLX-152
CLX:QUERY-BEST-STIPPLE FUNCTION......................................................................CLX-152
CLX:QUERY-BEST-TILE FUNCTION.............................................................................CLX-153
CLX:QUERY-COLORS FUNCTION............................................................................... CLX-153
CLXrQUERY-EXTENSION FUNCTION.......................................................................... CLX-154
CLX:QUERY-KEYMAP FUNCTION............................................................................... CLX-154
CLXrQUERY-POINTER FUNCTION............................................................................... CLX-155
CLX:QUERY-TREE FUNCTION.................................................................................... CLX-156
CLX:QUEUE-EVENT FUNCTION..................................................................................CLX-156
CLX:READ-BITMAP-FILE FUNCTION.......................................................................... CLX-157
CLX:RECOLOR-CURSOR FUNCTION ........................................................................ CLX-158
CLX:RECT-SEQ TYPE SPECIFIER............................................................................... CLX-158
CLX:REMOVE-ACCESS-HOST FUNCTION.................................................................CLX-158
CLX:REMOVE-FROM-SAVE-SET FUNCTION.............................................................. CLX-159
CLX:REPARENT-WINDOW FUNCTION........................................................................ CLX-159
CLX-.REPEAT-SEQ TYPE SPECIFIER.......................................................................... CLX-160
CLX:RESET-SCREEN-SAVER FUNCTION................................................................... CLX-160
CLX:RESOURCE-ID TYPE SPECIFIER........................................................................ CLX-160
CLX:RGB-VAL TYPE SPECIFIER..................................................................................CLX-161

CLX:SCREEN STRUCTURE......................................................................................... CLX-161
CLX:SCREEN-BACKING-STORES FUNCTION............................................................ CLX-162
CLX:SCREEN-BLACK-PIXEL FUNCTION ....................................................................CLX-162
CLX:SCREEN-DEFAULT-COLORMAP FUNCTION ..................................................... CLX-163
CLX:SCREEN-DEPTHS FUNCTION............................................................................. CLX-163
CLX:SCREEN-DISPLAY FUNCTION............ .................................................................CLX-164
CLX:SCREEN-EVENT-MASK-AT-OPEN FUNCTION ...................................................CLX-164
CLX:SCREEN-HEIGHT FUNCTION ............................................................................. CLX-165
CLX:SCREEN-HEIGHT-IN-MILLIMETERS FUNCTION................................................ CLX-165
CLX:SCREEN-MAX-INSTALLED-MAPS FUNCTION..................................................... CLX-165
CLX:SCREEN-MIN-INSTALLED-MAPS FUNCTION..................................................... CLX-166
CLX:SCREEN-P FUNCTION......................................................................................... CLX-166
CLX:SCREEN-ROOT FUNCTION.................................................................................. CLX-167
CLX:SCREEN-ROOT-DEPTH FUNCTIO N....................................................................CLX-167
CLX:SCREEN-ROOT-VISUAL FUNCTION....................................................................CLX-168
CLX:SCREEN-SAVER FUNCTION................................................................................CLX-168
CLX:SCREEN-SAVE-UNDERS-P FUNCTION...............................................................CLX-169
CLX:SCREEN-WHITE-PIXEL FUNCTION...................................................................... CLX-169
CLX:SCREEN-WIDTH FUNCTION................................................................................CLX-170
CLX:SCREEN-WIDTH-IN-MILLIMETERS FUNCTION...................................................CLX-170
CLX:SEG-SEQ TYPE SPECIFIER ................................................................................CLX-171
CLX:SELECTION-OWNER FUNCTION........................................................................ CLX-171
CLX:SEND-EVENT FUNCTION.................................................................................... CLX-171
CLX:SET-INPUT-FOCUS FUNCTION ...........................................................................CLX-173
CLX:SET-MODIFIER-MAPPING FUNCTION................................................................. CLX-173
CLX:SET-SCREEN-SAVER FUNCTION........................................................................ CLX-174
CLX:SET-WM-CLASS FUNCTION ................................................................................CLX-174
CLX:STATE-MASK-KEY TYPE SPECIFIER ................................................................. CLX-175
CLX:STORE-COLOR FUNCTION.................................................................................. CLX-175
CLX:STORE-COLORS FUNCTION................................................................................CLX-176
CLX:STRINGABLE TYPE SPECIFIER...........................................................................CLX-176
CLX:TEXT-EXTENTS FUNCTION.................................................................................. CLX-177
CLX:TEXT-WIDTH FUNCTION.......................................................................................CLX-178
CLX:TIMESTAMP TYPE SPECIFIER............................................................................. CLX-178
CLX:TRANSLATE-COORDINATES FUNCTION............................................................ CLX-179
CLX-TRANSLATE-DEFAULT FUNCTION...................................................................... CLX-179
CLX:UNGRAB-BUTTON FUNCTION ..............................................................................CLX-180
CLX:UNGRAB-KEY FUNCTION.................................................................................... CLX-181
CLX:UNGRAB-KEYBOARD FUNCTION........................................................................ CLX-181
CLX:UNGRAB-POINTER FUN CTIO N...........................................................................CLX-182
CLX:UNGRAB-SERVER FUNCTION............................................................................. CLX-182
CLX:UNINSTALL-COLORMAP FUNCTION....................................................................CLX-183
CLXrUNMAP-SUBWINDOWS FUNCTIO N....................................................................CLX-183
CLX:UNMAP-WINDOW FUNCTION ............................................................................. CLX-184
CLX.-VISUAL TYPE SPECIFIER.................................................................................... CLX-184
CLX:VISUAL-INFO STRUCTURE.................................................................................. CLX-184
CLX:VISUAL-INFO-BITS-PER-RGB FU NCTIO N.......................................................... CLX-185
CLX:VISUAL-INFO-BLUE-MASK FUNCTIO N...............................................................CLX-185
CLX:VISUAL-INFO-CLASS FUNCTION........................................................................ CLX-186
CLX:VISUAL-INFO-COLORMAP-ENTRIES FUNCTION .............................................. CLX-186
CLX:VISUAL-INFO-GREEN-MASK FUNCTION............................................................ CLX-187
CLX:VISUAL-INFO-ID FUNCTION ................................................................................CLX-187
CLX:VISUAL-INFO-P FUNCTION.................................................................................. CLX-188
CLX:VISUAL-INFO-RED-MASK FUNCTION................................................................. CLX-188
CLX:WARP-POINTER FUNCTION................................................................................CLX-188
CLX:WARP-POINTER-IF-INSIDE FUNCTION...............................................................CLX-189
CLX:WARP-POINTER-RELATIVE FUNCTION...............................................................CLX-190

o o o o o o o o o o o o o o o o p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p p

o o o o

C C ^C
X X
y 1y0
f0 1r0 M~ rb M Nf Mf fM E
ro
lb ho
to to rb
£
£
1
M
M< o-i( D o o o o * N i * N i O ) 0 ) o i c j i - ^ - ^ c o a > r o r o
ro w M M M
»
•
o
o
oo i\> ro

X
X

r~ r~ r~ p r~ rYro Yro YroYroYroYro

- * 0 0 0 0 0
O

<D CD CD M

0
0 0 0 0 0 O0
0
0
OOO0 OO
0 0—0
r~ 0 r~
r~ 0 0
r~ t- 1
i- r- 0
r~ r~ r~ r~ i- r~ r~
r~ r~ r - r~
X
X
>< * *
>< F *1 >1< Y1 1 1L 1 Y1 Y1 Y1 Y1 Y1 1
1 Y1 F1 ?1
_X
ro
rb ro
rl>
ro
ro
1
0 ro
C
D
CD CDC
C
D
C
OC
D
C
D
C
D CD
0
C
D
D
C
D
0
0
C
D
C
D
0
0
0
0
0
C
DC
CD -fx
L OD
CD CD
0 0 CD CD CD CD
0 GOro 10 _
_A

---

—A

__A

CLX:WM-SIZE-HINTS-Y FUNCTION............................................................................. CLX-223
CLX:WM-ZOOM-HINTS FUNCTION............................................................................. CLX-224
CLX:WRITE-BITMAP-FILE FUNCTIO N........................................................................ CLX-224
CLX:XATOM TYPE SPECIFIER.................................................................................... CLX-225

Appendix A

DECwindows Constants

Appendix B

CLX to X II Mappings

index

Examples
2-1

Defining the UIL M odule...............................................................................................

2-4

2-2

Defining the Main W indow.............................................................................................

2-5

2-3

Defining a Simple Text W id g e t.....................................................................................

2-5

2—4

Defining a Menu Bar ....................................................................................................

2—6

2-5

Defining Pull-Down Menu E n tries.................................................................................

2-6

2 -6

Defining Widget Variables.............................................................................................

2-8

2 -7

Defining Widgets with High-LevelFunctions..................................................................

2-8

8 Creating a Message B o x...............................................................................................

2-10

3— 1 Initializing a UIL Application..........................................................................................

3-2

3—2

Creating a Widget H ierarchy........................................................................................

3—3

3-3

Realizing the User Interface..........................................................................................

3-4

3—4

Calling the Main Loop....................................................................................................

3—4

3—5

Creating a List of Callback N a m e s ..............................................................................

3-5

3-6

Creating a List of Callback EntryPoints.........................................................................

3-5

3—7

Accessing the Callback Widget ...................................................................................

3-6

3-8
3—9

Writing to a Text W id g e t...............................................................................................
Pretty-Printing a Recipe ...............................................................................................

3-7
3—7

3—10

Accessing Callback Arguments.....................................................................................

3-8

3— 11 Printing Calorie Information..........................................................................................

3—8

4— 1 Sample CLX Program....................................................................................................

4-5

6-1

Creating a Window ......................................................................................................

6—3
6-12

6-2

Changing Window A ttrib u te s.......................................................................................

9-1

Drawing P o in ts .............................................................................................................

9-2

Drawing Lines and Line Segm ents..............................................................................

9-6

9-3

Drawing an Arc

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

9-8

9-4

Creating a C u rs o r.........................................................................................................

9-11

11—1

Specifying F o n ts ...........................................................................................................

11— 2 Drawing Text
1212-2

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

1 Using the CLX:PROCESS-EVENT Function
Using the CLX:EVENT-CASE Macro

11—4
11-8

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

12-7

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

12-8

Figures
1-1

DECwindows Layered Architecture..............................................................................

1-3

1-2

Hello World! Application..............................................................................................

1-6

3 Hello World! Widget Hierarchy.....................................................................................

1-7

1 Choosing from a Pull-Down Menu................................................................................

2-2

A Widget H ierarchy.....................................................................................................

2-3

3 A Message B o x ............................................................................................................

2-11

3— 1 DECwindows Callback Argument L i s t .........................................................................

3-6

9-1

Drawing P o in ts .......................................................................................

9-4

9-2

Drawing Lines and Line S egm ents..............................................................................

9-6

9-3

Drawing an Arc

9—8

11-

1 Drawing Text

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

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

11-9

12— 1 The Event Queue ..............................................................................................

12—5

I — 1 Types of DECwindows W id g e ts ..................................................................................

1—4

Tables
1 CLX Data T y p e s ..........................................................................................................

4-2

5— 1 Information Functions for DISPLAY O b je c ts ...............................................................

5—2

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

5-3

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

5—4

Information Functions for CLX:SCREEN Objects

1 CLX:CREATE-WINDOW Keywords

6-2

Output Buffer Routines

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

6-2

Information Functions for CLX:WM-HINTS Objects ...................................................

6-7

6-3

Information Functions for CLX:WM-SIZE-HINTS Objects

6-8

6—4

Additional Window Manager Property Functions........................................................

6-9

6-5

Information Functions for CLX:WINDOW Objects ......................................

6—11

6-6
SETF Functions for CLX:WINDOW O b je c ts ...............................................................
6 - 7 Information Functions for CLXrDRAWABLE Objects .................................................

6-12
6—12

7-2

1 CLX:CREATE-GCONTEXT K eyw ords.........................................................................

7-2
78-

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

CLX:LOGICAL-OP Values

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

7-3

3 Information Functions for CLX:GCONTEXT Objects .................................................
1 Information Functions for CLX:VISUAL-INFO Objects ...............................................

7-4
8-2

8—2

Information Functions for CLX:COLOR Objects

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

8—4

8-3

Information Functions for CLX:COLORMAP Objects .................................................

8-5

10-1

Information Functions for Pixmaps ..............................................................................

10-2

Information Functions for Pixmap Formats

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

10—2

10-3

Information Functions for Bitmap-Formats ..................................................................

10—3

10-4

Information Functions for CLX:IMAGE O b je c ts ...........................................................

10-4

10-5

Information Functions for :XY-PIXMAP Im a g e s...........................................................

10—5

10-

6 Information Functions for :Z-PIXMAP Im ages..............................................................

10-5

II-

1 Information Functions for Characters

11-1

11-

2 Information Functions for CLX:FONT Objects

12-

1 Event Keys

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

12—2

12-2

Event Masks

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

12-2

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

11-2

12-3

Pointer Event Masks ....................................................................................................

12-10

12-4

State M a s k s ..................................................................................................................

12-10

12-5

Modifier M a s k s ..............................................................................................................

12-10
xxi

12-6

:BUTTON-PRESS Event-Key

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

12-16

12-7

:BUTTON-RELEASE Event-Key

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

12-16

12-6

:CIRCULATE-NOTIFY Event-K ey................................................................................

12-17

12-9

:CIRCULATE-REQUEST Event-Key ...........................................................................

12-17

12-10

:CLIENT-MESSAGE Event-Key ...................................................................................

12-17

12-11

:COLORMAP-NOTIFY Event-Key

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

12-18

12-12

:CONFIGURE-NOTIFY Event-Key ..............................................................................

12-18

12-13

:CONFIGURE-REQUEST Event-Key

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

12-19

12-14

:CREATE-NOTIFY Event-Key .....................................................................................

12-19

12-15

:DESTROY-NOTIFY Event-Key ...................................................................................

12-20

12-16

:ENTER-NOTIFY Event-Key .......................................................................................

12-20

12-17

EXPOSURE Event-K ey...............................................................................................

12-21

12-18

:FOCUS-IN Event-Key .................................................................................................

12-21

12-19

:FOCUS-OUT Event-Key

12-20

:GRAPHICS-EXPOSURE Event-Key

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

12-22

12-21

:GRAVITY-NOTIFY Event-K ey.....................................................................................

12-22

:KEYMAP-NOTIFY E vent-K ey.....................................................................................

12-23

:KEY-PRESS Event-Key...............................................................................................

12-23

12-24

:KEY-RELEASE E vent-K ey..........................................................................................

12-24

12-25

1EAVE-NOTIFY Event-Key

12-24

12-26

:MAPPING-NOTIFY Event-Key

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

12-25

12-27

:MAP-NOTIFY E vent-K ey............................................................................................

12-25

12-28

:MAP-REQUEST Event-Key

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

12-26

12-29

:MOTION-NOTIFY Event-Key .....................................................................................

12-26

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

12-21

12-30

:NO-EXPOSURE Event-Key .......................................................................................

12-26

12-31

:PROPERTY-NOTIFY Event-Key ................................................................................

12-27

12-32

:REPARENT-NOTIFY Event-Key ................................................................................

12-27

12-33

:RESIZE-REQUEST Event-Key ...................................................................................

12-27

12-34

SELECTION-CLEAR Event-Key ................................................................................

12-28

12-35

SELECTION-NOTIFY Event-Key................................................................................

12-28

12-36
12-37

SELECTION-REQUEST E vent-K ey............................................................................
:UNMAP-NOTIFY Event-K ey.......................................................................................

12-28
12-29

12-38

:VISIBILITY-NOTIFY E vent-K ey...................................................................................

12-29

CLX-1 WITH-STATE Accessor and SETF Groups

..................................................................CLX-207

A-1

DECwindows Constants Defined by VAX L IS P ...........................................................

A-1

A-2

DRM Constants.............................................................................................................

A—3

A-3

Callback R ea so n s........................................................................................................

A-5

B—1

Mapping X II Requests to CLX F unctions..................................................................

B-2

Mapping CLX Functions and Macros to X II Requests

B-10

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

Preface
This manual provides information on writing VAX LISP programs that use the
DECwindows Toolkit or Common LISP X (CLX).

Intended Audience
This manual is intended for programmers with a good knowledge of VAX LISP
and the DECwindows Toolkit or the X Window System.™

Structure
The DECwindows Tbolkit and CLX are discussed in separate parts of this
manual, as follows:
• Part I explains how to use the DECwindows Ibolkit with VAX LISP.
• Part II provides brief descriptions of the DECwindows Ibolkit functions.
• Part III is a guide to programming CLX.
• Part IV contains reference material on all functions, macros, data types, and
structures in CLX.
If you are programming strictly with the DECwindows Toolkit and not calling
any CLX functions, you should read Parts I and II only. Similarly, if you want to
program in CLX only, you need to read Parts III and IV only.
Appendix A lists the constants associated with the DECwindows Toolkit which
are defined in VAX LISP.
Appendix B contains two tables that show the mapping among X Protocol
requests, Xlib routines, and CLX routines.

Associated Documents
You will need the following documents to do DECwindows Toolkit programming
in VAX LISP/VMS:
• VMS DECwindows User Interface Language Reference Manual
• VMS DECwindows U ser’
s Guide
• XUI Style Guide

™ The X Window System is a trademark of the Massachusetts Institute of Technology.

xxiii

You will need the following documents to do CLX programming in VAX
LISP/VMS:
• VMS DECwindows Guide to XLib Programming: MIT C Binding
• VMS DECwindows Xlib Routines Reference Manual
• X Window System: C Library and Protocol Reference1
The following documents may also be helpful:
• VAX LISP/VMS Program Development Guide
• VAX LISP/VMS System Access Programming Guide
• Common LISP: The Language

Conventions
The following conventions are used in this manual:
C o n ve n tio n

M eaning

UPPERCASE

DCL commands and qualifiers and VMS file names are printed in
uppercase characters; however, you can enter them in uppercase,
lowercase, or a combination of uppercase and lowercase characters.
For example:
The examples directory (SYS$SYSROOT:[VAXLISP.EXAMPLES] by
default) contains sample LISP source files.

UPPERCASE
TYPEWRITER

Defined LISP functions, macros, variables, constants, and other
symbol names are printed in uppercase TYPEWRITER charac
ters; however, you can enter them in uppercase, lowercase, or a
combination of uppercase and lowercase characters. For example:
The CALL-OUT macro calls a defined external routine. . . .

lo w e r c a s e
t y p e w r it e r

LISP forms are printed in the text in lowercase t y p e w r it e r
characters; however, you can enter them in uppercase, lowercase, or
a combination of uppercase and lowercase characters. For example:

SANS SERIF

Format specifications of LISP functions and macros are printed in a
sans serif typeface. For example:

( s e t f example-1

(m ake-space))

CALL-OUT external-routine &REST routine-arguments
italics

Lowercase italics in format specifications and in text indicate
arguments that you supply; however, you can enter them in
lowercase, uppercase, or a combination of lowercase and uppercase
characters. For example:
The routine-arguments must be compatible with the arguments
defined in the call to the DEFINE-EXTERNAL-ROUTINE macro.

( )

Parentheses used in examples of LISP code and in format
specifications indicate the beginning and end of a LISP form. For
example:
(setq name lisp)

1 Robert W. Scheifler, James Gettys, and Ron Newman, X Window System: C Library and Protocol Reference, Digital
Press (1988), Burlington, Massachusetts.

xxiv

C o n ve n tio n

M eaning

[]

Square brackets in format specifications enclose optional elements.
For example:
[doc-string]

Square brackets do not indicate optional elements when they are
used in the syntax of a directory name in a VMS file specification.
Here, the square bracket characters must be included in the syntax.
For example:
(pathname "MIAMI::DBA1 :[SMITH]LOGIN.COM;4 ")
{}

In function and macro format specifications, braces enclose elements
that are considered one unit of code. For example:
{keyword value}

{}*

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

&OPTIONAL

In function and macro format specifications, the word &OPTIONAL
indicates that the arguments that follow it are optional. For
example:
PPRINT object &OPTIONAL stream
Do not specify &OPTIONAL when you invoke a function or macro
whose definition includes &OPTIONAL.

&REST

In function and macro format specifications, the word &REST
indicates that an indefinite number of arguments may appear. For
example:
CALL-OUT external-routine &REST routine-arguments
Do not specify &REST when you invoke a function or macro whose
definition includes &REST.

&KEY

In function and macro format specifications, the word &KEY
indicates that keyword arguments are accepted. For example:
COMPILE-FILE input-pathname
&KEY LISTING MACHINE-CODE :OPTIMIZE
:OUTPUT-FILE VERBOSE WARNINGS
Do not specify &KEY when you invoke a function or macro whose
definition includes &KEY.
A horizontal ellipsis in a format specification means that the
element preceding the ellipsis can be repeated. For example:
function-name .. .

A vertical ellipsis in a code example indicates that all the
information that the system would display in response to the
function call is not shown; or that all the information a user is to
enter is not shown.

XXV

C o n ve n tio n

M ea n ing

|Return |

Ietna: i

Two key names enclosed in a box indicate a control key sequence in
which you hold down Ctrl while you press another key. For example:
ICtrl/C |or [Ctri/Sl

EE1EZ3

A sequence such as [pfT] []r] indicates that you must first press and
release the key labeled PF1, then press and release another key.

mouse

The term mouse refers to any pointing device, such as a mouse, a
puck, or a stylus.

MB1, MB2, MB3

By default, MB1 indicates the left mouse button, MB2 indicates the
middle mouse button, and MB3 indicates the right mouse button.
You can rebind the mouse buttons.

Red print

In interactive examples, user input is shown in red. For example:
L is p >
(B C)
L is p >

xxvi

(e d r ' ( a b c ) )

Parti
Guide to the DECwindows ToolKit

Chapter 1

Overview of the DECwindows Toolkit
The DECwindows Toolkit is a set of application development tools and run-time
functions that help you implement DECwindows applications. A DECwindows
application has the “
look and feel”described in the XUI Style Guide. It is
characterized by a direct-manipulation interface rather than a command-line
interface. For example, the user selects options not by issuing commands but by
pointing with a mouse at an object such as a menu choice.
The DECwindows Toolkit is layered on top of Xlib, the routines library that
implements the X Windows System, Version 11, protocol. The routines in Xlib
enable application programs to communicate with a server to perform the
following tasks:
• Open the connection to a workstation display
• Create windows on the display
• Perform output operations to the windows
• Notify the application of pointer or keyboard input through the windows
The DECwindows Toolkit does not hide Xlib from applications. You can call
Xlib routines directly via CLX (described in Parts III and IV of this book).
For example, an application can call Xlib routines directly to perform drawing
operations in a window.
Programming with the DECwindows Toolkit lets you separate form from
function. That is, you can consider the form your application takes—its user
interface—apart from the functions the application performs. The user interface
is a collection of widgets. Widgets are objects like menus, windows, dialog boxes,
and so on, through which the user interacts with the application. The application
functions are defined as attributes of the widgets. They are called by the widgets
under predefined circumstances, or reasons.
Because form and function are separate, programming with the DECwindows
'Ibolkit differs somewhat from traditional programming techniques. The
application cannot be thought of as a set of procedures to be performed in a
predefined order. Rather, the application is a collection of widgets and a collection
of functions that can be invoked by those widgets. The behavior of the application
is determined by the widgets that the user selects.
Before you begin to program with the DECwindows Toolkit in LISP, you should
be familiar with the following DECwindows documents:
• XUI Style Guide
• VMS DECwindows User Interface Language Reference Manual
• VMS DECwindows Toolkit Routines Reference Manual

Overview of the DECwindows Toolkit

1-1

This chapter provides an overview of the components of the DECwindows Toolkit,
It describes the types of widgets that can be used by a DECwindows application.
It describes how the widgets make up a user interface and how they call back to
your application functions.

1.1

DECwindows Toolkit Components
The DECwindows Toolkit consists of the following components:
• Low-level functions, which let you access all the attributes associated with
a widget. You assign values to widget attributes in an argument list that is
passed to the function as an alien structure. A low-level function accepts this
argument list as one of its standard formal parameters.
• High-level functions, which are easier to program than low-level functions
but let you access only some of the widget attributes. Instead of using an
argument list to specify widget attributes, you pass attribute values as formal
parameters to the high-level function.
• Alternatively, you can define widgets with the User Interface Language (UIL)
and the DECwindows Resource Manager (DRM).
— The UIL lets you define widgets in a text file called a UIL specification
file. You compile this specification file with the UIL compiler. However,
instead of creating an object module, as other compilers do, the UIL
compiler creates a user-interface database (UID). Your application
accesses this database at run time with the functions of the DRM.
— The DRM is a database manager designed to operate on UID files. DRM
functions can open the UID, retrieve widget specifications, create widgets,
and build the user interface at run time. DRM functions optimize the
initialization and startup of a DECwindows application.
Because the UIL and DRM let you separate widget definitions from the
operations performed on those widgets, they can make it easier to translate
an application into other languages.
When you define widgets in a UIL specification file, you can access all widget
attributes. T he UIL com p iler checks th at the valu es you a ssign to attributes

are of the data type expected by the widget. The high-level and low-level
functions do not check the data types of attribute values.

When deciding how to define your application’
s widgets, you must choose the
method that lets you access the widget attributes you need to set. Although
you can access all attributes after the widget has been created, it is more
efficient to assign the widget’
s attribute values when you create it.
• Intrinsic functions are the backbone of every DECwindows application. They
provide general application support services. For example, a main loop
intrinsic function controls the process of determining which widgets have
been selected and which actions to take when they have been selected. After
you create widgets, intrinsic functions make them appear on the display.
These functions also provide the facilities you need to build your own widgets.
• Cut-and-paste functions let your application exchange data with other
DECwindows applications through the clipboard.

1-2

Overview of the DECwindows Toolkit

Figure 1-1:

DECwindows Layered Architecture

r
Callback Routines
Main Loop
Application -<

>
DECwindows
Toolkit

Windows

Menus

Push Buttons

Pop-up Menus

Dialog Boxes

Scroll Bars

Text Widgets

;

Other Widgets

User Interface
Language (UIL)
DECwindows
Resource
Manager (DRM)

High-Level
Creation
Routines

Low-Level
Creation
Routines

Cut and Paste
Routines

Intrinsic
Routines

Xlib
MLO-003384

Figure 1-1 illustrates the components of the DECwindows Toolkit and their
relationship to both the application and Xlib.
VAX LISP has its own interface to the Toolkit because it supports special LISP
objects that are not VAX standard data types. Therefore, when calling a Toolkit
function, VAX LISP must convert data from LISP types to VAX types. When the
Toolkit calls back to LISP, VAX LISP must convert data from VAX types to LISP
types.
The VAX LISP interface to the Toolkit provides the following source files in
LISP$EXAMPLES to help you pass data between LISP and the Toolkit functions:
• DWTAPPL.LSP defines Toolkit constants and some alien structures.
• DECW-CALLBACK-STRUCTURES.LSP defines callback structures.
• DECW-PUBLIC.LSP defines additional structures and many functions to
construct and dereference those structures.
The LISP functions are defined in the d w t + package. All references to the d w t +
package in this manual refer to the functions defined in LISP$EXAMPLES.

1.2 User Interface Widgets
A DECwindows user interface is made up of widgets. A widget can be a menu,
a push button, a scroll bar, and so on. Some widgets display information, such
as text or graphics. Others, like menu bars and dialog boxes, simply contain
other widgets. Still others change their display in response to user input and can
invoke functions.
Each widget in a DECwindows user interface has a set of attributes, such
as width, height, font, color, and border. The DECwindows Toolkit assigns
default values for these attributes. The default attributes conform to the
recommendations of the XUI Style Guide. However, you can customize the
widget’
s appearance and behavior by specifying the desired attributes.

Overview of the DECwindows Toolkit

1—3

The DECwindows Toolkit widgets fall into five general categories:
• Window widgets enable you to open windows. They include a title bar and
other window components.
• Box widgets are containers for other widgets. Box widgets provide no input
or output capabilities of their own. However, they can contain other widgets
that display messages and prompt the user for information.
• Menu widgets are containers for widgets that present lists of choices.
• Label, separator, and button widgets provide many of the basic input ana
output capabilities of a user interface. These widgets are used to build the
more complex widgets, such as menus and dialog boxes. The DECwindows
Toolkit provides a second version of these widgets, called gadgets.
• Miscellaneous widgets perform specialized user interface functions. For
example, the simple text widget lets you accept text input from the user.
Table 1-1 fists all the types of widgets that you can create with the DECwindows
Toolkit.
Table 1-1:

Types of DECwindows Widgets

Type

P u rp o se

W indow W idgets
Command window

A command entry area in a main window widget.

Main window

A window with a title bar, and, optionally, a menu bar,
command window, and scroll bars.

Box W idgets
Attached dialog box

A dialog box that changes the position of its subwidgets when
resized.

Caution box

A dialog box that presents a warning message before an
irreversible action is executed.

Dialog box

A container for other widgets. It haB no input capabilities

File selection box

A dialog box that queries the user for a file specification.

Help box

A widget that presents help text.

Message box

A dialog box that displays a message.

Pop-up attached dialog
box

An attached dialog box that cannot extend beyond the edges of
its parent.

Pop-up dialog box

A dialog box that cannot extend beyond the edges of its parent.

Selection box

A dialog box that presents the user with a list of choices, only
one of which can be selected at a time.

Work-in-progress box

A dialog box that displays a “
Work in Progress”message.

ap art from th ose o f th e su b w id gets it contains.

(continued on next page)

1—4 Overview of the DECwindows Toolkit

Table 1-1 (Cont.):

Types of DECwindows Widgets

T ype

P u rp ose

M en u W id g ets

Menu bar

A list of choices, each of which is a pull-down menu entry.

Option menu

A list of choices, from which one may be chosen. It always
displays the current choice.

Pop-up menu

A menu that appears when the user presses MB2. It can extend
beyond the borders of its parent.

Pull-down menu

A menu that appears when the user presses MB1 or MB2. It
can extend beyond the borders of its parents.

Pull-down menu entry

A button-like widget that causes a pull-down menu to appear.

Radio box

A work area menu in which a list of choices is presented, only
one of which can be selected at a time.

Work area menu

A container for menu items.

L abel, S ep a ra tor, a n d B u tto n W id g e ts

Label

Read-only, constant text.

Push button

A label that invokes a callback routine when selected.

Separator

A line or bar that separates items in a list or menu.

Toggle button

A label that controls an on and off state.

M is c e lla n e o u s W id g e ts

List box

A list of choices, typically a long list. It contains a scroll bar
for viewing all list items.

Scale

A pointer that moves within a range of values. The user selects
a value by sliding the pointer to the desired position within the
range.

Scroll bar

A bar with a sliding scale at the side of a window. It shows
the user’
s current position within a body of data that is larger
than the window. The user can reposition the sliding scale to
display a different portion of the data.

Scroll window

A window with a built-in scroll bar.

Simple text

A window for reading and writing text.

Window

An area on the Bcreen in which to perform graphics operations.

Some widgets have variants, called gadgets. A gadget has the same appearance
as its widget counterpart but uses fewer resources. Gadgets do not support
all the attributes supported by their widget counterparts. Thus, gadgets offer
improved performance but are not as customizable.
The distribution kit for VAX LISP contains some examples of applications
written with the DECwindows Tbolkit. The Hello World! application is a simple
DECwindows application of four widgets: a main window, a dialog box, a push
button, and a label containing the text “
Hello World!”When you click MB1 on
the push button once, it changes the label to “
Goodbye World!”When you click a
second time, the application exits. You can run Hello World! to see an example of
these common types of widgets and to become familiar with the look and feel of a
DECwindows application.

Overview of the DECwindows Toolkit

1-5

The source files for the Hello World! application can be installed by the LISP
distribution kit in the directory defined by the logical name LISP$EXAMPLES.
Copy the files from LISP$EXAMPLES to your working directory, then execute the
command procedure as follows:
$
$

COPY LISP$EXAMPLES:HELLOWORLD.* *.*
SHELLOWORLD

Figure 1-2 shows the user interface to Hello World! as it appears initially and as
it changes when you interact with the application by clicking MB1.
Figure 1-2:

Hello World! Application

[H P
Press button once
to change label;
twice to exit.

Press button once
to change label;
twice to exit.

VAX Lisp Listener
Press button once
to change label;
twice to exit.

1-6

Overview of the DECwindows Toolkit

1.3 Creating a User Interface
You create a user interface by establishing parent/child relationships among the
widgets. The resulting family tree is called a widget hierarchy. Widgets that can
only be children of other widgets are called primitive widgets. Widgets that can
be either parents or children are called composite widgets. Labels, separators,
and buttons are primitive widgets; all others are composite widgets.
The user interface of the Hello World! application has a simple widget hierarchy
made up of four widgets. At the top of the hierarchy is the apphcation main
window widget. The main window acts as the mediator between the apphcation
program and the workstation environment. In all DECwindows applications,
a main window widget is at the top of the hierarchy. In the Hello World!
apphcation, the dialog box widget is the only child of the main window widget.
The dialog box is the parent of both a push button widget and a label widget.
The main window and dialog box widgets are examples of composite widgets;
they contain other widgets. The push button and label widgets are examples of
primitive widgets; they do not have children. Figure 1-3 shows the hierarchy
formed by the user interface of the Hello World! apphcation.
Figure 1-3:

Hello World! Widget Hierarchy

MLO-003386

1.4 Calling Back to Application Functions
The user interface interacts with your apphcation functions through the VAX
LISP callback facility. Callback functions are defined as attributes of widgets.
These attributes define what functions to call under specific circumstances, or
reasons. Each widget supports one or more reasons. The following are some
common reasons:
• The widget has been created.
• The user has activated the widget.
• The user has requested help.
• The user has changed the value of the widget attribute.

Overview of the DECwindows Toolkit

1-7

The reasons each widget supports are detailed in the VMS DECwindows Toolkit
Routines Reference Manual.
You can specify different functions to call for different reasons. For example, a
widget may define one callback function for the “
help”reason and another for the
“
activated”reason. You can also associate more than one callback function with a
single reason. When you do, the functions are executed in the order you specify.
In the Hello World! application, only the push button is associated with a
callback function. This function is invoked when the widget is activated (the
“
activate”reason). The callback function checks to see how many times the push
button has been activated. The first time, the callback function changes the text
of the label widget. The second time, the function exits from the application.

1-8

Overview of the DECwindows Toolkit

Chapter 2

Creating a User Interface

A DECwindows application is a collection of user interface widgets and the
functions they invoke. This chapter describes how to create a DECwindows user
interface; Chapter 3 describes how to access that user interface from LISP.
There are three ways to define the widgets that make up an application’
s user
interface.
• Low-level functions let you access all the attributes associated with a widget
but present a more complex programming task.
• High-level functions are easier to program but let you access only some of the
widget attributes.
• The User Interface Language (UIL) lets you define widgets in a text file,
which you then compile with the UIL compiler to create a user-interface
database (UID). Your program can access the UID at run time using DRM
functions. When you define widgets in this way, you can access all widget
attributes.
The UIL compiler checks that the values you assign to widget attributes are of
the data type expected by the widget; the high-level and low-level functions do
not.
The UIL is perhaps the simplest method to use because it is a high-level
language that provides many default attributes to make the widgets conform to
the DECwindows style. Furthermore, the user interface specification is separate
from the actions that the application performs. This makes the UIL a good choice
for applications that will be translated into other languages. High-level and
low-level functions are better for creating widgets or changing their attributes at
rim time.

2.1 A Sample DECwindows Application
The VAX LISP /VMS Program Development Guide shows a LISP appli cation that
calculates the number of calories per serving for a few recipes. This chapter
explains how to write a DECwindows interface for the recipe application.
The source files for the recipe application are included in the LISP$EXAMPLES
directory, created when VAX LISP is installed on your system. Ib run the
application, copy the files to your working directory and invoke the command file,
as follows:
$
$

COPY LISP$EXAMPLES:RECIPE*.* *.*
6RECIPE

Creating a User Interface

2-1

The recipe application displays a main window, a menu bar, and a simple
text widget. If you press MB1 on the Ingredients pull-down menu entry, a
menu appears. You can choose from a list of ingredients. When you choose
an ingredient, the application displays the number of calories per some unit
of measure. If you press MB1 on the Recipes pull-down menu entry, a menu
of recipes appears. When you choose a recipe, the application displays the
ingredients, the number of servings, and the number of calories per serving for
that recipe, based on the number of calories in each ingredient. Figure 2—1 shows
what the application displays if you choose french toast from the Recipe menu.
Figure 2-1:

Choosing from a Pull-Down Menu

NOTE

In order to choose french toast or toast from the Recipes menu, you
must enter the following form at the Lisp> prompt or add it to the
RECIPE.LSP source file:
(setf (get 'bread 'calories) 100)

See Chapter 5 of your Program Development Guide for more
information about the recipe application.
The recipe application has one main window. This is the top-level widget. All
other widgets are children of the top-level widget or its children. A simple text
widget and a menu bar are the immediate children of the main window. The
menu bar is parent to the pull-down menu entries, which are each parents to one
pull-down menu. Each pull-down menu is parent to a series of push buttons, and
associated with each push button is a callback function. When the user clicks on
a push button, it invokes the callback function associated with that push button.
Figure 2-2 shows the hierarchical relationship among the widgets that make up
the application.

2-2

Creating a User interface

Figure 2-2:

A Widget Hierarchy

MLO—003388

2.2 The User Interface Language
The UIL lets you describe widgets with UIL statements stored in one or more
source files. UIL statements can define any widgets required by the application
and their position in a widget hierarchy. The UIL is described in detail in VMS
DECwindows User Interface Language Reference Manual.
The widget hierarchy for the recipe application is defined in the file named
RECIPE.UIL. Example 2-1 shows the portion of the source file that sets up
the user interface module. That is, it gives the module a name, defines some of
its characteristics, and defines the procedure names and constants that will be
referred to throughout the module. All UIL keywords are shown in uppercase
letters. Note that the names of procedures and widgets cannot contain hyphens;
you may use underscores instead.

Creating a User Interface

2-3

Example 2-1:

Defining the UIL Module

O MODULE my_module
© VERSION = 'vl.0'
© NAMES = CASE_INSENSITIVE
©

PROCEDURE
display_message ();
practice_callback (INTEGER);
dw_calories (INTEGER);
dw_print_recipe (INTEGER);
escape to lisp ();
exit lisp ();
remexnber_text_id () ;

LIST
nop_cal!back : CALLBACKS {
DESTROY = PROCEDURE practice_callback (1);
};

VALUE
i_butter
: 1;
i_milk
: 2;
i_bread
: 3;
i_egg
: 4;
i_syrup
: 5;
r_cookies
: 6;
r_french_toast : 7;
r_toast
: 8;
r omelet
: 9;

O The MODULE statement allows you to divide the user interface definitions
into separate areas called modules. A UIL module consists of a single module
block, which contains any number of procedure, list, value, identifier, and
object sections. Modules let you share UIL code between applications. That
is, you can place commonly used definitions in their own modules, which
many applications can access.
© You can assign a version number to the application’
s user interface with the
VERSION statement.
© The NAMES statement determines whether the UIL module is case-sensitive.
In this example, the UIL is case-insensitive, which means that it will treat
uppercase and lowercase letters the same.
© The PROCEDURE section declares the callback procedures referenced by the
widgets. You must supply the names of the callback procedures and the data
types of their arguments, if any.
© Like a macro expansion in other programming languages, the LIST section
lets you give a name to an argument, controls, or callback list to which you
can refer anywhere in the UIL. This example defines a callback list that
defines the callback function to call when an object is destroyed. This callback
list can be referred to by the name n o p _ c a l l b a c k .
© The VALUE section defines symbolic constants. The symbolic constants
defined in this example are used as arguments to the callback functions.

2—4 Creating a User Interface

Example 2-2 shows the definition of the application’
s main window.
Example 2-2:

Defining the Main Window

OBJECT app_window : PRIVATE MAIN_WINDOW {
ARGUMENTS {

X = 10;
Y = 20;

HEIGHT = 300;
WIDTH = 300;
©
©

CALLBACKS nop_callback;
CONTROLS {
MENU_BAR main_menubar;
SIMPLEJTEXT text_object;
};

};

The main window is named a p p _w i n d o w . It is defined with the p r i v a t e keyword,
indicating that the window cannot be referenced from outside this module.
a p p _w i n d o w has the following attributes:

O The ARGUMENTS section defines the X and Y coordinates and the height
and width of the window in pixels.
© The CALLBACKS section refers to the callback list defined in Example 2-1.
It calls the p r a c t i c e _ c a l l b a c k function when the main window widget is
destroyed.
© The CONTROLS section defines the names and types of widgets that are the
children of the main window.
Example 2-3 shows the definition of a simple text widget that is a child of the
main window.
Example 2-3:

Defining a Simple Text Widget

OBJECT text_object : PRIVATE SIMPLEJTEXT {
ARGUMENTS {
Y = 40;
HEIGHT = 220;
WIDTH = 300;
};
CALLBACKS {
©
CREATE = PROCEDURE remember_text_id;
};
CONTROLS {
©
};

The t e x t j o b j e c t has the following attributes:
O

The ARGUMENTS section defines the window’
s position and size.

© The CALLBACKS section states that the function r e m e m b e r _ t e x t _ id should
be called when this widget is created.
© The CONTROLS section does not contain any widget names. Therefore, this
widget does not have children. (This section could be omitted because it is
empty.)

Creating a User Interface

2-5

Example 2-4 shows the definition of the main menu bar (the horizontal bar at
the top of the main window showing the names of the pull-down menus).
Example 2-4:

Defining a Menu Bar

OBJECT mainjnenubar : PRIVATE MENU_BAR {
ARGUMENTS {
ORIENTATION = HORIZONTAL;
I'©
CONTROLS {
PULLDOWN_ENTRY option_menu_entry;
PULLDOWN_ENTRY ingredients_menu_entry;
PULLDOWN_ENTRY recipes_menu_entry;
};
};

The m a i n _ m e n u b a r has the following attributes:
O The ARGUMENTS section sets the ORIENTATION attribute to
HORIZONTAL.
© The CONTROLS keyword lists the names and types of the menu bar’
s
children, which are all pull-down menu entries.
Example 2—5 shows the definition of a pull-down menu. It defines the label that
appears in the menu bar, the pull-down menu, and the push buttons that are the
pull-down menu entries.
Example 2-5:

Defining Pull-Down Menu Entries

OBJECT option_menu_entry : PRIVATE PULLDOWN_ENTRY {
ARGUMENTS {
LABEL_LABEL = 'Options';
_
1'
©
CONTROLS {
PULLDOWN_MENU options_menu;
>;
};

OBJECT options_menu : PRIVATE PULLDOWN_MENU {
CALLBACKS nop_callback;
CONTROLS {
PUSH_BUTTON message_button;
PUSH_BUTTON escape_button;
PU SH_BUTTON exit_button;
};

};
©

OBJECT message_button : PRIVATE PUSH_BUTTON {
ARGUMENTS {
LABE L_LABE L = 'Message';
};
CALLBACKS {
ACTIVATE = PROCEDURE display_message;
};

};

(continued on next page)

2-6

Creating a User Interface

Example 2-5 (Cont.):

Defining Pull-Down Menu Entries

OBJECT escape_button : PRIVATE PUSH_BUTTON {
ARGUMENTS {
LABEL_LABEL = 'Escape to Lisp';
};
CALLBACKS {
ACTIVATE = PROCEDURE escape_to_lisp;
};
};

OBJECT exit_button : PRIVATE PUSH_BUTTON {
ARGUMENTS {
LABE L_LABE L = 'Exit';
};
CALLBACKS {
ACTIVATE = PROCEDURE exit_lisp;
};

© The LABEL_LABEL keyword defines the text of this menu entry, which is
’
Options’
. (Note that character strings are enclosed in single quotes.)
© The o p t i o n _ m e n u _ e n t r y has one pull-down menu as its child.
© The o p t i o n s _ m e n u pull-down menu has two children. They are push buttons.
© The first push button, called m e s s a g e _ b u t t o n , has the label ’
M essage’
. It calls
the LISP procedure d i s p l a y _ m e s s a g e when activated. ACTIVATE is one of
the reasons with which a push button can call back to a LISP function.
© The Esca p e _ b u t t o n has the label ’
Escape to Lisp’
. It defines e s c a p e _ to _ l i s p
as the function to call when the button is activated.
© The e x i t _ b u t t o n push button has the label ’
E xit’
. It defines e x i t _ l i s p as the
LISP function to call when the button is activated.
The rest of the widget hierarchy consists of two more pull-down menus, which
are constructed in the same way as the Options menu in Example 2-5. Refer to
the RECIPE.LSP source file to see how these menus are defined. An e n d _ m o d u l e
statement marks the end of the UIL module.
The UIL file contains only source code. It must be compiled into a UID file before
LISP can access the user interface at run time. To compile the UIL file for the
recipe application, issue the following UIL command:
$ UIL RECIPE

In this command line, the UIL compiler assumes that the file has the default file
type (.UIL). It creates a file with the same name and the default file type (.UID).

2.3 High-Level Functions
When you use high-level functions to define widgets, their attributes are specified
as formal parameters. The widgets you define with high-level functions are not
a separate part of the application, as is the UID file, but are part of the LISP
source code for the application.

Creating a User Interface

2-7

The example in this section uses high-level functions to define a portion of
the widget hierarchy for the recipe application. In this example, each widget
is represented by a LISP variable. Thus, the widgets can easily be passed as
arguments to Toolkit functions at run time. Initially, the value of the variables is
set to n i l , as shown in Example 2—6.
Example 2-6:

Defining Widget Variables

(defvar *top-level* nil)
(defvar *app-window* nil)
(defvar ‘text-widget* nil)
(defvar *main-menubar* nil)
(defvar *option-menu-entry* nil)
(defvar *options-menu* nil)
(defvar ‘message-button* nil)
(defvar ‘exit-button* nil)

When the widget is created, its variable is set to the widget’
s ID using
s e t f . The high-level functions are called within a LISP function named
m a k e -u s e r - i n t e r f a c e , shown in Example 2-7.
Example 2-7:

Defining Widgets with High-Level Functions

(defun make-user-interface ()
(setf *app-window*
O
(dwt:main-window ‘top-level* "APP_WINDOW" 10 20 300 300))
(setf ‘text-object*
©
(dwt:s-text *app-window* "TEXT_OBJECT" 0 24 40 22 ""))
(setf *main-menubar*
©
(dwt:menu-bar *app-window* "MAIN_MENUBAR" nil nil))
(setf ‘option-menu-entry*
©
(dwt:pull-down-menu-entry
‘main-menubar* "OPTION_MENU_ENTRY" 0 0
(dwt:latinl-string "Options”)
(setf ‘options-menu*
©
(dwt:menu
*main-menubar*
"OP TION S_MENU"
0 0
DwtMenuPulldown
DwtOrientationVertical
nil nil nil))
nil nil))
(setf ‘exit-button*
©
(dwt:push-button
‘options-menu* "MESSAGE_BUTTON" 0 0
(dwt:latinl-string "Message")
(dwt+:make-decw-callback-point 'display-message)
nil) )
(setf ‘message-button*
(dwt:push-button
‘options-menu* "EXIT_BUTTON" 0 0
(dwt:latinl-string "Exit")
(dwt+:make-decw-callback-point 'exit-lisp)
nil))))

2-8

DWT ;MAIN-w i n d o w creates the application’
s main window. All widgets are
children of the main window or its children. When calling d w t :m a i n -w i n d o w ,
you supply the name of the main window’
s parent widget, the name of the
main window, its X and Y coordinates, and its length and width in pixels. The

Creating a User Interface

parent of the main window is created when the Toolkit is initialized by the
application at run time. Initialization is described in Section 3.1.1.
©

dwt : s - text creates

the sim p le text widget, which is a child o f the m ain

window. Formal parameters name the parent widget, the window’
s name, its
position and size, and any initial text to be displayed in the window.
©

DWT:menu- bar creates the main menu bar. This menu bar is the child of the

application main window, and its name is MAIN_MENUBAR. The last two
parameters allow you to name two callback functions: an application function
and a help function. Because these parameters are specified as n il , this
menu bar does not call back to either type of function.

© A pull-down menu entry is created with the dwt : pull -down-menu- entry
function. It defines the attributes of the labels that appear in the menu bar.
In this example, there is only one menu entry, the Options entry. Its parent
is the main menu bar. Its label, “
Options”
, appears at offset 0,0 within the
menu bar. Its name is OPTION_MENU_ENTRY and it has one child—the
Options menu.
The text of the labels is converted to compound strings by the
DWT :LATIN1-STRING function. All text that is displayed in a window must
be converted to compound strings. A compound string describes not only
the text string to be displayed, but also the character set to be used and the
writing direction.
©

dwt : menu creates the Options menu.

This menu is defined as follows:

Its parent is the main menu bar.

Its name is OPTIONS.MENU.

It is at offset 0,0 from the upper left comer of the menu entry.

It is a pull-down menu, defined with the symbolic constant
DwtMenuPulldown, defined in LISP$EXAMPLES:DWTAPPL.LSP.

It is a vertical pull-down menu, defined with the symbolic constant
DwtOrientationVertical, defined in LISP$EXAMPLES:DWTAPPL.LSP.

There are three possible callback functions for this menu—a map callback,
an application callback, and a help callback. All three are defined as n il .

DWT:PUSH-BUTTON defines the Message and Exit p u sh b u tton s. Like
the other calls to high-level functions, the calls to dwt :push -button
define the parent widget, the widget name, the location, and the
label. Unlike the other widgets, these push buttons define callback
functions, using the dwt+:MAKE-decw-callback-POINT function in
LISP$EXAMPLES:DECW-PUBLIC.LSP. dwt+:M A K e-decw -callback-point
creates a structure with the address of the callback function.

2.4 Low-Level Functions
Like high-level functions, low-level Toolkit functions are called directly from
LISP. However, you supply widget attributes in an argument list, not as formal
parameters. You create an argument list with the DWT+: c r e a t e -a r g l i s t function,
defined in the LISP$EXAMPLES:DECW-PUBLIC.LSP source file.
You define the arguments as a list of triples of the form
(attribute-name value data-type ...).

Creating a User Interface

2-9

Attribute-name is a string; value is an arbitrary type; data-type is a keyword
indicating the C type to use. Symbolic constants for the attribute names known
to standard Ibolkit widgets are defined in LISP$EXAMPLES:DWTAPPL.LSP.

The DWT+: CREATE-ARGLIST function returns two values: the argument list and
the length of the list. You can call d w t +:CREATE-a r g l i s t within the context of the
m u l t i p l e -v a l u e -b i n d function to assign the return values to named variables.
For example, the recipe application displays a message box when the user
activates the Message push button. This message box is created at run time by
the d w t :m e s s a g e -b o x —c r e a t e low-level function, as shown in Example 2—8.
Example 2-8:
O
©
©
©

Creating a Message Box

(defun display-message (ap)
(dwt:manage-child
(multiple-value-bind (arglist argcount)
(dwt+:create-arglist
(list DwtNLabel "This is a message." :compound-string
DwtNokLabel "Acknowledged" :compound-string))
(dwt:message-box-create *app-window* "MY_MESSAGE"
arglist argcount))))

O The display-message function takes an argument pointer as its argument,
the value passed to this callback function from DECwindows. See Chapter 3
for information on the argument pointer.
©

d w t +: c r e a t e -a r g l i s t is passed a list of triples defining the DwtNlabel

and the DwtNokLabel attributes of the message box. DwtNlabel is set
to the string "This is a message." and DwtNokLabel is set to the string
"Acknowledged". Each one is a compound string.

m u l t i p l e -v a l u e -b i n d

assigns the two return values to the variables a r g l i s t

and a r g c o u n t .
© The message box is created by calling d w t :MESSAGE-b o x -c r e a t e , which takes
the paren t widget, the w id get name, the argument list, and the argument
count as its parameters.
© The message box is not displayed until it is managed. This is done with
d w t :m a n a g e —CHILD, described in Chapter 3.
When the application calls back to d i s p l a y -m e s s a g e , a message box like the one
shown in Figure 2-3 is displayed.

-10

Creating a User Interface

Figure 2-3:

A Message Box

*
This is a message.

Acknowledged
MLO-003389

Creating a User Interface

2-11

Chapter 3

Building a DECwindows Application
Every DECwindows application has a similar structure, no matter what function
the application performs. That is, a main loop determines which widget the
user has selected. As a result of being selected, a widget may invoke a callback
function to perform some function. When the callback function has completed,
the user interface returns control to the main loop.
Chapter 2 describes how to define the user interface. This chapter describes how
to access that user interface from a DECwindows application and how to write
the callback functions that the user interface invokes.

3.1

Accessing the User Interface
To access the user interface, the application must perform the following steps:
1. Initialize DECwindows
2. Create the application’
s widgets
3. Realize the top-level widget
4. Invoke the application’
s main loop

3.1.1 Initialization
Initialization performs several essential startup functions, including
establishing the connection between the client application and the server. It
also creates a widget that is the parent of the application’
s main window.
Simple initialization is performed by the dwt : initialize function. More
flexible but more complicated initialization can be done using the functions
DWT:TOOLKIT-INITIALIZE, DWT: CREATE-APPLICATION-CONTEXT, DWT:OPEN-DISPLAY,
and DWT:APP-CREATE-SHELL.

If the user interface for the recipe example were defined by high-level functions,
you would initialize DECwindows as follows:
(setf *top-level*
(dwt:initialize "Recipe Book / Calorie Counter"
"Lispclass" 0 0 0 0 ) )

When d w t :i n i t i a l i z e returns, it sets the variable called *t o p -l e v e l * to the
top-level widget for the application. Your application should call d w t :i n i t i a l i z e
only once.

Building a DECwindows Application

3-1

If you define the user interface with the UIL, as in the source files supplied in
LISP$EXAMPLES, you must also initialize the UID and prepare it for use by
DECwindows. In this case, you have to call the Tbolkit functions in the following
order:
1. The d w t :i n i t i a l i z e -d r m function prepares the application to use the DRM
functions.
2. The DWT:i n i t i a l i z e function initializes the DECwindows Toolkit.
3. The DRM hierarchy is the set of UID files containing the widget definitions.
The DWT:o p e n -h i e r a r c h y function opens these UID files.
4. The d w t :r e g i s t e r -d r m -n a m e s function registers the names and associated
values for access by DRM. The values can be callback functions, pointers
to user-defined data, or other values. DRM uses this information to resolve
symbolic references in UID files to their run-time values.
Because the recipe application defines its user interface in a UID file, it must call
DRM functions in addition to d w t :i n i t i a l i z e , as shown in Example 3—1.
Example 3-1:

Initializing a UIL Application

(dwt:initialize-drm)
(unless *top-level*
(setf *top-level*
(dwt:initialize "Recipe Book / Calorie Counter"
"Lispclass" 0 0 0 0)))
(unless *drm-hierarchy*
(setf *drm-hierarchy*
(dwt:open-hierarchy 1 (dwt+:make-asciz-array *uil-file*) nil))
(dwt:register-drm-names
(dwt+:make-register-callback-list *uil-callback-names*
(uil-callback-points))
(length *uil-callback-names*))

In Example 3— 1, *uil-file* is a variable that has been initialized to the name
of the application’
s UIL file; *uil-cailback-names* is a variable that has been
initialized to the names of the application’
s callback functions, as described in
Section 3.2.1. uil-callback-points is a function that creates a list of callback
entry points, as described in Example 3—5.

3.1.2

Creating Widgets
Widgets are created with Tbolkit intrinsic or DRM functions. The intrinsic
functions create widgets on the basis of definitions made by high-level or low-level
functions. The DRM functions create widgets on the basis of definitions in UID
files.
In Section 2.3, the m a k e -u s e r - i n t e r f a c e function defined a portion of the recipe
widget hierarchy using high-level functions. These widgets are not created
until the m a k e -u s e r -i n t e r f a c e function is invoked and the main window’
s
children are managed. One of the intrinsic functions, either d w t :MANAGE-c h i l d or
d w t :MANAGE-c h i l d r e n , is used to manage children.

3-2

Building a DECwindows Application

dwt : manage- ch ild m a n a ges one w id get at a time, as in:

(dwt:manage-chiId ‘text-widget*)
(dwt:manage-child *main-menubar*)
(dwt:manage-chiId *option-menu-entry*)
(dwt:manage-chiId *exit-button*)
(dwt:manage-chiId ‘message-button*)
DWT :MANAGE-CHILDREN manages every widget in a list. You can construct
this list with a function called dwt+: CREATE-WIDGET-LIST, provided in
LISP$EXAMPLES:DECW-PUBLIC.LSP. This function returns the widget
list and the length of the list. You can pass both these return values to
DWT :MANAGE-CHILDREN as follows:
(multiple-value-bind (widget-list widget-count)
(dwt+:create-widget-list
(list *text-widget*
*main-menubar*
*option-menu-entry*
*exit-button*))
(dwt:manage-children widget-list widget-count))

Similarly, the widgets defined in a UID file are not created or managed until you
call the DRM function dwt : fetch -widget at run time. The term “
fetch”means to
both create the widget and manage its children.
You specify the main window widget of the application and its parent
(the top-level widget created by the call to dwt: i n i t i a l i z e ) in the call to
dwt : fetch - w idget . A s a result of this single call, DRM fetches all the widgets in
the hierarchy.
Example 3-2:

Creating a Widget Hierarchy

(setf *app-window*
(dwt:fetch-widget *drm-hierarchy* "APP_WINDOW" *top-level*))

3.1.3

Realizing the Top-Level Widget
The term “
realize”means to display the widget hierarchy on the workstation
screen. During creation, only the child widgets are created. During realization,
the main window widget is managed and the top-level widget is realized.
The steps for managing and realizing a user interface are the same whether the
user interface has been created with the UIL, the high-level functions, or the
low-level functions:
1. Manage the main window widget. The intrinsic function dwt:MANAGE-child
makes the main window a child of the top-level widget returned by the call to
dwt: i n i t i a l i z e . The entire widget hierarchy is managed as a result of this
call.
2. Realize the top-level widget. The intrinsic function dwt:REALIZE-widget
displays the entire widget hierarchy.
Example 3-3 shows how these functions are called to realize the recipe
application’
s user interface.

Building a DECwindows Application

3-3

Example 3-3:

Realizing the User Interface

(dwt:manage-chiId *app-window*)
(dwt:realize-widget *top-level*)

3.1.4

Calling the Main Loop
The Tbolkit provides an intrinsic function to act as the main loop of any
DECwindows application. The main loop handles callback events; that is, it
determines which widgets are selected and which callback functions to invoke.
Example 3-4 shows how the recipe application invokes the d w t :m a i n -l o o p
function. This step is the same regardless of how you create the user interface.
Example 3-4:

Calling the Main Loop

(catch 'original-lisp (dwt:main-loop))

In this example, d w t :m a i n -l o o p is called within the context of the c a t c h special
form. A callback routine can return to LISP by issuing a call to the t h r o w special
form and naming the o r i g i n a l -l i s p label. Once you return to LISP in this way,
you cannot restart this or any other DECwindows application from the same
LISP session; you must first exit and restart LISP. Tb write an application that
can be restarted, you must explicitly create an application context and handle
the DECwindows display rather than letting d w t :i n i t i a l i z e and d w t :MAi n -l o o p
handle these things for you.

3.2 Writing a Callback Function
Although the main loop controls the DECwindows application, it is your LISP
callback functions that perform the functions of the application. Writing LISP
functions that operate within a DECwindows application requires special
considerations:
• Defining the callback functions in LISP
You use the callback facility to let LISP know which functions DECwindows
will call back to.
• Accessing the callback structure
DECwindows widgets always call back with an argument list containing three
arguments: the widget ID, user-defined data (called a tag), and a callback
structure that differs, depending on the type of widget that is calling back.
Your callback function must be written in a way that correctly accesses these
arguments.

3.2.1

Declaring Callback Functions
Callback functions must be declared in LISP before the application invokes the
main loop. These entry points must also be registered with DECwindows. You
can use the m a k e -c a l l -b a c k -r o u t i n e function to declare the callback functions
for LISP and the DWT:REGISTER-DRM-NAMES function to register them with
DECwindows. (See VAX LISP/ VMS System Access Programming Guide for more
information about m a k e -c a l l -b a c k -r o u t i n e .)

3-4

Building a DECwindows Application

To declare the callback points for both LISP and DECwindows, you must first
create a list of callback names. The list contains all the callback function names
as they are known to DECwindows. They must be in uppercase letters and
appear in alphabetical order within the list. Each name is written as a separate
string. Example 3—5 shows the list of callback names for the recipe application.
The list is stored in the variable called *d i l -c a l l b a c k -n a m e s *.
Example 3-5:

Creating a List of Callback Names

(defvar *uil-callback-names* '("DISPLAY_MESSAGE" "DW_CALORIES"
"DW_PRINT_RECIPE” "ESCAPE_TO_LISP"
"EXIT_LISP" "PRACTICE_CALLBACK"
"REMEMBER TEXT ID"))

You then define the callback entry points, using the m a k e -c a l l -b a c k -RODTINE
function. The names for m a k e -c a l l -b a c k -r o u t i n e are written as they appear in
LISP. That is, they can contain lowercase letters and hyphens. These callback
points are also placed in a list in the same order as they appear in the list
of names; otherwise, the function’
s external name will not be correctly paired
with its LISP name. Example 3—6 shows how the entry points for the recipe
application are created by the u i l -c a l l b a c k -p o i n t s function:
Example 3-6:

Creating a List of Callback Entry Points

(defun uil-callback-points ()
(list (make-call-back-routine
# ' (lambda (ap) (display-message ap)))
(make-call-back-routine
#'(lambda (i) (dw-calories i)))
(make-call-back-routine
#'(lambda (r) (dw-print-recipe r)))
(make-call-back-routine
# ' (lambda (ap) (escape-to-lisp ap)))
(make-call-back-routine
#'(lambda (i) (declare (ignore i)) (exit)))
(make-call-back-routine
# ' (lambda (ap) (practice-callback ap)))
(make-call-back-routine
#' (lambda (ap) (remember-text-id ap)))))

After you create the lists, you create a register list of the callback points with
the dwt+ : make-r e g is t e r - l i s t function. This function is in the file called
LISP$EXAMPLES:DECW-PUBLIC.LSP, which you can load into your LISP
application. For example, you can create the callback register list for the recipe
application as follows:
(dwt+:make-register-callback-list *uil-callback-names*
(uil-callback-points))

This register list is of the appropriate form to pass to the
DWT :REGISTER-DRM-NAMES function, as follows:
(dwt:register-drm-names
(dwt+:make-register-callback-list *uil-callback-names*
(uil-callback-points))
(length *uil-callback-names*))

Building a DECwindows Application

3-5

3.2.2

Accessing the Callback Argument List
When DECwindows calls back to LISP, it always passes a pointer to an argument
list containing the widget ID, the user-defined data (tag), and a callback
structure. Figure 3—1 shows the form of the argument list. You can either
define your callback function to explicitly access the three arguments, or you can
access them indirectly through an argument pointer (AP) mechanism. All of the
examples in this section are written in terms of the latter approach.
Figure 3-1:

DECwindows Callback Argument List

Your callback function can access any of the items on
the argu m en t list, u sin g the dwt+: get - callback - w idget ,
dwt+: get - callback - tag , and dwt+ : get - callback -reason routines, defined in

LISP$EXAMPLES:DECW-PUBLIC.LSP.
3.2.2.1

Accessing the Widget ID

The dwt+: get - callback -w idget function is in
LISP$EXAMPLES:DECW-PUBLIC .LSP, a file that you can load
into your LISP application. It returns the widget that called back to LISP. In
the recipe application, the text widget is defined to call back to a function called
remember- tex t - id when it is created, as follows:
CALLBACKS {
CREATE = PROCEDURE remember_text_id;
};
REMEMBER-TEXT-ID is a LISP function. It uses DWT+: GET-CALLBACK-WIDGET to
return the ID of the text widget. It then stores that ID in the variable called
*TEXT-WIDGET*.

Example 3—7 shows how the remember- tex t - id function accesses the callback
widget.
Example 3-7:

Accessing the Callback Widget

(defun remember-text-id (ap)
(declare (special *text-widget*))
(format t "The text widget called back~%")
(setf *text-widget* (dwt+:get-callback-widget ap)))

3—6

Building a DECwindows Application

Other LISP functions can then use this widget to read from or write to the text
widget. For instance, the p r i n t -t o -w i n d o w function in Example 3-8 references
the *t e x t -w i d g e t * variable to write to the window. It first checks to make sure
that the variable contains a widget ID. If not, it displays an error message.
Otherwise, it calls DWT: s -t e x t -s e t -s t r i n g to write to the text widget. The
function DWT:s -t e x t -s e t -s t r i n g is high level. See Part II for more information
about DWT: s -t e x t -s e t -s t r i n g .
Example 3-8:

Writing to a Text Widget

(defun print-to-window (the-string)
(if (null *text-widget*)
(error "The text widget never called back with its ID."))
(dwt:s-text-set-string *text-widget* the-string))

In the recipe application, the d w -p r i n t -r e c i p e function uses p r i n t -t o -w i n d o w to
pretty-print a recipe, d w -p r i n t -r e c i p e is shown in Example 3-9.
Example 3-9:

Pretty-Printing a Recipe

(defun dw-print-recipe (the-recipe)
"DW-PRINT-RECIPE recipe
Pretty print a recipe, number of servings, and calories/serving,
using the DECwindows Toolkit."
(let ((recipe (convert-arg the-recipe)))
(print-lists recipe)
(print-to-window
(concatenate 'string
(format nil "~A:" (recipe-name recipe))
(princ-to-string #\linefeed)
(princ-to-string #\linefeed)
(format nil "~A" *part-of-recipe*)
(princ-to-string #\linefeed)
(format nil "Servings: ~D" (recipe-servings recipe))
(princ-to-string #\linefeed)
(format nil "Calories/serving: ~D"
(dw-calories the-recipe))))))
(defun print-lists (recipe)
(setf *part-of-recipe* nil)
(mapc # ' (lambda (a u i)
(setf *part-of-recipe*
(concatenate 'string
*part-of-recipe*
(format nil "~A ~D ~A” (rationalize a) u i)
(princ-to-string #\linefeed))))
(recipe-amount recipe)
(mapcar
♦ ' (lambda (i) (get i 'units))
(recipe-ingredients recipe))
(recipe-ingredients recipe)))

3.2.2.2

Accessing the User-Defined Data (Tag)

The d w t +: g e t -c a l l b a c k -t a g function, supplied in
LISP$EXAMPLES:DECW-PUBLIC.LSP, lets you access the user-defined data
with which the callback function was invoked. For example, the c o o k i e s _ b o t t o n
is defined to call back to DW-PRINT-RECIPE as follows:

Building a DECwindows Application

3-7

CALLBACKS {
ACTIVATE = PROCEDURE dw_print_recipe (r_cookies);
}

The r_ c o o k i e s argument, in turn, is defined in the VALUE section of the UIL as
follows:
r_cookies : 6;

In order for LISP to determine what value has been passed to the
d w -p r i n t -r e c i p e function, it must call d w t + :g e t -c a l l b a c k -t a g . Example 3-10
shows how the recipe application defines the c o n v e r t -a r g function, which uses
d w t +: g e t -c a l l b a c k -t a g to locate the arguments passed back by DECwindows
and translate them into the LISP representation of those arguments. A CASE
statement converts the argument to the appropriate LISP representation—either
a symbol or a structure. In the cookies example, DECwindows passes back the
number 6 to LISP and c o n v e r t -a r g translates it into the structure COOKIES.
Example 3-10:

Accessing Callback Arguments

(defun convert-arg (the-recipe)
(let ((tag (dwt+:get-callback-tag the-recipe)))
(declare (fixnum tag))
(case tag
(1 'butter)
(2 'milk)
(3 'bread)
(4 'egg)
(5 'syrup)
(6 cookies)
(7 french-toast)
(8 toast)
(9 omelet))))

The DW-c a l o r i e s function in Example 3-11 uses c o n v e r t -a r g to determine
whether DECwindows has passed back an ingredient or a recipe.
Example 3-11:

Printing Calorie Information

(defun dw-calories (the-recipe)
"DW-CALORIES the-recipe
Calculate the number of calories for an ingredient/unit-of-measure
or for a recipe/serving, using the DECwindows Toolkit.”
O (let ((x (convert-arg the-recipe)))
(cond ((symbolp x)
©
(print-to-window
(format nil "~A: ~D calories/~A"
x (get x 'calories) (get x 'units))))
((recipe-p x)
(numerator
(floor
(reduce #'+
(mapcar #'*
(mapcar #'(lambda (i) (get i 'calories))
(recipe-ingredients x))
(recipe-amount x)))
(recipe-servings x)))))))

3-8

dw- c a l o r ie s uses convert -arg to determine what item was selected—either
an ingredient or a recipe.

Building a DECwindows Application

3.2.2.3

p r in t - to - window disp lays the n um ber o f calories and the u nit o f m easu re i f
the a rgu m en t is an in gredien t (represented as a symbol).

Accessing the Callback Structure

The d w t + :g e t -c a i l b a c k -s t r u c t u r e -a d d r e s s function, supplied in
LISP$EXAMPLES:DECW-PUBLIC.LSP, returns the address of the callback
structure with which the callback function was invoked. You can use this address
as the :d a t a argument to the constructor function for any of the alien structures
defined in LISP$EXAMPLES:DECW-CALLBACK-STRUCTURES.LSP.
For example, you could define a function to get a DwtScaleCallbackStruct
structure from an argument pointer. (This type of callback structure is passed by
Scale widgets.)
(defun get-callback-DwtScaleCallbackStruct (ap)
(make-DwtScaleCallbackStruct
:data (dwt+:get-callback-structure-address ap)))

You could then use the alien structure accessor functions to get the value now
indicated by the scale widget, as in m y -s c a l e -w i d g e t -c a l l b a c k , shown below.
(defun my-scale-widget-callback (ap)
(setf *my-scale-value*
(DwtScaleCallbackStruct-value
(get-callback-DwtScaleCallbackStruct ap))))

LISP$EXAMPLES:DECW-PUBLIC.LSP also includes two functions for getting
the values of the reason and the event fields that are present in any callback
structure. Both d w t +:g e t -c a l l b a c k -r e a s o n and d w t +: g e t -c a l l b a c k -e v e n t take
an argument pointer as their single argument.
d w t +: g e t -c a l l b a c k -r e a s o n returns a callback reason as an integer.

Symbolic
constants for the standard DECwindows Toolkit reasons are defined in
LISP$EXAMPLES:DWTAPPL.LSP. For example, if the callback is due to widget
activation (such as pushing a push button), the reason value is 10, which is the
value of the constant DwtCRActivate.
returns an X event structure. You can pass this
structure as the : e v e n t argument to the c l x :p r o c e s s -e v e n t routine in order to
use the CLX event-processing mechanisms to access the fields of this structure.
See Chapter 12 of this manual for more information about CLX event processing
or Part IV for more specific information about the c l x :p r o c e s s -e v e n t function.
d w t +: g e t -c a l l b a c k -e v e n t

Building a DECwindows Application

3-9

Part II
Reference to the DECwindows ToolKit

All DECwindows Tbolkit routines can be called from VAX LISP. They ai;e in the
LISP package named d w t :. In most cases, the number of arguments and return
values is the same in VAX LISP as in the MIT C and VAX versions of the routine.
In some cases, the LISP routine differs slightly.
VAX LISP requires special LISP versions of the Toolkit routines because of the
way LISP represents data structures. For example, in the MIT C version of
these routines, objects such as widgets and argument lists are represented as C
typedefs (user-defined data types). In VAX LISP, they must be represented as
alien structures.
The Toolkit manages so many kinds of data structures that it is impractical for
VAX LISP to provide alien structure definitions for all Toolkit objects. However,
VAX LISP does provide the following source files in LISP$EXAMPLES. When
your application must access a specific type of structure, you can include the alien
structure definition from LISP$EXAMPLES.
• DWTAPPL.LSP defines Toolkit constants and some alien structures.
• DECW-CALLBACK-STRUCTURES.LSP defines callback structures.
• DECW-PUBLIC.LSP defines more structures and many functions to construct
and dereference those structures.
Therefore, to call a DECwindows routine, you need the following things:
• VMS DECwindows Toolkit Routines Reference Manual
• The routine description in Part II of this book
• DWTAPPL.LSP, DECW-CALLBACK-STRUCTURES.LSP, and
DECW-PUBLIC.LSP, found in LISP$EXAMPLES
Determine how to call the routine as follows:
1. Look up the complete routine description in the VMS DECwindows Tbolkit
Routines Reference Manual.
2. Locate the description of the routine in Part II of this book. It describes
the argument list and return values for each Tbolkit routine that you can
call from VAX LISP. Note the names of any alien structures used as either
arguments or return values. An argument or return value is either a Common
LISP type such as i n t e g e r , a CLX type such as c l x :w i n d o w , a DWT type such
as d w t :w i d g e t , or an MIT C structure such as Xtlnputld.
3. If the object is a Common LISP, CLX, or DWT type, the data type is already
defined by VAX LISP. You need do nothing more.
If the object’
s MIT C name is given, find its alien structure or constructor
definition in LISP$EXAMPLES and copy it into your LISP source file. If the
MIT C name is not there, you will need to build the structure yourself. Look
in DECW$INCLUDE:*.H for the C definition of these objects.

DWT:ADD-ACTIONS Intrinsic Function

DWT:ADD-ACTIONS Intrinsic Function
Declares an action table and registers it with the translation manager.
Format
DWT:ADD-ACTIONS action num-actions

action
num-actions

XtActionList
INTEGER

Return Value
U nspecified.

DWT:ADD-CALLBACK Intrinsic Function
Adds a callback procedure to a callback list.
Format
DWTiADD-CALLBACK widget callback-name callback client-data

widget

DWT:WIDGET

callback-name
callback

XtCallbackProc

client-data

INTEGER or alien structure

STRING

Return Value
U nspecified.

DWT:ADD-CALLBACKS Intrinsic Function
Adds a list of callback procedures to a callback list.
Format
DWTADD-CALLBACKS widget callback-name newcallbacks

widget
callback-name
newcallbacks

DWT:WIDGET
STRING
XtCallbackList

Return Value
U nspecified.

DWT-1

DWT:ADD-CONVERTER Intrinsic Function

DWT:ADD-CONVERTER Intrinsic Function
Registers a new resource converter.
Format
DWT:ADD-CONVERTER from-type to-type converter convert-arglist argcount

from-type
to-type
converter

STRING
STRING

convert-arglist

XtConverter
XtConvertArgList

argcount

INTEGER

Return Value

Unspecified.

DWT:ADD-EVENT-HANDLER Intrinsic Function
Registers an event handler procedure with the dispatch mechanism.
Format
DWTiADD-EVENT-HANDLER widget event-mask other client-proc client-data

widget
event-mask

XtEventMask

other

INTEGER

client-proc
client-data

XtEventHandler
INTEGER or alien structure

DWT:WIDGET

Return Value

Unspecified.

DWT:ADD-EXPOSURE-TO-REGION Intrinsic Function
Merges Expose and Graphics Expose events into a region.
Format
DWT:ADD-EXPOSURE-TO-REGION event region

event

DWT:EVENT

region

INTEGER

Return Value

Unspecified.

DWT—2

DWT:ADD-FONT-LIST C om p ou n d String Function

DWT:ADD-FONT-LIST Compound String Function
Adds an entry to a font list.
Format
DWT:ADD-FONT-LIST font-list font charset
font-list

DwtFontList

font
charset

INTEGER
INTEGER

Return Value

A DwtFontList alien structure representing the new font list.

DWT:ADD-GRAB Intrinsic Function
Redirects user input to a modal widget.
Format
DWTADD-GRAB widget exclusive spring-loaded
Widget

DWT: WIDGET

exclusive
spring-loaded

integer
integer

Return Value

Unspecified.

DWT:ADD-INPUT Intrinsic Function
Registers a new file for input.
Format
DWTADD-INPUT source condition client-proc client-data
source

INTEGER

condition

INTEGER or alien structure

client-proc

XtlnputCallbackProc

client-data

INTEGER or alien structure

Return Value

An Xtlnputld alien structure representing the input source identifier.

DWT—3

DWT:ADD-RAW-EVENT-HANDLER Intrinsic Function

DWT:ADD-RAW-EVENT-HANDLER Intrinsic Function
Registers an event handler procedure with the dispatch mechanism without
causing the server to select that event.
Format
DWT:ADD-RAW-EVENT-HANDLER widget event-mask other client-proc client-data
widget

DWT:WIDGET

event-mask

DWT:EVENT

other

INTEGER

client-proc

XtEventHandler

client-data

INTEGER or alien structure

Return Value

Unspecified.

DWT:ADD-TIME-OUT Intrinsic Function
Creates a timeout.
Format
DWT:ADD-TIME-OUT interval client-proc client-data
interval

INTEGER

client-proc

XtTimerCallbackProc

client-data

INTEGER or alien structure

Return Value

An Xtlntervalld alien structure representing the interval identifier.

DWT:ADD-WORK-PROC Intrinsic Function
Registers a work procedure in the default application context.
Format
DWTiADD-WORK-PROC work-proc client-data
work-proc

XtWorkProc

client-data

INTEGER or alien structure

Return Value

An XtWorkProcId alien structure representing the work procedure identifier.

DWT—4

DWT:APP-ADD-INPUT Intrinsic Function

DWT:APP-ADD-INPUT Intrinsic Function
R egisters a new file for input.

Format
DWTAPP-ADD-INPUT context source condition client-proc client-data

context

XtAppContext

source
condition
client-proc
client-data

in t e g e r
INTEGER or alien structure
XtlnputCallbackProc
INTEGER or alien structure

Return Value
An X tln p u tld alien structu re represen tin g the in pu t file identifier.

DWT:APP-ADD-TIME-OUT Intrinsic Function
C rea tes a tim eout value.

Format
DWTAPP-ADD-TIME-OUT context interval client-proc client-data

context

XtAppContext

interval
client-proc
client-data

INTEGER
XtTimerCallbackProc
INTEGER or alien structure

Return Value
An X tln terv a lld alien structure rep resen tin g the tim eout value identifier.

DWT:APP-ADD-WORK-PROC Intrinsic Function
R egisters a w ork procedure.

Format
DWTAPP-ADD-WORK-PROC context client-proc client-data

context

XtAppContext

client-proc
client-data

XtWorkProc
INTEGER or alien structure

Return Value
An X tW orkProcId alien structu re rep resen tin g the w ork p rocedu re identifier.

DWT-5

DWT:APP-CREATE-SHELL Intrinsic Function

DWT:APP-CREATE-SHELL Intrinsic Function
C reates a new top-level application w id get th at is the root o f the w id get hierarchy.

Format
DWT:APP-CREATE-SHELL name class widget-class display arglist argcount
name
class

STRING
STRING

widget-class

INTEGER

display

CLX:DISPLAY

arglist

ArgList

argcount

INTEGER

Return Value
An object o f type dwt: widget represen tin g the new widget.

DWT:APP-MAIN-LOOP Intrinsic Function
P rocesses input.

Format
DWT:APP-MAIN-LOOP context
context

INTEGER

Return Value
U nspecified.

DWT:APP-NEXT-EVENT Intrinsic Function
R eturns the value from the head of an application ’
s in p u t queue, or w aits for an
event if none are queued.

Format
DWTAPP-NEXT-EVENT context &OPTIONAL event
context

INTEGER

event

DWT:EVENT

Return Value
An object o f type dwt : event represen tin g the n ext event in the queue.

DWT—6

DWT:APP-PEEK-EVENT Intrinsic Function

DWT:APP-PEEK-EVENT Intrinsic Function
R etu rns the value from the head o f a given application ’
s in pu t qu eu e w ithout
rem ov in g in pu t from the queue.

Format
DWT:APP-PEEK-EVENT context &OPTIONAL event
context

INTEGER

event

DWT:EVENT

Return Value
U nspecified.

DWT:APP-PENDING Intrinsic Function
D eterm in es if th ere are any events on the in pu t qu eu e for a given application.

Format
DWTAPP-PENDING context
context

INTEGER

Return Value
An X tln p u tM a sk in teger b it m a sk rep resen tin g the O R o f XtIM XEvent,
XtIMTimer, and X tIM A lternateInput. A n on zero value m ean s there are events
p en d in g from the X server, timer, or other in pu t sources.

DWT:APP-PROCESS-EVENT Intrinsic Function
P rovides direct control o f the p roce ssin g o f different types o f input.

Format
DWTAPP-PROCESS-EVENT context input-mask
context

XtAppContext

input-mask

XtlnputMask

Return Value
U nspecified.

DWT—7

DWT:ATTACHED-DB High-Level Function

DWT:ATTACHED-DB High-Level Function
C reates an attached d ia log box widget.

Format
DWTATTACHED-DB parent-widget name default-position x y title style
map-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

default-position
xy

INTEGER
INTEGER

title

COMPOUND-STRING

style

INTEGER

map-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type DWT:w idget rep resen tin g the new widget.

DWT:ATTACHED-DB-CREATE Low-Level Function
C reates an attached dia log box widget.

Format
DWT:ATTACHED-DB-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT: WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type DWT:w idget rep resen tin g the new widget.

DWT:ATTACHED-DB-POPUP-CREATE Low-Level
Function
C reates an attached pop-up d ia log box widget.

Format
DWT:ATTACHED-DB-POPUP-CREATE parent-widget name override-arglist override-argcount

DWT—8

DWT:ATTACHED-DB-POPUP-CREATE Low-Level Function

parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type dwt :

id g et rep resen tin g the new widget.

DWT:AUGMENT-TRANSLATIONS Intrinsic Function
M erges new tran slation s into an ex istin g tran slation table.

Format
DWT:AUGMENT-TRANSLATIONS widget translation-table
widget

DWT:WIDGET

translation-table

XtTranslations

Return Value
U nspecified.

DWT:BEGIN-COPY-TO-CLIPBOARD Cut-and-Paste
Function
S e ts up stora ge and data structu res to receive clipboard data.

Format
DWT:BEGIN-COPY-TO-CLIPBOARD display window clip-label widget callback
&OPTIONAL it e m -id
display

CLX:DISPLAY

window

CLX:WINDOW

clip-label

COMPOUND-STRING

widget

DWT:WIDGET

callback

VoidProc

item-id

INTEGER

Return Values
Tw o values:
• An in teger rep resen tin g the item-id.
• O ne o f tw o p ossib le constants w h ose in teger valu es re p resen t the clipboard
status:

DWT-9

DWT:BEGIN-COPY-TO-CLIPBOARD Cut-and-Paste Function

DWT: CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:BUILD-EVENT-MASK Intrinsic Function
R etrieves the event m a sk for a widget.

Format
DWT:BUILD-EVENT-MASK widget

Widget

DWT:WIDGET

Return Value
An E ventM ask alien structure rep resen tin g the event mask.

DWT:CALL-ACCEPT-FOCUS Intrinsic Function
C a lls a w id get’
s accept in pu t focus procedure.

Format
DWT:CALL-ACCEPT-FOCUS widget time
W idget

DWT:WIDGET

time

INTEGER

Return Value
The accept focu s p rocedu re (XtAcceptFocusProc) return, w hich is false if accept
focus is nil.

DWT:CALL-CALLBACKS Intrinsic Function
E x ecu tes the procedu res in a callback list.

Format
DWT:CALL-CALLBACKS widget callback-name calldata

widget
callback-name

DWT: WIDGET

calldata

INTEGER or alien structure

Return Value
U nspecified.

DWT—10

STRING

DWT:CALLBACK-EXCLUSIVE Intrinsic Function

DWT:CALLBACK-EXCLUSIVE Intrinsic Function
M aps a pop-up shell from a given w id ge t’
s callback list.

Format
DWT:CALLBACK-EXCLUSIVE widget client-data callback-data
widget

DWT: WIDGET

client-data

XtClientData

callback-data

INTEGER or alien structure

Return Value
U nspecified.

DWT:CALLBACK-NONE Intrinsic Function
M aps a pop-up shell from a given w id get’
s callback list.

Format
DWT:CALLBACK-NONE widget client-data callback-data
widget

dwt : widget

client-data
callback-data

XtClientData
XtClientData

Return Value
U nspecified.

DWT:CALLBACK-NONEXCLUSIVE Convenience
Function
M a ps a pop-up shell from a given w id get’
s callback list.

Format
DWT:CALLBACK-NONEXCLUSIVE widget client-data callback-data
widget

dwt : widget

client-data

XtClientData

callback-data

INTEGER or alien structure

Return Value
U nspecified.

DWT—11

DWTiCALLBACK-POPDOWN Intrinsic Function

DWT:CALLBACK-POPDOWN Intrinsic Function
B rin gs dow n a w id get that w as pop p ed up w ith on e o f the callback routines
DWT:CALLBACK-NONE, DWT:CALLBACK-NONEXCLUSIVE, or DWT: CALLBACK-EXCLUSIVE.

Format
DWT:CALLBACK-POPDOWN widget client-data callback-data
widget

DWT: WIDGET

client-data
callback-data

INTEGER or alien stru ctu re
INTEGER or alien stru ctu re

Return Value
U nspecified.

DWT:CALLOC Intrinsic Function
A llocates and in itializes an array.

Format
DWT:CALLQC num-elements element-size
num-elements
element-size

in t e g e r
in t e g e r

Return Value
An in teger re p resen tin g the storage address.

DWT:CANCEL-COPY-FORMAT Cut-and-Paste
Function
In d icates that the application w ill no lon g er su p p ly a data item to the clipboard
that the application had previou sly p a sse d by name.

Format
DWT:CANCEL-COPY-FORMAT display window data-id

DWT—12

display

CLX: D ISP LAY

window

CLX: WINDOW

data-id

in t e g e r

DWT:CANCEL-COPY-FORMAT Cut-and-Paste Function
Return Value
O ne o f tw o p ossib le con stan ts w h ose in teger values rep resen t the clipboard status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:CANCEL-COPY-TO-CLIPBOARDCut-and-Paste
Function
C a n cels the copy to clipboard that is in progress.

Format
DWT:CANCEL-COPY-TO-CLIPBOARD display window item-id
display

CLX: DISPLAY

window

CLX: WINDOW

item-id

integer

Return Value
U nspecified.

DWT:CAUTION-BOX High-Level Function
C rea tes a caution box widget.

Format
DWT:CAUTION-BOX parent-widget name default-position x y format
label yes-label no-label cancel-label default-push-button
callback help-callback
parent-widget

DWT:WIDGET

name

STRING

default-position
xy
format

INTEGER
INTEGER
INTEGER

label
yes-label
no-label
cancel-label

COMPOUND-STRING
COMPOUND-STRING
COMPOUND-STRING
COMPOUND-STRING

default-push-button

INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type DWT:widget rep resen tin g the new widget.

DWT—13

DWT:CAUTION-BOX-CREATE Low-Level Function

DWT:CAUTION-BOX-CREATE Low-Level Function
C reates a caution box widget.

Format
DWT:CAUTION-BOX-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type DWT:widget rep resen tin g the new widget.

DWT:CHILDREN Convenience Function
R eturns a lis t o f the w id ge t’
s children.

Format
DWT:CHILDREN widget
widget

DWT: WIDGET

Return Value
A list o f the w id get’
s children.

DWT:CLASS Intrinsic Function
Identifies the w id get’
s cla ss structure.

Format
DWT:CLASS widget
Widget

DWT:WIDGET

Return Value
A W id getC la ss alien structu re rep resen tin g a p oin ter to the w id ge t’
s cla ss
structure.

DWT—14

DWT:CLIPBOARD-LOCK Cut-and-Paste Function

DWT:CLIPBOARD-LOCK Cut-and-Paste Function
L ocks the clipboard from a ccess by other apphcations.

Format
DWT:CLIPBOARD-LOCK display window
display

clx : Di sp lay

window

CLX: WINDOW

Return Value
O ne o f tw o p ossib le con stan ts w h ose in teger valu es rep resen t the clipboard status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:CLIPBOARD-UNLOCK Cut-and-Paste Function
U nlocks the clipboard, en ablin g it to be accessed by other applications.

Format
DWT:CLIPBOARD-UNLOCK display window remove-locks
CLX:DISPLAY

display
window

CLX: WINDOW

remove-locks

integer

Return Value
O ne o f tw o p ossib le con stan ts w h ose in teger valu es represen t the clipboard status:
DWT:CLIPBOARD-SUCCESS

DWT: CLIPBOARD-LOCKED

DWT:CLOSE-DISPLAY Intrinsic Function
C loses a disp la y and rem ov es it from an application context.

Format
DWT:CLOSE-DISPLAY display
display

CLX: DISPLAY

Return Value
U nspecified.

DWT—15

DWTiCLOSE-HIERARCHY DRM Function

DWTiCLOSE-HIERARCHY DRM Function
C loses a DRM hierarchy.

Format
DWTiCLOSE-HIERARCHY hierarchy-id

hierarchy-id

in t e g e r

Return Value
O ne o f tw o p ossible con stan ts w h ose in teger values represen t the DRM status:
DWT:DRM-SUCCESS

DWT:DRM-FAILURE

DWT:COMMAND-APPEND High-Level Function
A ppends the p a ssed strin g to the current com m an d lin e and execu tes it if
required.

Format
DWT:COMMAND-APPEND widget command

widget
command

DWT: WIDGET
STRING

Return Value
U nspecified.

DWT:COMMAND-ERROR-MESSAGE High-Level
Function
W rites an error m e ssa g e in the com m and w in dow and refresh es the com m and
line.

Format
DWT:COMMAND-ERROR-MESSAGE widget error

Widget
error
Return Value
Unspecified.

DWT—16

DWT: WIDGET
STRING

DWT:COMMAND-SET High-Level Function

DWT:COMMAND-SET High-Level Function
Replaces the current command string with the one passed and executes it if
required.
Format
DWT:COMMAND-SET widget command
widget

DWT:WIDGET

command

STRING

Return Value

Unspecified.

DWT:COMMAND-WINDOW High-Level Function
Creates a command window widget.
Format
DWT:COMMAND-WINDOW parent-widget name prompt lines callback help-callback
parent-widget

DWT:WIDGET

name

STRING

prompt

COMPOUND-STRING

lines

INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type DWT:w i d g e t rep resen tin g the new widget.

DWT:COMMAND-WINDOW-CREATE Low-Level
Function
Creates a command window widget.
Format
DWT:COMMAND-WINDOW-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

DWT—17

DWT:COMMAND-WINDOW-CREATE Low-Level Function
Return Value
An object o f type dwt: widget represen tin g the new widget.

DWT:CONFIGURE-WIDGET Intrinsic Function
M oves and re size s the sib lin g w id get o f the child w id get m ak in g the geom etry
request.

Format
DWT:CONFIGURE-WIDGET widget x y width height borderwidth
widget

DWT:WIDGET

xy
width
height
borderwidth

INTEGER
INTEGER
INTEGER
INTEGER

Return Value
U nspecified.

DWT:CONVERT Intrinsic Function
Invokes resou rce conversions.

Format
DWT:CONVERT widget src-type src-value dst-type dst-value
widget

DWT:WIDGET

src-type

STRING

src-value

XrmValuePtr

dst-type

STRING

dst-value

XrmValuePtr

Return Value
U nspecified.

DWT:CONVERT-CASE Intrinsic Function
D eterm in es the u p p erca se and low ercase equ ivalen ts for a key symbol.

Format
DWT:CONVERT-CASE display keysym lower-return upper-return
display

DWT-18

CLX:DISPLAY

DWT:CONVERT-CASE Intrinsic Function

keysym
lower-return
upper-return

KeySym
KeySym
KeySym

Return Value

Unspecified.

DWT:COPY-FROM-CLIPBOARD Cut-and-Paste
Function
Retrieves a data item from the clipboard.
Format
DWT:COPY-FROM-CLIPBOARD display window format-name buffer length
display

CLX:DISPLAY

window

CLX:WINDOW

format-name
buffer

STRING
STRING

length

INTEGER

Return Values

Four values:
• A string representing the buffer.
• An integer representing num-bytes.
• An integer representing the private-id.
• One of four possible constants whose integer values represent the clipboard
status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-TRUNCATE

DWT:CLIPBOARD-LOCKED

DWT:CLIPBOARD-NON-DATA

DWT:COPY-TO-CLIPBOARD Cut-and-Paste Function
Copies a data item to the clipboard.
Format
DWT:COPY-TO-CLIPBOARD display window item-id format-name buffer
length private-id

&OPTIONAL data-id

DWT—19

DWT:COPY-TO-CLIPBOARD Cut-and-Paste Function

display

CLX:DISPLAY

window

CLX:WINDOW

item-id

INTEGER

format-name
buffer

STRING
STRING

length
private-id
data-id

INTEGER
INTEGER
INTEGER

Return Values
Two values:
• An in teger represen tin g the data-id.
•

O ne o f tw o p ossib le constants w h ose in tegers rep resen t the status as follows:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWTiCREATE-APPLICATION-CONTEXT Intrinsic
Function
C reates an application context.

Format
DWT:CREATE-APPLICATION-CONTEXT

Return Value
XtA ppContext, an in teger represen tin g the application context.

DWT:CREATE-APPLICATION-SHELL Intrinsic
Function
C rea tes a top-level w id get that is the root o f an oth er w id get hierarchy.

Format
DWT:CREATE-APPLICATION-SHELL name widget-class arglist argcount
name

STRING

widget-class

INTEGER

arglist

ArgList

argcount

INTEGER

Return Value
An object o f type DWT:widget rep resen tin g the new widget.

DWT—20

DWT:CREATE-FONT-LIST Compound String Function

DWT:CREATE-FONT-LIST Compound String Function
C rea tes a new font list.

Format
DWT:CREATE-FONT-LIST font charset
font

CLX: FONT

charset

INTEGER

Return Value
DwtFontList, an in teger represen tin g the new font list.

DWT:CREATE-MANAGED-WIDGET Intrinsic Function
C reates and m a n a ges a widget.

Format
DWT:CREATE-MANAGED-WIDGET name widget-class parent-widget arglist argcount
name

STRING

widget-class

INTEGER

parent-widget

DWT:WIDGET

arglist

ArgList

argcount

INTEGER

Return Value
An object o f type DWT:widget rep resen tin g the new widget.

DWT:CREATE-POPUP-SHELL Intrinsic Function
C rea tes a pop-up shell.

Format
DWT:CREATE-POPUP-SHELL name widget-class parent-widget arglist argcount
name

STRING

widget-class

INTEGER

parent-widget

DWT:WIDGET

arglist

ArgList

argcount

INTEGER

Return Value
An object o f type dwt: w idget rep resen tin g the new widget.

DWT—21

DWT:CREATE-WIDGET Intrinsic Function

DWT:CREATE-WIDGET Intrinsic Function
Creates an instance of a widget.
Format
DWT:CREATE-WIDGET name widget-class parent-widget arglist argcount
name

STRING

widget-class

INTEGER

parent-widget

DWT:WIDGET

arglist

ArgList

argcount

INTEGER

Return Value

An object of type DWT:widget representing the new widget.

DWT.CREATE-WINDOW Intrinsic Function
Creates a window for a widget.
Format
DWT:CREATE-WINDOW widget window-class visual value-mask attributes
widget

DWT:WIDGET

window-class

INTEGER

visual

Visual

value-mask

XtValueMask

attributes

XSetWindowAttributes

Return Value

An object of type c l x : window representing the new window.

DWT:CSBYTECMP Compound String Function
Compares two compound strings to determine if they are identical.
Format
DWT:CSBYTECMP compound-stringi compound-string2
compound-string 1
compounds tring2

DWT—22

COMPOUND-STRING
COMPOUND-STRING

DWT:CSBYTECMP Compound String Function
Return Value

One of two integers representing the result of the comparison:
0

compound-stringi and compound-string2 are identical

compound-stringi and compound-string2 are not identical

DWT:CSEMPTY Compound String Function
Determines if the compound string contains any text segments.
Format
DWT:CSEMPTY compound-string
compound-string

compound- str in g

Return Value

A boolean value that is true if the compound string is empty.

DWT:CS-STRING Compound String Function
Creates a compound string.
Format
DWT:CS-STRING text charset language dir-r-to-i rend
text

STRING

charset
language
dir-r-to-i

integer

rend

DwtRendMask

integer

INTEGER

Return Value

An object of type compound- s t r in g representing the new compound string, or n il
if the input string is null.

DWT:CSTRCAT Compound String Function
Appends a copy of a compound string to the end of another compound string.
Format
DWT:CSTRCAT compound-stringi compound-string2
compound-string 1
compound-string2

COMPOUND-STRING
COMPOUND-STRING

DWT—23

DWT:CSTRCAT C om p o u n d String Function

Return Value

An object of type compound- s t r in g .

DWT:CSTRCPY Compound String Function
Copies a compound string.
Format
DWT:CSTRCPY compound-string
compound-string

compound-STRING

Return Value

An object o f type compound- s t r in g .

DWTi CSTRLEN Compound String Function
Returns tbe number of bytes in a compound string.
Format
DWT:CSTRLEN compound-string
compound-string

compound- st r in g

Return Value

An integer representing the number of bytes in the compound string, including
compound string terminators for headers and trailers. If the compound string has
an invalid structure, zero is returned.

DWT:CSTRNCAT Compound String Function
Appends a copy of a compound string to the end of another compound string.
Format
DWT:CSTRNCAT compound-stringi compound-string2 num-chars
compound-stringi
compound-string2

compound- st r in g

num-chars

INTEGER

COMPOUND-STRING

Return Value

An object o f type compound- s t r in g .

DWT-24

DWT:CSTRNCPY Compound String Function

DWT:CSTRNCPY Compound String Function
Copies a compound string.
Format
DWT:CSTRNCPY compound-string num-chars
compound-string

compound- str in g

num-chars

in teger

Return Value

An object o f type compound- s t r in g .

DWT:DATABASE Intrinsic Function
Returns the resource database for a display.
Format
DWT:DATABASE display
CLX:DISPLAY

display

Return Value

An integer representing the resource database.

DWT:DESTROY-APPLICATION-CONTEXT Intrinsic
Function
Destroys an application context and closes any displays within it.
Format
DWT:DESTROY-APPLIOATION-CONTEXT context
context

INTEGER

Return Value

Unspecified.

DWT-25

DWT:DESTROY-GC Intrinsic Function

DWT:DESTROY-GC Intrinsic Function
Deallocates a graphics context.
Format
DWT:DESTROY-GC widget gc
widget

DWT:WIDGET

CLX: GCONTEXT

Return Value

Unspecified.

DWT:DESTRO Y-WlDGET Intrinsic Function
Destroys an instance of a widget.
Format
DWT:DESTROY-WIDGET widget
widget

DWT:WIDGET

Return Value

Unspecified.

DWT:DIALOG-BOX High-Level Function
Creates a dialog box widget.
Format
DWT:DIALOG-BOX parent-widget name default-position x y title style
map-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

default-position
xy

INTEGER
INTEGER

title

COMPOUND-STRING

style

INTEGER

map-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

An object of type DWT: widget representing the new widget.

DWT—26

DWT.-DIALOG-BOX-CREATE Low-Level Function

DWT:DIALOG-BOX-CREATE Low-Level Function
Creates a dialog box widget.
Format
DWT:DIALOG-BOX-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type dwt: widget representing the new widget.

DWT:DIALOG-BOX-POPUP-CREATE Low-Level
Function
Creates a pop-up dialog box widget.
Format
DWT:DIALOG-BOX-POPUP-CREATE parent-widget name override-arglist
override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object o f type dwt:W!Dget rep resen tin g the n ew widget.

DWTiDIRECT-CONVERT Intrinsic Function
Invokes resource conversions.
Format
DWT:DIRECT-CONVERT converter arglist argcount src-value dst-value
converter

XtConverter

arglist

ArgList

argcount

INTEGER

DWT-27

DWT:DIRECT-CONVERT Intrinsic Function

src-value
dst-value

XrmValuePtr
XrmValuePtr

Return Value

Unspecified.

DWT:DISOWN-SELECTION Intrinsic Function
Informs the intrinsics global selection mechanism that a widget is no longer the
selection owner.
Format
DWTDISOWN-SELECTION widget selection time

widget
selection

in t e g e r

time

Time

DWT: WIDGET

Return Value

Unspecified.

DV\TT:DISPATCH-EVENT Intrinsic Function
Sends events to registered functions and widgets.
Format
DWT:DISPATCH-EVENT event

event

DWT:EVENT

Return Value

Unspecified.

DWTiDISPLAY Intrinsic Function
Returns the display pointer for the specified widget.
Format
DWT:DISPLAY widget

Widget

DWT: WIDGET

Return Value

An object of type CLX:d i s p l a y .

DWT—28

DWT:DISPLAY-CS-MESSAGE Convenience Function

DWT:DISPLAY-CS-MESSAGE Convenience Function
Displays a compound string message.
Format
DWT:DISPLAY-CS-MESSAGE parent-widget name pos x y style message-vector
widget convert-proc ok-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

pos
xy
style
message-vector

INTEGER
INTEGER
INTEGER
INTEGER

widget

DWT:WIDGET

convert-proc
ok-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

Unspecified.

DWTiDISPLAY-INITIALIZE Intrinsic Function
Initializes a display and adds it to an application context.
Format
DWT:DISPLAY-INITIALIZE context display-name application-name class-name
urlist urcount argcount argvalue
context

INTEGER

display-name
application-name
class-name

STRING
STRING
STRING

urlist

XrmOptionDescRec

urcount
argcount

INTEGER
INTEGER

argvalue

ArgList

Return Value

Unspecified.

DWT-29

DWT:DISPLAY-VMS-MESSAGE C on v en ien ce Function

DWT:DISPLAY-VMS-MESSAGE Convenience Function
Accepts and displays a VMS message.
Format
DWT:DISPLAY-VMS-MESSAGE parent-widget name pos x y style message-vector
widget convert-proc ok-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

pos
xy
style
message-vector

INTEGER
INTEGER
INTEGER
INTEGER

widget

DWT:WIDGET

convert-proc
ok-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROOTINE
CALL-BACK-ROUTINE

Return Value

An object of type dwt :w idget .

DWT:DRM-FREE-RESOURCE-CONTEXT DRM
Function
Frees a resource context.
Format
DWT:DRM-FREE-RESOURCE-CONTEXT context-id
context-id

DRMResourceContextPtr

Return Value

One of two possible constants whose integer values represent the DRM status:

DWT-30

DWT:DRM-SUCCESS

DWT:DRM-BAD-CONTEXT

DWT:DRM-GET-RESOURCE-CONTEXT DRM Function

DWT:DRM-GET-RESOURCE-CONTEXT DRM Function
Grets a resource context.
Format
DWT:DRM-GET-RESOURCE-CONTEXT alloc-func free-func size

alloc-func
free-func
size

c a ll- b a c k - r o u t in e or n u l l
c a ll- b a c k - r o u t in e or n u l l
DRMSize

Return Values

Two values:
• DRMResourceContextPtr, an integer representing the context-id-return.
• One of two possible constants whose integer values represent the DRM status:
DWT: DRM-FAILURE

DWT: DRM-SUCCESS

DWT:DRM-HGET-INDEXED-LITERAL DRM Function
Fetches indexed literals from a DRM hierarchy.
Format
DWT:DRM-HGET-INDEXED-LITERAL hierarchy-id index context-id

hierarchy-id
index

STRING

context-id

D R M R esou rceC on textP tr

in t e g e r

Return Value

One of three possible constants whose integer values represent the DRM status:
DWT:DRM-SUCCESS

DWT:DRM-FAILURE

DWT: DRM-NOT-FOUND

DWT—31

DWT:DRM-RC-BUFFER DRM Function

DWT:DRM-RC-BUFFER DRM Function
Returns a pointer to the resource context buffer.
Format
DWT:DRM-RC-BUFFER context-id
context-id

DRMResourceContextPtr

Return Value

An integer representing a pointer to the resource context buffer.

DWT:DRM-RC-SET-TYPE DRM Function
Modifies the type in the resource context.
Format
DWT:DRM-RC-SET-TYPE context-id type-value
context-id

DRMResourceContextPtr

type-value

DRMTVpe

Return Value

Unspecified.

DWT:DRM-RC-SIZE DRM Function
Returns the size of the value in the resource context buffer.
Format
DWT:DRM-RC-SIZE context-id
context-id

DRMResourceContextPtr

Return Value

An integer representing the buffer size.

DWT—32

DWT:DRM-RC-TYPE DRM Function

DWT:DRM-RC-TYPE DRM Function
Returns the type of the value in the resource context buffer.
Fprmat
DWT:DRM-RC-TYPE context-id
DRMResourceContextPtr

context-id

Return Value

An integer representing the type.

DWT:DWTHELP High-Level Function
Creates a help widget.
Format
DWT:DWTHELP parent-widget name default-position x y application-name library-type
library-spec first-topic overview-topic glossary-topic unmap-callback
parent-widget

DWT:WIDGET

name

COMPOUND-STRING

default-position
xy

INTEGER
INTEGER

application-name

COMPOUND-STRING

library-type

INTEGER

library-spec
first-topic
overview-topic
glossary-topic

COMPOUND-STRING
COMPOUND-STRING
COMPOUND-STRING

unmap-callback

CALL-BACK-ROUTINE

COMPOUND-STRING

Return Value

An object o f type dwt :w idget .

DWT:DWTWINDOW Intrinsic Function
Creates a window widget for simple applications to display in the main window
widget work area.
Format
DWT:DWTWINDOW parent-widget name x y width height callback
parent-widget

dwt :widget

DWT-33

DWTiDWTWINDOW Intrinsic Function

name

str in g

INTEGER
INTEGER

width
height

integer
call - back - routine

callback

Return Value
An object o f type dwt: widget rep resen tin g the window widget.

DWT:END-COPY-TO-CLIPBOARD Cut-and-Paste
Function
P laces data in the clipboard data structure.

Format
DWT:END-COPY-TO-CLIPBOARD display window item-id
display

clx : DI sp lay

window

CLX: window

item-id

INTEGER

Return Value
One o f tw o p ossib le con stan ts w h ose in teger values represen t the clipboard status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:ERROR-MSG Intrinsic Function
C alls the high-level error h an dler and p a sse s the inform ation specified.

Format
DWT:ERROR-MSG resource-name resource-type resource-class
default-string params num-params
resource-name
resource-type
resource-class
default-string
params

STRING
STRING
STRING
STRING
STRING

num-params

INTEGER

Return Value
U nspecified.

DWT—34

DWT.FETCH-INTERFACE-MODULE DRM Function

DWT:FETCH-INTERFACE-MODULE DRM Function
Fetches all the widgets defined in an interface module in the DRM hierarchy.
Format
DWT:FETCH-INTERFACE-MODULE hierarchy-id module-name parent
&OPTIONAL widget-return

hierarchy-id
module-name
parent
widget-return

INTEGER
STRING
DWT:WIDGET
DWT:WIDGET

Return Values

Two values:
• An object of type DWT: w id g e t representing widget-return.
• One of three possible constants whose integer values represent the DRM
status:
DWT:DRM-FAILURE

DWTiDRM-SUCCESS

DWT:DRM-NOT-FOUND

DWT:FETCH-SET-VALUES DRM Function
Fetches the values to be set from literals stored in UID files.
Format
DWT:FETCH-SET-VALUES hierarchy-id widget args num-args

hierarchy-id
widget
args

ArgList

num-args

INTEGER

INTEGER
DWT:WIDGET

Return Value

One of two possible constants whose integer values represent the DRM status:
DWT:DRM-SUCCESS

DWT:DRM-FAILURE

DWT-35

DWT:FETCH-WIDGET DRM Function

DWT:FETCH-WIDGET DRM Function
Fetches any indexed widget.
Format
DWT:FETCH-WIDGET hierarchy-id index parent
hierarchy-id

integer

index

strin g

parent

dwt: widget

Return Values

Two values:
• An object of type dwt : widget representing the widget.
• A string representing the widget class.

DWT:FETCH-WIDGET-OVERRIDE DRM Function
Fetches any indexed widget. Overrides dwt : fetch -widget arguments.
Format
DWT:FETCH-WIDGET-OVERRIDE hierarchy-id index parent override-name
override-args override-num-args
hierarchy-id

INTEGER

index

STRING

parent

DWT:WIDGET

override-name

STRING

override-args

ArgList

override-num-args

INTEGER

Return Values

Two values:
• An object of type dwt : widget representing the widget.
• A string representing the class.

DWT—36

DWT:FILE-SELECTION High-Level Function

DWT:FILE-SELECTION High-Level Function
Creates a file selection box widget.
Format
DWT:FILE-SELECTION parent-widget name x y title value dirmask visible-items-count
style default-position callback help-callback
parent-widget

DWT:WIDGET

name

STRING

INTEGER

title
value
dirmask

COMPOUND-STRING
COMPOUND-STRING
COMPOUND-STRING

visible-items-count
style
default-position

INTEGER
INTEGER
INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

An object o f type DWT:w idget representing the new widget.

DWT:FILE-SELECTION-CREATE Low-Level Function
Creates a file selection widget.
Format
DWT:FILE-SELECTION-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type DWT:w idget representing the new widget.

DWT—37

DWT:FILE-SELECTION-DO-SEARCH High-Level Function

DWT:FILE-SELECTION-DO-SEARCH High-Level
Function
Initiates a search with a directory mask option. Otherwise, the current directory
mask is used.
Format
DWT:FILE-SELECTION-DO-SEARCH widget dirmask
widget

DWT: WIDGET

dirmask

compound- st r in g

Return Value

Unspecified.

DWT:FREE intrinsic Function
Frees an allocated block of storage.
Format
DWHFREE address
INTEGER or any alien structure

address

Return Value

Unspecified.

DWT:GET-APPLICATION-RESOURCES Intrinsic
Function
Retrieves resources that are not specific to a widget but apply to the overall
application.
Format
DWT:GET-APPLICATION-RESOURCES widget base-addr resource-list arglist
resource-count argcount

DWT—38

widget

DWT:WIDGET

base-addr

INTEGER

resource-list

XtResourceList

arglist

ArgList

resource-count
argcount

INTEGER
INTEGER

DWT.'GET-APPLICATION-RESOURCES Intrinsic Function
Return Value

Unspecified.

DWTiGET-DISPLAY Convenience Function
See DWT:DISPLAY.

DWT:GET-ERROR-DATABASE Intrinsic Function
Obtains the error database.
Format
DWT:GET-ERROR-DATABASE

Return Value

An integer representing the address of the error database.

DWT:GET-ERROR-DATABASE-TEXT Intrinsic
Function
Obtains the error database text for an error or a warning.
Format
DWT:GET-ERROR-DATABASE-TEXT resource-name resource-type resource-class

default-string buffer size
resource-name
resource-type
resource-class
default-string
buffer
size

STRING
STRING
STRING
STRING
STRING
INTEGER

Return Value

Unspecified.

DWT-39

DWT:GET-GC Intrinsic Function

DWT:GET-GC Intrinsic Function
Returns a read-only, shareable graphics context.
Format
DWT:GET-GC widget value-mask values
Widget

DWT: WIDGET

value-mask

XtGCM ask

values

XtGCValues

Return Value

An object of type c l x : g c o n t e x t representing the graphics context.

DWT:GET-NEXT-SEGMENT Compound String
Function
Grets information about the next segment in the compound string.
Format
DWT:GET-NEXT-SEGMENT context

&OPTIONAL string-text charset dir-r-to-l language rend
context

DwtCom pStringContext

string-text

s t r in g

charset
dir-r-to-l
language
rend

in t e g e r

INTEGER
in t e g e r

INTEGER

Return Values

Six values:
• A string representing the string-text.
• An integer representing the charset.
• An integer representing the dir-r-to-l.
• An integer representing the language.
• An integer representing rend.
• One of three possible constants whose integer values represent the status as
follows:
DWT: FAIL

DWT—40

DWT:SUCCESS

DWT: END-CS

DWT:GET-RESOURCE-LIST Intrinsic Function

DWT:GET-RESOURCE-LIST Intrinsic Function
Obtains the resource list structure for a particular class of widget.
Format
DWT:GET-RESOURCE-LIST class resources-return num-resources-return

class
resources-return
num-resources-return

W idgetClass
XtResourceList

in t e g e r

Return Value

Unspecified.

DWT:GET-SCREEN Convenience Function
Returns the widget screen.
Format
DWTGET-SCREEN widget

widget

DWT: WIDGET

Return Value

An object of type c l x : screen representing the widget screen.

DWT:GET-SELECTION-TIMEOUT Intrinsic Function
Returns the current value of the intrinsics selection timeout interval.
Format
DWTrGET-SELECTION-TIMEOUT

Return Value

An integer representing the current value of the timeout interval in milliseconds.

DWT:GET-SELECTION-VALUE Intrinsic Function
Obtains the selection value in a single, logical unit.
Format
DWT:GET-SELECTION-VALUE widget selection target callback client-data time

DWT—41

DWT:GET-SELECTION-VALUE Intrinsic Function

widget

DWT:WIDGET

selection
target

INTEGER
INTEGER

callback

XtSelectionCallbackProc

client-data

INTEGER or alien structure

time

Time

Return Value
U nspecified.

DWT:GET-SELECTION-VALUE-INCR Intrinsic
Function
Obtains the selection data to the specified widget when using incremental data
transfers.
Format
DWT:GET-SELECTION-VALUE-INCR widget selection target callback
cancel client-data time
widget

DWT:WIDGET

selection
target

INTEGER
INTEGER

callback

XtSelectionlncrCallbackProc

cancel

XtCancelConvertSelectionProc

client-data

INTEGER or alien structure

time

Time

Return Value
U nspecified.

DWT:GET-SELECTION-VALUES Intrinsic Function
Obtains the selection value in a single, logical unit.
Format
DWT:GET-SELECTION-VALUES widget selection targets count callback
client-datas time
widget

DWT—42

dwt : widget

selection

INTEGER

targets

Alien structure

count

INTEGER

DWT:GET-SELECTION-VALUES Intrinsic Function

callback

XtSelectionCallbackProc

client-datas

INTEGER or alien structure

time

Time

Return Value

Unspecified.

DWT:GET-SELECTION-VALUES-INCR Intrinsic
Function
Obtains the selection data to the specified widget when using incremental data
transfers.
Format
DWT:GET-SELECTION-VALUES-INCR widget selection targets count callback
cancel client-datas time
widget

DWT:WIDGET

selection

INTEGER

targets

Alien structure

count

INTEGER

callback

XtSelectionlncrCallbackProc

cancel

XtCancelConvertSelectionProc

client-datas

INTEGER or alien structure

time

Time

Return Value
U nspecified.

DWT.GET-SUBRESOURCES Intrinsic Function
Retrieves resources for nonwidget subparts.
Format
DWT:GET-SUBRESOURCES widget base-addr resource-name resource-class resource-list
resource-count arglist argcount
widget

DWT:WIDGET

base-addr

INTEGER

resource-name
resource-class

STRING
STRING

resource-list

XtResourceList

resource-count

INTEGER

DWT—43

DWT:GET-SUBRESOURCES Intrinsic Function

arglist

ArgList

argcount

INTEGER

Return Value

Unspecified.

DWT:GET-SUBVALUES Intrinsic Function
Retrieves the value of nonwidget resource data associated with a widget instance.
Format
DWT:GET-SUBVALUES base-addr resource-list resource-count arglist argcount

base-addr
resource-list
resource-count

XtResourceList

arglist

ArgList

argcount

INTEGER

INTEGER
INTEGER

Return Value

Unspecified.

DWT:GET-VALUES Intrinsic Function
Retrieves the current value of resource data associated with a widget instance.
Format
DWT:GET-VALUES widget arglist argcount

widget
arglist

DWT: WIDGET

argcount

in t e g e r

ArgList

Return Value

The argument list that was passed to the function.

DWT:HAS-CALLBACKS Intrinsic Function
Determines the status of a callback list.
Format
DWT:HAS-CALLBACKS widget callback-name

DWT—44

DWT:HAS-CALLBACKS Intrinsic Function
widget
callback-name

DWT:WIDGET
INTEGER

Return Value

One of the following constants whose integer values represent the status:
DWT: XTCALLBACKNOL1ST

DWT:XTCALLBACKHASNONE

DWT: XTCALLBACKHAS SOME

DWT:HELP High-Level Function
See dwt :Dwthelp high-level function.

DWT:HELP-CREATE Low-Level Function
Creates a help widget.
Format

DWT:HELP-CREATE parent-widget name override-arglist override-argcount
parent-widget
name
override-arglist
override-argcount

DWT:WIDGET
STRING
ArgList
INTEGER

Return Value

An object of type dwt : widget representing the new widget.

DWT:INIT-GET-SEGMENT Compound String Function
Initializes the context needed by dwt : get -next - segment.
Format

DWT:INIT-GET-SEGMENT context compound-string
context
compound-string

DwtCompStringContext
compound- str in g

Return Values

Two values:
• A compound string representing the context.

DWT-45

DWT:INIT-GET-SEGMENT Compound String Function
• One of three possible constants whose integer values represent the status:
DWT: FAIL

DWT:SUCCESS

DWT:END-CS

DWT:INITIALIZE Intrinsic Function
Initializes the DECwindows Toolkit.
Format
DWT:INITIALIZE name class-name urlist num-urlist argcount argvalue
STRING

name
class-name

strin g

urlist

XrmOptionDescRec

num-urlist
argcount

INTEGER
INTEGER

argvalue

ArgList

Return Value

An object o f type DWT:widget rep resen tin g the new widget.

DWT:INITIALIZE-DRM DRM Function
Prepares an application to use DRM facilities.
Format
DWT:INITIALIZE-DRM

Return Value

Unspecified.

DWT:INQUIRE-NEXT-PASTE-COUNT Cut-and-Paste
Function
Opens all the UID files in the DRM hierarchy.
Format
DWT:INQUIRE-NEXT-PASTE-GOUNT display window

DWT—46

display

CLX: DI SPLAY

window

CLX: WINDOW

DWT:INQUIRE-NEXT-PASTE-COUNT Cut-and-Paste Function
Return Values

Two values:
• An integer representing the count.
• An integer representing max-format-name-length.

DWT:INQUIRE-NEXT-PASTE-FORMAT Cut-and-Paste
Function
Returns a specified format name for the next-paste item in the clipboard.
Format
DWT:INQUIRE-NEXT-PASTE-FORMAT display window number
format-name-buf buffer-len
display

CLX:DISPLAY

window

CLX:WINDOW

number

INTEGER

format-name-buf

STRING

buffer-len

INTEGER

Return Values

Three values:
• A string representing the format-name-buf.
• An integer representing the copied-length.
• One of three possible constants whose integer values represent the clipboard
status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-TRUNCATE

DWT:CLIPBOARD-LOCKED

DWT:INQUIRE-NEXT-PASTE-LENGTH Cut-and-Paste
Function
Returns the length of the data stored under a specified format name for the
next-paste item in the clipboard.
Format
DWT:INQUIRE-NEXT-PASTE-LENGTH display window format-name
display

CLX: DISP LAY

DWT—47

DWT:INQUIRE-NEXT-PASTE-LENGTH Cut-and-Paste Function

window

CLX: WINDOW

format-name

str in g

Return Values

Two values:
• An integer representing the length.
• One of two possible constants whose integer values represent the clipboard
status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:INSTALL-ACCELERATORS Intrinsic Function
Installs accelerators from a widget on another widget.
Format
DWT:INSTALL-ACCELERATORS dst-widget src-widget
dst-widget
src-widget

dwt:widget

DWT:widget

Return Value

Unspecified.

DWT:INSTALL-ALL-ACCELERATORS Intrinsic
Function
Installs all accelerators from a widget and all its descendants onto one
destination.
Format
DWT:INSTALL-ALL-ACCELERATORS dst-widget src-widget
dst-widget
src-widget

Return Value

Unspecified.

DWT—48

dwt : widget
dwt : widget

DWT:IS-COMPOSITE Intrinsic Function

DWT:IS-COMPOSITE Intrinsic Function
Determines if a widget is a subclass of Composite.
Format
DWT:IS-COMPOSITE widget
widget

DWT: WIDGET

Return Value

A boolean value that is true if the widget is a subclass of Composite.

DWT:IS-MANAGED Intrinsic Function
Determines the managed state of a given child widget.
Format
DWT:IS-MANAGED widget

widget

DWT: WIDGET

Return Value

A boolean value that is true if the widget is managed.

DWT.IS-REALIZED Intrinsic Function
Determines if the widget is realized.
Format
DWT:IS-REALIZED widget

Widget

DWT:WIDGET

Return Value

A boolean value that is true if the widget is realized.

DWT:IS-SENSITIVE Intrinsic Function
Determines the current sensitivity state of a widget.
Format
DWT:IS-SENSITIVE widget

Widget

DWT:WIDGET

DWT—49

DWTilS-SENSITIVE Intrinsic Function
Return Value

True or false to indicate whether user input events are being dispatched.

DWT:IS-SUBCLASS Intrinsic Function
Determines the subclass that the specified widget belongs to.
Format
DWT:IS-SUBCLASS widget widget-class
Widget

DWT: WIDGET

widget-class

INTEGER

Return Value

A boolean value that is true if the widget is a subclass of widget-class.

DWT:LABEL High-Level Function
Creates a label widget for the application to display identification information on
the screen.
Format
DWT:LABEL parent-widget name x y label help-callback
parent-widget

DWT:WIDGET

name

STRING

INTEGER

label

COMPOUND-STRING

help-callback

CALL-BACK-ROUTINE

Return Value

An object of type dwt: w idget representing the new widget.

DWT:LABEL-CREATE Low-Level Function
Creates a label widget for the application to display identification information on
the screen.
Format
DWT:LABEL-CREATE parent-widget name override-arglist override-argcount

DWT—50

parent-widget

dwt : widget

name

str in g

DWT:LABEL-CREATE Low-Level Function

override-arglist

ArgList

override-argcount

integer

Return Value

An object of type dwt : widget representing the new widget.

DWT:LABEL-GADGET-CREATE Gadget Function
Creates a label gadget.
Format
DWT:LABEL-GADGET-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type dwt :w idget representing the newly created widget.

DWT:LATIN1-STRING Compound String Function
Creates a compound string for the LATIN1 character set.
Format
DWTiATINI -STRING text-string
text-string

str in g

Return Value

An object of type compound- st r in g representing the resulting compound string.

DWT:LIST-BOX High-Level Function
Creates a list box widget for the application to display large numbers of item
choices or entries in a list format.
Format
DWT:LIST-BOX parent-widget name x y items item-count visible-items-count callback
help-callback resize horiz
parent-widget

dwt : WIDGET

name

STRING

DWT—51

DWT:LIST-BOX High-Level Function

INTEGER

items

COMPOUND-STRING

item-count
visible-items-count

INTEGER
INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

resize
horiz

INTEGER
INTEGER

Return Value

An object of type dwt:w idget representing the new widget.

DWT:LIST-BOX-ADD-ITEM High-Level Function
Adds an item to the list within a list box widget.
Format
DWT:LIST-BOX-ADD-ITEM widget item pos
widget

DWT-.WIDGET

item

COMPOUND-STRING

pos

INTEGER

Return Value

Unspecified.

DWT:LIST-BOX-CREATE Low-Level Function
Creates a list box widget.
Format
DWT:LIST-BOX-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

A rgList

override-argcount

INTEGER

Return Value

An object of type dwt : widget representing the new widget.

DWT—52

DWT:LIST-BOX-DELETE-ITEM High-Level Function

DWT:LIST-BOX-DELETE-ITEM High-Level Function
Deletes an item from the list within a list box widget.
Format
DWT:LIST-BOX-DELETE-ITEM widget item
widget

DWT: widget

item

COMPOUND-STRING

Return Value

Unspecified.

DWT:LIST-BOX-DELETE-POS High-Level Function
Deletes an item identified by its position from the list within a list box widget.
Format
DWT:LIST-BOX-DELETE-POS widget position
widget

DWT: widget

position

INTEGER

Return Value

Unspecified.

DWT:LIST-BOX-DESELECT-ALL-ITEMS High-Level
Function
Deselects all of the previously selected items in a list box.
Format
DWT1IST-BOX-DESELECT-ALL-ITEMS widget
widget

dwt: widget

Return Value

Unspecified.

DWT—53

DWT:UST-BOX-DESELECT-ITEM High-Level Function

DWT:LIST-BOX-DESELECT-ITEM High-Level Function
Deselects a previously selected item in a list box.
Format
DWT:LIST-BOX-DESELECT-ITEM widget item
Widget

DWT: WIDGET

item

COMPOUND-STRING

Return Value

Unspecified.

DWT:LIST-BOX-DESELECT-POS High-Level Function
Deselects an item identified by its position in a list box.
Format
DWT1IST-BOX-DESELECT-POS widget position
widget

DWT: WIDGET

position

INTEGER

Return Value

Unspecified.

DWT:LIST-BOX-ITEM-EXISTS High-Level Function
Verifies the existence of a particular item in a list box.
Format
DWT:LIST-BOX-ITEM-EXISTS widget item
widget

DWT: WIDGET

item

COMPOUND-STRING

Return Value

A boolean value that is true if the list box item exists.

DWT—54

DWT:LIST-BOX-SELECT-ITEM High-Level Function

DWT:LIST-BOX-SELECT-ITEM High-Level Function
Selects an item in the list box.
Format
DWT1IST-BOX-SELECT-ITEM widget item notify
widget

DWT:WIDGET

item

COMPOUND-STRING

notify

INTEGER

Return Value

Unspecified.

DWT:LIST-BOX-SELECT-POS High-Level Function
Selects an item identified by its position in the list box.
Format
DWT1IST-BOX-SELECT-POS widget position notify
widget

DWT:WIDGET

position
notify

INTEGER
INTEGER

Return Value

Unspecified.

DWT:LIST-BOX-SET-HORIZ-POS High-Level Function
Sets the horizontal position to a specified position.
Format
DWT:LIST-BOX-SET-HORIZ-POS widget position
widget

DWT:WIDGET

position

INTEGER

Return Value

Unspecified.

DWT—55

DWT:LIST-BOX-SET-ITEM High-Level Function

DWT:LIST-BOX-SET-ITEM High-Level Function
Makes a specified item (if it exists) the first visible item in a list box, or as close
to the top as possible. The item always becomes visible.
Format
DWT:LIST-BOX-SET-ITEM widget item
widget

DWT: widget

item

COMPOUND-STRING

Return Value

Unspecified.

DWT:LIST-BOX-SET-POS High-Level Function
Makes a specified position (item number in bst) the top visible position in a Hst
box, or as close to the top as possible.
Format
DWT:LIST-BOX-SET-POS widget position
widget

DWT: WIDGET

position

INTEGER

Return Value

Unspecified.

DWT:LIST-PENDING-ITEMS Cut-and-Paste Function
Returns a bst of data id/private id pairs for a specified format name.
Format
DWT:LIST-PENDING-ITEMS display window format-name item-list count
display

DWT—56

CLX: DISPLAY

window

CLX: WINDOW

format-name

str in g

item-list

DwtClipboardPendingList

count

INTEGER

DWT:LIST-PENDING-ITEMS Cut-and-Paste Function
Return Values

Three values:
• An alien structure representing the item-list.
• An integer representing the count.
• One of two possible constants whose integer values represent the clipboard
status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:MAIN-LOOP Intrinsic Function
Processes input data.
Format
DWT:MAIN-LOOP

Return Value

Unspecified.

DWT:MAIN-WINDOW High-Level Function
Creates the main window widget.
Format
DWT:MAIN-WINDOW parent-widget name x y width height
parent-widget

DWT:WIDGET

nam e

STRING

INTEGER
INTEGER
INTEGER

width
height

Return Value

An object o f type DWT:w idget representing the new widget.

DWT:MAIN-WINDOW-CREATE Low-Level Function
Creates a main window widget that is the parent of all widgets in an application
that conforms to the DECwindows style.
Format
DWT:MAIN-WINDOW-CREATE parent-widget name override-argiist override-argcount

DWT—57

DWT:MAIN-WINDOW-CREATE Low-Level Function

parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type DWT:w idget representing the new widget.

DWT:MAIN-WlNDOW-SET-AREAS High-Level
Function
Sets up or adds the menu bar, work window, command window, and scroll bar
widgets to the main window widget of the application.
Format
DWT:MAIN-WINDOW-SET-AREAS widget menu-bar work-window command-window
h-scroll v-scroll
widget
menu-bar
work-window
command-window
h-scroll
v-scroll

DWT:WIDGET
DWT:WIDGET
DWT:WIDGET
DWT:WIDGET
DWT:WIDGET
DWT.-WIDGET

Return Value

Unspecified.

DWT:MAKE-GEOMETRY-REQUEST Intrinsic Function
Makes a geometry manager request from a widget.
Format
DWTrMAKE-GEOMETRY-REQUEST widget requested-size approved-size
widget
requested-size
approved-size

dwt : widget

XtWidgetGeometry
XtWidgetGeometry

Return Value

An XtGeometryResult alien structure representing the return code from the
Geometry Manager.

DWT—58

DWT:MAKE-RESIZE-REQUEST Intrinsic Function

DWT:MAKE-RESIZE-REQUEST Intrinsic Function
Makes a resize request from a widget.
Format
DWT:MAKE-RESIZE-REQUEST widget requested-width requested-height

widget
requested-width
requested-height

DWT: w id ge t
in t e g e r
INTEGER

Return Values

Three values:
• An integer representing the approved-width.
• An integer representing the approved-height.
• One of the following constants representing the status:
DWT:FAIL

DWT:SUCCESS

DWT: GEOMETRY-ALMOST

DWT:MALLOC Intrinsic Function
Allocates storage.
Format
DWT:MALLOC size
s iz e

INTEGER

Return Value

An integer representing a pointer to a block of storage.

DWT:MANAGE-CHILD Intrinsic Function
Adds a single child to the managed children of the parent widget.
Format
DWT:MANAGE-CHILD widget

widget

DWT:WIDGET

Return Value

Unspecified.

DWT—59

DWT:MANAGE-CHILDREN Intrinsic Function

DWT:MANAGE-CHILDREN Intrinsic Function
Performs the basic functions of managing children.
Format
DWT:MANAGE-CHILDREN widget-list num-children

widget-list
num-children

WidgetList
INTEGER

Return Value

Unspecified.

DWT:MAP-WIDGET Intrinsic Function
Maps a widget explicitly.
Format
DWT:MAP-Wl DG ET widget

widget

D W T :WIDGET

Return Value

Unspecified.

DWT:MENU High-Level Function
Creates a menu widget to contain other menu items (subwidgets) for the display
of application menus.
Format
DWT:MENU parent-widget name x y format orientation callback map-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

xy
format
orientation

INTEGER
INTEGER
INTEGER

callback
map-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUT INE
CALL-BACK-ROUT INE

Return Value

An object of type DWT:w i d g e t representing the new widget.

DWT-60

DWT:MENU-BAR High-Level Function

DWT:MENU-BAR High-Level Function
Creates a menu bar widget to contain other menu items (subwidgets) for the
application in menu bar displays.
Format
DWT:MENU-BAR parent-widget name callback help-callback
parent-widget

dwt: widget

name

st r in g

callback
help-callback

call - back - routine
call - back - routine

Return Value

An object of type dwt : w idget representing the new widget.

DWT:MENU-BAR-CREATE Low-Level Function
Creates a menu bar widget.
Format
DWT:MENU-BAR-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type dwt :w idget representing the new widget.

DWT:MENU-CREATE Low-Level Function
Creates a menu widget to contain other menu items (subwidgets) for the display
of application menus.
Format
DWT:MEN!U-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-a rglist

ArgList

override-a rgcount

INTEGER

DWT—61

DWT:MENU-CREATE Low-Level Function
Return Value

An object of type d w t :w i d g e t representing the new widget.

DWT:MENU-POPUP-CREATE Low-Level Function
Creates a pop-up menu (MB2 only).
Format
DWT:MENU-POPUP-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type d w t :WIDGET representing the new widget.

DWT:MENU-POSITION High-Level Function
Positions the pop-up menu when user presses MB2.
Format
DWT:MENU-POSITION widget event
widget

DWT: WIDGET

event

DWT:EVENT

Return Value

Unspecified.

DWT:MENU-PULLDOWN-CREATE Low-Level
Function
Creates a pull-down menu.
Format
DWT:MENU-PULLDOWN-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT—62

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

DWT:MENU-PULLDOWN-CREATE Low-Level Function
Return Value

An object of type dwt :widget representing the new widget.

DWT:MERGE-ARG-LISTS Intrinsic Function
Merges two argument lists.
Format
DWT:MERGE-ARG-LISTS arglistl argcountl arglist2 argcount2
arglistl

ArgList

argcountl

INTEGER

arglist2

ArgList

argcount2

INTEGER

Return Value

An object of type ArgList representing the combined argument list.

DWT:MESSAGE-BOX High-Level Function
Creates a message box widget for the application to display text to the user.
Format
DWT:MESSAGE-BOX parent-widget name default-position x y style label ok-label
callback help-callback
parent-widget

DWT:WIDGET

name

STRING

default-position
xy
style

INTEGER
INTEGER
INTEGER

label
ok-label

COMPOUND-STRING
COMPOUND-STRING

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

An object of type dwt :widget representing the new widget.

DWT-63

DWT:MESSAGE-BOX-CREATE Low-Level Function

DWT:MESSAGE-BOX-CREATE Low-Level Function
Creates a message box widget for the application to display text to the user.
Format
DWT:MESSAGE-BOX-CREATE paren t-w idget n a m e override-arglist override-argcou n t
paren t-w id get

DWT:WIDGET

nam e

STRING

override-arglist

ArgList

ov erride-argcou n t

INTEGER

Return Value

An object of type DWT:w i d g e t representing the new widget.

DWT:MOVE-WIDGET Intrinsic Function
Moves widget children around.
Format
DWT:MOV E-Wl DG ET w id ge t x y
w id g e t

DWT:wiDGET

INTEGER

Return Value

Unspecified.

DWT:NAME-TO-WIDGET Intrinsic Function
Translates a widget name to a widget instance.
Format
DWT:NAM E-TO-Wl DG ET ro o t n a m e
root

DWT:WIDGET

nam e

string

Return Value

An object of type DWT:w i d g e t representing the new widget.

DWT—64

DWT:NEXT-EVENT Intrinsic Function

DWT:NEXT-EVENT Intrinsic Function
Reads the next input available, or waits for the next event if none is queued.
Format
DWT:NEXT-EVENT &OPTIONAL event
event

d w t :e v e n t

Return Value
A n object of type d w t :e v e n t representing the next event in the queue.

DWT:NUMBER-CHILDREN Convenience Function
Determines how many widgets are children of a given widget.
Format
DWT:NUMBER-CHILDREN widget
widget

DWT: WIDGET

Return Value

A positive integer representing the number of children.

DWT:OPEN-DISPLAY Intrinsic Function
Opens a display, initializes it, and adds it to an application context.
Format
DWT:OPEN-DISPLAY context display-name application-name class-name
urlist urcount argcount argvalue
context

INTEGER

display-name
application-name
class-name

STRING
STRING
STRING

urlist

XrmOptionDescRec

urcount
argcount

INTEGER
INTEGER

argvalue

ArgList

Return Value

An object of type c l x :d i s p l a y representing the CLX display.

DWT-65

DWT:OPEN-HIERARCHY DRM Function

DWT:OPEN-HIERARCHY DRM Function
Opens all the UID files in the DRM hierarchy.
Format
DWT:OPEN-HIERARCHY num-files file-names-list ancillary-structures-list
&OPTIONAL hierarchy-id-return
num-files

INTEGER

file-names-list

STRING

ancillary-structures-list

IDBOSOpenParam Ptr

hierarchy-id-re turn

DRMHierarchy

Return Value

An alien structure representing the hierarchy-id-return.

DWT:OPTION-MENU High-Level Function
Creates an option menu widget to display and handle an application option list of
attributes or modes of the menu topic. It allows just one option selected from the
list in the menu.
Format
DWT:OPTION-MENU parent-widget name x y label submenu callback help-callback
parent-widget

D W T :WIDGET

name

STRING

INTEGER

label

COMPOUND-STRING

submenu

DWT:WIDGET

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

An object of type DWT:w i d g e t representing the new widget.

DWT:OPTION-MENU-CREATE Low-Level Function
Creates an option menu widget.
Format
DWT:OPTION-MENU-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT-66

DWT: w i d g e t

DWT:OPTION-MENU-CREATE Low-Level Function
name

s tr in g

override-arglist
override-argcount

ArgList

INTEGER

Return Value

An object of type dwt i WIDGET representing the new widget.

DWT:OVERRIDE-TRANSLATIONS Intrinsic Function
Overwrites existing translations with new translations.
Format
DWT:OVERRIDE-TRANSLATIONS widget translation-table

widget
translation-table

DWT: WIDGET
XtTranslations

Return Value

Unspecified.

DWT:OWN-SELECTION Intrinsic Function
Sets the selection owner when using atomic data transfers.
Format
DWT:OWN-SELECTION widget selection time convert-proc loss-proc notify-proc

widget

DWT:WIDGET

selection
time
convert-proc

INTEGER

loss-proc
notify-proc

Time
XtConvertSelectionProc
XtLoseSelectionProc
XtSelectionDoneProc

Return Value

Unspecified.

DWT-67

DWT:OWN-SELECTION-INCREMENTAL Intrinsic Function

DWT:OWN-SELECTION-INCREMENTAL Intrinsic
Function
Sets the selection owner when using incremental transfers.
Format
DWT:OWN-SELECTION-INCREMENTAL widget selection time convert-proc loss-proc

notify-proc cancel-proc ciient-datas

widget

DWT:WIDGET

selection

INTEGER

time
convert-proc
loss-proc
notify-proc
cancel-proc
ciient-datas

Time
XtConvertSelectionlncrProc
XtLoseSelectionlncrProc
XtSelectionDonelncrProc
XtCancelSelectionCallbackProc

INTEGER or alien structure

Return Value

A boolean value that is true if the widget is successful in becoming the owner.

DWT:PARENT Intrinsic Function
Returns the parent widget for a specified widget.
Format
DWT:PARENT widget

widget

DWT: WIDGET

Return Value

An object of type dwt :widget that is the parent widget.

DWT:PARSE-ACCELERATOR-TABLE Intrinsic
Function
Parses an accelerator table.
Format
DWT:PARSE-ACCELERATOR-TABLE source

source

DWT—68

STRING

DWT:PARSE-ACCELERATOR-TABLE Intrinsic Function
Return Value
An X tA ccelerators alien structure pointer re p resen tin g the p arsed tran slation
table.

DWT:PARSE-TRANSLATION-TABLE Intrinsic
Function
P a rses a translation table.

Format
DWT:PARSE-TRANSLATION-TABLE source
source

str in g

Return Value
X tTranslations, a pointer to the p arsed tran slation table.

DWT:PEEK-EVENT Intrinsic Function
R etu rn s the value from the h ead o f the in pu t q u eu e w ith out rem ov in g in put from
th e queue.

Format
DWT:PEEK-EVENT &OPTIONAL event
event

dwt: event

Return Value
An object o f type dwt : e v e n t .

DWTi PENDING Intrinsic Function
D eterm in es if any events are p en din g on the in p u t queue.

Format
DWTiPENDING

Return Value
A boolean value that is tru e if events are p en d in g on the in p u t queue.

DWT-69

DWT:POPDOWN Intrinsic Function

DWT:POPDOWN Intrinsic Function
U nm aps a pop-up from w ithin an application.

Format
D W T : P O P D O W N w id get
W idget

DWT: WIDGET

Return Value
Unspecified.

DWT:POPUP Intrinsic Function
M aps (pops up) a pop-up from w ithin an application.

Format
DWT:POPUP w id get pgrab-kind
W idget

DWT: WIDGET

pgrab-kin d

XtGrabKind

Return Value
U nspecified.

DWT:PROCESS-EVENT Intrinsic Function
P rocesses one in pu t event, timeout, or altern ate in p u t source.

Format
DWT:PROCESS-EVENT input-m ask
input-m ask

Return Value
U nspecified.

DWT-70

XtlnputM ask

DWT:PULL-DOWN-MENU-ENTRY High-Level Function

DWT:PULL-DOWN-MENU-ENTRY High-Level Function
C rea tes an in stance o f the pull-down m en u entry widget.

Format
DWT:PULL-DOWN-MENU-ENTRY parent-widget name x y label menu-id
callback help-callback
parent-widget

DWT:WIDGET

name

STRING

INTEGER

label

COMPOUND-STRING

menu-id

DWT:WIDGET

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type DWT:widget rep resen tin g the new widget.

DWT:PULL-DOWN-MENU-ENTRY-CREATE Low-Level
Function
C rea tes a pull-down m en u entry widget.

Format
DWT:PULL-DOWN-MENU-ENTRY-CREATE parent-widget name
override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
A n object o f type dwt: widget represen tin g the new widget.

DWT:PULL-DOWN-MENU-ENTRY-HILITE High-Level
Function
H igh ligh ts a m en u entry.

Format
DWT:PULL-DOWN-MENU-ENTRY-HILITE menu hilite

DWT—71

DWT:PULL-DOWN-MENU-ENTRY-HILITE High-Level Function

DWT:WIDGET

hilite

INTEGER

Return Value
U nspecified.

DWT:PUSH-BUTTON High-Level Function
Creates a push b u tto n w id g e t fo r the applicatio n.

Format
DWT:PUSH-BUTTON parent-widget name x y label callback help-callback
parent-widget

DWT:WIDGET

name

STRING

INTEGER

label

COMPOUND-STRING

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
A n object o f type DWT: w idget representin g th e new w idget.

DWT:PUSH-BUTTON-CREATE Low-Level Function
Creates a push b u tto n w idget.

Format
DWT:PUSH-BUTTON-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
A n object o f type DWT:w idget representin g th e new w idget.

DWT—72

DWT:PUSH-BUTTON-GADGET-CREATE G adget Function

DWT:PUSH-BUTTON-GADGET-CREATE Gadget
Function
C reates a pu sh button gadget.

Format
DWT:PUSH-BUTTON-GADGET-CREATE parent-widget name

override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist
override-argcount

ArgList

INTEGER

Return Value
An object o f type DWT:widget re p resen tin g the new widget.

DWT:QUERY-GEOMETRY Intrinsic Function
O btains a w id get’
s preferred geometry.

Format
DWT:QUERY-GEOMETRY widget requested approved

widget
requested
approved

DWT: WIDGET
XtW idgetGeometry
XtW idgetGeometry

Return Value
An X tG eom etry alien structure poin ter rep resen tin g the w id get’
s preferred
geometry.

DWT:RADIO-BOX High-Level Function
C reates a radio box w id get for the application to disp lay m u ltiple to gg le buttons.

Format
DWT:RADIO-BOX parent-widget name x y callback help-callback

parent-widget

dwt: w id g e t

name

STRING

INTEGER

DWT—73

DWT:RADIO-BOX High-Level Function

callback
help-callback

CALL-BACK- ROOTINE
call - back - routine

Return Value
An object o f type dwt: widget represen tin g the new widget.

DWT:RADIO-BOX-CREATE Low-Level Function
C reates a radio box widget.

Format
DWT:RADIO-BOX-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type dwt :w idget represen tin g th e new widget.

DWT:REALIZE-WIDGET Intrinsic Function
P erform s w id get realization.

Format
DWT:REALIZE-WIDGET widget
widget

dwt : widget

Return Value
Unspecified.

DWT:REALLOC Intrinsic Function
C h a n ges the size o f an allocated block o f storage.

Format
DWT:REALLOC addr size
addr
size

INTEGER
INTEGER

Return Value
An in teger rep resen tin g the new storage address.

DWT—74

DWT:RECOPY-TO-CLIPBOARD Cut-and-Paste Function

DWT:RECOPY-TO-CLIPBO ARD Cut-and-Paste
Function
C op ies a data item th at h ad been p a ssed by nam e to the clipboard.

Format
DWT:RECOPY-TO-CLIPBOARD display window data buffer private-id
display

CLX:DISPLAY

window

CLX:WINDOW

data

INTEGER

buffer

STRING

private-id

INTEGER

Return Value
O ne o f tw o p ossib le con stan ts w h ose in teger values rep resen t the clipboard status:
DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT: REGISTER-CASE-CONVERTER Intrinsic
Function
R egisters a case converter.

Format
DWT:REGISTER-CASE-CONVERTER display converter start stop
display

CLX:DISPLAY

converter

XtCaseProc

start
stop

KeySym
KeySym

Return Value
Unspecified.

DWT—75

DWT:REGISTER-CLASS DRM Function

DWT:REGISTER-CLASS DRM Function
P rovides DRM w ith inform ation abou t a user-defined w idget class, such as the
cla ss record and cla ss name, th at is n ecessa ry to create w id gets o f th is class.

Format
DWT:REGISTER-CLASS class-code class-name create-name creator-proc class-record
class-code

DRMType

class-name
create-name

STRING
STRING

creator-proc

DWT:WIDGET

class-record

WidgetClass

Return Value
O ne o f tw o p ossible constants w h ose in te ge r valu es rep resen t the DRM status:
DWT:DRM—SUCCESS

DWT:DRM-FAILURE

DWT:REGISTER-DRM-NAMES DRM Function
R eg isters a vector o f n am es o f iden tifiers o r callback routines for a ccess in DRM.

Format
DWT:REGISTER-DRM-NAMES register-list register-count
register-list

DRMRegisterArgList

DRMCount

Return Value
O ne o f tw o p ossible constants w h ose in te ge rs represen t the statu s as follows:
DWT:DRM-SUCCESS

DWT:DRM-FAILURE

DWT:REMOVE-ALL-CALLBACKS Intrinsic Function
R em oves all callback procedu res from a callback list.

Format
DWT:REMOVE-ALL-CALLBACKS widget callback-name
widget

DWT—76

DWT; WIDGET

DWT:REMOVE-ALL-CALLBACKS Intrinsic Function
callback-name

STRING

Return Value
U nspecified.

DWT:REMOVE-CALLBACK Intrinsic Function
R em oves a callback p rocedu re from a callback list.

Format
DWT:REMOVE-CALLBACK widget callback-name callback client-data

widget

DWT:WIDGET

callback-name
callback
client-data

STRING
XtCallbackProc
INTEGER or alien structure

Return Value
U nspecified.

DWT:REMOVE-CALLBACKS Intrinsic Function
R em oves a list o f callback procedu res from a callback list.

Format
DWT:REMOVE-CALLBACKS widget callback-name callbacks

widget
callback-name
callbacks

dwt : w id ge t
s t r in g
XtCallbackList

Return Value
U nspecified.

DWT:REMOVE-EVENT-HANDLER Intrinsic
Function
R em oves a p rev iou sly re gistere d event handler.

Format
DWT:REMOVE-EVENT-HANDLER widget event-mask other client-proc client-data

widget

dwt : w id g e t

DWT—77

DWT:REMOVE-EVENT-HANDLER Intrinsic Function

event-mask

XtEventMask

other

INTEGER

client-proc

XtEventHandler

client-data

INTEGER or alien structure

Return Value
U nspecified.

DWT:REMOVE-GRAB Intrinsic Function
R em oves the redirection of u ser in pu t to a m odal widget.

Format
DWT:REMOVE-GRAB widget
widget

DWT:WIDGET

Return Value
U nspecified.

DWT:REMOVE-INPUT Intrinsic Function
D iscon tin u es a sou rce o f input.

Format
DWT:REMOVE-INPUT input-id
input-id

Xtlnputld

Return Value
U nspecified.

DWT:REMOVE-RAW-EVENT-HANDLER Intrinsic
Function
R em oves a previou sly registered raw event handler.

Format
DWT:REMOVE-RAW-EVENT-HANDLER widget event-mask other client-proc client-data

DWT—78

widget

DWT:WIDGET

event-mask

XtEventMask

other

INTEGER

DWT:REMOVE-RAW-EVENT-HANDLER Intrinsic Function

client-proc

XtEventHandler

client-data

INTEGER or alien structure

Return Value
U n sp ecified .

DWT:REMOVE-TIME-OUT Intrinsic Function
C lea rs a tim eou t value.

Format
DWT:REMOVE-TIME-OUT interval-id
interval-id

Xtlntervalld

Return Value
U nspecified.

DWT:REMOVE-WORK-PROC Intrinsic Function
R em oves a w ork procedure.

Format
DWT:REMOVE-WORK-PROC work-proc-id
work-proc-id

XtWorkProcId

Return Value
U nspecified.

DWT:RESIZE-WIDGET Intrinsic Function
R e sizes a sib lin g w id get o f the child m ak in g the geom etry request.

Format
DWT:RESIZE-WIDGET widget width height border-width
widget

DWT:WIDGET

width
height
border-width

INTEGER
INTEGER
INTEGER

Return Value
U nspecified.

DWT-79

DWT:RESIZE-WINDOW Intrinsic Function

DWT: RESIZE-WIN DOW Intrinsic Function
R e sizes a child w id get that already h as the new valu es o f its width, height, and
border-w idth fields.

Format
DWT:RESIZE-WINDOW widget
DWT: WIDGET

W idget

Return Value
U nspecified.

DWT:SCALE High-Level Function
C reates a sca le w id get that allow s an application to disp la y a scale for vernier
control of a pa ra m eter w hile displayin g the current valu e and range.

Format
DWT:SCALE parent-widget name x y width height scale-width scale-height title
min-value max-value decimal-points value orientation callback
drag-callback help-callback
parent-widget

DWT:WIDGET

name

STRING

xy
width
height
scale-width
scale-height

INTEGER
INTEGER
INTEGER
INTEGER
INTEGER

title

COMPOUND-STRING

min-value
max-value
decimal-points
value
orientation

INTEGER
INTEGER
INTEGER
INTEGER
INTEGER

callback
drag-callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type dwt: widget represen tin g the new widget.

DWT-80

DWT:SCALE-CREATE Low-Level Function

DWT:SCALE-CREATE Low-Level Function
C rea tes a scale widget.

Format
DWT:SCALE-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type DWT:w idget represen tin g the new widget.

DWT:SCALE-GET-SLIDER High-Level Function
G ets the current value o f the slid er position displayed in the scale.

Format
DWT:SCALE-GET-SLIDER widget &OPTIONAL value
widget

DWT: WIDGET

value

INTEGER

Return Value
T he value o f the cu rren t slid er position.

DWT:SCALE-SET-SLIDER High-Level Function
S ets or ch an ges the cu rren t value o f the slid er p osition disp layed in the scale.

Format
DWT:SCALE-SET-SLIDER widget value
widget

DWT: WIDGET

value

INTEGER

Return Value
Unspecified.

DWT-81

DWTrSCREEN Intrinsic Function

DWT:SCREEN Intrinsic Function
Returns the screen pointer for the specified widget.
Format
DWT:SCREEN widget
widget

DWT: WIDGET

Return Value

An object of type c l x : screen representing the screen.

DWT:SCROLL-BAR High-Level Function
Creates a scroll bar widget for the application to display and process scroll bar
screen operations.
Format
DWT:SCROLL-BAR parent-widget name x y width height inc page-inc shown int-value
min-value max-value orientation callback help-callback
unit-inc-callback unit-dec-callback page-inc-callback
page-dec-callback to-top-callback to-bottom-callback drag-callback
parent-widget

DWT:WIDGET

name

STRING

xy
width
height
inc
page-inc
shown
int-value
min-value
max-value
orientation

INTEGER
INTEGER
INTEGER

callback
help-callback
unit-inc-callback
unit-dec-callback
page-inc-callback
page-dec-callback
to-top-callback
to-bottom-callback
drag-callback

CALL-BACK-ROUT INE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

INTEGER

INTEGER
INTEGER
INTEGER
INTEGER
INTEGER
INTEGER

Return Value
An object o f type DWT:WIDGET rep resen tin g the new widget.

DWT—82

DWT:SCROLL-BAR-CREATE Low-Level Function

DWT:SCROLL-BAR-CREATE Low-Level Function
C rea tes a scroll bar widget.

Format
DWT:SCROLL-BAR-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object o f type dwt: widget represen tin g th e new widget.

DWT:SCROLL-BAR-GET-SLIDER High-Level Function
R etrieves the current size and p osition p aram eters o f the slid er in the scroll bar
widget.

Format
DWT:SCROLL-BAR-GET-SLIDER widget &OPTIONAL value shown inc page-inc
widget

dwt : widget

value
shown
inc
page-inc

integer
integer

INTEGER
integer

Return Value
F our values:
• An in teger represen tin g the value.
•

An in teger rep resen tin g the shown.

• An in teger represen tin g the inc.
•

An in teger represen tin g the page-inc.

DWT—83

DWT:SCROLL-BAR-SET-SLIDER High-Level Function

DWT:SCROLL-BAR-SET-SLIDER High-Level Function
S ets or ch a n ges the current size/position p aram eters o f the slid er in the scroll bar
widget.

Format
DWT:SCROLL-BAR-SET-SLIDER widget value shown inc page-inc notify
widget

DWT:WIDGET

value
shown
inc
page-inc
notify

INTEGER
INTEGER
INTEGER
INTEGER
INTEGER

Return Value
U nspecified.

DWT:SCROLL-WlNDOW High-Level Function
C reates a scroll w indow w id get for sim ple application s in the m ain w indow w idget
w ork area.

Format
DWT:SCROLL-WINDOW parent-widget name x y width height
parent-widget

DWT:WIDGET

name

STRING

INTEGER
INTEGER
INTEGER

width
height

Return Value
An object o f type DWT:widget represen tin g the new widget.

DWT:SCROLL-WINDOW-CREATE Low-Level Function
C reates a scroll w indow w id get for sim ple application s in the m ain w indow w id get
w ork area.

Format
DWT:SCROLL-WINDOW-CREATE parent-widget name override-arglist override-argcount

DWT—84

parent-widget

dwt : wi d get

name

STRING

DWT:SCROLL-WINDOW-CREATE Low-Level Function

override-arglist

ArgList

override-argcount

integer

Return Value

An object of type dwt : widget representing the new widget.

DWT:SCROLL-WINDOW-SET-AREAS High-Level
Function
Sets up or adds the window region, and the horizontal or vertical scroll bar
widgets to the scroll window widget.
Format
DWT:SCROLL-WINDOW-SET-AREAS widget h-scroll v-scroll work-region
widget
h-scroll
v-scroll
work-region

DWT:WIDGET
DWT:WIDGET
DWT:WIDGET
DWT:WIDGET

Return Value

Unspecified.

DWT:SELECTION High-Level Function
Creates a selection widget.
Format
DWT:SELECTION parent-widget name x y title value items itemcount visibleitemcount
style default-position callback help-callback

parent-widget

DWT:WIDGET

name

STRING

INTEGER

title
value
items

COMPOUND-STRING
COMPOUND-STRING
COMPOUND-STRING

itemcount
visibleitemcount
style
default-position

INTEGER
INTEGER
INTEGER
INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value

An object of type DWT: WIDGET representing the new widget.

DWT-85

DWT:SELECTION-CREATE Low-Level Function

DWT:SELECTION-CREATE Low-Level Function
Creates a selection widget.
Format
DWT:SELECTION-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type dwt :w idget representing the new widget.

DWT:SEPARATOR High-Level Function
Creates a separator widget for the application to define a border between items in
a display.
Format
DWT:SEPARATOR parent-widget name x y orientation
parent-widget

DWT:WIDGET

name

STRING

xy
orientation

INTEGER
INTEGER

Return Value

An object of type dwt : w idget representing the new widget.

DWT:SEPARATOR-CREATE Low-Level Function
Creates a separator widget.
Format
DWT:SEPARATOR-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type dwt :w idget representing the new widget.
DWT—86

DWT:SEPARATOR-GADGET-CREATE G a dget Function

DWT:SEPARATOR-GADGET-CREATE Gadget

Function
C rea tes a separator gadget.

Format
DWT:SEPARATOR-GADGET-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
A n object o f type dwt: widget rep resen tin g the new widget.

DWT:SET-ERROR-HANDLER Intrinsic Function
R eg ister s an error p rocedu re to be called on a fatal error condition.

Format
DWT:SET-ERROR-HANDLER handler
handler

XtErrorHandler

Return Value
U nspecified.

DWT:SET-ERROR-MSG-HANDLER Intrinsic Function
R e g ister s a procedure that is called on a fatal error condition.

Format
DWT:SET-ERROR-MSG-HANDLER handler
handler

XtErrorMsgHandler

Return Value
U nspecified.

DWT-87

DWT:SET-KEYBOARD-FOCUS Intrinsic Function

DWT:SET-KEYBOARD-FOCUS Intrinsic Function
R edirects keyw ord in pu t to a child w id get o f a com p osite widget.

Format
DWT:SET-KEYBOARD-FOCUS subtree descended

subtree
descended

DWT: w id g e t
DWT: WIDGET

Return Value
U nspecified.

DWT:SET-KEY-TRANSLATOR Intrinsic Function
R egisters a k ey translator.

Format
DWT:SET-KEY-TRANSLATOR display translator

display

CLX: DISP LAY

translator

XtKeyProc

Return Value
U nspecified.

DWT:SET-MAPPED-WHEN-MANAGED Intrinsic
Function
C h a n ges the value o f a w id get’
s m apped-w hen-m anaged field.

Format
DWT:SET-MAPPED-WHEN-MANAGED widget mapped-when-managed

widget
mapped-when-managed
Return Value
Unspecified.

DWT—88

dwt: w id g e t
INTEGER

DWT:SET-SELECTION-TIMEOUT intrinsic Function

DWTiSET-SELECTION-TIMEOUT Intrinsic Function
S e ts the in trinsics selection timeout.

Format
DWT:SET-SELECTION-TIMEOUT timeout

timeout

INTEGER

Return Value
U nspecified.

DWT:SET-SENSITIVE Intrinsic Function
S e ts the sen sitivity state o f a widget.

Format
DWTiSET-SENSITIVE widget sensitive

widget
sensitive

DWT:WIDGET
INTEGER

Return Value

Unspecified.

DWTiSET-SUBVALUES Intrinsic Function
S e ts the current value o f a n on w idget resou rce associated w ith a w id get instance.

Format
DWTiSET-SUBVALUES base-addr resource-list resource-count arglist argcount

base-addr

INTEGER or alien structure

resource-list

XtResourceList

resource-count
arglist
argcount

ArgList

INTEGER
INTEGER

Return Value

Unspecified.

DWT—89

DWT:SET-VALUES Intrinsic Function

DWTrSET-VALUES Intrinsic Function
M odifies th e current value o f a resou rce a ssocia ted w ith a w id get instance.

Format
DWT:SET-VALUES widget arglist argcount
widget

DWT:WIDGET

arglist

ArgList

argcount

INTEGER

Return Value

Unspecified.

DWT:SET-WARNING-HANDLER Intrinsic Function
R eg ister s a procedure to be called on nonfatal error conditions.

Format
DWT:SET-WARNING-HANDLER handler
handler

XtErrorHandler

Return Value

Unspecified.

DWT:SET-WARNING-MSG-HANDLER Intrinsic
Function
R e g ister s a procedure that is called on a nonfatal error condition.

Format
DWT:SET-WARNING-MSG-HANDLER handler
handler

Return Value

Unspecified.

DWT-90

XtErrorMsgHandler

DWT:S-TEXT High-Level Function

DWT:S-TEXT High-Level Function
Creates a simple text widget for the application to display a single or multiline
text field. The user can enter and edit text in the field.
Format
DWT:S-TEXT parent-widget name x y cols rows string-value
parent-widget

DWT:WIDGET

name

STRING

x y

cols
rows

INTEGER
INTEGER
INTEGER

string-value

STRING

Return Value

An object of type dwt:w idget representing the new widget.

DWT:S-TEXT-CLEAR-SELECTION High-Level
Function
Clears the global selection highlighted in the simple text widget.
Format
DWT:S-TEXT-CLEAR-SELECTION widget time
widget

dwt: widget

time

Time

Return Value

Unspecified.

DWT:S-TEXT-CREATE Low-Level Function
Creates a simple text widget.
Format
DWT:S-TEXT-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

DWT—91

DWT:S-TEXT-CREATE Low-Level Function
Return Value
An object o f type d w t :w i d g e t re p resen tin g the new widget.

DWT:S-TEXT-GET-EDITABLE High-Level Function
Grets the current p erm ission inform ation con cern in g w hether the text in the
sim p le text w id get m ay be edited b y the user.

Format
DWT:S-TEXT-GET-EDITABLE widget

widget

DWT: WIDGET

Return Value
A boolean value that is true if the u ser can edit the text in the sim p le text widget.

DWT:S-TEXT-GET-MAX-LENGTH High-Level Function
Grets the current m axim u m allow able len gth o f the text strin g in the sim ple text
widget.

Format
DWT:S-TEXT-GET-MAX-LENGTH widget

Widget

DWT: WIDGET

Return Value
A n in te g e r re p re se n tin g the m a xim u m le n g th o f the te x t w idget.

DWT:S-TEXT-GET-SELECTION High-Level Function
G ets the global selection, if any, cu rren tly h igh ligh ted in the sim p le text widget.

Format
DWT:S-TEXT-GET-SELECTION widget selection selection-ien

widget

dwt :widget

selection
selection-ien

STRING
integer

Return Value
A strin g con tain in g the cu rren tly selected text in the sim p le text widget.

DWT—92

DWT:S-TEXT-GET-STRING High-Level Function

DWT:S-TEXT-GET-STRlNG High-Level Function
G ets the text strin g from the sim p le text widget.

Format
DWT:S-TEXT-GET-STRING widget string-value string-len
widget

dwt : widget

string-value

STRING

string-len

integer

Return Value
An alien structure containing the entire contents o f the text w id get as an A S C IZ
string.

DWT:S-TEXT-REPLACE High-Level Function
R ep laces a portion o f the current text strin g in the sim p le text w idget or in serts a
n ew su b strin g in the text.

Format
DWT:S-TEXT-REPLACE widget from-pos to-pos string-value
widget

DWT:WIDGET

from-pos
to-pos

INTEGER
INTEGER

string-value

STRING

Return Value
U nspecified.

DWT:S-TEXT-SET-EDITABLE High-Level Function
S e ts the perm ission inform ation th at determ in es w h eth er the text in the w idget
m a y be edited by the user.

Format
DWT:S-TEXT-SET-EDITABLE widget editable
widget

DWT: WIDGET

editable

integer

Return Value
U nspecified.

DWT—93

DWT:S-TEXT-SET-MAX-LENGTH High-Level Function

DWT:S-TEXT-SET-MAX-LENGTH High-Level Function
S e ts the m axim u m allow able len gth o f the text strin g in the sim p le text widget.

Format
DWT:S-TEXT-SET-MAX-LENGTH widget max-ten
widget

DWT:WIDGET

max-len

INTEGER

Return Value
U nspecified.

DWT:S-TEXT-SET-SELECTION High-Level Function
M akes specified tex t in the sim ple text w id get the current global selection and
h igh ligh ts it in the sim p le text widget.

Format
DWT:S-TEXT-SET-SELECTION widget first last time
Widget

DWT: WIDGET

first
last

INTEGER
INTEGER

time

Time

Return Value
U nspecified.

DWT:S-TEXT-SET-STRING High-Level Function
S ets the text strin g in the sim ple text widget.

Format
DWT:S-TEXT-SET-STRING widget string-value
widget

DWT: WIDGET

string-value

STRING

Return Value
U nspecified.

DWT—94

DWTiSTRING C om p ou n d String Function

DWT:STRING Compound String Function
S ee DWT: x t st r in g com p ou n d strin g function.

DWT:SUPERCLASS intrinsic Function
Identifies the w id get’
s superclass.

Format
DWT:SUPERCLASS widget
widget

DWT: WIDGET

Return Value
A W idgetC lass alien stru ctu re re p resen tin g a pointer to the w id get’
s su p erclass
cla ss structure.

DWT:TOGGLE-BUTTON High-Level Function
C reates a to gg le bu tton w id ge t for the application to disp lay screen settable
sw itches for the user.

Format
DWT:TOGGLE-BUTTON parent-widget name x y label value callback help-callback
parent-widget

DWT:WIDGET

name

STRING

INTEGER

label

COMPOUND-STRING

value

INTEGER

callback
help-callback

CALL-BACK-ROUTINE
CALL-BACK-ROUTINE

Return Value
An object o f type DWT:w idget rep resen tin g the new widget.

DWT-95

DWT:TOGGLE-BUTTON-CREATE Low-Level Function

DWTiTOGGLE-BUTTON-CREATE Low-Level Function
Creates a toggle button widget.
Format
DWTiTOGGLE-BUTTON-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value

An object of type DWT:widget representing the new widget.

DWT:TOGGLE-BUTTON-GADGET-CREATE Gadget
Function
Creates a toggle button gadget.
Format
DWTiTOGGLE-BUTTON-GADGET-CREATE parent-widget name
override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
A n object o f type DWT:widget rep resen tin g the new widget.

DWT:TOGGLE-BUTTON-GET-STATE High-Level
Function
Gets the current state of the toggle button.
Format
DWT:TOGGLE-BUTTON-GET-STATE widget
widget

INTEGER

Return Value
A n in teger represen tin g the value attribu te o f the to gg le button.

DWT—96

DWT:TOGGLE-BUTTON-SET-STATE High-Level Function

DWT:TOGGLE-BUTTON-SET-STATE High-Level
Function
S ets or ch an ges the current state o f the to gg le button.

Format
DWT:TOGGLE-BUTTON-SET-STATE widget value notify

Widget

DWT:WIDGET

value
notify

INTEGER
INTEGER

Return Value
Unspecified.

DWTiTOOLKIT-INITIALIZE Intrinsic Function
InitiaH zes the X U I Tbolkit internals.

Format
DWT:TOOLKIT-INITIALIZE

Return Value
U nspecified.

DWT:TRANSLATE-COORDS Intrinsic Function
T ran slates X an d Y w id get coordinates to root coordinates.

Format
DWT:TRANSLATE-COORDS widget x y
widget

DWT: WIDGET

INTEGER

Return Value
Two values:
• An in teger re p resen tin g the root-relative X coordinate.
• An in teger rep resen tin g the root-relative Y coordinate.

DWT—97

DWT:TRANSLATE-KEYCODE Intrinsic Function

DWT:TRANSLATE-KEYCODE Intrinsic Function
Invokes the currently registered K eyC ode to the K eySym translator.

Format
DWT:TRANSLATE-KEYCODE display keycode modifiers modifiers-return keysym-return

display

CLX:DISPLAY

keycode
modifiers
modifiers-return

KeyCode

keysym-return

KeySym

Modifiers
Modifiers

Return Value
U nspecified.

DWT:UNDO-COPY-TO-CLIPBOARD Cut-and-Paste
Function
D eletes the la st item placed on the clipboard.

Format
DWT:UNDO-COPY-TO-CLIPBOARD display windowidget

display
windowidget

c l x : DI sp la y
DWT: WIDGET

Return value
O ne o f tw o p ossib le con stan ts w h ose in tegers rep resen t the statu s as follows:
DWT: CLIPBOARD-SUCCESS

DWT:CLIPBOARD-LOCKED

DWT:UNINSTALL-TRANSLATIONS Intrinsic Function
R em oves all ex istin g translations.

Format
DWT:UNINSTALL-TRANSLATIONS widget

widget
Return Value
U nspecified.

DWT—98

DWT: w id g e t

DWT:UNMANAGE-CHILD Intrinsic Function

DWT:UNMANAGE-CHILD Intrinsic Function
R em oves a sin gle child w id get from its p aren t’
s set o f m an aged children.

Format
DWT:UNMANAGE-CHILD widget
Widget

DWT: WIDGET

Return Value
Unspecified.

DWT:UNMANAGE-CHILDREN Intrinsic Function
R em oves a list o f children from the p aren t w id get’
s m an aged fist.

Format
DWT:UNMANAG E-CHILDREN widget-list num-children
widget-list

WidgetList

num-children

INTEGER

Return Value
Unspecified.

DWT:UNREALIZE-WIDGET Intrinsic Function
D estroy s the w indow s associated w ith a w id get and its descendants.

Format
DWT:UNREALIZE-WIDGET widget
widget

DWT: WIDGET

Return Value
Unspecified.

DWT—99

DWT:VMS-CLEAR-STRING Convenience Function

DWT:VMS-CLEAR-STRING Convenience Function
F rees a strin g in an argu m en t list.

Format
DWT:VMS-CLEAR-STRING arglist argcount
arglist

ArgList

argcount

INTEGER

Return Value
U nspecified.

DWT:VMS-FREE-ARGNAMES Convenience Function
F rees m em ory allocated for argu m en t names.

Format
DWTrVMS- FREE-ARGNAMES arglist argcount
arglist

ArgList

argcount

INTEGER

Return Value
U nspecified.

DWT:VMS-SET-ARG Convenience Function
P la ces an a rgu m en t in the argu m en t list.

Format
DWT:VMS-SET-ARG arg arglist argnumber argname
arg

ALIEN-STRUCTURE

arglist

ArgList

argnumber

INTEGER

argname

STRING

Return Value
U nspecified.

DWT-100

DWT:VMS-SET-CALLBACK-ARG Convenience Function

DWT:VMS-SET-CALLBACK-ARG Convenience
Function
Places a callback in the argum ent list.
Format
DWT:VMS-SET-CALLBACK-ARG callback-arg arglist argnum argname

callback-arg

CALL-BACK-ROUTINE

arglist
argnum

ArgList

argname

STRING

INTEGER

Return Value
Unspecified.

DWT:VMS-SET-DESC-ARG Convenience Function
Places a descriptor in the argum ent list.
Format
DWT:VMS-SET-DESC-ARG arg arglist argnum argname

arg
arglist

s t r in g

argnum
argname

in t e g e r

ArgList

s t r in g

Return Value

Unspecified.

DWT:WARNING Intrinsic Function
See DWT:XTWARNING in trin sic function.

DWT:WARNING-MSG Intrinsic Function
Calls th e in stalled high-level w arning handler.
Format
DWT:WARNING-MSG resource-name resource-type resource-class default-string

params num-params

DWT-101

DWT:WARNING-MSG Intrinsic Function

resource-name
resource-type
resource-class
default-string
params

STRING
STRING
STRING
STRING
STRING

num-params

INTEGER

Return Value
Unspecified.

DWT:WIDGET-TO-APPLICATION-CONTEXT Intrinsic
Function
R eturns the application context for a given widget.
Format
DWT:WIDGET-TO-APPLICATION-CONTEXT widget
widget

DWT: WIDGET

Return Value
An XtAppContext integer representing th e application context.

DWT:WINDOW Intrinsic Function
R eturns the window of the specified widget.
Format
DWTWINDOW widget
widget

DWT: WIDGET

Return Value
An object of type c l x :window rep resen tin g th e widget’s window.

DWT:WINDOW-CREATE Low-Level Function
C reates a window widget.
Format
DWT:WINDOW-CREATE parent-widget name override-arglist override-argcount

DWT—102

parent-widget

DWT: WIDGET

name

STRING

DWT:WINDOW-CREATE Low-Level Function

override-arglist

ArgList

override-argcount

integer

Return Value
An object o f type DWT: widget rep resen tin g the n ew widget.

DWT:WlNDOW-TO-WIDGET Intrinsic Function
T ranslates a window and display pointer into a widget instance.
Format
DWT:WI NDOW-TO-WI DG ET display window
display

CLX: DISPLAY

window

CLX: WINDOW

Return Value
An object of type dwt:widget representing th e new widget.

DWT:WORK-BOX High-Level Function
C reates a work box widget for th e application to display work in progress
m essages.
Format
DWT:WORK-BOX parent-widget name default-position x y style label cancel-label
use-percent-scale callback help-callback
parent-widget

dwt : WIDGET

n am e

STRING

default-position
xy
style

INTEGER
INTEGER
INTEGER

label
cancel-label

COMPOUND-STRING
compound- st r in g

use-percent-scale

integer

callback
help-callback

CALL-BACK-ROUTINE
call - back - routine

Return Value
An object of type dwt : widget representing th e new widget.

DWT—103

DWT:WORK-BOX-CREATE Low-Level Function

DWT:WORK-BOX-CREATE Low-Level Function
C reates a work box widget.
Format
DWT:WORK-BOX-CREATE parent-widget name override-arglist override-argcount
parent-widget

DWT:WIDGET

name

STRING

override-arglist

ArgList

override-argcount

INTEGER

Return Value
An object of type DWT:w idget representing th e new widget.

DWT:XTERROR Intrinsic Function
Calls th e installed fatal error procedure and passes the m essage specified.
Format
DWT:XTERROR message
message

STRING

Return Value
Unspecified.

DWT:XTSTRING Compound String Function
C reates a compound string.
Format
DWT:XTSTRING text charset dir-r-to-l
text

STRING

charset
dir-r-to-l

in teger
in teger

Return Value
An object of type compound- s t r in g representing th e resu ltin g compound string. A
null pointer is retu rn ed if the text is null.

DWT—104

DWTiXTWARNING Intrinsic Function

DWT:XTWARNING Intrinsic Function
Calls the installed nonfatal erro r procedure.
Format
DWT:XTWARNING message

message

str in g

Return Value
Unspecified.

DWT-105

Partlll
Guide to Programming CLX

Chapter 4

Programming Overview of CLX

VAX LISP provides an im plem entation of th e Common LISP X (CLX) interface to
th e X Window System™ protocol. This chapter provides an overview of CLX, a
description of CLX data types, and a n introductory CLX program . The program is
an n o tated w ith references to relevant program m ing descriptions in other chapters
of th is guide.

4.1 Overview of CLX
CLX is a package of LISP routines th a t give LISP program m ers access to the
capabilities of the X Window System (X) w ithout having to call out to external
ro utines or define non-LISP d a ta structures. X was developed by Project A thena
an d th e L aboratory for Com puter Science a t the M assachusetts In stitu te of
Technology w ith funding and participation by Digital E quipm ent Corporation and
In te rn atio n a l Business M achines, Inc. VAX LISP Version 3.0 supports X Version
11, Release 3 (X11R3). CLX ru n s on all VAX hardw are except th e VAX 11/725 and
th e MicroVAX I.
The program th a t controls devices such as screens, keyboards, and mice is called
th e “server.” X servers ru n on com puters w ith e ith e r monochrome or color bitm ap
screens (workstations). The server d istributes u se r in p u t to and accepts output
req u ests from “client” (application) program s. The server re tu rn s inform ation to
clients by m eans of either replies or events. Replies are retu rn ed synchronously
b u t events äre retu rn ed asynchronously.
CLX processes some client requests, such as queries about the characteristics of
windows, w ithin the CLX library. I t sends other client requests, such as those
p ertain in g to displaying graphics on a screen or receiving device input, to the
server. The server m ay or m ay not reside on the sam e system as the client
a n d CLX. In the la tte r case, CLX com m unicates w ith the server via DECnet or
TCP/IP.
CLX, like Xlib, enables clients to com m unicate w ith the X server to create and
m anage operations w ith windows, graphics, cursors, fonts and text, pixm aps
a n d offscreen images, and events. The Xlib docum entation explains th e basic
principles of the X Window System , such as th e window hierarchy, the coordinate
system , and so on. This m anual assum es th a t you are fam iliar w ith these
concepts and documents prim arily th e differences betw een CLX and Xlib. The
Xlib m anuals are:
•

VMS DECwindows Guide to Xlib Program m ing: MIT C Binding

™ X Window System is a tradem ark of the Massachusetts Institute of Technology.

Programming Overview of CLX 4—1

•

VMS DECwindows XLib Routines Reference Manual

• X Window System: C Library and Protocol Reference
All VAX LISP objects im plem enting CLX a re in package c l x : and are exported.
This package is p a rt of the LISP executable image. It is installed when VAX
LISP is installed. Some sam ple program s are included in th e VAX LISP example
directory, which can be referred to by th e logical nam e LISP$EXAMPLES.

4.2 CLX Data Types
The CLX specification defines num erous d a ta types. These are listed in Table 4—1
in alphabetical order.
Table 4-1:

CLX Data Types

T y p e S p e c ifie r

CLX:ALIST

R e p r e s e n t a t io n

LIST
An association list, with elements o f the form:

key-type-and-name datum-type-and-name

CLX:ANGLE

A number between (* -2 p i) and (* 2 p i ) , inclusive.
Note that this angle representation is different from the one actually
transm itted in the protocol.

CLX:ARC—SEQ

(CLX:REPEAT-SEQ (FIXNUM X) (FIXNUM Y)
(FIXNUM WIDTH) (FIXNUM HEIGHT)
(CLX:ANGLE ANGLE1) (CLX:ANGLE ANGLE2) )

CLX:ARRAY-INDEX

An integer between 0 and ARRAY-DIMENSION-LIMIT, inclusive.

CLX:BIT-GRAVITY

(MEMBER : FORGET : STATIC : CENTER :NORTH :NORTH-EAST
:EAST : SOUTH-EAST :SOUTH :SOUTH-WEST :WEST
:NORTH-WEST)

CLX:BITMAP

(ARRAY BIT (* *) )

CLX:BITMAP-FORMAT

LISP structure.

CLX:BOOLEAN

(OR NULL (NOT NULL) )

CLX:CARD8

FIXNUM

CLX:CARD16

FIXNUM

CLX:CARD2 9

INTEGER

CLX:COLOR

VAX LISP alien structure.

CLX: COLORMAP

LISP structure.

CLX:DEVICE-EVENT-MASK

(OR CLX:MASK32 (LIST CLXrDEVICE-EVENT-MASK-CLASS) )

CLX:DEVICE-EVENT-MASK-CLASS

(MEMBER :KEY-PRESS :KEY-RELEASE :BUTTON-PRESS
:BUTTON-RELEASE : POINTER-MOTION
:BUTTON-l-MOTION : BUTTON-2-MOTION
:BUTT0N-3-M0TI0N : BUTTON-4-MOTION
:BUTTON-5-MOTION : BUTTON-MOTION)

CLX:DISPLAY

VAX LISP alien structure.

CLX: DRAWABLE

(OR CLX:WINDOW CLX:PIXMAP)

CLX: DRAW-DIRECTION

(MEMBER : LEFT-TO-RIGHT :RIGHT-TO-LEFT)

(continued on next page)

4-2

Programming Overview of CLX

Table 4-1 (Cont.):

CLX Data Types

T y p e S p e c ifie r

R e p r e s e n t a t io n

CLX:EVENT-KEY

(MEMBER :KEY-PRESS : KEY-RELEASE :BUTTON-PRESS
:BUTTON-RELEASE -.MOTION-NOTIFY :ENTER-NOTIFY
:LEAVE-NOTIFY :FOCUS-IN :FOCUS~OUT
:KEYMAP-NOTIFY :EXPOSURE :GRAPHICS-EXPOSURE
:NO-EXPOSURE :VISIBILITY-NOTIFY :CREATE-NOTIFY
:DESTROY-NOTIFY :UNMAP-NOTIFY :MAP-NOTIFY
:MAP-REQUEST :REPARENT-NOTIFY
:CONFIGURE-NOTIFY :GRAVITY-NOTIFY
:RESIZE-REQUEST :CONFIGURE-REQUEST
:CIRCULATE-NOTIFY :CIRCULATE-REQUEST
:PROPERTY-NOTIFY :SELECTION-CLEAR
:SELECTION-REQUEST :SELECTION-NOTIFY
:COLORMAP-NOTIFY :CLIENT-MESSAGE)

CLX:EVENT-MASK

(OR CLX:MASK32 (LIST CLX:EVENT-MASK-CLASS) )

CLX:EVENT-MASK-CLAS S

(MEMBER :KEY-PRESS :KEY-RELEASE : OWNER-GRAB-BUTTON
:BUTTON-PRESS :BUTTON-RELEASE :ENTER-WINDOW
:LEAVE-WINDOW :POINTER-MOTION
:POINTER-MOTION-HINT :BUTTON-1-MOTION
:BUTTON-2-MOTION : BUTTON-3-MOTION
:BUTTON-4-MOTION : BUTTON-5-MOTION
:BUTTON-MOTION :EXPOSURE :VISIBILITY-CHANGE
: STRUCTURE-NOTIFY :RESIZE-REDIRECT
: SUBSTRUCTURE-NOTIFY : SUBSTRUCTURE-REDIRECT
:FOCUS-CHANGE : PROPERTY-CHANGE
:COLORMAP-CHANGE :KEYMAP-STATE)

CLX:FONT

LISP structure.

CLX:FONTABLE

(OR CLX: STRINGABLE CLX:FONT)

CLX:FONT-PROPS

LIST
The list contains alternating keywords and integers.

CLX:GCONTEXT-KEY

(MEMBER :FUNCTION : PLANE-MASK : FOREGROUND :BACKGROUND
:LINE-WIDTH :LINE-STYLE :CAP-STYLE :JOIN-STYLE
:FILL-STYLE :FILL-RULE : ARC-MODE : TILE
: STIPPLE : TS-X :TS-Y : FONT : SUBWINDOW-MODE
:EXPOSURES :CLIP-X :CLIP-Y : CLIP-MASK
:D A S H - O F F S E T :DASHES)

CLX:GRAB-STATUS

(MEMBER : SUCCESS :ALREADY-GRABBED :FROZEN
: INVALID-TIME :NOT-VIEWABLE)

CLX: IMAGE

VAX LISP alien structure.

CLX:IMAGE-DEPTH

(INTEGER 0 32)

CLX:INDEX-SIZE

(MEMBER : DEFAULT 8 16)

CLX:KEYSYM

INTEGER

CLX:LOGICAL-OP

(MEMBER : GX-CLEAR : GX-AND : GX -AND -REV ERSE :G X -C O PY
:G X -A N D -IN V E R T E D : GX-NOOP : GX-XOR :G X -O R
: GX-NOR : G X -E Q U IV :G X -IN V E R T : G X -O R -R EV ER SE
:G X -C O PY -IN V E R T E D : G X -O R -IN V ER T ED : GX-NAND
:G X -S E T )

O r a BOOLE constant (see Com mon LISP: The L an gu age ).

CLX:MASK16

FIXNUM

(continued on next page)

Programming Overview of CLX 4—3

Table 4-1 (Cont.):

CLX Data Types

T y p e S p e c ifie r

R e p r e s e n ta tio n

CLX:MASK32

INTEGER

CLX:MODIFIER-KEY

(MEMBER : SHIFT :LOCK :CONTROL :MOD-l :MOD-2 :MOD-3
:MOD-4 :MOD-5)

CLX:MODIFIER-MASK

(OR (MEMBER :ANY) CLX:MASK16 (LIST CLX:MODIFIER-KEY))

CLX:PIXARRAY

(ARRAY CLX:PIXEL (* *) )

CLX:PIXEL

(UNSIGNED-BYTE 32)

CLX:PIXMAP

LISP structure.

CLX:PIXMAP-FORMAT

VAX LISP alien structure.

CLX:P0INTER-EVENT-MASK

(OR CLX :MASK32 (LIST CLX: POINTER-EVENT-MASK-CLASS) )

CLX:POINTER-EVENT-MASK-CLASS

(MEMBER BUTTON-PRESS :BUTTON-RELEASE :ENTER-WINDOW
LEAVE-WINDOW :POINTER-MOTION
POINTER-MOTION-HINT : BUTTON-1-MOTION
BUTTON-2-MOTION : BUTTON-3-MOTION
BUTTON-4—MOTION :BUTTON-5-MOTION
BUTTON-MOTION : KEYMAP-STATE)

CLX:POINT-SEQ

(CLX:REPEAT-SEQ (CLX:CARD16 X) (CLX:CARD16 Y) )

CLX:RECT-SEQ

(CLX:REPEAT-SEQ (CLX: CARD16 X) (CLX:CARD16 Y)
(CLX: CARD16 WIDTH) (CLX:CARD16 HEIGHT) )

CLX:REPEAT-SEQ

SEQUENCE
A sequence containing zero or m ore elem ents o f the form

(type name).

CLX:RESOURCE-ID

INTEGER

CLX:RGB-VAL

(FLOAT 0. 0 1.0)

CLX:SCREEN

VAX LISP alien structure.

CLX: SEG-SEQ

(CLX:REPEAT-SEQ (FIXNUMX1) (FIXNUMY1)
(FIXNUMX2) (FIXNUM Y2) )

CLX:STATE-MASK-KEY

(OR CLX:MODIFIER-KEY
(MEMBER : BUTTON-1 :BUTTON-2 : BUTTON-3
:BUTTON-4 :BUTTON-5))

CLX: STRINGABLE

(OR STRING SYMBOL)
(OR NULL INTEGER)

CLX:TIMESTAMP

NIL stands for the current time.
CLX:VISUAL

CLX: CARD2 9

CLX:VISUAL-INFO

VAX LISP alien structure.

CLX:WINDOW

LISP structure.

CLX:WIN-GRAVITY

(MEMBER FORGET : STATIC : CENTER :NORTH :NORTH-EAST
•.EAST :SOUTH-EAST : SOUTH : SOUTH-WEST :WEST
:NORTH-WEST)

CLX:XATOM

(OR STRING SYMBOL)

CLX stru ctu res (such as CLX:d isp l a y , c l x :FONT, c l x :window, and so on) are
described in C hapters 5 through 13.

4—4

Programming Overview of CLX

4.3 A Sample CLX Program
The sam ple program in Exam ple 4—1 shows how to open a display, create
windows, display text, draw graphics, and handle events.
Example 4-1:

Sample CLX Program

;;; This is a CLX transcription of the sample Xlib program in the "VMS DECwindows
;;; Guide to Xlib Programming: MIT C Binding." Some utility functions that are
;;; not strictly part of the example precede the transcription.
;;; The following functions avoid repeatedly closing and reopening the display.
;;; DISPLAY-OPEN could be enhanced to check that *DISPLAY* actually contains a
;;; display and also close the old display and open a new one if a different host
;;; is specified.
(defvar *display* nil)
(defvar font-name "-ADOBE-NEW CENTURY SCHOOLBOOK-MEDIUM-R-NORMAL— *-140-*-*-P-*"
(defvar window-name "Sample CLX Program")
(defun display-open (Soptional (host ""))
(or *display*

(setq *display* (clx:open-display host)) ) )

(defun display-close ()
(unless (null ^display*)
(setq *display* (clx:close-display *display*)) ) )
;;; This helper function is part of the Xlib example
(defun define-color (screen visual color)
(case (clx:visual-info-class visual)
((:pseudo-color :direct-color)
©
(clx:alloc-color
(clx:screen-default-colormap screen)
(svref '#("DarkSlateBlue" "LightGray" "Firebrick") color) ) )
(otherwise
(case color
((0 2) (clx:screen-black-pixel screen))
(1 (clx:screen-white-pixel screen)) ) ) ) )
;;; Transcription of Xlib Programming Guide example
(defun xlib-example (Soptional (host ""))
"XLIB-EXAMPLE «.OPTIONAL (host "")
A CLX transcription of the sample Xlib program in the VMS DECwindows Guide to
Xlib Programming: MIT C Binding. If a display has already been opened by
DISPLAY-OPEN, it will be used. The display will be left open upon exit."

(continued on next page)

Programming Overview of CLX 4-5

Example 4-1 (Cont.):

Sample CLX Program

(let ((display (display-open host))
window-1
window-2
gc )
(let* ((screen (first (clx:display-roots display)))
(depth (clx:screen-root-depth screen))
(visual (clx:make-visual-info
:data (clx:screen-root-visual screen) ))
(window-lw 400)
(window-lh 300)
(window-lx (floor (- (clx:screen-width screen) window-lw) 2))
(window-ly (floor (- (clx:screen-height screen) window-lh) 2))
(window-2w 300)
(window-2h 150)
(window-2x 50)
(window-2y 75)
(font (clx:open-font display font-name ))
(event-mask (clx:make-event-mask :exposure :button-press)) )
©
(setq window-1 (clx:create-window
:parent (clx:screen-root screen)
:x window-lx :y window-ly
:width window-lw :height window-lh
:depth depth :border-width 0
:class :input-output :visual visual
:background (define-color screen visual 0)
:event-mask event-mask ))
(setq window-2 (clx:create-window
:parent window-1
:x window-2x :y window-2y
:width window-2w :height window-2h
:depth depth :border-width 4
:class '.input-output :visual visual
background (define-color screen visual 1)
:event-mask event-mask ))
©
(setq gc (clx:create-gcontext idrawable window-2
foreground (define-color screen visual 2)
background (define-color screen visual 1)
:font font ))

(setf (clx:wm-normal-hints window-1)
(clx:make—wm-size-hints :x 362 :y 282 :width 400 :height 300) )
(setf (clx:wm-name window-1) window-name)
(clx:map-window window-1)
(clx:map-window window-2)
;;The event loop — the core of an Xlib program
(clx:event-case (display)
(button-press (window)
(if (eq window window-1)
(progn
(clx:draw-image-glyphs window-2 gc 75 75 "Click HERE to exit")
nil )
t ) )
(:exposure (window)
(if (eq window window-2)
(clx:draw-image-glyphs window-2 gc 75 75 "Click here to exit") )
nil) ) )

(continued on next page)

4—6

Programming Overview of CLX

Example 4-1 (Cont.):
(D
©

Sample CLX Program

(clx:destroy-window window-1)
(clx:display-force-output display)

) )

O The clx:Open-display function establishes a connection betw een th e client
(the LISP program ) and the X server, and re tu rn s a CLX:DISPLAY object. See
C hapter 5 for more inform ation on displays and screens.
©

CLX buffers client requests and sends them to the server asynchronously. The
c l x :DISPLAY-f o r c e -o o t p u t function flushes th e buffer, forcing th e requested
ou tp u t to be displayed.

The keyword argum ents to th e c l x :c r e a t e -w i n d o w function specify
th e characteristics of th e c l x : w i n d o w object retu rn ed by the function.
CLX:c r e a t e -w i n d o w does not cause the window actually to appear on the
display. See C hapter 6 for m ore inform ation on windows.

The c l x :c r e a t e —g c o n t e x t function re tu rn s a c l x :Gc o n t e x t object w ith the
specified graphics characteristics. See C hapter 7 for details on graphics
contexts.

The : f o n t slot of the c l x :g c o n t e x t object determ ines w hich font th e program
uses to w rite text in w i n d o w -2. See C hapter 11 for m ore inform ation on
draw ing text. For a list of font nam es, see th e VMS DECwindows Guide to

XLib Programming: MIT C Binding.
©

The c l x :ALLOC-COLOR function uses the predefined DECwindows colors nam ed
D arkSlateB lue, LightGray, and Firebrick. For more inform ation on colors, see
C hapter 8. F or a list of predefined color nam es, see the VMS DECwindows

Guide to XLib Programming: MIT C Binding.

These functions provide h in ts to th e window m anager (th a t is, DECwindows)
as to w hat size and title the client would like its window to have. See
C hapter 6 for more inform ation on window m anagem ent functions.

The c l x :m a p -w i n d o w function places a M apRequest event in the server queue;
it does not actually m ake the window visible on the screen. See the following
steps and C hapter 6 for more inform ation.

The c l x :e v e n t -c a s e m acro loops until events occur (th a t is, events of the
types requested by the client in the : e v e n t -c a s e slot of a window). The
CLX:m a p -w i n d o w functions place : e x p o s u r e events in th e queue, so th a t clause
is executed first. C hapter 12 h a s more inform ation on events.

The CLX:c l o s e -d i s p l a y function unm aps th e window(s) and ends the
connection betw een the client and the server. See C hapter 5 for details.

Programming Overview of CLX 4-7

Chapter 5

Managing the Client-Server Connection

Before your client program can use a display, you m u st establish a connection
to the X server driving th a t display. Once you have established th is connection,
you can use the CLX m acros and functions discussed in th is chapter to get
inform ation about th e display. This chapter explains how to perform th e following
operations:
•

Open (connect to) th e display.

•

G et inform ation about the display and screen.

•

Send req u ests to the server.

•

Close (disconnect from) the display.

The chapter concludes w ith a general discussion of w h a t happens w hen the
connection to th e X server is closed.

5.1 Opening the Display
The first call a client m akes is to open a display. A fter opening a display, the
client can get inform ation from and send requests to th e server. To increase the
efficiency of th e client-server connection, CLX buffers client requests.
The c l x :OPEN-d i s p l a y function establishes a connection from the client to the
X server driving the specified display, and re tu rn s a c l x :d i s p l a y object. The
form at of th e CLX: o p e n -d i s p l a y function is:
CLX:OPEN-DISPLAY host &KEY :DISPLAY display PROTOCOL system
h ost

A string that specifies the name o f the host machine.

d isp la y

An integer that specifies the number o f the display. The default is 0.

system

A keyword that specifies the type o f network, either : DECNET or TCP. The
default is : DECNET.

The default value of zero for th e display arg u m en t corresponds to the default
screen on th e specified host. If th e call to CLX:o p e n -d i s p l a y is successful, the
function re tu rn s a CLX:d i s p l a y object; if not, it re tu rn s n i l .The function m ay
fail if th e h o st is unknow n or unreachable, or if you do not have access to the
host.
The following exam ple shows how to establish a connection to the server on
a m achine nam ed SM ITH and obtain some inform ation about the display and
screen.

Managing the Client-Server Connection

5-1

Lisp>

(setf display (clx:open-display "SMITH"))

#<XDisplay 104857 6 0
Lisp>

(setf screen (clx:display-default-screen display))

#<Screen 22120368>
Lisp>

(clx:display-vendor-name display)

"DECWINDOWS DigitalEquipmentCorp."
Lisp>

(clx:screen-width-in-millimeter screen)

346

The functions th a t re tu rn inform ation about c l x :d i s p l a y and c l x :s c r e e n objects
a re discussed in Section 5.2.

5.2 Getting Information About the Display and Screen
A fter opening a display, clients can get inform ation about the display itself, the
screens th e server is driving on th a t display, and the form at of im ages created on
those screens. The inform ation functions are listed in Tables 5—1 and 5—2.
Inform ation functions are useful for supplying argum ents to other CLX
routines. See P a rt IV for the syntax of inform ation functions. For examples
and descriptions of th e use of inform ation functions, see the exam ples throughout
P a rt III.
Table 5-1:

Information Functions for DISPLAY Objects

F u n c t io n

U se
w ith
SETF?

CLX:DISPLAY—BITMAP-FORMAT

The default CLX:BITMAP-FORMAT object for the
specified display.

CLX:DISPLAY-DEFAULT-SCREEN

The default CLX:SCREEN object for the display.

CLX:DISPLAY-ERROR-HANDLER

Yes

TBS.

CLX:DISPLAY-IMAGE-LSB-FIRST-P

T if the byte order for im ages is le a st significant
b it first or NIL if it is m ost significant bit first.

CLX:DISPLAY-MAX-KEYCODE

An integer that indicates the largest keycode value
transm itted by the X server.

CLX:DISPLAY-MAX-REQUEST-LENGTH

An integer that indicates the maximum length o f a
request accepted by the X server, in 4-byte units.

CLX:DISPLAY-MIN-KEYCODE

An integer that indicates the sm allest keycode
value transmitted by the X server.

CLX:DISPLAY-MOTION-BUFFER-SIZE

An integer that indicates the approximate size of
the X server’
s buffer containing the recent history
o f pointer motion.

CLX :DISPLAY-PIXMAP-FORMATS

A list of CLX :PIXMAP-FORMAT values th a t
correspond to the depth valu es of th e default
screen.

CLX:DISPLAY-PROTOCOL-MAJOR-VERSION

An integer that indicates the version number o f
the X protocol.

CLX:DISPLAY-PROTOCOL-MINOR-VERSION

An integer that indicates the release number of
the X protocol.

CLX:DISPLAY-RELEASE-NUMBER

An integer that indicates the release number of
the X server.

R e t u r n V alue

(continued on next page)

5-2

Managing the Client-Server Connection

Table 5-1 (Cont.):

Information Functions for DISPLAY Objects

F u n c t io n

U se
w ith
SE T F ?

CLX:DISPLAY-ROOTS

A list o f CLX: SCREEN objects that represent every
screen attached to the display.

CLX:DISPLAY-VENDOR-NAME

A string that contains the name o f the
im plem entor o f the X server.

Table 5-2:

R e t u r n V alue

Information Functions for CLX:SCREEN Objects

F u n c t io n

U se
w ith
SE TF ?

R e t u r n V alu e

CLX: SCREEN-BACKING-STORES

A keyword that specifies when the server saves

the contents of obscured windows: : WHEN-MAPPED,
:NOT-USEFUL, or :ALWAYS.
CLX:SCREEN-BLACK-PIXEL

The CLX:PIXEL value that produces black on this
screen.

CLX: SCREEN-DEFAULT-COLORMAP

The default CLX: COLORMAP of the specified screen.

CLX: SCREEN-DEPTHS

The depths supported by the display hardware, in
an association list whose elements have the form:

(depth visuals)
where depth is a CLX: IMAGE-DEPTH value and
visu a ls is a list o f CLX:VISUAL-INFO.
CLX: SCREEN-EVENT-MASK-AT-OPEN

A CLX: EVENT-MASK value that contains the event

types requested in the screen’
s root window.
CLX: SCREEN-HEIGHT

An integer that represents the height of the screen
in pixels.

CLX: SCREEN-HEIGHT-IN-MILLIMETERS

An integer that represents the height of the screen
in millimeters.

CLX: SCREEN-MAX-INSTALLED-MAPS

An integer that represents the maximum number of
colormaps that can be installed.

CLX: SCREEN-MIN- INSTALLED-MAPS

An integer that represents the number of colormaps
that can be guaranteed to be installed, regardless of
the number of entries allocated in each map.

CLX:SCREEN-ROOT

The root window of the specified screen.

CLX: SCREEN-ROOT-DEPTH

A CLX: IMAGE-DEPTH value that represents the
number of planes of the specified screen.

CLX: SCREEN-ROOT-VISUAL

An integer pointer to the default visual type of the
screen.

CLX: SCREEN-SAVE-UNDERS-P

T if the server saves the contents of windows that
the client windows obscure; otherwise NIL.

CLX:SCREEN-WHITE-PIXEL

The CLX:PIXEL value that produces white on this
screen.

CLX:SCREEN-WIDTH

An integer that represents the width of the screen
in pixels.

(continued on next page)

Managing the Client-Server Connection

5-3

Table 5-2 (Cont.):

Information Functions for CLX:SCREEN Objects

F u n ctio n

U se
w ith
SE TF ?

R e t u r n V alu e

CLX:SCREEN-WIDTH-IN-MILLIMETERS

An in t e g e r t h a t r e p r e s e n t s t h e width of t h e B creen
i n m illim e t e r s .

5.3 Sending Requests to the Server
CLX norm ally buffers client requests instead of sending individual requests to
the server as they are specified. This increases the efficiency of client-to-server
comm unication. The functions and macro listed in Table 5-3 allow you to control
how requests are output from the buffer.
Table 5-3:

Output Buffer Routines

R o u t in e

D e s c r ip t io n

CLX:DISPLAY-FORCE-OUTPUT

Flushes the buffer, that is, forces all requested
output to be displayed.

CLX:DISPLAY-FINISH-OUTPUT

Flushes the buffer and waits until the server has
received and processed all events, including errors.

CLX:DISPLAY-AFTER-FUNCTION

Specifies the function the client calls after processing
any protocol request.

CLX:WITH-DISPLAY

Causes the server to process requests synchronously.

The CLX:d is p l a y -a fter - function function can be used w ith s e t f .
W hile debugging a program , you m ay w ish to set this function to
CLX:d is p l a y - f i n i s h - output so th a t error m essages will appear im m ediately
after th e request th a t caused them . If you w an t to program interactively, set
th e function to c l x : d is p l a y -force - output so th a t o utput will be displayed
im m ediately after you request it. For example:
(setf (clx:display-after-function display) #'clx:display-force-output)

5.4 Closing the Display
CLX autom atically destroys windows and resources related to a process when
the process exits th e server. This m eans th a t clients usually do not have to close
th eir connection w ith a server explicitly. However, clients can explicitly close the
connection by using the CLX:cl o se - d isp l a y function. This function destroys all
windows associated w ith the display and all resources the client has allocated.
Its form at is:
CLX:CLOSE-DISPLAY display

w here display is a c l x : d isp l a y object th a t specifies the display to be closed.
References to resources (such as windows) associated w ith a display th a t has
been closed cause errors.

5-4

Managing the Client-Server Connection

W hen th e X server’s connection to a client is closed, eith e r by an explicit call to
CLX: close-display or by a process th a t exits, th e X server does the following:
•

D iscards all in p u t events selected by the client (see c l x :s e t -s e l e c t i o n -o w n e r
in C hapter 12).

•

Releases all active and passive grabs m ade by the client (see
CLX:UNGRAB-KEYBOARD, CLX:UNGRAB-POINTER, and CLX:UNGRAB-SERVER in

C hapter 12).
•

D eterm ines w hether to re ta in or destroy client resources after th e display is
closed (see c l x : s e t -c l o s e -d o w n -m o d e in C hapter 13).

If the server is to destroy all client resources, it does so as follows:
•

Exam ines each window in the client’s saveset to determ ine if it is a
subwindow, or child, of a window created by th e client. (The saveset is a
list of other clients’ windows; windows in th is list are called saveset windows.)
If a window is a subwindow, the X server rep aren ts the saveset window to
its closest ancestor so th a t it is no longer a child of a window created by the
client.

•

M aps th e saveset window if it is unm apped. The X server does th is even if
th e saveset window is not a subwindow of a window created by th e client.

•

Destroys all windows created by th e client, after exam ining each one in the
client saveset.

•

Frees each nonwindow resource (font, pixmap, cursor, colormap, and
GrContext) created by th e client.

•

Frees all colors a n d colormap entries allocated by the client.

Additional processing occurs w hen you log out of the process in which you invoked
CLX functions. See th e VMS DECwindows Guide to Xlib Programming: MIT C
Binding for details.

Managing the Client-Server Connection

5-5

Chapter 6

Working with Windows

CLX window routines allow client program s to create m ultiple windows and
define window size, location, and appearance on one or m ore screens. A window
m ay be input-only (in which case it is never visible on th e screen) or input-output.
A window is always clipped by its parent.
Conflicts betw een clients about displaying windows are handled by a window
m anager, which has final control over the size and placem ent of windows and, in
some cases, characteristics such as title bars and borders. The window m anager
also keeps clients informed about w hat it is doing w ith th eir windows. For
example, the window m anager m ay tell a client th a t one of its windows h as been
resized so th a t the client can reform at inform ation displayed in the window. The
default window m anager is DECwindows.
This chapter describes the following topics:
•

C reating and destroying windows

•

M apping and unm apping windows

•

Associating properties w ith windows

•

Com m unicating w ith th e window m anager

•

Exchanging properties betw een clients

•

Stacking windows

•

C hanging window attrib u tes

For m ore inform ation about X window types, hierarchy, and visibility, see the

VMS DECwindows Guide to XLib Programming: MIT C Binding.

6.1 Creating Windows
A fter opening a display, you can create windows. Note th a t creating a window
does not m ake it visible on th e screen. To be visible, a window m u st m eet the
following conditions: it m u st be input-output; it m u st be m apped; its ancestors
m u st be m apped; and it m u st not be completely u n d ern eath an o th er window.
M apping windows is explained in Section 6.3.
The clx : create -window function allows you to specify all th e characteristics of a
window, or to copy some a ttrib u tes from th e p a re n t window. Its form at is:
CLX:CREATE-WINDOW &KEY :PARENT :X :Y WIDTH :HEIGHT :DEPTH BORDER-WIDTH
BLASS :VISUAL BACKGROUND BORDER :GRAVITY
BIT-GRAVITY BACKING-STORE BACKING-PLANES
BACKING-PIXEL BAVE-UNDER BVENT-MASK

Working with Windows

6-1

:DO-NOT-PROPAGATE-MASK :OVERRIDE-REDIRECT
:COLORMAP :CURSOR

The values of the keyword argum ents specify th e a ttrib u tes of th e c l x :w i n d o w
object retu rn ed by th e c l x :c r e a t e -w i n d o w function, as described in Table 6-1.
U nless otherw ise noted, the keywords have no default values.
Table 6-1:

QLX:CREATE-WINDOW Keywords

: PARENT

A CLX: WINDOW object that specifies the parent of the
window being created.

:X and :Y

Integers that specify the X and Y coordinates of the topleft comer of the window, measured in pixels.

:WIDTH and : HEIGHT

Integers that specify the width and height of the window,
measured in pixels, but not including the border.

:DEPTH

An integer that specifies the number of bits per pixel. The
default value is 0.

.•BORDER-WIDTH

An integer that specifies the width of the window’
s border,
measured in pixels. The default value is 0.

: CLASS

: COPY, : INPUT-OUTPUT, or : INPUT-ONLY, specifying
whether the window can display output. The default
value is .-COPY, which means the same class as the parent
window.

:VISUAL

Either a CLX: VISUAL value or :COPY. The default value
is : COPY, specifying the same visual information as the
parent window.

:BACKGROUND

A CLX:PIXEL value, a CLX:PIXMAP value, :NONE,
: PARENT-RELATIVE, or NIL, specifying the background
color.

:BORDER

A CLX:PIXEL value, a CLX:PIXMAP value, or :COPY,
specifying the border color.

: GRAVITY

A CLX: WIN-GRAVITY value that specifies how the window
will be positioned after its parent is resized.

: BIT-GRAVITY

A CLX:BIT-GRAVITY value that specifies which region of
the window will be retained after it is resized.

:BACKING-STORE

:NOT-USEFUL, :WHEN-MAPPED, :ALWAYS, or NIL,
specifying when the server will maintain the contents
of the window.

:BACKING-PLANES

A CLX: PIXEL value or NIL, specifying which bit planes of
the window hold dynamic data that must be preserved in
:BACKING-STORE.

: BACKING-PIXEL

A CLX:PIXEL value or NIL, specifying the value to use in
planes not covered by : BACKING-PLANES.

: SAVE-UNDER

:ON or :OFF, specifying whether the server will save the
contents of windows obscured by the created window.

:EVENT-MASK

A CLX: EVENT-MASK value or NIL, specifying for which
events in this window the client requests notification from
the server.

:DO-NOT-PROPAGATE-MASK

A CLX: DEVICE-EVENT-MASK value or NIL, specifying
which events should not be propagated to ancestor
windows.

(continued on next page)

6—2 Working with Windows

Table 6-1 (Cont.):

CLX:CREATE-WINDOW Keywords

: OVERRIDE-REDIRECT

:ON or :OFF, specifying whether calls to map and
configure the window should override a request from
another client to redirect those calls.

: COLORMAP

An object of type CLX: COLORMAP, :COPY, or NIL,

specifying the colormap that best reflects the true colors
of the window.
: CURSOR

An object of type CLX: CURSOR, :NONE, or NIL, specifying

the cursor shape to be used when the pointer is in the
window.

Inform ation about the display is obtained from the p a re n t window. (See Table 5—1
for a complete list of display inform ation functions.)
Exam ple 6-1 shows the creation, on a m achine nam ed SMITH, of a window
whose paren t is the root; top-left corner is the top-left com er of the screen; w idth
and height are 200 pixels; and border is 1 pixel wide.
Example 6-1:

Creating a Window

Lisp> (setf ‘display* (clx:open-display "smith"))
#<XDisplay 13043164>
Lisp> (setf ‘screen* (clx:display-default-screen *display*))
#<Screen 13302544>
Lisp> (setf *root* (clx:screen-root ‘screen*))
#<Window 524395>
Lisp> (setf *window* (clx:create-window :parent ‘root* :x 0 :y 0
:width 200 :height 200
:border-width 1))
#<Window 12582913>
Lisp> (clx:map-window ‘window*)
Lisp> (clx:display-force-output ‘display*)

The final call to c l x :d i s p l a y -f o r c e -o u t p u t is necessary to m ake the window
visible.
Because no value w as supplied for th e b a c k g r o u n d argum ent, the window is
tran sp aren t. The window’s title, “No nam e,” is supplied by the DECwindows
Session M anager. The DECwindows Session M anager rep aren ts each client
window.

6.2 Destroying Windows
Destroying a window frees all storage allocated for th a t window object. If the
window is m apped, th e server notifies clients using the window th a t it has been
destroyed. The server also notifies clients of exposure events on windows formerly
obscured by destroyed windows. The c l x :d e s t r o y -w i n d o w function destroys a
specified window and all its subwindows; the c l x b e s t r o y -s u b w i n d o w s function
destroys all the subwindows of a p a re n t window.

Working with Windows

6-3

The format of the CLX:DESTROY- w i n d o w function is:
CLX:DESTROY-WIN DOW window
where window is the CLX:w i n d o w object that is destroyed.

The form at of the c l x :DESt r o y - s o b w i n d o w s function is:
CLX:DESTROY-SUBWINDOWS window
where window is the CLX:w i n d o w object whose subwindows are destroyed.

Normally, all windows belonging to a client are destroyed w hen th e client exits.
If your client uses windows created by another client, you can prevent them from
being destroyed by adding them to your saveset. The saveset is a list, which the
X server m aintains for each client, of windows created by other clients which
should be rem apped ra th e r th a n destroyed when those clients exit.
The CLX:a d d - t o -s a v e - s e t function adds th e specified window to your saveset. Its
form at is:
CLX:ADD-TO-SAVE-SET window
where window is a c l x :w i n d o w object.

The c l x :r e m o v e -f r o m -s a v e -s e t function removes a window from your saveset.
Its form at is:
CLX:REMOVE-FROM-SAVE-SET window

w here window is a c l x :w i n d o w object.
The window argum ent passed to the c l x :a d d -t o -s a v e - s e t and
c l x :r e m o v e -f r o m -s a v e - s e t functions mu s t have been created by some other

client or an error occurs.

6.3 Mapping and Unmapping Windows
M apping a window, if its ancestors are also m apped, allows i t to be viewed on the
screen. The window is also visible unless it is totally obscured by other windows.
CLX provides the c l x : m a p -w i n d o w function for m apping a single window, and the
c l x :MAP-s ü b w i n d o w s function for m apping m ultiple windows.
The form at of c l x :m a p -w i n d o w is:
CLX:MAP-WINDOW window
where window is the c l x :w i n d o w object that is mapped.

The form at of c l x :m a p -s u b w i n d o w s is:
CLX:MAP-SUBWINDOWS window
where window is the c l x -.w i n d o w object whose subwindows are mapped.

U nm apping a window rem oves it from th e screen, b u t leaves th e window object
itself intact. The c l x :u n m a p -w i n d o w function removes a single window; the
CLX:u n m a p -s u b w i n d o w s function rem oves all the subwindows of a p a re n t window.
See Section 6.2 for inform ation on deallocating storage for window objects.
The form at of c l x :u n m a p -w i n d o w is:
CLX:UNMAP-W!NDOW window

w here window is the c l x :w i n d o w object th a t is unm apped.

6—4 Working with Windows

The format of c l x :u n m a p -s u b w i n d o w s is:
CLX:UNMAP-SUBWINDOWS window
where window is the c l x :w i n d o w object whose subwindows are unmapped.

6.4 Associating Properties with Windows
CLX enables clients to associate additional d a ta w ith a window. This d a ta is
considered a property of the window. A lthough a property m u st be d a ta of only
one type, it can be stored in 8-bit, 16-bit, and 32-bit form ats. The indicators
for a property list in CLX are called atom s. Atoms m ay be passed as strings or
symbols and are always returned as keywords. For a list of predefined atom s, see
the VMS DECwindows Guide to Xlib Programming: MIT C Binding.
The c l x : change- property function allows you to set a new value for a window
property. Its form at is:
CLX:CHANGE-PROPERTY window property data type format
&KEY :MODE :START :END TRANSFORM
w in dow

The CLX:WINDOW object w hose properties are changed.

prop erty

A CLX: XATOM value that specifies the property to change.

d a ta

A sequence that specifies the new property data.

type

A CLX: XATOM value that defines the type of property to be changed.

fo rm a t

The data format size, either 8, 16, or 32.

:MODE

:REPLACE, :PREPEND, or : APPEND, specifying the m anner in which the
window’
s property list is to be changed. The default value is : REPLACE.

: START

An integer that defines the starting position w ithin the window’
s
property list. The default value is 0.

: END

An integer that specifies the last position w ith the window’
s property list,

or NIL.
: TRANSFORM

A function that is applied to each extracted element.

The values : start and :END affect sub-sequences extracted from data.
The c l x : get -property function re tu rn s inform ation about a window property. Its
form at is:
CLX:GET-PROPERTY window property
&KEY TYPE :START :END :DELETE-P :RESULT-TYPE TRANSFORM
w in dow

The CLX:WINDOW object w hose property is bein g queried.

property

A CLX: XATOM value that specifies the property being queried.

: TYPE

A CLX:XATOM value that specifies the type of the property, or NIL.

: START

An integer that defines the starting position within the window’
s
property list. The default value is 0.

: END

An integer that specifies the last position with the window’
s property
list, or NIL.

:DELETE-P

A CLX: BOOLEAN value that determines whether the specified property

will be deleted.

:RESULT-TYPE

The type specifier of the value returned by the function. The default
type is 'LIST.

Working with Windows

&-5

: TRANSFORM

A function that is applied to each returned integer.

The c l x : get -property function re tu rn s a sequence of four values: the property
data, its type, its form at, and the num ber of bytes rem aining in the property if a
p artial read operation w as performed.
The CLX:l i s t -p r o p e r t ie s function re tu rn s all the properties defined for a
specified window. Its form at is:
CLX:LIST-PROPERTIES w in d ow &KEY :RESULT-TYPE
w in d ow

A CLX:WINDOW object.

: RESULT-TYPE

The type specifier of the value returned by the function. The default
type is ' LIST.

The function retu rn s a sequence of keywords nam ing th e properties of the
window argum ent. Atoms are alw ays retu rn ed as keywords.
The CLX:rotate - p r o p e r t ie s function ro tates the properties of a specified window
and generates a :PROPERTY-n o t if y event in th a t window. The form at of the
CLX:ROTATE-PROPERTIES function is:
CLX:ROTATE-PROPERTIES w in d ow p ro p e rtie s &OPTIONAL d elta
w in dow

The CLX: WINDOW object w hose properties are rotated.

p roperties

A sequence o f CLX: XATOM values. Each value specifies a property to be
rotated.

d elta

An integer that specifies the direction and amount of rotation. The default is

1.
NOTE
A positive value for delta ro tates the properties to th e left, and a
negative value ro tates right. This is the opposite of th e X protocol.
The CLX:delete - property function rem oves a specified property from the
property fist of a window. Its form at is:
CLX:DELETE-PROPERTY w in d ow p ro p e rty
w in dow

The CLX: WINDOW w hose properties are deleted.

property

A CLX: XATOM that specifies the property to be deleted.

Given an integer resource-id, th e clx : atom-name function re tu rn s a n atom nam e
as a keyword. Its form at is:
CLX:ATOM-NAME d is p la y a to m -id
d isp la y

A CLX:DISPLAY object.

atom -id

An integer.

Given a keyword, the CLX:FIND-atom an d c l x : intern -atom functions re tu rn the
integer resource-id of th a t atom . The form at of cl X:FIND-atom is:
CLX:FIND-ATOM d is p lay n a m e

6-6

d isp la y

A CLX: DISP LAY object.

nam e

A CLX: XATOM value.

Working with Windows

The form at of c l x : intern - atom is:
CLX:INTERN-ATOM d isplay n a m e
d isp la y

A CLX:DISPLAY object.

nam e

A CLX: XATOM value.

Both functions retu rn an integer corresponding to the atom.

6.4.1

Communicating with the Window Manager
CLX provides two structures, c l x :Wm -h i n t s and c l x :w m -s i z e -h i n t s , to enable
clients to communicate h in ts to the window m anager about th e following window
properties:
•

Pixm aps used to define icons

•

Window and icon nam es

•

Position and size of windows

•

Initial state of windows

•

In p u t th a t windows accept

•

Com m ands used to s ta rt th e application

•

N am es used to retrieve application resources

All accessor functions for these two stru ctu res are valid s e t f places so th a t you
can set individual properties of a window. The functions th a t re tu rn inform ation
about window m anager properties are described in Tables 6—2 and 6-3. Unless
otherw ise noted, a null value indicates th a t the property h a s not been defined for
th e window.
Table 6-2:

Information Functions for CLX:WM-HINTS Objects

F u n c t io n N a m e

U se
w ith
SETF?

CLX:WM-HINTS-INPUT

Yes

:ON if the client relies on the window m anager to get
keyboard input; : OFF if it does not.

CLX: WM-HINTS-INITIAL-STATE

Yes

A keyword that defines how the window should appear in its
initial configuration. Possible values are:

R e t u r n V alu e

DONT-CARE

Client is not interested in the initial state

NORMAL

Initial state used m ost often

ZOOM

Window starts zoomed

ICONIC

Window starts as an icon

inactive

Window is Beldom used

CLX:WM—HINT S- 1CON-PIXMAP

Yes

The CLX:PIXMAP value used to create the window icon.

CLX:WM-HINTS-ICON-WINDOW

Yes

The CLX: WINDOW object to be used as an icon.

CLX:WM-HINTS-ICON-X

YeB

An integer that specifies the initial X coordinate o f the icon.

CLX:WM-HINTS-ICON-Y

Yes

An integer that specifies the initial Y coordinate of the icon.

(continued on next page)

Working with Windows

6-7

Table 6-2 (Cont.):

Information Functions for CLX:WM-HINTS Objects

F u n c t io n N a m e

U se
w ith
SETF?

CLX:WM-HINTS-ICON-MASK

Yes

A CLX: PIXMAP value that specifies which pixels of the icon
pixmap are used to create the icon.

CLX:WM-HINTS-WINDOW-GROUP

Yes

A CLX: RESOURCE-ID that identifies a group of other

R e tu rn V alue

windows to which the specified window belongs.
CLX:WM-HINTS-FLAGS

Yes

An integer that specifies which elem ents o f the data
structure are defined.

The DECwindows window m anager overrides m ost calls to resize and relocate
windows. To prevent this, create the window w ith : OVERRIDE-REDIRECT set to
: ON. M ost applications, however, can use the c l x :WM-s i z e - h in t s stru ctu re to
work w ith the window m anager.
Table 6-3:

Information Functions for CLX:WM-SIZE-HINTS Objects
U se
w ith
SETF?

F u n c t io n N a m e

R e t u r n V alue

CLX:WM-SIZE-HINTS-USER-SPECIFIEDPOSITION-P

Yes

T if the user wants the window moved to the
specified X and Y position; otherwise NIL. The
default value is T.

CLX:WM-SIZE-HINTS-USER-SPECIFIEDSIZE-P

Ye8

T if the user wants the window resized; otherwise
NIL. The default value is T.

CLX:WM-SIZE-HINTS-X

Yes

An integer that specifies the X coordinate of the
window position.

CLX:WM—SIZE-HINTS-Y

Yes

An integer that specifies the Y coordinate of the
window position.

CLX:WM-SIZE-HINTS-WIDTH

Yes

An integer that specifies the width of the window.

CLX:WM-SIZE-HINTS-HEIGHT

Yes

An integer that specifies the height o f the window.

CLX:WM-SIZE-HINTS-MIN-WIDTH

Yes

An integer that specifies the sm allest useful width
o f the window.

CLX:WM-SIZE-HINTS-MIN-HEIGHT

Yes

An integer that specifies the sm allest useful height
o f the window.

CLX:WM-SIZE-HINTS-MAX-WIDTH

Yes

An integer that specifies the largest useful width
o f the window.

CLX:WM-SIZE-HINTS-MAX-HEIGHT

Yes

An integer that specifies the largest useful height
o f the window.

CLX:WM-SIZE-HINTS—WIDTH-INC

Yes

An integer that specifies the increments by which
the width o f the window can be resized.

CLX:WM-SIZE-HINTS-HEIGHT-INC

Yes

An integer that specifies the increments by which
the height o f the window can be resized.

CLX:WM-SIZE-HINTS-MIN-ASPECT

Yes

A number that specifies the sm allest aspect ratio
o f the window.

CLX:WM-SIZE-HINTS-MAX-ASPECT

Yes

A number that specifies the largest aspect ratio of
the window.

Table 6 -4 lists additional window m anager property functions defined in CLX.
N ot all th e functions can be used w ith s e t f .

6—8 Working with Windows

Table 6-4:

Additional Window Manager Property Functions

N am e

U se
w ith
SETF?

D e s c r ip tio n

CLX:GET-WM-CLASS

Returns the class of a specified window.

CLX:ICON-SIZES

Yes

Returns the recom m ended sizes for a window’
s icon.

CLX: SET-WM-CLASS

Sets the class of a specified window.

CLX:WM-HINTS

Yes

Returns the values for the window m anager hints.

CLX:WM-ICON-NAME

Yes

Returns the name of the icon for a specified window.

CLX:WM-NAME

Yes

Returns the name o f a window.

CLX:WM-NORMAL-HINTS

Yes

Returns recom m ended values for the size and location o f a
window in its m ost frequent initial state.

CLX:WM-ZOOM-HINTS

Yes

Returns the recom m ended size and location for a window in
the zoom ed state.

6.4.2

Exchanging Properties Between Clients
Properties th a t are global to the server are called selections and m ay be
exchanged betw een clients. An example is tex t cut from one window and
pasted into another. The text cut in window A is a property owned by client
A. O w nership of th e property transfers to client B, who th en pastes the tex t into
window B.
Clients can determ ine th e owner of a selection by calling the
c l x : s e l e c t io n - owner function. Its form at is:
CLX:SELECTION-OWNER display selection
d isp la y

A CLX: DISPLAY object.

selection

The CLX: XATOM value that identifies the selection.

The c l x : s e l e c t io n - owner function re tu rn s the c l x : window object th a t
currently owns the specified selection, or n il if no window owns the
selection. C lients establish ownership of a selection by using the setf form
of CLX:SELECTION-OWNER.
The c l x : convert - se l e ct io n function asks the owner of a selection to convert it
to a p articu lar d a ta type. Its form at is:
CLX:CONVERT-SELECTION selection type requestor &OPTIONAL property time
selection

The CLX: XATOM value of the requested selection.

type

A CLX: XATOM value.

requestor

A CLX:WINDOW object.

property

A CLX:XATOM value, or NIL.

tim e

A CLX:TIMESTAMP value.

C lients request selections and notify other clients of them by using events. For
inform ation about using events to request and convert selections, and to notify
clients of them , see C hapter 12. For style guidelines about m aking selections, see
the XUI Style Guide.

Working with Windows

6-9

6.5 Stacking Windows
CLX provides functions th a t allow you to perform th e following operations:
•

Move a window to the top or bottom of the stacking order.

•

Find the p a re n t and children of a window.

•

Change the p a re n t of a window.

The c l x :c i r c u l a t e -w i n d o w -u p function raises to th e top of the stacking order the
lowest m apped window (if any) th a t is obscured by a sibling. Its form at is:
CLX:CIRCULATE-WINDOW-UP window
where w i n d o w is the clx :window object that is placed on the top of the stacking
order.

The c l x :c i r c u l a t e -w i n d o w -d o w n function lowers to the bottom of th e stacking
order the highest m apped window (if any) th a t obcures a sibling. Its form at is:
CLX:CIRCULATE-WINDOW-DOWN window
where w i n d o w is the clx :window object that is shuffled to the bottom of the
stacking order.

W ith both circulate functions, exposure events are generated in form erly obscured
windows.
You can find a window’s position in the hierarchy by calling th e CLX:q u e r y -t r e e
function. Its form at is:
CLX:QUERY-TREE window &KEY :RESULT-TYPE
w indow

A CLX:WINDOW object.

:RESULT-TYPE

The type specifier of the first value returned by the function. The
default type is 'LIST.

The CLX:query-tree function re tu rn s th re e values: a sequence of clx : window
objects, listing th e children of th e window; th e p a re n t window; and the root
window.
The c l x :r e p a r e n t -w i n d o w function changes the p a re n t of a window. Its form at
is:
CLX:REPARENT-WINDOW window parent x y
w indow

The CLX: WINDOW object whose parent is changed.

p a re n t

The CLX: WINDOW object that is the new parent of w indow .

x and y

Integers that specify the X and Y coordinates of the top left comer of the
window relative to the new parent.

6.6 Changing Window Attributes
M any of th e accessor functions for CLX: w i n d o w objects m ay be used with s e t f
so th a t you can change a window’s a ttrib u te s after you have created it. The
functions th a t re tu rn inform ation about windows are fisted in Table 6-5, w ith an
explanation of th eir re tu rn value and w hether they can be used w ith SETF.

6-10

Working with Windows

Table 6-5:

Information Functions for CLX:WINDOW Objects

F u n c t io n N a m e

U se
w ith
SETF?

R e t u r n V alue

CLX:WINDOW-AIL-EVENT-MASKS

CLX:MASK32.

CLX:WINDOW-BACKING-PIXEL

Yes

A CLX:PIXEL value or NIL, specifying the value to
use in planes not covered by :BACKING-PLANES.

CLX:WINDOW-BACKING-PLANES

Yes

A CLX:PIXEL value or NIL, specifying which

bit planes hold data that must be preserved in
:BACKING-STORE.
CLX:WINDOW-BACKING-STORE

Yes

:NOT-USEFUL, :WHEN-MAPPED, or :ALWAYS.

CLX:WINDOW-BIT-GRAVITY

Yes

A CLX: WIN-GRAVITY value that defines how the

contents of the window should be moved when it is
resized.
CLX:WINDOW-CLASS

The class o f the window, either : INPUT-OUTPUT or

CLX:WINDOW-COLORMAP

Yes

The CLX: COLORMAP that best reflects the colors of the
window, or : COPY if the colormap is copied from the
parent.

CLX:WINDOW-COLORMAP-INS TALLED-P

A CLX: BOOLEAN value that indicates whether a

: INPUT-ONLY.

colormap is installed.
CLX:WINDOW-DISPLAY

The CLX:DISPLAY object on which the window
appears.

CLX:WINDOW-DO-NOT-PROPAGATE-MASK

Yes

A CLX: MASK32 value that specifies which events

should not be propagated to ancestor windows.
CLX:WINDOW-EQUAjj

A CLX: BOOLEAN value that indicates whether two

windows are the same window.
CLX:WINDOW-EVENT-MASK

Yes

A CLX:MASK32 value that defines which types of

events occurring in the window should be reported to
the client.
CLX:WINDOW-GRAVITY

A CLX: WIN-GRAVITY value that defines how the

server should reposition the window when its parent
is resized.
CLX:WINDOW-ID

An integer pointer to the C LX: WINDOW object.

CLX: WINDOW-MAP-STATE

T h e v isib ility sta tu s o f th e window, on e o f : UNMAPPED,

:UNVIEWABLE, or :VIEWABLE.
CLX:WINDOW-OVERRIDE-REDIRECT

Yes

:ON or :OFF, specifying whether requests to map and
configure the window should override a request from
another client to redirect those calk.

CLX:WINDOW-P

A CLX: BOOLEAN value that indicates whether its

argument is a CLX: WINDOW object.
CLX:WINDOW-SAVE-UNDER

Yes

: ON or : OFF, specifying whether the server will save
the contents of windows obscured by the created
window.

CLX:WINDOW-VISUAL

INTEGER.

Table 6-6 lists additional functions th a t m ay be used w ith setf b u t th a t m ay not
be called.

Working with Windows

6-11

Table 6-6:

SETF Functions for CLX:WINDOW Objects

F u n c t io n N a m e

T y p e o f V alue

CLX:WINDOW-BACKGROUND

Specifies the background color; m ay be NIL or :NONE,

CLX:WINDOW-BORDER

An integer, NIL, :COPY, or a CLX:PIXMAP value that defines
the window border.

CLX:WINDOW-CURSOR

A CLX:CURSOR object that specifies the cursor shape to be used

CLX:WINDOW-PRIORITY

:ABOVE, :BELOW, : TOP-IF, :BOTTOM-IF, or :OPPOSITE.

: PARENT-RELATIVE, an integer, or a CLX:PIXMAP value.

when the pointer is in the window, or :NONE.

Exam ple 6 -2 shows how to change th e background color of a window. The
variables »w i n d o w *, »s c r e e n *, and »d i s p l a y * were assigned in Exam ple 6-1.
Example 6-2:

Changing Window Attributes

Lisp> (setf (clx:window-background »window»)
(clx:screen-black-pixel »screen»))
252
Lisp> (clx:clear-area »window»)
Lisp> (clx:display-force-output »display»)

Some components of th e c l x : w i n d o w stru ctu re have no accessor function. These
a ttrib u tes can be identified, and in some cases set, w ith the functions listed in
Table 6-7. (A draw able can be either a window or a pixmap.)
Table 6-7:

Information Functions for CLX:DRAWABLE Objects

F u n c t io n N a m e

U se
w ith
SETF?

CLX.-DRAWABLE-BORDER-WIDTH

Yes

An integer that represents the width of the drawable’
s
border in pixels.

CLX:DRAWABLE-DEPTH

An integer that represents the number of planes in the
drawable.

CLX:DRAWABLE-HEIGHT

Yes

An integer that represents the height of the drawable in
pixels.

CLX:DRAWABLE-ROOT

A CLX:DRAWABLE object that represents the root of the
drawable.

CLX:DRAWABLE-WIDTH

Yes

An integer that represents the width of the drawable in
pixels.

CLX:DRAWABLE-X

Yes

An integer that represents the X coordinate of the top left
corner of the drawable, measured in pixels from the origin of
its parent.

CLX:DRAWABLE-Y

Yes

An integer that represents the Y coordinate of the top left
corner of the drawable, measured in pixels from the origin of
its parent.

6-12

Working with Windows

R e tu r n V alue

The CLX: wi th - state m acro coerces m ultiple window queries and changes into as
few protocol requests as possible, thereby im proving perform ance. Its form at is:
CLX:WITH-STATE drawable {body}'
draw able

The CLX: WINDOW or CLX: PIXMAP object whose attributes are being accessed
or set.

body

LISP forms to be executed.

The body is not surrounded by a c l x :WITH-d isp l a y macro. For more inform ation,
see the description in P a rt IV.

Working with Windows

6-13

Chapter 7

Defining Graphics Characteristics

In CLX, graphics characteristics, such as line w idth and style, are stored in
CLX:g c o n t e x t structures. Clients specify a GContext to be used w hen draw ing
graphics objects. This chapter describes how to define graphics characteristics
prior to draw ing objects. The following procedures are covered:
•

C reating a graphics context

•

Q uerying and setting GContext components

•

Copying and freeing GContexts

•

U sing GContexts efficiently

C hapter 9 describes how to draw graphics objects. C hapter 11 describes how to
display text.

7.1 Creating a Graphics Context
CLX provides default values for all graphics characteristics. Clients create
a GContext by calling the c l x :c r e a t e -g c o n t e x t function. For all GContext
components, a value of n i l causes th e default GContext value to be used.
The form at of th e c l x :c r e a t e -g c o n t e x t function is:
(CLX:CREATE-GCONTEXT &KEY :DRAWABLE FUNCTION :PLANE-MASK FOREGROUND
BACKGROUND LINE-WIDTH LINE-STYLE :CAP-STYLE
JOIN-STYLE FILL-STYLE FILL-RULE :ARC-MODE :TILE
:STIPPLE :TS-X :TS-Y FONT :SUBWINDOW-MODE
:EXPOSURES :CLIP-X :CLIP-Y BLIP-MASK
BLIP-ORDERING :DASH-OFFSET BASHES :CACHE-P)

w here th e values of th e keyword argum ents specify th e graphics characteristics of
a window. Table 7-1 explains the keyword argum ents to CLX: c r e a t e -GCONTEXT.

Defining Graphics Characteristics

7-1

Table 7-1:

CLX:CREATE-GCONTEXT Keywords

K eyw ord

V alu e

:DRAWABLE

A CLX: DRAWABLE object. This argument is required.

: FUNCTION

A CLX: LOGI CAL-OP value (see Table 7-2) that defines how the
server computes pixel values when the client updates a section of
the screen. The default operation is : GX-COPY.

:PLANE-MASK

An integer that defines the planes on which the server performs the
bitwise computation of pixels defined by the value of : FUNCTION.
The default plane mask is all Is.

:FOREGROUND and
:BACKGROUND

CLX:PIXEL values that specify the foreground and background
colors. The default values are 0 and 1, respectively.

:LINE-WIDTH

An integer that defines the width of a line, in pixels. The default
value is 0.

:LINE-STYLE

A keyword that specifies which sections of a line the server
draws. The possible values are : SOLID (the default), :DASH,
and :DOUBLE-DASH.

: CAP-STYLE

A keyword that specifies how the server draws the endpoints of
a line. The possible values are :BUTT (the default), :NOT-LAST,
:ROUND, and :PROJECTING.

: JOIN-STYLE

A keyword that specifies how the servers draw corners for wide
lines. The possible values are :MITER (the default), .-ROUND, and
:BEVEL.

:FILL-STYLE

A keyword that specifies the contents of the source for line, text,
and fill operations. The possible values are : SOLID (the default),
:TILED, :OPAQUE-STIPPLED,and : STIPPLED.

:FILL-RULE

A keyword that specifies how the server computes which points are
inside when filling a polygon. The possible values are : EVEN-ODD
(the default) and :WINDING.

:ARC-MODE

A keyword that specifies how the server connects the endpoints
of an arc. The possible values are :PIE-SLICE (the default) or
: CHORD.

: TILE and
: STIPPLE

The CLX:PIXMAP objects used for tile and stipple operations,
respectively. The default pixmaps are of unspecified size, filled with
the foreground pixel for tiling but Is for stippling.

: TS-X and
: TS-Y

Integers that define the X and Y coordinates of the origin for tile
and stipple operations. The default values are both 0.

:FONT

A CLX: FONTABLE that defines the font used in text operations.
Using a string for the : FONT component will cause an implicit call
to CLX:OPEN-FONT.

: SUBWINDOW-MODE

A keyword that specifies whether inferior windows clip superior
windows. The possible values are : CLIP-BY-CHILDREN (the
default) and : INCLUDE-INFERIORS.

:EXPOSURES

A keyword that specifies whether the server informs the client when
the contents of a window are lost. The possible values are : ON (the
default) and :OFF.

: CLIP-X and
: CLIP-Y

Integers that define the X and Y coordinates of the origin for clip
operations. The default values are both 0.

(continued on next page)

7-2

Defining Graphics Characteristics

Table 7-1 (Cont.):

CLX:CREATE-GCONTEXT Keywords

K eyw ord

V alu e

: CLIP-MASK

A CLX:PIXMAP or CLX:RECT-SEQ value that the server uses to
restrict write operations to the drawable. The default is no clip
mask.

:CLIP-ORDERING

A hint to the server that im proves performance o f clip operations.
The possible values are : UNSORTED, :Y-SORTED, :YX-SORTED, and

:YX-BANDED.
: DASH-OFFSET

An integer that defines the pixel within the dash length sequence
(specified by the : DASHES keyword) at which the server starts
draw ing a dashed line. The default is 0.

: DASHES

An integer or a sequence o f integers that defines the length, in
pixels, o f each section o f a dashed line. The default is the list (44).

: CACHE-P

A CLX : BOOLEAN value that specifies whether the graphics context
is to be cached locally by CLX. The default is T.

Table 7-2 lists th e operations th a t m ay be specified for the : f u n c t i o n component
of a c l x :g c o n t e x t structure.
Table 7-2:

CLX:LOGICAL-OP Values

K eyw ord

D e s c r ip t io n

:GX-CLEAR

:GX-AND

src AND d st

:GX-AND-REVERSE

src AND NOT d st

:GX-COPY

src

:GX-AND-INVERTED

(NOT src) AND d st

:GX-NOOP

d st

:GX-XOR

src XOR d st

:GX-OR

src OR d st

:GX-NOR

(NOT src) AND NOT d st

:GX-EQUIV

(NOT src) XOR d st

:GX-INVERT

NOT d s t

:GX-OR-REVERSE

src OR NOT d s t

GX-COPY-INVERTED

NOT src

:GX-OR-INVERTED

(NOT src) OR d st

:GX-NAND

(NOT src) OR NOT d st

:GX-SET

The screen the client is updating is the destination (dst). The graphics object
th a t th e client is draw ing on th e screen is th e source (src). The keyword value
specifies how th e server com putes new bits from th e existing destination bits and
the source bits. The default (and m ost common) logical function is specified by
:GX-COPY, which uses only th e source bits to update th e screen.

Defining Graphics Characteristics

7—3

7.2

Querying and Setting GContext Components
Objects of type c l x :g c o n t e x t are retu rn ed by the c l x :c r e a t e -g c o n t e x t function
(see Section 7.1) and are passed to the draw ing functions (see C hapter 9).
Table 7-3 lists th e functions th a t re tu rn inform ation about c l x :g c o n t e x t objects,
w ith descriptions of th eir re tu rn values and w hether they can be used w ith s e t f .

Table 7-3:

Information Functions for CLX:GCONTEXT Objects

F u n c t io n N a m e

U se
w ith
SETF?

CLX:GCONTEXT-ARC-MODE

Yes

The method used to join the endpoints o f an arc, either
: CHORD or :PIE-SLICE.

CLX:GCONTEXT-BACKGROUND

Yes

A CLX:PIXEL value that specifies the background color.

C LX:GCONTEXT-CACHE-P

Yes

A C LX:BOOLEAN value that indicates whether the structure
is stored locally by CLX.

CLX:GCONTEXT-CAP-STYLE

Yes

The m ethod used to draw the endpoints o f lines. The
possible values are :BUTT, :NOT-LAST, :ROUND, and
:PROJECTING.

CLX:GCONTEXT-CLIP-MASK

Yes

The m ask used to restrict write operations, either :NONE or
a CLX:PIXMAP or CLX:RECT-SEQ value.

CL X :GCONTEXT-CLIP-ORDERING

Yes

:UNSORTED, :Y-SORTED, :YX-SORTED, or :YX-BANDED.

CLX:GCONTEXT-CLIP-X

Yes

The integer X coordinate of the origin for the clip mask.

CL X :GCONTEXT-CLIP-Y

Yes

The integer Y coordinate of the origin for the clip mask.

CLX:GCONTEXT-DASHES

Yes

An integer or list o f integers. Each integer specifies the
length o f a dash or a gap in a line drawn with :LINE-STYLE
set to : DASH or : DOUBLE-DASH.

CLX:GCONTEXT-DASH-OFFSET

Yes

An integer index into the dashes list.

CLX:GCONTEXT-DISPLAY

The CLX:DISPLAY object on which the G Context was
created.

CLX:GCONTEXT-EQUAL

A CLX: BOOLEAN value that indicates whether the predicate’s
two arguments are the same GContext.

CLX:GCONTEXT-EXPOSURES

Yes

: ON when the server processes exposure events for the
window, otherwise :OFF.

CLX:GCONTEXT-FILL-RULE

Yes

The m ethod used to determine which pixels are “
inside”a
shape being filled, either : EVEN-ODD or : WINDING.

CLX:GCONTEXT-FILL-STYLE

Yes

The method used to fill a shape. The possible values are
: SOLID, : TILED, : OPAQUE-STIPPLED, and : STIPPLED.

CLX:GCONTEXT-FONT

YeB

A CLX:FONTABLE value that specifies the font to be used
when displaying text.

CLX:GCONTEXT-FOREGROÜND

Yes

A CLX:PIXEL value that specifies the foreground color.

CLX:GCONTEXT-FUNCTION

Yes

A CLX: LOG ICAL-OP value (see Table 7-2) that specifies the
m ethod used to combine bits.

CLX:GCONTEXT-ID

The integer resource-id of the GContext.

CLX:GCONTEXT-JOIN-STYLE

Yes

The m ethod used to join lines and line segments. The
possible values are :MITER, : ROUND, and :BEVEL.

R e tu rn V alue

(continued on next page)

7-4

Defining Graphics Characteristics

Table 7-3 (Cont.):

Information Functions for CLX:GCONTEXT Objects

F u n c t io n N a m e

U se
w ith
SETF7

CLX:GCONTEXT-LINE-STYLE

Yes

The method used to draw lines. The possible values are
:SOLID, :DASH, and : DOUBLE-DASH.

CLX:GCONTEXT-LINE-WIDTH

Yes

An integer that specifies the width o f a line in pixels.

CLX:GCONTEXT-P

A C LX:BOOLEAN value that indicates whether the argum ent
is o f type CLX: GCONTEXT.

CLX: GCONTEXT-PLANE-MASK

Yes

An integer that specifies the planes on which graphics
objects are drawn.

CLX: GCONTEXT-STIPPLE

Yes

The CLX:PIXMAP value used for stippling operations.

CLX: GCONTEXT-SUBWINDOW-MODE

Yes

A keyword that indicates whether children clip
their ancestors, either : CLIP-BY-CHILDREN or
: INCLUDE-INFERIORS.

CLX: GCONTEXT-TILE

Yes

The CLX:PIXMAP value used for tiling operations.

CLX:GCONTEXT-TS-X

Yes

An integer that specifies the X coordinate o f the origin for
tile and stipple operations.

CLX:GCONTEXT-TS-Y

Yes

An integer that specifies the Y coordinate o f the origin for
tile and stipple operations.

R e tu r n V alue

GContext components can also be set tem porarily by using the
CLX:WITH-GCONTEXT m acro. See Section 7.4 for inform ation on
CLX:WITH-GCONTEXT.

7.3 Copying and Freeing GContexts
In addition to creating a graphics context, clients can copy defined characteristics
from one c l x :g c o n t e x t stru ctu re into another. The CLX:COPY-GCONTEXT function
copies all components of the source GContext into the destination GContext. Its
form at is:
(CLX:COPY-GCONTEXT source destination)
source

The CLX:GCONTEXT object to copy from.

d estin ation

The CLX:GCONTEXT object to copy into.

The CLX: c o p y -g c o n t e x t -c o m p o n e n t s function copies only specified components
into the destination GContext. Its form at is:
(CLX:COPY-GCONTEXT-COM PON ENTS source destination &REST keys)
source

The CLX:GCONTEXT object to copy from.

d estin ation

The CLX:GCONTEXT object to copy into.

keys

Keywords that specify which components are copied.

The keyword argum ents correspond to those listed for the CLX: c r e a t e - g c o n t e x t
function in Section 7.1, Table 7-1, except for :DRAWAb l e .
W hen a graphics context is no longer needed, you should deallocate it by calling
th e c l x :f r e e -g c o n t e x t function in th e following format:
(CLX:FREE-GCONTEXT gcontext)

•where g c o n t e x t is the clx:gcontext object whose m em ory is to be deallocated.
Defining Graphics Characteristics

7-5

7.4 Using GContexts Efficiently
Changing GContext components frequently can seriously degrade performance, as
the server m u st revalidate a GContext w henever a client redefines it. Grouping
server requests th a t identify th e same window and GContext will improve
performance. W hen graphics characteristics need to be changed frequently,
creating a new GContext is m ore efficient th an redefining a n existing one. Clients
using th e DECwindows server should create no m ore th a n 50 GContexts.
W hen th e : c a c h e -p component is true, which is th e default, CLX stores the
GContext locally to the client so th a t server requests a re batched. Component
changes (by m eans of s e t f and w i t h -g c o n t e x t ) are alw ays deferred regardless
of the cache mode, and are sent over the protocol only w hen required by a local
operation or by an explicit call to CLX : f o r c e -g c o n t e x t -c h a n g e s .
The form at of th e CLX:f o r c e -g c o n t e x t -c h a n g e s function is:
(CLX:FORCE-GCONTEXT-CHANGES gcontext)

w here gcontext is the c l x :g c o n t e x t object whose components are changed.
The c l x :w i t h -g c o n t e x t m acro changes GContext com ponents w ithin the dynamic
scope of th e body.
(CLX:WITH-GCONTEXT gcontext
&KEY :FUNCTION :PLANE-MASK :FOREGROUND :BACKGROUND :LINE-WIDTH
:LINE-STYLE :CAP-STYLE :JOIN-STYLE :FILL-STYLE :FILL-RULE ARC-MODE
:TILE :STIPPLE :TS-X :TS-Y :FONT :SUBWINDOW-MODE EXPOSURES
:CLIP-X :CLIP-Y :CLIP-MASK :CLIP-ORDERING :DASHES :DASH-OFFSET
&BODY forms)
gcontext

The CLX: GCONTEXT object whose components are changed.

: FUNCTION . . . The keyword arguments specify the components of gcontext that are
changed.
form s

LISP form s to be executed while the changes to the graphics context are
in effect.

The body is not surrounded by a CLX:WITH-DISPLAY. If :CACHE-P is NIL or some
component s ta te s a r e unknown, c l x : w i t h - g c o n t e x t im p le m e n t s sa v e/restore b y
creating a tem porary GContext and using c l x :COPY-g c o n t e x t - c o m p o n e n t s to
copy components to it and from it.

7-6

Defining Graphics Characteristics

Chapter 8

Using Color

Color is a n a ttrib u te of both windows and graphics objects. D epending on display
hardw are, clients can define color as black or white, as shades of gray, or as
a spectrum of hues. For a detailed description of color definitions, including
VAXstations and the visual types they support, see the VMS DECwindows Guide

to Xlib Programming: MIT C Binding.

This chapter introduces m anaging color w ith CLX and describes how to share and
allocate color resources; the following topics are covered:

8.1

•

Pixels and colormaps

•

M atching color requirem ents to screen types

•

S haring color resources

•

Allocating colors for exclusive use

•

Storing color values

•

Freeing color resources

•

Q uerying colormap entries

Pixels and Colormaps
The color of a window or graphics object depends on the values of the pixels
th a t constitute it. The num ber of bits associated w ith each pixel determ ines the
n um ber o f p ossib le pixel values. M onoch rom e screen s have one bit p er pixel,

w hich gives two possible pixel values, black and white. On a monochrome screen,
all bits th a t define an image reside on a single “plane,” a n allocation of memory in
which there is a one-to-one correspondence betw een bits and pixels. The num ber
of planes is called th e depth of the screen. The greater th e depth of the screen,
th e m ore colors it can display a t one tim e.
Color and in tensity (gray-scale) screens have m ore th a n one plane, so more th an
one b it defines the value of a pixel. Each of these bits resides on a different plane
in memory. For example, a four-plane in ten sity display can produce up to sixteen
levels of brightness. A four-plane color display can produce as m any as sixteen
colors. The c l x :s c r e e n -d e p t h s function re tu rn s a list of all the depths supported
by the display hardw are.
CLX uses a table, called a colormap, to define the color of each pixel. A colormap
contains a collection of color cells, each of which defines a pixel value in term s
of its red, green, and blue (RGB) components. In CLX, RGB components are
floating-point num bers betw een zero and one, inclusive, not integers betw een zero
(off) and 65535 (brightest). Each pixel value is a n index into a colormap.

Using Color

8—1

Because m ost VAXstation w orkstations have a global hardw are colormap th a t
applies to th e entire display, clients should use th e sam e colormap w henever
possible. If a client allocates and installs its own colormap, other clients on the
display appear in the wrong colors.
CLX provides a default colormap to which all clients have access. This is retu rn ed
by th e c l x : s c r e e n -d e f a u l t -c o l o r m a p function. C lients can e ith e r allocate color
cells for exclusive use or allocate colors for shared use from the default colormap.
S haring colors conserves space in the default colormap.
In cases w here the client cannot use the default colormap and m u st use a new
colormap, CLX creates virtual colormaps th a t are swapped in and out of the
hardw are colormap. Color values of a v irtual colormap are loaded or unloaded
into th e hardw are lookup table w hen a client calls the c l x :i n s t a l l -c o l o r m a p or
CLX:UNINSTALL-COLORMAP function.
The form at of th e CLX: i n s t a l l - c o l o r m a p function is:
CLXMNSTALL-COLORMAP colormap

w here colormap is the c l x :c o l o r m a p object th a t is installed.
The form at of th e CLX: u n i n s t a l l -c o l o r m a p function is:
CLX:UNINSTALL-COLORMAP colormap

w here colormap is the c l x :c o l o r m a p object th a t is swapped out.
CLX also provides th e CLX: i n s t a l l e d -c o l o r m a p s function, which re tu rn s the
colormaps currently installed. Its form at is:
CLX:INSTALLED-COLORMAPS window &KEY :RESULT-TYPE
w in dow

The CLX: WINDOW object whose colormaps are listed.

:RESULT-TYPE

The LISP type o f the return value. The default is 'LIST.

The default colormap on a specified screen is retu rn ed by the
CLX:SCREEN-DEFAULT-COLORMAP function.

8.2 Matching Color Requirements to Screen Types
Each screen h as certain visual characteristics, such as color or monochrome
capability, th a t are collectively called the visual inform ation of th e screen. CLX
stores visual inform ation in th e CLX:v i s u a l - i n f o structure. Table 8-1 lists the
accessor functions for c l x :v i s u a l - i n f o objects. None of these functions can be
used w ith s e t f .
Table 8-1:

Information Functions for CLX:VISUAL-INFO Objects

F u n c t io n N a m e

R e t u r n V alue

CLX:VISUAL-INFO-ID

An integer resource-id.

CLX:VISUAL-INFO-CLASS

The visual type o f the screen:
:STATIC-GRAY, :STATIC-COLOR,
:TRUE-COLOR, :GRAY-SCALE,
:PSEUDO-COLOR, or :DIRECT-COLOR.

CLX:VISUAL-INFO-RED-MASK

A CLX:PIXEL value.

(continued on n ext page)

8-2

Using Color

Table 8-1 (Cont.):

Information Functions for CLX:VISUAL-INFO Objects

F u n c t io n N a m e

R e tu rn V alue

C LX:VISUAL-INFO-GREEN-MASK

A CLX:PIXEL value.

CLX:V ISUAL-INFO-BLUE-MASK

A CLX:PIXEL value.

CLX:VISUAL-INFO-BITS-PER-RGB

An integer specifying the number o f bits in
each red, green, or blue value pf a color cell.

CLX:VISUAL-INFO-COLORMAP-ENTRIES

An integer specifying the number of entries
in the colormap.

The constructor function for c l x :VISUa l - i n f o objects is CLX:m a k e -v i s u a l - i n f o .
This function takes a single argum ent, which is a n integer resource-id (a
CLX:v i s u a l value). The CLX:v i s u a l value associated w ith a specified window
is retu rn ed by th e c l x :WINDOW-v i s u a l function; w ith a specified screen by the
CLX: s c r e e n -r o o t -v i s u a l function. For example:
Lisp> *window*
#<Window 12582913>
Lisp> (setf *visual* (clx:window-visual *window*))
14041000
Lisp> (setf *info* (clx:make-visual-info *visual*))
#<Visual-Info 524389>
Lisp> (clx:visual-info-colormap-entries *info*)
256

8.3

Sharing Color Resources
CLX provides th e following ways to share color resources:
•

U sing nam ed colors

•

Specifying exact color values

8.3.1 Using Named Colors
X l l servers provide nam ed colors th a t clients can share. (For a list of
VMS DECwindows color nam es, see the VMS DECwindows Guide to Xlib
Programming: MIT C Binding. Such nam es, however, are not portable to
other servers.) Tb use a nam ed color, call th e CLX:ALL0C-C0L0R function w ith a
c l x :s t r i n g a b l e value for th e color argum ent. The c l x :ALLOC-c o l o r function
determ ines w hether th e colormap defines a value for th e specified color. If the
color exists, th e server re tu rn s th e index to the colormap (th a t is, a pixel value).
If th e color does not exist, th e server re tu rn s an error.
The form at of th e c l x :ALLOC-c o l o r function is:
CLX:ALLOC-COLOR colormap color
c o lo rm a p

The CL X :COLORMAP object that is to be accessed.

co lo r

Either a CLX:COLOR object or a string or symbol value that names the color
to be allocated.

The function re tu rn s three values: a pixel, th e screen color, and the exact color.
The screen color contains th e RGB values supported by the display hardw are.
The exact color contains the RGB values specified by the nam ed color.

Using Color

8-3

The files RADAR.LSP and REBOUND.LSP are exam ples of using
c l x :a l l o c -c o l o r w ith nam ed colors. These program s a re in the directory
referenced by the logical nam e LISP$EXAMPLES.

8.3.2 Specifying Exact Color Values
To specify exact color values, use th e following method:
1. Assign values to a c l x :c o l o r object.
2.

Call the CLX:a l l o c -c o l o r function, specifying the color created in Step 1.
The CLX: a l l o c -c o l o r function re tu rn s the pixel value of th e color and the
RGB values of th e closest color supported by th e hardw are.

Table 8-2 lists the functions th a t re tu rn inform ation about CLX:COLOR objects.
Table 8-2:

Information Functions for CLX:COLOR Objects

F u n c t io n N a m e

U se
w ith
SE T F ?

CLX:COLOR-BLUE

Yes

A number between 0 and 1, inclusive, indicating the
percentage o f blue in the color.

CLX:COLOR-GREEN

Yes

A number between 0 and 1, inclusive, indicating the
percentage of green in the color.

CLX:COLOR-RED

Yes

A number between 0 and 1, inclusive, indicating the
percentage o f red in the color.

C LX:COLOR-RGB

Three CLX:RGB-VAL values for red, green, and blue.

R e tu r n V alue

The constructor function for c l x :c o l o r objects is c l x :m a k e -c o l o r . The form at of
this function is:
CLX:MAKE-COLOR &KEY :RED GREEN BLUE
&ALLOW-OTHER-KEYS
F o r example:
L i s p > (setf sea-green (clx:make-color :red 0 :green 1 :blue .8))
#<Color red: 0.00 green: 1.00 blue: 0.80>
L i s p > (clx:alloc-color ‘colormap* sea-green)
243 ;
#<Color red: 0.00 green: 1.00 blue: 0.80>
Lisp> (setf (clx:gcontext-foreground *gcontext*) 243)
243

8.4

Allocating Colors for Exclusive Use
W hen a client w ants to change color values th a t are already in a colormap, it
m u st allocate them for its exclusive use. CLX provides two m ethods for allocating
colors for the exclusive use of a client. F irst, the client can allocate cells and store
color values in the default colormap. Second, if th e default colormap does not
contain enough storage, the client can create its own colormap in which to store
color values.
This section describes how to specify a colormap, how to allocate cells for
exclusive use, and how to store values in th e color cells.

8-4

Using Color

8.4.1

Specifying a Colormap
To create your own colormap, call the CLX: c r e a t e - c o l o r m a p function. Its form at
is:
CLX:CREATE-COLORMAP visual window &OPTIONAL alloc-p
v is u a l

A CLX:VISÜAL value, that is, an integer pointing to the CLX:VISUAL-INFO
data supported by the screen hardware.

w in d o w

A CLX:WINDOW object, used to specify the screen.

a llo c -p

A CLX:BOOLEAN value that specifies whether the client allocates all colormap
entries for its exclusive use or creates a colormap with no defined entries.

If th e visual type is : s t a t i c -g r a y , :s t a t i c -c o l o r , or : t r u e -c o l o r , the client
m u st allocate no entries. Specifying n i l for the alloc-p argum ent is useful when
two or m ore clients are to sh are th e newly created colormap. The function retu rn s
th e specified c l x :c o l o r m a p object.
Table 8-3 lists th e functions th a t are available for c l x :c o l o r m a p objects. None of
these functions can be used w ith s e t f .
Table 8-3:

8.4.2

Information Functions for CLX:COLORMAP Objects

F u n c t io n N a m e

R e tu r n V alue

C LX:COLORMAP-DISP LAY

CLX:DISPLAY

C LX:COLORMAP-EQUAL

CLX:BOOLEAN

CLX:COLORMAP-ID

INTEGER

C LX:COLORMAP-P

CLX:BOOLEAN

Allocating Color Cells
A fter specifying a colormap, allocate color cells in it. The c l x :ALLOC-c o l o r -c e l l s
function allocates cells for a pseudocolor or a gray-scale device. The
c l x :a l l o c -c o l o r -p l a n e s function sim ulates a direct color device.
The form at of th e c l x :Al l o c -c o l o r -c e l l s function is:
CLX:ALLOC-COLOR-CELLS colormap colors
&KEY :PLAN ES :CONTIGUOUS-P :RESULT-TYPE
co lo rm a p

The CLX:COLORMAP object in which cells are allocated.

co lo rs

An integer that specifies the number o f pixels to be returned.

:PLANES

An integer that specifies the number of plane m asks to be returned.
The default value is 0.

:CONTIGUOUS-P

A CLX:BOOLEAN value that specifies whether the colormap entries
m ust be contiguous.

:RESULT-TYPE

The LISP type o f the return values. The default is 'LIST.

The function re tu rn s a sequence of c l x :p i x e l values and a sequence of
c l x :MASK16 values. For detailed inform ation on plane m asks, see the X Window

System: C Library and Protocol Reference.

The form at of th e c l x :a l l o c - c o l o r -p l a n e s function is:
CLX:ALLOC-COLOR-PI_ANES colormap colors
&KEY :REDS :GREENS .BLUES :CONTIGUOUS-P
:RESULT-TYPE
Using Color

8—5

colorm ap

The C LX:COLORMAP object that is to be accessed.

colors

An integer that specifies the number o f pixel values returned.

: REDS

An integer that specifies the number o f red planes. The default
value is 0.

:GREENS

An integer that specifies the number of green planes. The default
value is 0.

:BLUES

An integer that specifies the number o f blue planes. The default
value is 0.

:CONTIGUOUS-P

A CLX:BOOLEAN value that specifies whether the colormap entries
are contiguous.

:RESULT-TYPE

The type specifier of the first return value. The default is ' LIST.

The function re tu rn s four values: a sequence of CLX:p i x e l values and three
c l x :MASKl 6 values for th e red, green, and blue planes.
W hen allocating colors from a shared colormap, the client m ay
exhaust the resources of th e colormap. In this case, CLX provides the
c l x :c o p y -c o l o r m a p -a n d -f r e e

function for copying existing colormap entries

into a new client-created colormap. The function re tu rn s a colormap of the same
visual type and for the sam e screen as the previously shared colormap. The
previously shared colormap can be either the default colormap or a client-created
colormap.
The form at of th e c l x :c o p y -c o l o r m a p -a n d -f r e e function is:
CLX:COPY-COLORMAP-AND-FREE colormap
where colormap is the c l x :c o l o r m a p object that is to be copied.

The function re tu rn s the newly copied c l x :c o l o r m a p object.
c l x :c o p y -c o l o r m a p -a n d -f r e e copies all allocated cells from the previously shared
colormap to the new colormap, keeping color values intact. The new colormap is
created w ith the sam e value for the alloc-p argum ent as the previously shared
colormap. This value determ ines which entries are moved to th e new colormap
and which entries in the shared colormap are freed:
T

All entries are copied from the previously shared colorm ap and are then freed to
create writable m ap entries.

NIL

The entries m oved are all pixels and planes that have been allocated with
the follow ing routines and that have not been freed since they were allocated:
CLX:ALLOC-COLOR, CLX:ALLOC-COLOR-CELLS, CLX:ALLOC-COLOR-PLANES.

8.5 Storing Color Values
After allocating color entries in th e colormap, you can store RGB values in
specified colormap cells w ith th e following method:
1. Assign color values to a c l x :c o l o r structure.
2.

Call the c l x :s t o r e -c o l o r function to store one color or th e c l x :s t o r e -c o l o r s
function to store m ultiple colors.

To store nam ed colors, use a c l x :s t r i n g a b l e value in place of a c l x :c o l o r object.
CLX looks up the color nam e.
The form at of th e CLX: s t o r e -c o l o r function is:
CLX:STORE-COLOR colormap pixel spec &KEY :RED-P ;GREEN-P :BLUE-P

&-6

Using Color

colorm ap

The CLX: COLORMAP object w hose color cell will be stored in memory.

p ixel

A CLX: PIXEL value that specifies where to store the color.

spec

Either a CLX: COLOR object or a CLX :STR INGABLE value that names the
color to be stored.

:RED-P

A CLX: BOOLEAN value that indicates whether the red value should be
stored. The default is T.

: GREEN-P

A CLX:BOOLEAN value that indicates whether the green value should be
stored. The default is T.

:BLUE-P

A CLX: BOOLEAN value that indicates whether the blue value should be
stored. The default is T.

The form at of th e c l x : sto r e - colors function is:
CLX:STORE-COLORS colormap specs &KEY :RED-P :GREEN-P :BLUE-P
colorm ap

The CLX: COLORMAP object w hose color cells will be stored in memory.

specs

A CLX:REPEAT-SEQ value w ith elem ents o f the form:

(pixel color)
where p ix el is a CLX: PIXEL value and color is either a CLX: COLOR object or
a CLX: STRINGABLE value that nam es the color to be stored.

:RED-P

A CLX:BOOLEAN value that indicates whether the red value should be
stored. The default is T.

: GREEN-P

A CLX: BOOLEAN value that indicates whether the green value should be
stored. The default is T.

:BLUE-P

A CLX:BOOLEAN value that indicates whether the blue value should be
stored. The default is T.

8.6 Freeing Color Resources
To free storage allocated for client colors, call th e c l x : f r e e - c o l o r s function.
c l x : FREE-coLORS releases all storage allocated by the following color functions:
CLX:ALLOC-COLOR, CLX:ALLOC-COLOR-CELLS, and CLX:ALLOC-COLOR-PLANES. The
form at of the CLX: FREE-COLORS function is:
CLX:FREE-COLORS colormap pixels &OPTIONAL :PLANE-MASK
colorm ap

The CLX: COLORMAP object w hose color cells are to be erased from
memory.

pixels

A sequence of CLX: P IXEL values, specifying the cells to erase.

: PLANE-MASK

A CLX:MASK16 value that specifies which planes are erased. The default
value is 0, m eaning all planes.

To delete th e association betw een a colormap ID and a colormap, call the
CLX : FREE-colormap function. clX:FREE-colorm ap h as no effect on th e screen’s
default colormap. If th e colormap is installed, c l x : fr e e - c o lo r m a p removes it.
The form at of th e c l x : fr e e - c o lo r m a p function is:
CLX:FREE-COLORMAP colormap

w here colormap is the clx : colormap object th a t is to be erased from memory.

Using Color

8-7

8.7 Querying Colormap Entries
CLX provides functions to re tu rn the RGB values of both colormap entries and
nam ed colors.
To query th e RGB values of specified entries in a colormap, use the
CLX:q u e r y -c o l o r s function. Its form at is:
CLX:QUERY-COLORS colormap pixels &KEY :RESULT-TYPE
colorm ap

The CLX: COLORMAP object whose colors will be returned.

pixels

A sequence of C LX:PIXEL values specifying the entries being queried.

:RESULT-TYPE

The LISP type o f the return value. The default is 'LIST.

clx:query-colors returns a sequence of the CLX: color objects defined in the
specified colormap.

To look up th e RGB values associated w ith a nam ed color, use the
c l x :l o o k u p - c o l o r function. This function uses the specified colormap to
find out th e value w ith respect to a p articu lar screen. The form at of the
c l x :l o o k u p - c o l o r function is:
CLX:LOOKUP-COLOR colormap name
colorm ap

The CLX:COLORMAP object of interest.

nam e

A CLX: STRINGABLE value th a t nam es th e color.

The function re tu rn s both the screen values (w hat the hardw are supports) and
the tru e values of th e nam ed color. For example, assum ing th a t the variable
*COLORMAP* is bound to the default colormap of a screen:
Lisp> (clx::lookup-color *colormap* "turquoise")
#<Color red: 0.68 green: 0.91 blue: 0.91> ;
#<Color red: 0.68 green: 0.92 blue: 0.92>

8-8

Using Color

Chapter 9

Graphics Functions

CLX provides routines for draw ing graphics into windows and pixmaps. This
chapter describes how to create and m anage graphics draw n into windows, and
covers the following topics:
•

Drawing points

•

Drawing lines

•

Drawing and filling rectangles

•

Drawing and filling arcs

•

Clearing and copying areas

•

Creating cursors

All the draw ing functions in th is chapter take a draw able and a GContext as
th eir first two argum ents. For b e tte r performance, group calls w ith the same,
unmodified GContext.
C hapter 10 h a s additional inform ation on draw ing graphics into pixmaps.

9.1

Drawing Points
CLX provides th e CLX: d r a w -p o i n t function for draw ing a single point and
th e CLX:d r a w -p o i n t s function for draw ing m ultiple points. CLX batches
draw ing requests to th e server; however, w hen you are draw ing m ultiple points,
p e r f o r m a n c e i s b e t t e r i f y o u u s e a s i n g l e call t o d r a w - p o i n t s r a t h e r t h a n m any
calls to DRAW-POINT.
The form at of th e CLX: d r a w -p o i n t function is:
CLX:DRAW-POINT drawable gcontext x y
draw able

The C LX:DRAWABLE object in which the point is displayed.

gcontext

The CLX: GCONTEXT object that specifies the graphics characteristics o f the
point (such as color).

x and y

Integers that specify the X and Y coordinates of the point.

The X and Y coordinates a re relative to the origin of th e draw able.
The CLX:d r a w -p o i n t s function can draw m ultiple points in a single request.
The coordinates of th e points can be stored in a CLX:p o i n t - s e q value before the
function is called. The form at of th e CLX:d r a w -p o i n t s function is:
CLX:DRAW-POINTS drawable gcontext points &OPTIONAL relative-p

Graphics Functions

9-1

d ra w a b le

The CLX: DRAWABLE object in which the points are displayed.

gcontext

The CLX:GCONTEXT object that specifies the graphics characteristics o f the
points (such as color).

p o in ts

A value of type CLX :POINT-SEQ that specifies the coordinates of the points.

r e la tiv e - p

An optional argument whose CLX:BOOLEAN value specifies whether the
coordinates of each point are relative to the previous point.

The coordinates of the first point in the sequence are relative to the origin of the
draw able. If relative-p is false, the coordinates of all other points are also relative
to the origin. If relative-p is true, they are relative to the point th a t precedes
them in th e sequence.
Exam ple 9—1 uses the CLX:draw-points function to draw a circle of points around
each click of MB1 . This is tra n sla ted from Exam ple 6-1 in the VMS DECwindows

Guide to Xlib Programming: MIT C Binding.
Example 9-1:

Drawing Points

;;;This code creates the window for the CLX:DRAW-POINTS example
(defvar "window* nil "The window to show examples in.")
(defvar "gcontext* nil "The gcontext for the window to show examples in.")
(defun create-example-window (host)
(let* ((display (clx:open-display host))
(screen (clx:display-default-screen display))
(root-window (clx:screen-root screen))
(white-pixel (clx:screen-white-pixel screen)))
(setq ‘window*
(clx:create-window :parent root-window
:x 100 :y 100 :width 600 :height 600
:background white-pixel
:event-mask ' (:exposure :button-press)))
(setq ‘gcontext*
(clx:create-gcontext :drawable *window*)))
(clx:map-window ‘window*)
(clx:display-force-output (clx:window-display *window*)))
;; Help function for point-example
(defun write-point-messages (window gcontext)
(clx: draw-glyphs window gcontext 150 25 "To create points, press MB1")
(clx:draw-glyphs window gcontext 150 50
"Each press creates a new circle of points")
(clx:draw-glyphs window gcontext 150 75 "To exit, press MB2"))

(continued on next page)

9-2

Graphics Functions

Example 9-1 (Cont.):

Drawing Points

(defun point-example (win gcontext)
;; Window should be width 600, height 600, and event mask set to
;; button-press and exposures. This may be done as follows:
;; (setf (window-event-mask <window>)
;;
(make-event-mask :button-press :exposure))
(write-point-messages win gcontext)
(let ((point-vector (make-array 200 :element-type 'fixnum)))
(clx:event-case ((clx:window-display win) :discard-p t)
;; On exposure events, rewrite the text
(:exposure () (write-point-messages win gcontext) nil)
(:button-press (x y code)
(if (= code 1) ; that's MB1
(progn
;; Fill in the array points
(dotimes (index 100)
(setf (aref point-vector (* 2 index))
(+ x (truncate (* 50 (cos index)))))
(setf (aref point-vector (1+ (* 2 index)))
(+ y (truncate (* 50 (sin index))))))
;; and draw them
(clx:draw-points win gcontext point-vector) nil)
;; Otherwise it's MB2 or MB3, so exit event-case
t)>>>>

Figure 9 -1 shows the output from Exam ple 9-1. l b ru n th is example, first
invoke c r e a t e -e x a m p l e -w i n d o w and then pass *w i n d o w * and *g c o n t e x t * to
POINT-EXAMPLE.

Graphics Functions

9-3

Figure 9-1:

Drawing Points

dll No name
To create points, press MB1
Each press creates a new circleof points
To exit,press MB2

MLO-003391

9.2 Drawing Lines
CLX provides three functions for draw ing lines and line segm ents. The
c l x :d r a w -l i n e function draw s a straig h t line betw een two specified endpoints.
The CLX:d r a w -l i n e s function draw s a series of straig h t lines connecting each
point in a sequence (a CLX:POINT- s e q value). Similarly, the c l x :d r a w -s e g m e n t s
function draw s stra ig h t lines connecting each pair of points in a sequence (a
c l x :s e g -s e q value). T hat is, c l x :d r a w -l i n e s tre a ts consecutive lines as having a
common endpoint, b u t c l x :d r a w -s e g m e n t s does not.
The form at of th e c l x :d r a w -l i n e function is:
CLX:DRAW-LINE drawable gcontext x l y l x2 y2 &OPTIONAL relative-p
d ra iu a b le

9-4

Graphics Functions

The CLX:DRAWABLE object in which the line is drawn.

gcontext

The CLX: GCONTEXT object that specifies the graphics characteristics of the
line (line style, line width, and so on).

x l andyj

Integers that specify the X and Y coordinates of the first endpoint of the line.

x2 and y 2

Integers that specify the X and Y coordinates of the second endpoint of the
line.

relative-p

A CLX:BOOLEAN value that specifies whether the coordinates of the second
endpoint are relative to the first endpoint.

If relative-p is false, th e coordinates of both endpoints are relative to the origin of
drawable. This is the default.
The form at of the c l x :d r a w -l i n e s function is:
CLX:DRAW-LINES d raw able g c o n te x t p o in ts &KEY :RELATIVE-P :FILL-P :SHAPE
draw able

The CLX:DRAWABLE object in which the lines are drawn.

gcontext

The CL X :GCONTEXT object that specifies the graphics characteristics o f
the lines (line style, line width, and so on).

po in ts

A CLX: POINT-SEQ value that contains the X and Y coordinates o f the
lines, in the form:
( x l y l x 2 y 2 ... )

RELATIVE-P

A CLX: BOOLEAN value that specifies whether the coordinates o f the
second and following points are relative to the point that precedes them
in the point sequence.

:FILL-P

A CLX:BOOLEAN value that specifies whether the region enclosed by the
lines is filled.

:SHAPE

A keyword used by the server to optimize fill operations. Possible values
are explained below:
:COMPLEX

The region enclosed by the lines can intersect itself.

:NON-CONVEX

The region does not intersect itself.

:CONVEX

The region is wholly convex.

The default value is :COMPLEX.

If :FILL-P is tru e and th e :s h a p e is known and correctly specified, perform ance
m ay be improved.
The form at of th e c l x :d r a w -s e g m e n t s function is:
CLXrDRAW-SEGMENTS d ra w a b le g c o n te x t s e g m e n ts
draw able

The CLX:DRAWABLE in which the line segm ents are drawn.

gcontext

The CL X :GCONTEXT that specifies the graphics characteristics o f the line
segm ents (line style, line width, and so on).

segm ents

A CLX: SEG-SEQ value that contains the X and Y coordinates o f the endpoints
o f the line segments.

W ith CLXrDRAW-SEGMENTS, line segm ents are not connected unless you specify
a common endpoint in the c l x :SEG-s e q value. Exam ple 9—2 illu strates the
difference betw een CLX:d r a w -l i n e s and c l x :d r a w -s e g m e n t s .

Graphics Functions

9-5

Example 9-2:

Drawing Lines and Line Segments

(defun lines-segments-demo (host)
(let* ((d (clx:open-display host))
(s (clx:display-default-screen d))
(wl (clx:create-window :parent (clx:screen-root s)
:x 0 :y 0 :width 200 :height 100
background (clx:screen-white-pixel s)))
(w2 (clx:create-window :parent (clx:screen-root s)
:x 210 :y 0 :width 200 :height 100
background (clx:screen-white-pixel s)))
(gc (clx:create-gcontext :drawable wl
foreground (clx:screen-black-pixel s)
background (clx:screen-white-pixel s)))
(points '( 10 10 190 10
10 50 190 50
10 90 190 90)))
(clx:map-window wl)
(clx:map-window w2)
;; Make windows appear before drawing in them
(clx:display-force-output d)
;; Give windows names
(setf (clx:wm-name wl) "DRAW-LINES")
(setf (clx:wm-name w2) "DRAW-SEGMENTS”)
;; Draw same points as lines and as segments
(clx:draw-lines wl gc points)
(clx:draw-segments w2 gc points)
(clx:display-force-output d)))

Figure 9 -2 shows the output of this example.
Figure 9-2:

Drawing Lines and Line Segments

M L O -0 0 3 3 9 2

9.3 Drawing and Filling Rectangles
Rectangles can eith er be draw n as outlines or can be filled. A single call
to the d r a w -r e c t a n g l e s function is more efficient th a n m ultiple calls to the
DRAW-RECTANGLE function.
The form at of th e c l x :d r a w -r e c t a n g l e function is:
CLX:DRAW-RECTANGLE drawable gcontext x y width height &OPTIONAL fill-p

9-6

Graphics Functions

draw able

The CLX:DRAWABLE object in which the rectangle is drawn.

gcontext

The CLX:GCONTEXT object that specifies the graphics characteristics o f the
rectangle (line width, color, and so on).

x and y

Integers that specify the X and Y coordinates o f the top-left corner o f the
rectangle.

w id th and
height

Integers that specify the width and height, in pixels, of the rectangle.

fill-p

A CLX :BOOLEAN value that specifies whether the rectangle is filled.

If fill-p is tru e, the rectangle is filled w ith the pixm ap specified by the
:f i l l -s t y l e component of gcontext.
The CLX:d r a w -r e c t a n g l e s function h as a required argum ent of type
c l x :r e c t — s e q th a t m u st contain the X and Y coordinates, width, and height
of each rectangle to be draw n. The form at of th is function is:
CLX:DRAW-RECTANGLES drawable gcontext rectangles &OPTIONAL fill-p
draw able

The CLX:DRAWABLE object in which the rectangles are drawn.

gcontext

The CLX: GCONTEXT object that specifies the graphics characteristics o f the
rectangles (line width, color, and so on).

rectangles

A CLX:RECT-SEQ value that specifies the origin and size of the rectangles.

fill-p

A CLX:BOOLEAN value that specifies whether the rectangles are filled.

9.4 Drawing and Filling Arcs
Tb draw an arc w ith CLX, you m ust specify a rectangle th a t defines the
boundaries of the arc as well as two angles th a t indicate the sta rtin g point
and extent of th e arc. T h at is, an arc is specified as a portion of an ellipse
inscribed w ithin a rectangle. For example, to draw a circle, you would specify a
square as th e bounding rectangle, any angle as the s ta rt, and 2JI radians as the
extent. CLX provides the c l x :d r a w -a r c function for draw ing a single arc and the
c l x :d r a w -a r c s function for draw ing m ultiple arcs. A single call to CLX:DRAW-a r c s
is more efficient th a n m ultiple calls to c l x :d r a w -a r c .
The format of th e CLX:d r a w -a r c function is:
CLX:DRAW-ARC drawable gcontext x y width height anglel angle2
&OPTIONAL fill-p degrees-p
draw able

The CLX:DRAWABLE object in which the arc is drawn.

gcontext

The C LX:GCONTEXT object that specifies the graphics characteristics of
the arc (arc-mode, color, and so on).

x andy

Integers that specify the X and Y coordinates o f the top left com er o f the
arc’
s bounding rectangle.

w id th and
height

Integers that specify the dimensions, in pixels, o f the arc’
s bounding
rectangle.

a n g lel

A CLX: ANGLE value that specifies the start o f the arc.

angle2

A CLX: ANGLE value that specifies the extent o f the arc.

fill-p

A C LX:BOOLEAN value that specifies whether the arc is filled.

degrees-p

A CLX:BOOLEAN value that specifies whether the angles are m easured in
degrees.

Graphics Functions

9-7

The angles are m easured in ra d ia n s unless degrees-p is true. Positive values
indicate counterclockwise motion; negative values indicate clockwise motion.
The s ta rt of the arc is relative to the 3 o’clock position from the center of the
rectangle. The extent of the arc is relative to the s ta rt of the arc. Exam ple 9-3
illu strate s the relationships am ong th e rectangle and the angles th a t specify an
arc.
Example 9-3:

Drawing an Arc

(defun arcs-demo (host)
(let* ((display (clx:open-display host))
(screen (clx:display-default-screen display))
(window (clx:create-window :parent (clx:screen-root screen)
:x 0 :y 0 :width 400 :height 200))
(gc (clx:create-gcontext :drawable window
:arc-raode :pie-slice)))
;; Make window visible
(clx:map-window window)
(clx:display-force-output display)
;; Draw bounding rectangle (for demonstration only)
(clx:draw-rectangle window gc 10 10 380 180)
;; Draw complete ellipse (for demonstration only)
(clx:draw-arc window gc 10 10 380 180 0 360 nil t)
;; Draw arc from 12:00 to 11:00, filled
(clx:draw-arc window gc 10 10 380 180 90 30 t t)
(clx:display-force-output display)))

Figure 9—3 shows the output from Exam ple 9—3, w ith labels added.
Figure 9-3:

Drawing an Arc
Extent Angle

Bounding Rectangle

9-8

Graphics Functions

M L O -0 0 3 3 9 3

If f i l l - p is true, the endpoints of th e arc are joined according to the : a r c -m o d e
component of g c , and the resulting shape is filled w ith the pixm ap specified by
the : b a c k g r o u n d component of g c .
The form at of the c l x :d r a w -a r c s function is:
CLX:DRAW-ARCS d ra w a b le g c o n te x t a rc s &OPTIONAL fill-p d e g re e s -p
draw able

The CLX:DRAWABLE object in which the arcs are drawn.

gcontext

The CLX: GCONTEXT object that specifies the graphics characteristics of the
arcs (arc-mode, color, and so on).

arcs

A CLX:ARC-SEQ value that specifies the origins and dim ensions o f the arcs’
bounding rectangles.

fill-p

A CLX:BOOLEAN value that specifies whether the arcs are filled.

degrees-p

A CLX:BOOLEAN value that specifies whether the angles are measured in
degrees.

9.5 Clearing and Copying Areas
A rectan g u lar a re a of a window can be cleared (filled w ith the background color)
w ith the CLX:CLEAR-AREA function or copied to another window or pixm ap w ith
the CLX: c o p y -a r e a function. A reas of pixm aps can also be copied, b u t because
pixm aps do not have defined backgrounds, you m ust use th e c l x :d r a w -r e c t a n g l e
function to clear an a re a of a pixmap. A single bit plane of a window or pixmap
can be copied w ith the c l x :c o p y -p l a n e function.
The form at of th e c l x :c l e a r -a r e a function is:
CLX:CLEAR-AREA w in d ow &KEY :X :Y WIDTH :HEIGHT :EXPOSURES-P
w in dow

The CLX:WINDOW object that contains the area to clear.

:X and :Y

Integers that specify the X and Y coordinates o f the top left com er of
the area. The default value for both keywords is 0, which specifies the
origin o f the window.

:WIDTH and
:HEIGHT

Integers that specify the dimensions, in pixels, o f the area.

:EXPOSURES-P

A CLX:BOOLEAN value that specifies whether exposure events are
generated in w indow .

N ull values for : WIDTH and : h e i g h t default to th e cu rren t w idth of the window
m inus :X and th e current height of the window m inus :Y, respectively. In other
words, using th e default values for :X, :Y, :WIDTH, and h e i g h t resu lts in clearing
th e entire window. Passing in a zero : w i d t h or : h e i g h t is a null operation.
The form at of th e c l x :c o p y -a r e a function is:
CLX:COPY-AREA src g c o n te x t s rc -x s rc -y width h e ig h t d s t d st-x d st-y
src

The CLX:DRAWABLE object that contains the area to copy.

gcontext

The CLX: GCONTEXT object of the source area.

src-x and src-y

Integers that specify the X and Y coordinates of the origin of the
source area.

w id th and height

Integers that specify the dimensions, in pixels, of the source area.

dst

The CLX:DRAWABLE object in which the copy is displayed.

Graphics Functions

9-9

dst-x and dst-y

Integers that specify the X and Y coordinates of the origin where
the copied area is displayed.

Using the GContext of the source area ensures th a t th e copy looks the sam e as
the source.
The form at of the c l x :c o p y -p l a n e function is:
CLX:COPY-PLANE src gcontext plane src-x src-y width height dst dst-x dst-y
src

T he CLX:DRAWÄBLE object that contains the area to modify.

gcontext

The CLX:GCONTEXT object of the source area.

p la n e

An integer that specifies which bit plane o f the source area is
copied.

src-x and src-y

Integers that specify the X and Y coordinates o f the origin of the
source area.

w idth and height

Integers that specify the dimensions, in pixels, o f the source area.

dst

The CLX:DRAWÄBLE object in which the modified area is displayed.

d st-x and dst-y

Integers that specify the X and Y coordinates o f the origin where
the modified area is displayed.

The source and destination draw ables m u st have the sam e root b u t m ay have
different depths.

9.6 Creating Cursors
You can create your own pointer cursor from an im age w ith the
CLX:c r e a t e -c u r s OR function, or a character of a font w ith the
CLX: c r e a t e -GLYPH- c u r s OR function. You can also recolor a cursor, query the
hardw are for best cursor size, and free the memory allocated to a cursor.
The form at of th e CLX: c r e a t e -c u r s o r function is:
CLX:CREATE-CURSOR &KEY :SOURCE :MASK :X :Y FOREGROUND BACKGROUND
:SOURCE

A C LX:PIXMAP object that contains the cursor shape.

:MASK

A CLX :PIXMAP object that modifies the cursor shape. If no m ask is
provided, all bits of the source are used.

: X and : Y

Integers that specify the X and Y coordinates o f the cursor’
s hot
spot.

:FOREGROUND and
BACKGROUND

Two CLX: COLOR objects that specify the cursor’
s foreground and
background colors.

The function re tu rn s a CL X :c u r s o r object w ith the specified characteristics.
The form at of th e c l x :c r e a t e -g l y p h -c u r s o r function is:
CLX:CREATE-GLYPH-CURSOR &KEY :SOURCE-FONT :SOURCE-CHAR :MASK-FONT
:MASK-CHAR FOREGROUND BACKGROUND

9-10

:SOURCE-FONT

The C LX:FONT object that includes the glyph used to create the
cursor.

:SOURCE-CHAR

An integer that identifies the glyph in the source font to be used as
the source for the cursor shape.

:MASK-FONT

A C LX:FONT object that contains m asks that control how the cursor
is displayed on the screen. The default value is NIL.

Graphics Functions

:MASK-CHAR

An integer that identifies the glyph in the m ask font to be used as
the m ask for the cursor shape. The default value is NIL.

:FOREGROUND and
:BACKGROUND

Two CLX: COLOR objects that specify the foreground and background
colors of the cursor.

The :SOURCE-FONT, :SOURCE-CHAR, :FOREGROUND, and :BACKGROUND argum ents
are required. If no m ask is provided, all bits of the source are used. If
:m a s k -c h a r is specified b u t :m a s k -f o n t is not, th e :s o u r c e -f o n t is used.
The CLX:c r e a t e -g l y p h -c u r s o r function re tu rn s a CLX:c u r s o r w ith the specified
characteristics.
Exam ple 9 -4 creates a cursor by calling the CLX:c r e a t e -g l y p h -c u r s o r function
w ith the specified argum ents. If none of the argum ents a re supplied, it creates
th e w ait cursor in the DECW$CURSOR font w ith a black or red foreground
(depending on th e depth of the display) and a w hite background. This example
is derived from CURSORS.LSP in the directory referenced by the logical nam e
LISP$EXAMPLES.
Example 9-4:

Creating a Cursor

(defun create-oursor (display &key
cursor-font
(cursor-font-name "decw$cursor")
(source-char clx+:decw$c_wait_cursor)
(background ;white
(clx:make-color :red 1 :green 1 :blue 1))
foreground ;set below if unsupplied
)
(cond ((clx:font-p cursor-font))
; fine, do nothing
((null cursor-font)
(unless (simple-string-p cursor-font-name)
(error "CURSOR-FONT-NAME must be of type ~
SIMPLE-STRING, received ~s" cursor-font-name))
(let ((font-name-list
(clx:list-font-names display cursor-font-name
:max-fonts 1)))
(if font-name-list
(setf cursor-font (clx:open-font display (car font-name-list)))
(error "No font matches ~s" cursor-font-name))))
(t (error "CURSOR-FONT must be of type CLX:FONT, received ~s"
cursor-font)))
(unless (integerp source-char)
(error "SOURCE-CHAR must be of type INTEGER, received ~s”
source-char))
(unless (clx:color-p background)
(error "BACKGROUND must be of type CLX:COLOR, received ~s"
background))
;; here we'll use black or red, depending on the depth of
;; the display.
(cond ((clx:color-p foreground))
((null foreground)
(setf foreground
;; red or black, depending on display depth
(if
(< 1 (clx:screen-root-depth
(clx:display-default-screen display)))
(clx:make-color :red 1 :green 0 :blue 0) ; red
(clx:make-color :red 0 :green 0 :blue 0)))) ; black
(t (error "FOREGROUND must be of type CLX:COLOR, received ~s”
foreground)))

(continued on next page)
Graphics Functions

9-11

Example 9-4 (Cont.):

Creating a Cursor

(clx:create-glyph-cursor :source-font cursor-font
:mask-font
cursor-font
:source-char source-char
:mask-char
(1+ source-char)
:foreground foreground
:background background))

Use the c l x :r e c o l o r -c u r s o r function to change th e foreground and background
colors of a cursor. Its form at is:
CLX:RECOLOR-CURSOR cursor foreground background
cursor

The CLX:CURSOR object whose colors change.

foreground and
background

Two CLX:COLOR objects that specify the new colors.

The CLX:q u e r y -b e s t -c u r s o r function queries the display hardw are for th e m ost
efficient cursor size. Its form at is:
CLX:QUERY-BEST-CURSOR width height display
w idth and
height

Integers that specify the desired dim ensions o f a cursor.

d isp la y

The CLX:DISPLAY device on which the cursor will be used.

The function re tu rn s two integer values: the w idth and height, supported by the
display hardw are, th a t m ost closely m atch the desired dimensions.
lb free the m em ory allocated to a cursor, call the CLX:FREE-c u r s o r function. Its
form at is:
CLX:FREE-CURSOR cursor

w here cursor is a c l x :c u r s o r object originally retu rn ed by c l x :CREATE-c u r s o r or
CLX:CREATE-GLYPH-CURSOR.

9-12

Graphics Functions

Chapter 10

Using Pixmaps and Images

CLX enables clients to create and w ork w ith both on-screen graphics, such as
lines and cursors, and off-screen graphics, such as pixmaps and im ages. This
chapter describes how to work w ith off-screen graphics, and includes th e following
topics:
•

C reating and freeing pixm aps

•

C reating and m anaging bitm ap files

•

Working w ith images

C hapter 7 and C hapter 9 explain how to work w ith on-screen graphics objects.

10.1

Creating and Freeing Pixmaps
A pixm ap is an area of m em ory into which clients can either draw objects or
tem porarily save p a rt of a screen. Pixm aps are useful for graphics th a t are
displayed repeatedly, such as cursors and icons; for creating tiling p atterns; and
for saving portions of windows th a t have been obscured. In addition, draw ing
complicated graphics sequences into pixm aps and th en copying the pixm aps to a
window m ay be faster th a n draw ing th e sequences directly into a window.
The c l x :c r e a t e -p i x m a p function re tu rn s a CLX:p i x m a p object w ith the specified
w idth, height, and depth. I t is an erro r to specify a w idth or height of zero, or
a depth th a t is not supported by the draw able’s root window. The form at of the
c l x :c r e a t e -p i x m a p

function is:

CLX:CREATE-PIXMAP &KEY WIDTH :HEIGHT :DEPTH :DRAWABLE
:WIDTH and : HEIGHT

Integers that specify the dimensions of the pixmap.

:DEPTH

An integer that specifies the depth of the pixmap.
A CLX:DRAWABLE object that specifies the screen on which the
pixmap is created.

:DRAWABLE

The functions th a t re tu rn inform ation about pixmaps are listed in Table 10-1.
None of these functions is a valid s e t f place.

Using Pixmaps and Images

10-1

Table 10-1:

information Functions for Pixmaps

F u n c t io n

R e tu r n V alu e

CLX:PIXMAP-DISPLAY

The CLX:DISPLAY object on which the pixmap was created.

CLX:PIXMAP-EQUAL

A CLX:BOOLEAN value that indicates whether the two
arguments are the same pixmap.

CLX.:PIXMAP-ID

The integer resource-id o f the pixmap.

CLX:PIXMAP-P

A CLX:BOOLEAN value that indicates whether the argument is
of type CLX: PIXMAP.

Objects of type CLX: p i x m a p -f o r m a t show w h at form ats th e display hardw are
supports, and are retu rn ed by th e c l X:DISP l a y -p i x m a p -f o r m a t s function. The
functions th a t re tu rn inform ation about CLX: p i x m a p -f o r m a t objects are described
in Table 10-2. All of these functions can be used w ith s e t f .
Table 10-2:

Information Functions for Pixmap Formats

F u n c t io n

R e t u r n V alu e

CLX:PIXMAP-FORMAT-BITS-PER-PIXEL

T h e n u m b e r o f b its u sed to h old each pixel, a
m e m b e r of (1 4 8 16 24 3 2 ) .

CLX:PIXMAP-FORMAT-DEPTH

A C L X :IMAGE-DEPTH v a lu e t h a t specifies
th e d e p th o f th e display.

CLX:PIXMAP-FORMAT-PAD

T h e n u m b e r o f b its to a m u ltip le of w hich
ea ch sc an lin e is pad d ed , a m e m b er o f (8 16
32).

W hen your program no longer needs a pixmap, use the CLX: FREE-PIXMAP function
to free th e m em ory allocated to it. The form at of this function is:
CLX:FREE-PIXMAP pixmap
where p i x m a p is the CLX:pixmap object to be freed in server memory.
CLX:FREE- p i x m a p first deletes the association between the pixmap and its
resource-id and then frees the pixmap storage.

10.2 Creating and Managing Bitmap Files
A bitm ap is a pixm ap of depth 1, or a n a rra y of bits. CLX enables clients to
create files of bitm ap d a ta and th en use those files to create either bitm aps or
pixmaps. Tb create a bitm ap d a ta file, use the CLX:w r i t e -b i t m a p -f i l e function.
Its form at is:
CLX:WRITE-BITMAP-FILE pathname image
&OPTIONAL name
&KEY :PIXMAP-P WIDTH :HEIGHT :X-HOT :Y-HOT :DRAWABLE

10-2

path n a m e

A pathname that specifies the file to write.

im age

The CLX: IMAGE or CLX:PIXMAP object to write.

nam e

A CLX:STRINGABLE value that nam es the bitmap and is used for
variable prefixes. The default is "IMAGE-".

:PIXMAP-P

A CLX:BOOLEAN value that specifies whether the im a g e argument is a
pixmap or an image.

Using Pixmaps and Images

: WIDTH a n d
: HEIGHT

Two integers that specify the dim ensions o f the im age or pixmap.

: X-HOT and

Two integers that specify the hot spot of a cursor. The defaults are 0.

: Y-HOT

: DRAWABLE

A CLX : DRAWABLE object that provides information on the screen and
display.

The c l x : w r i t e - b i t m a p - f i l e function creates a C include file in stan d ard X l l
form at.
To create a n im age or a pixmap from an X l l bitm ap file, use the
CLX: R EA D -B IT M A P-FIL E function. Its form at is:
CLX:READ-BITMAP-FILE pathname &KEY :PIXMAP-P :DRAWABLE
p a th n a m e

A pathname or string that specifies the file to read.

:PIX M A P-P

A CLX:BOOLEAN value that specifies whether the function returns a
pixmap or an image.

: DRAWABLE

A CLX : DRAWABLE object that identifies the screen on which to create the
pixmap. This argum ent is required only if :PIX M A P-P is true.

If :PIX M A P-P is true, th e function re tu rn s three values: th e c l x : p i x m a p object
and two integers th a t specify the X and Y coordinates of a cursor’s hot spot. If
:PIX M A P-P is false, the function retu rn s the c l x : im a g e object only.
Objects of type c l x : b i t m a p - f o r m a t store th e form at in which im ages
are tra n sm itte d and received by the server, and a re retu rn ed by the
c l x :D I S p l a y - b i t m a p - f o r m a t function. B itm aps a re represented in scanline order.
The functions th a t re tu rn inform ation about objects of type c l x : b i t m a p - f o r m a t
are described in Table 10-3. None of these functions is a valid s e t f place.
Table 10-3:

Information Functions for Bitmap-Formats

F u n c t io n

R e t u r n V alu e

CLX: BITMAP-FORMAT-UNIT

The number of bits in a unit o f the scanline, a
m em ber o f (8 16 32).

CLX : BITMAP-FORMAT-PAD

The number o f bits to a m ultiple o f which each
scanline is padded, a m em ber o f (8 16 32).

CLX : B IT M A P-FO R M A T-LSB -FIR ST—P

A CLX : BOOLEAN value that indicates whether
the least significant bit or the m ost significant
bit is the leftm ost bit in each unit.

10.3 Working with Images
Off-screen im ages m ay be simple p a tte rn s stored directly in an a rra y or more
complex form s draw n into a pixmap. Instances of th e c l x : im a g e stru c tu re include
a pointer to im age d a ta th a t m ay be stored in a n a rra y or pixmap. Clients can
perform operations on im ages which a re not possible w ith pixmaps. The following
is a lis t of direct m anipulations th a t can be perform ed on images:
•

D estroying an im age

•

G etting a pixel from an image

•

Storing a pixel in a n image

•

E xtracting p a rt of an image

•

Adding a constant to th e im age
Using Pixmaps and Images

15-3

CLX lets clients store im age d a ta as a bitm ap ( : b i t m a p form at), as a stack of
bitm aps (:X Y - p i x m a p format), or as a list of pixel values (:Z -P IX M A P form at), l b
create a c l x : im a g e object, use th e CLX: c r e a t e - im a g e function. Its form at is:
CLX:CREATE-IMAGE &KEY WIDTH :HEIGHT :DEPTH :DATA :RED-MASK :GREEN-MASK
:BLUE-MASK :BITS-PER-PIXEL :FORMAT :SCANLINE-PAD
:BYTES-PER-LINE :BYTE-LSB-FIRST-P BIT-LSB-FIRST-P
: WIDTH and : HEIGHT

Two CLX:CARD 16 values that specify the dim ensions o f the
image. These arguments are required.

: DEPTH

A CLX:CARD 8 value that specifies the depth o f the image. The
default is 1.

: DATA

A sequence in which to store the data. Its type depends on the
value o f the : FORMAT argument:
: FORMAT : BITMAP

(ARRAY CLX: CARD8 (* ) )

: FORMAT :XY-PIXMAP

(L IS T CLX: BITMAP)

: FORMAT :Z-PIX M A P

CLX:PIXARRAY

: RED-MASK
: GREEN-MASK a n d
: BLUE-MASK

Three CLX : P IX E L values that specify the red, green, and blue
values for pixels in :Z-PIXM AP format images.

: B IT S -P E R -P IX E L

T h e n u m b e r o f b its u s e d to s to re a p ix e l, a m e m b e r o f (1 4 8 16
24 3 2 ) .

: FORMAT

The ty p e o f im age returned, one o f :BITMAP, :XY-PIXMAP, or
: Z-PIXMAP.

: SCANLINE-PAD

An integer that specifies the number o f bits each scanline is
padded to a m ultiple of, a m em ber o f (8 1 6 3 2 ) .

: B Y T E S-PE R -LIN E

An integer that specifies the number o f bytes in a scanline. The
default is calculated from the : WIDTH and : SCANLINE-PAD
arguments.

: BYTE-LSB—F IR S T -P

A CLX : BOOLEAN value that specifies whether the least
significant byte is first.

: B IT -L S B -F IR S T -P

A CLX:BOOLEAN v a lu e t h a t sp ecifies w h e th e r th e le a s t
s ig n ific a n t b i t is first.

The functions th a t re tu rn inform ation on c l x : im a g e objects a re listed in
Table 10—4.
Table 10-4:

Information Functions for CLX:IMAGE Objects

F u n ctio n

U se
w ith
SETF?

C L X :IM A G E -B IT -L S B -F IR S T -P

Yes

A CLX: BOOLEAN value that specifies
whether the least significant bit is first.

CLX: IMAGE-BLUE-MASK

Yes

A C LX :PIX E L value that specifies the
blue value in a pixel, in : Z-PIXMAP
format.

R e tu rn V alue

(continued on next page)

10-4

Using Pixmaps and Images

Table 10-4 (Cont.):

Information Functions for CLX:IMAGE Objects

F u n c t io n

U se
w ith
SETF?

R e tu r n V alue

CLX: IM A G E -B Y T E -L S B -F IR S T -P

Yes

A CLX: BOOLEAN v a lu e t h a t sp ecifies

CLX: IM A G E-BY TES-PER -LIN E

Y es

A n in te g e r t h a t sp ecifie s th e n u m b e r o f
b y te s in a sc a n lin e .

CLX: IMAGE-FORMAT

Y es

A k e y w o rd t h a t sp ecifie s th e fo r m a t o f th e
im a g e d a ta : : BITMAP, :XY-PIXM AP, or
: Z-PIXMAP.

CLX:IMAGE-GREEN-MASK

Yes

A CLX : PIX EL v a lu e t h a t sp e c ifie s th e
g r e e n v a lu e in a p ix el, in : Z-PIXMAP

CLX:IMAGE-DEPTH

A CLX:CARD8 v a lu e t h a t sp ecifie s th e

w h e th e r th e le a s t s ig n ific a n t b y te is first.

fo rm a t.
d e p th o f th e im a g e . T h e d e f a u lt v a lu e is
1, w h ic h m e a n s a b itm a p .
CLX:IMAGE-HEIGHT

A CLX:CARD 16 v a lu e t h a t sp ecifie s th e
h e ig h t o f th e im a g e . T h e d e f a u lt v a lu e is
0.

CLX : IMAGE-RED-MASK

Yes

A C L X :PIX E L v a lu e t h a t sp ecifie s th e re d
v a lu e in a p ix e l, i n : Z-PIXMAP fo rm a t.

CLX:IMAGE-SCANLINE-PAD

Y es

E a c h s c a n lin e i n th e im a g e is a m u ltip le
o f th i s v a lu e , w h ic h m a y b e 8 , 16, o r 32.

CLX:IMAGE-WIDTH

A CLX:CARD 16 v a lu e t h a t sp ecifie s th e
w id th o f th e im a g e . T h e d e fa u lt v a lu e is
0.

The functions listed in Table 10—4 access im ages in all three form ats. Tables
10-5 and 10-6 describe the additional accessors for images in :XY-p i x m a p and
:z-p i x m a p form ats. None of th e following functions is a valid s e t f place:
Table 10-5:

Information Functions for :XY-PIXMAP Images

F u n c t io n

R e t u r n V alue

C LX:IMAGE-XY-BITMAP-LIST

A list of the CLX:BITMAP values that contain the
image data.

Table 10-6:

Information Functions for :Z-PIXMAP Images

F u n c t io n

R e t u r n V alue

C LX:IMAGE-Z-BITS-PER-PIXEL

The number o f bits used to store each pixel, a
m em ber o f (1 4 8 16 24 32).

CLX:IMAGE-Z-PIXARRAY

The CLX:PIXARRY value that contains the im age
data.

Using Pixmaps and Images

10-5

10.3.1

Getting Images from the Server
Im ages can be brought into LISP memory w ith the CLX: G E T - image and
CLX: GET-RAW-IMAGE functions. The CLX: GET-IMAGE function re tu rn s a CLX: IMAGE
object; the CLX:g e t -r a w - i m a g e function returns a sequence of bytes.

The form at of the CLX: g e t - i m a g e function is:
CLX:GET-IMAGE drawable &KEY :X :Y WIDTH :HEIGHT :PLANE-MASK : FORMAT

drawable

The CLX: DRAWABLE object that contains the im age to be stored in
memory.

:X and :Y

Integer X and Y coordinates o f the origin o f the im age in the
drawable. These argum ents are required.

:WIDTH and
:HEIGHT

Integers that specify the dim ensions o f the image. These arguments
are required.

:PLANE-MASK

A C LX :PIX E L value that specifies the planes to be retrieved. The
default is #>:FFFFFFFF, which m eans all planes.

:FORMAT

The data format stored in the server, either : XY-PIXMAP or
: Z—PIXMAP. The default is :Z -PIX M A P.

The form at of th e CLX: g e t -r a w - i m a g e function is:
CLX:GET-RAW-IMAGE drawable &KEY :DATA :START :X :Y WIDTH :HEIGHT :PLANE-MASK
.•FORMAT :RESULT-TYPE

drawable

T h e CLX: DRAWABLE t h a t c o n ta in s t h e im a g e to b e s to re d i n m em o ry .

: DATA

A se q u e n c e o f 8 -b it q u a n titie s .

: START

A CLX: ARRAY-INDEX v a lu e s p e c ify in g t h e s t a r t i n g p o s itio n in th e d a ta .
T h e d e f a u lt v a lu e is 0.

: X a n d :Y

In te g e r s t h a t sp ecify th e X a n d Y c o o rd in a te s o f th e o rig in o f t h e im a g e
in th e d ra w a b le .

: WIDTH a n d
: HEIGHT

In te g e r s t h a t sp ecify th e d im e n s io n s o f t h e im a g e .

: PLANE-MASK

A C L X :PIX E L v a lu e t h a t sp ecifie s t h e p la n e s to b e re tr ie v e d . T h e
d e f a u lt v a lu e is #xFFFFFFFF.

: FORMAT

A k e y w o rd t h a t sp ecifie s th e ty p e o f im a g e fo r m a t, e i t h e r : XY-P IXMAP
o r Z-PIXMAP.

: RESULT-TYPE

T h e LISP ty p e o f t h e r e t u r n v a lu e . T h e d e f a u lt is ' (VECTOR
(UNSIGNED-BYTE 8 ) ) .

The function re tu rn s a sequence of 8-bit quantities, in transm ission form at. If
:DATA is given, it is modified in place (and returned); otherwise, a new sequence
is created and retu rn ed , w ith a size computed from th e other argum ents and the
retu rn ed depth.

10.3.2

Displaying Images
Im ages can be displayed w ith the c l x : P U T - i m a g e and C L X : p u t - r a w - i m a g e
functions. The C L X : p u t - im a g e function outputs a c l x : i m a g e object; the
CLX :P U T - r a w - im a g e function outputs a sequence of bytes.
The form at of the c l x : p u t - im a g e function i s :
CLX:PUT-IMAGE drawable gcontext image
&KEY :SRC-X :SRC-Y :X :Y WIDTH :HEIGHT :BITMAP-P

10-6

Using Pixmaps and Images

d raw able

T h e CLX: DRAWABLE o b je c t i n w h ic h t h e im a g e is d is p la y e d .

gcontext

T h e CLX: GCONTEXT o b je c t t h a t sp e c ifie s t h e g ra p h ic s c h a r a c te r is tic s o f
th e im a g e .

im age

T h e CLX: IMAGE o b je c t to b e d is p la y e d .

: SRC-X a n d
: SRC-Y

I n te g e r s t h a t sp e c ify th e X a n d Y c o o rd in a te s o f t h e im a g e . T h e d e fa u lts
a r e 0.

:X a n d :Y

I n te g e r s t h a t sp ecify th e X a n d Y c o o rd in a te s o f t h e im a g e . T h e s e
a r g u m e n ts a r e re q u ire d .

: WIDTH a n d
:HEIGHT

I n te g e r s t h a t sp ecify th e d im e n s io n s o f t h e im a g e .

:B IT M A P-P

A CLX: BOOLEAN v a lu e t h a t in d ic a te s w h e th e r t h e im a g e is a b itm a p
w h e n d e p th is 1. S e ttin g th i s a r g u m e n t to T c a u s e s gcontext to su p p ly
t h e fo re g ro u n d a n d b a c k g ro u n d p ix e ls.

The form at of th e c l x : p u t - r a w - i m a g e function is:
CLX:PUT-RAW-IMAGE drawable gcontext data
&KEY :START :DEPTH :X :Y :WIDTH :HEIGHT :LEFT-PAD :FOR MAT
d raw able

The CLX: DRAWABLE object where the im age is to be displayed.

gcontext

The CLX: GCONTEXT object that specifies the graphics characteristics
used to display the image: function, plane-mask, subwindow-mode,
clip-x, clip-y, clip-mask, foreground, and background.

d a ta

A sequence of 8-bit quantities that contain the image.

: START

A CLX:ARRAY-INDEX value that specifies the starting point within d a ta .
The default value is 0.

: DEPTH

An integer that specifies the depth o f the drawable.

:X and :Y

Two integers that specify the X and Y coordinates of the rectangle where
the im age is drawn in the drawable.

: WIDTH and
: HEIGHT

Two integers that specify the dim ensions o f the rectangle where the
im age is drawn in the drawable.

: LEFT-PAD

An integer that specifies the num ber o f bits to the left o f each scanline
which are ignored by the server. The default value is 0; this value is
required when the format is : Z-PIXM AP.

: FORMAT

The type o f im age format, either :XY-PIXMAP or : Z-PIXMAP.

The data argum ent m u st be a sequence of 8-bit quantities already in the
appropriate form at for transm ission. The : START argum ent is th e startin g
index in data ; the end is computed from th e other argum ents. If : d e p t h is 1 and
:f o r m a t is :XY-p i x m a p , data is a bitm ap.

Using Pixmaps and Images

10-7

V _x

Chapter 11

Writing Text

This ch ap ter describes how to w rite text w ith CLX, and includes the following
topics:
•

C haracters and fonts

•

Specifying fonts

•

Com puting tex t size

•

D raw ing tex t on th e screen

VMS DECwindows provides a font compiler th a t enables program m ers to convert
ASCII files into binary form. For inform ation on th e font compiler, see the VMS

DECwindows Guide to Xlib Programming: MIT C Binding.

11.1 Characters and Fonts
A character is the sm allest u n it of text the server can display. A font is a group of
characters th a t have th e sam e style and size. CLX refers to characters by using
indexes into fonts. The accessor functions for characters are listed in Table 11—1.
None of these functions is a valid s e t f place.
Table 11-1:

Information Functions for Characters

F u n c t io n N a m e

R e tu r n V alu e

CHAR-ASCENT

An i n t e g e r t h a t s p e c ifie s t h e d i s t a n c e f r o m t h e b a s e l i n e to t h e
top of the bounding box.

CH A R -A TTR IB U TES

A positive integer whose 1 bits specify the attributes of the
character defined in the bitm ap distribution format (BDF) file.
A character is not guaranteed to have any attributes.

CHAR-DESCENT

An integer that specifies the distance from the baseline to the
bottom o f the bounding box.

C H A R -L E F T -B E A R IN G

An integer that specifies the distance from the origin to the left
edge of the bounding box.

C H A R -R IG H T -B E A R IN G

An integer that specifies the distance from the origin to the
righ t edge of the bounding box.

CHAR-WIDTH

An integer that specifies the distance from the origin o f the
current character to the origin o f the next character.

Each character accessor function takes two argum ents: the first is a c l x :FONT
object, the second an index of type CARD 16. For 8-bit fonts, the index is usually
th e ASCII value of th e character so you can pass a c h a r a c t e r as th e second
argum ent. For example:
Writing Text

11-1

Lisp> *font*
#<Font 9x15>
Lisp> (clx:char-ascent *font* #\f)
12

Lisp> (clx:char-descent *font* #\f)
3

The character accessor functions re tu rn n i l if the index is out of bounds for the
font.
The functions th a t re tu rn inform ation about c l x : f o n t objects are described in
Table 11—2. None of these functions is a valid s e t f place.
Table 11-2:

Information Functions for CLX: FONT Objects

F u n c t io n N a m e

R e tu rn V alue

F O N T -A LL -C H A R S-E X IST-P

A CLX: BOOLEAN value that indicates whether all
characters in the font have nonzero bounding boxes.

FONT-ASCENT

An integer that specifies the distance from the baseline
to the top of the bounding box.

FONT-DEFAULT-CHAR

The integer index to the character used when an
undefined or nonexistent character is printed.

FONT-DESCENT

An integer that specifies the distance from the baseline
to the bottom o f the bounding box.

FONT-DIRECTION

A CLX: DRAW-DIRECT ION value that gives a hint about
the direction in which the font is painted. The possible
values are :L E F T -T O -R IG H T and : R IG H T -T O -LE FT .

FONT-MAX-CHAR

The integer index to the last character in the font.

FONT-MAX-BYTE1

An integer that specifies the last row of the font.

FONT-MAX-BYTE2

An integer that specifies the last byte in a 16-bit font.
In 8-bit fonts, this is the sam e as FONT-MAX-CHAR.

FONT-MIN-CHAR

The integer index to the first character in the font.

F0N T-M IN -B Y TE1

An integer that specifies the first row o f the font.

FONT-M IN-BYTE2

An integer that specifies the first byte in a 16-bit font.
In 8-bit fonts, this is the sam e as FONT-MIN-CHAR.

FONT-NAME

A s trin g t h a t n a m e s th e fo n t

FO NT-PROPERTIES

A CLX:FONT-PROPS v a lu e t h a t c o n ta in s a l i s t o f
a d d itio n a l fo n t p r o p e r tie s , a s a lt e r n a t in g k e y w o rd s
a n d in te g e rs .

FONT-PROPERTY

This function requires two arguments: the first is a
CLX: FONT object, the second a keyword nam ing a font
property. The return value is an integer that specifies
the value o f that property.

MAX-CHAR-ASCENT

The largest ascent of any character in the font.

MAX-CHAR-ATTRIBUTES

The largest number o f attributes o f any character in the
font.

MAX-CHAR-DESCENT

The largest descent o f any character in the font.

MAX-CHAR-LEFT-BEARING

The largest left-bearing o f any character in the font.

MAX-CHAR-RIGHT-BEARING

The largest right-bearing o f any character in the font.

(continued on next page)

11-2 Writing Text

Table 11-2 (Cont.):

Information Functions for CLX:FONT Objects

F u n c t io n N a m e

R e t u r n V alue

MAX-CHAR-WIDTH

The largest width o f any character in the font.

M IN-CHÄR-ASCENT

The sm allest ascent o f any character in the font.

MIN-CHAR-ATTRIBUTES

The sm allest number o f attributes owned by any
character in the font.

MIN-CHAR-DESCENT

The sm allest descent o f any character in the font.

MIN-CHAR-LEFT-BEARING

The sm allest left-bearing o f any character in the font.

M IN-CHAR-RIGHT-BEARING

The sm allest right-bearing o f any character in the font.

MIN-CHAR-WIDTH

The sm allest width o f any character in the font.

C lients can compute th e bounding box of the font from the m axim um and
m inim um character m etrics. The upper-left coordinate of th e bounding box whose
origin is a t (r, y) is defined as follows:
(+ x (CLX:MIN-CHAR-LEFT-BEARING font) ) , ( - / (CLX:MAX-CHAR-ASCENT font))

The w idth of the font bounding box is defined as follows:
(+ (CLX:MIN-CHAR-LEFT-BEARING font) (CLX:MAX-CHAR-RIGHT-BEARING font))

The height of the font bounding box is defined as follows:
(+ (CLX:MAX-CHAR-ASCENT font) (CLX:MAX-CHAR-DESCENT font))

The following additional functions a re defined for CLX:FONT objects:
CLX: FONT-DISPLAY

Returns the CLX:DISPLAY object on which the font is open.

C LX :FO N T-ID

Returns the integer resource-id o f the font.

CLX:FONT-EQUAL

Predicate returns true if arguments are identical.

CLX: FONT-P

Predicate returns true i f argument is a CLX: FONT object.

11.2 Specifying Fonts
The font used when draw ing text is specified by the : f o n t slot of the GContext
passed to the draw function. You can provide a font value when you create the
GContext, or you can first open a font and th en set the slot to th a t value. In
eith e r case, you need to know th e nam e of th e font.
The c l x :L I S t - f o n t - n a m e s function re tu rn s a fist of font nam es th a t m atch a
given p a tte rn and the num ber of m atches found. Its form at is:
CLX:LIST-FONT-NAMES display pattern &KEY :MAX-FONTS :RESULT-TYPE
d isp la y

A C LX :D ISPLA Y o b ject.

p a tte rn

A string that specifies the search pattern to be matched by the font
names that are returned.

: MAX-FONTS

An integer that specifies the m aximum number o f font names
returned. The default value is 1024.

: RESULT-TYPE

The LISP type of the return value. The default is ' L IS T .

See the VMS DECwindows Guide to Xlib Programming: MIT C Binding for a
complete list of DECwindows font nam es.

Writing Text

11-3

The c l x :Li s t -f o n t s function re tu rn s “pseudo” fonts th a t contain basic font
m etrics and properties b u t no per-character m etrics and no resource-ids. These
pseudo fonts are autom atically converted to real fonts dynam ically as needed,
by issuing an O penFont protocol request. The form at of the CLX:l i s t -f o n t s
function is:
CLX:LIST-FONTS display pattern &KEY :MAX-FONTS :RESULT-TYPE
d isp la y

A CLX:DISPLAY object.

p a tte rn

A string that specifies the search pattern to be matched by the
names of fonts that are returned.

: MAX-FONTS

An integer that specifies the maximum number of fonts returned.
The default value is 1024.

: RESULT-TYPE

The LISP type o f the return value. The default is ' L IS T .

Once you have a font nam e, use th e C LX:o p e n -f o n t function to load it into LISP
memory. F ont objects m ay be cached and reference counted locally w ithin the
display object. This function m ay not execute a c l x :WITH-d i s p l a y if the font is
cached. The form at of the c l x :o p e n -f o n t function is:
CLX:OPEN-FONT display name
d isp la y

A CLX:DISPLAY object.

nam e

A s t r in g t h a t sp ecifie s t h e fo n t.

Exam ple 11-1 shows how to use c l x :l i s t -f o n t -n a m e s to search for a font whose
nam e m atches a wildcard string. The function o p e n -w i l d c a r d -f o n t opens and
re tu rn s the first font th a t m atches the specified string. If no font nam e m atches
the wildcard, the function re tu rn s n i l .
Example 11-1:

Specifying Fonts

Lisp> (defun open-wildcard-font (display wildcard-string)
(let ((font-list (clx:list-font-names display wildcard-string
:max-fonts 1)))
(when font-list
(clx:open-font display (car font-list)))))
OPEN-WILDCARD-FONT

Lisp> (open-wildcard-font *d* ”*Lubalin*24*")
#<Font -Adobe-ITC Lubalin Graph-Book-R-Normal— 24-240-75-75-P-139-IS08859-l>

This exam ple assum es th a t *D* is a c l x :d i s p l a y object previously retu rn ed by
the CLX: o p e n -d i s p l a y function.
The CLX:d i s c a r d -f o n t - i n f o function discards any sta te th a t can be reobtained
w ith a QueryFont request. This is simply a perform ance h in t for m em ory-lim ited
system s. The form at of this function is:
CLX:DISCARD-FONT-INFO font
w h e r e f o n t is the clx :font object whose state is to be discarded.

The CLX: c l o s e -f o n t function m ay not generate a protocol req u est if the font is
reference counted locally or if it is a pseudo font.
CLX:CLOSE-FONT font
w h e r e f o n t is t h e clx : font o b ject t h a t is n o lo n g e r n e e d e d .

11-4

Writing Text

The c l x :f o n t -p a t h function re tu rn s a list (by default) of strings or pathnam es
th a t show w here the server looks for font files. You can change the search path
w ith s e t f . The form at of the c l x : f o n t -p a t h function is:
CLX:FONT-PATH display &KEY :RESULT-TYPE
d isp la y

A CLX:DISPLAY object.

: RESULT-TYPE

The LISP type o f the return value.

11.3 Computing Text Size
CLX provides functions th a t calculate the w idth and extent of 8-bit strings. To
draw 2-byte strings, you m u st provide a tra n sla te function th a t re tu rn s indexes
into the 2-byte fonts.
The c l x :t e x t -w i d t h function computes the sum of the w idth of each character in
a specified string. Its form at is:
CLX:TEXT-WlDTH font sequence &KEY :START :END TRANSLATE
font

Either a CLX:FONT or a CLX:GCONTEXT object that specifies the font
used.

sequence

A sequence of characters (that is, a string) to measure.

: START a n d
: END

Two integers that specify the first and last characters in the sequence.
The default value for : START is 0; for : END the length of the string.

: TRAN SLATE

A function that translates sequence into font indexes. The default
function is CLX:TRANSLATE-DEFAULT.

The CLX: t e x t -e x t e n t s function computes th e bounding box of a specified string.
Its form at is:
CLX:TEXT-EXTENTS fonts sequence &KEY :START :END TRANSLATE
fon ts

Either a CLX:FONT or a CLX: GCONTEXT object that specifies the font
used.

sequence

A sequence of characters (that is, a string) to measure.

: START a n d

Integers that specify the first and last characters in sequence. The
default for : START is 0; for :END the end o f the sequence.

: END
: TRANSLATE

A function that translates sequence into font indexes. The default
function is CLX: TRAN SLATE-DEFAULT.

The function re tu rn s th e width, ascent, descent, left-bearing, right-bearing,
font-ascent, font-descent, and direction of th e specified string, and an array index
value. The index indicates the position w ithin th e string w here th e translation
failed; if th e entire strin g was translated, th e la st re tu rn value is n i l . The
:t r a n s l a t e function will always be called w ith a 16-bit destination buffer.
You need th e c l x t r a n s l a t e -d e f a u l t function only if you are using two-byte
fonts. Its form at is:
CLXTRANSLATE-DEFAULT src src-start src-end font dst dst-start
src

A sequence o f characters to m easure or draw.

src-start and
src-end

Two CLX:ARRAY-INDEX values that specify the first and last positions in
the source.

fon t

The CLX: FONT object to use.

Writing Text

11-5

dst

A vector that holds the font indexes.

d st-sta rt

A CLX: ARRAY- INDEX v a lu e t h a t sp ecifie s th e s t a r t i n g p o s itio n w ith in th e
d e s tin a tio n .

The dst is guaranteed to have room for (- s r c - e n d s r c - s t a r t ) integer elem ents,
sta rtin g a t dst-start] w hether dst holds 8-bit or 16-bit elem ents depends on
context. If known, font is the current font. The function should tran slate as
m any elem ents of src as possible into indexes in th e c u rren t font, and store them
into dst. The first re tu rn value should be the src index of the first un tran slated
elem ent. If no fu rth er elem ents need to be tran slated , th e second re tu rn value
should be n i l . If a horizontal motion is required before fu rth e r translation, the
second re tu rn value should be the delta in X coordinate. If known, the pixel
w idth of the tra n sla ted tex t can be retu rn ed as the th ird value; th is can allow for
appending of subsequent output to the sam e protocol request if no overall w idth
h a s been specified a t th e higher level.

11.4 Drawing Text on the Screen
In the text-draw ing functions below, if w idth is specified, it is assum ed to be
th e total pixel w idth of w hatever string of glyphs is actually draw n. Specifying
w idth will allow for appending the output of subsequent calls to the same protocol
request, provided GContext h a s not been modified in th e interim . If w idth is not
specified, appending of subsequent output m ay not occur (unless th e tran slate
function re tu rn s th e width). Specifying w idth is simply a hin t, for performance.
The functions in th is section expect th e text to be draw n to be a LISP string. If
you provide your own : t r a n s l a t e function it should ou tp u t a strin g or a vector of
characters, which is effectively the same thing.
The C LX : draw - g l y p h and C LX : d raw - g l y p h s functions draw only pixels set to on in
th e glyph, th a t is, th e foreground b u t not th e background. The C L X : draw - g l y p h
function p ain ts a single character; the C L X : draw - g l y p h s function can handle
strings. The form at of th e C LX : d raw - g l y p h function is:
CLX:DRAW-GLYPH drawable gcontext x y elt
&KEY TRANSLATE WIDTH :SIZE
draw able

The CLX: DRAWABLE object where the glyph will be displayed.

gcontext

The CLX: GCONTEXT object that determ ines the graphics characteristics
o f the glyph. It contains the font.

x an d y

Integers that specify the X and Y coordinates o f the origin of the glyph.

elt

An elem ent (such as a character) to draw.

: TRANSLATE

A function that translates elt into a font index. The default function is
CLX: TRANSLATE-DEFAULT.

: WIDTH

An integer that specifies the width o f the glyph in pixels.

: S IZ E

A CLX: IN D E X -S IZ E value that specifies the size of the font. The default
value is : DEFAULT, which m eans an 8-bit font.

The first re tu rn value is tru e if elt is output, or n i l if th e : t r a n s l a t e function
refuses to output it (for example, if there is no font specified in gcontext). The
second resu lt is the w idth of the glyph displayed, m easured in pixels, if known, or
n i l if unknown.
The form at of the c l x : draw - g l y p h s function is:
CLX:DRAW-GLYPHS drawable gcontext x y sequence
&KEY :START :END TRANSLATE WIDTH :SIZE

11-6

Writing Text

drawable
gcontext

The CLX: DRAWABLE object where the glyphs will be displayed.

x and y

Integers that specify the X and Y coordinates o f the origin of the first
character displayed.

sequence

A sequence of characters (that is, a string) to draw.

: START a n d
:END

Two CLX:ARRAY-INDEX values that specify the first and last positions
within the sequence. The default value for : START is 0. If : END is null,
the length o f the sequence is used.

: TRANSLATE

A function that translates sequence into font indexes. The default
function is CLX: TRANSLATE-DEFAULT.

: WIDTH

An integer that specifies the width o f the glyphs, in pixels.

: S IZ E

A CLX: IN D E X -S IZ E that specifies the size of the font. The default value

The CLX: GCONTEXT object that determines the graphics characteristics
o f the text, such as the font.

is : DEFAULT, w h ic h m e a n s a n 8 -b it fo n t.

The function re tu rn s two values: the first is the new start, if the end was not
reached; th e second is the overall w idth if known.
The c l x : draw - i m a g e - g l y p h and c l x : draw - i m a g e - g l y p h s functions display both
the foreground and background of the character m atrix. This is useful when
w riting over previously displayed text. The form at of the C L X : draw - i m a g e -GLYPH
function is:
CLX:DRAW-IMAGE-GLYPH drawable gcontext x y elt
&KEY TRANSLATE WIDTH :SIZE

drawable
gcontext

The CLX:DRAWABLE object where the glyph will be displayed.

x and y
elt

Integers that specify the X and Y coordinates of the origin o f the glyph.
An item (that is, a character) to draw.

: TRANSLATE

A function that translates elt into a font index. The default function is

The CLX: GCONTEXT object that determines the graphics characteristics
o f the glyph. It contains the font.

CLX: TRANSLATE-DEFAULT.
: WIDTH

An integer that specifies the width o f the glyph, in pixels.

: S IZ E

A CLX: IN D E X -S IZ E value that specifies the size o f the font. The default
v a lu e is : DEFAULT, w h ic h m e a n s a n 8 -b it fo n t.

The function re tu rn s two values. The first is T if elt is output, n i l if the
translate function refuses to output it. The second resu lt is the overall width, if
known. The : translate function m ay specify a new font.
The form at of th e c l x :d r a w - i m a g e -g l y p h s function is:
CLX:DRAW-IMAGE-GLYPHS drawable gcontext x y sequence
&KEY :START :END WIDTH TRANSLATE :SIZE

drawable

The CLX: DRAWABLE object where the glyphs will be displayed.

gcontext

The CLX: GCONTEXT object that determines the graphics characteristics
o f the glyphs, such as the font.

x andy

Integers that specify the X and Y coordinates o f the origin o f the first
character displayed.

sequence

A sequence of item s (that is, a string) to draw.

: START and
:END

Two CLX:ARRAY-INDEX values that specify the first and last positions
within the sequence. The default value for : START is 0. If : END is null,
the length o f the sequence is used.

Writing Text

11-7

: WIDTH

An integer that specifies the width o f the glyphs, in pixels.

: TRANSLATE

A function that translates s e q u e n c e into font indexes. The default
function is CLX: TRANSLATE-DEFAULT.

:SIZE

A CLX: INDEX-SIZE value that specifies the size of the font. The default
value is :DEFAULT, m eaning an 8-bit font.

The first re tu rn value is the new s ta rt if :END was not reached. The second resu lt
is overall w idth if known.
Exam ple 11—2 shows th e difference betw een CLX:d r a w -g l y p h s and
CLX:DRAW-IMAGE-GLYP HS.

Example 11-2:

Drawing Text

(defun clx-text-example (Soptional (machine (machine-instance)))
(let* ((d (clx:open-display machine))
(s (first (clx:display-roots d)))
(r (clx:screen-root s))
(black-pixel (clx:screen-black-pixel s))
(white-pixel (clx:screen-white-pixel s ) )
(w (clx:create-window
:parent r :x 10 :y 100
:width 300 :height 100
:background white-pixel
:event-mask '(:button-press)))
(font (clx:open-font
d
(first (clx:list-font-names d
"*times*bold*24*"))))
(gc (clx::create-gcontext :drawable w
:foreground black-pixel
background white-pixel
:font font)))
;; Display the window
(setf (clx:wm-name w) "Drawing Text")
(clx:map-window w)
(clx:display-finish-output d)
;; Make some distracting background
(clx:draw-lines w gc '(0 100 100 0 100 100 200 0 200 100 300 0))
;; Draw some text
(clx:draw-glyphs w gc 10 40 "These are glyphs.")
(clx:draw-image-glyphs w gc 10 80 "These are image-glyphs.")
(clx:display-force-output d)
(clx:event-case
(d :force-output-p t)
(button-press ()
(clx:destroy-window w)
t))
(clx:display-force-output d)))

Figure 11-1 shows th e output of this example on a system w here th e first font
th a t m atches "*times*bold*24*" is:
" -Adobe-Times-Bold-R-Normal— 24-240 -7 5 -7 5 -P-1 3 2 - I S088 5 9 -1 "

D epending on which fonts are loaded on your system and th e order in which they
were loaded, Exam ple 11—2 m ay not ru n on y o u r system , o r m ay not produce the
sam e results.

11-8

Writing Text

Figure 11-1:

■■
■■

Drawing Text

Ü H/

T hese ar e glyphs.

T hese ar e im a g e -j glyphs.

i/
M LO -0 0 3 39 4

Writing Text

11-9

Chapter 12

Event Functions

An event is a report from the X server. E vents indicate eith er a change in the
sta te of a device (such as a mouse b utton being pressed) or th e execution of a
routine called by a client (such as a window being mapped). W hen an event
occurs, CLX notifies in terested clients by placing inform ation about the event in a
queue. The visible window th a t contains the pointer cursor w hen an event occurs
is called th e source window. CLX searches th e window hierarchy upw ard from
th e source window until one of the following applies:
•

CLX finds a window in which one or m ore clients have selected th a t event
type. This window is called the event window. A fter CLX locates a n event
window, it sends inform ation about the event to th e appropriate clients.

•

CLX finds a window whose :D O - n o t - p r o p a g a t e - m a s k component h a s been set
by a client to include th a t event type. S etting this component specifies th a t
CLX should not notify clients about events occurring in th e window and its
children.

•

CLX reaches the top of th e window hierarchy w ithout finding an event
window.

The CLX event routines allow client program s to select th e types of events they
w an t to be informed of and to m anage event processing. This chapter explains
how to perform th e following operations:
•

Select the event types to be reported to your window.

•

Process events reported by CLX.

•

Control which clients are notified of device events.

•

Send an event to a window.

The la st section in this chapter provides a n alphabetical reference to each event
type.

12.1

Selecting Events
CLX can report 33 types of events related to keyboards, mice, windowing, and
graphics operations. Table 12-1 lists the event types, grouped by category.
Usually, CLX sends inform ation about an event only to clients th a t have specified
an in te rest in th a t event type. C lients use one of the following m ethods to select
th e event types in which they are interested:
*

Specifying an event m ask w hen creating a window w ith c l x : c r e a t e - w in d o w .

•

Changing a window’s event m ask w ith s e t f or c l x :W IT H - s t a t e .

Event Functions

12-1

•

C reating or changing the graphics exposure m ask of a graphics context.

Five events, however, are useful to alm ost all clients and are reported regardless
of event m asks. CLX reports client m essages, m apping notifications, selection
clearings, selection notifications, and selection requests to all clients.
Table 12-1:

Event Keys

C lie n t C o m m u n ic a tio n E v e n ts

K e y b o a r d E v e n ts

W in d o w C r o s s i n g E v e n ts

:CLIENT-MESSAGE
:PROPERTY-NOTIFY
:SELECTION-CLEAR
:SELECTION-NOTIFY
:SELECTION-REQÜEST

: KEY-PRESS
: KEY-RELEASE

: ENTER-NOTIFY
: LEAVE-NOTIFY

K e y m a p S ta te E v e n ts

W in d o w S ta te E v e n ts

:KEYMAP-NOTIFY

:CIRCULATE-NOTIFY
:CONFIGURE-NOTIFY
:CREATE-NOTIFY
:DESTROY-NOTIFY
:GRAVITY-NOTIFY
:MAP-NOTIFY
:REPARENT-NOTIFY
:UNMAP-NOTIFY
:VISIBILITY-NOTIFY

C o lo r m a p S ta te E v e n ts

:COLORMAP-NOTIFY
E x p o s u r e E v e n ts
: EXPOSURE
: GRAPHICS-EXPOSURE
: NO-EXPOSURE

In p u t F o c u s E v e n ts
: FO CU S-IN
: FOCUS-OUT

P o in t e r E v e n ts
: BUTTON-PRESS
: BUTTON-RELEASE
: MOTION-NOTIFY

S tr u c tu r e C o n tr o l E v e n ts
: CIRCULATE-REQUEST
: CONFIGURE-REQUEST
: MAP-REQUEST
: RESIZE-REQU EST

See Section 12.5 for details on w hat inform ation is reported for each event type.
Sections 12.1.1 through 12.1.3 dem onstrate how to create, specify, and change an
event m ask. For m ore inform ation about specifying th e : EXPOSURE component of
a GContext, see C hapter 7.

12.1.1

Constructing Event Masks
E vent m asks are used to specify which event types are reported to a client.
Table 12-2 lists th e event m ask keywords provided by CLX w ith the
corresponding event types. An event m ask of 0 specifies th a t no events are
requested.

Table 12-2:

Event Masks

K eyw ord

E v e n ts R e p o r t e d (E vent Type)

: BUTTON-MOTION

At least one button on the pointing device is pressed while the pointer
moves (:MOTION-NOTIFY).

: BUTTON- 1 -MOTION

Button 1 of the pointing device is pressed while the pointer moves
(:M OTION-NOTIFY).

: B U T T 0N -2-M 0T I0N

Button 2 of the pointing device is pressed while the pointer moves
(:M OTION-NOTIFY).

: BUTTON-3-MOTION

Button 3 of the {jointing device is pressed while the pointer moves
(:M OTION-NOTIFY).

: BUTTON-4-MOTION

Button 4 of the pointing device is pressed while the pointer moves
(:M OTION-NOTIFY).

(continued on next page)

12-2

Event Functions

Table 12-2 (Cont.):

Event Masks

K eyw ord

E v e n ts R e p o r t e d (E vent Type)

: BUTTON- 5 -MOTION

B u tto n 5 o f th e p o in tin g d ev ic e is p re s s e d w h ile t h e p o in te r m o v es
(:M OTION-NOTIFY).

: BUTTON-PRESS

A b u tto n o n t h e p o in tin g d e v ic e is p re s s e d (: BUTTON-PRESS).

: BUTTON-RELEASE

A b u tto n o n t h e p o in tin g d e v ice is r e le a s e d ( : BUTTON-RELEASE).

: COLORMAP-CHANGE

A c lie n t in s ta l ls , c h a n g e s , o r re m o v e s a c o lo rm a p ( : COLORMAP-NOTIFY).

: ENTER-WINDOW

T h e p o in te r e n te r s a w in d o w ( : ENTER-NOTIFY).

: EXPOSURE

A w in d o w b e c o m e s v is ib le , a g ra p h ic s re g io n c a n n o t b e c o m p u te d , a
g ra p h ic s r e q u e s t e x p o se s a re g io n , o r a ll so u rc e s a r e a v a ila b le a n d
a n o ex p o se e v e n t is g e n e r a te d ( : EXPOSURE, : GRAPHICS-EXPOSURE,
: NO-EXPOSURE).

: FOCUS-CHANGE

T h e k e y b o a rd focus c h a n g e s (:F O C U S -IN , : FOCUS-OUT).

: KEYMAP-STATE

T h e k e y m a p c h a n g e s ( : KEYMAP-NOTIFY).

:K EY -PRESS

A k e y o n t h e k e y b o a rd is p re s s e d ( : KEY-PRESS).

: KEY-RELEASE

A k e y o n t h e k e y b o a rd is r e le a s e d ( : KEY-RELEASE).

: LEAVE-WINDOW

T h e p o in te r le a v e s a w in d o w ( : LEAVE-WINDOW).

: OWNER-GRAB-BUTTON

A u to m a tic g r a b s sh o u ld a c tiv a te w ith : OWNER-P s e t to T (n o e v e n t ty p e).

: POINTER-MOTION

T h e p o in te r m o v e s (:M 0 T I0 N -N 0 T IF Y ).

: PO INTER-M O TION -H INT

CLX is fre e to r e p o r t o n ly o n e p o in te r m o tio n e v e n t ( :MOTION-NOTIFY)
u n ti l o n e o f t h e fo llo w in g o ccu rs:
•

E it h e r t h e k e y o r b u tto n s t a te c h a n g e s.

•

T h e p o in te r le a v e s t h e w indow .

•

T h e c lie n t c a lls CLX:QUERY-POINTER o r CLX:MOTION-EVENTS.

: PROPERTY-CHANGE

A c lie n t c h a n g e s a p r o p e r ty ( :PROPERTY-NOTIFY).

: R ESIZE -R E D IR E C T

A n o th e r c lie n t c h a n g e s th e size o f a w in d o w ( : RESIZE-REQU EST).

: STRUCTURE-NOTIFY

O n e o f t h e fo llo w in g o p e ra tio n s o c c u rs o n a w in d o w :
•

: SUBSTRUCTURE-NOTIFY

C irc u la te ( : CIRCULATE-NOTIFY)

•

C o n fig u re (:CO N FIGU RE-NO TIFY)

•

D e s tro y (:DESTRO Y -NO TIFY)

•

M a p ( : MAP-NOTIFY)

•

M o v e ( : GRAVITY-NOTIFY)

•

R e p a r e n t ( : REPARENT-NOTIFY)

•

U n m a p (:UNMAP-NOTIFY)

O n e o f t h e fo llo w in g o p e ra tio n s o cc u rs o n a c h ild o f a w in d o w :
•

C irc u la te ( : CIRCULATE-NOTIFY)

•

C o n fig u re (:CO N FIGU RE-NO TIFY)

•

D e s tro y (:DESTRO Y -NO TIFY)

•

M a p ( : MAP-NOTIFY)

•

M o v e ( : GRAVITY-NOTIFY)

•

R e p a r e n t ( : REPARENT-NOTIFY)

•

U n m a p (:UNMAP-NOTIFY)

(continued on next page)

Event Functions

12-3

Table 12-2 (Cont.):

Event Masks

K eyw ord

E v e n ts R e p o r t e d (E vent Type)

: SUBSTRUCTURE-REDIRECT

Another client performs one of the following operations on a window:
• Circulate (:CIRCULATE-REQUEST)
• Configure (: CONFIGURE-REQUEST)
• M ap ( : MAP-REQUEST)

: V ISIB IL IT Y -C H A N G E

The visibility of a window changes (:V IS IB IL IT Y -N O T IF Y ).

E vent m asks are encoded as CLX:MASK32 values by the c l x : m a k e - e v e n t - m ask
function and are deciphered by the c l x : m ake - e v e n t - k e y s function. These
functions are defined only for core events (events th a t are listed in Table 12—1).
The form at of the CLX: m a k e - e v e n t - m a sk function is:
CLX:MAKE-EVENT-MASK &REST keys

w here keys is a list of event m ask keywords shown in Table 12—2. The function
re tu rn s a c l x : MASK32 value th a t m ay be used to specify the event m ask of a
window (see Section 12.1.2) or passed to th e c l x : g r a b - p o i n t e r , c l x : g r a b - b u t t o n ,
and c l x : s e n d - e v e n t functions (see Sections 12.3 and 12.4).
The form at of the c l x : m a k e - e v e n t - k e y s function is:
CLX:MAKE-EVENT-KEYS event-mask
w h e r e event-mask i s a CLX:MASK32 v a l u e o r i g i n a l l y r e t u r n e d b y t h e
C LX : m a k e - e v e n t - m a sk function. The function re tu rn s a list of the event keys

coded in the event m ask. For example:
Lisp>

(clx:make-event-mask :button-press :exposure)

32772

Lisp>

(clx:make-event-keys 32772)

( : BUTTON-PRESS

12.1.2

: EXPOSURE)

Specifying an Event Mask
Tb specify which event types you are in terested in when creating a window,
provide a CLX:MASK32 value or a list of event m ask keywords as th e value of
the : e v e n t - m a sk keyword of the c l x : c r e a t e - w in d o w function. For example,
the following fragm ent from Exam ple 4 -1 specifies th a t the client program is
in terested in exposure and button press events:

(let* ( . . . )
(window (clx:create-window :parent (clx:screen-root screen)
:event-mask '(:exposure :button-press)))

)

• . •

12.1.3

Changing an Event Mask
To c h a n g e t h e e v e n t s e l e c t i o n o f a w in d o w , u s e a s e t f f o r m , w i t h i n a
c l x : w i t h - s t a t e m acro if you prefer. The example below adds key press events to
th e event m ask of the window created in Section 12.1.1:

(setf (clx:window-event-mask window) '(exposure :button-press :key-press))

The next example m akes th e sam e change to the event m ask b u t uses the
CLX:W ITH-STATE macro:
12-4

Event Functions

(clx:with-state (window)
(setf (window-event-mask window) ' (:exposure :button-press :key-press))

...

)
Using the CLX: w i t h - s t a t e macro improves perform ance w hen several window
accessors are used.

12.2 Processing Events
Clients have one event queue for each display connection, not one for each
window. Events in different windows on th e sam e display are interleaved in
th e event queue. Figure 12—1 shows two CLX-created windows, a fragm ent of
code, and a representation of an event queue. W hen a u ser moves th e pointer
cursor from th e larg er window to the sm aller one and clicks a button, the events
generated include : m o t i o n - n o t i f y and :LEAVE - n o t i f y in th e larger window and
: ENTER-NOTIFY, : KEYMAP-NOTIFY, : BUTTON-PRESS, : EXPOSURE, : BUTTON-RELEASE,

and : f o c u s - i n in the sm aller window. However, the windows’ event m asks filter
out all but the : b u t t o n - p r e s s and : e x p o s u r e events in th e sm aller window.
Figure 12-1:

The Event Queue

(clx:Greate-window : p a ren t *root*
:x 300 :y 100 : w idth 600 :h e ig h t 500
:background (c lx :sc re e n -w h ite -p ix e l *screen*)
:event-mask ' ( : exposure :k e y -p re ss))
(clx:create-w indow :p a re n t *root*
:x 100 :y 200 :w idth 400 ’.h e ig h t 300
:background (c lx :sc re e n -w h ite -p ix e l *screen*)
: evrent-mnsk ' (exposure :b u tt on—
p re ss) )

The routines in this section allow you to perform th e following operations:
•

Lock the event queue.

•

Find th e length of the queue.

Event Functions

12-5

12.2.1

•

H andle events in th e queue.

•

Add an event to the queue.

•

Remove an event from th e queue.

Locking the Event Queue
The CLX: w it h - e v e n t - q u e u e m acro locks th e event queue s o th a t your client h as
exclusive access. Its form at is:
CLX:WITH-EVENT-QUEUE display &BODY forms
display

A CLX:DISPLAY o b ject.

form s

One or more LISP forms to be executed while the event queue is locked.

A c a ll t o t h e CLX:w i t h - e v e n t - q u e u e m a c r o i s i m p l i c i t i n t h e s e t w o f u n c t i o n s a n d
m acro : c l x : event- l is t e n , c l x : pr o c e ss - ev en t, a n d c l x : ev ent- c a se.

12.2.2

Finding the Length of the Event Queue
The c l x : e v e n t - l i s t e n function re tu rn s the num ber of events queued for a
display. Its form at is:
CLX:EVENT-LISTEN display &OPTIONAL timeout
display

A CLX:DISPLAY o b ject.

tim eout

A number that specifies how long to wait for the event, or N IL . The default
value is zero.

c l x : e v e n t - L i s t e n w aits for events to occur, eith er forever if timeout is n i l , or for
th e specified num ber of seconds. The function re tu rn s n i l if the queue is em pty
and re tu rn s im m ediately if timeout is zero.

12.2.3

Handling Events in the Queue
CLX p r o v i d e s a b o t h a f u n c t i o n ,

c lx :p r o c e s s -e v e n t, a n d a m a c ro ,

c l x : e v e n t - c a s e , for handling

events. C lients can obtain events, in order,
and either remove them from th e queue after handling or leave them in place.
The form at of the c l x :P R O C E S S - e v e n t function is:
CLX:PROCESS-EVENT display &KEY HANDLER TIMEOUT :PEEK-P :DISCARD-P
:FORCE-OUTPUT-P :EVENT

12-6

display

A C LX :D ISPLA Y object.

: HANDLER

A function that is applied to the events in the queue.

: TIMEOUT

A number that specifies how many seconds to wait for an event.

: PEEK -P

Has a CLX: BOOLEAN value that specifies whether events are left on
the queue after they are processed.

: DISCARD-P

Has a CLX: BOOLEAN value that specifies whether events for which
the : HANDLER function returns N IL are removed from the queue.

: FORCE-OUTPUT-P

Has a CLX:BOOLEAN value that specifies whether the
CLX: DISPLAY-FORCE-OUTPUT function is called before this function
begins execution. The default value is T.

Event Functions

A DWT: EVENT value, or NIL. If a value is provided, the

:EVENT

CLX:PROCESS-EVENT function handles that event rather than
querying the event queue.
I f : FORCE-OUTPUT-P is true, CLX:DISPLAY-F0RCE-OUTPUT is in v o k e d b e fo re any
e v e n ts a re p ro cessed . T h e : handler fu n ctio n is in v o k e d on e a ch e v e n t in the
q u e u e u n til it re tu r n s non-NlL. T h e o b je c t th a t th e h a n d le r r e tu r n s is th en
r e tu r n e d b y th e clx:process-event fu nction. T h e v a lu es o f :PEEK-P and
:discard-p d e te r m in e w h a t h a p p e n s to ev en ts: I f :PEEK-P is true, th e ev en t
th a t r e tu r n e d non-NlL r e m a in s on th e q u eu e; i f : discard-p is true, all e v e n ts for
w h ich th e h a n d le r re tu r n s NIL a re r e m o v e d from th e queue. O th erw ise, th ey are
le ft in place. clx:PROCESS-event h a n g s u n til a non-NlL v a lu e is re tu r n e d fo r an
e v e n t o r u n til th e n u m b e r o f s e c o n d s sp e c ifie d b y : timeout h a v e elap sed . T h e
fu n ctio n r e tu r n s nil on tim eou t.

The argum ents to the :HANDLER function are described fu rth e r in Section 12.5.
Exam ple 12-1 shows how to use th e CLX: PRO CESS-EVENT function to p rin t the
contents of an event queue.

Example 12-1:

Using the CLX:PROCESS-EVENT Function

(defun print-queue (display)
(clx:process-event display :handler #'print-event
:discard-p nil
:timeout 0))
(defun print-event (&key event-key)
(print event-key)
nil)

The : HANDLER function, p r i n t -e v e n t , never re tu rn s true, so : TIMEOUT m u st be set
to zero, c l x :p r o c e s s-e v e n t is guaran teed to look through the entire queue once.
If c l x :p r o c e s s -e v e n t is invoked recursively, th e nested invocation begins w ith
the event a fter the one currently being processed.
The format of the CLX:e v e n t - c a s e macro is:
CLX:EVENT-CASE d isplay
&KEY TIMEOUT :PEEK-P :DISCARD-P :FORCE-OUTPUT-P
&BODY cla u ses
d isp la y

A CLX:DISPLAY object.

:TIMEOUT

A number that specifies how many seconds to wait until
CLX:EVENT-CASE returns; or NIL, meaning until one of the clauses
returns non-NIL.

:PEEK-P

Has a CLX:BOOLEAN value that specifies whether events are left on
the queue.

:DISCARD-P

Has a CLX:BOOLEAN value that specifies whether events for which
the handler returns NIL are removed from the queue.

:FORCE-OUTPUT-P

Has a CLX:BOOLEAN value that specifies whether the
CLX: DISPLAY-FORCE-OUTPUT function is called before this function
starts reading events from the queue. The default value is true.

clauses

Specify the event keys and the LISP forms to be executed when the
events occur.

Event Functions

12-7

The clauses have th e following syntax:

(event-key \ ({event-key}*) ({arg}* | {(arg vat)}*) forms )
event-key

An event key shown in Table 12—1. The names may be typed as variables
or as keywords.

arg

An argument appropriate to the event key, as listed in Section 12.5.

va r

A variable you want to be bound to the event key argument.

form s

One or more LISP forms to be executed for the event.

The following fragm ent illu strates a call to CLX: e v e n t -c a s e w ith a single clause:
(clx:event-case (*my-display*)
;; | event-key
| ({arg}*)
|
forms
|
(:button-press (window x y) (if (member window *my-window-list*)
(progn (move-cursor x y) t) nil)))

This exam ple uses three components of a : button-press event: the window and
the X and Y coordinates of the pointer cursor. If the window is a m em ber of
th e set nam ed by *MY-window-list*, th e user-defined function move-cursor is
passed the X and Y coordinates. The clause re tu rn s nil s o th a t event processing
continues.
The la s t clause in a c l x : e v e n t -c a s e m ay contain T or o t h e r w i s e in place of an
event key. If you do not provide such a clause, th e im plicit clause (otherwise
nil) is used.
Exam ple 12—2 is a portion of the file BLACKBOARD.LSP, which is in the
LISP$EXAMPLES directory.

Example 12-2:

Using the CLX:EVENT-CASE Macro

;;Now we go into the event-case, which sits at the event queue
;;and processes button events. When a keyboard event occurs, it
;;exits the loop.
(clx:event-case
(♦blackboard-display* :discard-p t)
(:exposure (window)
;; This is a simple way to handle the exposure -- just
;; r e d r a w our ent i r e line-list.

(when (eq window *blackboard-window*)
(clx:draw-segments *blackboard-window*
♦blackboard-gcontext*
*blackboard-line-list*)))
(:button-press (x y code)
(case code ;this tells which button was pushed
(1 (clx:draw-point *blackboard-window*
♦blackboard-gcontext*
(setq old-x last-x last-x x)
(setq old-y last-y last-y y))
(setq last-button 1))
(2 (draw-and-record-line last-x last-y
(setq old-x last-x last-x x)
(setq old-y last-y last-y y))
(setq last-button 2))
(3 (if (= last-button 3)
(clx:clear-area *blackboard-window*)
(progn
(undraw-and-unrecord-1ine
old-x old-y last-x last-y)
(setq last-x old-x last-y old-y)))

(continued on next page)
12-8

Event Functions

Example 12-2 (Cont.):

Using the CLX:EVENT-CASE Macro

(setq last-button 3)))
nil);this tells event-case not to exit
(:key-press () t)/pressing a key returns t, thus exiting event-case

)))

12.2.4 Adding an Event to the Queue
The form at of th e c l x :q u e u e -e v e n t function is:
CLX:QUEUE-EVENT d isplay e v e n t-k e y
&REST args
&KEY :APPEND-P
&ALLOW-OTHER-KEYS
d isp la y

A CLX:DISPLAY object.

event-key

A CLX: EVENT-KEY value.

args

Keyword-value pairs that specify information appropriate to the event-key
(see Section 12.5).

:APPEND-P

Has a CLX:BOOLEAN value that determines whether the event is put at the
tail of the queue (if true) or head.

A dditional keyword argum ents depend on event-key and are as specified in
Section 12.5.

12.2.5 Removing an Event from the Queue
The c l x :D i s c a r d -c u r r e n t -e v e n t function deletes the event a t the head of the
queue. Its form at is:
CLX:DISCARD-CURRENT-EVENT d is p la y

w here display is a CLX:DISPLAY object. The c l x :d i s c a r d -c u r r e n t -e v e n t function
re tu rn s T if it succeeded; NIL if th e queue was empty. For example:

12.3

Lisp>
27

(clx:event-listen *display*)

Lisp>

(clx:discard— c u r r e n t — eve n t

T
Lisp>
26

(clx:event-listen *display*)

^display*)

Controlling Events
A client m ay “grab” exclusive use of th e keyboard, keyboard keys, pointer, pointer
buttons, or server. The keyboard or pointer can be explicitly grabbed by calling
th e c l x :g r a b -k e y b o a r d or CLX:g r a b -p o i n t e r function: th is is called an active
grab. A particu lar key or b utton can be passively grabbed in a particu lar window:
th e grab activates w hen the key or b utton is actually pressed. W hen a device
is actively grabbed, keyboard or pointer events are reported to the client th a t
established th e grab ra th e r th a n th e client th a t owns the event window. If the
grab places the keyboard or pointer in asynchronous mode, fu rth e r keyboard
or pointer events continue to be processed. If the keyboard or pointer is in
synchronous mode, no fu rth e r events are processed u n til the grabbing client

Event Functions

12-9

allows them (see Section 12.3.4). The keyboard or pointer is “frozen” during a
synchronous grab. Actual keyboard or pointer changes are not lost while the
device is frozen: they are sim ply queued for la te r processing. The event th a t
triggered th e grab can also be replayed.
W hen the server is grabbed, no requests from other clients are processed.
G rabbing the server is highly discouraged.
Several of th e functions in th is section tak e a pointer event, state, or modifier
m ask argum ent. Tables 12-3 through 12—5 list the valid keywords for these
argum ents.

Table 12-3:

Pointer Event Masks

:BUTTON-MOTION
:BUTTON-l-MOTION
:BUTTON-2-MOTION
:BUTTON-3-MOTION
:BUTTON-4-MOTION

Table 12-4:
:SHIFT
:LOCK
:CONTROL

Table 12-5:
:SHIFT
:LOCK

BUTTON-5-MOTION
BUTTON-PRESS
BUTTON-RELEASE
ENTER-WINDOW

KEYMAP-STATE
LEAVE-WINDOW
POINTER-MOTION
POINTER-MOTION-HINT

State Masks
MOD-1
MOD-2
MOD-3
MOD-4
MOD-5

BUTTON-1
BUTTON-2
BUTTON-3
BUTTON-4
BUTTON-5

Modifier Masks
:CONTROL
:MOD-1

:MOD-2
:MOD-3

:MOD-4
:MOD-5

Like event m asks, state m asks are encoded as c l x :MASK16 values w ith the
CLX:MAKE-s t a t e -m a s k function and a re deciphered w ith th e CLX:m a k e -STATE-KEYS
function. The form at of the c l x :m a k e -s t a t e -m a s k function is:
CLX:MAKE-STATE-MASK &REST k e y s

w here keys are CLX: s t a t e -m a s k -k e y s values. The function re tu rn s a CLX:MASK16
value th a t m a y b e passed to the c l x :m a k e -s t a t e -k e y s and c l x :g r a b -b u t t o n
(:m o d i f i e r argum ent) functions.
The form at of th e c l x :m a k e -s t a t e -k e y s function is:
CLX:MAKE-STATE-KEYS s ta te -m a s k

w here state-mask is a c l x :MASK16 value th a t encodes a state m ask. The function
re tu rn s a list of c l x :s t a t e -m a s k -k e y values. For example:
Lisp> (clx:make-event-mask :button-1 :shift :lock)
259
Lisp> (clx:make-event-keys 259)
(: SHIFT -.LOCK :BUTTON-1)

12-10

Event Functions

12.3.1

Grabbing the Pointer
The functions in this section allow you to control in p u t from the pointer,
which is usually a m ouse. The pointer m ay be actively grabbed by calling the
CLX: g r a b -p o i n t e r function or passively grabbed by calling the c l x :g r a b -b u t t o n
function. Passive grabs are convenient for im plem enting reliable pop-up m enus.
For example, you can guarantee th a t the pop-up is m apped before th e pointer
button is released by grabbing th e button and requesting synchronous behavior.
The b u tton press will trigger the grab and freeze fu rth e r event reporting until
you can m ap the pop-up window. W hen you th en allow fu rth e r event processing,
the b utton release will be correctly processed relative to the pop-up window.
The form at of th e c l x :g r a b -p o i n t e r function is:
CLX:GRAB-POINTER w in d ow e v e n t-m a s k
&KEY :OWNER-P :SYNC-POINTER-P :SYNC-KEYBOARD-P
:CONFINE-TO :CURSOR :TIME
w in dow

The CLX:WINDOW within which the client grabs the pointer.

event-m ask

The CLX:POINTER-EVENT-MASK value that specifies for which
events the client iB notified.

:OWNER-P

Has a CLX:BOOLEAN value that specifies whether all pointer
events are reported to the client. When false, pointer events are
reported only when they occur in w in d o w and are selected by its
event mask.

:SYNC-POINTER-P

Has a CLX:BOOLEAN value that specifies whether pointer events
are processed synchronously.

:SYNC-KEYBOARD-P

Has a CLX:BOOLEAN value that specifies whether keyboard events
are processed synchronously.

:CONFINE-TO

Either has a CLX: WINDOW value that specifies the window to
which the pointer cursor is confined, or is null, meaning that the
cursor can move to any window.

:CURSOR

Either has a CLX:CURSOR value that specifies the cursor’s shape
during the grab, or is null, meaning that the cursor does not
change during the grab.

:TIME

Has a CLX:TIMESTAMP value that specifies the time at which
events are to be released.

The function re tu rn s a keyword th a t indicates th e grab sta tu s of th e pointer
cursor. The possible values are : g r a b -s u c c e s s , :a l r e a d y -g r a b b e d , :g r a b -f r o z e n ,
:GRAB-INVALID-TIME, and : GRAB-NOT-VIEWABLE.
The form at of th e c l x :g r a b -b u t t o n function is:
CLX:GRAB-BUTTON w in d ow button e v e n t-m a s k
&KEY MODIFIERS :OWNER-P :SYNC-POINTER-P
:SYNC-KEYBOARD-P :CONFINE-TO :CURSOR
w in dow

The CLX:WINDOW object within which the client grabs the pointer
button.

button

An integer that specifies which button is grabbed, or the keyword
:ANY.

event-m ask

The CLX:POINTER-EVENT-MASK value that specifies for which
events the client is notified.

:MODIFIERS

Has a CLX:MODIFIER-MASK value that specifies which keyboard
modifiers are grabbed. The default value is zero.

Event Functions

12-11

:OWNER-P

:SYNC-POINTER-P

Has a CLX:BOOLEAN value that specifies whether pointer events
are processed synchronously.

:SYNC-KEYBOARD-P

Has a CLX:BOOLEAN value that specifies whether keyboard events
are processed synchronously.

:CONFINE-TO

Either has a CLX:WINDOW value that specifies the window to
which the pointer cursor is confined, or is null, meaning that the
cursor can move to any window.

:CURSOR

Either has a CLX:CURSOR value that specifies the cursor that is
displayed during the grab, or is null, meaning that the shape does
not change.

The CLX:u n g r a b -p o i n t e r and c l x :u n g r a b -b u t t o n functions release pointer and
button grabs, respectively. The form at of the c l x :u n g r a b -p o i n t e r function is:
CLX:UNGRAB-POINTER d is p la y &KEY :TIME
d isp la y

The CLX:DISPLAY whose pointer cursor is to be released.

:TIME

Has a CLX: TIMESTAMP value that specifies when pointer events are released.

The format of the c l x :u n g r a b -b u t t o n function is:
CLX:UNGRAB-BUTTON w in d ow button &KEY MODIFIERS
w indow

The CLX:WINDOW object within which the client releases the pointer
button.

button

An integer that specifies which button is released, or the keyword :ANY.

:MODIFIERS

Has a CLX:MODIFIER-MASK value that specifies which keyboard
modifiers are released. The default value is zero.

Use the c l x :c h a n g e -a c t i v e -p o i n t e r -g r a b function to change th e event m ask or
cursor of an ongoing pointer grab. Its form at is:
CLX:CHANGE-ACTIVE-POINTER-GRAB d is p la y e v e n t-m a s k
&OPTIONAL cu rsor tim e
d isp la y

The CLX:DISPLAY whose active pointer grab is changed.

event-m ask

The CLX:POINTER-EVENT-MASK that specifies for which events the
client is notified.

cursor

NIL or the CLX: CURSOR that specifies the shape of the cursor that is

tim e

A CLX:TIMESTAMP that specifies when the grab is changed.

displayed. If no value is provided, the cursor shape does not change.

The specified time m u st be no earlier th a n th e tim e a t which the grab was
established, and no la te r th a n the cu rren t server tim e.

12.3.2

Grabbing the Keyboard
The keyboard m ay be actively grabbed by calling th e c l x : g r a b -k e y b o a r d function;
individual keys or com binations of keys m ay be passively grabbed by calling the
c l x :g r a b -k e y function. The form at of th e c l x : g r a b -k e y b o a r d function is:
CLX:GRAB-KEYBOARD w in d o w
&KEY :OWNER-P :SYNC-POINTER-P :SYNC-KEYBOARD-P :TIME

12-12

Event Functions

w in dow

The CLX: WINDOW within which the keyboard is grabbed.

:OWNER-P

Has a CLX:BOOLEAN value that specifies whether all keyboard
events are reported to the client. When false, keyboard events are
reported only when they occur in w in d o w and are selected by its
event mask.

:SYNC-POINTER-P

Has a CLX:BOOLEAN value that specifies whether pointer events
are processed synchronously.

:SYNC-KEYBOARD-P

Has a CLX:BOOLEAN value that specifies whether keyboard events
are processed synchronously.

:TIME

Has a CLX:TIMESTAMP that specifies when the grab is established.

The function returns a keyword th at indicates th e statu s of the grab:
:GRAB-SUCCESS, :ALREADY-GRABBED, :GRAB-FROZEN, :GRAB-INVALID-TIME, or
:GRAB-NOT-VIEWABLE.

The form at of the CLX: grab-key function is:
CLX:GRAB-KEY w in d ow k e y
&KEY MODIFIERS :OWNER-P :SYNC-POINTER-P :SYNC-KEYBOARD-P
w in dow

The CLX:WINDOW object in which the key is grabbed.

key

An INTEGER or : ANY and specifies the key that is grabbed.

:MODIFIERS

Has a CLX:MODIFIER-MASK value that specifies which keyboard
modifiers are grabbed. The default value is zero.

:OWNER-P

Has a CLX:BOOLEAN value that specifies whether all keyboard
events are reported to the client. When false, keyboard events
are reported only when they occur in w in d o w and only if they are
selected by event-m ask.

:SYNC-POINTER-P

Has a CLX:BOOLEAN value that specifies whether pointer events
are processed synchronously.

:SYNC-KEYBOARD-P

Has a CLX:BOOLEAN value that specifies whether keyboard events
are processed synchronously.

The CLX: UN grab-keyboard and clx :ungrab-key functions release active and
passive keyboard grabs, respectively. The form at of the clx :ungrab-keyboard
function is:
CLX:UNGRAB-KEYBOARD d is p lay &KEY :TIME
d isp la y

The CLX:DISPLAY whose keyboard is released.

:TIME

Has a CLX:TIMESTAMP that specifies when keyboard events are released.

The form at of the clx:ungrab-key function is:
CLX:UNGRAB-KEY w in d ow k e y &KEY MODIFIERS
w in dow

The CLX:WINDOW in which the keyboard is released.

key

An INTEGER or :ANY and specifies the key that is grabbed.

:MODIFIERS

Has a CLX:MODIFIER-MASK value that specifies which keyboard
modifiers are released. The default value is zero.

Event Functions

12-13

12.3.3

Grabbing the Server
The c l x :g r a b -s e r v e r function allows a client program to take exclusive
possession of the server for a specified display. No requests are processed,
including requests to close connections, while the server is grabbed. A client
autom atically ungrabs the server w hen it closes its connection to th a t server.
Clients should not grab the server any m ore th a n is absolutely necessary.
The format of the c l x :g r a b - s e r v e r function is:
CLX:GRAB-SERVER d is p lay
where display is a c l x :d i s p l a y object.

The form at of the c l x :WITH-s e r v e r -g r a b b e d m acro is:
CLX:WITH-SERVER-GRABBED d is p lay &BODY b o d y
d isp la y

A CLX:DISPLAY object.

body

LISP forms to be executed while the server is grabbed.

The body is not surrounded by a c l x :WITH-d i s p l a y macro.
The CLX:u n g r a b - s e r v e r function releases an active server grab. Its form at is:
CLX:UNGRAB-SERVER d is p lay

w here display is a c l x :d i s p l a y object.

12.3.4

Allowing Events
The c l x :a l l o w -e v e n t s function releases events th a t were queued because a
device was grabbed.
The form at of th e c l x :a l l o w -e v e n t s function is:
CLX:ALLOW-EVENTS d is p la y m o d e &OPTIONAL tim e
d isp la y

The CLX:DISPLAY object whose events are released.

mode

A keyword that specifies which events are released.

tim e

The CLX:TIMESTAMP value that specifies when events are released.

The possible values for the mode argum ent are explained below:

12-14

:ASYNC-POINTER

Allows pointer event processing to continue normally after a
pointer has been stopped.

:SYNC-POINTER

Allows pointer event processing to continue normally after a
pointer has been frozen or grabbed until the next BUTTON-PRESS
or :BUTTON-RELEASE event is reported to the client.

:REPLAY-POINTER

If the pointer is actively grabbed by the client, and is frozen, the
pointer grab is released and the event is completely reprocessed.

:ASYNC-KEYBOARD

Allows keyboard event processing to continue normally after a
keyboard has been frozen.

:SYNC-KEYBOARD

If the keyboard is frozen and actively grabbed by the client,
keyboard event processing continues as usual until the next
KEY-PRESS or : KEY-RELEASE event is reported to the client.

Event Functions

:REPLAY-KEYBOARD

If the keyboard is actively grabbed by the client, and is frozen
as the result of an event having been sent to the client either
from the activation of CLX: GRAB-KEY or from a previous
CLX: ALLOW-EVENTS with m ode : SYNC-KEYBOARD (but not from
a CLX:GRAB-KEYBOARD), the keyboard grab is released and the
event is completely reprocessed.

:ASYNC-BOTH

If the pointer and the keyboard are frozen by the client, event
processing (for both devices) continues normally.

:SYNC-BOTH

If the pointer and keyboard are frozen by the client, event
processing (for both devices) continues normally until the next
BUTTON-PRESS, BUTTON-RELEASE, :KEY-PRESS, or KEY-RELEASE
event is reported to the client for a grabbed device, at which time
the devices again appear to freeze.

12.4 Sending Events
Use th e c l x : s e n d -e v e n t function to send an event to a specified window. The
function identifies th e destination window, determ ines which client should receive
th e event, and ignores any active grabs. The contents of th e event are specified
by additional keyword argum ents, and are not checked or altered by the X server
except th a t the : s e n d -e v e n t component is set to T.
The form at of th e c l x : s e n d -e v e n t function is:
CLX:SEND-EVENT w in d o w e v e n t-k e y e v e n t-m a s k
&REST args
&KEY :PROPAGATE-P :DISPLAY
&ALLOW-OTHER-KEYS
w in dow

A CLX:WINDOW object or a keyword specifying a special window. The
possible keywords are :POINTER-WINDOW and INPUT-FOCUS.

event-key

A CLX:EVENT-KEY or NIL; specifies what kinds of events to generate.

event-m ask

A CLX:EVENT-MASK; if nonzero, sends the event to the client that

args

Keyword-value pairs that contain information about the event being
sent.

:PROPAGATE-P

Has a CLX:BOOLEAN value that specifies whether to propagate the
event to other clients.

:DISPLAY

A CLX:DISPLAY object or NIL.

created the window.

The function re tu rn s t if th e X server successfully generates the event, n i l if the
conversion to th e wire protocol failed.
The valid s r e s t argum ents vary according to th e event-key argum ent. The tables
in Section 12.5 lis t the keywords. If a n event component h as synonyms, supply
a value for only one of them . The fragm ent below illu strates the syntax of the
additional keyword argum ents:
(send-event *application-window* :button-press 0
:state 0
:code 1
:child *application-popup*
:propagate-p t)

This exam ple generates an MB1 press w ith no modifiers in the
* APPLICATION-POPUP* window. For a complete list of components of a
: BUTTON-PRESS event, see Table 12-6.

Event Functions

12-15

The :DISPLAY argum ent is required only if the w i n d o w is :pointer-window or
:INPUT-FOCUS.

12.5 Event Keys
The tables show th e components of each core event reported by CLX. These
components determ ine the argum ents th a t m ay be passed to event-handling
routines such as c l x :Pr o c e s s -e v e n t and c l x :e v e n t -c a s e .

Table 12-6:

:BUTTON-PRESS Event-Key

A rgum ent

Type

M eaning

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argument is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w in dow
. event-window

CLX:BOOLEAN

True ifthe event came from a CLX: SEND-EVENT request.

CLX:WINDOW

The event window (w in d ow and event-window are
synonyms).

root

CLX:WINDOW

The root window in which the event occurred.

ch ild

(OR NULL CLX:WINDOW)

The source window in which the event occurred.

same-screen-p

CLX:BOOLEAN

Indicates whether the event window is on the same screen
as the root window.

INTEGER

The X coordinate of the pointer in the event window.

INTEGER

The Y coordinate of the pointer in the event window.

root-x

INTEGER

The X coordinate of the pointer relative to the root window.

root-y

INTEGER

The Y coordinate of the pointer relative to the root window.

state

CLX:MASK16

The state of buttons and modifier keys just prior to the
event.

tim e

CLX:TIMESTAMP

The time in milliseconds at which the event occurred.

code

INTEGER

The number of the button that was pressed.

Table 12-7:

:BUTTON-RELEASE Event-Key

A rgum ent

Type

M eaning

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argument is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w indow
. event-window

CLX:BOOLEAN

True ifthe event came from a C LX:SEND-EVENT request.

CLX:WINDOW

The event window (w in d ow and event-window are
synonyms).

root

CLX:WINDOW

The root window in which the event occurred.

ch ild

(OR NULL CLX:WINDOW)

The source window in which the event occurred.

same-screen-p

CLX:BOOLEAN

Indicates whether the event window is on the same screen
as the root window.

INTEGER

The X coordinate of the pointer in the event window.

(continued on next page)

12-16

Event Functions

Table 12-7 (Cont.):

:BUTTON-RELEASE Event-Key

A rgu m en t

Type

M e a n in g

INTEGER

T h e Y c o o rd in a te o f t h e p o in te r in th e e v e n t w indow .

root-x

INTEGER

T h e X c o o rd in a te o f t h e p o in te r r e la tiv e to t h e ro o t w indow .

root-y

INTEGER

T h e Y c o o rd in a te o f t h e p o in te r r e la tiv e to t h e ro o t w indow .

s ta te

CLX:MASK16

T h e s t a te o f b u tto n s a n d m o d ifie r k e y s j u s t p rio r to th e
e v e n t.

tim e

CLX:TIMESTAMP

T h e tim e in m illis e c o n d s a t w h ic h t h e e v e n t o c c u rred .

code

INTEGER

T h e n u m b e r o f th e b u tt o n t h a t w a s re le a s e d .

Table 12-6:

:CIRCULATE-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

T h e d is p la y o n w h ic h th e e v e n t o c c u rre d . T h is
a r g u m e n t is a v a ila b le o n ly to CLX:PROCESS-EVENT
h a n d le r fu n c tio n s .

even t-k e y

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -eve n t-p

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT
re q u e s t.

e v e n t-w in d o w

CLX:WINDOW

T h e e v e n t w in d o w .

w in d o w

CLX:WINDOW

T h e w in d o w t h a t h a s b e e n c irc u la te d .

p la c e

(MEMBER : TOP : BOTTOM)

T h e p o s itio n o f t h e w in d o w o n th e s ta c k a f t e r i t h a s
b e e n c irc u la te d .

Table 12-9:

:CIRCULATE-REQUEST Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

T h e d is p la y o n w h ic h th e e v e n t o c c u rre d . T h is
a r g u m e n t is a v a ila b le o n ly to CLX:PROCESS-EVENT
h a n d le r fu n c tio n s .

even t-k e y

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -even t-p

C L X : BOOLEAN

T ru e i f t h e e v e n t c a m e fro m a CLX: SEND-EVENT
re q u e s t.

CLX: WINDOW

T h e p a r e n t o f th e w in d o w to b e c ir c u la te d {p a re n t a n d
e v e n t-w in d o w a r e sy n o n y m s).

w in d o w

CLX:WINDOW

T h e w in d o w t h a t is to be c irc u la te d .

p la c e

(MEMBER :TOP : BOTTOM)

T h e r e q u e s te d p o s itio n o f t h e w in d o w o n t h e s ta c k .

pa ren t
e v e n t-w in d o w

Table 12-10:

:CLIENT-MESSAGE Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s .

even t-k e y

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

(continued on next page)

Event Functions

12-17

Table 12-10 (Cont.):

:CLIENT-MESSAGE Event-Key

A rgu m en t

T ype

M e a n in g

sen d -even t-p
Tw in d o w
Le v e n t-w in d o w

CLX: BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT r e q u e s t.

CLX: WINDOW

T h e w in d o w to w h ic h th e m e s s a g e is s e n t (w in d o w a n d
e v e n t-w in d o w a r e sy n o n y m s).

fo r m a t

(MEMBER 8 16 3 2 )

In d ic a te s w h e th e r t h e d a ta is in u n its o f 8, 16, o r 32 -bits.

d a ta

(SEQUENCE INTEGER)

T h e m e s s a g e d a ta .

Table 12-11:

:COLORMAP-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

T h e d is p la y o n w h ic h th e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

even t-k ey

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -even t-p
w in d o w
. e v e n t-w in d o w

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX :SEND-EVENT r e q u e s t.

CLX:WINDOW

T h e w in d o w w h o s e co lo rrn a p h a s c h a n g e d (w in d o w a n d
e v e n t-w in d o w a r e sy n o n y m s).

colorrnap

(OR NULL
CLX : COLORMAP)

N IL i f th e co lo rrn a p w a s c h a n g e d a s a r e s u l t o f a call to
CLX:FREE-COLORMAP; o th e rw is e , t h e n e w co lo rrn ap .

n ew -p

CLX:BOOLEAN

T ru e i f t h e co lo rrn a p h a s c h a n g e d ; fa ls e i f th e co lo rrn a p h a s
b e e n in s ta l le d o r re m o v e d .

in s ta lle d -p

CLX:BOOLEAN

T ru e i f t h e c o lo rrn a p is in s ta lle d , o th e r w is e fa lse .

Table 12-12:

:CONFIGURE-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p

CLX:BOOLEAN

True i f the event came from a C L X :s e n d - e v e n t request.

e v e n t-w in d o w

CLX: WINDOW

The event window.

w in d o w

CLX:WINDOW

The window that has been configured.

INTEGER

The X coordinate o f the top-left com er o f the region that is
exposed (relative to the origin o f the drawable).

INTEGER

The Y coordinate of the top-left com er o f the region that is
exposed (relative to the origin o f the drawable).

w id th

INTEGER

The width o f the exposed region.

h e ig h t

INTEGER

The height o f the exposed region.

b o rd e r -w id th

INTEGER

The width o f the border, in pixels.

a b o v e -s ib lin g

(OR NULL CLX:WINDOW)

The sibling window above which w in d o w is stacked. If this
is N IL , CLX places w in d o w on the bottom of the stack.

o v e rrid e-red irect-p

CLX:BOOLEAN

Specifies whether the server ignores requests to reconfigure
w in d o w .

12-18

Event Functions

Table 12-13:

:CONFIGURE-REQUEST Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

T h e d is p la y o n w h ic h th e e v e n t o c c u rre d . T h is
a r g u m e n t is a v a ila b le o n ly to CLX:PROCESS-EVENT
h a n d l e r fu n c tio n s .

even t-k ey

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -even t-p

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX : SEND-EVENT
r e q u e s t.

pa ren t
. e v e n t-w in d o w

CLX:WINDOW

T h e p a r e n t o f th e w in d o w to b e re c o n fig u re d (p a ren t
a n d e v e n t-w in d o w a r e sy n o n y m s).

w in d o w

CLX:WINDOW

T h e w in d o w t h a t is to b e re c o n fig u re d .

INTEGER

T h e r e q u e s te d X c o o rd in a te o f th e to p - le ft c o rn e r o f
t h e re g io n t h a t is e x p o se d (r e la tiv e to t h e o rig in o f th e
d ra w a b le ).

INTEGER

T h e r e q u e s te d Y c o o rd in a te o f th e to p - le ft c o rn e r o f
t h e re g io n t h a t is e x p o se d (r e la tiv e to t h e o rig in o f th e
d ra w a b le ).

w id th

INTEGER

T h e r e q u e s te d w id th o f th e e x p o se d re g io n .

h e ig h t

INTEGER

T h e r e q u e s te d h e ig h t o f th e e x p o se d re g io n .

b o rd e r -w id th

INTEGER

T h e r e q u e s te d w id th o f th e b o rd e r, in p ix e ls.

sta c k -m o d e

(MEMBER : ABOVE : BELOW
: T O P -IF
: BOTTOM-IF
:O P P O S IT E )

T h e r e q u e s te d p o s itio n o f t h e w in d o w i n t h e sta c k .
S e e t h e d e s c r ip tio n o f t h e CLX: WINDOW-PRIORITY
fu n c tio n i n P a r t IV fo r d e ta ils .

a b o v e -sib lin g

(OR NULL CLX:WINDOW)

T h e s ib lin g w in d o w a b o v e w h ic h w in d o w is sta c k e d .
I f N IL , w in d o w is p la c e d a t t h e b o tto m o f t h e s ta c k .

va lu e -m a sk

CLX:MASK16

A b i t m a s k t h a t d e sc rib e s w h ic h o f t h e a r g u m e n ts
w e re sp e c ifie d in t h e C o n fig u re W in d o w r e q u e s t.

Table 12-14:

:CREATE-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX: DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k e y

CLX:EVENT-KEY

The current event.

sen d -even t-p

CLX:BOOLEAN

True if the event came from a CLX: SEND-EVENT request.

w in d o w
pa ren t
. e v e n t-w in d o w

CLX:WINDOW

The window ju s t created.

CLX:WINDOW

The parent o f the created window (p a re n t and e v e n t-w in d o w are
synonyms).

INTEGER

The X coordinate of the origin o f w in d o w .

INTEGER

The Y coordinate of the origin o f w in d o w .

w id th

INTEGER

The width o f w in d o w .

h e ig h t

INTEGER

The height o f w in d o w .

b o rd e r -w id th

INTEGER

The width o f the border, in pixels.

o v e rrid e -re d ire c t-p

CLX:BOOLEAN

Specifies whether the server ignores requests to create w in d o w .

Event Functions

12-19

Table 12-15:

:DESTROY-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX: PROCESS-EVENT handler functions.

even t-k ey

CLX: EVENT-KEY

The current event.

sen d -even t-p

CLX: BOOLEAN

True i f the event came from a CLX: SEND-EVENT request.

e v e n t-w in d o w

CLX: WINDOW

The event window.

w in d o w

CLX: WINDOW

The window that has been destroyed.

Table 12-16:

:ENTER-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p

CLX:BOOLEAN

True i f the event cam e from a CLX: SEND-EVENT
request.

w in d o w

CLX:WINDOW

The event window (w in d o w and e v e n t-w in d o w
are synonyms).

root

CLX:WINDOW

The root o f the source window.

c h ild

(OR NULL CLX:WINDOW)

The source window.

sam e-screen -p

CLX:BOOLEAN

Specifies whether the event window and the root
window are on the sam e screen.

INTEGER

The X coordinate o f the pointer in the event
window.

INTEGER

The Y coordinate o f the pointer in the event
window.

root-x

INTEGER

The X coordinate o f the pointer relative to the
root window.

root-y

INTEGER

The Y coordinate o f the pointer relative to the
root window.

s ta te

CLX:MASK16

The state o f buttons and keys juBt prior to the
event.

tim e

CLX:TIMESTAMP

The time in m illiseconds at which the event
occurred.

m ode

(MEMBER : NORMAL : GRAB
: UNGRAB)

Indicates whether the event is normal or
pseudomotion.

k in d

(MEMBER : ANCESTOR
: VIRTUAL
: IN FERIO R
: NON-LINEAR
: NONLINEAR-VITUAL)

L e v e n t-w in d o w

focu s-p

12-20

CLX: BOOLEAN

Event Functions

Indicates which windows CLX notifies o f the
w in d o w e n tr y e v e n t.

If true, specifies that the event window is the
focus window. I f false, one o f the children o f the
event window is the focus window.

Table 12-17:

:EXPOSURE Event-Key

A rgu m en t

Type

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w indow
. even t-w in dow .

CLX:BOOLEAN

True if the event cam e from a CLX: SEND-EVENT request.

CLX:WINDOW

The event window (w in d o w and event-w indow are synonyms).

INTEGER

The X coordinate o f the top-left com er of the region that is
exposed (relative to the origin o f the drawable).

INTEGER

The Y coordinate o f the top-left com er o f the region that is
exposed (relative to the origin o f the drawable).

w id th

INTEGER

The width o f the exposed region.

h eigh t

INTEGER

The height o f the exposed region.

count

INTEGER

The number o f exposure events that are to follow.

Table 12-18:

:FOCUS-IN Event-Key

A rgu m en t

Type

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p

CLX:BOOLEAN

True i f the event came from a CLX: SEND-EVENT
request.

w in dow
. even t-w in dow .

CLX:WINDOW

The event window (w in d o w and event-w indow
are synonyms).

m ode

(MEMBER : NORMAL
: WHILE-GRABBED
: GRAB : UN GRAB)

k in d

Table 12-19:

(MEMBER : ANCESTOR : VIRTUAL
: IN FERIOR
: NONLINEAR
: NONLINEAR-VIRTUAL
: POINTER
: POINTER-ROOT :NONE)

Specifies whether the event is the result of
n o r m a l k e y b o a rd in p u t; k e y b o a rd i n p u t a f t e r
a c lie n t h a s g ra b b e d th e k e y b o a rd ; k e y b o a rd
i n p u t a t t h e tim e th e c lie n t a c tiv a te s a k e y b o a rd
g ra b ; o r k e y b o a rd i n p u t a t th e tim e th e c lie n t
d e a c tiv a te s a k e y b o a rd g ra b .

Indicates which windows and pointers CLX
n o tifie s o f t h e in p u t fo cu s c h a n g e .

:FOCUS-OUT Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.
(con tin u ed on n ex t page)

Event Functions

12-21

Table 12-19 (Cont.):

:FOCUS-OUT Event-Key

A rgum en t

Type

M e a n in g

sen d -even t-p

CLX: BOOLEAN

True i f the event came from a CLX: SEND-EVENT
request.

CLX:WINDOW

The event window (w in d o w and e v e n t-w in d o w
are synonyms).

m ode

(MEMBER : NORMAL
: WHILE-GRABBED
: GRAB : UNGRAB)

Specifies whether the event is the result of
norma] keyboard input; keyboard input after
a client has grabbed the keyboard; keyboard
input at the tim e the client activates a keyboard
grab; or keyboard input at the tim e the client
deactivates a keyboard grab.

k in d

(MEMBER : ANCESTOR : VIRTUAL
: IN FERIOR
: NONLINEAR
: NONLINEAR-VIRTUAL
: POINTER
: POINTER-ROOT : NONE)

Indicates which windows and pointers CLX
notifies of the input focus change.

w in d o w
. e v e n t-w in d o w

Table 12-20:

:GRAPHICS-EXPOSURE Event-Key

A rgum en t

Type

M e a n in g

d is p la y

CLX :D ISPLA Y

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

even t-key

CLX: EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -even t-p
d ra w a b le
. e v e n t-w in d o w

CLX: BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT r e q u e s t.

CLX:DRAWABLE

T h e d ra w a b le r e p o r tin g t h e e v e n t (d r a w a b le a n d e v e n t-w in d o w
a r e sy n o n y m s).

INTEGER

T h e X c o o rd in a te o f th e to p - le ft c o rn e r o f t h e e x p o se d re g io n
( r e la tiv e to t h e o rig in o f t h e d ra w a b le ).

INTEGER

T h e Y c o o rd in a te o f th e to p - le ft c o rn e r o f t h e e x p o se d re g io n
( r e la tiv e to t h e o rig in o f t h e d ra w a b le ).

w id th

INTEGER

T h e w id th o f t h e e x p o se d re g io n .

h e ig h t

INTEGER

T h e h e ig h t o f t h e e x p o se d re g io n .

co u n t

INTEGER

T h e n u m b e r o f e x p o s u re e v e n ts t h a t a r e to follow .

m a jo r

INTEGER

I n d ic a te s w h e th e r th e g ra p h ic s r e q u e s t w a s a C o p y A re a (6 2 ) o r
a C o p y P la n e (6 3 ).

m in o r

INTEGER

T h e v a lu e zero . R e s e rv e d fo r u s e b y e x te n s io n s .

Table 12-21:

:GRAVITY-NOTIFY Event-Key

A rgum en t

Type

M e a n in g

d is p la y

C LX :D ISPLA Y

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

even t-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

sen d -even t-p

CLX: BOOLEAN

T ru e i f t h e e v e n t c a m e fro m a CLX: SEND-EVENT r e q u e s t.

(continued on next page)

12-22

Event Functions

Table 12-21 (Cont.):
A rgu m en t

:GRAVITY-NOTIFY Event-Key

Type

M e a n in g

even t-w in dow

CLX:WINDOW

T h e e v e n t w indow .

w in dow

CLX:WINDOW

T h e w in d o w t h a t h a s b e e n m o v ed .

INTEGER

T h e X c o o rd in a te o f th e n e w o rig in , r e la tiv e to th e p a r e n t
w indow .

INTEGER

T h e Y c o o rd in a te o f th e n e w o rig in , r e la tiv e to t h e p a r e n t
w indow .

Table 12-22:

:KEYMAP-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p
w indow
. even t-w in dow .

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT re q u e s t.

CLX:WINDOW

T h e e v e n t w in d o w (w indow a n d even t-w in dow a r e
sy n o n y m s).

keym ap

(BIT-VECTOR 2 5 6 )

T h e b i t v e c to r o f th e k e y b o a rd . E a c h 1 b i t in d ic a te s t h a t
t h e c o rr e s p o n d in g k e y is c u r r e n tly p re s se d .

Table 12-23:

:KEY-PRESS Event-Key

A rgu m en t

Type

M e a n in g

d isp la y

CLXrDISPLAY

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s .

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p
[ w indow
Leven t-w in dow

CLX:BOOLEAN

T ru e i f t h e e v e n t c a m e fro m a CLX: SEND-EVENT r e q u e s t.

CLX:WINDOW

T h e e v e n t w in d o w (w in d o w a n d even t-w in dow a r e
sy n o n y m s).

root

CLX:WINDOW

T h e r o o t w in d o w o f t h e so u rc e w indow .

ch ild

(OR NÜLL CLX:WINDOW)

T h e so u rc e w indow .

sam e-screen-p

CLX:BOOLEAN

In d ic a te s w h e th e r t h e e v e n t w in d o w is o n t h e s a m e s c re e n
a s t h e ro o t w indow .

INTEGER

T h e X c o o rd in a te o f t h e p o in te r i n t h e e v e n t w indow .

INTEGER

T h e Y c o o rd in a te o f t h e p o in te r i n t h e e v e n t w indow .

root-x

INTEGER

T h e X c o o rd in a te o f t h e p o in te r r e l a ti v e to t h e ro o t w indow .

root-y

INTEGER

T h e Y c o o rd in a te o f t h e p o in te r r e l a ti v e to t h e ro o t w indow .

sta te

CLX:MASK16

T h e s t a t e o f b u tto n s a n d m o d ifie r k e y s j u s t p r io r to th e
e v e n t.

tim e

CLX:TIMESTAMP

T h e tim e in m illis e c o n d s a t w h ic h t h e e v e n t o c c u rre d .

code

INTEGER

T h e k e y c o d e o f th e k e y t h a t w a s p re s s e d .

Event Functions

12-23

Table 12-24:

:KEY-RELEASE Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p
w in d o w
. e v e n t-w in d o w

CLX: BOOLEAN

True i f the event cam e from a CLX: SEND-EVENT request.

CLX:WINDOW

The event window (w in d o w and e v e n t-w in d o w are
synonyms).

root

CLX: WINDOW

The root window o f the window in which the event
occurred.

c h ild

(OR NULL CLX : WINDOW)

The source window.

sam e-screen -p

CLX: BOOLEAN

Indicates whether the event window is on the sam e screen
as the root window.

INTEGER

The X coordinate o f the pointer in the event window.

INTEGER

The Y coordinate o f the pointer in the event window.

root-x

INTEGER

The X coordinate of the pointer relative to the. root window.

root-y

INTEGER

The Y coordinate of the pointer relative to the root window.

s ta te

CLX-.MASK16

The state o f buttons and modifier keys ju st prior to the
event.

tim e

CLX:TIMESTAMP

The time in m illiseconds at which the event occurred.

code

INTEGER

The keycode o f the key that was released.

Table 12-25:

:LEAVE-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX: DISPLAY

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p

CLX:BOOLEAN

True if the event came from a CLX: SEND-EVENT
request.

w in d o w
. e v e n t-w in d o w

CLX:WINDOW

The event window (w in d o w and e v e n t-w in d o w
are synonyms).

root

CLX:WINDOW

The root o f the source window.

c h ild

(OR NULL CLX:WINDOW)

The source window.

sam e-screen -p

CLX:BOOLEAN

Specifies whether the event window and the root
window are on the sam e Bcreen.

INTEGER

The X coordinate o f the pointer in the event
window.

INTEGER

The Y coordinate of the pointer in the event
window.

root-x

INTEGER

The X coordinate of the pointer relative to the
root window.

root-y

INTEGER

The Y coordinate o f the pointer relative to the
root window.
(c o n tin u e d o n n e x t p a g e )

12-24

Event Functions

Table 12-25 (Cont.):

:LEAVE-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

state

INTEGER

The state o f buttons and keys ju st prior to the
event.

tim e

INTEGER

The tim e in m illiseconds at which the event
occurred.

m ode

(MEMBER

NORMAL : GRAB
UNGRAB)

Indicates whether the event is normal or
pseudomotion.

k in d

(MEMBER

ANCESTOR : VIRTUAL
INFERIOR
NON-LINEAR
NONLINEAR—VITUAL)

Indicates which windows CLX notifies of the
window exit event.

focus-p

CLX: BOOLEAN

Table 12-26:

If true, specifies that the event window is the
focus window. I f false, one of the children o f the
event window is the focus window.

rMAPPING-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

C LX :D ISPLA Y

The display on which the event occurred.
This argum ent is available only to
CLX: PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p

CLX:BOOLEAN

T ru e i f t h e e v e n t c a m e fro m a CLX: SEND-EVENT
r e q u e s t.

request

(MEMBER : MODIFIER : KEYBOARD
: POINTER)

T h e ty p e o f m a p p in g c h a n g e b e in g re p o r te d .

sta rt

INTEGER

T h e f i r s t n u m b e r o f t h e r a n g e o f a lte r e d k e y s , s e t
o n ly i f request is : KEYBOARD.

count

INTEGER

T h e l a s t n u m b e r o f t h e r a n g e o f a lte r e d k e y s , s e t
o n ly i f request is : KEYBOARD.

Table 12-27:

:MAP-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT re q u e s t.

event-w indow

CLX: WINDOW

T h e e v e n t w in d o w .

w in dow

CLX: WINDOW

T h e w in d o w t h a t h a s b e e n m a p p e d .

override-redirect-p

CLX: BOOLEAN

S p ecifies w h e th e r t h e s e r v e r ig n o re s r e q u e s ts to m a p th e
w indow .

Event Functions

12-25

Table 12-28:

:MAP-REQUEST Event-Key

A rgu m en t

T ype

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX: EVENT-KEY

The current event.

sen d -even t-p
' p a ren t
. e v e n t-w in d o w

CLX:BOOLEAN

True i f the event cam e from a CLX: SEND-EVENT request.

w in d o w

CLX:WINDOW
CLX:WINDOW

Table 12-29:

The parent o f the window to be m apped {p a re n t and
e v e n t-w in d o w are synonyms).

The window that is to be mapped.

:MOTION-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p
w in d o w
. e v e n t-w in d o w

CLX:BOOLEAN

True i f t h e event cam e from a CLX: SEND-EVENT request.

CLX:WINDOW

The event window {w in d o w and e v e n t-w in d o w are
synonyms).

root

CLX: WINDOW

The root o f the source window.

c h ild

(OR NULL CLX:WINDOW)

The source window.

sam e-screen -p

CLX: BOOLEAN

Indicates whether the event window is on the sam e screen
as the root window.

INTEGER

The X coordinate o f the pointer in the event window.

INTEGER

The Y coordinate o f the pointer in the event window.

root-x

INTEGER

The X coordinate of the pointer relative to the root window.

root-y

INTEGER

The Y coordinate o f the pointer relative to the root window.

s ta te

CLX:MASK16

The state o f the m ouse buttons ju st prior to the event.

tim e

CLX:TIMESTAMP

The time in m illiseconds at which the event occurred.

h in t-p

CLX:BOOLEAN

Indicates whether other motion events that CLX has not
yet reported have occurred.

Table 12-30:

:NO-EXPOSURE Event-Key

A rgu m en t

T ype

M e a n in g

d is p la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

even t-k ey

CLX:EVENT-KEY

The current event.

sen d -even t-p
d r a w a b le
. e v e n t-w in d o w

CLX:BOOLEAN

True i f the event came from a CLX: SEND-EVENT request.

CLX:DRAWABLE

The window or pixmap reporting the event {d ra w a b le and
e v e n t-w in d o w are synonyms).

m a jo r

INTEGER

Indicates whether the graphics request was a Copy Area (6 2 ) or
a CopyPlane (6 3 ).

m in o r

INTEGER

The value zero. Reserved for use by extensions.

12-26

Event Functions

Table 12-31:

:PROPERTY-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p

CLX:BOOLEAN

True i f the event came from a CLX : SEND-EVENT
request.

w indow
L event-w indow

CLX:WINDOW

The window whose property was changed
(w in dow and even t-w in dow are synonyms).

atom

KEYWORD

Identifies the property that was changed. For
m ore information on properties and atoms, see
Section 6.4.

state

(MEMBER : NEW-VALUE : DELETED)

Indicates whether the property is being changed
(or rotated) or is being deleted.

tim e

CLX:TIMESTAMP

Server tim e that the property changed.

Table 12-32:

:REPARENT-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p

CLX:BOOLEAN

True i f the event came from a CLX : SEND-EVENT request.

even t-w in dow

CLX:WINDOW

The event window.

w indow

CLX:WINDOW

The window that is to be reparented.

p a re n t

CLX:WINDOW

The new parent of w indow .

INTEGER

The X coordinate of the origin o f the new parent window.

INTEGER

The Y coordinate of the origin o f the new parent window.

override-redirect -p

CLX: BOOLEAN

Specifies whether the Berver ignores requests to reparent
w indow .

Table 12-33:

;RESIZE-REQUEST Event-Key

A rgu m en t

Type

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w indow
. event-w indow

CLX:BOOLEAN

True i f the event came from a CLX : SEND-EVENT request.

CLX:WINDOW

The window that is to be resized (w indow and event-w indow are
synonyms).

w id th

INTEGER

The new width o f the window.

h eigh t

INTEGER

The new height o f the window.

Event Functions

12-27

Table 12-34:

:SELECTION-CLEAR Event-Key

A rgum en t

T ype

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w indow
. event-w indow .

CLX:BOOLEAN

True i f the event came from a CLX: SEND-EVENT request.

CLX:WINDOW

The window losing ownership of the selection ( w indow and
event-w indow are synonyms).

selection

KEYWORD

The selection atom.

tim e

CLX:TIMESTAMP

Last time change recorded for the selection.

Table 12-35:

:SELECTION-NOTIFY Event-Key

A rgum en t

Type

M e a n in g

d isp la y

CLX:DISPLAY

The display on which the event occurred. This argum ent is
available only to CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p
w indow
. event-w indow .

CLX:BOOLEAN

True if the event came from a CLX: SEND-EVENT request.

CLX:WINDOW

The window that owns the selection (w in d o w and
event-w indow are synonyms).

selection

KEYWORD

The selection atom.

ta rg et

KEYWORD

The target type atom.

p roperty

(OR NULL KEYWORD)

The atom that specifies a property.

tim e

(OR CLX:TIMESTAMP
KEYWORD)

A timestamp.

Table 12-36:

:SELECTION-REQUEST Event-Key

A rgum en t

TVpe

M e a n in g

d isp la y

CLX :D ISPLA Y

T h e d is p la y o n w h ic h t h e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p
w indow
. event-w indow J

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT re q u e s t.

requestor

CLX:WINDOW

T h e w in d o w t h a t r e q u e s ts t h e se le c tio n .

selection

KEYWORD

T h e se le c tio n a to m .

ta rget

KEYWORD

T h e t a r g e t ty p e a to m .

property

(OR NULL KEYWORD)

T h e a to m t h a t sp ecifie s a p ro p e rty .

tim e

INTEGER

A tim e s ta m p , e x p re s s e d i n m illis e c o n d s , o r th e k e y w o rd

CLX:WINDOW

T h e w in d o w t h a t o w n s t h e se le c tio n ( w in d o w a n d

event-w indow a r e sy n o n y m s).

: CURRENT-TIME fro m t h e C o n v e rtS e le c tio n re q u e s t.

12-28

Event Functions

Table 12-37:

:UNMAP-NOTIFY Event-Key

A rgu m en t

T ype

M e a n in g

d isp la y

CLX :D ISPLA Y

T h e d is p la y o n w h ic h th e e v e n t o c c u rre d . T h is a r g u m e n t is
a v a ila b le o n ly to CLX:PROCESS-EVENT h a n d le r fu n c tio n s.

event-key

CLX:EVENT-KEY

T h e c u r r e n t e v e n t.

send-event-p

CLX:BOOLEAN

T ru e i f th e e v e n t c a m e fro m a CLX: SEND-EVENT r e q u e s t.

event-w indow

CLX:WINDOW

T h e e v e n t w indow .

w indow

CLX:WINDOW

T h e w in d o w t h a t w a s u n m a p p e d .

configure-p

CLX:BOOLEAN

I f t r u e , in d ic a te s t h a t t h e u n m a p e v e n t o c c u rre d a s a r e s u l t
o f r e s iz in g th e p a r e n t o f w in d o w w h e n t h e w in d o w g ra v ity
o f w in d o w is :ÜNMAP-GRAVITY.

Table 12-38:

:VISIBILITY-NOTIFY Event-Key

A rgu m en t

Type

M e a n in g

d isp la y

CLX :D ISPLA Y

The display on which the event occurred.
This argum ent is available only to
CLX:PROCESS-EVENT handler functions.

event-key

CLX:EVENT-KEY

The current event.

send-event-p

CLX:BOOLEAN

True if the event came from a CLX: SEND-EVENT
request.

CLX:WINDOW

The window whose visibility changed (w indow
and event-w indow are synonyms).

(MEMBER : UNOBSCURED
: PARTIALLY-OBSCURED
: FULLY-OBSCURED)

Indicates whether the window has changed from
being obscured to bein g visible, or from being
visible to being partially or fully obscured.

w indow
. event-w indow
state

Event Functions

12-29

Chapter 13

Window and Session Management

A window or session m anager program completes the following types of tasks:
•

R eparenting windows

•

Custom izing the keyboard and pointer

•

U sing th e screen saver

•

Controlling netw ork access

•

Closing th e connection

•

Finding extensions
NOTE
M ost clients are not responsible for window or session m anagem ent
and do not need to use these routines. A client could use these routines
if there were no form al window or session m anager program . Window
or session m anagem ent routines m u st be used w ith great care, as they
can affect the operation of other applications.

13.1

Reparenting Windows
You can change a window’s p a re n t to another window on th e same screen w ith
th e c l x : r e p a r e n t - w in d o w function. Its form at is:
CLX:REPARENT-WINDOW window parent x y
w in d o w

The CLX: WINDOW object w hose parent is changed.

p a re n t

The CLX:WINDOW object that is the new parent.

x and y

Integers that specify the X and Y coordinates of the origin o f w indow in
p a re n t.

If th e specified window is m apped, c l x : r e p a r e n t - w in d o w autom atically unm aps
it; rem oves it from its current position in the window hierarchy; in serts it as the
child of the specified parent; and m aps it again. The window is placed on top of
th e stacking order w ith respect to its new siblings.

13.2 Customizing the Keyboard and the Pointer
CLX provides functions th a t you can use to change the keyboard controls; set or
obtain th e lis t of auto-repeat keys; ring the bell; set or obtain th e pointer button
or keybard m appings; and obtain a b it vector for the keyboard. This section
discusses th e user-preference options of bell and key click loudness, pointer
behavior, and so on.
Window and Session Management

13-1

13.2.1

Ringing the Bell
The c l x :BELL function rings the keyboard bell. Its form at is:
CLX:BELL display &OPTIONAL percent-from-normal

display
percent-from-normal

A CLX :D ISPLA Y o b ject.
An integer from -100 (off) to 100 (loudest), inclusive. The default
value is zero.

The optional percent-from-normal arg u m en t specifies a percentage increase
(positive values) or decrease (negative values) from the volume set in a
LISP program w ith the CLX: c h a n g e - k e y b o a r d - c o n t r o l function or, if the
DECwindows Session M anager is present, w ith th e Keyboard... item of the
Customize m enu. The pitch and duration of the bell can be modified only w ith
th e CLX: CHANGE-KEYBOARD-CONTROL function.

13.2.2

Keyboard and Pointer Mappings
A “key code” represents a physical (or logical) key on the keyboard. Key codes are
betw een 8 and 255, inclusive. The m apping betw een keys and key codes cannot
be changed. A “keysym ” is an encoding of th e symbol on the cap of a key. A list
of keysym s is associated w ith each key code. The first keysym in each list is the
one for no modifiers. See the X Window System: C Library and Protocol Reference
for inform ation on keysym encoding. This section explains how to control the
bindings of keysyms to keys and modifiers.
The C L X : k e y b o a r d - m a p p in g function re tu rn s th e valid key codes for a specified
display. Its form at is:
CLX:KEYBOARD-MAPPING display
&KEY :FIRST-KEYCODE :START :END :DATA

display

A CLX :D ISPLA Y o b ject.

: FIRST-KEYCODE

A n in te g e r t h a t sp e c ifie s w h ic h k e y c o d e to s t a r t a t, o r N IL. T h e
d e fa u lt v a lu e is t h e :MIN-KEYCODE c o m p o n e n t o f display.

: START

A CLX:ARRAY-INDEX v a lu e t h a t sp ecifie s w h e re (in t h e r e t u r n
a r r a y ) to p u t t h e f i r s t k e y c o d e , o r N IL . T h e d e f a u lt v a lu e is
: FIRST-KEYCODE.

: END

A CLX:ARRAY-INDEX v a lu e o r N IL . T h e d iffe re n c e b e tw e e n :END
a n d : START is t h e n u m b e r o f k e y c o d e s to r e t u r n . T h e d e f a u lt :END
is o n e m o re t h a n t h e :MAX-KEYCODE o f display.

:DATA

A n a r r a y i n w h ic h to r e t u r n t h e k e y co d es, o r N IL .

The function re tu rn s an a rra y of keysym s. If :DATA is specified, th e results are
p u t there.
Tb change the m apping of keysyms to key codes, use the
C L X : c h a n g e - k e y b o a r d - m a p p in g function. Its form at is:
CLX:CHANGE-KEYBOARD-MAPPING display keysyms
&KEY :START :END :FIRST-KEYCODE

display
keysyms

A CLX :D ISPLA Y object.
An array.

13—2 Window and Session Management

: START a n d :END

Two CLX: ARRAY- INDEX v a lu e s t h a t sp e c ify th e s u b r a n g e of
k e y sy m s.

: FIRST-KEYCODE

An integer that specifies the first keycode to store at. The default
value is that o f : START.

X perm its a t m ost eight m odifier keys. The C L X : m o d i f i e r - m a p p i n g function
re tu rn s th e key codes currently being used as modifiers. Its form at is:
CLX:MODIFIER-MAPPING display

w here display is a C L X : d i s p l a y object. The function re tu rn s m ultiple values,
each of which is a lis t of integers representing the key codes th a t have a modifier
bound to them :

shift
lock
control
modi
mod2
mod3
mod4
mod5
Use th e C L X : s e t - m o d i f i e r - m a p p in g function to change th e key codes
of th e keys (if any) th a t are to be used as modifiers. The form at of the
CLX: SET-M O D IFIER -M A PPIN G function is:
CLX:SET-MODIFIER-MAPPING display &KEY :SHIFT :LOCK :CONTROL
:MOD1 :MOD2 :MOD3 :MOD4 :MOD5

display

A C LX :D ISPLA Y o b ject.

: S H IF T
: LOCK
: CONTROL

Sequences o f integers that specify the key codes o f the modifier keys.

and
:MODn

The CLX: SET-M O DIFIER-M APP ING function re tu rn s a keyword indicating the statu s
of the change: : s u c c e s s , :BUSY, m eaning th a t a modifier whose key codes are
being changed is logically down, or : f a i l e d , m eaning th a t the specified key codes
a re not valid for the modifier.
The CLX: p o i n t e r - m a p p i n g function re tu rn s a m apping list th a t defines which
buttons are enabled for th e pointer cursor on th e specified display. The form at of
th e c l x : p o i n t e r - m a p p in g function is:
CLX:POINTER-MAPPING display &KEY :RESULT-TYPE

display

A CLX: DISPLAY object.

: RESULT-TYPE

The LISP type o f the return value. The default value is 'L I S T .

The function re tu rn s a sequence of i n t e g e r .

13.2.3

Keycode Mapping
T he functions in th is section provide tran slatio n s among characters, key codes,
and keysyms.

Window and Session Management

13-3

The c l x :CHARACTER-> k e y s Ym s function retu rn s a list of the keysyms th a t
m atch a specified character. If a display is provided, tran slatio n s specific to
th a t display are used; if not, global translations are used. The form at of the
CLX : CHARACTER->KEYSYMS function is:
CLX:CHARACTER->KEYSYMS character &OPTIONAL display
character

Any LISP object.

d isp la y

A CLX:DISPLAY object.

The CLX:KEYCODE->KEYSYM function retu rn s the keysym to which a specified
keycode is bound. Its form at is:
CLX:KEYCODE->KEYSYM display keycode keysym-index
d isp la y

A CLX :D ISPLA Y object.

keycode

An integer.

keysym -index

An integer or N IL .

The CLX : k e y s y m - > c h a r a c t e r function finds the character or string associated
w ith a keysym. Its form at is:
CLX:KEYSYM->CHARACTER display keysym &OPTIONAL state
d isp la y

A CLX: DISPLAY o b ject.

keysym

A CLX: KEYSYM v a lu e .

sta te

An integer or N IL . This argum ent is ignored b y VAX LISP.

The CLX: k e y s y m - > c h a r a c t e r function retu rn s m ultiple values if keysym is bound
to more th a n one character. The first re tu rn value is the character to which
keysym is bound, or the first character of the string; th e second is th e string, if
any; and th e th ird is the length of the string.
The CLX:KEYSYM->KEYCODES function re tu rn s th e keycodes corresponding to the
specified C LX : k e y s y m , or n i l if th ere is none. Its form at is:
CLX:KEYSYM->KEYCODES display keysym
d isp la y

A CLX:DISPLAY o b ject.

keysym

A CLX:KEYSYM.

The c l x : k e y c o d e - > c h a r a c t e r function re tu rn s th e character corresponding to the
specified keycode, or n i l if th ere isn’t one. Its form at is:
CLX:KEYCODE->CHARACTER display keycode state
&KEY :KEYSYM-INDEX :KEYSYM-INDEX-FUNCTION

13-4

d isp la y

A CLX:DISPLAY object.

keycode

An integer.

sta te

A CLX:MASK16 v a lu e t h a t sp e c ifie s t h e s t a t e o f m o d ifie r
keys (shift, control, and so on).

: KEYSYM-INDEX

An integer or N IL . The default value is the result o f the
: KEYSYM-INDEX-FDNCTION fu n c tio n .

Window and Session Management

:KEYSYM-INDEX-FUNCTION

NIL or a function that takes the following arguments:
(charO state caps-lock-p keysyms-per-keycode)
ch a rt

The character associated with the
first : KEYSYM-INDEX value.

state

A CLX:MASK16 v a lu e t h a t
specifies the state of modifier
keys (shift, control, and so on).

caps-lock-p

True when the keysym associated
with the lock modifier is for
caps-lock.

keysym s-per-keycode

The number o f keysyms per
keycode.

T h e d e f a u lt is # ' CLX: KEYSYM-INDEX-FUNCTION.

The c l x :k e y c o d e ->c h a r a c t e r function re tu rn s m ultiple values if keycode is
bound to more th a n one character. The first re tu rn value is the character to
which keycode is bound, or the first character of th e string; th e second is the
string, if any; and the th ird is the length of the string.

13.2.4

Keyboard and Pointer Controls
CLX allows client program s to query and to change several keyboard and pointer
settings. The c l x :k e y b o a r d -c o n t r o l function re tu rn s th e current keyboard
settings. Its form at is:
CLX:KEYBOARD-CONTROL display

w here display is a CLX:DISPLAY object. The keyboard settings are retu rn ed as
m ultiple values:
key-click-percent

The volume of key clicks betw een 0 (off) and 100 (loudest).

bell-percent

The volume of a bell ring betw een 0 (off) and 100 (loudest).

bell-pitch

The pitch (specified in hertz) o f the bell.

bell-duration

The duration of a bell ring, in milliseconds.

led-m ask

Each 1 bit indicates an LED that is on. The least significant bit
corresponds to the first LED.

g lo b a l-a u to -re p e a t

: on if auto-repeat is enabled for the keyboard as a whole; : OFF if it
is not.

auto-repeats

A bit vector where each 1 bit indicates that auto-repeat is enabled
for the corresponding key.

The CLX:CHANGE -k e y b o a r d - c o n t r o l allows you to change the keyboard settings.
Its form at is:
CLX:CHANGE-KEYBOARD-CONTROL display
&KEY :KEY-CLICK-PERCENT :BELL-PERCENT :BELL-PITCH :BELL-DURATION
:LED LED-MODE :KEY :AUTO-REPEAT-MODE
d isp la y

A CLX: D I SPLAY object.

: KEY-CLICK-PERCENT

An integer that represents the volume o f a key click from 0
(off) to 100 (loudest), : DEFAULT, or N IL .

: BELL-PERCENT

An integer that specifies the volume o f a bell ring from 0 (off)
to 1 0 0 (lo u d e s t), : DEFAULT, o r N IL .

Window and Session Management

13-5

:BELL-PITCH

An integer that specifies the pitch o f the bell in hertz,
:DEFAULT, or NIL.

:BELL-DURATION

An integer that specifies the duration o f a bell ring in
milliseconds, : DEFAULT, or NIL.

:LED

An integer w hose 1 bits specify which LEDs (counting from
zero) are affected by the :LED-MODE argument, or NIL.

:LED-MODE

The keyword : ON or : OFF that specifies the state of LEDs on
the keyboard, or NIL.

:KEY

An integer w hose 1 bits specify that the corresponding key has
auto-repeat m ode enabled, or NIL.

:AUTO-REPEAT-MODE

The keyword : ON, : OFF or : DEFAULT that specifies the global
auto-repeat m ode for the keyboard, or NIL.

If both : l e d -m o d e and : l e d are specified, the state of th e appropriate LEDs is
changed. If only : l e d -m o d e is specified, the state of all LEDs is changed.
Similarly, if both : a u t o -r e p e a t -m o d e and :KEY are specified, th e auto-repeat
mode of th a t key is changed. If only : a u t o -r e p e a t -m o d e is specified, the
global auto-repeat mode for the entire keyboard is changed, w ithout affecting
th e individual key settings. I t is an error to specify a :KEY w ithout an
:AUTO-REP EAT-MODE.

W hen th e global auto-repeat mode is : ON, keys obey th eir individual auto-repeat
modes; w hen the global mode is :OFF, no keys auto-repeat. An auto-repeating key
generates a lte rn a tin g : k e y -p r e s s and : k e y -r e l e a s e events. W hen a key is used
as a modifier, it does not auto-repeat regardless of its auto-repeat setting.

13.2.5

Setting Pointer Controls
T h e way th e pointer cursor moves in response to m ovem ent of the pointing device

is affected by two pointer controls: acceleration and threshold. Acceleration,
expressed as a ratio, is a m ultiplier for cursor movement. For example, an
acceleration of 3 / 1 m eans th a t th e pointer moves three tim es as fast as the
default. Acceleration takes effect only if th e pointer moves m ore th a n threshold
pixels a t a tim e, and applies only to th e distance moved beyond th e threshold.
C L X p r o v id e s fu n c tio n s th a t a llo w you to find th e current pointer controls and to
set th eir values.
The CLX:p o i n t e r -c o n t r o l function re tu rn s the pointer m ovem ent values for
acceleration and th e threshold a t which acceleration should be applied. Its form at
is:
CLX:POINTER-CONTROL display

w here display is a CLX:DISPLAY object. The function retu rn s two num eric values:
acceleration The ratio of the current pointer speed to the default speed.
th reshold

The distance, in pixels, that the pointer cursor m ust m ove before acceleration
is applied.

The CLX:c h a n g e -p o i n t e r -c o n t r o l function lets you define how the pointer cursor
moves. If you supply a num eric value for a c c e l e r a t i o n , it m u st be positive.
CLX will rationalize the value if necessary, and the ratio m ay be rounded
arb itra rily by the X server.
The form at of th e c l x :c h a n g e -p o i n t e r -c o n t r o l function is:
CLX:CHANGE-POINTER-CONTROL display &KEY ACCELERATION THRESHOLD

13-6

Window and Session Management

13.3

d isp la y

A CLX: D I SPLAY o b ject.

: ACCELERATION

A n u m b e r , : DEFAULT, o r N IL .

: THRESHOLD

An INTEGER, : DEFAULT, o r N IL .

Using the Screen Saver
U sers can set the tim eout in terv al for, and enable or disable, the screen saver
feature interactively in the DECwindows Session M anager w ith the Window...
item of the Customize m enu. CLX functions allow client program s to override the
screen saver settings.

13.3.1 Querying the Screen Saver
The CLX: s c r e e n - s a v e r function re tu rn s th e current screen saver settings for the
specified display. The form at of th is function is:
CLX:SCREEN-SAVER display

w here display is a C L X : d i s p l a y object. The values retu rn ed are:
tim eou t

The time, in seconds, that m ust elapse with no input from the keyboard or
pointer before the screen saver turns on. A value o f zero m eans that the
screen saver is disabled.

in terval

The time, in seconds, betw een invocations of the screen saver.

blan kin g

One o f three keywords specifying how the screen is cleared:

exposures

: YES

B la n k t h e sc re e n . ThiB c a n b e r e t u r n e d o n ly i f t h e d is p la y
h a r d w a r e s u p p o r ts v id eo b la n k in g .

:NO

Do not blank the screen. If exposures are allowed (see below), or
if the screen can be regenerated without sending exposure events
to clients, the screen is tiled with the root window background
tile. If exposures are not allowed or the exposure events are sent
to clients, the screen does not change.

: DEFAULT

The default blanking m ethod is used.

One o f three keywords specifying whether exposure events are generated:
:YES

E xposures are allowed. This is the default.

: NO

Exposures are not allowed.

: DEFAULT

The default value is used.

13.3.2 Setting the Screen Saver
The C L X : s e t - s c r e e n - s a v e r function allows client program s to set the controls for
th e screen saver. The form at of th is function is:
CLX:SET-SCREEN-SAVER display timeout interval blanking exposures
d isp la y

A C LX :D ISPLA Y object.

tim eou t

An integer that specifies the time that m ust elapse without input from
the keyboard or pointer before the screen saver turns on, or the keyword
: DEFAULT. A value of zero means that the screen saver is disabled. : DEFAULT
m eans that the default setting is restored.

in terval

An integer or the keyword : DEFAULT that specifies the time between
invocations o f the screen saver.

Window and Session Management

1S-7

blan kin g

:Y ES, :N 0 , or : DEFAULT.

exposures

:Y ES, :N 0 , or : DEFAULT.

The values of timeout and interval a re specified in seconds. T he keyword values
for the exposures arg u m en t are:
: YES

Blank the Bcreen. This can be used only if the display hardware supports
video blanking.

: NO

Do not blank the screen. If exposures are allowed (see below), or if the screen
can be regenerated without sending exposure events to clients, the screen is
tiled w ith the root window background tile. If exposures are not allowed or
the exposure events are sent to clients, the screen does not change.

: DEFAULT

The default blanking m ethod is used.

The keyword values for the blanking arg u m en t are:
:YES

Exposures are allowed.

: NO

E xposures are not allowed.

: DEFAULT

The default value is used.

The c l x :r e s e t - s c r e e n -s a v e r function resets th e tim eout clock to zero, as if input
had ju s t been received. The form at of th is function is:
CLX:RESET-SCREEN-SAVER display
where display is a c l x :DISPLAY object.

13.3.3 Enabling the Screen Saver
The c l x :a c t i v a t e -s c r e e n - s a v e r function enables th e screen saver, even if it is
currently disabled. The form at of this function is:
CLX:ACTIVATE-SCREEN-SAVER display
where display is a c l x :d i s p l a y object.

13.4

Controlling Network Access
For each display, CLX m ain tain s an “access control list” of the m achines th a t can
connect across the netw ork to the X server controlling th a t display. CLX provides
four routines for controlling netw ork access:
•

CLX:ADD-ACCESS-HOST

•

CLX:REMOVE-ACCESS-HOST

•

CLX:ACCESS-HOSTS

•

CLX:ACCESS-CONTROL

The first two allow client program s to specify which m achines have access to a
p articu lar display. The la st two re tu rn inform ation about netw ork access to a
display.
U sers can m an ip u late the access control lis t in th e DECwindows Session M anager
by using th e Security... item of th e Custom ize m enu. Such changes m ay also be
saved from one session to th e next. See th e VMS DECwindows U ser’
s Guide for
details.

13-8

Window and Session Management

13.4.1

Adding and Removing Hosts
The CLX: a d d - a c c e s s - h o s t function dynam ically adds one host to th e list of
hosts th a t can connect to th e server controlling a display. This function does not
execute successfully unless the client issuing th e comm and resides on the same
host as th e server.
The form at of the c l x : a d d - a c c e s s - h o s t function is:
CLX:ADD-ACC ESS-HOST display host

display A CLX: DISPLAY o b ject.
host

A STRING t h a t n a m e s t h e m a c h in e to b e a d d e d to t h e a c c e ss lis t.

The r e m o v e - a c c e s s - h o s t function rem oves a host from the access control list of
th e display. Its form at is:
CLX:REMOVE-ACCESS-HOST display host

display A CLX: D I SPLAY o b ject.
host
A STRING t h a t n a m e s t h e m a c h in e to b e re m o v e d fro m th e a c c e ss lis t.
NOTE
The server does not re ta in changes to th e access control list m ade w ith
CLX:ADD-ACCESS-HOST Or CLX:REMOVE-ACCESS-HOST w hen its host is
rebooted.

13.4.2

Getting Information About Hosts
The access control lis t of a display m ay be enabled or disabled. W hen the access
control list is enabled, only hosts on th e list can connect to th a t display.
The C LX : a c c e s s - h o s t s function re tu rn s the access control list of a display and
indicates w hether th e access list is enabled. The form at of the c l x : a c c e s s - h o s t s
function is:
CLX:ACCESS-HOSTS display &KEY :RESULT-TYPE

display

A CLX :D ISPLA Y o b ject.

: RESULT-TYPE

The LISP type of the first return value. The default is ' L IS T .

The function re tu rn s two values:
hosts
enabled-p

A se q u e n c e o f s tr in g s n a m in g t h e h o s ts o n t h e a c c e ss c o n tro l l i s t o f display,
A CLX: BOOLEAN v a lu e t h a t is t r u e i f t h e a c c e ss l i s t is e n a b le d fo r display.

The C LX : a c c e s s - c o n t r o l function also re tu rn s a c l x : b o o l e a n value th a t is tru e
if the access control list is enabled for display, false if it is disabled. The form at
of th e c l x : a c c e s s - c o n t r o l function is:
CLX ACCESS-CONTROL display

w here display is a c l x :D I S P l a y object. The c l x : a c c e s s - c o n t r o l function m ay be
used w ith s e t f if your client program is on th e sam e m achine as the display.

Window and Session Management

13-9

13.5

Closing the Connection
The functions described in this section allow client program s to control the
processing th a t takes place w hen a connection to the X server is closed.
Specifically, you can:

13.5.1

•

D eterm ine w hat happens to a client’s resources w hen the client disconnects.

•

Disconnect clients associated w ith particu lar resources.

•

Save windows from being destroyed w hen th eir client disconnects.

Deallocating Resources
The c l x :c l o s e -d o w n -m o d e function indicates w hat happens to a client’s resources
w hen th e client disconnects from the server. The default close-down mode
is : d e s t r o y , which frees all client resources. The : r e t a i n -t e m p o r a r y and
:r e t a i n -p e r m a n e n t modes keep the client’s resources a fter it disconnects until a
client invokes c l x :k i l l -t e m p o r a r y -c l i e n t s or c l x :k i l l -c l i e n t s , respectively.
The form at of the CLX: c l o s e -d o w n -m o d e function is:
CLX:CLOSE-DOWN-MODE display

w here display is a clx:DISPLAY object. The function re tu rn s the current
close-down mode of the specified display, e ith e r : destroy, : retain-permanent
or : RETAIN-TEMPORARY. This value is cached locally in the display object so th a t
invoking CLX:close-down-mode generates no server request.
The CLX: c l o s e -d o w n -m o d e function m ay be used w ith s e t f :
(SETF (CLX:CLOSE-DOWN-MODE display) mode)

13.5.2 Disconnecting Other Clients
CLX provides the clx :kill-client function for disconnecting the client
associated w ith a particu lar resource, and the clx :kill-temporary-client
fu n ctio n fo r destroying the resources associated w ith clients th a t disconnected
in : retain-temporary close-down mode. (See Section 13.5.1 for m ore details on
close-down mode.)
The form at of the c l x :k i l l -c l i e n t function is:
CLX:KILL-CLIENT display resource-id

display
resource-id

A CLX:DISPLAY o b ject.
A CLX:RESOURCE-ID v a lu e t h a t id e n tif ie s t h e re s o u rc e (w indow , c o lo rm a p ,
a n d so o n ) a s s o c ia te d w ith t h e c lie n t to b e d is c o n n e c te d .

The form at of th e c l x :k i l l -t e m p o r a r y -c l i e n t s function is:
CLX:KILL-TEMPORARY-CLIENTS display
where display is a c l x :DISp l a y object.

13-10

Window and Session Management

13.5.3 Saving Windows
The saveset is a list of other clients’ windows th a t, if they are children of your
client’s windows, should not be destroyed w hen your client disconnects from
th e server and th a t should be rem apped if your window is unm apped. W hen a
connection is closed, th e server rep aren ts saveset windows to an ancestor not
created by th e disconnecting client and m aps them if they are unm apped.
The CLX: a d d -t o - s a v e -s e t function adds a window to your client’s saveset. Its
form at is:
CLX:ADD-TO-SAVE-SET window
where window is a CLX:w i n d o w object created by another client.

The server autom atically rem oves windows from th e saveset w hen they are
destroyed. You use the CLX:r e m o v e -f r o m - s a v e -s e t function to remove an
existing window from your client’s saveset. Its form at is:
CLX:REMOVE-FROM-SAVE-SET window
where window is a CLX: w i n d o w object created by some other client.

13.6

Finding Extensions
CLX provides two functions for finding extensions included in a p articu lar
im plem entation. The c l x :q u e r y -e x t e n s i o n function retu rn s inform ation on a
specific extension, and th e c l x :l i s t -e x t e n s i o n s function re tu rn s th e extensions
supported by th e server.
The form at of th e c l x :q u e r y -e x t e n s i o n function is:
CLX:QUERY-EXTENSION display name
d isp la y

A CLX:DISPLAY object.

nam e

A CLX:STRINGABLE that nam es an extension.

If the extension specified by name is supported on display, c l x :q u e r y -e x t e n s i o n
re tu rn s three values:
m ajor-opcode

The m ajor opcode assigned to the extension by the server, or NIL i f it has
none.

first-even t

The base event type code assigned to the extension, or NIL if the
extension generates no additional event types.

first-error

The base error code assigned to the extension, or NIL if the extension
generates no additional error codes.

The form at of th e c l x :LIST-e x t e n s i o n s function is:
CLX:LIST-EXTENSIONS display &KEY :RESULT-TYPE
d isp la y

A CLX:DI SPLAY object.

:RESULT-TYPE

The LISP type o f the returned value.

The function re tu rn s a sequence of strings nam ing all the extensions supported
by the server th a t controls display.

Window and Session Management

13-11

Part IV
Reference to Common LISP X

P a rt IV contains, in alphabetical order, a description of each function and macro
exported from the c l x : package.

CLX:ACCESS-CONTROL Function

CLX:ACCESS-CONTROL Function
R eturns T if th e access control list is enabled on the specified display, n i l if it is
not. This function can be used w ith SETF if your client program is on the same
m achine as th e display.

Format
CLX:ACCESS-CONTROL d is p la y
Argument
display
A C LX :D ISPLA Y object.

Return Value
A CLX:BOOLEAN value.

CLX:ACCESS-HOSTS Function
R eturns th e access control list of th e specified display, and indicates w hether the
list is enabled. In VAX LISP, hosts are strings.

Format
CLX-.ACCESS-HOSTS d is p la y & KEY :RESULT-TYPE
Arguments
display
A CLX :D ISPLA Y object.
:RESULT-TYPE
The LISP type of the first re tu rn value. The default value is ' l i s t .

Return Values
Two values:
•

A sequence (by default, a list) of hosts.

•

A CLX:BOOLEAN value.

CLX—1

CLX:ACTIVATE-SCREEN-SAVER Function

CLX:ACTIVATE-SCREEN-SAVER Function
Enables th e screen saver feature.

Format
CLX:ACTIVATE-SCREEN-SAVER d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
Unspecified.

CLX:ADD-ACCESS-HOST Function
Adds the specified host to the access control list of th e specified display.

Format
CLX:ADD-ACCESS-HOST d is p la y h o s t
Arguments
display
A CLX:DISPLAY object.

host
A s t r i n g that names a machine.

Return Value
Unspecified.

CLX—2

CLX:ADD-TO-SAVE-SET Function

CLX:ADD-TO-SAVE-SET Function
Adds the specified window to your client’s saveset so th a t it is rem apped ra th e r
th a n destroyed when its client exits. The window m u st have been created by
some other client or an erro r occurs.

Format
CLX:ADD-TO-SAVE-SET w in d o w
Argument
window
A c l x :w i n d o w object.

Return Value
Unspecified.

CLX:ALIST Type Specifier
An association list of key nam es and d a ta types. This type is an abstraction th a t
is used for describing th e stru c tu re of other CLX types.

Representation
key-type-and-name datum-type-and-name

CLX:ALLOC-COLOR Function
Allocates a nam ed or exact color for shared use.
To use a nam ed color, pass a C LX : s t r i n g a b l e value for th e color argum ent, lb
specify an exact color, create a c l x :c o l o r stru ctu re and pass it and its associated
colormap to the c l x :a l l o c -c o l o r function.

Format
CLX:ALLOC-COLOR c o lo r m a p c o lo r

CLX—3

CLX:ALLOC-COLOR Function

Arguments
colormap
A CLX:COLORMAP object.

color
A CLX :STR IN GABLE value Or CLX: COLOR object.

Return Values
T hree values:
•

The CLX:p i x e l value of the allocated color.

•

A CLX:c o l o r stru ctu re th a t contains th e RGB values supported by the display
(the “screen color”).

•

A c l x :c o l o r stru ctu re th a t contains the RGB values specified by the
DECwindows nam ed color (the “exact color”).

CLX:ALLOC-COLOR-CELLS Function
Allocates cells in a specified colormap for exclusive use by a client program .
Use th is function on a pseudocolor or a gray-scale device. Use the
c l x :a l l o c -c o l o r -p l a n e s function on a direct color device.

Format
CLX:ALLOC-COLOR-CELLS c o lo r m a p c o lo rs &KEY :PLANES :CONTIGUOUS-P
:RESULT-TYPE
Arguments
colormap
T he c l x :c o l o r m a p in which cells a re allocated.

colors
The i n t e g e r num ber of pixels allocated.

:PLANES
The i n t e g e r num ber of planes returned. The default is 0.

:CONTIGUOUS-P
A c l x :b o o l e a n value: T specifies that the allocated color cells m u s t be contiguous
entries in the colormap.

:RESULT-TYPE
T h e L IS P ty p e o f th e r e tu r n valu es. T h e d e fa u lt v a lu e is ' l i s t .

CLX—4

C L X :A LLO C -C O LO R -C ELLS Function

Return Values
Two values:
•

A sequence of c l x :p i x e l values.

•

A sequence of c lx :mask1 6 values representing plane masks.

CLX:ALLOC-COLOR-PLANES Function
Allocates color cells for exclusive use by a client program. Use th is function to
sim ulate a direct color device. Use the c l x :ALLo c -c o l o r -c e l l s function on a
pseudocolor or gray-scale device.

Format
CLX:ALLOC-COLOR-PLANES c o lo r m a p c o lo rs &KEY :REDS :GREENS :BLUES
:CONTIGUOUS-P
:RESULT-TYPE
Arguments
colormap
The c l x :c o l o r m a p in which cells are allocated.

colors
The i n t e g e r num ber of pixels retu rn ed .
:REDS :GREENS :BLUES

T hree i n t e g e r values specifying th e num ber of bits set in th e retu rn ed plane
m asks. The default values are 0.
:CONTIGUOUS-P

A c l x :b o o l e a n value: T specifies that the allocated color cells mu s t be contiguous
entries in the colormap.

:RESULT-TYPE
The LISP type of the first re tu rn value. The default value is 'l i s t .

Return Values
F our values:
•

A sequence of CLX:p i x e l values.

•

A CLX:MASK16 value representing the plane-mask for red values.

•

A CLX:m a s k 16 value representing the plane-m ask for green values.

•

A CLX.-MASK16 value representing the plane-m ask for blue values.

CLX-5

C LX :A LLO W -E V E N TS Function

CLX:ALLOW-EVENTS Function
Allows processing of events th a t w ere not reported because a device was grabbed.

Format
CLX:ALLOW-EVENTS d is p la y m o d e &OPTIONAL tim e
Arguments
display
A CLX:DISPLAY object.

mode
A keyword th a t specifies which events are to be released. The possible values are:
: ASYNC-POINTER

A llo w s { jo in ter e v e n t p ro c e s s in g to c o n tin u e n o rm a lly a f t e r a
p o in te r h a s b e e n sto p p e d .

: SYNC-POINTER

A llo w s p o in te r e v e n t p ro c e s s in g to c o n tin u e n o rm a lly a f t e r a
p o in te r h a s b e e n fro z e n o r g ra b b e d u n ti l th e n e x t : BUTTON-PRESS
o r : BUTTON-RELEASE e v e n t is r e p o r te d to th e c lie n t.

: REPLY-POINTER

I f t h e p o in te r is a c tiv e ly g ra b b e d b y t h e c lie n t a n d is fro z e n , t h e
p o in te r g ra b is r e le a s e d a n d t h a t e v e n t is c o m p le te ly re p ro c e sse d .

: AS YNC-KEYBOARD

A llo w s k e y b o a rd e v e n t p ro c e s s in g to c o n tin u e n o rm a lly a f te r a
k e y b o a rd h a s b e e n fro z e n .

: SYNC-KEYBOARD

I f t h e k e y b o a rd is fro z e n a n d a c tiv e ly g ra b b e d b y t h e c lie n t,
k e y b o a rd e v e n t p ro c e s s in g c o n tin u e s a s u s u a l u n t i l t h e n e x t
: KEY-PRESS o r : KEY-RELEASE e v e n t is r e p o r te d to t h e c lie n t.

: REPLAY-KEYBOARD

I f th e k e y b o a rd is a c tiv e ly g ra b b e d b y t h e c lie n t, a n d is fro z e n
a s th e r e s u l t o f a n e v e n t h a v in g b e e n s e n t to t h e c lie n t e it h e r
fro m t h e a c tiv a tio n o f a p a s s iv e g ra b e s ta b lis h e d b y a c a ll to
CLX:GRAB-KEY o r fro m a p re v io u s CLX:ALLOW-EVENTS w ith
m o d e : SYNC-KEYBOARD (b u t n o t fro m a CLX:GRAB-KEYBOARD),
t h e k e y b o a rd g ra b is r e le a s e d a n d t h a t e v e n t is c o m p le te ly
re p ro c e s s e d .

: ASYNC-BOTH

I f t h e p o in te r a n d th e k e y b o a rd a r e fro z e n b y t h e c lie n t, e v e n t
p ro c e s s in g (fo r b o th d e v ic e s) c o n tin u e s n o rm a lly .

: SYNC-BOTH

I f t h e p o in te r a n d k e y b o a rd a r e fro z e n b y th e c lie n t, e v e n t
p ro c e s s in g (fo r b o th d e v ic e s) c o n tin u e s n o rm a lly u n ti l th e
n e x t : BUTTON-PRESS, : BUTTON-RELEASE, : K EY-PRESS, o r
: KEY-RELEASE e v e n t is r e p o r te d to t h e c lie n t fo r a g ra b b e d
d e v ic e , a t w h ic h tim e t h e d e v ic e s a g a in a p p e a r to freeze.

time
The C L X : t i m e s t a m p w hen events are released.

CLX-6

C LX:A LLO W -E V E N TS Function

Return Value
Unspecified.

CLX:ANGLE Type Specifier
N ote th a t the representation of a c l x :a n g l e differs from th e one actually
tra n sm itte d in the protocol.

Representation
(NUMBER , (‘ -2 PI) , (* 2 PI))

CLX:ARC-SEQ Type Specifier
An arc sequence is a c l x :r e p e a t - s e q u e n c e of f i x n u m ’s (rectangles) and
c l x :a n g l e ’s . Objects of type c l x :a r c - s e q m ay be passed to th e c l x :d r a w -a r c s
function.

Representation
(CLX::REPEAT-SEQ (FIXNUM x) (FIXNUM y)
(FIXNUM width) (FIXNUM height)
(CLX ANGLE anglel) (CLXANGLE angie2))

CLX:ARRAY-INDEX Type Specifier
This type is a n abstraction th a t places upper and lower bounds on integers used
as a rra y indexes in CLX.

Representation
(INTEGER 0, ARRAY-DIMENSION-LIMIT)

CLX:ATOM-NAME Function
Given an integer resource-id, this function re tu rn s the nam e of th e corresponding
atom on a specified display.

Format
CLX:ATOM-NAME d is p la y a t o m - id

CLX—7

CLX:ATO M -NA M E Function

Arguments
display
A CLX : DISPLAY object.

atom-id
An i n t e g e r value.

Return Value
A keyword.

CLX:BELL Function
Sounds th e keyboard bell. The volume m ay be specified.

Format
CLX:BELL d is p la y &OPTIONAL p e r c e n t - f r o m - n o r m a !
Arguments
display
A C LX :D ISPLA Y o b je c t.

percent-from-normal
A num ber betw een -100 and 100, inclusive. The default is 0.

Return Value
Unspecified.

CLX:BIT-GRAVITYType Specifier
The b it gravity of a window specifies w here its contents could be relocated
w hen it is resized. Objects of type C LX : b i t - g r a v it y are retu rn ed by the
c l x : w in d o w - b i t - g r a v it y function, and can be used as a s e t f value for th a t
accessor or for the : b i t - g r a v it y component of th e c l x : c r e a t e - w in d o w function.

Representation
(MEMBER :FORGET :STATIC :CENTER :NORTH :NORTH-EAST -.EAST SOUTH-EAST
SOUTH SOUTH-WEST :WEST :NORTH-WEST)

CLX-8

CLX:BITMAP Type Specifier

CLX:BITMAP Type Specifier
B itm aps are pixm aps of depth 1, th a t is, array s of bits.

Representation
(ARRAY BIT (* *))

CLX:BITMAP-FORMAT Structure
Objects of type c l x : b i t m a p - f o r m a t store th e form at in which im ages are
tran sm itted and received by th e server. The c l x : d i s p l a y - b i t m a p - fo r m a t
function re tu rn s the bitm ap-form at used by the specified display.
Constructor Function
CLX: MAKE-BITMAP-FORMAT

Accessor Functions
None of the following functions is a valid s e t f place:
N am e

T y p e D e fin itio n

CLX: B IT M A P-FO R M A T -L SB -FIR ST-P

CLX:BOOLEAN

CLX: BITMAP-FORMAT-PAD

(MEMBER 8 16 3 2 )

CLX: BITMAP-FORMAT-UNIT

(MEMBER 8 16 3 2 )

Deallocator Function
B itm ap-form ats are subject to garbage collection.

CLX:BITMAP-FORMAT-LSB-FIRST-P Function
Predicate indicates w hether th e lea st significant bit or th e m ost significant b it is
th e leftm ost bit in each u n it of a bitm ap.

Format
CLX:BITMAP-FORMAT-LSB-FIRST-P b it m a p - f o r m a t
Argument
bitmap-format
A CLX:BITMAP-FORMAT object.

CLX-9

CLXiBITMAP-FORMAT-LSB-FIRST-P Function

Return Value
A CLX: BOOLEAN value.

CLX:BITMAP-FORMAT-P Function
Predicate re tu rn s tru e if its argum ent is a bitm ap-form at.

Format
CLX:BITMAP-FORMAT-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX: BOOLEAN value.

CLX:BITMAP-FORMAT-PAD Function
R eturns the num ber of bits to a m ultiple of which each scanline is padded.

Format
CLX:BITMAP-FORMAT-PAD b itm a p -fo r m a t
Argument
bitmap-format
A CLX:BITMAP-FORMAT object.

Return Value
A m em b er o f (8 16 32).

CLX—10

C LX:B ITM A P-FO R M Ä T-U N IT Function

CLX:BITMAP-FORMAT-UNIT Function
R eturns th e num ber of bits in a u n it of a bitm ap.

Format
CLX:BITMAP-FORMAT-UNIT b itm a p - f o r m a t
Argument
bitmap-format
A CLX:BITMAP-FORMAT object.

Return Value
A member of (8 16 32).

CLX:BOOLEAN Type Specifier
R epresents values th a t are eith er tru e or false.

Representation
(OR NULL (NOT NULL))

CLX:CARD8 Type Specifier
An a b stra ct type used for m asks and other integer values less th a n 256.

Representation
FIXNUM

CLX:CARD16 Type Specifier
An a b stract type used for m asks and other integer values less th a n 65536.

Representation
FIXNUM

CLX—11

CLX:CARD29 Type Specifier

CLX:CARD29 Type Specifier
An ab stract type used for m asks and resource-ids.

Representation
INTEGER

CLX:CHANGE-ACTIVE-POINTER-GRAB Function
Modifies the active pointer grab on th e specified display.

Format
CLX:CHANGE-ACTIVE-POINTER-GRAB d is p la y e v e n t - m a s k
&OPTIONAL c u r s o r tim e
Arguments
display
A CLX:DISPLAY object.

event-mask
The C L X : p o i n t e r - e v e n t - m a s k to be changed.

cursor
The C L X : c u r s o r to be displayed d u ring th e grab.

time
The C L X : t im e s t a m p w hen the grab is changed.

Return Value
Unspecified.

CLX:CHANGE-KEYBOARD-CONTROL Function
Modifies the keyboard settings on th e specified display.

Format
CLX:CHANGE-KEYBOARD-CONTROL d is p la y
&KEY :KEY-CLICK-PERCENT :BELL-PERCENT :BELL-PITCH
:BELL-DURATION :LED :LED-MODE :KEY :AUTO-REPEAT-MODE
CLX—12

C L X :C H A N G E -K E Y B O A R D -C O N T R O L Function

Arguments
display
A CLXrDISPLAY object.
:KEY-CLICK-PERCENT

An integer th a t represents the volume of a key click from 0 (off) to 100 (loudest).
:BELL-PERCENT

An integer th a t specifies th e volume of a bell rin g from 0 (off) to 100 (loudest),
: DEFAULT, o r N IL .

:BELL-PITCH

An integer th a t specifies th e pitch of the bell in hertz, : d e f a u l t , or N IL .
:BELL-DURATION

An integer th a t specifies th e duration of a bell ring in m illiseconds, : d e f a u l t , or
N IL .

:LED

An integer whose l bits specify th a t th e corresponding LEDs (counting from 0)
a re affected by th e : l e d - m ode argum ent, or n i l .
:LED-MODE

Keyword :ON or :O FF th a t specifies the state of LEDs on the keyboard, or N IL .
:KEY

An integer th a t specifies th a t the corresponding key h as auto-repeat mode
enabled, or n i l .
:AUTO-REPEAT-MODE

Keyword : ON, : o f f , or : d e f a u l t th a t specifies the global auto-repeat mode for the
keyboard, or n i l .

Return Value
Unspecified.

CLX:CHANGE-KEYBOARD-MAPPING Function
Changes the m apping of keysyms to key codes.

Format
CLX:CHANGE-KEYBOARD-MAPPING d is p la y k e y s y m s
&KEY :START :END :FIRST-KEYCODE

CLX-13

C L X :C H A N G E -K E Y B O A R D -M A P P IN G Function

Arguments
display
A CLX : DISPLAY object.

keysyms
An array.
: START : END

Two c l x : a r r a y - i n d e x values th a t specify a subrange of keysyms. The default
value for : s t a r t is 0.
:FIRST-KEYCODE

The first keycode to store. The default value is the value of the : s t a r t keyword.

Return Value
Unspecified.

CLX:CHANGE-POINTER-CONTROL Function
Defines how fast the pointer cursor moves com pared to th e default speed
( : a c c e l e r a t i o n ) and how far it m u st move before acceleration is applied
( : THRESHOLD).

If you supply a num eric value for : ACCELERATION, it m u st be positive. CLX
rationalizes the value if necessary, and th e ratio m ay be rounded a rb itrarily by
the X server.

Format
CLX:CHANGE-POINTER-CONTROL d is p la y
&KEY ACCELERATION THRESHOLD
Arguments
display
A CLX:DISPLAY object.
:ACCELERATION

A n u m b e r, : d efau lt, o r n il .
^THRESHOLD
A n INTEGER, : DEFAULT, o r N IL .

CLX—14

CLXiCHANGE-POINTER-CONTROL Function

Return Value
Unspecified.

CLX:CHANGE-PROPERTY Function
A lters th e property list of the specified window. : s t a r t and : e n d affect
sub-sequences extracted from data. : t r a n s f o r m is applied to each extracted
elem ent.

Format
CLX:CHANGE-PROPERTY w in d o w p r o p e r t y d a ta ty p e fo r m a t
&KEY :MODE :START :END TRANSFORM
Arguments
window
A c l x :w i n d o w object.

property
The c l x :x a t o m value th a t nam es th e property to change.

data
A s e q u e n c e containing the new property data.

type
A CLX:XATOM value.

format
The size of th e data, e ith e r 8, 16 , or 32.
:MODE

One of :replace, :prepend, or : append. The default value is :REPLACE.
:START

An integer. The default value is 0.
:END

An integer or NIL.
:TRANSFORM

A function that takes an integer argument, or n i l .

Return Value
Unspecified.

CLX—15

C LX :C H A R A C T E R -»K E Y S Y M S Function

CLX:CHARACTER->KEYSYMS Function
Given a character, re tu rn s a list of all m atching keysyms. If a display is provided,
translations specific to th a t display are used; if not, global tran slatio n s are used.

Format
CLX:CHARACTER->KEYSYMS c h a r a c t e r &.OPTIONAL d is p la y
Arguments
character
Any LISP object.

display
A CLX:DISPLAY object.

Return Value
A list.

CLX:CHAR-ASCENT Function
R eturns the vertical distance from the baseline to the top of a character.

Format
CLX:CHAR-ASCENT fo n t in d e x
Arguments
font
A CLX:f o n t object.

index
The character number.

Return Value
A f i x n u m or n i l if index is out of bounds for font.

CLX—16

CLX:CH AR-ATTRIBUTES Function

CLX:CHAR-ATTRIBUTES Function
R eturns the attrib u tes of a character.

Format
CLX:CHAR-ATTRIBUTES fo n t in d e x
Arguments
font
A CLX:FONT object.

index
The character number.

Return Value
A f i x n u m or n i l if index is out of bounds for font.

CLX:CHAR-DESCENT Function
R eturns th e vertical distance from the baseline to th e bottom of a character.

Format
CLX:CHAR-DESCENT fo n t in d e x
Arguments
font
A CLX:FONT object.

index
The character number.

Return Value
A FIXNOM or n i l if index is out of bounds for font.

CLX—17

C LX :C H A R -LE FT-B E A R IN G Function

CLX:CHAR-LEFT-BEARING Function
R eturns the horizontal distance from th e origin to th e left edge of a ch aracter’s
bounding box.

Format
CLX:CHAR-LEFT-BEARING fo n t in d e x
Arguments
font
A CLX:FONT object.

Index
The ch aracter num ber.

Return Value
A f i x n u m or n i l if index is out of bounds for font.

CLX:CHAR-RIGHT-BEARING Function
R eturns th e horizontal distance from th e origin to the rig h t edge of a character’s
bounding box.

Format
CLX:CHAR-RIGHT-BEARING fo n t in d e x
Arguments
font
A CLX:FONT object.

index
The ch aracter num ber.

Return Value
A f i x n u m or n i l if index is out of bounds for font.

CLX-18

C LX :C H A R -W ID TH Function

CLX:CHAR-WIDTH Function
R eturns the horizontal distance from th e origin of the specified character to the
origin of th e next.

Format
CLX:CHAR-WIDTH fo n t in d e x
Arguments
font
A CLX :FONT object.

Index
The character num ber.

Return Value
A f ix n u m or n i l if index is out of bounds for font.

CLX:CIRCULATE-WINDOW-DOWN Function
Shuffles the specified window to the bottom of the stacking order so th a t none of
its siblings is obscured by it.

Format
CLX:CIRCULATE-WINDOW-DOWN w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
Unspecified.

CLX—19

C LX:C IR C U LA TE -W IN D O W -U P Function

CLX:CIRCULATE-WINDOW-UP Function
Brings the specified window up to the top of the stacking order so th a t it is not
obscured by any of its siblings.

Format
CLX:CIRCULATE-WINDOW-UP w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
Unspecified.

CLX:CLEAR-AREA Function
Clears (fills w ith th e background color or pixmap) a rectan g u lar a re a of a window.
Passing in a zero w idth or height is a no-op. A null w idth or height defaults to
the w idth or height of the window.

Format
CLX:CLEAR-AREA w in d o w & KEY :X :Y :WIDTH :HEIGHT :EXPOSURES-P
Arguments
window
The C LX : w in d o w object th a t contains the a re a to be cleared.
:X :Y

Two integers th a t specify th e X and Y coordinates of th e top left com er of the
a re a to be cleared. The default value for both keywords is 0, m eaning th e origin
of the window.
:WIDTH :HEIGHT

Two integers th a t specify the w idth and height, in pixels, of the a re a to be cleared.
:EXPOSURES-P

A c l x : b o o l e a n value th a t specifies w hether th e server sends exposure events for
the visible portions of window w hen they a re cleared.

CLX—20

C L X :C LE A R -A R E A Function

Return Value
Unspecified.

CLX:CLOSE-DISPLAY Function
Closes the connection betw een your client program and the X server th a t controls
the specified display. C L X : c l o s e - d i s p l a y destroys all client windows and frees all
client resources.

Format
CLX:CLOSE-DISPLAY d is p la y
Argument
display
The object of type c l x : d i s p l a y whose connection is to be closed.

Return Value
Unspecified.

CLX:CLOSE-DOWN-MODE Function
Specifies w h at happens to a client’s resources when the client disconnects
from th e server. The default close-down mode is : d e s t r o y , which frees all
client resources. The : r e t a i n - t e m p o r a r y and :R E T A I N - p e r m a n e n t modes
k e e p th e c lie n t’
s r e s o u r c e s a fte r it d iscon n ects, u n til a n o th e r c lie n t in v o k e s
CLX: KILL-TEM PORARY-CLIENTS or C L X :K IL L -C L IE N T S , respectively.

This function can be used w ith s e t f .

Format
CLX:CLOSE-DOWN-MODE d is p la y
Argument
display
A CLX:DISPLAY object.

CLX—21

C LX :C L O S E -D O W N -M O D E Function

Return Value
:DESTROY, :RETAIN-PERMANENT, or :RETAIN-TEMPORARY, indicating the close-down
m o d e of the specified display.

CLX:CLOSE-FONT Function
U nloads a font from LISP memory. It is a n erro r to access a closed font.

Format
CLX:CLOSE-FONT fo n t
Argument
font
A c l x : f o n t object.

Return Value
Unspecified.

CLX:COLOR Structure
Holds the representation of a color. Note th a t CLX red, green, and blue values
range from 0 to 1, indicating percentages, not from 0 to 65535 as in Xlib.
Constructor Function
CLX:MAKE-COLOR

Accessor Functions
U nless otherwise indicated, th e following functions can be used w ith s e t f :
N am e

T y p e D e fin itio n

CLX:COLOR-BLUE

(NUMBER 0 1)

CLX:COLOR-GREEN

(NUMBER 0 1)

CLX:COLOR-RED

(NUMBER 0 1)

CLX:COLOR-RGB

T h r e e CL X :RGB -VAL v a lu e s .
T h is fu n c tio n is n o t a v a lid SETF p la c e .

Deallocator Function
Instances of type c l x : COLOR a re subject to garbage collection.

CLX—22

C LX :C O LO R -B LU E Function

CLX:COLOR-BLUE Function
R eturns th e blue value of th e specified color.

Format
CLX:COLOR-BLUE c o lo r
Argument
color
A c l x :c o l o r object.

Return Value
A c l x :RGB-v a l value.

CLX:COLOR-GREEN Function
R eturns th e green value of the specified color.

Format
CLX:COLOR-GREEN c o lo r
Argument
color
A c l x :c o l o r object.

Return Value
A c l x :Rg b -v a l value.

CLX.-COLORMAP Structure
Colormaps are tables of color cells, each of which defines th e color of a pixel in
term s of its red, green, and blue components.
Constructor Function
CLX:MAKE-COLORMAP

CLX—23

CLX:COLORMAP Structure
Accessor Functions
Unless otherw ise indicated, th e following functions are not valid s e t f places:
N am e

T y p e D e fin itio n

CLX:COLORMAP-DISPLAY

CLX:DISPLAY

CLX:COLORMAP-ID

INTEGER

Predicates
CLX:COLORMAP-EQUAL, CLX:COLORMAP-P

Deallocator Function
CLX: FREE-COLORMAP

CLX:COLORMAP-DISPLAY Function
R eturns the display on which the specified colormap was created.

Format
CLXrCOLORMAP-DISPLAY c o lo r m a p
Argument
colormap
A CLX : COLORMAP object.

Return Value
A CLX:DISPLAY object.

CLX:COLORMAP-EQUAL Function
R eturns T if its two argum ents are th e sam e c l x : c o l o r m a p object.

Format
CLX:COLORMAP-EQUAL o b j e c t - 1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

CLX—24

C L X :C O LO R M A P -E Q U A L Function

Return Value
A CLX:BOOLEAN value.

CLX:COLORMAP-ID Function
R eturns the integer resource-id associated w ith the specified colormap.

Format
CLX:COLORMAP-ID c o lo rm a p
Argument
colormap
A CLX:COLORMAP object.

Return Value
A CLX:RESOURCE-ID value.

CLX:COLORMAP-P Function
R eturns T if its argum ent is a CLX: c o l o r m a p object.

Format
CLX:COLORMAP-P o b je c t
Argument
object
Any LISP object.

Return Value
A c l x :b o o l e a n value.

CLX—25

C L X :C O LO R -P Function

CLX:COLOR-P Function
R eturns tru e if its argum ent is a c l x :c o l o r object.

Format
CLX:COLOR-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:COLOR-RED Function
R eturns th e red value of the specified color.

Format
CLX:COLOR-RED c o lo r
Argument
color
A c l x :c o l o r object.

Return Value
A CLX:RGB-VAL value.

CLX:COLOR-RGB Function
R eturns th e three values of the red, green, and blue components of the specified
color.

CLX-26

C LX:C O LO R -R G B Function

Format
CLX:COLOR-RGB c o lo r
Argument
color
A c l x :c o l o r object.

Return Values
Three c l x :RGB-v a l values:
red
green
blue

CLX:CONVERT-SELECTION Function
Asks the owner of the specified selection (global property) to convert it to the
specified d a ta type.

Format
CLX:CONVERT-SELECTION s e le c tio n ty p e r e q u e s t o r &OPTIONAL p r o p e r t y tim e
Arguments
selection type
Tw o c l x :x a t o m values.

requestor
The c l x :w i n d o w object th a t receives selection notification.

property
The c l x :x a t o m value of th e selection.

time
A CLX:TIMESTAMP value.

Return Value
Unspecified.

CLX—27

C LX :C O P Y-A R EA Function

CLX:COPY-AREA Function
Copies a rectan g u lar area of one draw able to another drawable.

Format
CLX:COPY-AREA s rc g c o n te x t s r c - x s r c - y w id th h e ig h t d s t d s t-x d s t-y
Arguments
src
The c l x :d r a w a b l e object th a t contains th e a re a to copy.

gcontext
The c l x :g c o n t e x t object th a t contains the copy function to use (see the
description of CLX: l o g Ic a l -op values).

src-x src-y
Two integers th a t specify the X and Y coordinates of the origin of the area.

width height
Two integers th a t specify th e dim ensions, in pixels, of the area.

dst
The c l x :d r a w a b l e object in which the copy is displayed.

dst-x dst-y
Two integers th a t specify the X and Y coordinates of th e origin w here the copied
a re a is displayed.

Return Value
Unspecified.

CLX:COPY-COLORMAP-AND-FREE Function
C reates a new colormap for th e sam e screen a s th e given colormap. All existing
allocations are moved from th e given colorm ap to the new colormap, and freed
in the given colormap. The values of o ther en tries in the new colormap are
unspecified.

Format
CLX:COPY-COLORMAP-AND-FREE c o lo r m a p

CLX—28

C L X :C O P Y -C O LO R M A P -A N D -FR E E Function

Argument
colormap
A CLX : COLORMAP object.

Return Value
The newly copied c l x :c o l o r m a p object.

CLX:COPY-GCONTEXT Function
Copies all components of the source GContext to th e destination GContext.

Format
CLX:COPY-GCONTEXT s rc d s t
Arguments
src dst
Two CLX:GCONTEXT objects.

Return Value
Unspecified.

CLX:COPY-GCONTEXT-COMPONENTS Function
Copies only specified components of th e source GContext to the destination
GContext.

Format
CLX:COPY-GCONTEXT-COMPONENTS s rc d s t &REST k e y s
Arguments
src dst
Two CLX:GCONTEXT objects.

keys
A lis t of CLX:GCONTEXT-KEY values.

CLX—29

C LX :C O P Y -G C O N TE X T-C O M P O N E N TS Function

Return Value
Unspecified.

CLX:COPY-IMAGE Function
Copies an im age w ith optional subim aging and form at conversion.

Format
CLX:COPY-IMAGE im a g e &KEY :X :Y :WIDTH .HEIGHT :RESULT-TYPE
Arguments
image
A CLX: i m a g e object to copy.
:X :Y

The X and Y coordinates of the subim age to copy. The default values are 0.
:WIDTH :HEIGHT

The dim ensions of the subim age.
:RESULT-TYPE

A sequence type specifier for the re tu rn value. The default is the sam e as the
original image.

Return Value
The newly copied i m a g e object.

CLX:COPY-PLANE Function
Copies a single plane from a specified a re a of a draw able, and uses it to modify
an area of an o th er draw able.

Format
CLX:COPY-PLANE s r c g c o n t e x t p la n e s r c - x s r c - y w id th h e ig h t d s t d s t-x d s t-y
Arguments
src
The C L X : d r a w a b l e object th a t contains th e a re a to modify.

CLX—30

CLX:COPY-PLANE Function
gcontext
The c l x : g c o n t e x t object th a t contains the copy function to be used (see the
description of c l x : l o g i c a l - o p values).

plane
An integer th a t specifies which bit plane of the source a re a is copied.

src-x src-y
Two integers th a t specify the X and Y coordinates of the origin of the source area.

width height
Two integers th a t specify th e dim ensions, in pixels, of the source area.

dst
The c l x : d r a w a b le object in which th e modified a re a is displayed.

dst-x dst-y
Two integers th a t specify the X and Y coordinates of the origin w here the modified
a re a is displayed.

Return Value
Unspecified.

CLX:CREATE-COLORMAP Function
C reates a c l x : co lo r m a p object for the screen th a t is associated w ith the window
argum ent.

Format
CLX:CREATE-COLORMAP visual window &OPTIONAL alloc-p
Arguments
visual
An i n t e g e r resource-id.

window
A c l x : w in d o w object.

alloc-p
A c l x : b o o l e a n value th a t specifies w h ether the colormap is allocated w ritable
(clients can allocate cells for exclusive use) or shareable.

CLX—31

C LX :C R E A TE -C O LO R M A P Function

Return Value
The newly created c l x :c o l o r m a p object.

CLX:CREATE-CURSOR Function
C reates a CLX:c u r s o r object from an im age draw n in a pixmap.

Format
CLX:CREATE-CURSOR &KEY :SOURCE :MASK :X :Y FOREGROUND
BACKGROUND
Arguments
:SOURCE

The c l x :p i x m a p object th a t contains the cursor image.
:MASK

A CLX : P IXMAP object th a t specifies which bits of th e source pixm ap to use (the
cursor shape).
:X :Y

Two integers specifying the X and Y coordinates of the cursor’s hot spot.
:FOREGROUND B ACKG ROUND

Two c l x :c o l o r objects th a t specify the foreground and background of the cursor.

Return Value
The newly created c l x :c u r s o r object.

CLX:CREATE-GCONTEXT Function
R eturns an instance of the c l x :g c o n t e x t stru ctu re containing the specified
graphics characteristics. For all components, a value of n i l causes the default
GContext value to be used.
NOTE

U sing a c l x :STRINGABLE value for :F0n t causes an im plicit call to
CLX:OPEN-FONT.
If : c a c h e -p is true, th en GContext state is cached locally, and changing a
GContext component h as no effect unless th e new value differs from the cached
value. Com ponent changes (s e t f s and c l x :WITH-g c o n t e x t ) are always deferred
regardless of the cache mode, and are sent over the protocol only w hen required
by a local operation or by an explicit call to c l x :F0Rc e - g c q n t e x t -c h a n g e s .

CLX—32

CLXrCREATE-GCONTEXT Function

Format
CLX:CREATE-GCONTEXT
&KEY :DRAWABLE FUNCTION -.PLANE-MASK FOREGROUND
BACKGROUND :LINE-WIDTH :LINE-STYLE :CAP-STYLE
:JOIN-STYLE FILL-STYLE FILL-RULE :ARC-MODE :TILE
:STIPPLE :TS-X :TS-Y FONT :SUBWINDOW-MODE
FXPOSURES :CLIP-X :CLIP-Y :CLIP-MASK BLIP-ORDERING
:DASH-OFFSET BASHES :CACHE-P
Arguments
:DRAWABLE
A CLX:DRAWABLE Value.
:FUNCTION
A CLX:LOGICAL-OP value or NIL.

:PLANE-MASK FO R EG R O U N D BACKG RO UND :LINE-WIDTH
Integers or n i l .
:LINE-STYLE
NIL or one of :SOLID, :DASH, or :DOUBLE-DASH.

:CAP-STYLE
NIL or one of :NOT-LAST, :BDTT, :ROUND, Or PROJECTING.

:JOIN-STYLE
NIL or one of :MI TER, :R0UND, or :BEVEL.

F ILL-S TY LE
NIL or one of :SOLID, :TILED, :OPAQOE-STIPPLED, or :STIPPLED.

FIL L -R U L E
nil

or either :e v e n -o d d or :w i n d i n g .

:ARC-MODE
nil

or either :c h o r d or :p i e -s l i c e .

:TILE :STIPPLE
T w o c l x :p i x m a p objects.

:TS-X :TS-Y
Integers.

FONT
A

c l x :f o n t

object.

:SUBWINDOW-MODE
nil

or either :c l i p -b y -c h i l d r e n or :i n c l u d e - i n f e r i o r s .

EXPOSURES
nil

or either :ON or :OFF.

CLX—33

CLXrCREATE-GCONTEXT Function
:CLIP-X CLIP-Y

Integers.
:CLIP-MASK
N IL or :NONE, Or e ith e r a CLX:PIXMAP or a C LX :RECT-SEQ .

:CLIP-ORDERING
N IL or one of i ONSORTED, :Y -S 0R T E D ,

: YX-SORTED, Or : YX-BANDED.

: DASHES

An integer or a sequence of integers.
:DASH-OFFSET

An integer.
:CACHE-P

A c l x : b o o l e a n value. The default i s T.

Return Value
The newly created c l x : g c o n t e x t object.

CLX:CREATE-GLYPH-CURSOR Function
C reates a c l x : c u r s o r object from a character (glyph) in the specified font. The
: SOURCE-FONT, : SOURCE-CHAR, : FOREGROUND, and : BACKGROUND argum ents are
required.

Format
CLX:CREATE-GLYPH-CURSOR &KEY :SOURCE-FONT :SOURCE-CHAR
:MASK-FONT .MASK-CHAR
FOREGROUND BACKGROUND
Arguments
:SOURCE-FONT

The C L X : f o n t object th a t includes the glyph used to create th e cursor.
:SOURCE-CHAR

An integer th a t identifies the glyph in th e source font.
:MASK-FONT

A C L X : f o n t object th a t contains th e glyph to be used as a m ask for the cursor
shape. The default value is n i l , which specifies the source font.
:MASK-CHAR

An integer th a t identifies th e glyph used as a m ask to determ ine which pixels of
th e source character are displayed. The default value is n i l , which specifies th a t
all bits of the source character a re used.
CLX—34

C LX:C R EA TE-G LYPH -C U R SO R Function

FO R E G R O U N D B ACKG RO UND

Two CLX-COLOR objects th a t specify the foreground and background of the cursor
to be created.

Return Value
The newly created CLX: CURSOR object.

CLX:CREATE-IMAGE Function
R eturns an i m a g e -X, i m a g e -x y , or i m a g e - z structure, depending on the type of
the : d a t a param eter.

Format
CLX:CREATE-IMAGE &KEY :WIDTH :HEIGHT :DEPTH :DATA :RED-MASK
:GREEN-MASK :BLUE-MASK :BITS-PER-PIXEL
:FORMAT :SCANLINE-PAD :BYTES-PER-LINE
:BYTE-LSB-FIRST-P :BIT-LSB-FIRST-P
Arguments
:W IDTH :HE1GHT

Integers th a t specify th e w idth and height of the image, m easured in pixels.
These argum ents are required.
:DEPTH

An integer th a t specifies the depth of th e image. The default is 1.
:DATA

A sequence in which to store the data. Its type depends on the value of the
: f o r m a t argum ent:
: FORMAT : BITMAP

(ARRAY CLX: CARD8 (* )

: FORMAT :XY-PIXMAP

(L IS T CLXrBITMAP)

: FORMAT :Z-PIX M A P

CLX:PIXARRAY

)

:RED-MASK :GREEN-MASK :BLUE-MASK

T hree c l x : p i x e l values.
:BITS-PER-PIXEL
(MEMBER 1 4 8 1 6 24 3 2 )

FORM AT
(MEMBER -.BITMAP -.XY-PIXMAP :Z -PIX M A P)

:SCANLINE-PAD
(MEMBER 8 1 6 3 2 )

CLX—35

CLX:CREATE-IMAGE Function

:BYTES-PER-LINE

Specifies the num ber of bytes in the client image betw een the s ta rt of one scanline
and the s ta rt of th e next.
:BYTE-LSB-FIRST-P :BIT-LSB-FIRST-P

Two c l x :b o o l e a n values th a t specify byte and bit ordering.

Return Value
An i m a g e -x, i m a g e -XY, or i m a g e - z structure, depending on the type of the :DATA
parameter.

CLX:CREATE-PIXMAP Function
C reates a c l x :PIXm a p object w ith the specified characteristics.

Format
CLX:CREATE-PIXMAP &KEY :WIDTH rHEIGHT :DEPTH :DRAWABLE
Arguments
:WIDTH :HEIGHT :DEPTH

Integers th a t specify the dim ensions of the pixmap. These argum ents are
required.
:DRAWABLE

A CLX: d r a w a b le object th a t provides display inform ation. This argum ent is
required.

Return Value
The newly created c l x :p i x m a p object.

CLX:CREATE-WINDOW Function
C reates a c l x :w i n d o w object w ith the specified a ttrib u tes. The appropriate
display is obtained from th e parent argum ent.

Format
CLXrCREATE-WINDOW &KEY :PARENT :X :Y :WIDTH :HEIGHT :DEPTH
:BORDER-WIDTH :CLASS rVISUAL
BACKGROUND BORDER rGRAVITY
BIT-GRAVITY BACKING-STORE
CLX—36

CLX:CREATE-WINDOW Function
BACKING-PLANES :BACKING-PIXEL
SAVE-UNDER :EVENT-MASK
DO-NOT-PROPAGATE-MASK
OVERRIDE-REDIRECT :COLORMAP
CURSOR
Arguments
:PARENT
A c l x :w i n d o w th a t specifies th e p a re n t of the window retu rn ed by th is function.
:X :Y
Integers th a t specify the X and Y coordinates of th e top-left corner, m easured in
pixels from the top-left corner of th e parent.
:WIDTH :HEIGHT
Integers th a t specify the w idth and height, m easured in pixels, not including the
border.
:DEPTH
An integer th a t specifies th e num ber of bits per pixel. The default value is 0.
:BORDER-WIDTH
An integer th a t specifies th e size of the border, m easured in pixels. The default
value is 0.
:CLASS
One of : c o p y , :i n p u t -o u t p u t , or : i n p u t -o n l y , specifying w hether the window
can display output. The default value is : c o p y , which m eans th e sam e class as
th e p aren t window.
rVISUAL
E ith e r a c l x :v i s u a l value or :COPY. The default value is :COPY, specifying the
sam e visual inform ation as the p a re n t window.
BACKGROUND
A CLX:PIXEL value, a CLX:PIXMAP object, :NONE, :p a r e n t -r e l a t i v e , or NIL,
specifying the background.

BORDER
A c l x :p i x e l value, c l x :PIXm a p object, or :COPY, specifying the border.
:GRAVITY
A c l x :w i n -g r a v i t y value that specifies h o w the wind o w is positioned after its
parent is resized.

BIT-GRAVITY
A CLX: BIT-GRAVITY value that specifies which region of the w i n d o w is retained
after it is resized.

BACKING-STORE
:n o t -u s e f u l , :w h e n -m a p p e d , :a l w a y s , or NIL, specifying w h e n the server
maintains the contents of the window.

CLX—37

C LX :C R E A TE -W IN D O W Function

:BACKING-PLANES
A c l x :p i x e l or n i l , specifying which b it planes of the window hold dynamic data
th a t m u st be preserved in -.b a c k i n g - s t o r e .
:BACKING-PIXEL
A CLX:PIXEL value or n i l , specifying the value to use in planes not covered by
:BACKING-PLANES.

:SAVE-UNDER
E ith e r : ON or : OFF, specifying w hether th e server saves the contents of windows
obscured by th e created window.
:EVENT-MASK
A c l x :e v e n t -m a s k or n i l , specifying which events in te rest the client in th is
window.
:DO-NOT-PROPAGATE-MASK
A CLX:d e v i c e -e v e n t -m a s k or n i l , specifying which events should not be
propagated to ancestor windows.

:OVERRIDE-REDIRECT
E ith er :ON or :OFF, specifying w hether calls to m ap and configure the window
should override a request from an o th er client to redirect those calls.
:COLORMAP
A c l x :c o l o r m a p , :c o p y , or n i l , specifying th e colormap th a t best reflects th e tru e
colors of the window.
:CURSOR
A CLX: c u r s o r object, :NONE, or NIL, specifying th e cursor shape to be used w hen
th e pointer is in th e window.

R eturn V alue
The newly created c l x :w i n d o w object.

CLX:CURSOR-DISPLAY Function
R eturns th e c l x :D!s p l a y object for which th e specified cursor w as created.

Format
CLX:CURSOR-DISPLAY c u r s o r
Argument
cursor
A c l x : c u r s o r object.

CLX—38

C LX:C U R SO R -D ISP LA Y Function

Return Value
A CLX:DISPLAY object.

CLX:CURSOR-EQUAL Function
R eturns tru e if its two argum ents are the sam e c l x :c u r s o r object.

Format
CLX:CURSOR-EQUAL o b je c t - 1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

Return Value
A c l x :b o o l e a n value.

CLX:CURSOR-ID Function
R eturns th e integ er resource-id of the specified cursor.

Format
CLX:CURSOR-ID c u r s o r
Argument
cursor
A c l x :c u r s o r object.

Return Value
A c l x :r e s o u r c e - id value.

CLX—39

C LX :C U R S O R -P Function

CLX:CURSOR-P Function
This predicate re tu rn s tru e if its argum ent is of type c l x :c u r s o r .

Format
CLX:CURSOR-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:DELETE-PROPERTY Function
Removes th e specified property from the specified window’s property list.

Format
CLX:DELETE-PROPERTY w in d o w p r o p e r t y
Arguments
window
A c l x :w i n d o w object.

property
A c l x :x a t o m value.

Return Value
Unspecified.

CLX—40

C L X :D E STR O Y-SU B W IN D O W S Function

CLX:DESTROY-SUBWINDOWS Function
Calls c l x :d e s t r o y -w i n d o w on all the children of th e specified window, in
bottoxn-to-top stacking order.

Format
CLX:DESTROY-SUBWINDOWS w in d o w
Argument
window
A c l x :w i n d o w object.

Return Value
Unspecified.

CLX:DESTROY-WlNDOW Function
If the specified window is m apped, a call to c l x :u n m a p -w i n d o w is performed
autom atically. The window and all its children a re th en destroyed, in order
from the specified window downward. The order am ong siblings a t each level is
undefined. A : d e s t r o y -n o t i f y event is generated for each window.
N orm al exposure processing is performed on all windows form erly obscured by
the specified window or its children.
If th e window argum ent is a root window, this function h a s no effect.

Format
CLX:DESTROY-WINDOW w in d o w
Argument
window
A CLX : w i n d o w object.

Return Value
Unspecified.

CLX—41

CLX:DEVICE-EVENT-MASK Type Specifier

CLX:DEVICE-EVENT-MASK Type Specifier
Objects of type c l x :d e v i c e -e v e n t -m a s k are retu rn ed by the
function and m ay be passed to th e c l x :c r e a t e -w i n d o w
function as the value of the :DO-n o t -p r o p a g a t e -m a s k argum ent.
c l x :MAKE-e v e n t -m a s k

Representation
(OR CLX:MASK32 (LIST CLX:DEVICE-EVENT-MASK-CLASS))

CLX:DEVICE-EVENT-MASK-CLASS Type Specifier
A bstract type used to define CLX:d e v i c e -e v e n t -m a s k values.

Representation
(MEMBER :KEY-PRESS :KEY-RELEASE :BUTTON-PRESS BUTTON-RELEASE
:POINTER-MOTION :BUTTON-1 -MOTION :BUTTON-2-MOTION
:BUTTON-3-MOTION :BUTTON-4-MOTION :BUTTON-5-MOTION
:BUTTON-MOTION)

CLX:DISCARD-CURRENT-EVENT Function
Deletes the event a t the head of th e event queue.

Fo rm at

CLX:DISCARD-CURRENT-EVENT d is p la y
Argument
display
A CLX :DISPLAY object.

Return Value
T if an event was deleted; n i l if the queue wa s empty.

CLX—42

C LX:D IS C A R D -FO N T-IN FO Function

CLX:DISCARD-FONT-INFO Function
D iscards any state th a t can be re-obtained by functions th a t generate a
Q ueryFont protocol request, such as c l x :CHAR-a s c e n t , c l x :f o n t -m a x -w i d t h ,
and so on. This is sim ply a perform ance h in t for m em ory-lim ited system s.

Format
CLX:DISCARD-FONT-INFO fo n t
Argument
font
A CLX:FONT object.

Return Value
Unspecified.

CLX:DISPLAY Structure
This structure contains inform ation about th e display itself and th e X server
controlling the display.

Constructor Function
An instance of th e c l x :d i s p l a y stru ctu re is retu rn ed by th e c l x :o p e n -d i s p l a y
function.
Accessor Functions

U nless otherw ise indicated, these functions are not valid s e t f places.
N am e

T y p e D e fin itio n

CLX:DISPLAY-BITMAP-FORMAT

CLX:BITMAP-FORMAT

CLX:DISPLAY-DEFAULT-SCREEN

CLX:SCREEN

C L X :DISPLAY-IMAGE-LSB-FIRST-P

CLX:BOOLEAN

CLX:DISPLAY-MAX-KEYCODE

FIXNUM

C L X :DISPLAY-MAX-REQUEST-LENGTH

FIXNUM

CLX:DISPLAY-MIN-KEYCODE

FIXNUM

CLX:DISPLAY-MOTION-BUFFER-SIZE

FIXNUM

CLX:DISPLAY-PIXMAP-FORMATS

LIST ofCLX:PIXMAP-FORMAT

CLX:DISPLAY-PROTOCOL-MAJOR-VERSION

FIXNUM

CLX:DISPLAY-PROTOCOL-MINOR-VERSION

FIXNUM

CLX—43

CLX:DISPLAY Structure

N am e

T y p e D e fin itio n

CLX:DISPLAY-RELEASE-NUMBER

FIXNUM

CLX:DISPLAY-ROOTS

LIST of CLX: SCREEN

CLX:DISPLAY-VENDOR-NAME

STRING

Deallocator Function
CLX:CLOSE-DISPLAY

CLX:DISPLAY-AFTER-FUNCTION Function
Specifies a function to be called a fter every protocol request is generated, even
those inside a n explicit c l x :WITH-d i s p l a y macro. The function is called inside
th e effective c l x :WITH-d i s p l a y for the associated request. Can be set, for
example, to # ' CLX:DISPLAY-FORCE-OUTP ü T or # ' CLX:DISPLAY-FINISH-OUTPUT.
T he default value is n i l , m eaning th a t no after function is defined.
c l x :Di s p l a y -a f t e r -f u n c t i o n is never called from inside the after function
itself.

Format
CLX:DISPLAY-AFTER-FUNCTION d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
n i l , or a function that takes a c l x :d i s p l a y

object.

CLX:DISPLAY-BITMAP-FORMAT Function
R eturns th e default bitm ap-form at on the specified display.

Format
CLX:DISPLAY-BITMAP-FORMAT d is p la y

CLX—44

C LX:D ISPLA Y-B ITM A P-FO R M A T Function

Argument
display
A CLX:DISPLAY object.

Return Value
A CLX :BITMAP-FORMAT object.

CLX:DISPLAY-DEFAULT-SCREEN Function
R eturns th e default screen on the specified display.

Format
CLX:DISPLAY-DEFAULT-SCREEN d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A CLX: SCREEN object.

CLX:DISPLAY-FINISH-OUTPUT Function
Forces all requested o u tp u t to be displayed, th en causes a round-trip request
betw een server and client to ensure th a t all possible errors and events have been
received, d i s p l a y -a f t e r -f u n c t i o n can be set to this function while debugging so
th a t error m essages a re displayed immediately.

Format
CLX:DISPLAY-FINISH-OUTPUT d is p la y
Argument
display
A CLX:DISPLAY object.

CLX—45

C LX:D IS P LA Y-FIN ISH -O U TPU T Function

Return Value
Unspecified.

CLX:DISPLAY-FORCE-OUTPUT Function
Flushes the output buffer used by CLX to store requests. All requests in the
output buffer th a t have not yet been sent are tran sm itted to the X server.

Format
CLX:DISPLAY-FORCE-OUTPUT d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
Unspecified.

CLX:DISPLAY-IMAGE-LSB-FIRST-P Function
Indicates w hether im age d ata is stored w ith the least significant b it first.

Format
CLX:DISPLAY-IMAGE-LSB-FIRST-P d is p la y
Argument
display
A CLXrDISPLAY object.

Return Value
T if the byte order for image data is least significant bit first; n i l if it is most
significant bit first.

CLX—46

C LX:D ISPLA Y-M A X-K EYC O D E Function

CLX.DISPLAY-MAX-KEYCODE Function
Indicates the largest keycode value tra n sm itte d by the X server. For more
inform ation, see th e X Window System: C Library and Protocol Reference.

Format
CLX:DISPLAY-MAX-KEYCODE d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A n integer.

CLX:DISPLAY-MAX-REQUEST-LENGTH Function
R eturns the m axim um length of a request accepted by the X server, in 4-byte
units. For more inform ation, see the X Window System: C Library and Protocol

Reference.

Format
CLX:DISPLAY-MAX-REQUEST-LENGTH d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
An integer.

CLX—47

C LX :D IS P LA Y-M IN -K EY C O D E Function

CLX:DISPLAY-MIN-KEYCODE Function
Indicates the sm allest keycode value tra n sm itte d by the X server. For more
inform ation, see the X Window System: C Library and Protocol Reference.

Format
CLX:DISPLAY-MIN-KEYCODE d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A n integer.

CLX:DISPLAY-MOTION-BUFFER-SIZE Function
The X server m ay m ain tain th e recent history of pointer motion. This function
indicates the approxim ate size of the pointer motion buffer.

Format
CLX:DISPLAY-MOTION-BUFFER-SIZE display
Argument
display
A CLX:DISPLAY object.

Return Value
An integer.

CLX—48

CLX:DISPLA Y-P Function

CLX:DISPLAY-P Function
R eturns t if its argum ent is a c l x :d i s p l a y object.

Format
CLX:DISPLAY-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:DISPLAY-PIXMAP-FORMATS Function
L ists the pixm ap form at of each depth supported by the display.

Format
CLX:DISPLAY-PIXMAP-FORMATS d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A list of CLX:PIXMAP-FORMAT objects.

CLX:DISPLAY-PROTOCOL-MAJOR-VERSION
Function
R eturns th e version num ber of the X protocol.

CLX—49

C LX :D IS P LA Y-PR O TO C O L-M A JO R -V ER SIO N Function

Format
CLX:DISPLAY-PROTOCOL-MAJOR-VERSION d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A n integer.

CLX:DISPLAY-PROTOCOL-MINOR-VERSION
Function
R eturns the release num ber of the X protocol.

Format
CLX:DISPLAY-PROTOCOL-MINOR-VERSION d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
An integer.

CLX:DISPLAY-RELEASE-NUMBER Function
R eturns the release num ber of the X server. This value depends on the
im plem entation.

Format
CLX:DISPLAY-RELEASE-NU MBER d is p la y

CLX-50

C LX:D ISPLA Y-R ELEA S E-N U M B E R Function

Argument
display
A CLX:DISPLAY object.

Return Value
An integer.

CLX:DISPLAY-ROOTS Function
R eturns a list of c l x :s c r e e n objects, one for each screen attached to the specified
display.

Format
CLX:DISPLAY-ROOTS d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
A list of c l x :s c r e e n objects.

CLX:DISPLAY-VENDOR-NAME Function
R eturns th e nam e of the im plem entor of th e X server.

Format
CLX:DISPLAY-VENDOR-NAME d is p la y
Argument
display
A CLX:DISPLAY object.

CLX-51

C LX:D IS P LA Y-VE N D O R -N A M E Function

Return Value
A string.

CLX:DRAWABLE Type Specifier
A CLX : d r a w a b l e is either a window or a pixmap. Objects of type CLX iDRAWABLE
can be passed to any of the c l x :DRAW- and CLX:d r a w a b l e - functions.

Representation
(OR CLX:WINDOW CLX:PIXMAP)

CLX:DRAWABLE-BORDER-WIDTH Function
R eturns the w idth of the border of the specified draw able, in pixels. This function
can be used w ith s e t f .

Format
CLX:DRAWABLE-BORDER-WIDTH d r a w a b le
Argument
drawable
A CLXiDRAWABLE object.

Return Value
An integer.

CLX:DRAWABLE-DEPTH Function
R eturns the num ber of bits per pixel in the specified draw able. This function is
not a valid s e t f place.

Format
CLX:DRAWABLE-DEPTH d r a w a b le

CLX-52

C LX:D R A W A B LE-D E PTH Function

Argument
drawable
A CLX: DRAWABLE object.

Return Value
An integer.

CLX:DRAWABLE-DISPLAY Function
R eturns the display on which the specified draw able appears. This function is not
a valid s e t f place.

Format
CLX:DRAWABLE-DISPLAY d r a w a b le
Argument
drawable
A CLX:DRAWABLE object.

Return Value
A CLX:DISPLAY object.

CLX:DRAWABLE-EQUAL Function
R eturns T if its two argum ents are th e sam e c l x :d r a w a b l e object.

Format
CLX:DRAWABLE-EQUAL o b j e c t - 1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

CLX—53

C LX :D R A W A B LE-EQ U A L Function

Return Value
A CLX:BOOLEAN value.

CLX:DRAWABLE-HEIGHT Function
R eturns the height of the specified draw able, in pixels. For windows, this is the
inside height, excluding any border. This function can be used w ith s e t f .

Format
CLX:DRAWABLE-HEIGHT d r a w a b le
Argument
drawable
A CLX : DRAWABLE object.

Return Value
An integer.

CLX:DRAWABLE-ID Function
R eturns the integer resource-id of th e specified draw able. This function is not a
valid s e t f place.

Format
CLX:DRAWABLE-ID d r a w a b le
Argument
drawable
A CLX:DRAWABLE object.

Return Value
A CLX:RESOURCE-ID value.

CLX-54

C LX:D R A W A B LE-P Function

CLX:DRAWABLE-P Function
R eturns t if its argum ent is a c l x :d r a w a b l e object.

Format
CLX:DRAWABLE-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:DRAWABLE-ROOT Function
R eturns the root window of th e specified draw able. This function is not a valid
s e t f place.

Format
CLX:DRAWABLE-ROOT d r a w a b le
Argument
drawable
A CLX:DRAWABLE object.

Return Value
A c l x :w i n d o w object.

CLX—55

C LX:D R A W A B LE-W ID TH Function

CLX:DRAWABLE-WIDTH Function
R eturns th e w idth, in pixels, of the specified draw able. For windows, th is is the
inside width, excluding any border. This function can be used w ith s e t f .

Format
CLX:DRAWABLE-WIDTH d r a w a b le
Argument
drawable
A CLX: DRAWABLE object.

Return Value
An integer.

CLX:DRAWABLE-X Function
R eturns the X coordinate of th e top-left com er of th e specified draw able,
m easured in pixels from th e top-left com er of its p arent. This function can be
used w ith s e t f .

Format
CLX:DRAWABLE-X d r a w a b le
Argument
drawable
A c l x :d r a w a b l e object.

Return Value
An integer.

CLX—56

C LX:D R A W A B LE-Y Function

CLX:DRAWABLE-Y Function
R eturns the Y coordinate of the top-left com er of the specified draw able,
m easured in pixels from the top-left com er of its parent. This function can be
used w ith s e t f .

Format
CLX:DRAWABLE-Y d r a w a b le
Argument
drawable
A CLX:DRAWABLE object.

Return Value
An integer.

CLX:DRAW-ARC Function
D raw s the arc defined by a portion of th e ellipse inscribed w ithin a specified
rectangle. The angle th a t determ ines th e sta rtin g position of the arc is specified
relative to the 3 o’clock position of th e bounding rectangle; th e angle th a t
determ ines th e extent of the arc is specified relative to the startin g position
of th e arc. By default, th e angles are m easured in radians.

Format
CLX:DRAW-ARC d r a w a b le g c o n te x t x y w id th h e ig h t a n g l e l a n g le 2
&OPTIONAL fill-p d e g r e e s - p
Arguments
drawable
The c l x :d r a w a b l e object in which th e arc is draw n.

gcontext
The c l x :g c o n t e x t object th a t specifies th e graphics characteristics (such as
arc-mode) of th e arc.

xy
Two integers th a t specify the X and Y coordinates of the top-left corner of the
arc’s bounding rectangle.

CLX—57

C LX:DR A W -A RC Function

width height
Two integers th a t specify th e dimensions, in pixels, of th e arc’s bounding
rectangle.

anglel angle2
Two CLX: a n g l e values that specify the starting point and extent of the arc,
respectively.

fill-p
A c l x :b o o l e a n value that specifies whether the arc is filled.

degrees-p
A c l x :b o o l e a n value that specifies whether the angles are measured in degrees
or radians.

Return Value
Unspecified.

CLX:DRAW-ARCS Function
D raws m ultiple arcs in the specified draw able.

Format
CLX:DRAW-ARCS d r a w a b le g c o n te x t a rc s &OPTIONAL fill-p d e g r e e s - p
Arguments
drawable
The c l x :d r a w a b l e object in which the arcs are draw n.

gcontext
The c l x :g c o n t e x t object th a t specifies th e graphics characteristics (Buch as
arc-mode) of the arcs.

arcs
A c l x :a r c - s e q value th a t specifies the origins and dim ensions of th e arcs’
bounding rectangles.
fill-p
A c l x :b o o l e a n value th a t specifies w hether th e arcs a re filled.
degrees-p
A c l x :b o o l e a n value th a t specifies w h eth er the angles are m easured in degrees.

CLX—58

C LX:D R A W -A R C S Function

Return Value
Unspecified.

CLX:DRAW-DIRECTION Type Specifier
Specifies w hether a font should be draw n from left to rig h t (like English) or rig h t
to left (like Hebrew). Objects of type c l x :d r a w -d i r e c t i o n are retu rn ed by the
CLX:FONT-DIRECTION function.

Representation
(MEMBER :LEFT-TO-RIGHT :RIGHT-TO-LEFT)

CLX:DRAW-GLYPH Function
D raw s a single character in th e specified draw able. Only foreground pixels are
draw n; the background is not affected.

Format
CLX:DRAW-GLYPH d r a w a b le g c o n t e x t x y e lt &.KEY TRANSLATE :WIDTH :SIZE
Arguments
drawable
The c l x :d r a w a b l e in which the glyphs are draw n.

gcontext
The c l x :g c o n t e x t th a t determ ines the graphics characteristics of the text, such
as font and color.

xy
Two integers th a t specify the X and Y coordinates of the origin of th e text.

elt
An elem ent, such as a character, to draw.
:TRANSLATE
A function th a t tra n sla te s elt into a font index. The default is
#'CLX:TRANSLATE-DEFAULT.

:WIDTH
An i n t e g e r th a t specifies th e w idth of the text in pixels, or n i l .

CLX—59

C LX:DR A W -G LYPH Function

:SIZE
A CLX: index - s iz e value that specifies the size of the font. The default value is
: default, which means an 8-bit font.

Return Values
Two values:
•

T if elt is output b u t n i l if th e : t r a n s l a t e function refuses to output it.

•

An integer th a t indicates the w idth of the draw n text if known.

CLX-.DRAW-GLYPHS Function
D raw s m ultiple glyphs in th e specified draw able. Only foreground pixels are
draw n; th e background is not affected.

Format
CLX:DRAW-GLYPHS d r a w a b le g c o n t e x t x y s e q u e n c e
&KEY :START :END TRANSLATE :WIDTH :SIZE
Arguments
drawable
The c l x :d r a w a b l e in which th e glyphs are draw n.

gcontext
The c l x :g c o n t e x t th a t determ ines the graphics characteristics of the text, such
as font and color.

xy
Two integers th a t specify the X and Y coordinates of the origin of the text.

sequence
A sequence of item s to draw; for example, a string.
:START
The c l x :a r r a y - i n d e x value th a t specifies the sta rtin g position w ithin sequence.
The default value is 0.
:END
The c l x :a r r a y - i n d e x th a t specifies th e la s t position w ithin sequence. If this is
null, the length of sequence is used.
TRANSLATE
A function th a t tra n sla tes sequence into font indexes. The default is
#'CLX:TRANSLATE-DEFAULT.

:WIDTH
An integer or n i l , specifying the w idth of the glyphs in pixels if known.
CLX-60

CLX:DR A W -G LYPH S Function

:SIZE
A clx : index - s iz e value that specifies the size of the font. The default is
: default, meaning an 8-bit font.

Return Values
Two values:
•

An a r r a y - i n d e x value that indicates the n e w start if :END was not reached;
or NIL if it was.

•

An integer th a t indicates the overall w idth of th e glyphs if known; or NIL if
not.

CLX:DRAW-IMAGE-GLYPH Function
D raw s a single ch aracter in the specified draw able. Both foreground and
background pixels a re draw n. An in itial font change from the : t r a n s l a t e
function is allowed.

Format
CLX:DRAW-IMAGE-GLYPH d r a w a b le g c o n te x t x y e lt
&KEY :TRANSLATE :WIDTH :SIZE
Arguments
drawable
The c l x :d r a w a b l e in which the glyph is draw n.

gcontext
T h e C L X :g c o n te x t t h a t d e te r m in e s th e g r a p h ic s c h a r a c te r is tic s o f th e te x t, s u c h

as font and color.

xy
Two integers th a t specify the X and Y coordinates of th e origin of the text.

elt
An elem ent, such as a character, to draw.
:TRANSLATE
A function th a t tra n sla te s elt into a font index. The default is
#'CLX:TRANSLATE-DEFAULT.

WIDTH
An integer that specifies the width of the text in pixels, or NIL.
:SIZE
A CLX: i n d e x - s i z e value th a t specifies the size of th e font. The default value is
:d e f a u l t , which m eans an 8-bit font.

CLX-61

CLX:DR A W -IM AG E-G LYPH Function

Return Values
Two values:
•

t if elt is output b u t n i l if th e

•

An integer th a t indicates the overall w idth of the draw n tex t if known.

: t r a n s l a t e function refuses to output it.

CLX:DRAW-IMAGE-GLYPHS Function
D raws m ultiple glyphs in th e specified draw able. Both foreground and
background pixels are draw n. An initial font change is allowed from the
:t r a n s l a t e function, b u t any subsequent font change or horizontal m otion causes
term ination.

Format
CLX:DRAW-IMAGE-GLYPHS d r a w a b le g c o n t e x t x y s e q u e n c e
&KEY :START :END TRANSLATE :WIDTH :SIZE
Arguments
drawable
The c l x :d r a w a b l e in which th e glyphs a re draw n.

gcontext
The CLX: g c o n t e x t th a t determ ines the graphics characteristics of the text, such
as font and color.

xy
Two integers th a t specify the X and Y coordinates of the origin of the text.

sequence
A sequence of item s to draw ; for example, a string.
:START
The CLX:ARRAY- i n d e x value th a t specifies the sta rtin g position w ithin sequence.
The default value is 0.
:END
The CLX:ARRAY-INDEX value th a t specifies the la s t position w ithin sequence. If
this is null, the length of sequence is used.
TRANSLATE
A function th a t tra n sla te s sequence into font indexes. The default is
#'CLX:TRANSLATE-DEFAULT.

:WIDTH
An integer or n i l , specifying the w idth of the glyphs in pixels if known.

CLX—62

C LX:D R A W -IM A G E-G LYPH S Function

:SIZE
A clx : index - s iz e value that specifies the size of the font. The default is
: default, meaning an 8-bit font.

Return Values
Two values:
•

An a r r a y - i n d e x value that indicates the n e w start if :END was not reached;
or n i l if it was.

•

An integer th a t indicates th e overall w idth of th e glyphs if known; or n i l if
not.

CLX:DRAW-LINE Function
D raws a stra ig h t line betw een two specified points.

Format
CLX:DRAW-LINE d r a w a b le g c o n t e x t x l y l x 2 y 2 &OPTIONAL r e la tiv e - p
Arguments
drawable
The CLX:d r a w a b l e object in which th e line is draw n.

gcontext
The CLX: g c o n t e x t object th a t specifies th e graphic characteristics of th e fine,
such as fine style, fine w idth, and so on.

xl yl
Two integers th a t specify th e X and Y coordinates of th e first endpoint of th e line.

x2y2
Two integers th a t specify the X and Y coordinates of th e second endpoint of the
fine.

relative-p
A c l x :b o o l e a n value th a t specifies w h ether th e coordinates of the second
endpoint are relative to th e first endpoint.

Return Value
Unspecified.

CLX-63

CLX: DRAW-LINES Function

CLX:DRAW-LINES Function
D raws stra ig h t lines connecting each point in a sequence or c l x :POINT-s e q value.

Format
CLX:DRAW-LINES d r a w a b le g c o n te x t p o in ts
&KEY :RELATIVE-P :FILL-P :SHAPE
Arguments
drawable
The c l x :d r a w a b l e object in which the lines are draw n.

gcontext
The c l x :g c o n t e x t object th a t specifies th e graphic characteristics of the lines,
such as fine style, line w idth, and so on.

points
A sequence or c l x .-p o i n t - s e q value th a t contains the X and Y coordinates of the
endpoints of the lines.
:RELATIVE-P
A c l x :b o o l e a n value th a t specifies w hether the coordinates of the second
and following points are relative to the point th a t precedes them in the point
sequence.
:FILL-P
A CLX:b o o l e a n value th a t specifies w h eth er the region enclosed by the lines is
filled.
:SHAPE
A keyword used by th e server to optim ize fill operations. Possible values are
c o m p l e x , : n o n - c o n v e x , and : c o n v e x . The default value is : c o m p l e x .

Return Value
Unspecified.

CLX:DRAW-POINT Function
D raw s a single point a t the specified coordinates. The coordinates are relative to
the origin of the draw able.

CLX-64

C LX:D R A W -P01N T Function

Format
CLX:DRAW-POINT d r a w a b le g c o n te x t x y
Arguments
drawable
The CLX: d r a w a b l e object in which the point is draw n.

gcontext
The CLX: g c o n t e x t object th a t specifies the graphics characteristics of the point,
such as color.

xy
Two integers th a t specify the X and Y coordinates of the point.

Return Value
Unspecified.

CLX:DRAW-POINTS Function
D raw s m ultiple points in th e specified draw able. The X and Y coordinates of
each point m ay be given in a single c l x :POINT-s e q value. The coordinates of
th e first point in the sequence are relative to th e origin of the draw able, but the
coordinates of the second and following points m ay be relative to th e point th a t
precedes them in the sequence.

Format
CLX:DRAW-POINTS d r a w a b le g c o n te x t p o in ts &OPTIONAL r e la tiv e - p
Arguments
drawable
The c l x :d r a w a b l e object in which th e points are draw n.

gcontext
The CLX: GCONTEXT object th a t specifies the graphics characteristics of the points
(such as color).

points
A c l x :POINT-s e q value th a t specifies the coordinates of th e points.

relative-p
A c l x :b o o l e a n value th a t specifies w hether the coordinates of each point are
relative to th e previous point.

CLX-65

C LX :D R A W -PO IN TS Function

Return Value
Unspecified.

CLXrDRAW-RECTANGLE Function
D raw s a sofid or outlined rectangle.

Format
CLX:DRAW-RECTANGLE drawable gcontext x y width height &OPTIONAL fill-p
Arguments
drawable
The CLX : d r a w a b l e object in which th e rectangle is draw n.

gcontext
The CLX: g c o n t e x t object th a t specifies th e graphics characteristics of the
rectangle, such as color, line width, and so on.

xy
Two integers th a t specify the X and Y coordinates of the top-left corner of the
rectangle.

width height
Two integers th a t specify th e dim ensions of the rectangle, m easured in pixels.

flll-p
A clx : boolean v a lu e t h a t s p e c ifie s w h e th e r t h e r e c ta n g le is fille d .

Return Value
Unspecified.

CLX:DRAW-RECTANGLES Function
D raws m ultiple solid or outlined rectangles. The origin and dim ensions of each
rectangle m ay be stored in a c l x :RECT-s e q value.

Format
CLX:DRAW-RECTANGLES drawable gcontext rectangles &OPTIONAL fill-p

CLX-66

C LX:D R A W -R EC TA N G LES Function

Arguments
drawable
The c l x :d r a w a b l e object in which the rectangles are draw n.

gcontext
The CLX:g c o n t e x t object th a t specifies the graphic characteristics (line width,
color, and so on) of th e rectangles.

rectangles
A sequence or c l x :RECT-s e q value that specifies the origins and sizes of the
rectangles.

flll-p
A c l x :b o o l e a n value th a t specifies w hether th e rectangles are filled.

Return Value
Unspecified.

CLX:DRAW-SEGMENTS Function
D raw s m ultiple line segm ents connecting each p air of points in a sequence or
C L X :SEG-SEQ value.

Format
CLX:DRAW-SEGMENTS d r a w a b le g c o n te x t s e g m e n ts
Arguments
drawable
T he c l x :d r a w a b l e object in which the line segm ents are draw n.

gcontext
T he c l x :g c o n t e x t object th a t specifies the graphics characteristics of th e line
segm ents, such as color, w idth, and so on.

segments
A sequence or CLX: s e g - s e q value th a t contains the X and Y coordinates of the
endpoints of the line segm ents.

Return Value
Unspecified.

CLX-67

CLX:EVENT-CASE Macro

CLX:EVENT-CASE Macro
Executes the m atching clause for each event in th e queue u ntil a clause retu rn s
non-NiL. The value retu rn ed by th a t clause is then retu rn ed by c l x :e v e n t -c a s e .
H a n gs until non-NiL is gen erated for som e event, or for the specified :TIMEOUT.
R eturns n i l if : t i m e o u t is reached.

Format
CLX:EVENT-CASE d is p la y &KEY TIMEOUT :PEEK-P :DISCARD-P
:FORCE-OUTPUT-P
&BODY c la u s e s
Arguments
display
A CLX:DISPLAY object.
TIMEOUT
The num ber of seconds to w ait before the m acro retu rn s.
:PEEK-P
A CLX:b o o l e a n value. If true, the event for which the clauses return non-NiL is
left on the queue.

:DISCARD-P
A c l x -.b o o l e a n value. If true, events for which th e clauses re tu rn n i l are
removed from the queue; otherwise they are left in place.
:FORCE-OUTPUT-P
A c l x :b o o l e a n value. If true, the default, the macro invokes
CLX:d i s p l a y -f o r c e -o u t p u t before it s ta rts reading events.

clauses
One or m ore LISP form s th a t include the form s to be executed w hen particular
events occur. The clauses have the following syntax;
(event-key | ({event-key}*) ({arg}* \ {(arg var)}*) forms)
event-key

A CLX:EVENT-KEY value. The nam es may be typed as variables or as
keywords. The names are not evaluated, and it is an error for the same
event-key to appear in m ore than one clause.

a rg

An argum ent that is appropriate to the event-key, as listed in
S e c tio n 12.5. As w ith k e y w o rd a r g u m e n ts i n a la m b d a l i s t (keyword

vat) formB a r e a llo w ed .

var

A variable you want to be bound to the event-key argument.

fo rm s

O n e or m o re L ISP form s to b e ex ecu ted for th e event.

The last clause m ay contain T or o t h e r w i s e in place of a c l x :e v e n t -k e y . If you
do not provide such a clause, the im plicit clause (otherwise nil) is used.

CLX-68

CLX:EVENT-CASE Macro

Return Value
The first non-NiL value returned by one of the clauses, or n i l if : t i m e o u t is
reached.

CLX:EVENT-KEYType Specifier
CLX:e v e n t -k e y is a data abstraction that specifies the keywords that are usable
with the CLX:e v e n t -c a s e macro and CLX:p r o c e s s -e v e n t function.

Representation
(MEMBER :KEY-PRESS :KEY-RELEASE :BUTTON-PRESS :BUTTON-RELEASE
:MOTION-NOTIFY :ENTER-NOTIFY 1EAVE-NOTIFY :FOCUS-IN :FOCUS-OUT
:KEYMAP-NOTIFY EXPOSURE :GRAPHICS-EXPOSURE :NO-EXPOSURE
:VISIBILITY-NOTIFY :CREATE-NOTIFY :DESTROY-NOTIFY :UNMAP-NOTIFY
:MAP-NOTIFY :MAP-REQUEST :REPARENT-NOTIFY :CONFIGURE-NOTIFY
:GRAVITY-NOTIFY :RESIZE-REQUEST :CONFIGURE-REQUEST
:CIRCULATE-NOTIFY :CIRCULATE-REQUEST :PROPERTY-NOTIFY
SELECTION-CLEAR SELECTION-REQUEST SELECTION-NOTIFY
iCOLORMAP-NOTIFY :CLIENT-MESSAGE)

CLX:EVENT-LISTEN Function
R eturns th e num ber of events queued for th e specified display, if any, else n i l .
H angs w aiting for events, forever if timeout is NIL, else for the specified num ber
of seconds.

Format
CLX:EVENT-LISTEN d is p la y & OPTIONAL tim e o u t
Arguments
display
A CLX:DISPLAY object.

timeout
The num ber of seconds to w ait for events, or NIL if no lim it. The default value is
0 .

Return Value
T he num ber of events queued locally, or NIL if there are none.

CLX—69

CLX:EVENT-MASK Type Specifier

CLX:EVENT-MASK Type Specifier
Objects of type c l x :e v e n t -m a s k a re retu rn ed by the CLX:m a k e -e v e n t -m a s k
function and can be passed to the CLX: s e n d -e v e n t function.

Representation
(OR CLX:MASK32 (LIST CLX:EVENT-MASK-CLASS))

CLX:EVENT-MASK-CLASS Type Specifier
Objects of type CLX:e v e n t -m a s k -c l a s s are retu rn ed by the c l X:MAKE- e v e n t -k e y s
function and m ay be passed to the c l x :m a k e -e v e n t -m a s k function.

Representation
(MEMBER :KEY-PRESS :KEY-RELEASE :OWNER-GRAB-BUTTON :BUTTON-PRESS
:BUTTON-RELEASE :ENTER-WINDOW :LEAVE-WINDOW :POINTER-MOTION
POINTER-HINT :BUTTON-1-MOTION :BUTTON-2-MOTION :BUTTON-3-MOTION
:BUTTON-4-MOTION :BUTTON-5-MOTION :BUTTON-MOTION EXPOSURE
:VISiBILITY-CHANGE :STRUCTURE-NOTIFY :RESIZE-REDIRECT
:SUBSTRUCTURE-NOTIFY :SUBSTRUCTURE-REDIRECT :FOCUS-CHANGE
PROPERTY-CHANGE :COLORMAP-CHANGE :KEYMAP-STATE)

CLX:FIND-ATOM Function
Given th e nam e of a property, re tu rn s the atom num ber.

Format
CLX:FIND-ATOM d is p la y n a m e
Arguments
display
A CLX:DISPLAY object.

name
A c l x :x a t o m value.

Return Value
A f i x n u m th a t indicates th e atom-id.

CLX—70

CLX:FONT Structure

CLX:FONT Structure
Holds th e representation of a font.
Constructor Function
CLX:CREATE-FONT

Accessor Functions
None of the following functions can be used w ith s e t f :
N am e

T y p e D e fin itio n

CLX:FONT-ALL-CHARS-EXIST-P

CLX:BOOLEAN

CLX:FONT-ASCENT

INTEGER

CLX:FONT-DEFAULT-CHAR

INTEGER

CLX:FONT-DESCENT

INTEGER

CLX:FONT-DIRECTION

CLX:DRAW-DIRECTI ON

CLX:FONT-DISPLAY

CLX:DISPLAY

CLX:FONT-EQUAL

CLX:BOOLEAN

CLX:FONT-ID

CLX:RESOURCE-ID

CLX:FONT-MAX-BYTE1

INTEGER

CLX:FONT-MAX-BYTE2

INTEGER

CLX:FONT-MAX-CHAR

INTEGER

CLX:FONT-MIN-BYTE1

INTEGER

CLX:FONT-MIN-BYTE2

INTEGER

CLX:FONT-MIN-CHAR

INTEGER

CLX:FONT-NAME

(OR STRING NULL)

CLX:FONT-P

CLX:BOOLEAN

Dealiocator Function
Instances of type CLX:FONT are subject to garbage collection.

CLX:FONTABLE Type Specifier
A d a ta abstraction rep resen tin g objects th a t can be coerced into a font
specification.

Representation
(OR CLX:STRINGABLE CLX:FONT)

CLX—71

C LX :FO N T-A LL-C H A R S-EX IST-P Function

CLX:FONT-ALL-CHARS-EXIST-P Function
R eturns tru e if all characters in the specified font have nonzero bounding boxes.

Format
CLX:FONT-ALL-CHARS-EXIST-P fo n t
Argument
font
A CLX :FONT object.

Return Value
A CLX:BOOLEAN value.

CLX:FONT-ASCENT Function
R eturns the distance from the baseline to the top of th e font’s bounding box.

Format
CLX:FONT-ASCENT fo n t
Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX:FONT-DEFAULT-CHAR Function
R eturns the index to the character used w hen an undefined or nonexistent
character is draw n.

CLX—72

C LX:FO NT-D EFA ULT-CH A R Function

Format
CLX:FONT-DEFAULT-CHAR fo n t
Argument
font
A c l x :f o n t object.

Return Value
An integer.

CLX:FONT-DESCENT Function
R eturns the distance from the baseline to the bottom of th e font’s bounding box.

Format
CLXiFONT-DESCENT fo n t
Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX:FONT-DIRECTION Function
Gives a h in t about th e direction in which th e font is painted.

Format
CLX:FONT-DIRECTION fo n t
Argument
font
A c l x :f o n t object.

CLX—73

C LX :FO N T-D IR EC TIO N Function

Return Value
The c l x :d r a w -d i r e c t i o n of th e given font, either : l e f t - t o -r i g h t or
:RIGHT-TO-LEFT.

CLX:FONT-DISPLAY Function
R eturns the display on which th e specified font was opened.

Format
CLX:FONT-DISPLAY fo n t
Argument
font
A CLX:FONT object.

Return Value
A d i s p l a y object.

CLX:FONT-EQUAL Function
R eturns tru e if its two argum ents are th e sam e c l x :f o n t object.

Format
CLX:FONT-EQUAL o b je c t - 1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

Return Value
A CLX:BOOLEAN value.

CLX—74

C LX:FO NT-ID Function

CLX:FONT-ID Function
R eturns the resource-id of th e specified font.

Format
CLX:FONT-ID fo n t
Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX:FONT-MAX-BYTE1 Function
R eturns th e la s t row of the font.

Format
CLX:FONT-MAX-BYTE1 fo n t
Argument
font
A CLX : FONT object.

Return Value
A n integer.

CLX:FONT-MAX-BYTE2 Function
For 16-bit fonts, re tu rn s th e la st byte of th e font. For 8-bit fonts, th is is the same
as CLX:FONT-MAX-CHAR.

CLX-75

C L X :F 0N T -M A X -B Y T E 2 Function

Format
CLX:FONT-MAX-BYTE2 fo n t
Argument
font
A c l x :f o n t object.

Return Value
An integer.

CLX:FONT-MAX-CHAR Function
R eturns th e index to the la s t character of th e font.

Format
CLX:FONT-MAX-CHAR fo n t
Argument
font
A c l x :f o n t object.

Return Value
A n integer.

CLX:FONT-MIN-BYTE1 Function
R eturns th e first row of the font.

Format
CLX:FONT-MIN-BYTE1 fo n t
Argument
font
A CLX:FONT object.

CLX—76

C LX:FO NT-M IN-BYTE1 Function

Return Value
An integer.

CLX:F0NT-MIN-BYTE2 Function
For 16-bit fonts, re tu rn s th e first byte in the font. For 8-bit fonts, this is the sam e
as CLX:FONT-MIN-CHAR.

Format
CLX:FONT-MIN-BYTE2 fo n t
Argument
font
A CLX:f o n t object.

Return Value
An integer.

CLX:FONT-MIN-CHAR Function
R eturns th e index of th e first character in the font.

Format
CLX:FONT-MIN-CHAR fo n t
Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX—77

C LX :FO N T-N A M E Function

CLX:FONT-NAME Function
R eturns a string th a t nam es the font. R eturns n i l for a pseudo font retu rn ed by
CLX:GCONTEXT-FONT.

Format
CLX:FONT-NAME fo n t
Argument
font
A CLX:FONT object.

Return Value
A STRING or NIL.

CLX:FONT-P Function
R eturns tru e if its argum ent is a CLX:FONT object.

Format
CLX:FONT-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX—78

CLX:FO NT-PATH Function

CLX:FONT-PATH Function
R eturns th e search p a th used by th e server to find font files.

Format
CLX:FONT-PATH d is p la y & KEY :RESULT-TYPE
Arguments
display
A CLX: DISPLAY object.

:RESULT-TYPE
The LISP type of the re tu rn value. The default is 'l i s t .

Return Value
A sequence of strings or pathnam es.

CLX:FONT-PROPERTIES Function
R eturns any additional properties defined for the specified font.

Format
CLX.FONT-PROPERTIES fo n t
Argument
font
A CLX:FONT object.

Return Value
A c l x :f o n t -p r o p s value.

CLX—79

C LX :FO N T-P R O P E R TY Function

CLX:FONT-PROPERTY Function
Given a font and th e nam e of a property, re tu rn s the value of th a t property.

Format
CLX:FONT-PROPERTY fo n t n a m e
Arguments
font
A CLX:FONT object.

name
A keyword th a t nam es a property.

Return Value
An integer, or n i l if th e property is not defined.

CLX:FONT-PROPS Type Specifier
A list containing a lte rn a tin g keywords and integers. Objects of type
c l x :f o n t -p r o p s are retu rn ed by the c l x :f o n t -p r o p e r t i e s function.

Representation
LIST

CLX:FORCE-GCONTEXT-CHANGES Function
Forces any batched changes to a GContext to be sent to th e X server.

Format
CLX:FORCE-GCONTEXT-CHANGES g c o n t e x t
Argument
gcontext
A CLX : GCONTEXT object.

CLX-80

C L X :FO R C E -G C O N TEX T-C H A N G ES Function

Return Value
Unspecified.

CLX:FREE-COLORMAP Function
D eletes the association betw een the specified colormap and its resource-id. This
function h a s no effect on the default colormap of th e screen.

Format
CLXrFREE-COLORMAP c o lo r m a p
Argument
colormap
A C L X :COLORMAP object.

Return Value
Unspecified.

CLX:FREE-COLORS Function
Releases all storage allocated by the following functions:
CLX:ALLOC-COLOR-CELLS, and CLX:ALLOC-COLOR-PLANES.

c l x :ä l l o c -c o l o r ,

Format
CLX:FREE-COLORS c o lo r m a p p ix e ls &OPTIONAL p la n e - m a s k
Arguments
colormap
A CLX:COLORMAP object.

pixels
A sequence of c l x :p i x e l values to erase.

plane-mask
A CLX:m a s k value th a t specifies which planes to erase. The default is 0, m eaning
all planes.

CLX-81

C LX :FR E E -C O LO R S Function

Return Value
Unspecified.

CLX:FREE-CURSOR Function
Frees the m em ory allocated for th e specified cursor.

Format
CLX:FREE-CURSOR c u rs o r
Argument
cursor
A c l x :c u r s o r object.

Return Value
Unspecified.

CLX:FREE-GCONTEXT Function
Frees the m em ory allocated to a GContext.

Format
CLX:FREE-GCONTEXT g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
Unspecified.

CLX-82

C LX :FR E E -P IX M A P Function

CLX:FREE-PIXMAP Function
Deallocates the m em ory used by a pixmap.

Format
CLX:FREE-PIXMAP p ix m a p
Argument
pixmap
A c l x : p i x m a p object.

Return Value
Unspecified.

CLX:GCONTEXT Structure
C ontains a se t of graphics characteristics to be used w hen draw ing graphics
objects.
Constructor Function
instance of the c l x :GC0n t e x t structure is returned by the
CLX:CREATE-GCONTEXT function.

Accessor Functions
U nless otherw ise indicated, the following functions can be used w ith SETF:
N am e

T y p e D e fin itio n

CLX: GCONTEXT-ARC-MODE

(OR NULL (MEMBER :CHORD :PIE-SLICE))

CLX: GCONTEXT-BACKGROUND

CLX:PIXEL

CLX: GCONTEXT-CACHE-P

CLX:BOOLEAN

This function is not a valid SETF place.
CLX: GCONTEXT-CAP- STYLE

(OR NULL (MEMBER :NOT-LAST :BUTT :ROUND
PROJECTING) )

CLX: GCONTEXT-CLIP-MASK

(OR NULL (MEMBER :NONE)
CLX PIXMAP CLXPECT-SEQ)

CLX: GCONTEXT-CLIP-ORDERING

(OR NULL (MEMBER :UNSORTED :Y-SORTED
:YX-SORTED :YX-BANDED))

CLX: GCONTEXT-CLIP-X

INTEGER

CLX: GCONTEXT-CLIP-Y

INTEGER

CLX—83

C L X :G C O N TE X T S tructure

N am e

T y p e D e fin itio n

CLX:GCONTEXT-DASH-OFFSET

(OR NULL INTEGER)

CLX: GCONTEXT-DASHES

(OR NULL (OR INTEGER (SEQUENCE INTEGER)))

CLX: GCONTEXT-DISPLAY

CLX:DISPLAY

This function is not a valid SETF place.
CLX: GCONTEXT-EQUAL

CLX:BOOLEAN

This function is not a valid SETF place.
CLX: GCONTEXT—EXPOSURES

(OR NULL (MEMBER :ON :OFF) )

CLX: GCONTEXT-FILL-RULE

(OR NULL (MEMBER :EVEN-ODD :WINDING))

CLX: GCONTEXT-FILL-STYLE

(OR NULL (MEMBER :SOLID :TILED
:OPAQUE-STIPPLED
:STIPPLED))

CLX: GCONTEXT-FONT

CLX:PIXEL

CLX: GCONTEXT-FOREGROUND

CLX:LOGICAL-OP

(OR NULL FONTABLE)

CLX: GCONTEXT-FÜNCTION

INTEGER

CLX:GCONTEXT-ID

This function is not a valid SETF place.
(OR NULL (MEMBER :MITER :ROUND :BEVEL))

CLX: GCONTEXT-JOIN-STYLE

(MEMBER :SOLID :DASH :DOUBLE-DASH)

CLX: GCONTEXT-LINE-STYLE

INTEGER

CLX: GCONTEXT-LINE-WIDTH

CLX:BOOLEAN

CLX: GCONTEXT-P

This function is not a valid SETF place.
INTEGER

CLX: GCONTEXT-PLANE-MASK

(OR NULL CLX:PIXMAP)

CLX: GCONTEXT-STIPPLE

(OR NULL (MEMBER :CLIP-BY-CHILDREN
:INCLUDE-INFERIORS))

CLX: GCONTEXT-SUBWINDOW-MODE

(O R N U L L C L X : R IX M A P )

CLX: GCONTEXT-TILE

INTEGER

CLX: GCONTEXT-TS-X

INTEGER

CLX: GCONTEXT-TS-Y

Deallocator Function
CLX:FREE-GCONTEXT

CLX:GCONTEXT-ARC-MODE Function
R eturns a keyword indicating how th e server connects th e endpoints of an arc
draw n w ith the specified graphics context.

Form at

CLX:GCONTEXT-ARC-MODE g c o n te x t

CLX-84

C L X :G C O N TE X T-A R C -M O D E Function

Argument
gcontext
A CLX: GCONTEXT object.

Return Value
The arc mode of th e given g c o n t e x t , eith e r : CHORD or : p i e - s l i c e .

CLX:GCONTEXT-BACKGROUND Function
R eturns the background color of the specified graphics context.

Format
CLX:GCONTEXT-BACKGROUND g c o n t e x t
Argument
gcontext
A c l x :g c o n t e x t object.

Return Value
A c l x :p i x e l value.

CLX:GCONTEXT-CACHE-P Function
R eturns th e caching mode of the specified graphics context.

Format
CLX:GCONTEXT-CACHE-P g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

CLX-85

C LX :G C O N TE X T-C A C H E -P Function

Return Value
T if the GContext is stored locally by CLX; otherw ise n i l .

CLX:GCONTEXT-CAP-STYLE Function
R eturns a keyword indicating how the server draw s th e endpoints of wide lines in
the specified graphics context.

Format
CLX:GCONTEXT-CAP-STYLE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
:BUTT, :NOT-l a s t , :R0u n d , or :PROJECTiNG; or n i l if the cap style is not defined.

CLX:GCONTEXT-CLIP-MASK Function
R eturns the m ask used to restric t w rite operations to a draw able.

Format
CLX:GCONTEXT-CLIP-MASK g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
A c l x :p i x m a p or c l x :RECT-s e q value containing the clip mask, or :NONE.

CLX-86

C LX:G C O N TE XT-C LIP -X Function

CLX:GCONTEXT-CLIP-X Function
R eturns the X coordinate of the origin for clipping operations in the specified
graphics context.

Format
CLX:GCONTEXT-CLIP-X g c o n te x t
Argument
gcontext
A CLX: GCONTEXT object.

Return Value
An integer.

CLX:GCONTEXT-CLIP-Y Function
R eturns th e Y coordinate of the origin for clipping operations in the specified
graphics context.

Format
CLX:GCONTEXT-CLIP-Y g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
An integer.

CLX—87

C LX :G C O N TE X T-D A S H E S Function

CLX:GCONTEXT-DASHES Function
R eturns th e length, in pixels, of each section of a dashed line.

Format
CLX:GCONTEXT-DASHES g c o n te x t
Argument
gcontext
A CLX: GCONTEXT object.

Return Value
An integer, or a list of integers.

CLX:GCONTEXT-DASH-OFFSET Function
R eturns the position w ithin the dashes list (returned by c l x :GC0n t e x t -d a s h e s ) a t
which the server begins draw ing a dashed line.

Format
CLX:GCONTEXT-DASH-OFFSET g c o n te x t
Argument
gcontext
A C L X :GCONTEXT object.

Return Value
An integer.

CLX-88

C LX:G C O N TE XT-D ISPLA Y Function

CLXiGCONTEXT-DISPLAY Function
R eturns the c l x :DIs p l a y object on which th e specified graphics context was
created.

Format
CLXrGCONTEXT-DISPLAY g c o n te x t
Argument
gcontext
A CLX :GCONTEXT object.

Return Value
A CLX:DISPLAY object.

CLX:GCONTEXT-EQUAL Function
R eturns tru e if its two argum ents are th e sam e c l x :g c o n t e x t object.

Format
CLX:GCONTEXT-EQUAL o b je c t - 1 o b je c t -2
Argum ents

object-1 object-2
Any two LISP objects.

Return Value
A C L X :BOOLEAN value.

CLX—89

C LX :G C O N TE X T-E X P O S U R E S Function

CLX:GCONTEXT-EXPOSURES Function
R eturns a keyword indicating w hether the server inform s the client when a
CLX: c o p y -AREA or c o p y -p l a n e function is called.

Format
CLX:GCONTEXT-EXPOSURES g c o n te x t
Argument
gcontext
A CLX :GCONTEXT object.

Return Value
:ON, :OFF, or NIL if exposures is not defined.

CLX:GCONTEXT-FILL-RULE Function
R eturns th e m ethod used by the server to determ ine w hether a point is “inside” a
shape to be filled.

Format
CLX:G CO NTEXT-FILL-RULE gcontext

Argument
gcontext
A CLX: GCONTEXT object.

Return Value
:EVEN-ODD, :w i n d i n g , or n i l if the fill rule is not defined.

CLX—90

C LX :G C O N TE XT-FILL-STY LE Function

CLX:GCONTEXT-FILL-STYLE Function
R eturns th e m ethod used by the server w hen filling lines, text, and shjapes.

Format
CLX:GCONTEXT-FILL-STYLE g c o n te x t
Argument
gcontext
A CLX: GCONTEXT object.

Return Value
:SOLID, :TILED, :OPAQUE-STIPPLED, or : STIPPLED; or NIL if th e fill style is not

defined.

CLX:GCONTEXT-FONT Function
R eturns th e font stored in the specified GContext if it is known. If it is not known
and :METRics—p is false, n i l is returned. If it is not know n and :METRlcs-P is
true, th en a pseudo font is returned. Full m etric and property inform ation can
be obtained from a pseudo font, but th e pseudo font does not have a nam e or a
resource-id; attem p ts to use a pseudo font w here a resource-id is required resu lt
in an invalid font error.

Format
CLX:GCONTEXT-FONT g c o n t e x t &.OPTIONAL :METRICS-P
Arguments
gcontext
A CLX:GCONTEXT object.

:METRICS-P
A CLX:BOOLEAN value.

Return Value
A c l x :F o n t a b l e value or n i l if the font is not defined.

CLX—91

C LX :G C O N TE X T-FO R E G R O U N D Function

CLXrGCONTEXT-FOREGROUND Function
R eturns the foreground color of the specified graphics context.

Format
CLX:GCONTEXT-FOREGROUND g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
A c l x :p i x e l value.

CLX:GCONTEXT-FUNCTION Function
R eturns the logical function used by the server to combine bits from a graphics
object to be displayed w ith bits from th e existing drawable.

Format
CLX:GCONTEXT-FUNCTION g c o n t e x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
A c l x :l o g Ic a l -o p value.

CLX-92

C LX:G C O N TE X T-ID Function

CLX:GCONTEXT-ID Function
R eturns th e resource-id of th e specified graphics context.

Format
CLX:GCONTEXT-ID g c o n te x t
Argument
gcontext
A CLX : GCONTEXT object.

Return Value
An integer.

CLX:GCONTEXT-JOIN-STYLE Function
R eturns the m ethod used by th e server w hen draw ing connections betw een fine
segm ents in th e specified graphics context.

Format
CLX:GCONTEXT-JOIN-STYLE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
:m i t e r , :r o u n d , or : b e v e l ; or n i l if th e join style is not defined.

CLX-93

CLX:GCONTEXT-KEY Type Specifier

CLX:GCONTEXT-KEY Type Specifier
Objects of type c l x :g c o n t e x t -k e y m ay be passed to the
function. The values correspond to those
components of th e c l x :g c o n t e x t stru ctu re th a t are valid s e t f places.
c l x :c o p y - g c o n t e x t -c o m p o n e n t s

Representation
(MEMBER FUNCTION :PLANE-MASK :FOREGROUND :BACKGROUND :LINE-WIDTH
1INE-STYLE :CAP-STYLE JOIN-STYLE :FILL-STYLE :FILL-RULE :ARC-MODE
:TILE :STIPPLE :TS-X :TS-Y :FONT :SUBWINDOW-MODE EXPOSURES :CLIP-X
:CLIP-Y :CLIP-MASK :DASH-OFFSET :DASH ES)

CLX:GCONTEXT-LINE-STYLE Function
R eturns th e m ethod used by the server to draw lines in the specified graphics
context.

Format
CLX:GCONTEXT-LINE-STYLE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
:s o l i d , :d a s h , or : d o u b l e -d a s h ; or n i l if the line style is not defined.

CLX:GCONTEXT-LINE-WIDTH Function
R eturns th e w idth, in pixels, of lines draw n in the specified graphics context.

Format
CLX:GCONTEXT-LINE-WIDTH g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

CLX—94

CLX:GCONTEXT-LIN E-WIDTH Function

Return Value
A n integer.

CLX:GCONTEXT-P Function
R eturns T if its argum ent is a CLX:GCONTEXT object.

Format
CLX:GCONTEXT-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:GCONTEXT-PLANE-MASK Function
Specifies the planes to which graphics operations are lim ited w hen draw ing w ith
th e specified graphics context.

Format
CLX:GCONTEXT-PLANE-MASK g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
An integer containing a b it m ask.

CLX—95

C LX :G C O N TE XT-STIP PLE Function

CLX:GCONTEXT-STIPPLE Function
R eturns the c l x i PIXMAP used for stipple operations in th e specified graphics
context.

Format
CLX:GCONTEXT-STIPPLE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
A CLX:PiXMAP value.

CLX:GCONTEXT-SUBWINDOW-MODE Function
R eturns a keyword indicating w hether child windows clip th eir ancestors.

Format
CLX:GCONTEXT-SUBWINDOW-MODE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
:c l i p -b y - c h i l d r e n or : i n c l u d e - i n f e r i o r s , or n i l if the subwindow mode is not

defined.

CLX—96

C LX:G C O N TE XT-TILE Function

CLX.GCONTEXT-TILE Function
R eturns th e c l x :p i x m a p used for tile operations in the specified graphics context.

Format
CLX:GCONTEXT-TILE g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
A c l x :P i x m a p value.

CLX:GCONTEXT-TS-X Function
R eturns the X coordinate of the origin for tile and stipple operations in the
specified graphics context.

Format
CLX:GCONTEXT-TS-X g c o n te x t
Argument
gcontext
A CLX:GCONTEXT object.

Return Value
An integer.

CLX—97

C LX :G C O N TE XT-TS -Y Function

CLX:GCONTEXT-TS-Y Function
R eturns the Y coordinate of th e origin for tile and stipple operations in the
specified graphics context.

Format
CLX:GCONTEXT-TS-Y g c o n te x t
Argument
gcontext
A CLX: GCONTEXT object.

Return Value
An integer.

CLX:GET-IMAGE Function
Gets an im age from the server.

Format
CLX:GET-IMAGE d r a w a b le &KEY :X :Y :WIDTH :HEIGHT :PLANE-MASK
:FORMAT :RESULT-TYPE

Arguments
drawable
A CLX:DRAWABLE object.
:X :Y
Two integers th a t specify th e X and Y coordinates of th e origin of th e image.
These argum ents are required.
:WIDTH :HEIGHT
Two integers th a t specify th e dim ensions of the image. These argum ents are
required.
:PLANE-MASK
An integer th a t specifies which planes to get. The default value is # x F F F F F F F F ,
m eaning all planes.
rFORMAT
The type of image. The default is :Z-p i x m a p .
CLX—98

C LX:G ET-IM A G E Function

.RESULT-TYPE
The type of the re tu rn value. The default is th e value of the : f o r m a t argum ent.

Return Value
R eturns a CLX: i m a g e -x, c l x :i m a g e -x y , or c l x :Im a g e -z structure, depending on
th e value of the : r e s u l t -t y p e argum ent.

CLX:GET-PROPERTY Function
R eturns th e specified property and inform ation about it from th e property list
of the specified window. The : t r a n s f o r m function is applied to each integer
retrieved. NIL is retu rn ed for :TYPE w hen the protocol re tu rn s None.

Format
CLX:GET-PROPERTY w in d o w p r o p e r t y &KEY :TYPE :START :END :DELETE-P
:RESULT-TYPE :TRANSFORM
Arguments
window
A c l x :w i n d o w object.

property
A c l x : XATOM value.
:TYPE
A CLX:x a t o m value, or NIL.
:START
An integer. The default value is 0.
:END
An integer.
:DELETE-P
A CLX:BOOLEAN value.
:RESULT-TYPE
The LISP type of the re tu rn value. The default value is 'l i s t .
TRANSFORM
A function that takes an integer argument, or n i l .

CLX—99

C LX :G E T-P R O P E R TY Function

Return Values
A sequence of four values:
d a ta

the property itself

type

the type of the property

form at

the size o f the data format

bytes-after

the num ber o f bytes rem aining in the property if a partial read operation
w as performed

In each case, NIL is retu rn ed when the protocol re tu rn s N one.

CLX:GET-RAW-1 MAGE Function
B rings an im age into LISP memory.
If : d a t a is given, it is modified in place (and returned); otherwise, a new sequence
is created and retu rn ed , w ith a size computed from the other argum ents and
th e retu rn ed depth. The sequence is filled w ith 8-bit quantities, in transm ission
form at.

Format
CLX:GET-RAW-IMAGE d r a w a b le &KEY :DATA :START :X :Y :WIDTH
:HEIGHT :PLANE-MASK :FORMAT
:RESULT-TYPE
Arguments
drawable
The c l x :d r a w a b l e th a t contains th e im age to be stored in memory.
:DATA
A sequence to store the image in, or n i l .
:START
A CLX:a r r a y - i n d e x value th a t specifies the s ta rtin g position in :DATA. The default
value is 0.
:X :Y
Two integers th a t specify the X and Y coordinates of th e origin of the image.
:WIDTH :HEIGHT
Two integers th a t specify the dim ensions of th e image.
:PLANE-MASK
A c l x :p i x e l value th a t specifies the planes to be retrieved. The default value is
#XFFFFFFFF.

:FORMAT
The type of im age form at, eith er :XY-p i x m a p or :Z-p i x m a p .
CLX-100

C LX:G ET-RA W -IM A G E Function

:RESULT-TYPE
The LISP type of th e first re tu rn value. The default is ' (v e c t o r (u n s i g n e d -b y t e
8)).

Return Values
Two values:
•

A sequence of bytes containing the im age data.

•

An integer th a t indicates the depth of the image.

CLX:GET-WM-CLASS Function
R eturns the class of a window.

Format
CLX:GET-WM-CLASS w in d o w
Argument
window
A c l x :w i n d o w object.

Return Values
Two values:
•

A string containing the w i n d o w ’s name, or n i l if none has been defined.

• T h e w in d o w ’
s cla ss, e ith e r " i n p u t " o r " in p u t - o u t p u t "; o r n i l i f th e c la ss w a s
copied from the w i n d o w ’s parent w h e n the wind o w w as created.

CLX:GLOBAL-POINTER-POSITION Function
R eturns the position of th e pointer cursor and th e root window on th e specified
display.

Format
CLX:GLOBAL-POINTER-POSITION d is p la y

CLX—101

C L X :G L O B A L-P O IN TE R -P O S ITIO N Function

Argument
display
A CLX:DISPLAY object.

Return Values
Three values:
•

The X coordinate of th e pointer cursor.

•

The Y coordinate of th e pointer cursor.

•

The root window.

CLX:GRAB-BUTTON Function
Passively grabs the specified b utton on th e pointer device. The grab is activated
w hen the button is pressed.

Format
CLX:GRAB-BUTTON w in d o w b u tto n e v e n t - m a s k
&KEY :MODIFIERS OWNER-P :SYNC-POINTER-P
:SYNC-KEYBOARD-P :CONFINE-TO :CURSOR
Arguments
window
A CLX:WINDOW object.

button
An integer or :a n y .

event-mask
A CLX:POINTER-EVENT-MASK value.
MODIFIERS
A CLX:m o d i f i e r -m a s k value. The default value is 0.
:OWNER-P
A c l x :b o o l e a n value. If true, all pointer events are reported to th e client. If
false, pointer events are reported only w hen they occur in window and are
selected by event-mask.
:SYNC-POINTER-P
A c l x :b o o l e a n value. If true, pointer events are processed synchronously.
:SYNC-KEYBOARD-P
A c l x :b o o l e a n value. If true, keyboard events are processed synchronously.

CLX—102

CLX:GRAB-BUTTON Function
:CONFINE-TO
The CLX: WINDOW object to which th e cursor is confined for th e duration of the
grab, or null if th e cursor can move to any window.
:CURSOR
The CLX: c u r s o r to be displayed for th e d uration of th e grab, or null if the cursor
does not change.

Return Value
Unspecified.

CLX:GRAB-KEY Function
Passively grabs the specified key on the keyboard. The grab is activated when
the key is pressed.

Format
CLX:GRAB-KEY w in d o w k e y &KEY :MODIFIERS :OWNER-P :SYNC-POINTER-P
:SYNC-KEYBOARD-P
Arguments
window
A c l x :w i n d o w object.

key
An integer or : a n y .
M O D IFIE R S

A c l x :m o d i f i e r -m a .s k .The default value is 0.
:OWNER-P
A c l x :b o o l e a n value. If true, all keyboard events a re reported to the client. If
false, only events occurring in window and selected by key a re reported.
:SYNC-POINTER-P
A c l x :b o o l e a n value. If true, pointer events are processed synchronously.
:SYNC-KEYBOARD-P
A c l x :b o o l e a n value. If true, keyboard events are processed synchronously.

Return Value
Unspecified.

CLX—103

CLX.GRAB-KEYBOARD Function

CLX:GRAB-KEYBOARD Function
Actively grabs the keyboard.

Format
CLX:GRAB-KEYBOARD w in d o w &KEY :OWNER-P :SYNC-POINTER-P
:SYNC-KEYBOARD-P :TIME
Arguments
window
A c l x :w i n d o w object.
:OWNER-P
A c l x :b o o l e a n value. If true, all pointer events are reported to th e client. If
false, keyboard events are reported only when they occur in window.
:SYNC-POINTER-P
A c l x :b o o l e a n value. If true, pointer events are processed synchronously.
:SYNC-KEYBOARD-P
A c l x :b o o l e a n value. If true, keyboard events are processed synchronously.
:TIME
The c l x :t i m e s t a m p w hen the grab takes effect.

Return Value
A CLX:GRAB-STATUS value.

CLX:GRAB-POINTER Function
Actively grabs the pointing device.

Format
CLX:GRAB-POINTER w in d o w e v e n t - m a s k
&KEY :OWNER-P :SYNC-POINTER-P :SYNC-KEYBOARD-P
:CONFINE-TO :CURSOR :TIME
Arguments
window
A c l x :w i n d o w object.

CLX-104

CLX:GRAB-POINTER Function
event-mask
A c l x :p o i n t e r -e v e n t -m a s k value th a t specifies which pointer events are reported
during the grab.
:OWNER-P
A c l x :b o o l e a n value. If true, all pointer events are reported to th e client. W hen
false, pointer events are reported only w hen they occur in window.
:SYNC-POINTER-P
A CLX:BOOLEAN value. If true, pointer events are processed synchronously.
:SYNC-KEYBOARD-P
A CLX:b o o l e a n value. If true, keyboard events are processed synchronously.
:CONFINE-TO
The CLX:w i n d o w object to which the pointer cursor is confined for th e duration of
the grab, or null if th e cursor can move to any window.
:CURSOR
The c l x :c u r s o r displayed for the duration of the grab, or null if the cursor does
not change.
:TIME
The CLX:t i m e s t a m p w hen the grab takes effect.

Return Value
A c l x :g r a b - s t a t u s value.

CLX:GRAB-SERVER Function
Allows a client program to take exclusive possession of the server for a specified
display. No requests are processed while the server is grabbed, not even requests
to close connections. You should not grab the server any m ore th an is absolutely
necessary.
A server grab is autom atically released w hen th e client closes its connection to
th e server.

Format
CLX:GRAB-SERVER d is p la y
Argument
display
A CLX:DISPLAY object.

CLX—105

C LX :G R A B -SE R V ER Function

Return Value
Unspecified.

CLX:GRAB-STATUS Type Specifier
Objects of type CLX: g r a b -s t a t u s are retu rn ed by the c l x :g r a b -k e y b o a r d and
CLX:GRAB-POINTER functions.

Representation
(MEMBER SU CCESS :ALREADY-GRABBED :FROZEN :INVALID-TIME :NOT-VIEWABLE)

CLX:ICON-SIZES Function
Uses the c l x :s i z e -h i n t s stru ctu re to find the recom mended size for the icon of a
window.

Format
CLX:ICON-SIZES w in d o w
Argument
window
A c l x :w i n d o w object.

Return Value
A c l x :w m - s i z e -h i n t s object.

CLX:IMAGE Structure
Im ages structures allow you to access screen d ata from LISP, and tran sfer data
betw een the client and the server.

C onstructor Function
CLX:CREATE-IMAGE

CLX—106

CLX:!MAGE Structure
A ccessor Functions
Unless otherw ise indicated, the following functions can be used w ith s e t f :
N am e

T y p e D e fin itio n

CLX:IMAGE-BIT-LSB-FIRST-P

C LX:BOOLEAN

CLX:IMAGE-BITS-PER-PIXEL

INTEGER

CLX:IMAGE-BLUE-MA.SK

CLX:MASK16

CLX:IMAGE-BYTE-LSB-FIRST-P

CLX:BOOLEAN

CLX:IMAGE-BYTES-PER-LINE

CLX:CARD16

CLX:IMAGE-DEPTH

CARD 8

The default value is 1. This function is not a valid
SETF place.
CLX:IMAGE-FORMAT

(MEMBER :BITMAP :XY-PIXMAP :Z-PIXMAP)

CLX:IMAGE-GREEN-MASK

CLX:MASK16

CLX:IMAGE-HEIGHT

CARD16

CLX:IMAGE-RED-MASK

CLX:MASK16

CLX:IMAGE-SCANLINE-PAD

(MEMBER 8 16 32)

CLX:IMAGE-WIDTH

CARD16

Predicate
CLX:IMAGE-P

Dealiocator Function
Objects of type c l x :i m a g e are subject to garbage collection.

CLX:IMAGE-BIT-LSB-FIRST-P Function
R e tu rn s tr u e i f th e d a ta for th e sp e cifie d im a g e is sto r e d w ith th e le a s t sig n ifica n t

b it first.

Format
CLX:IMAGE-BIT-LSB-FIRST-P im a g e
Argument
image
A CLX: IMAGE object.

CLX—107

C LX :IM A G E -B IT-LSB -FIR S T-P Function

Return Value
A CLX:BOOLEAN value.

CLX:IMAGE-BITS-PER-PIXEL Function
R eturns th e num ber of bits used to hold each pixel in the specified image.

Format
CLX:IMAGE-BITS-PER-PIXEL im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A m em ber of (l 4 8 16 2 4 3 2 ) .

CLX:IMAGE-BLUE-MASK Function
R eturns the blue value of a pixel in an im age whose form at is :Z-PIXMAP.

Format
CLX:IMAGE-BLUE-MASK im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A c l x :p i x e l value.

CLX—108

C LX :IM A G E -B Y TE -LS B -FIR S T-P Function

CLX:IMAGE-BYTE-LSB-FIRST-P Function
R eturns tru e if th e d a ta for the specified im age is stored w ith th e least significant
byte first.

Format
CLX:IMAGE-BYTE-LSB-FIRST-P im a g e
Argument
image
A CLX:IMAGE object.

Return Value
A c l x :b o o l e a n value.

CLX:IMAGE-BYTES-PER-LINE Function
R eturns the num ber of bytes in each scanline of the specified image.

Format
CLX:IMAGE-BYTES-PER-LINE im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A CLX: c a r d i 6 value.

CLX—109

C LX :IM A G E -D E P TH Function

CLX:IMAGE-DEPTH Function
R eturns the depth of the specified image.

Format
CLX:IMAGE-DEPTH im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A c l x :c a r d 8 value.

CLX:IMAGE-DEPTH Type Specifier
An abstract type used for the depth of an image, pixm ap-form at, or visual-info.

Representation
(INTEGER 0 32)

CLX:IMAGE-FORMAT Function
R eturns the form at in which im age d a ta is stored.

Format
CLX:IMAGE-FORMAT im a g e
Argument
Image
A CLX: IMAGE object.

CLX—110

C LX :IM A G E -FO R M A T Function

Return Value
:BITMAP, :XY-PIXMAP, Or :Z-PIXMAP.

CLX:IMAGE-GREEN-MASK Function
R eturns th e green value of a pixel in a n im age whose form at is : z -p i x m a p .

Format
CLX:IMAGE-GREEN-MASK im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A c l x :p i x e l value.

CLX:IMAGE-HEIGHT Function
R eturns th e heig h t of th e specified image.

Format
CLX:IMAGE-HEIGHT im a g e
Argument
Image
A CLX: IMAGE object.

Return Value
A clx:card 1 6 value.

CLX—111

C LX :IM A G E -P Function

CLX:IMAGE-P Function
R eturns tru e if its arg u m en t is of type c l x :i m a g e .

Format
CLX:IMAGE-P o b je c t
Argument
object
Any LISP object.

Return Value
A c l x :b o o l e a n value.

CLX:IMAGE-RED-MASK Function
R eturns the red value of a pixel in an im age whose form at is :Z-p i x m a p .

Format
CLX:IMAGE-RED-MASK im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A CLX:p i x e l value.

CLX:IMAGE-SCANLINE-PAD Function
R eturns 8, 16, or 32. Each scanline in th e specified im age is padded to a m ultiple
of this value.

CLX-112

C LX:IM A G E -S C A N LIN E-PA D Function

Format
CLX:IMAGE-SCANLINE-PAD im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A m em b er of (8 1 6 32).

CLX:IMAGE-WIDTH Function
R eturns the w idth of th e specified image.

Format
CLX:IMAGE-WIDTH im a g e
Argument
image
A CLX: IMAGE object.

Return Value
A CLX :CARD1 6 value.

CLX:INDEX-SIZE Type Specifier
An a b stract type representing th e size of the buffer used for character
translations, th a t is, 8-bit font or 16-bit font.

Representation
(MEMBER DEFAULT 8 16)

CLX—113

C LX :IN P U T-FO C U S Function

CLX:INPUT-FOCUS Function
R eturns th e window th a t currently has th e in p u t focus, and w here th e focus
rev erts to if th a t window becomes unviewable.

Format
CLX:INPUT-FOCUS d is p la y
Argument
display
A CLX:DISPLAY object.

Return Values
Two values:
•

The CLX:w i n d o w object th a t h as in p u t focus.

•

:NONE, :PARENT, Or :PARENT-ROOT.

CLX:INSTALL-COLORMAP Function
Loads color values from a virtual colormap into th e h ard w are colormap.

Form at

CLXrINSTALL-COLORMAP c o lo r m a p
Argument
colormap
A CLX:COLORMAP object.

Return Value
Unspecified.

CLX—114

C LX:IN STA LLE D -C O LO R M A P S Function

CLX:INSTALLED-COLORMAPS Function
R eturns th e currently installed colormaps.

Format
CLX:INSTALLED-COLORMAPS w in d o w &KEY :RESULT-TYPE
Arguments
window
A c l x :w i n d o w object.
:RESULT-TYPE
The LISP type of the re tu rn value. The default is 'LIST.

Return Value
A sequence of c l x :c o l o r m a p objects.

CLX:INTERN-ATOM Function
Allocates a c l x :x a t o m for use by th e client. If name does not nam e an atom , one
is created.

Format
CLX:INTERN-ATOM display name

Arguments
display
A CLX:DISPLAY object.

name
A c l x :x a t o m value.

Return Value
An integer th a t uniquely identifies the atom.

CLX—115

C L X :K E Y B O A R D -C O N TR O L Function

CLX:KEYBOARD-CONTROL Function
R eturns the current keyboard settings.

Format
CLX:KEYBOARD-CONTROL d is p la y
Argument
display
A CLX:DISPLAY o b je c t.

Return Values
Seven values:
k ey-click -p ercen t

The volume of key clicks between 0 (off) and 100 (loudest).

b ell-p erc en t

The volume of a bell ring between 0 (off) and 100 Goudest).

b e ll-p itc h

The pitch (specified in hertz) of the bell.

b e ll-d u ra tio n

The duration of a bell ring, in milliseconds.

le d -m a sk

Each 1 bit indicates an LED that is on. The least significant bit
corresponds to the first LED.

g lo b a l-a u to -re p e a t

: ON if auto-repeat is enabled for the keyboard as a whole; : OFF if it
is not.

a u to -re p e a ts

A bit vector where each 1 bit indicates that auto-repeat is enabled
for the corresponding key.

CLX:KEYBOARD-MAPPING Function
R eturns th e vabd keycodes for th e specified display. The num ber of keycodes
retu rn ed is the difference betw een :END and : s t a r t . If :DATA is specified, the
results are p u t there.

CLX-116

C LX :K E Y B O A R D -M A P P IN G Function

Format
CLX:KEYBOARD-MAPPING d is p la y &.KEY :FIRST-KEYCODE :START :END
:DATA
Arguments
display
A CLX:DISPLAY object.
:FIRST-KEYCODE

An integer th a t specifies which keycode to s ta rt at. The default is the
: m i n - k ey c o d e component of the display argum ent.
:START

An integer th a t specifies w here (in the re tu rn value) to p u t the first keycode. The
default is :F IR S T - k e y c o d e .
:END

An integer th a t specifies th e la st keycode returned. The default : e n d is one m ore
th a n the : MAX-KEY CODE component of the display argum ent.
:DATA

An a rra y in which to store the retu rn ed keycodes.

Return Value
An a r r a y o f c l x :KEYSYM v a lu e s .

CLX:KEYCODE->CHARACTER Function
R eturns th e c h a r a c t e r th a t corresponds to the specified keycode. The YAX
LISP im plem entation ignores the :KEYSYM-i n d e x and i KEYSYM-i n d e x - f u n c t io n
argum ents.

Format
CLX:KEYCODE->CHARACTER d is p la y k e y c o d e s ta te
&KEY :KEYSYM-INDEX
:KEYSYM-INDEX-FUNCTION
Arguments
display
A CLX: DISPLAY object.

keycode
A CLX:c a r d 8 value.
CLX—117

C L X :K E Y C O D E ->C H A R A C TE R Function

state
A c l x :MASKi 6 value.
:KEYSYM-INDEX

An integer. The default is the resu lt of the :KEYSYM-i n d e x - f u n c t i o n function,
which is called w ith the following param eters:
(charO state caps-lock-p keysyms-per-keycode)

The charO argum ent is the character associated w ith the first : k e y sy m - i n d e x .
The state argum ent is an integer th a t specifies the sta te of th e modifier keys.
The caps-lock-p argum ent is non-NiL w hen the keysym associated w ith the lock
modifier is for caps-lock.
:KEYSYM-INDEX-FUNCTION

The default value is #' default-keysym-index.

Return Values
Three values:
•

The c h a r a c t e r th a t corresponds to keycode', or n i l if th ere is none.

•

If m ore th a n one character is bound to keycode, th e second re tu rn value is a
strin g and th e first re tu rn value is the first character in th a t string.

•

If m ore th a n one character is bound to keycode, th e th ird re tu rn value is the
num ber of characters in the string.

CLX:KEYCODE->KEYSYM Function
Converts a keycode to a keysym.

Format
CLX:KEYCODE->KEYSYM d is p la y k e y c o d e k e y s y m - in d e x
Arguments
display
A CLX:DISPLAY object.

keycode
A c l x : c a r d 8 value.

keysym-index
An integer.

CLX—118

CLX:KEYCODE-> KEYSYM Function

Return Value
A c l x : k eysym value.

CLXiKEYSYM Type Specifier
A keysym is an encoding of the symbol on the cap of a key. A list of keysyms
is associated w ith each keycode. The first keysym in each list is th e one for no
modifiers. Objects of type CLX: k e y sy m are retu rn ed by th e c l x :KEYCODE->k ey sy m
function and c l x : k e y sy m m acro, and can be passed to th e c l x :KEYSYm- > c h a r a c t e r
and CLX:k e y sy m - > k e y c o d e s functions.

Representation
INTEGER

CLX:KEYSYM->CHARACTER Function
Finds the character associated w ith a keysym.

Format
CLX:KEYSYM->CHARACTER d is p la y k e y s y m &OPTIONAL s ta te
Arguments
display
A CLX:DISPLAY object.

keysym
A c l x : k ey sy m value.

state
A clx:M A S K 16 v a lu e t h a t s p e c i f ie s t h e s t a t e o f t h e m o d if ie r k e y s .

Return Values
Three values:
•

The c h a r a c t e r th a t corresponds to keysym; or n i l if th ere is none.

•

If m ore th a n one character is bound to keysym, th e second re tu rn value is a
string and the first re tu rn value is th e first character in th a t string.

•

If m ore th a n one character is bound to keysym, th e th ird re tu rn value is the
num ber of ch aracters in th e string.

CLX-119

C LX :K E Y S Y M ->K E Y C O D E S Function

CLX:KEYSYM->KEYCODES Function
Finds the keycode m apped from a keysym.

Format
CLX:KEYSYM->KEYCODES d is p la y k e y s y m &OPTIONAL s ta te
Arguments
display
A CLX:DISPLAY object.

keysym
A c l x : k e y sy m value.

state
An integer th a t specifies the sta te of th e modifier keys, or n i l .

Return Value
A c l x : c a r d 8 value.

CLX:KILL-CLIENT Function
Disconnects the client th a t created the specified resource.

Format
CLX:KILL-CUENT d is p la y r e s o u r c e -id
Arguments
display
A CLX:DISPLAY object.

resource-id
A c l x : r e s o u r c e - i d value.

Return Value
Unspecified.

CLX—120

C LX :K ILL-TEM PO R A R Y-C LIE N TS Function

CLX:KILL-TEMPORARY-CLIENTS Function
Destroys all resources created by clients th a t disconnected in :R E TA IN - tem po r ar y
close-down mode.

Format
CLX:KILL-TEMPORARY-CLIENTS d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
Unspecified.

CLX:LIST-EXTENSIONS Function
R eturns a list of extensions to the X server.

Format
CLX:LIST-EXTENSIONS d is p la y *KEY :RESULT-TYPE
Arguments
display
A CLX:DISPLAY object.
:RESULT-TYPE

The LISP type of th e re tu rn value. The default i s ' l i s t .

Return Value
A sequence of strings.

CLX—121

C LX :LIS T-FO N T-N A M ES Function

CLX:LIST-FONT-NAMES Function
Lists all available font nam es th a t m atch a given search string.

Format
CLX:LIST-FONT-NAMES d is p la y p a t t e r n &.KEY :MAX-FONTS :RESULT-TYPE
Arguments
display
A CLX:DISPLAY object.

pattern
A strin g containing the p a tte rn th a t font nam es m u st m atch. Both wildcard
characters are allowed. An a ste risk (* ) m atches any num ber of characters; a
question m ark (? ) m atches a single character.
:MAX-FONTS

The m axim um num ber of font nam es th a t can be returned. The default value is
1024.
:RESULT-TYPE

The LISP type of the first re tu rn value. The default value is 'l i s t .

Return Values
Two values:
• A sequ en ce o f strin gs con tain in g the n am es o f fonts that m atch the p a tte r n

argum ent.
•

An integer indicating th e num ber of m atches found.

CLX:LIST-FONTS Function
R eturns pseudo fonts th a t contain basic font m etrics and properties, but no
per-character m etrics and no resource-ids. These pseudo fonts are converted
(internally) to real fonts dynam ically as needed, by issuing an OpenFont request.
However, th e O penFont m ight fail, in which case the : i n v a l i d -f o n t error is
signaled.

Format
CLX:LIST-FONTS d is p la y p a t t e r n &KEY :MAX-FONTS :RESULT-TYPE

CLX-122

C LX:LIST-FO N TS Function

Arguments
display
A C L X : D I S P L A Y object.

pattern
A string containing the p a tte rn th a t font nam es m u st m atch. Both wildcard
characters are allowed. An asterisk (* ) m atches any num ber of characters; a
question m ark (? ) m atches a single character.
:MAX-FONTS

The m axim um num ber of font nam es th a t m ay be retu rn ed . The default value is
1024.
:RESULT-TYPE

The LISP type of the first re tu rn value. The default value is ' l i s t .

Return Values
Two values:
•

A sequence of pseudo fonts whose nam es m atch the pattern argum ent.

•

An integer indicating th e num ber of m atches found.

CLX:LIST-PROPERTIES Function
R eturns the property list of th e specified window.

Format
CLXrLIST-PROPERTIES w in d o w &KEY :RESULT-TYPE
Arguments
window
A c l x : w indow object.
:RESULT-TYPE

The LISP type of th e re tu rn value. The default is ' l i s t .

Return Value
A sequence of keywords. Atoms are retu rn ed as keywords.

CLX—123

CLX:LOG!CAL OP Type Specifier

CLX:LOGICAL-OP Type Specifier
Logical operations are functions used by the server to combine source and
destination bits w hen displaying graphics objects on a screen. The screen the
client is updating is th e destination (dst). W hatever graphics object the client is
draw ing on the screen is th e source (src). c l x : l o g ic a l - op values a re specified as
keywords in the : f u n c t i o n component of c l x : g c o n t e x t objects.

Representation
A Common LISP BOOLE constant, or one of th e following keywords:
K eyw ord

D escription

GX-CLEAR

GX-AND

S7C AND d st

GX-AND-REVERSE

src AND NOT d st

GX-COPY

src

GX-AND-INVERTED

(NOT src ) AND d st

GX-NOOP

d st

GX-XOR

src XOR d st

GX-OR

src OR d st

GX-NOR

(NOT src ) AND NOT d st

GX-EQUIV

(NOT src) XOR d st

GX-INVERT

NOT d st

GX-OR-REVERSE

src OR NOT d st

GX-COPY-INVERTED

NOT src

GX-OR-INVERTED

(NOT src) O R d st

GX-NAND

(NOT src) OR NOT d st

GX-SET

CLX:LOOKUP-COLOR Function
Finds th e RGB values associated w ith a nam ed color on a p a rticu la r screen.
R eturns both th e screen values (w hat the hardw are supports) and the tru e values
of the nam ed color.

Format
CLX:LOOKUP-COLOR c o lo r m a p n a m e

CLX—124

C LX :LO O K U P -C O LO R Function

Arguments
colormap
A CLX: COLORMAP object.

name
A CLX: STRINGABLE V a lu e .

Return Values
Two c l x : co lo r values: the first is th e screen color; the second is the tru e color.

CLX:MAKE-COLOR Function
M akes an instance of the c l x : colo r structure.

Format
CLX:MAKE-COLOR &KEY :RED :GREEN :BLUE &ALLOW-OTHER-KEYS
Arguments
:RED :GREEN :BLUE
(NUMBER 0 1 )

Return Value
A c l x : colo r object.

CLX:MAKE-COLORMAP Function
Given a display and a colormap resource-id, m akes an instance of the
c l x : colorm ap structure.

Format
CLX:MAKE-COLORMAP d is p la y r e s o u r c e - id
Arguments
display
A CLX:DISPLAY object.

CLX-125

C LX :M Ä K E -C O LO R M A P Function

resource-id
An integer.

Return Value
A CLX:COLORMAP object.

CLX:MAKE-CURSOR Function
Given a display and a cursor resource-id, m akes an instance of th e c l x :c u r s o r
structure.

Format
CLX:MAKE-CURSOR d is p la y r e s o u r c e -id
Arguments
display
A CLX:DISPLAY object.

resource-id
An integer

Return Value
A c l x :c u r s o r object.

CLX:MAKE-DRAWABLE Function
Given a display and a draw able resource-id, m akes an object of type
CLX:DRAWABLE.

Format
CLX:MAKE-DRAWABLE d is p la y r e s o u r c e -id
Arguments
display
A CLX :DISPLAY object.

resource-id
An integer.

CLX—126

C LX:M A K E-D R A W A B LE Function

Return Value
A CLX : DRAWABLE object.

CLX:MAKE-EVENT-KEYS Function
R eturns a list of CLX:e v e n t -m a s k -c l a s s keywords th a t indicate which events are
encoded in th e event m ask. This is defined only for core events.

Format
CLX:MAKE-EVENT-KEYS e v e n t - m a s k
Argument
event-mask
A CLX:MASK32 value.

Return Value
A LIST Of CLX:EVENT-MASK-CLASS values.

CLX:MAKE-EVENT-MASK Function
This is defined only for core events. Useful for constructing CLX:EVENT-MASK,
CLX:POINTER-EVENT-MASK, CLX:DEVICE-EVENT-MASK.

Format
CLX:MAKE-EVENT-MASK &REST k e y s
Arguments
keys
c l x :e v e n t -m a s k - c l a s s keywords th a t indicate which events the m ask contains.

Return Value
A c l x :MASK32 value th a t can be passed to functions th a t require an event m ask.

CLX—127

C LX :M A K E -F O N T Function

CLX:MAKE-FONT Function
Given a display and a font resource-id, m akes an instance of th e CLX:FONT
structure.

Format
CLX:MAKE-FONT d is p la y r e s o u r c e -id
Arguments
display
A CLX:DISPLAY object.

resource-id
An integer.

Return Value
A CLX:FONT object.

CLX:MAKE-GCONTEXT Function
Given a display and a GContext resource-id, m akes an instance of the
c l x :g c o n t e x t structure.

Format
CLX:MAKE-GCONTEXT d is p la y r e s o u r c e -id
Arguments
display
A CLX:DISPLAY object.

resource-id
An integer.

Return Value
A CLX:GCONTEXT object.

CLX—128

C LX :M A K E -P IX M A P Function

CLX:MAKE-PIXMAP Function
Given a display and a pixm ap resource-id, m akes an instance of th e c l x :p i x m a p
structure.

Format
CLX:MAKE-PIXMAP d is p la y r e s o u r c e - id
Arguments
display
A CLX:DISPLAY object.

resource-id
An integer.

Return Value
A CLX:p i x m a p object.

CLX:MAKE-STATE-KEYS Function
R eturns a lis t of c l x :s t a t e -m a s k -c l a s s keywords th a t indicate which events are
encoded in th e event m ask. This is defined only for core events.

Format
CLX:MAKE-STATE-KEYS s t a t e - m a s k
Argument
state-mask
A c l x :m a s k i 6 value.

Return Value
A list of CLX: STATE-MASK-KEY values.

CLX—129

C LX :M A K E -STA TE-M A SK Function

CLX:MAKE-STATE-MASK Function
Useful for constructing c l x :m o d i f i e r -m a s k and c l x :s t a t e -m a s k .

Format
CLX:MAKE-STATE-MASK &REST k e y s
Argument
keys
A list O f CLX: STATE-MASK-KEYS Values.

Return Value
A CLX:MASK16 value th a t can be passed to functions th a t require a state m ask.

CLX:MAKE-VISUAL-INFO Function
Given a resource-id, m akes a n instance of th e CLX:VISü a l - i n f o structure.

Format
CLX:MAKE-VISUAL-INFO r e s o u r c e - id
Argument
resource-id
A CLX:v i s u a l value.

Return Value
A CLX:VISUAL-INFO object.

CLX:MAKE-WINDOW Function
Given a display and a resource-id, m akes a n instance of th e c l x :w i n d o w structure.

Format
CLX:MAKE-WINDOW d is p la y r e s o u r c e - id

CLX—130

C L X :M A K E -W IN D O W Function

Arguments
display
A CLX:DISPLAY object.

resource-ld
An integer.

Return Value
A c l x :w i n d o w object.

CLX:MAKE-WM-HINTS Function
Given a display and a resource-id, m akes a n instance of the c l x :WM-h i n t s
structure.

Format
CLX:MAKE-WM-HINTS d is p la y r e s o u r c e -id
Arguments
display
A CLX:DISPLAY object.

resource-ld
An integer.

Return Value
A CLX :WM-HINTS object.

CLX:MAKE-WM-SIZE-HINTS Function
Given a display and a resource-id, m akes an instance of th e c l x :WM-s i z e -h i n t s
structure.

Format
CLX:MAKE-WM-SIZE-HINTS d is p la y r e s o u r c e -id

CLX—131

C LX :M A K E -W M -S IZ E -H IN T S Function

Arguments
display
A CLX:DISPLAY object.

resource-id
An integer.

Return Value
A CLX :WM-SIZE-HINTS object.

CLX:MAP-SUBWINDOWS Function
Causes all subwindows of the specified window to be m apped or m ade viewable on
the screen. The windows become visible when th e output buffer holding requests
to the server is flushed (see c l x :DISPLa y -f o r c e -o u t p u t ).

Format
CLX:MAP-SUBWINDOWS w in d o w
Argument
window
A CLX:w i n d o w object.

Return Value
Unspecified.

CLX:MAP-WINDOW Function
Causes the specified window to be m apped or m ade viewable on th e screen. The
window becomes visible when the output buffer holding requests to the server is
flushed (see c l x :DISPLAY-f o r c e -o u t p u t ).

Format
CLX:MAP-WINDOW w in d o w

CLX—132

C LX :M A P -W IN D O W Function

Argument
window
A c l x :w i n d o w object.

Return Value
Unspecified.

CLX:MASK16 Type Specifier
An abstract type used to indicate 16-bit m asks. S tate m asks are of type
CLX:MASK16.

Representation
FIXNUM

CLX:MASK32 Type Specifier
An ab stract type used to indicate 32-bit m asks. E vent m asks a re of type
CLX:MASK3 2.■

Representation
INTEGER

C LX:MAX-CH AR-ASCENT Function
R eturns the larg est ascent of any character in the font.

Format
CLX:MAX-CHAR-ASCENT fo n t
Argument
font
A c l x :f o n t object.

CLX—133

C L X :M A X -C H A R -A S C E N T Function

Return Value
An integer.

CLX:MAX-CHAR-ATTRIBUTES Function
R eturns th e larg est num ber of attrib u tes of any character in th e font.

Format
CLX:MAX-CHAR-ATTRIBUTES fo n t
Argument
font
A CLX: FONT object.

Return Value
A n integer.

CLX:MAX-CHAR-DESCENT Function
R eturns th e larg est descent of any character in th e font.

Format
CLX:MAX-CHAR-DESCENT fo n t
Argument
font
A c l x : f o n t object.

Return Value
A n integer.

CLX—134

C LX:M A X-C H A R -LE FT-B E A R IN G Function

CLX:MAX-CHAR-LEFT-BEARING Function
R eturns the larg est left-bearing of any character in the font.

Format
CLX:MAX-CHAR-LEFT-BEARING fo n t
Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX:MAX-CHAR-RIGHT-BEARING Function
R eturns th e larg est right-bearing of any character in th e font.

Format
CLX:MAX-CHAR-RIGHT-BEARING fo n t
Argument
font
A CLX: FONT object.

Return Value
An integer.

CLX:MAX-CHAR-WIDTH Function
R eturns th e larg est w idth of any character in th e font.

Format
CLX:MAX-CHAR-WlDTH fo n t

CLX-135

C LX :M A X -C H A R -W ID TH Function

Argument
font
A CLX:FONT object.

Return Value
An integer.

CLX:MIN-CHAR-ASCENT Function
R eturns th e sm allest ascent of any character in the font.

Format
CLX:MIN-CHAR-ASCENT fo n t
Argument
font
A clx:F0 nt object.

Return Value
A n integer.

CLX.MIN-CHAR-ATTRIBUTES Function
R eturns th e sm allest num ber of a ttrib u tes owned by any character in the font.

Format
CLX:MIN-CHAR-ATTRIBUTES fo n t
Argument
font
A c l x :f o n t object.

CLX-136

C LX :M IN -C H A R -A TTR IB U TE S Function

Return Value
An integer.

CLX:MIN-CHAR-DESCENT Function
R eturns the sm allest descent of any character in the font.

Format
CLX:MIN-CHAR-DESCENT fo n t
Argument
font
A c l x :FONT object.

Return Value
An integer.

CLX:MIN-CHAR-LEFT-BEARING Function
R eturns the sm allest left-bearing of any character in the font.

Format
CLX:MIN-CHAR-LEFT-BEARING fo n t
Argument
font
A c l x : f o n t object.

Return Value
An integer.

CLX—137

C L X :M IN -C H A R -R IG H T-B EA R IN G Function

CLX:MIN-CHAR-RIGHT-BEARING Function
R eturns th e sm allest right-bearing of any character in th e font.

Format
CLX.MIN-CHAR-RIGHT-BEARING fo n t
Argument
font
A c l x : f o n t object.

Return Value
An integer.

CLX:MIN-CHAR-WIDTH Function
R eturns th e sm allest w idth of any character in the font.

Format
CLX:MIN-CHAR-WIDTH fo n t
Argument
font
A c l x :FONT object.

Return Value
An integer.

CLX:MODIFIER-KEY Type Specifier
Objects of type c l x : m o d i f i e r - k e y are retu rn ed by th e c l x : m a k e - s t a t e - k e y s
function and m ay be passed to the c l x :MAKE-s t a t e - m a sk function.

CLX-138

CLX:MODIFIER-KEY Type Specifier

Representation
(MEMBER :SHIFT :LOCK :CONTROL :MOD-1 :MOD-2 :MOD-3 :MOD-4 :MOD-5)

CLX:MODIFIER-MAPPING Function
R eturns the key codes currently being used as modifiers. X perm its a t m ost eight
modifier keys.

Format
CLX:MODIFIER-MAPPING d is p la y
Argument
display
A CLX:DISPLAY object.

Return Values
E ight values, each of which is a list of c l x :k e y s y m values representing key codes
th a t have the m atching modifier bound to them:

shift
lock
control
modi
mod2
mod3
mod4
mod5

CLX:MODIFIER-MASK Type Specifier
Objects of type c l x :m o d i f i e r -m a s k are retu rn ed by th e c l x :m a k e -s t a t e -m a s k
function and m ay be passed to the c l x :u n g r a b -k e y and c l x :MAKE-s t a t e -k e y s
functions.

Representation
(OR (MEMBER :ANY) CLX:MASK16 (LIST CLX:M0D1FIER-KEY))

CLX-139

C LX :M O T IO N -E V E N T S Function

CLX:MOTION-EVENTS Function
R eturns all events in the motion history buffer which fall betw een the specified
s ta rt and stop tim es (inclusive) and which have coordinates th a t lie w ithin
(including borders) the specified window a t its present location.
The X and Y coordinates retu rn ed are relative to th e origin of the window.
If th e s ta rt tim e is la te r th a n the stop tim e or if the s ta rt tim e is late r th a n the
c u rren t tim e, no events are retu rn ed . If th e stop tim e is la te r th a n the cu rren t
tim e, th e cu rren t tim e is used as the stop time.

Format
CLX:MOTION-EVENTS w in d o w & K E Y :START :STOP :RESULT-TYPE
Arguments
window
A c l x :w i n d o w object.
:START :STOP
TWO CLX:TIMESTAMP v a l u e s .

:RESULT-TYPE
The LISP type of the re tu rn value. The default i s 'L IS T .

Return Value
A CLX:REPEAT-SEQ value whose elem ents contain three values:
X

Integer

tim e

CLX:TIMESTAMP

CLX:OPEN-DISPLAY Function
Opens a connection to th e X server on th e specified host and re tu rn s a
c l x :d i s p l a y structure. You can open a connection to an o th er m achine on the
netw ork only if you a re an authorized u se r on th a t m achine. See th e VMS
DECwindows U ser’
s Guide for inform ation on controlling netw ork access to your
w orkstation.

Format
CLXrOPEN-DISPLAY h o s t &KEY :DISPLAY :PROTOCOL

CLX—140

C LX:O PE N -D ISP LA Y Function

Arguments
host
A strin g th a t nam es a machine.

:DISPLAY
An integer specifying a screen attached to the given host. The default value is 0,
m eaning display 0.

PROTOCOL
E ith er : DECNET or :TCP. The default value is :DECNET.

Return Value
An object of type CLX:d i s p l a y .

CLX:OPEN-FONT Function
Loads a font into LISP m em ory from a file. The CLX:FONT-PATH function retu rn s
the search p a th used by the server to find font files.

Format
CLX:OPEN-FONT d is p la y n a m e
Arguments
display
A CLX:DISPLAY object.

name
A string th a t nam es the font to be opened.

Return Value
The opened clx:F0 nt object.

CLX:PIXARRAY Type Specifier
P ixarrays are array s of CLX:PIXEL values.

Representation
(ARRAY CLX:PIXEL (* *))

CLX—141

C LX :P IX E L Type Specifier

CLXiPIXEL Type Specifier
Objects of type c l x : p i x e l are retu rn ed by the color allocation functions, and
can be passed to the color storage and deallocation functions and used in the
: f o r e g r o u n d and : b a c k g r o u n d components of a GContext.

Representation
(UNSIGNED-BYTE 32)

CLX:PIXMAP Structure
A pixmap is an area of m em ory into which clients can eith er draw objects or
tem porarily save p a rt of a screen.
Constructor Function
C L X : CREATE-PIXM A P

Information Functions
None of the following functions is a valid s e t f place:
N am e

T y p e D e fin itio n

C L X : P IX M A P -D IS P L A Y

C L X :D IS P L A Y

C L X :PIX M A P-E Q U A L

CLX:BOOLEAN

C L X :P IX M A P -ID

C L X :R E S O U R C E -ID

C L X :P IX M A P -P

CLX:BOOLEAN

Deallocator Function
C L X :F R E E -P IX M A P

CLX:PIXMAP-DISPLAY Function
R eturns the display on which the specified pixm ap w as created.

Format
CLX:PIXMAP-DISPLAY p ix m a p
Argument
pixmap
A c l x : p i x m a p object.

CLX—142

C LX:PIX M A P-D ISP LA Y Function

Return Value
A CLX:DISPLAY object.

CLX:PIXMAP-EQUAL Function
R eturns tru e if its two argum ents are th e sam e c l x :p i x m a p object.

Format
CLX:PIXMAP-EQUAL o b je c t-1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

Return Value
A CLX:BOOLEAN value.

CLX:PIXMAP-FORMAT Structure
Objects of type c l x :P i x m a p -f o r m a t show which form ats the display hardw are
supports.
Constructor Function
CLX:MAKE-PIXMAP-FORMAT

Accessor Functions
All of th e following functions can be used w ith s e t f :
N am e

T y p e D e fin itio n

CLX:PIXMAP-FORMAT-BITS-PER-PIXEL

(MEMBER 1 4 16 24 32)

CLX:PIXMAP-FORMAT-DEPTH

CLX:IMAGE-DEPTH

CLX:PIXMAP-FORMAT-PAD

(MEMBER 8 16 32)

Deallocator Function
Pixm ap-form ats are subject to garbage collection.

CLX—143

C LX :P IX M A P -FO R M A T-B ITS -P E R -P IX E L Function

CLX:PIXMAP-FORMAT-BITS-PER-PIXEL Function
R eturns the num ber of bits used to rep resen t each pixel in th e specified
pixm ap-form at.

Format
CLX:PIXMAP-FORMAT-BITS-PER-PIXEL p ix m a p - f o r m a t
Argument
pixmap-format
A CLX:PIXMAP-FORMAT object.

Return Value
A m em ber of (l 4 8 16 24 32).

CLX:PIXMAP-FORMAT-DEPTH Function
R eturns the depth, or num ber of planes, in th e specified pixmap-format.

Format
CLX:PIXMAP-FORMAT-DEPTH p ix m a p - f o r m a t
Argument
pixmap-format
A CLX:PIXMAP-FORMAT object.

Return Value
A CLX: IMAGE-DEPTH value.

CLX—144

C LX:PIX M A P-FO R M A T-P Function

CLX:PIXMAP-FORMAT-P Function
R eturns T if its argum ent is a CLX:p i x m a p -f o r m a t object.

Format
CLX:PIXMAP-FORMAT-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:PIXMAP-FORMAT-PAD Function
R eturns the num ber of bits to a m ultiple of which each scanline in th e specified
pixm ap-form at is to be padded.

Format
CLX:PIXMAP-FORMAT-PAD p ix m a p - f o r m a t
Argument
pixmap-format
A CLX:PIXMAP-FORMAT object.

Return Value
A m em ber of (8 16 32).

CLX—145

C LX :P IX M A P-ID Function

CLX:PIXMAP-ID Function
R eturns th e integer resource-id of the specified pixmap.

Format
CLX:PIXMAP-ID p ix m a p
Argument
pixmap
A c l x :p i x m a p object.

Return Value
The c l x :r e s o u r c e - i d associated w ith pixmap.

CLX:PIXMAP-P Function
R eturns T if its argum ent is a c l x :p i x m a p object.

Format
CLX:PIXMAP-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:POINTER-CONTROL Function
R eturns th e pointer cursor acceleration and threshold as m ultiple values.

Format
CLX:POINTER-CONTROL d is p la y

CLX—146

C LX-.PO INTER-CO NTRO L Function

Argument
display
A CLX:DISPLAY object.

Return Values
Two values:
•

A num ber, possibly a ratio, th a t indicates acceleration compared to the default
speed.

•

An integer th a t indicates the threshold distance of pointer motion before
acceleration is applied.

CLX:POINTER-EVENT-MASK Type Specifier
Objects of type CLX:p o i n t e r -e v e n t -m a s k are retu rn ed by the
c l x :m a k e -e v e n t -m a s k function and m a y

be passed to the CLX:m a k e -e v e n t -k e y s ,
CLX: GRAB-POINTER, and C LX:GRAB-BUTTON functions.

Representation
(OR CLX:MASK32 (LIST CLX:POINTER-EVENT-MASK-CLASS))

CLX:POINTER-EVENT-MASK-CLASS Type Specifier
Objects of type c l x :p o i n t e r -e v e n t -m a s k -c l a s s are retu rn ed by the
c l x :m a k e -e v e n t -m a s k function and can be passed to th e c l x :m a k e -e v e n t -k e y s
function.

Representation
(MEMBER :BUTTON-PRESS :BUTTON-RELEASE :ENTER-WINDOW 1EAVE-WINDOW
POINTER-MOTION POINTER-HINT :BUTTON-1-MOTION :BUTTON-2-MOTION
:BUTTON-3-MOTION :BUTTON-4-MOTION :BUTTON-5-MOTION
:BUTTON-MOTION :KEYMAP-STATE)

CLX-.POINTER-MAPPING Function
R eturns a m apping list th a t defines which butto n s are enabled for the pointer
cursor on th e specified display. This function can be used w ith s e t f .

CLX—147

C LX :P O IN TE R -M A P P IN G Function

Format
CLXrPOINTER-MAPPING d is p la y & KEY :RESULT-TYPE
Arguments
display
A CLX:DISPLAY object.
:RESULT-TYPE

The LISP type of the re tu rn value. The default is 'l i s t .

Return Value
A sequence of integers.

CLX:POINTER-POSITION Function
R eturns th e position of the pointer cursor relative to the origin of the specified
window. The la s t re tu rn value indicates w hether th e pointer cursor is on the
sam e screen.

Format
CLX:POINTER-POSITION w in d o w
Argument
window
A C LX : w in d o w object.

Return Values
Three values:

CLX—148

An integer X coordinate.

An integer Y coordinate.

sa m e-screen -p

A CLX:BOOLEAN value.

CLX:POINT-SEQ Type Specifier

CLX:POINT-SEQ Type Specifier
A c l x :r e p e a t -s e q of X and Y coordinates. Objects of th is type m ay be passed to
th e CLX: d r a w -p o i n t s function.

Representation
(CLX:REPEAT-SEQ (FIXNUM x) (FIXNUM y))

CLX:PROCESS-EVENT Function
R eads even ts from the qu eu e and in vok es the : h a n d l e r function on each event
until a non-NiL value is returned. That return ed object is then retu rn ed by
CLX: p r o c e s s -e v e n t . I f this function is invoked recursively, the n ested invocation
b egin s w ith the event after the one cu rren tly b e in g processed.
H a n gs until non-NiL is return ed for an event, or for the n um ber o f secon ds
specified by the : t i m e o u t argument.

The argum ents to the : h a n d l e r function are described in detail in Section 12.5.
If a value for th e : e v e n t argum ent is provided, the function processes th a t event
ra th e r th a n reading from the server queue.

Format
CLX:PROCESS-EVENT d is p la y & KEY :HANDLER :TIMEOUT :PEEK-P
:DISCARD-P :FORCE-OUTPUT-P :EVENT
Arguments
display
A CLX:DISPLAY object.
:HANDLER
A function to be executed when an event occurs.
rTIMEOUT
The num ber of seconds to w ait for an event.
:PEEK-P
A c l x :b o o l e a n value. If true, events are left on th e queue.
:D1SCARD-P
A CLX:b o o l e a n value. If true, events for which th e :.h a n d l e r function re tu rn s NIL
are removed from the queue; otherwise, they are left in place.
:FORCE-OUTPUT-P
A CLX: boolean value. If true, the function invokes CLX :DISPLAY-FORCE-OUTPUT
before it s ta rts reading events. The default value is T.
CLX—149

C L X :P R O C E S S -E V E N T Function

:EVENT
A dvjt :e v e n t value.

Return Value
The first non-NiL value returned by the :h a n d l e r function, or n i l if :t i m e o u t is
reached.

CLX:PUT-IMAGE Function
P u ts an im age into a draw able. W hen : b i t m a p -p is true, the function forces the
form at of th e im age to be : b i t m a p w hen its depth is 1. This causes gcontext to
supply th e foreground and background pixels.

Format
CLX:PUT“IMAGE d r a w a b le g c o n t e x t im a g e &KEY :SRC-X :SRC-Y :X :Y :WIDTH
:HEIGHT :BITMAP-P
Arguments
drawable
A CLX:DRAWABLE object.

gcontext
A CLX:GCONTEXT object.

Image
A CLX: IMAGE object.
:SRC-X :SRC-Y
Integers th a t specify the X and Y offsets into the im age d ata. The default value
for these keywords is 0.
:X :Y
Integers th a t specify the X and Y coordinates in th e draw able for th e origin of the
inserted im age data. These argum ents are required.
:WIDTH :HEIGHT
Integers th a t specify th e dim ensions of th e im age to insert.
:BITMAP-P
A CLX:BOOLEAN value.

CLX—150

C LX:PU T-IM A G E Function

Return Value
Unspecified.

CLX:PUT-RAW-IMAGE Function
P u ts image d a ta into a drawable.
The data argum ent m u st be a sequence of 8-bit quantities already in the
appropriate form at for transm ission; th e client is responsible for all byte and
b it swapping and compaction. The : START argum ent is the startin g index in data ;
th e end is computed from the other argum ents.

Format
CLX:PUT-RAW-IMAGE d r a w a b le g c o n te x t d a ta
&KEY :START :DEPTH :X :Y :WIDTH :HEIGHT
:LEFT-PAD :FORMAT
Arguments
drawable
The CLX:d r a w a b l e where the im age is displayed.

gcontext
The CLX: GCONTEXT th a t specifies th e graphics characteristics, such as foreground
and background colors, of the image.

data
A sequence of 8-bit q u antities containing th e image.
:START

A CLX:a r r a y - i n d e x specifying th e sta rtin g point w ithin data. The default value
is 0.
:DEPTH
An integer th a t specifies the depth of th e image.
:X :Y
Integers th a t specify the X and Y coordinates in th e draw able for th e origin of the
image.
:WIDTH :HEIGHT
Integers th a t specify th e dim ensions of the im age to insert.
:LEFT-PAD
An integer th a t specifies the num ber of pixels offset in th e X direction. The
default value is 0.

CLX—151

C LX:PU T-R A W -IM A G E Function

:FORMAT
The type of im age form at, eith er :XY-p i x m a p or z -p i x m a p .

Return Value
Unspecified.

CLX:QUERY-BEST-CURSOR Function
Asks th e server for the preferred cursor dim ensions th a t a re closest to the ones
supplied as argum ents to the function.

Format
CLX:QUERY-BEST-CURSOR w id th h e ig h t d is p la y
Arguments
width height
Integers th a t indicate dim ensions of a cursor, in pixels.

display
A CLX:DISPLAY object.

Return Values
Two integers th a t specify the dim ensions of the server’s n e arest cursor
dim ensions.

CLX:QUERY-BEST-STIPPLE Function
Asks the server for the preferred dim ensions for fast stippling th a t a re closest to
the ones supplied as argum ents to the function.

Format
CLX:QUERY-BEST-STIPPLE w id th h e ig h t d r a w a b le
Arguments
width height
Integers th a t indicate the requested dimensions.

CLX—152

C LX:Q U ER Y-B EST-STIPPLE Function

drawable
A CLX: DRAWABLE object.

Return Values
Two integers th a t rep resen t the server’s preferred dim ensions for fast stipple
operations.

CLX:QUERY-BEST-TILE Function
Asks the server for th e preferred dim ensions for fast tiling th a t are closest to the
ones supplied as argum ents to the function.

Format
CLX:QUERY-BEST-TILE w id th h e ig h t d r a w a b le
Arguments
width height
Integers th a t indicate the requested dimensions.

drawable
A CLX:DRAWABLE object.

Return Values
Two integers th a t rep resen t the server’s preferred dim ensions for fast tiling
operations.

CLX:QUERY-COLORS Function
R eturns th e RGB values of specified entries in a colormap.

Format
CLX:QUERY-COLORS c o lo r m a p p ix e ls &KEY :RESULT-TYPE
Arguments
colormap
A CLX:COLORMAP object.

pixels
A sequence of CLX:p i x e l values.
CLX—153

CLX.-QUERY-COLORS Function
:RESULT-TYPE
The LISP type of the re tu rn value. The default is 'l i s t .

Return Value
A sequence of c l x :c o l o r objects.

CLX:QUERY-EXTENSION Function
R eturns inform ation about th e specified extension. For m ore inform ation, see the
X Window System: C Library and Protocol Reference.

Format
CLXrQUERY-EXTENSION d is p la y n a m e
Arguments
display
A CLX:DISPLAY object.

name
A string th a t nam es an extension.

Return Values
Three integer values:
•

The major operation code, if any.

•

The base event type code, if th e extension defines additional event types.

•

The base error code, if the extension defines additional erro r codes.

CLX:QUERY-KEYMAP Function
R eturns the state of keys on th e keyboard.

Format
CLX:QUERY-KEYMAP d is p la y

CLX—154

C LX :Q U ER Y-K EYM A P Function

Argument
display
A CLX:DISPLAY object.

Return Value
A (b i t -v e c t o r 256) value whose 1 bits signify th a t a key is pressed.

CLX:QUERY-POINTER Function
Asks th e server for inform ation about th e pointer, relative to th e specified window.

Format
CLX:QUERY-POINTER w in d o w
Argument
window
A c l x :w i n d o w object.

Return Values
E ight values:
1.

Integer X coordinate of the pointer cursor’s location.

Integer Y coordinate of the pointer cursor’s location.

3. A c l x :BOOLEAN value that indicates whether the pointer cursor is on the sa m e
screen as window.

The c l x :w i n d o w object th a t is a child of window and th a t contains th e pointer
cursor.

5. A c l x :MASK32 value that indicates the state of buttons on the pointer device.
6.

Integer X coordinate of the pointer cursor’s location relative to the root of

window.
7.

Integer Y coordinate of the pointer cursor’s location relative to th e root of

window.
8.

The c l x :w i n d o w object th a t is the root of window.

CLX—155

CLX:QUERY TREE Function

CLX:QUERY-TREE Function
R eturns th e children, parent, and root of the specified window.

Format
CLX:QUERY-TREE w in d o w & K E Y :RESULT-TYPE
Arguments
window
A c l x :w i n d o w object.
:RESULT-TYPE
The LISP type of the first re tu rn value. The default is ' l i s t .

Return Values
Three values:
•

A sequence of CLX : w i n d o w objects th a t contains th e children of window.

•

The c l x :w i n d o w object th a t is the p a re n t of window.

• The c l x :w i n d o w object th a t is the root of window.

CLX:QUEUE-EVENT Function
Adds an event to th e queue.
The event is p u t a t the head of th e queue if :APPEND-p is n i l , else the tail.
Additional argum ents depend on the event-key argum ent and are as specified in
Section 12.5.

Format
CLX:QUEUE-EVENT d is p la y e v e n t - k e y & REST a r g s &KEY :APPEND-P
&ALLOW-OTHER-KEYS
Arguments
display
A CLX:DISPLAY object.

event-key
A CLX:EVENT-KEY value.

CLX-156

CLX:QUEUE-EVENT Function
args
A lam bda list of the argum ents allowed for event-key (see Section 12.5).
:APPEND-P

A c l x :b o o l e a n value. If true, th e event is placed a t the tail of th e queue.
A dditional keyword argum ents, corresponding to the valid argum ents for the
event-key, a re allowed.

Return Value
Unspecified.

CLX:READ-BITMAP-FILE Function
C reates a n im age or a pixm ap from a C include file in standard X l l form at.

Format
CLX:READ-BITMAP-FILE p a t h n a m e &KEY :PIXMAP-P :DRAWABLE
Arguments
pathname
A pathnam e or string th a t specifies th e file to read.
:PIXMAP-P
A c l x :b o o l e a n value th a t determ ines w hether the re tu rn value is a pixmap or an
image.
:DRAWABLE
A c l x :d r a w a b l e object. This arg u m en t is required if : p i x m a p -p is true.

Return Values
If : p i x m a p -p is false, th e function re tu rn s a single c l x :i m a g e object. If :Pi x m a p -p
is true, th e function re tu rn s three values:
•

A c l x :p i x m a p object containing th e d a ta from the specified file.

•

An i n t e g e r th a t specifies the X coordinate of a cursor’s hot spot.

•

An i n t e g e r th a t specifies the Y coordinate of a cursor’s hot spot.

CLX—157

C L X :R E C O LO R -C U R S O R Function

CLX:RECOLOR-CURSOR Function
Changes the foreground and background colors of th e specified cursor.

Format
CLX:RECOLOR-CURSOR c u r s o r fo r e g r o u n d b a c k g r o u n d
Arguments
cursor
A c l x :c u r s o r object.

foreground background
Two c l x :c o l o r objects th a t specify the new colors.

Return Value
Unspecified.

CLX:RECT-SEQ Type Specifier
A c l x :r e p e a t - s e q of X and Y coordinates, w idth and height. Objects of type
c l x :r e c t - s e q can be passed to th e c l x :d r a w -r e c t a n g l e s function.

Representation
(CLX:REPEAT-SEQ (FIXNUM x) (FIXNUM y)
(FIXNUM width) (FIXNUM height))

CLX:REMOVE-ACCESS-HOST Function
D eletes a m achine from th e access control list of th e specified display.

Format
CLX:REMOVE-ACCESS-HOST d is p la y h o s t
Arguments
display
A CLX:DISPLAY object.

CLX—158

C LX :R E M O V E -A C C E S S -H O S T Function

host
A strin g th a t nam es a m achine.

Return Value
Unspecified.

CLX:REMOVE-FROM-SAVE-SET Function
Removes the specified window from your client’s saveset so th a t it is destroyed
w hen its client exits. The window m u st have been created by some other client or
an error occurs.

Format
CLX:REMOVE-FROM-SAVE-SET w in d o w
Argument
window
A c l x :w i n d o w object.

Return Value
Unspecified.

CLX:REPARENT-WINDOW Function
C hanges the parent and possibly location of th e specified window.

Format
CLX:REPARENT-WINDOW w in d o w p a r e n t x y
Arguments
window parent
Two c l x :w i n d o w objects.

xy
Integer X and Y coordinates of the new origin of window, m easured in pixels from
th e origin of parent.

CLX—159

C LX:R E P A R EN T-W IN D O W Function

Return Value
Unspecified.

CLX:REPEAT-SEQ Type Specifier
CLX: r e p e a t - s e q is an abstract type that denotes sequences composed of repeating
patterns of specifically typed objects.

Representation
SEQUENCE

A sequence containing 0 or m ore elem ents of th e form:
(type name)

CLX:RESET-SCREEN-SAVER Function
Resets the screen saver’s tim eout clock to 0, as if in p u t had ju s t been received.

Format
CLX:RESET-SCREEN-SAVER d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
Unspecified.

CLX:RESOURCE-ID Type Specifier
Objects of type CLX: r e s o u r c e - i d are retu rn ed by th e CLX: *-i d functions.

Representation
INTEGER

CLX—160

C LX:RG B-VA L Type Specifier

CLX:RGB-VALType Specifier
Objects of type c l x :r g b -v a l are retu rn ed by the color allocation functions
and can be used w ith s e t f and th e c l x :c o l o r -r e d , c l x :c o l o r -g r e e n , and
c l x :c o l o r -b l u e functions.

Representation
(FLOAT 0.0 1.0))

CLX:SCREEN Structure
This stru ctu re contains inform ation on the hardw are and software characteristics
of a w orkstation screen.
Constructor Function
Instances of type c l x :s c r e e n are retu rn ed by th e c l x :DISp l a y -d e f a u l t -s c r e e n
and c l x :d i s p l a y -r o o t s functions.
Accessor Functions
None of these functions is a valid s e t f place.
Name

Type Definition

CLX:SCREEN-BACKING-STORES

MEMBER :NEVER :WHEN-MAPPED :ALWAYS

CLX:SCREEN-BLACK-PIXEL

CLX:PIXEL

CLX:SCREEN-DEFAULT-COLORMAP

CLX:COLORMAP

CLX:SCREEN-DEPTHS

(ALIST (CLX: IMAGE-DEPTH depth)
((LIST CLX:VISUAL-INFO) visuals) )

CLX:SCREEN-DISPLAY

CLX-.DISPLAY

CLX:SCREEN-EVENT-MASK-AT-OPEN

CLX:EVENT-MASK

CLX:SCREEN-HEIGHT

INTEGER

CLX:SCREEN-HEIGHT-IN-MILLIMETERS

INTEGER

CLX:SCREEN-MAX-INSTALLED-MAPS

INTEGER

CLX:SCREEN-MIN-INSTALLED-MAPS

INTEGER

CLX:SCREEN-P

CLX:BOOLEAN

CLX:SCREEN-ROOT

CLX:WINDOW

CLX:SCREEN-ROOT-DEPTH

CLX:IMAGE-DEPTH

CLX:SCREEN-ROOT-VISUAL

CLX:VISUAL

CLX:SCREEN-SAVE-UNDERS-P

CLX:BOOLEAN

CLX:SCREEN-WHITE-PIXEL

CLX:PIXEL

CLX:SCREEN-WIDTH

INTEGER

CLX:SCREEN-WIDTH-IN-MILLIMETERS

INTEGER

CLX—161

C LX :S C R EEN Structure

Deallocator Function
Instances of the CLX:s c r e e n stru ctu re are subject to garbage collection.

CLX:SCREEN-BACKING-STORES Function
R eturns a keyword th a t indicates w hen the server m aintains contents of windows.

Format
CLX:SCREEN-BACKING-STORES s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
:NEVER, :WHEN-MAPPED, Or :ALWAYS.

CLX:SCREEN-BLACK-PIXEL Function
R eturns the pixel value th a t produces black on the specified screen.

Format
CLX:SCREEN-BLACK-PIXEL s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A c l x :p i x e l value.

CLX—162

C LX:SC R EEN -D E FA U LT-C O LO R M A P Function

CLX:SCREEN-DEFAULT-COLORMAP Function
R eturns the default colormap of the specified screen.

Format
CLXrSCREEN-DEFAULT-COLORMAP s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX : COLORMAP object.

CLX:SCREEN-DEPTHS Function
R eturns th e depths supported by the display hardw are, w ith a list of the valid
visual types supported a t each depth.

Format
CLX:SCREEN-DEPTHS s c r e e n
Argument
screen
A CLX:SCREEN object.

Return Value
An association list whose elem ents have the form at:
(depth visuals)
where d e p t h is a clx: image-depth value and v i s u a l s is a list of CLX:visual-info
objects.

CLX—163

C LX:S C R EEN -D ISP LA Y Function

CLX:SCREEN-DISPLAY Function
R eturns th e display associated w ith the specified screen.

Format
CLX:SCREEN-DISPLAY s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX:DISPLAY object.

CLX:SCREEN-EVENT-MASK-AT-OPEN Function
R eturns th e event m ask of the specified screen’s root window, a t the tim e the
connection was established.

Format
CLX:SCREEN-EVENT-MASK-AT-OPEN s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX:EVENT-MASK value.

CLX—164

C LX :S C R E E N -H E IG H T Function

CLX:SCREEN-HEIGHT Function
R eturns the height of th e screen, m easured in pixels.

Format
CLX:SCREEN-HEIGHT s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
An integer.

CLX:SCREEN-HEIGHT-IN-MILLIMETERS Function
R eturns the height of th e screen, m easured in m illim eters.

Format
CLX:SCREEN-HEIGHT-IN-MILLIMETERS s c r e e n
Argument
screen
A CLX:SCREEN object.

Return Value
An integer.

CLX:SCREEN-MAX-INSTALLED-MAPS Function
R eturns th e m axim um num ber of colormaps th a t can be installed on th e specified
screen.

CLX—165

C LX :S C R E E N -M A X -IN S TA LLE D -M A P S Function

Format
CLX:SCREEN-MAX-INSTALLED-MAPS s c r e e n
Argument
screen
A c l x :s c r e e n object.

Return Value
An integer.

CLX:SCREEN-MIN-INSTALLED-MAPS Function
R eturns the num ber of colormaps th a t can be guaranteed to be installed on the
specified screen regardless of th e num ber of entries allocated in each map.

Format
CLX:SCREEN-MIN-INSTALLED-MAPS s c r e e n
Argument
screen
A CLX:SCREEN object.

Return Value
A n integer.

CLX:SCREEN-P Function
Ttests w hether its argum ent is a c l x :s c r e e n object.

Format
CLX:SCREEN-P o b je c t

CLX-166

C L X :S C R E E N -P Function

Argument
object
Any LISP object.

Return Value
T if o b j e c t is of type CLX: screen; otherwise, nil.

CLX:SCREEN-ROOT Function
R eturns the root window of the specified screen.

Format
CLX:SCREEN-ROOT s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX:w i n d o w object.

CLX:SCREEN-ROOT-DEPTH Function
R eturns th e num ber of planes in the specified screen.

Format
CLX:SCREEN-ROOT-DEPTH s c r e e n
Argument
screen
A CLX: SCREEN object.

CLX—167

C LX :S C R E EN -R O O T-D E PTH Function

Return Value
A CLX:IMAGE-DEPTH value.

CLX:SCREEN-ROOT-VISUAL Function
R eturns the visual type of th e specified screen.

Format
CLX.SCREEN-ROOT-VISUAL s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX:VisuAL value.

CLX:SCREEN-SAVER Function
R eturns the cu rren t screen saver settings for the specified display.

Format
CLX:SCREEN-SAVER d is p la y
Argument
display
A CLX:DISPLAY object.

Return Values
F our values:

CLX—168

tim eou t

Number o f seconds that m ust elapse with no input from the keyboard or
pointer before the screen saver turns on. A value o f 0 m eans that the screen
saver is disabled.

in terval

N u m ber o f secon d s b etw een in v ocation s o f the screen saver.

CLX:SCREEN-SAVER Function

blan kin g

exposures

One o f three keywords specifying how the screen is cleared:
:YES

Blank the screen. This can be returned only if the display
hardware supports video blanking.

: no

Do not blank the screen. I f exposures are allow ed (see below),
or if the screen can be regenerated without sending exposure
events to clients, the screen is tiled with the root window
background tile. I f exposures are not allowed or the exposure
events are sent to clients, the screen does not change.

:DEFAULT

The default blanking m ethod is used.

One of three keywords specifying whether exposure events are generated:
:YES

Exposures are allowed. This is the default.

:NO

Exposures are not allowed.

:DEFAULT

The default value is used.

CLX:SCREEN-SAVE-UNDERS-P Function
Indicates w hether the server saves the contents of windows obscured by client
windows.

Format
CLX:SCREEN-SAVE-UNDERS-P s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
A CLX:BOOLEAN value.

CLX:SCREEN-WHITE-PIXEL Function
R eturns the pixel value th a t produces w hite on th e specified screen.

Format
CLX:SCREEN-WHITE-PIXEL s c r e e n

CLX-169

C LX :S C R E E N -W H IT E -P IX E L Function

Argument
screen
A CLX :SCREEN object.

Return Value
A c l x :p i x e l value.

CLX:SCREEN-WIDTH Function
R eturns the w idth of the specified screen, m easured in pixels.

Format
CLX:SCREEN-WIDTH s c r e e n
Argument
screen
A CLX: SCREEN object.

Return Value
An integer.

CLX:SCREEN-WIDTH-IN-MILLIMETERS Function
R eturns the w idth of the specified screen, m easured in m illim eters.

Format
CLX:SCREEN-WIDTH-IN-MILLIMETERS s c r e e n
Argument
screen
A CLX: SCREEN object.

CLX—170

C LX:S C R E E N -W ID TH -IN -M ILLIM E TE R S Function

Return Value
An integer.

CLX:SEG-SEQ Type Specifier
A CLX: r e p e a t - s e q u e n c e of line segm ents. Objects of type CLX:SEG- s e q can be
passed to the c l x :d r a w -s e g m e n t s function.

Representation
(CLX:REPEAT-SEQ (FIXNUM xl) (FIXNUM yl) (FIXNUM x2) (FIXNUM y2))

CLX:SELECTION-OWNER Function
R eturns th e c u rren t owner of th e specified selection (global property).

Format
CLX:SELECTION-OWNER d is p la y s e le c tio n
Arguments
display
A CLX:DISPLAY object.

selection
A c l x :x a t o m value.

Return Value
A c l x :w i n d o w object or n i l if no client owns the selection.

CLX:SEND-EVENT Function
Sends an event to a specified window. The function identifies the destination
window, determ ines which client should receive the event, and ignores any active
grabs. The contents of th e event are specified by additional keyword argum ents,
and are not checked or altered by the X server except th a t the : s e n d -e v e n t
component is set to T.
The window argum ent determ ines the destination window. A value of
:p o i n t e r -w i n d o w specifies the window th a t contains the pointer cursor. A value
of : i n p u t -f o c u s specifies the window th a t h as input focus.

CLX—171

C L X :S E N D -E V E N T Function

Normally, the event is sent to every client whose event m ask for the destination
window m atches the event-mask argum ent. U nder certain circum stances, the
event m ay be sent to other clients, or no event m ay be sent:
•

If event-mask is 0, th e event is sent to th e client th a t created th e destination
window. If th a t client no longer exists (its connection to the display h as been
closed), no event is sent.

•

If : p r o p a g a t e -p is T b u t no client has selected any of th e event types in
event-mask for the destination window, th e destination window is replaced
w ith its closest ancestor for which some client has selected a m atching event
type (assum ing any intervening windows propagate the event type). If no
such ancestor exists, or if the window is an ancestor of the focus window and
:i n p u t -f o c u s was originally specified as th e destination window, th en the
event is not sent to any client.

Format
CLX:SEND-EVENT w in d o w e v e n t - k e y e v e n t - m a s k &REST a rg s
&KEY :PROPAGATE-P :DISPLAY &ALLOW-OTHER-KEYS
Arguments
window
A CLX: WINDOW object, :POINTER-WINDOW, or :INPUT-FOCUS.

event-key
A CLX:EVENT-KEY Value Or NIL.

event-mask
A CLX:EVENT-MASK value.

args
Keyword-value pairs appropriate to th e event-key. See Section 12.5.
:PROPAGATE-P
A CLX:BOOLEAN value. If true, th e event is propagated to other clients.
:DISPLAY
A CLX:DISPLAY object or NIL.
Additional keywords, corresponding to the argum ents listed in Section 12.5, are
allowed.

Return Value
Unspecified.

CLX—172

C LX:SET-IN PU T-FO C U S Function

CLX:SET-INPUT-FOCUS Function
Sets the in p u t focus to the specified window.

Format
CLX:SET-INPUT-FOCUS d is p la y fo c u s r e v e r t-t o &OPTIONAL tim e
Arguments
display
A CLX:DISPLAY object.

focus
The CLX:w i n d o w object th a t gets in p u t focus.

revert-to
A keyword th a t specifies th e window in p u t focus reverts to if the focus window is
unviewable: :NONE, : p a r e n t , or : p o i n t e r - r o o t .

time
The c l x :t i m e s t a m p when in p u t focus is set.

Return Value
Unspecified.

CLX’.SET-MODIFIER-MAPPING Function
Changes the key codes of the keys (if any) th a t are used as modifiers. The
function re tu rn s a keyword th a t indicates the sta tu s of th e change.

Format
CLX:SET-MODIFIER“MAPPING d is p la y & KEY :SHIFT :LOCK :CONTROL :MOD1
:MOD2 :MOD3 :MOD4 :MOD5
Arguments
display
A CLX:DISPLAY object.
:SHIFT :LOCK :CONTROL :MOD1 :MOD2 :MOD3 :MOD4 :MOD5
Sequences of integers th a t specify the key codes of the modifier keys.

CLX—173

C L X :S E T-M O D IFIE R -M A P P IN G Function

Return Value
A k ey w ord :
:SUCCESS

The key code is changed.

:BUSY

A modifier whose key codes are being changed is logically down.

:FAILED

The specified key codes are not valid for the modifier.

CLX:SET-SCREEN-SAVER Function
Changes the settings of the screen saver on the specified display.

Format
CLX:SET-SCREEN-SAVER display timeout interval blanking exposures
Arguments
display
A CLX:DISPLAY object.

timeout Interval
Integers th a t indicate tim e in seconds, or : d e f a u l t .

blanking exposures
:YES, :NO, Or :DEFAULT.

Return Value
Unspecified.

CLX:SET-WM-CLASS Function
Sets the class of a specified window. Note th a t th e nam e set w ith th is function
m ay differ from the nam e set w ith the c l X:WM- n a m e function. The resource-name
is the form al nam e of th e application th a t should be used when retrieving the
application’s resources from th e resource database.

Format
CLX:SET-WM-CLASS window resource-name resource-class

CLX—174

C LX:SET-W M -C LA SS Function

Arguments
window
A c l x :w i n d o w object.

resource-name resource-class
Two CLX:STRINGABLE values Or NIL.

Return Value
Unspecified.

CLX:STATE-MASK-KEY Type Specifier
Objects of type c l x :s t a t e -m a s k -k e y are retu rn ed by the c l x :m a k e -s t a t e -k e y s
function and can be passed to the c l x :MAKE-s t a t e -m a s k function.

Representation
(OR CLX:MODIFIER-KEY (MEMBER :BUTTON-1 :BUTTON-2 :BUTTON-3 :BUTTON-4
:BUTTON-5))

CLX:STORE-COLOR Function
Stores an RGB value in the specified colormap. If the spec argum ent is of type
c l x :s t r i n g a b l e , a nam ed color is stored.

Format
CLX:STORE-COLOR c o lo r m a p p ix e l s p e c &KEY :RED-P :GREEN-P :BLUE-P
Arguments
colormap
A CLX:COLORMAP object.

pixel
A c l x :p i x e l value.

spec
A CLX:COLOR object or CLX: STRINGABLE value.
:RED-P :GREEN-P :BLUE-P
T hree c l x :b o o l e a n values th a t specify w hether the red, green, and blue values,
respectively, are stored. The defaults are T.

CLX—175

C LX :S TO R E-C O LO R Function

Return Value
Unspecified.

CLX:STORE-COLORS Function
Stores m ultiple RGB values in th e specified colormap. If the spec argum ent
uses CLX : STRINGABLE values, the nam es are first resolved and th en a single
StoreColors protocol request is issued.

Format
CLX:STORE-COLORS c o lo r m a p s p e c s &KEY :RED-P :GREEN-P :BLUE-P
Arguments
colormap
A CLX:COLORMAP object.

specs
A c l x :r e p e a t -s e q with elements in the format:
(pixel coloi)
where p i x e l is a CLX:pixel and c o l o r is either a CLX:color object or a
clx:STRINGABLE value that specifies a n a m e d color.

:RED-P :GREEN-P :BLUE-P
Three clx :boolean values th a t specify w hether the red, green, and blue values,
resp ectively, a re stored. T h e d e fa u lts a re T.

Return Value
Unspecified.

CLX:STRINGABLE Type Specifier
E ith e r a string or a symbol. This ab stract type is used by functions th a t need
strin g argum ents. Symbols are coerced to strings.

Representation
(OR STRING SYMBOL)

CLX—176

C LX:TE XT-EXTE N TS Function

CLX:TEXT-EXTENTS Function
R eturns th e m axim um character m etrics of a specified string. The : t r a n s l a t e
function is alw ays called w ith a 16-bit destination buffer.

Format
CLX:TEXT-EXTENTS fo n ts s e q u e n c e &KEY :START :END TRANSLATE
Arguments
fonts
A CLX : FONT Or a CLX:GCONTEXT object.

sequence
A sequence of characters (th a t is, a string).
:START
An integer. The default value is 0.
:END
An integer. The default value is the length of the sequence.
TRANSLATE
A function th a t tra n sla tes sequence into font indexes. The default function is
C L X :TRANSLATE-DEFAULT.

Return Values
N ine values:
1.

The total w idth of th e specified string.

The largest ascent of any character in the string.

The largest descent of any character in th e string.

The sm allest left-bearing of any character in the string.

The larg est right-bearing of any character in th e string.

The font-ascent of th e specified font.

The font-descent of th e font.

The direction h in t of the font, eith er o for left-to-right or l for right-to-left.

An a rra y index value th a t indicates th e position w ithin the string w here the
tran slatio n failed; if the entire string was tran slated , this value is n i l .

CLX—177

CLX:TE XT-W ID TH Function

CLX:TEXT-WIDTH Function
R eturns the w idth of the specified string, m easured in pixels and calculated using
the character inform ation stored in the specified font.

Format
CLX:TEXT-WIDTH fo n ts s e q u e n c e &KEY :START :END :TRANSLATE
Arguments
fonts
A CLX:FONT Or a CLX:GCONTEXT object.

sequence
A sequence of text item s; for example, a string.
:START
An index into sequence. The default is 0.
:END
An index into sequence. The default is th e length of sequence.
^TRANSLATE
A function th a t tra n sla te s sequence into font indexes. The default function is
CLX: t r a n s l a t e -d e f a u l t . If you provide a different function, it m u st deal w ith
16-bit buffers.

Return Values
Two values:
•

An integer th a t gives the w idth of th e sequence.

•

A c l x :a r r a y - i n d e x value th a t indicates the position in the sequence w here
the : t r a n s l a t e function failed; or NIL if the whole sequence w as translated.

CLX:TIMESTAMP Type Specifier
Objects of type c l x :t i m e s t a m p a re used as argum ents in th e c l x :e v e n t - c a s e
macro and c l x :p r o c e s s -e v e n t function, and can be passed to the c l x :s e n d -e v e n t
and CLX: GRAB-k e y b o a r d functions. NIL stands for th e cu rren t server tim e.

Representation
(OR NULL FIXNUM)

CLX—178

C LX:TR A N SLA TE -C O O R D IN A TE S Function

CLXrTRANSLATE-COORDINATES Function
T ranslates X and Y coordinates in one window to those in another, and indicates
which subwindow contains th e coordinates. If th e src and dst windows are not on
th e sam e screen, the values retu rn ed are 0 ; 0 ; NIL.

Format
CLX:TRANSLATE-COORDINATES s rc s r c - x s r c - y d s t
Arguments
src
A c l x :w i n d o w object.

src-x src-y
Integer X and Y coordinates of a location in the source window.

dst
A c l x :w i n d o w object.

Return Values
Three values:
•

The X coordinate in th e destination window.

•

The Y coordinate in th e destination window.

•

A CLX: w i n d o w object if the translated coordinates are contained in a m a p p e d
child of the destination window; otherwise n i l .

CLX:TRANSLATE-DEFAULT Function
T ranslates as m any elem ents of src as possible into indexes in the cu rren t font,
and stores them into dst.
The dst argum ent is guaranteed to have room for (src-end src-start) integer
elem ents, sta rtin g a t dst-start; w hether dst holds 8-bit or 16-bit elem ents depends
on context. If known, font is the current font.
The first re tu rn value should be th e src index of the first u n tra n sla ted element.
If no fu rth e r elem ents need to be translated, the second re tu rn value should
be n i l . If a horizontal m otion is required before fu rth e r translation, the second
re tu rn value should be th e delta in X coordinate. If known, the pixel w idth of the
tra n sla ted text can be retu rn ed as the th ird value; this can allow for appending
of subsequent o utput to the sam e protocol req u est if no overall w idth h as been
specified a t the higher level.

CLX—179

C LX TRANSLATE-DE FAULT Function

Format
CLX:TRANSLATE-DEFAULT s rc s r c - s ta r t s r c - e n d fo n t d s t d s t-s ta r t
Arguments
src
A sequence of text elem ents; for example, a string.

src-start src-end
Two CLX: a r r a y - i n d e x values th a t specify the first and la st positions w ithin the
source.

font
N ull or a clx:F0 nt object.

dst
A vector.

dst-start
A c l x :a r r a y - i n d e x value that specifies the starting position within the
destination.

Return Values
T hree values:
•

A c l x :a r r a y - i n d e x value th a t indicates th e first u n tra n sla te d elem ent in the
source.

•

nil

if the source was entirely translated.

• A n i n t e g e r th a t in d ic a te s th e w id th o f th e tr a n sla te d te x t in p ix e ls i f kn ow n ;
or NIL if not.

CLX:UNGRAB-BUTTON Function
Releases a passive grab of a b utton on th e pointing device.

Format
CLX:UNGRAB-BUTTON w in d o w b u tto n &KEY :MODIFIERS
Arguments
window
A C L X : C R E A T E -W IN D O W object.

button
An integer or : a n y .
CLX—180

C LX:U N G R A B -B U TTO N Function

[MODIFIERS
A CLX:MODIFIER-MASK value. The default i s 0.

Return Value
Unspecified.

CLX:UNGRAB-KEY Function
Releases a passive grab of a key on th e keyboard.

Format
CLX:UNGRAB-KEY w in d o w k e y &KEY :MODIFIERS
Arguments
window
A c l x : w in d o w object.

key
An integer or : a n y .
[MODIFIERS
A c l x : m o d i f i e r - m a sk value. The default is 0.

Return Value
Unspecified.

CLX:UNGRAB-KEYBOARD Function
Releases an active grab of the keyboard.

Format
CLXrUNGRAB-KEYBOARD d is p la y & KEY :TIME
Arguments
display
A CLX:DISPLAY o b je c t.
[TIME
The CLX:TIMESTAMP w hen the keyboard is released.

CLX—181

C LX :U N G R A B -K E Y B O A R D Function

Return Value
Unspecified.

CLX:UNGRAB-POINTER Function
Releases an active grab of the pointing device.

Format
CLX:UNGRAB-POINTER d is p la y & KEY :TIME
Arguments
display
A CLX:DISPLAY object.

:T1ME
The c l x :t i m e s t a m p w hen the pointer is released.

Return Value
Unspecified.

CLX:UNGRAB-SERVER Function
Releases an active server grab established by c l x : g r a b - s e r v e r . E vents that

occurred while the server w as grabbed are released to the event queue.

Format
CLX:UNGRAB-SERVER d is p la y
Argument
display
A CLX:DISPLAY object.

Return Value
Unspecified.

CLX—182

C LX:U N IN S TA LL-C O LO R M A P Function

CLX:UNINSTALL-COLORMAP Function
Removes color values from th e hardw are lookup table.

Format
CLX:UNINSTALL-COLORMAP c o lo r m a p
Argument
colormap
A CLX : COLORMAP object.

Return Value
Unspecified.

CLX:llNMAP-SUBWINDOWS Function
C auses all children of th e specified window to be unm apped or m ade not viewable
on the screen. The windows are actually rem oved w hen the output buffer holding
requests to the server is flushed (see c l x :D ISP L A Y - f o r c e - o o t p u t ).

Format
CLX:UNMAP-SUBWlNDOWS w in d o w
Argument
window
A c l x : w indow object.

Return Value
Unspecified.

CLX—183

C L X :U N M A P -W IN D O W Function

CLX:UNMAP-WINDOW Function
C auses the specified window to be unm apped or m ade unview able on th e screen.
The window is actually removed when th e output buffer holding requests to the
server is flushed (see CLX:d i s p l a y - f o r c e - o u t p u t ).

Format
CLX:UNMAP-WINDOW w in d o w
Argument
window
A c l x : w indow object.

Return Value
Unspecified.

CLX:VISUAL Type Specifier
Values of type c l x :V IS u a l are pointers to c l x : v i s u a l - i n f o objects. They are
retu rn ed by th e c l x : s c r e e n - r o o t - v i s u a l and c l x : w indow - v i s u a l functions.

Representation
INTEGER

CLX:VISUAL-INFO Structure
This stru c tu re contains inform ation on the hardw are and software characteristics
of a w orkstation screen.

C onstructor Function
The c l x : m ake - v i s u a l -IN FO function takes a c l x : v i s u a l value and re tu rn s a
c l x -.v i s u a l - i n f o object.

A ccessor Functions
None of the following functions is a valid s e t f place:

CLX—184

CLX:VISUAL-INFO Structure

N am e

T y p e D e fin itio n

CLX:V ISU A L -IN FO -B IT S-PE R -R G B

INTEGER

CLX:VISUAL-INFO-BLUE-MASK

CLX:PIXEL

CLX:VISUAL-INFO-CLASS

(MEMBER : STATIC-GRAY : STATIC-COLOR
: TRUE-COLOR : GRAY-SCALE
: PSEUDO-COLOR :DIRECT-COLOR)

CLX:VISUAL-INFO-COLORMAP-ENTRIE S

INTEGER

CLX:VISUAL-INFO-GREEN-MASK

CLX:PIXEL

C LX :V ISU A L -IN FO -ID

INTEGER

CLX:VISUAL-INFO-RED-MASK

CLX:PIXEL

Deallocator Function
Instances o f th e CLX:v i s u a l - i n f o stru ctu re are subject to garbage collection.

Predicate
CLX:V ISU A L -IN FO -P

CLX:VISUAL-INFO-BITS-PER-RGB Function
R eturns the num ber of b its used to store a n RGB value.

Format
CLX:VISUAL-INFO-BITS-PER-RGB v is u a l-in fo
Argument
visual-info
A c l x : v iS U A L - i n f o object.

Return Value
An integer.

CLX:VISUAL-INFO-BLUE-MASK Function
R eturns th e m ask used for blue indexes.

CLX—185

C LX :V IS U A L-IN FO -B LU E -M A S K Function

Format
CLX:VISUAL-INFO-BLUE-MASK v is u a l-in fo
Argument
visual-info
A CLX: VISUAL-INFO object.

Return Value
A c l x : p i x e l v a lu e .

CLX:VISUAL-INFO-CLASS Function
R eturns th e visual class of th e screen.

Format
CLX:VISUAL-INFO-CLASS v is u a l-in fo
Argument
visual-info
A CLX:VISUAL-INFO o b je c t.

Return Value
: STATIC-GRAY, : STATIC-COLOR, : TRUE-COLOR, : GRAY-SCALE, : PSEUDO-COLOR, Or
: DIRECT-COLOR.

CLX:VISUAL-INFO-COLORMAP-ENTRIES Function
R eturns th e size of th e colormap used by the visual.

Format
CLX:VISUAL-INFO-COLORMAP-ENTR«ES v is u a l-in fo
Argument
visual-info
A CLX:VISUAL-INFO o b je c t.
CLX—186

C L X :V IS U A L -IN FO -C O LO R M A P -E N TR IE S Function

Return Value
An integer.

CLX:VISUAL-INFO-GREEN-MASK Function
R eturns the m ask used for green indexes.

Format
CLX:VISUAL-INFO-GREEN-MASK v is u a l-in fo
Argument
visual-info
A CLX: VISUAL-INFO object.

Return Value
A CLX:p i x e l value.

CLX:VISUAL-INFO-ID Function
R eturns the integer resource-id of the specified visual-info.

Format
CLX:VISUAL-INFO-ID v is u a l-in fo
Argument
visual-info
A CLX:VISUAL-INFO object.

Return Value
A CLX:RESOURCE-ID value.

CLX—187

CLX.VISUAL-INFO-P Function

CLX:VISUAL-INFO-P Function
R eturns tru e i f its argum ent is o f type c l x : v i s u a l - i n f o .

Format
CLX:VISUAL-INFO-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX:VISUAL-INFO-RED-MASK Function
R eturns the m ask used for red indexes.

Format
CLX:VISUAL-INFO-RED-MASK v is u a l-in fo
Argument
visual-info
A CLX: VISUAL-INFO object.

Return Value
A CLX:p i x e l value.

CLX:WARP-POINTER Function
Moves the pointer cursor to the specified location in th e destination window.

Format
CLX:WARP-POINTER d s t d s t-x d s t-y

CLX—188

C LX :W A R P-PO IN TER Function

Arguments
dst
A CLX: window object.

dst-x dst-y
Integer X and Y coordinates of th e cursor’s destination.

Return Value
Unspecified.

CLX:WARP-P0INTER-IF-1NSIDE Function
Moves the pointer cursor to the specified location in the destination window if the
pointer cursor is w ithin the specified rectangle of the source window.
Passing in a zero src-width or src-height is a no-op. If src-width is null, the
current w idth of the source window m inus src-x is used. If src-height is null, the
current height of the source window m inus src-y is used.

Format
CLX:WARP-POINTER-IF-INSIDE d s t d s t-x d s t-y s rc s r c - x s r c - y
&OPTIONAL s rc -w id th s r c - h e ig h t
Arguments
dst
A c l x : window object.

dst-x dst-y
Integer X and Y coordinates of th e cursor’s destination.

src
A c l x : window object.

src-x src-y
Integer X and Y coordinates of th e origin of a rectangle w ithin the source window.

src-width src-height
Integer dimensions of a rectangle w ithin the source window.

Return Value
Unspecified.

CLX—189

C LX :W A R P-PO IN TER -R ELA TIVE Function

CLX:WARP-POINTER-RELATIVE Function
Moves the pointer cursor a specified distance relative to its cu rren t position.

Format
CLX:WARP-POINTER-RELATIVE d is p la y x - o f f y - o f f
Arguments
display
A CLX : DISPLAY object.

x-off y-off
Integer distances (offsets) to move the pointer cursor.

Return Value
Unspecified.

CLX:WARP-POINTER-RELATIVE-IF-INSIDE Function
Moves th e pointer cursor a specified distance relative to its current position if the
pointer cursor is w ithin the specified rectangle of th e source window.
Passing in a zero src-width or src-height is a no-op. If src-width is null, the
cu rre n t w idth of th e source window m inus src-x is used. If src-height is null, the
cu rre n t height of the source window m inus src-y is used.

Format
CLX:WARP-POINTER-RELATIVE-IF-INSIDE x - o f f y - o f f s r c s r c - x s r c - y
&OPTIONAL s r c -w id th s r c - h e ig h t
Arguments
x-off y-off
Integer distances (offsets) to move the pointer cursor.

src
A c l x : w i n d o w object.

src-x src-y
Integer X an d Y coordinates of th e origin of a rectangle in the source window.

CLX-190

C LX :W A R P -PO IN TER -R ELA TIVE-IF-IN SID E Function

src-width src-height
Integer dim ensions of a rectangle in the source window.

Return Value
Unspecified.

CLX:WINDOW Structure
The CLX: w i n d o w stru ctu re contains the visible (size, color) and invisible (event
m asks) characteristics of a window. Not all the components of a window
stru ctu re have a n accessor function: Use th e d r a w a b l e -x , d r a w a b l e -y ,
DRAWABLE-WIDTH, DRAWABLE-HEIGHT, DRAWABLE-DEPTH, DRAWABLE-BORDER-WIDTH,
and d r a w a b l e -r o o t functions to access the corresponding a ttrib u tes of a window.
Use the CLX:q u e r y -t r e e function to find the p a re n t of a window.

Windows have no foreground component. The foreground color of graphics objects
is determ ined by the foreground component of the GContext used w hen they are
draw n.
Constructor Function
CLX:CREATE-WINDOW.

Predicates
CLX:WINDOW-P and CLX:WINDOW-EQUAL.

Accessor Functions
U nless otherw ise noted, the following functions can be used w ith s e t f :
N am e
CLX: WINDOW-ALL-EVENT-MASKS

T y p e D e fin itio n
CLX: MASK32

This fu n c tio n is n o t a v a lid SETF p la c e .
CLX:WINDOW-BACKING-PIXEL

C LX :PIX E L

CLX: WINDOW-BACKING-PLANES

C LX :PIX E L

CLX: WINDOW-BACKING-STORE

(MEMBER :NOT-DSEFUL : WHEN-MAPPED : ALWAYS)

CLX: WINDOW-BIT-GRAVITY

CLX:WIN-GRAVITY

CLX: WINDOW-CLAS S

(MEMBER : INPUT-OUTPUT : INPUT-ONLY)

This fu n c tio n is n o t a v a lid SETF p la c e .
CLX: WINDOW-COLORMAP
CLX: WINDOW-COLORMAP- INSTALLED-P

(OR (MEMBER :COPY) CLX: COLORMAP)
CLX:BOOLEAN

This fu n c tio n is n o t a valid SETF place.
CLX: WINDOW-DISPLAY

CLX:DISPLAY

This function iB not a valid SETF place.
CLX:WINDOW-DO-NOT-PROPAGATE-MASK

CLX:MASK32

CLX—191

CLX:WINDOW Structure

N am e

T y p e D e fin itio n

CLX: WINDOW-EVENT-MASK

CLX:MASK32

CLX: WINDOW-GRAVITY

CLX:W IN-GRAVITY

CLX:WINDOW-ID

CLX:RESOURCE-ID
T h is fu n c tio n is n o t a v a lid SETF p lace .

CLX: WINDOW-MAP- STATE

(MEMBER : UNMAPPED : UNVIEWABLE : VIEWABLE)
T h is fu n c tio n is n o t a v a lid SETF p lace .

CLX:WINDOW-OVERRIDE-REDIRECT

(MEMBER :ON:O FF)

CLX: WINDOW-SAVE-UNDER

(MEMBER : ON :O FF)

CLX: WINDOW-VISUAL

CLX:VISUAL
T h is fu n c tio n is n o t a v a lid SETF p lace .

SETF Forms
T h e f o l lo w in g f u n c t i o n s c a n b e u s e d w i t h s e t f b u t c a n n o t b e c a ll e d :

N am e

D e s c r ip t io n

CLX: WINDOW-BACKGROUND

C h a n g e s th e b a c k g ro u n d co lo r o f t h e sp ecifie d w indow . T h is d o es n o t c h a n g e
t h e w in d o w ’s c o n te n ts u n ti l i t is c le a re d .

(SETF (CLX:WINDOW-BACKGROUND window) color)

window

A CLX:WINDOW object.

color

N IL , :NONE, : PARENT-RELATIVE, a C L X :PIX E L v a lu e , o r a
CLX:PIXMAP object.

I f th e b a c k g ro u n d is : PARENT-RELATIVE, th e o rig in o f t h e w in d o w ’s
b a c k g ro u n d tile a lig n s w ith th e o rig in o f th e p a r e n t’s b a c k g ro u n d tile .
CLX: WINDOW-BORDER

C h a n g e s t h e co lo r o f a w in d o w ’s b o rd e r.

(SETF (CLX:WINDOW-BORDER window ) color )

window

A CLX:WINDOW object.

color

(OR NULL (MEMBER :COPY) CLX: P IX E L CLX:PIXMAP )

U s e a CLX: P IX E L v a lu e o r CLX: PIXMAP o b je c t fo r th e co lo r o f th e w in d o w ’s
b o rd e r, o r :COPY i f t h e b o rd e r w a s co p ied fro m t h e w in d o w ’s p a r e n t w h e n i t
w a s c re a te d .
CLX: WINDOW-CURSOR

C h a n g e s th e c u rs o r u s e d w h e n th e p o in te r is in th e sp e c ifie d w indow .

(SETF (CLX:WINDOW-CURSOR window) cursor)

window

A CLX:WINDOW object.

cursor

A CLX: CURSOR o b je c t o r : NONE o r N IL i f no c u rs o r s h a p e is d e fin e d
fo r th e w indow .

C h a n g in g th e c u r s o r o f a ro o t w in d o w to :NONE r e s to r e s t h e d e f a u lt c u rs o r fo r
t h a t w in d o w a n d a ll it s su b w in d o w s.

CLX-192

CLX:WINDOW Structure

N am e

D e s c r ip t io n

CLX: WINDOW-PRIORITY

Changes the hierarchical position of a window in relation to all windows in
the stack or to a specified sibling.

(SETF (CLX:WINDOW-PRIORITY window [sibling]) mode )

window
sibling

Two CLX:WINDOW objects.

mode

A keyword that names the stacking m ode o f the specified window.
Possible values are:
K eyw ord

R e la tiv e t o All W in d o w s

R e la tiv e to S ib lin g

: ABOVE

Top of stack.

Above sibling.

: BELOW

Bottom o f stack.

Below sibling.

: T O P -IF

If any sibling obscures
window, the server places
window on top o f the
stack.

I f sibling obscures
window, the server
places window on top

I f window obscures any
sibling, the server placeB
window at the bottom o f
the stack.

I f window obscures
sibling, the server
places window at the

If any sibling obscures
window, the server pops
window to the top of the
stack. If window obscures
any other window, the
server pushes window to
the bottom of the stack.

If sibling obscures
window, the server
pops window to the

: BOTTOM-IF

: OPPOSITE

o f the stack.

bottom o f the stack.

top of the stack. If
window obscures
sibling, the server
pushes window to the
bottom of the stack.

Dealiocator Function
C L X : D E S T R O Y -W IN D O W

CLX:WINDOW-ALL-EVENT-MASKS Function
R eturns the inclusive-OR of all event m asks selected on the specified window by
clients.

Format
CLX:WINDOW-ALL-EVENT-MASKS w in d o w

CLX—193

C L X :W IN D O W -A LL-E V E N T-M A S K S Function

Argument
window
A c l x : w in d o w object.

Return Value
A c l x :MASK32 value.

CLX:WINDOW-BACKING-PIXEL Function
Indicates which pixel value to use in planes not covered by the backing-planes
component.
This function can be used w ith s e t f , b u t changing the backing-pixel of a m apped
window m ay have no im m ediate effect.

Format
CLX:WINDOW-BACKING-PIXEL w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A c l x - . p i x e l v a lu e o r n i l i f window u s e s th e d e fa u lt ba ck in g - p ix el o f its parent.

CLX:WINDOW-BACKING-PLANES Function
R eturns the planes of the specified window’s contents th a t are kep t in the backing
store by the server. This function can be used w ith s e t f .

Format
CLX:WINDOW-BACKING-PLANES w in d o w
Argument
window
A c l x : w in d o w o b je c t.

CLX—194

C LX :W IN D O W -B A C K IN G -P L A N E S Function

Return Value
A c l x : p i x e l value or n i l if m aintaining contents is :N O T - u s e f u l .

CLX:WINDOW-BACKING-STORE Function
R eturns the sta tu s of the backing store for the specified window. This function
can be used w ith s e t f .

Format
CLX:WINDOW-BACKING-STORE w in d o w
Argument
window
A C LX : w in d o w object.

Return Value
:N O T - u s e f u l , : w h en - m a p p e d , or

: a l w a y s ; or n i l if no backing store h a s been

defined for window.

CLX:WINDOW-BIT-GRAVITY Function
R eturns th e b it gravity for the specified window, indicating which region of
window is retain ed if it is resized. This function can be used w ith s e t f .

Format
CLX:WINDOW-BIT-GRAVITY w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A C L X : b i t - g r a v it y value or N IL if no b it gravity is defined for window.

CLX—195

C LX :W IN D O W -C LA S S Function

CLX:WlNDOW-CLASS Function
R eturns th e class of th e specified window, th a t is, indicates w hether the window
can display output as well as receive input.

Format
CLX:WINDOW-CLASS w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
: COPY, : INPÜT-OÜTPÜT, o r : INPOT-ONLY.

CLXiWINDOW-COLORMAP Function
R eturns th e colormap th a t reflects the “tru e ” colors of the specified window.
This function can be used w ith SETF. The colormap m u st have th e same visual
type as the window or a n erro r occurs. If : c o p y is specified, th e colormap is
copied from the parent, b u t th e window m u st have th e sam e visual type as the
paren t and the p a re n t m u st not have a colormap of : n o n e or an erro r occurs.
Changing the colormap of a visible window m ay have no im m ediate effect on the
screen; see C L X : i n s t a l l - c o l o r m a p . Also, changes to the p a re n t’s colormap do not
affect the child, even if the window’s colormap h as previously been set to :COPY.

Format
CLX:WINDOW-COLORMAP w in d o w
Argument
window
A C LX : w in d o w object.

Return Value
A CLX : c o l o r m a p object, or : COPY if window's colormap was copied from its paren t
when window was created.

CLX—196

C LX:W IN D O W -C O LO R M A P -IN S TA LLE D -P Function

CLX:WINDOW-COLORMAP-INSTALLED-P Function
R eturns T if th e specified window has a colormap installed.

Format
CLX:WINDOW-COLORMAP-INSTALLED-P w in d o w
Argument
window
A CLX: w indow object.

Return Value
A CLX:b o o l e a n value.

CLX:WINDOW-DISPLAY Function
R eturns the display on which the specified window appears when it is m apped.
This function is not a valid SETF place.

Format
CLXiWINDOW-DISPLAY w in d o w
A rgum ent

window
A c l x : w indow object.

Return Value
A CLX:DISPLAY object.

CLX—197

C LX :W IN D O W -D O -N O T-PR O P A G A TE -M A SK Function

CLX:WINDOW-DO-NOT-PROPAGATE-MASK Function
R eturns the events th a t should not be propagated to ancestor windows w hen
no client h as selected the event type in the specified window. There is only one
do-not-propagate m ask per window, not one per client for each window. This
function can be used w ith s e t f .

Format
CLX:WINDOW-DO-NOT-PROPAGATE-MASK w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
An integer or C L X : d e v i c e - e v e n t - m a sk value; or n i l if no do-not-propagate m ask
h a s been defined for the specified window.

CLX:WINDOW-EQUAL Function
R eturns tru e i f its two argum ents are the sam e c l x : w in d o w object.

Form at

CLX:WINDOW-EQUAL o b je c t-1 o b je c t - 2
Arguments
object-1 object-2
Any two LISP objects.

Return Value
A c l x : b o o l e a n value.

CLX—198

C L X :W IN D O W -E V E N T-M A S K Function

CLX:WINDOW-EVENT-MASK Function
R eturns the events selected by th e client in th e specified window. This function
can be used w ith s e t f .

Format
CLX:WINDOW-EVENT-MASK w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A c l x : e v e n t - m a sk value or n i l if no event m ask is defined for window.

C LX:Wl N DOW-G RAVIT Y Function
Indicates how the specified window is repositioned after its p a re n t is resized.
This function can be used w ith s e t f .

Format
CLX:WINDOW-GRAVITY w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A c l x : w i n - g r a v it y value or n i l if no window gravity is defined for window.

CLX—199

C LX :W IN D O W -ID Function

CLX:WINDOW-ID Function
R eturns th e resource-id of the specified window. This function is not a valid s e t f
place.

Format
CLX:WINDOW-ID w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A CLX:RESOURCE-ID value.

C LX:Wl N DOW-M AP-STATE Function
R eturns th e m ap state of the specified window. This function is not a valid s e t f
place.

Format
CLX:WINDOW-MAP-STATE window
Argument
window
A c l x : w in d o w o b je c t .

Return Value
: UNMAPPED, : UNVIEWABLE, o r : VIEWABLE.

CLX—200

C L X :W IN D O W -O V E R R ID E -R E D IR E C T Function

CLX:WINDOW-OVERRIDE-REDIRECT Function
Indicates w hether m ap and configure requests on the specified window should
override a SubstructureR edirect protocol request on its parent. Typically, this
function is used to tell th e window m anager not to tam p er w ith the window. This
function can be used w ith s e t f .

Format
CLX:WINDOW-OVERRIDE-REDIRECT w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
: ON o r :O FF.

CLX:WINDOW-P Function
R eturns T if th e argum ent is a c l x : w in d o w object.

Format
CLX:WINDOW-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX:BOOLEAN value.

CLX-201

C LX :W IN D O W -SA V E-U N D ER Function

CLX:WINDOW-SAVE-UNDER Function
Indicates w hether th e server saves the contents of windows obscured by the
specified window. This function can be used w ith s e t f .

Format
CLX:WINDOW-SAVE-UNDER w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
: ON o r :O FF.

CLX:WINDOW-VISUAL Function
R eturns a pointer to th e CLX: v i s u a l - i n f o object associated w ith the specified
window.

Format
CLX:WINDOW-VISUAL window
Argument
window
A C LX : w in d o w object.

Return Value
A CLX: v i s u a l v a l u e o r :COPY i f t h e v i s u a l in f o w a s c o p ie d f r o m t h e p a r e n t w h e n
window w a s c r e a t e d .

CLX—202

C L X :W lN -G R A VITY Type Specifier

CLX:WlN-G RAVITY Type Specifier
G ravity is the direction in which the children or contents of a window move
w hen it is resized. Objects of type c l x : w in - g r a v it y are retu rn ed by the
c l x : w in d o w - b i t - g r a v it y and CLX: w in d o w - g r a v it y functions and can be passed
to s e t f forms of these functions.

Representation
(MEMBER :FORGET :STATIC :CENTER :NORTH :NORTH-EAST :EAST :SOUTH-EAST
:SOUTH :SOUTH-WEST :WEST :NORTH-WEST)

CLX:WITH-DISPLAY Macro
This macro is for use in a m ultiprocess environm ent. I t provides exclusive access
to the local display object for m ultiple request generation. It need not provide
im m ediate exclusive access for replies; th a t is, if an o th er process is w aiting for a
reply (while not in a c l x :W IT H - d i s p l a y ), synchronization need not (but can) occur
immediately.
N ested uses of this m acro w ork correctly. This m acro does not prevent concurrent
event processing; see w i t h - e v e n t - q u e u e .

Format
CLX:WITH-DISPLAY d is p la y & BODY b o d y
Arguments
display
A CLX:DISPLAY object.

body
LISP forms.

Return Value
Unspecified.

CLX-203

C LX :W ITH -E V E N T-Q U E U E M acro

CLX:WITH-EVENT-QUEUE Macro
G rants exclusive access to event queue.

Format
CLX:WITH-EVENT-QUEUE d is p la y & BODY b o d y
Arguments
display
A CLX : DISPLAY object.

body
LISP form s to be executed while th e client h a s exclusive access to the event
queue.

Return Value
Unspecified.

CLX:WITH-GCONTEXT Macro
Changes GCONTEXT components w ithin th e dynam ic scope of the body (that
is, indefinite scope and dynamic extent). The body is not surrounded by a
w i t h - d i s p l a y . If : c a c h e - p is n i l or some component states are unknown,
this im plem ents save/restore by creating a tem porary GContext and doing
c l x : c o p y - g c o n t e x t —c o m p o n e n t s to and from it.

CLX—204

C LX :W IT H -G C O N T E X T M acro

Format
CLX:WITH-GCONTEXT g c o n te x t
&KEY :FUNCTION :PLANE-MASK :FOREGROUND
:BACKGROUND :LINE-WIDTH :LINE-STYLE
:CAP-STYLE :JOIN-STYLE :FILL-STYLE
:FILL-RULE :ARC-MODE :TILE :STIPPLE
:TS-X :TS-Y :FONT :SUBWINDOW-MODE
EXPOSURES :CLIP-X :CLIP-Y :CLIP-MASK
:CLIP-ORDERING :DASHES :DASH-OFFSET
&BODY b o d y
Arguments
gcontext
A CLX : GCONTEXT object.
FUNCTION
A CLX: l o g I c a l - o p value.
:PLANE-MASK
Integer o r n i l .
:FOREGROUND BACKGROUND
Two C LX : p i x e l values or n i l .
:LINE-WIDTH
Integer or n i l .
:LINE-STYLE
N IL o r : SO LID, : DASH, Or : DOUBLE-DASH.

:CAP-STYLE
N IL o r o n e o f :N O T-LA ST, : BUTT, : ROUND, Or P R O JE C T IN G .

JOIN-STYLE
N IL or one of : MITER, :ROUND, or : BEVEL.

:FILL-STYLE
N IL o r o n e o f : SOLID, : T ILED , : OPAQUE-STIPPLED, o r : ST IPPL ED .

:FILL-RULE
or eith er : e v e n - o d d or : w in d i n g .

n il

:ARC-MODE
or eith er : ch o r d or : p i e - s l i c e .

n il

:TILE :STIPPLE
A c l x : p ix m a p object.
:TS-X :TS-Y
Integers.

CLX-205

CLXiWITH-GCONTEXT Macro
:FONT
A CLX : FONT object.
:SUBWINDOW-MODE
n il

o r e i t h e r :C l i p - b y - c h il d r e n o r : i n c l u d e - i n f e r i o r s .

:EXPOSURES
N IL o r e i t h e r :ON o r :O FF.

:CLIP-X CLIP-Y
Integers.
:CLIP-MASK
N IL o r : n o n e , o r e i t h e r a c l x : P ix m a p o r a c l x :R E C T - s e q .

:CLIP-ORDERING
N IL o r o n e o f : UNSORTED, :Y-SORTED, : YX-SORTED, Or : YX-BANDED.

:DASHES
An integer or a sequence of integers.
:DASH-OFFSET
An integer.

body
LISP forms.

Return Value
Unspecified.

CLX:WITH-SERVER-GRABBED Macro
Invokes C L X : g r a b - s e r v e r before executing th e body, and C LX : u n g r a b - s e r v e r
afterw ard. The client therefore h a s exclusive possession of the server, on the
specified display, while the body is executed.
The body is not surrounded by a n im plicit c l x :Wi t h - d i s p l a y .

Format
CLX:WITH-SERVER-GRABBED d is p la y & BODY b o d y
Arguments
display
A CLX:DISPLAY object.

body
LISP forms to be executed while the client h a s possession of the server.

CLX—206

C LX :W ITH -S E R V E R -G R A B B E D M acro

Return Value
Unspecified.

CLX:WITH-STATE Macro
B atches m ultiple window queries into a single protocol GetW indow Attributes
or GetGeom etry request; and m ultiple window settings into a single protocol
ChangeW indow Attributes or ConfigureWindow request.
Table CLX—1 Hsts the accessor functions and s e t f places batched by the
c l x : w it h - s t a t e macro. W ithin the indefinite scope of th e body, the first call
w ithin a n Accessor Group on the specified draw able causes the complete results
of the protocol request to be retained, and retu rn ed in any subsequent accessor
calls. Calls w ithin a SETF Group are delayed, and are executed in a single request
on exit from the body. In addition, if a call on a function w ithin an Accessor
Group follows a call on a function in th e corresponding s e t f Group, then all
delayed s e t f s for th a t group a re executed; any retain ed accessor inform ation for
th a t group is discarded; the corresponding protocol request is (re issu e d ; and the
resu lts are (again) retained and retu rn ed in any subsequent accessor calls.
Table CLX-1: WITH-STATE Accessor and SETF Groups
A c c e s s o r G r o u p A (for G etW in d ow A ttrib u tes)
CLX:WINDOW-ALL-EVENT-MASKS
CLX:WINDOW-BACKING-PIXEL
CLX:WINDOW-BACKING-PLANES
CLX:WINDOW-BACKING-STORE
CLX:WINDOW-BIT-GRAVITY
CLX:WINDOW-CLASS
CLX:WINDOW-COLORMAP
CLX:WINDOW-COLORMAP-INSTALLED-P

CLX: WINDOW-DO-NOT-PROPAGATE-MASK
CLX: WINDOW-EVENT-MASK
CLX: WINDOW-GRAVITY
CLX: WINDOW-MAP-STATE
CLX: WINDOW-OVERRIDE-REDIRECT
CLX: WINDOW-SAVE-UNDER
CLX: WINDOW-VISUAL

S E T F G r o u p A (for C h a n g e W in d o w A ttrib u te s)
CLX: WINDOW-BACKING-PIXEL
CLX: WINDOW-BACKING-PLANES
CLX: WINDOW-BACKING-STORE
CLX:WINDOW-BIT-GRAVITY
CLX: WINDOW-COLORMAP
CLX: WINDOW-CURSOR

CLX: WINDOW-DO-NOT-PROPAGATE-MASK
CLX: WINDOW-EVENT-MASK
CLX: WINDOW-GRAVITY
CLX: WINDOW-OVERRIDE-REDIRECT
CLX: WINDOW-SAVE-UNDER

A c c e s s o r G r o u p G (for G e tG eo m etry )
CLX: DRAWABLE-BORDER-WIDTH
CLX: DRAWABLE-DEPTH
CLX: DRAWABLE-HEIGHT
CLX: DRAWABLE-ROOT

CLX: DRAWABLE-WIDTH
CLX: DRAWABLE-X
CLX:DRAWABLE-Y

(continued on next page)

CLX—207

CLX:W ITH-STATE M acro

Table CLX-1 (Cont.):

WITH-STATE Accessor and SETF Groups
S E T F G r o u p G (for C o n fig u r e W indow )

CLX: DRAWABLE-BORDER-WIDTH
CLX: DRAWABLE-HEIGHT
CLX: DRAWABLE-WIDTH

CLX: DRAWABLE-X
CLX:DRAWABLE-Y
CLX: WINDOW-PRIORITY

The body i s n o t s u r r o u n d e d b y a c l x : W I T H - d i s p l a y .

Format
CLX:WITH-STATE d r a w a b le &BODY b o d y
Arguments
drawable
A CLX:DRAWABLE object.

body
LISP forms.

Return Value
Unspecified.

CLX:WM-HINTS Function
R e tu rn s th e w in d o w m a n a g e r h in ts o f th e sp e cifie d w indow .

Format
CLX:WM-HINTS w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A CLX : WM-HINTS object.

CLX-208

C LX :W M -H IN TS S tructure

CLX:WM-HINTS Structure
The c l x : wm- h i n t s stru ctu re contains th e client’s h in ts to the window m anager as
to a window’s sta tu s and its icon. The window m anager is not obliged to follow
th e client’s hints.
Constructor Function
CLX:MAKE-WM-HINTS

Accessor Functions
All of the following functions a re valid SETF places:
N am e

T y p e D e fin itio n

CLX:W M-HINTS-FLAGS

CARD32

CLX: WM-HINTS-ICON-MASK

(OR NULL CLX:PIXM AP)

CLX: W M -HINTS-ICON-PIXM AP

(OR NULL CLX:PIXM AP)

CLX:WM-HINTS-ICON-WINDOW

(OR NULL CLX:WINDOW)

CLX :W M -H INTS-ICO N-X

(OR NULL CARD16)

CLX :W M -H INTS-ICO N-Y

(OR NULL CARD16)

CLX: W M -H IN T S -IN IT IA L -S T A T E

(OR NULL (MEMBER :DONT-CARE : NORMAL : ZOOM
: ICO NIC : IN A C T IV E ))

CLX:W M -HINTS-INPUT

(OR NULL (MEMBER :O FF :O N ))

CLX: WM-HINTS-WINDOW-GROUP

(OR NULL CLX: RE SOURCE-ID)

Deallocator Function
Instances of t h e c l x : wm- h i n t s stru ctu re are subject to garbage collection.

CLX:WM-HINTS-FLAGS Function
Indicates which com ponents of a c l x : wm- h i n t s object have been defined. This
function can be used w ith s e t f .

Format
CLX:WM-HINTS-FLAGS h in ts
Argument
hints
A CLX:WM-HINTS object.

CLX—209

C L X :W M -H IN T S -F LA G S Function

Return Value
An integer.

CLX:WM-HINTS-ICON-MASK Function
Indicates which pixels of th e icon pixm ap are used to create th e icon associated
w ith a window. This function can be used w ith SETF.

Format
CLX:WM-HINTS-ICON-MASK h in ts
Argument
hints
A CLX : WM-HINTS object.

Return Value
A C L X : p i x m a p object.

CLX:WM-HINTS-ICON-PIXMAP Function
R eturns the pixmap used to create th e icon associated w ith a window. This
function can be used w ith s e t f .

Format
CLX:WM-HINTS-ICON-PIXMAP h in ts
Argument
hints
A CLX:WM-HINTS o b je c t.

Return Value
A c l x : p i x m a p object.

CLX—210

C L X :W M -H IN TS -IC O N -W IN D O W Function

CLX:WM-HlNTS-ICON-WINDOW Function
R eturns the window used for th e icon associated w ith a window. This function
can be used w ith s e t f .

Format
CLX:WM-HINTS-ICON-WINDOW h in ts
Argument
hints
A CLX : WM-HINTS object.

Return Value
A c l x : w in d o w object.

CLX:WM-HINTS-ICON-X Function
R eturns th e X coordinate of the icon associated w ith a window. This function can
be used w ith SETF.

Format
CLX:WM-HINTS-ICON-X h in ts
Argument
hints
A CLX:WM-HINTS object.

Return Value
An integer.

CLX—211

C LX :W M -H IN TS -IC O N -Y Function

CLX.WM-HINTS-ICON-Y Function
R eturns the Y coordinate of the icon associated w ith a window. This function can
be used w ith s e t f .

Format
CLX.WM-HINTS-ICON-Y h in ts
Argument
hints
A CLX : WM-HINTS object.

Return Value
An integer.

CLX:WM-HINTS-INITIAL-STATE Function
Indicates how the window should appear in its in itial state. This function can be
used w ith s e t f .

Format
CLX:W M -HINTS-INITIAL-STATE hints

Argument
hints
A CLX:WM-HINTS object.

Return Value
A keyword:

CLX—212

: DONT-CAR.E

Client is not interested in the initial state.

: NORMAL

Initial state used m ost often.

: ZOOM

Window starts zoomed.

: ICONIC

Window starts as an icon.

: INACTIVE

Window is seldom used.

C LX :W M -H IN T S -IN P U T Function

CLX:WM-HINTS-INPUT Function
Indicates w hether th e client relies on the window m anager to get keyboard input.
This function can be used w ith s e t f .

Format
CLX:WM-HINTS-INPUT h in ts
Argument
hints
A CLX:WM-HINTS object.

Return Value
R eturns : ON if th e client relies on the window m anager to get keyboard input,
: o f f if it does not.

CLX:WM-HINTS-P Function
R eturns tru e if its argum ent is a c l x : wm- h i n t s object.

Format
CLX:WM-HINTS-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX: BOOLEAN object.

CLX-213

C LX :W M -H IN T S -W IN D O W -G R O U P Function

CLX:WM-HINTS-WINDOW-GROUP Function
Indicates w hether a window belongs to a group. This function can be used w ith
SETF.

Format
CLX:WM-HINTS-WINDOW-GROUP h in ts
Argument
hints
A CLX:WM-HINTS object.

Return Value
’

R eturns th e CLX: r e s o u r c e - i d of the group to which a window belongs.

CLX:WM-ICON-NAME Function
R eturns th e title of the icon associated w ith the specified window. This function
can b e used w ith s e t f .

Format
CLX:WM-ICON-NAME w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A string containing the nam e in the window’s icon.

CLX—214

C L X :W M -N A M E Function

CLX:WM-NAME Function
R eturns th e title of the specified window. This function can be used w ith SETF.

Format
CLX:WM-NAME w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A strin g containing the nam e in the window’s title bar.

CLX:WM-NORMAL-HINTS Function
R eturns the suggested values for the size and location for a window in th e norm al
state.

Format
CLX:WM-NORMAL-HINTS w in d o w
Argument
window
A c l x : w in d o w object.

Return Value
A C LX :W M -SIZE-H IN TS object.

CLX-215

CLX:WM-SIZE-HINTS Structure

CLX:WM-S1ZE-HINTS Structure
The c l x : wm- s i z e - h i n t s stru ctu re contains the client’s suggestions to the window
m anager as to how a window should be sized. The window m anager is not
guaranteed to follow th e client’s suggestions.
Constructor Function
CLX: M AKE-W M -SIZE-HINTS

Accessor Functions
All of the following functions are valid s e t f places. A fter setting values
in a C LX : wm- s i z e - h i n t s object you can use it as th e value to s e t f the
CLX:WM-NORMAL-HINTS Or CLX:WM-ZOOM-HINTS function.
N am e

T y p e D e fin itio n

CLX:WM-SIZE-HINTS-HEIGHT

(OR NULL CARD16)

CLX:WM-SIZE-HINTS-HEIGHT-INC

(OR NULL CARD16)

CLX:WM-SIZE-HINTS-MAX-ASPECT

(OR NULL NUMBER)

CLX:WM-SIZE-HINTS-MAX-HEIGHT

(OR NULL CARD1 6 )

CLX:WM-SIZE-HINTS-MAX-WIDTH

(OR NULL CARD1 6 )

CLX:WM-SIZE-HINTS-MIN-ASPECT

(OR NULL NUMBER)

CLX:WM-SIZE-HINTS-MIN-HEIGHT

(OR NULL CARD16)

CLX:WM-SIZE-HINTS-MIN-WIDTH

(OR NULL CARD16)

CLX:WM-SIZE-HINTS-USER-SPECIFIED-POSITION-P

CLX:BOOLEAN

CLX:WM-SIZE-HINTS-USER-SPECIFIED-SIZE-P

CLX:BOOLEAN

CLX:WM-SIZE-HINTS-WIDTH

(OR NULL CARD16)

CLX:WM-SIZE-HINTS-WIDTH-INC

(OR NULL CARD1 6 )

CLX:WM-SIZE-HINTS-X

(OR NULL INTEGER)

CLX:WM-SIZE-HINTS-Y

(OR NULL INTEGER)

Deallocator Function
Instances of th e c l x :WM-s i z e -h i n t s stru ctu re are subject to garbage collection.

CLX:WM-SIZE-HINTS-HEIGHT Function
Indicates th e w idth of th e window. This function can be used w ith SETF.

Format
CLX.WM-SIZE-HINTS-HEIGHT s iz e -h in ts

CLX—216

C LX :W M -S IZ E -H IN T S -H E IG H T Function

Argument
size-hints
A C LX :W M -SIZE-H IN TS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-HEIGHT-INC Function
Indicates th e increm ent by which the height of a window m ay be resized. This
function can be used w ith SETF.

Format
CLX:WM-SIZE-HINTS-HEIGHT-INC s iz e -h in ts
Argument
size-hints
A CLX : WM- S I Z E -HINTS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-MAX-ASPECT Function
Indicates the largest aspect ratio of a window. This function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MAX-ASPECT s iz e -h in ts
Argument
size-hints
A CLX:W M -SIZE—HINTS object.

CLX-217

C L X :W M -S IZ E -H IN T S -M A X -A S P E C T Function

Return Value
A num ber.

CLX:WM-SIZE-HINTS-MAX-HEIGHT Function
Indicates the largest useful height of a window. This function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MAX-HEIGHT s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-MAX-WIDTH Function
Indicates th e largest useful w idth of a window. This function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MAX-WIDTH s iz e -h in ts
Argument
size-hints
A CLX : WM-SIZE-HINTS object.

Return Value
An integer.

CLX—218

CLX:WM-SIZE-HINTS-MIN-ASPECT Function

CLX:WM-SIZE-HINTS-MIN-ASPECT Function
Indicates th e sm allest aspect ratio of a window. T his function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MIN-ASPECT s iz e -h in ts
Argument
size-hints
A C L X : WM-SIZE-HINTS object.

Return Value
A num ber.

CLX:WM-SIZE-HINTS-MIN-HEIGHT Function
Indicates th e sm allest useful height of a window. This function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MIN-HEIGHT s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
An integer.

CLX-219

C LX :W M -S IZ E -H IN T S -M IN -W ID T H Function

CLX:WM-SIZE-HINTS-MIN-WIDTH Function
Indicates th e sm allest useful w idth of a window. This function can be used w ith
SETF.

Format
CLX:WM-SIZE-HINTS-MIN-WIDTH s iz e -h in t s
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-P Function
R eturns tru e if its argum ent is a CLX:WM- s i z e -h i n t s object.

Format
CLX:WM-SIZE-HINTS-P o b je c t
Argument
object
Any LISP object.

Return Value
A CLX: BOOLEAN object.

CLX-220

C LX :W M -S IZE -H IN TS -U S E R -S P E C IFIE D -P O S ITIO N -P Function

CLX:WM-SIZE-HINTS-USER-SPECIFIED-POSITION-P
Function
Indicates w hether the user w ants to move the window to the X and Y location
specified in size-hints. This function can be used w ith s e t f .

Format
CLX:WM-SIZE-HINTS-USER-SPECIFIED-POSITION-P s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
T if the user has moved the window, n i l if not.

CLX:WM-SIZE-HINTS-USER-SPECIFIED-SIZE-P
Function
Indicates w hether the u ser has resized the window. This function can be used
w ith SETF.

Format
CLX:WM-SIZE-HINTS-USER-SPECIFIED-SIZE-P s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
T if the user has resized the window, n i l if not.

CLX-221

C LX :W M -S IZE -H IN TS -W ID TH Function

CLX:WM-SIZE-HINTS-WIDTH Function
Indicates the w idth of a window. This function can be used w ith s e t f .

Format
CLX:WM-SIZE-HINTS-WIDTH s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-WIDTH-INC Function
Indicates the increm ent by which the w idth of a window m ay be resized. This
function can be used w ith s e t f .

Format
CLX:WM-SIZE-HINTS-WIDTH-INC s iz e -h in ts
Argument
size-hints
A CLX : WM-SIZE-HINTS object.

Return Value
An integer.

CLX—222

C L X :W M -S IZE -H IN TS -X Function

CLX:WM-SIZE-HINTS-X Function
Indicates the X coordinate of th e window’s top-left comer. This function can be
used w ith SETF.

Format
CLX:WM-SIZE-HINTS-X s iz e -h in ts
Argument
size-hints
A CLX:WM-SIZE-HINTS object.

Return Value
An integer.

CLX:WM-SIZE-HINTS-Y Function
Indicates the Y coordinate of th e window’s top-left comer. This function can be
used w ith s e t f .

Format
CLX:WM-SIZE-HINTS-Y s iz e -h in ts
Argument
size-hints
A C L X :WM-SIZE-HINTS object.

Return Value
An integer.

CLX-223

C LX :W M -ZO O M -H IN TS Function

CLX:WM-ZOOM-HINTS Function
R eturns the suggested size and location of a window in the zoomed state. This
function can be used w ith s e t f .

Format
CLX:WM-ZOOM-HINTS w in d o w
Argument
window
A c l x :w i n d o w object.

Return Value
A CLX:WM-SIZE-HINTS object.

CLX:WRITE-BITMAP-FILE Function
W rites an image or a pixm ap to a C include file in stan d ard X l l form at. The
name argum ent is used for variable prefixes and defaults to "i m a g e -".

Format
CLX:WRITE-BITMAP-FILE p a t h n a m e im a g e
&OPTIONAL n a m e
&KEY :PIXMAP-P :WIDTH rHEIGHT :X-HOT :Y-HOT
:DRAWABLE
Arguments
pathname
The pathnam e of the file to w rite.

image
A CLX: IMAGE object.

name
A CLX:STRINGABLE value.
:PIXMAP-P

A c l x : b o o l ea n value th a t specifies w h eth er th e image argum ent is a pixmap or
an integer.

CLX—224

CLX:WRITE-BITMAP-FILE Function
:WIDTH .HEIGHT
Integers th a t specify th e dim ensions of image.
:X-HOT :Y-HOT
Integers th a t specify the X and Y coordinates of a cursor’s hot spot. The defaults
are 0.

:DRAWABLE
A c l x :d r a w a b l e object th a t provides inform ation about th e screen and display.

Return Value
Unspecified.

CLX:XATOM Type Specifier
Atoms are nam es of properties. Objects of type c l x :x a t o m can be passed to
th e CLX:CHANGE-PROPERTY, CLX:GET-PROPERTY, C LX:LIST-PROPERTIES, and
CLX:ROTATE-PROPERTIES functions.

Representation
(OR STRING SYMBOL)

CLX-225

Appendix A

DECwindows Constants

VAX LISP defines the DECwindows constants listed in Table A-1.

Table A -1: DECwindows C onstants Defined by VAX LISP
N am e

V alue

A lig n m e n ts
D W T :A L I G N M E N T - C E N T E R

DWT:ALIGNMENT-BEGINNING

D W T :A L I G N M E N T - E N D

L abel T ype
DWT:TEXT

DWT:PIXMAP

D W T :T E X T 1 6

D W T :T E X T - W I T H - A C C E L E R A T O R

D W T :T E X T 1 6- W I T H - A C C E L E R A T O R

T o g g le B u tto n S h a p e s
D W T :R E C T A N G U L A R

D W T :O V A L

O r ie n ta tio n s
D W T :O R I E N T A T I O N - V E R T I C A L

D W T :O R I E N T A T I O N - H O R I Z O N T A L

D ia lo g S ty les
DWT:MODAL

DWT:MODELESS

D W T :W O R K A R E A

(continued on next page)

DECwindows Constants

A-1

Table A—1 (Cont.):

DECwindows Constants Defined by VAX LISP

N am e

V alue

M en u S ty les

DWT:MENU-BAR-TYPE

DWT:MENU-WORK-AREA

DWT:MENU-PULL-DOWN

DWT-.MENU-POPUP

DWT:MENU-OPTION

M en u - P a ck in g S ty les

DWT:MENU-PACKING-TIGHT

DWT:MENU-PACKING-COLUMN

DWT:MENU-PACKING-NONE

F ile S e le c t io n

DWT:VMS

DWT:UNIX

DWT:MSDOS

C a u tio n B o x

DWT:YES-BUTTON

DWT:NO-BUTTON

DWT:CANCEL-BUTTON

F o n t U n it P o s it io n in g

DWT:FONT-UNITS

DWT:PIXEL-UNITS

C u t a n d P a s te

DWT:CLIPBOARD-SUCCESS

DWT:CLIPBOARD-TRUNCATE

DWT:CLIPBOARD-FAIL

DWT:CLIPBOARD-LOCKED

DWT:CLIPBOARD-NON-DATA

(continued on next page)

A-2 DECwindows Constants

Table A-1 (Cent.):

DECwindows Constants Defined by VAX LISP

N am e

V alue

A ll C o n v e r s io n S tr in g s
DWT:C-NULL

DW T:C-FALSE

DWT: C-TRUE

DWT:NO-CALLBACKLIST

DWT:NO-CALLBACKS

DWT:YES-CALLBACKS

DWT:GEOMETRY-YES

DWT: GEOME TRY-NO

DWT : GEOME TRY-ALMO ST

E ven t M anagem ent
DWT: C-PASS

DWT: C-IGNORE

DWT:C-REMAP

DWT :C-IS-SE N SIT IV E

DWT: C-NOT-SENSITIVE

E v e n t- G a th e rin g R o u tin e s
D W T :C-INPUT-NONE-MASK

D W T :C-INPUT-READ-MASK

DWT:C-INPUT-WRITE-MASK

D W T :C-INPUT-EXCEPT-MASK

G eom etry M an agem en t
D W T :CSM-DONT-CHANGE

P o p - u p H a n d lin g
DWT: GRAB-NONE

DWT:GRAB-NONEXCLUSIVE

DWT:GRAB-EXCLUSIVE

DWT:OVERRIDE

DWT:AUGMENT

Table A-2:

DRM Constants

N am e

V alue

D e s c r ip t io n

DWT:DRM-SUCCESS

1
3

Operation completed without error

D W T :DRM-CREATENEW

New {file} created
(continued on next page)

DECwindows Constants

A-3

Table A-2 (Cont.):

DRM Constants

N am e

V alue

D e s c r ip t io n

DWT:DRM-INDEXRE TRY

Retry on entering index required

DWT:DRM-INDEXGT

Index orders greater-than entry

D W T :DRM-INDEXLT

Index orders less-than entry

D W T :DRM-FAILURE

Operation not successful

DWT:DRM-NOTFOÜND

{File, Record, etc.} not found

DWT:DRM-EXISTS

{File, Record, etc.} does not exist

DWT:DRM-NULGROUP

Null group field

DWT:DRM-NULTYPE

Null type field

D W T :DRM-WRONGGROUP

Wrong group field

DWT:DRM-WRONGTYPE

Wrong type field

DWT:DRM-OUTOFRANGE

Out o f range

DWT:DRM-BADRECORD

Record number w rong type

D W T :DRM-NULLDATA

No data for entry

DWT:DRM-BADDATAINDEX

Data index in RID out o f range

DWT:DRM-BADORDER

Bad ordering specifier

DWT:DRM-BADCONTEXT

Invalid DRM context

D W T :DRM-NOTVALID

Validation failure

D W T :DRM-BADBTREE

GT/LT pointer error in BTree

D W T :DRM-BADWIDGETREC

Validation failure on w idget record

D W T :DRM-BADCLASSTYPE

Class type not a valid DRMwc...
value

DWT:DRM-NOCLASSNAME

U ser class name is null

DWT:DRM-TOOMANY

Too many entries requested in
some list

D W T :DRM-BADIFMODULE

Invalid interface module

D W T :DRM-NULLDES C

Arglist or children descriptor null

D W T :DRM-OUTOFBOUNDS

Argument index out o f arglist
bounds

DWT:DRM-BADCOMPRESS

Invalid com pression code

DWT:DRM-BADARGTYPE

Invalid type, not in RGMrType...

DWT:DRM-NOTIMP

Not yet im plem ented

D W T :DRM-NULLINDEX

Empty index string

DWT:DRM-BADKEYTYPE

Key m ust be DRM rlndex or
DRMrRID

D W T :DRM-BADCALLBACK

Invalid callback descriptor

D W T :DRM-NULLROUTINE

Empty callback routine name
string

DWT:DRM-VECTOOBIG

Too many elem ents in vector

DWT:DRM-BADHIERARCHY

Invalid DRM file hierarchy

D W T :DRM-BADCLASSCODE

Class code not found in DRMwc...

(continued on next page)

A-4

DECwindows Constants

Table A-2 (Cont.):

DRM Constants

N am e

V alue

D e s c r ip t io n

D W T :DRM-BADMSGTYPE

M essage type not in RGMmt...

D W T :DRM-BADMESSAGE

M essage record invalid

D W T :DRM-OPEN-PARAM-LEN

Length o f OPEN-PARAM structure

D W T :DRM-OPEN-PARAM-VERSION

Current version of this record is 1

Table A-3:

Callback Reasons

N am e

V alue

D W T :CRUNIT—INC

D W T :CRUNIT-DEC

D W T :CRPAGE-INC

D W T :CRPAGE-DEC

D W T :CRSCROLL-START

D W T :CRDRAG

D W T :CRSCROLL-END

D W T :CRTO-TOP

D W T :CRTO-BOTTOM

D W T :CRCANCEL

DWT:CRACTIVATE

D W T :CRARM

DWT:CRDISARM

D W T :CRVALUE-CHANGE

D W T :CRNO

D W T :CRTO-POSITION

D W T :CRMAP

D W T :CRUNMAP

D W T :CRPULL-DOWN

D W T :CFOCUS

DWT:SINGLE

D W T :SINGLE-CONFIRM

D W T :EXTEND

DWT:EXTEND-CONFIRM

D W T :CRCOMMAND-ENTERED

D W T :CRCREATE

D W T :CRHELP-REQUESTED

D W T :CRHELP

D W T :CRSELECTION

D W T :CRCLIPBOARD-DATA-REQUEST

D W T :CRCLIPBOARD-DATA-DELETE

(continued on next page)

DECwindows Constants A-5

Table A—3 (Cont.):

Callback Reasons

N am e

V alue

D W T :CRYES

D W T :CREXPOSE

A-6 DECwindows Constants

Appendix B

CLX to X II Mappings

The following tables show the m appings betw een CLX functions and X l l
requests. Table B—1 lists the X l l protocol requests in alphabetical order on the
left, w ith the corresponding CLX function, macro, or SETF form on the right.
Table B—2 lists the CLX functions and m acros in alphabetical order on the left,
w ith the corresponding X l l request, if any, on th e right. The Xlib functions th a t
m atch th e protocol requests are in the m iddle column in both tables. Due to
space lim itations, th e package prefix c l x : is not shown in these tables.

CLX to X ll Mappings

B-1

Table B-1:

Mapping X II Requests to CLX Functions

P ro to co l R eq u est

X lib F u n ction (s)

CL X F u n ction (s) o r E q u iv a le n t

AllocColor

XAllocColor

ALLOC-COLOR

AllocColorCells

XAllocColorCells

ALLOC-COLOR-CELLS

AllocColorPlanes

XAllocColorPlanes

ALLOC-COLOR-PLANES

AllocNam edColor

XAllocNamedColor

ALLOC-COLOR

AllowEvents

XAllowEvents

ALLOW-EVENTS

Bell

XBell

BELL

ChangeActivePointerGrab XChangeActivePointerGrab
ChangeGC

CHANGE-ACTIVE-POINTER-GRAB

X ChangeGC
XSetArcM ode
XSetB ackground
XSetClipM ask
X SetClipOrigin

XSetGraphicsExposures
XSetFillRule
XSetFillStyle
XSetFont
XSetForeground
XSetFunction
XSetLineAttributes
XSetPlaneM ask
X SetState
XSetStipple
XSetSubwindowM ode
XSetTile
X SetTSO rigin

(setf (gcontext-arc-mode gc) mode)
(setf (gcontext-background gc) integer)
(sett (gcontext-cap-style gc) keyword)
(setf (gcontext-ciip-mask gc [ordering]) mask
(setf (gcontext-clip-ordering gc) keyword)
(setf (gcontext-clip-x gc) integei)
(setf (gcontext-clip-y gc) integer)
(setf (gcontext-dash-offset gc) integer)
(setf (gcontext-dashes gc) dash-list)
(setf (gcontext-exposures gc) state)
(setf (gcontext-fill-rule gc) keyword)
(setf (gcontext-fill-style gc) keyword)
(setf (gcontext-font gc [metrics-p ]) foni)J\
(setf (gcontext-foreground gc) integer)
(setf (gcontext-function gc) logical-op)
(setf (gcontext-join-style gc) keyword)
(setf (gcontext-line-style gc) keyword)
(setf (gcontext-line-width gc) integer)
(setf (gcontext-plane-mask gc) integer)
(setf (gcontext-stipple gc) pixmap)
(setf (gcontext-subwindow-mode gc) keyword)
(setf (gcontext-tile gc) pixmap)
(setf (gcontext-ts-x gc) integei)
(setf (gcontext-ts-y gc) integer)
See also FORCE-GCONTEXT-CHANGES,
WITH-GCONTEXT

ChangeH osts

ChangeKeyboardControl

XAddHost
XAddHosts
X Rem oveHost
XRem oveHosts

ADD-ACCESS-HOST

XChangeKeyboardControl

CHANGE-KEYBOARD-CONTROL

REMOVE-ACCE S S-HO ST

XAutoRepeatOfF
XAutoRepeatOn
ChangeKeyboardM apping XChangeKeyboardM apping

CHANGE-KEYBOARD-MAPPING

ChangePointerControl

CHANGE-POINTER-CONTROL

XChangePointerControl

tNote that [brackets]represent optional arguments.

(continued on next page)

B-2 CLX to X11 Mappings

Table B—1 (Cont.):

Mapping X II Requests to CLX Functions

P r o to c o l R eq u est
ChangeProperty

X lib Function(s)

CLX Function(s) o r E quivalen t

XChangeProperty

CHANGE-PROPERTY

X SetC ommand
X S etl conN ame
X SetlconSizes
XSetJMormalHints
X SetSizeH ints
XSetStandardProperties
XSetW MHints
X SetZoom H ints
XStoreBufFer
XStoreBytes
XStoreNam e
ChangeSaveSet

Change Window Attributes

(sett (wm-icon-name window) string)
(setf (icon-sizes window) size-hints)
(setf (wm-normal-hints window) size-hints)
(setf (wm-size-hints-xxx window?) vaiue)%
(setf (wm-hints-xxx window) vaiue)t
(setf (wm-zoom-hints window) size-hints)

XChangeSaveSet
XAddToSaveSet
XRem oveFrom SaveSet

ADD-TO-SAVE-SET
REMOVE-FROM-SAVE-SET

XChangeWindowAttributes