CLX Common LISP X Interface 1988, 1989 Texas Instruments Incorporated Permission is granted to any individual or institution to use, copy, modify and distribute this document, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation. Texas Instruments Incorporated makes no representations about the suitability of this document or the software described herein for any purpose. It is provided ”as is” without express or implied warranty. CLX Programmer’s Reference i ACKNOWLEDGMENTS Primary Interface Author: Robert W. Scheifler MIT Laboratory for Computer Science 545 Technology Square, Room 418 Cambridge, MA 02139 [email protected] Primary Implementation Author: LaMott Oren Texas Instruments PO Box 655474, MS 238 Dallas, TX 75265 [email protected] Design Contributors: Dan Cerys, BBN Scott Fahlman, CMU Kerry Kimbrough, Texas Instruments Chris Lindblad, MIT Rob MacLachlan, CMU Mike McMahon, Symbolics David Moon, Symbolics LaMott Oren, Texas Instruments Daniel Weinreb, Symbolics John Wroclawski, MIT Richard Zippel, Symbolics Documentation Contributors: Keith Cessna, Texas Instruments Kerry Kimbrough, Texas Instruments Mike Myjak LaMott Oren, Texas Instruments Dan Stenger, Texas Instruments The X Window System is a trademark of MIT. UNIX is a trademark of AT&T Bell Laboratories. ULTRIX, ULTRIX–32, ULTRIX–32m, ULTRIX–32w, and VAX/VMS are trademarks of Digital Equipment Corporation. ii CLX Programmer’s Reference CONTENTS Section Title 1 INTRODUCTION TO CLX 2 DISPLAYS 3 SCREENS 4 WINDOWS AND PIXMAPS 5 GRAPHICS CONTEXTS 6 GRAPHIC OPERATIONS 7 IMAGES 8 FONTS AND CHARACTERS 9 COLORS 10 CURSORS 11 ATOMS, PROPERTIES, AND SELECTIONS 12 EVENTS AND INPUT 13 RESOURCES 14 CONTROL FUNCTIONS 15 EXTENSIONS 16 ERRORS A PROTOCOL VS. CLX FUNCTION CROSS-REFERENCE LISTING B GLOSSARY INDEX CLX Programmer’s Reference iii iv CLX Programmer’s Reference INTRODUCTION TO CLX Introduction 1.1 This manual assumes a basic understanding of window systems and the Common Lisp programming language. To provide an introduction to the Common Lisp X Inter- face (CLX) programming, this section discusses the following: • Overview of the X Window System • Naming and argument conventions • Programming considerations The X Window 1.2 The X Window System was developed at the Massachusetts Institute of System Technology (MIT) and first released in 1985. Since then, the X Window System has be- come an industry-standard product available on virtually every type of bit-mapped workstation. The current version of X, Version 11, has been implemented for several dif- ferent computer architectures, for a wide variety of display hardware, and also for many different operating systems. X Version 11 represents the fulfillment of the original de- sign goals proposed by MIT, as follows: • Portable — Support virtually any bitmap display and any interactive input device (including keyboards, mice, tablets, joysticks, and touch screens). Make it easy to implement the window system on different operating systems. • Device-Independent Applications — Avoid rewriting, recompiling, or even relink- ing in order to use different display/input hardware. Make it easy for an application to work on both monochrome and color hardware. • Network Transparent — Let an application run on one computer while using anoth- er computer’s display, even if the other computer has a different operating system or hardware architecture. • Multitasking — Support multiple applications being displayed simultaneously. • No User Interface Policy — Since no one agrees on what constitutes the best user interface, make it possible for a broad range of user interface styles (or policies) to be implemented, external to the window system and to the application programs. • Cheap Windows — Windows should be abundant, and ubiquitous. Provide overlap- ping windows and a simple mechanism for window hierarchy. • High-Performance Graphics — Provide powerful interfaces for synthesizing 2-D images (geometric primitives, high-quality text with multiple typefaces, and scanned images). • Extensible — Include a mechanism for adding new capabilities. Allow separate sites to develop independent extensions without becoming incompatible with re- mote applications. CLX Programmer’s Reference 1-1 Introduction to CLX Some of these goals lead directly to the basic X architecture — the client-server model. The basic window system is implemented by the X server program. An application pro- gram (the client) sends window system requests to the X server through a reliable two- way byte-stream. In general, the server and the client can be executing on separate host computers, in which case the byte-stream is implemented via some network protocol (TCP, DECnet, Chaosnet, and so forth). The X server, which is connected to several client programs run- ning concurrently, executes client requests in round-robin fashion. The server is respon- sible for drawing client graphics on the display screen and for making sure that graphics output to a window stays inside its boundary. The other primary job of the X server is to channel input from the keyboard, pointer, and other input devices back to the appropriate client programs. Input arrives at the client asynchronously in the form of input events representing up/down transitions of keys or pointer buttons, changes in the pointer position, and so on. In some cases, a request gen- erates a return value (or reply) from the server, which is another kind of client input. Re- plies and input events are received via the same byte-stream connecting the client with the server. Windows 1.2.1 The X Window System supports one or more screens containing overlapping windows and subwindows. A screen is a physical monitor and hardware, which can be either color or black and white. There can be multiple screens per display workstation. A single server can provide display services for any number of screens. A set of screens for a single user with one keyboard and one mouse is called a display. All windows in an X server are arranged in a strict hierarchy. At the top of the hierarchy are the root windows, which cover each of the display screens. Each root window is ei- ther partially or completely covered by child windows. All windows, except for root windows, have parents. Any window can in turn have its own children. In this way, an application program can create a window tree of arbitrary depth on each screen. A child window can be larger than its parent. That is, part or all of the child window can extend beyond the boundaries of the parent. However, all output to a window is clipped by the boundaries of its parent window. If several children of a window have overlapping locations, one of the children is considered to be on top of/or raised over the others, ob- scuring them. Window output to areas that are covered by other windows is suppressed. A window has a border that is zero or more pixels in width and can be any pattern (pix- map) or solid color. A window usually has a background pattern that is drawn by the X server. Each window has its own coordinate system. Child windows obscure their par- ents unless the child windows have no background. Graphics operations in the parent window are usually clipped by the children. X also provides objects called pixmaps for off-screen storage of graphics. Single-plane pixmaps (that is, of depth 1) are sometimes referred to as bitmaps. Both pixmaps and windows can be used interchangeably in most graphics functions. Pixmaps are also used in various graphics operations to define patterns, or tiles. Windows and pixmaps togeth- er are referred to as drawables. Input Events 1.2.2 The X input mechanism is conceptually simple yet quite powerful. Most events are attached to a particular window (that is, contain an identifier for the window receiv- ing the event). A client program can receive multiple window input streams, all multi- plexed over the single byte-stream connection to the server. 1-2 CLX Programmer’s Reference Introduction to CLX Clients can tailor their input by expressing interest in only certain event types. The server uses special event types to send important messages to the client. For example, the client can elect to receive an :enter-notify event when the pointer cursor moves into a certain window. Another vital message from the server is an :exposure event. This is a signal to the client indicating that at least some portion of the window has suddenly become vis- ible (perhaps the user moved another window which had been overlapping it). The client is then responsible for doing what is necessary to redisplay the window’s image. Client programs must be prepared to regenerate the contents of windows in this way on de- mand. Input is also subject to policy decisions about which client window receives keyboard and pointer events. Since the pointer is free to roam between windows, just clicking on a window is often enough to send a pointer event to that window. Keyboard events, how- ever, must go to a keyboard focus window which has to be designated in some other way. Usually, the arbiter of such input management policy is a program called the window manager. The window manager gives the human user a way to make a window the key- board focus, to manage the layout of windows on the screen, to represent windows with icons, and so forth. In fact, the window manager client determines most of the so-called look and feel of the X Window System. A Quick Tour 1.3 The X Window System is defined by the X Window System Protocol of CLX Specification, a detailed description of the encoding and the meaning of requests and events sent between a client and a server. This standard protocol does not depend on any particular programming language. As a result, each programming language must define its own functional interface for using the X protocol.