~ubuntu-branches/ubuntu/quantal/gclcvs/quantal

« back to all changes in this revision

Viewing changes to xgcl-2/Xakcl.paper

  • Committer: Bazaar Package Importer
  • Author(s): Camm Maguire
  • Date: 2004-06-24 15:13:46 UTC
  • Revision ID: james.westby@ubuntu.com-20040624151346-xh0xaaktyyp7aorc
Tags: 2.7.0-26
C_GC_OFFSET is 2 on m68k-linux

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
                        
 
2
        
 
3
 
 
4
                              A Guide to Xakcl
 
5
                              ----------------
 
6
 
 
7
                                    by 
 
8
 
 
9
                                Hiep H Nguyen
 
10
 
 
11
 
 
12
 
 
13
 
 
14
                Table of Contents
 
15
                -----------------       
 
16
        
 
17
 
 
18
                A. Getting Started
 
19
 
 
20
                        1. A brief description of X windows
 
21
                        2. A few commands to initialize graphics
 
22
                
 
23
                B. Creating and Using Windows
 
24
 
 
25
                        1. Creating Windows 
 
26
                        2. Controling Window attributes
 
27
                        3. Getting Window Geometry
 
28
 
 
29
                C. How to Use the Graphics Context
 
30
 
 
31
                        1. Changing the Graphics Context
 
32
                        2. Getting Information form the Graphics Context
 
33
 
 
34
                D. Basic Drawing and Color Drawing
 
35
 
 
36
                        1. Drawing Lines 
 
37
                        2. Drawing Rectangles
 
38
                        2. Drawing Arcs 
 
39
                        3. Drawing Text
 
40
 
 
41
 
 
42
                E. Handling Events
 
43
 
 
44
                        1. The event queue
 
45
                        2. Examples of Mouse Events
 
46
                        3. Examples of Keyboard Events
 
47
                        4. A sample program to track the mouse
 
48
 
 
49
 
 
50
                F. Conclusion
 
51
 
 
52
                G. Copyright
 
53
 
 
54
Software Copyright (c) 1992, The University of Texas at Austin.
 
55
All rights reserved.  See section G for full copyright statement.
 
56
 
 
57
 
 
58
 
 
59
                        A Guide to Xakcl
 
60
                        ----------------
 
61
 
 
62
 
 
63
 
 
64
        Xakcl is the basic Xwindows library for Akcl lisp (the C
 
65
header files for the library correspond to Xlib.h, Xutil.h, and X.h).
 
66
Since Xakcl supports only the basic Xwindows library, Xakcl
 
67
programming is intended to be a low level programming aproach to
 
68
graphics.  As a consequence, any Xwindows program written in C can
 
69
also be written in Xakcl, with little cost in performance.  The
 
70
primitive operations range from controling minute details in color, to
 
71
creating pixmaps, and configuring windows.  Thus a programer using
 
72
xakcl can exploit both the extensibility of Xwindows graphics
 
73
capabilities and the ease of lisp programming.
 
74
 
 
75
 
 
76
 
 
77
        It is assumed that the reader is familiar with Lisp, and has
 
78
some passing knowledge of C.  Also familiarity with the Xwindows
 
79
library routines and programming conventions would be helpful but is
 
80
not requiered.  All X functions in Xakcl begins with the letter 'X' ,
 
81
unless otherwise mentioned.  The Syntax and names of Xakcl functions
 
82
are kept as closely to the X library functions as possible, so that a
 
83
user of the Xwindows' C libary will have no trouble in learning how to
 
84
use Xakcl.  Of course this also makes translation of X programs in C,
 
85
into Lisp easier.  For an introduction to X programming in C 'Xlib
 
86
Programming Manual for version 11' by Adrian Nye is suggested.  Also,
 
87
any reference manual on the X library would be helpful, since the
 
88
names of Xakcl functions are identical to those of the C libararies'
 
89
functions.
 
90
 
 
91
 
 
92
 
 
93
A. Getting Started.
 
94
 
 
95
 
 
96
 
 
97
        In order to start using graphics in Xakcl, a few initilization
 
98
must take place.  These initilization correspond to Xwindows call to
 
99
get the root window, the display, the current screen, the Graphics
 
100
Context and other properties needed by X.  The use of these features
 
101
will be described further in later sections.
 
102
 
 
103
 
 
104
 
 
105
I. Initializing the Display
 
106
 
 
107
 
 
108
 
 
109
In the X windows system, a display on which graphics is being
 
110
done must be specified.  The display is initilized by calling the X
 
111
function XOpenDisplay.  For example,
 
112
 
 
113
 
 
114
(setq *default-display* (XOpenDisplay (get-c-string "")))
 
115
 
 
116
 
 
117
This functions needs a C string which is the name of the host,
 
118
which can be specified with the default host.  It returns a display in
 
119
which graphics will be manipulated.  For example, if two windows are
 
120
created on this display, than when handling events, both windows could
 
121
be polled.  However, if two different displays are used, than the user
 
122
can only handle events for one display at a time.
 
123
 
 
124
        Creating many displays could be useful for applications with
 
125
many different windows, but there is a performance cost.  It usually
 
126
takes the X serever some time to return a display ID.
 
127
 
 
128
 
 
129
 
 
130
 
 
131
II. The Default Screen and the Root Window
 
132
 
 
133
 
 
134
 
 
135
The next steps in getting started is to get the desired screen
 
136
(usually the default screen), and the root window.  These two operations
 
137
are similiar to getting a display and is straight forward.  Use the
 
138
 
 
139
commands:
 
140
 
 
141
 
 
142
(setq *default-screen* (XdefaultScreen *default-display*))
 
143
(setq *root-window* (XRootWindow *default-display* *default-screen*))
 
144
 
 
145
 
 
146
The default screen is the screen on which graphics will be
 
147
drawn, and the root window, is the window that the X serever creates
 
148
from which all other windows are created.  This is the window that is
 
149
created with the call to xstart, and resides in the background.
 
150
 
 
151
 
 
152
 
 
153
 
 
154
III.  The Black and White Pixel
 
155
 
 
156
 
 
157
 
 
158
        All graphics drawing, such as simple line drawing or text,
 
159
must be done with a specified color.  The default color is of course
 
160
black and white.  These pixel values will be used in creating windows
 
161
or telling X how to draw black and white lines.  X provides two
 
162
functions for getting   the value for the black and white pixel value,
 
163
XBlackPixel and XWhitePixel.
 
164
 
 
165
 
 
166
(setq *balck-pixel* (XBlackPixel *default-display*  
 
167
*default-screen*))
 
168
(setq *white-pixel* (XWhitePixel *default-display*  
 
169
*default-screen*))
 
170
 
 
171
 
 
172
        Again these commands are straight forward.  These two
 
173
functions are examples of the facilities that X uses to control color.
 
174
X will use pixel values to make color drawings.
 
175
 
 
176
 
 
177
 
 
178
 
 
179
IV.  The Default Graphics Context and Creation of a General GC
 
180
 
 
181
 
 
182
 
 
183
        Among other places, the pixel value, which will determine the
 
184
color of drawings, will be used in determining the Graphics Context.
 
185
In X, the graphics context is the structure that contains information
 
186
on how drawings will be done.  The line width will be determined by
 
187
the graphics context, as well as the color and the way lines join (if
 
188
they join at a rounded edge or at an angle.)  For now, only the
 
189
creation of the graphics context will be of concern.  XDefaultGC will
 
190
get a default grapics context.  For example:
 
191
 
 
192
 
 
193
(setq *default-GC* (XDefaultGC  *default-display*  *default-screen*))
 
194
 
 
195
 
 
196
However, a more general graphics context can be created with
 
197
XCreateGC.  The foreground color can be set to the black pixel and
 
198
the background color can be set to the white pixel.
 
199
 
 
200
 
 
201
(setq *default-GC* (XCreateGC  *default-display* *root-window* 0 NULL))
 
202
 
 
203
(XSetForeground  *default-display* *default-GC* *black-pixel*)
 
204
 
 
205
(XSetBackground  *default-display* *default-GC* *white-pixel*)
 
206
 
 
207
 
 
208
        After calling the above functions, a new graphics context will
 
209
be created. The new Graphics Context will tell X how to draw.  For
 
210
example, when using XDrawString, X will use the foreground pixel, in
 
211
this case, Black in the GC to draw the string.  Also, XDrawImageString
 
212
could be used.  This routine, X draws the string in the foreground
 
213
pixel and fills the background with the background pixel.  If the
 
214
foregorund and background pixels were switched than the string would
 
215
be white letters on a black background.  This is an example of
 
216
highlighting text.
 
217
 
 
218
 
 
219
 
 
220
 
 
221
VI.  The Default Color Map
 
222
 
 
223
 
 
224
X uses a colormap in order to allocate colors for a client.  A
 
225
colormap allows the user to match pixel values to an rgb value.  The
 
226
black pixel created by XBlackPixel is an example of a pixel value.  A
 
227
colormap may or may not have the exact color that is being requested.
 
228
The closest pixel value is given to the user.  In order to get a set
 
229
of specific colors it is necesary to create a unique colormap, however
 
230
for most applications, the default colormap will do.  An example of
 
231
creating a default colormap is shown below.
 
232
 
 
233
 
 
234
(setq *default-colormap* ( XDefaultColormap *default-display* *default-screen*))
 
235
 
 
236
 
 
237
 
 
238
 
 
239
 
 
240
 
 
241
B. Creating and Using Windows
 
242
 
 
243
 
 
244
I. Creating a Window
 
245
 
 
246
        To create windows in lisp two functions are avaialable,
 
247
XCreateWindow and XCreateSimpleWindow.  Even though XCreateWindow is a
 
248
more expansive function, for most applications XCreateSimpleWindow
 
249
will do.  Below is an example of the use of XCreateSimpleWindow.
 
250
 
 
251
 
 
252
(setq a-window (XCreateSimpleWindow
 
253
        *default-display*  *root-window*
 
254
        pos-x pos-y win-width win-height 
 
255
        border-width  *black-pixel*  *white-pixel*))
 
256
 
 
257
        This function will return an id number for the window. This id
 
258
number will be used whenever there is an operation on the window.
 
259
XCreateSimpleWindow expects the position (pos-x and pos-y), the size,
 
260
the border width, the foreground pixel (in this case *black-pixel*),
 
261
the background pixel (*white-pixel*), the display and the parent
 
262
window (in this case the root window).  Thus these attributes can be
 
263
assigned at the creation of a window.
 
264
 
 
265
 
 
266
II.  The XSizeHints, telling the Window Manager what to do
 
267
 
 
268
 
 
269
        In the example above, the window being created is the child of
 
270
the root window.  So, this window sits inside the root window.  Of
 
271
course a window doesn't have to be the child of the root window, in
 
272
which case it would reside in that parent window.  However children of
 
273
the root window are special.  They must be managed by the window
 
274
manager.  In an Xwindows environment, the window manager is a program
 
275
that manages among other things, the size and placement of windows on
 
276
the screen.  The user can tell the manager how to control different
 
277
aspects of a window or drawable by passing to the window manager size
 
278
hints.  This is done by first creating a structure know as the
 
279
Xsizehints.  Below are examples of creating an instance of this
 
280
structure, and it's initilization.
 
281
 
 
282
 
 
283
 
 
284
(setq *default-size-hints* (make-XsizeHints))
 
285
 
 
286
(set-Xsizehints-x *default-size-hints* 10)
 
287
 
 
288
(set-xsizehints-y *default-size-hints* 20)
 
289
 
 
290
(set-xsizehints-width *default-size-hints* 225)
 
291
 
 
292
(set-xsizehints-height *default-size-hints* 400)
 
293
 
 
294
(set-xsizehints-flags *default-size-hints* (+ Psize Pposition))
 
295
 
 
296
 
 
297
        Like all Xwindows structures in Xakcl, XSizeHints can be
 
298
created using the function make followed by the type name of the
 
299
struture (note however that unlike Xsizehints, the graphics context is
 
300
created using the X function XCreateGC.  The reason is that X provides
 
301
a means of creating this structure, while the 'make' facility is
 
302
provided to make C's struct in lisp).  The fields in the structure is
 
303
set using the functions set, followed by the type of the structure and
 
304
the name of the field.  These fields can be assessed with the function
 
305
that begins with the type name followed by the name of the field.  For
 
306
example, after setting the hints as described above, (XSizeHints-x
 
307
*default-size-hints*) will return 10.
 
308
 
 
309
        After Getting the Size Hints, the call to
 
310
XSetStandardProperties will tell the window manager how to manage
 
311
windows in the root window.
 
312
 
 
313
 
 
314
(XsetStandardProperties  *default-display*  a-window (get-c-string window-name)
 
315
(get-c-string icon-name) none null null
 
316
        *default-size-hints*) 
 
317
 
 
318
        Along with the size hints, XsetStandardProperties also expects
 
319
the display, the window being managed, the window name, and the icon
 
320
name.  XSetStandardProperties also expects three other parameters, an
 
321
icon_pixmap, which will represent the window when it is iconized, and
 
322
two arguments coressponding to resource information. Both these
 
323
featrues are beyond the scope of this paper (see 'Xlib Programming
 
324
Manual for version 11' for more information).  After
 
325
XSetStandardProperties tells the window manager what to do, the window
 
326
needs to be mapped.  Mapping will request that the X server draw the
 
327
window on the screen.
 
328
 
 
329
(Xmapwindow *default-display* a-window)
 
330
 
 
331
        The above function will map the window.  Only one last
 
332
function needs to be caled for a window to appear on the screen.  This
 
333
function is XFlush.  This function, or another function that affects
 
334
the event queue (discussed later) must be called whenever there is a
 
335
drawing request for the X server.
 
336
 
 
337
 
 
338
III.  Changing Window Attributes
 
339
 
 
340
        After creating and drawing a window, the window's attributes
 
341
can and modified using several X routines.  A window could be resized,
 
342
or the height of a window could could be extracted and used to do
 
343
scaling measurements.  Like most operations in X, there are two ways
 
344
to change window attributes.  The attributes could be changed directly
 
345
by calling XChangeWindowAttributes with one of the parameters being a
 
346
C structure, with the new information, and another parameter to
 
347
specifiy which attribute is being changed.  This could be clumbersome
 
348
and inefficeint in lisp, but fortunately X usually provides a
 
349
functional way of doing a task.  Some functions for changing the
 
350
window attributes are listed.  Like most functions in X the names are
 
351
self descriptive of the function.
 
352
 
 
353
 
 
354
 
 
355
XSetWindowBackgroundPixmap  
 
356
XSetWindowBackground
 
357
XSetWindowBorderPixmap
 
358
XSetWindowBorder
 
359
XSelectInput 
 
360
XSetWindowColormap
 
361
XDefineCursor
 
362
 
 
363
 
 
364
        As can be seen, the regularity in nameing conventions of X
 
365
routines.  Only the function XSelectInput will be discussd in this
 
366
report (see section E).  The list shown is meant to demonstrate how X
 
367
names functions, and how X can provid for functional equivalents for
 
368
most operations.  (Ofcourse any function that is not provided by X can
 
369
be written in lisp using primitive operations like
 
370
XChangeWindowAttributes.  The same applies for all objects in X.)
 
371
 
 
372
 
 
373
VI.  Getting the Window Geometry
 
374
 
 
375
        In order to extract important information about a window, one
 
376
of two functions can be used.  These functions are XGetGeometry and
 
377
XGetWindowProperty.  For most applications these functions perform the
 
378
same task, but because XGetGeometry deals not only with windows but
 
379
with all drawbles, only XGetGeometry will be discussed ( all objects
 
380
that can be drawn, such as a window or an icon is a drawable).  Below
 
381
is an example of a call to XGetGeometry.
 
382
 
 
383
 
 
384
 
 
385
(XGetGeometry display a-drawable *root-return* *x-return* *y-return* *width-return* 
 
386
        *height-return* *border-width-return* *depth-return*) 
 
387
 
 
388
        The values that are returned by XGetGeometry is pointed to by
 
389
the parameters that are denoted by teh word 'return'.  A root of a
 
390
window can be extracted, along with it's position, and size. Its
 
391
border width can also be returned, along with it's depth ( a depth
 
392
tells X how many colors can be drawn for a drawble).  This functions
 
393
also demonstrates how poitners are used in Xakcl to return multiple
 
394
values.  It is necessary to allocate an area of memory in order to
 
395
write into that memory locations.  The functions int-array and
 
396
char-array will create a C array of integers and characters
 
397
respectively.  A pointer to the array is returned. XGetGemoetry
 
398
expects pointers to integers so it is necessary to alocate integer
 
399
arrays of one element.  For example:
 
400
 
 
401
 
 
402
(defvar *x-return* (int-array 1))
 
403
 
 
404
 
 
405
 
 
406
        As is obvious, the parameter to int-array is the size of the
 
407
array.   The value itself can be obtained by the function int-pos as
 
408
follows:
 
409
 
 
410
(int-pos  *x-return* 0)
 
411
 
 
412
 
 
413
        Notice that the index '0' is supplied in order to get the
 
414
first element.  This is identical to lisp arrays which start with
 
415
index '0'.  The rest of the information returned by XGetGeometry can
 
416
be obtained similarly.
 
417
 
 
418
 
 
419
 
 
420
 
 
421
C. The Graphics Context
 
422
 
 
423
 
 
424
I.  Changing the Graphics Context
 
425
 
 
426
 
 
427
        After Creating a Graphics context, or getting a default
 
428
graphics context as shown in section A, the graphics context can be
 
429
used to control drawing applications.  By changing the graphics
 
430
context, the drawing operations will draw in a different manner.  For
 
431
example, drawing different color lines can be accomplished this way.
 
432
 
 
433
        X provides two ways of changing the Graphics Context.  Like
 
434
the window attributes, the graphics context can be changed with
 
435
function calls or by calling a function that expects structures (in
 
436
this case XCreateGC).  In this case as well, the functional ways of
 
437
setting and changing the graphics context is easier.  Some functions
 
438
for setting the graphics context are shown below.
 
439
 
 
440
XSetBackGround
 
441
XSetForeGround
 
442
XSetLineAttributes
 
443
XSetFont
 
444
XSetFunction
 
445
 
 
446
 
 
447
i. XSetBackGround and XSetForeGround.
 
448
 
 
449
        XSetForeground and XSetBackground sets the foreground and
 
450
background pixel as mentioned in section A.  In order to Allocate a
 
451
pixel besides black and white, a call to XAllocNamedColor must be
 
452
done.  XAllocNamedColor needs two Xcolor structrues, so they must be
 
453
created as well. For example:
 
454
 
 
455
(setq pixel-xcolor (make-Xcolor))       
 
456
(setq exact-rgb  (make-Xcolor))
 
457
(XAllocNamedColor display colormap  (get-c-string color) pixel-xcolor exact-rgb)
 
458
 
 
459
        The above function will return a pixel value in the structure
 
460
pixel-color.  this informaion can be extracted with (Xcolor-pixel
 
461
pixel-xcolor).  XAllocNamedColo also expects a colormap (the default
 
462
colormap will do), a display, and a String specifying the color (for a
 
463
list of colors see the file rgb.txt in /usr/lib/X11). Thus the
 
464
following funciton will cause all drawings to be done the specify
 
465
color.
 
466
 
 
467
(Xsetforeground display GC (Xcolor-pixel  pixel-xcolor))
 
468
 
 
469
        Similair to Xsetforeground, XSetBackGround will cause all
 
470
drawings needing the background color to use the sepcified pixel
 
471
value.
 
472
 
 
473
 
 
474
ii. XSetLineAttributes
 
475
 
 
476
        In order to change how lines are drawn the function
 
477
XSetLineAttributes must be used.  For example:
 
478
 
 
479
 
 
480
(XSetLineAttributes display GC width line-style cap-style join-style)
 
481
 
 
482
 
 
483
        As can be seen XSetLineAttributes will specify the width of
 
484
the line, the style of the line, the way lines end (the cap style) and
 
485
the way lines join.  The width is an integer, while line-style,
 
486
cap-style and join-style are constants.  The default styles are
 
487
LineSolid, CapButt, and JoinMitter.  This will make lines appear
 
488
solid.  They will join at a sharp angle and the lines will end in a
 
489
flat edge.  See any X refernce manual for the complete options on the
 
490
line styles.
 
491
 
 
492
 
 
493
iii. XSetFont
 
494
 
 
495
        In order to draw text a font must be specified.  The font
 
496
tells X how characters will look on the screen.  Thus a font must be
 
497
loaded before drawing can occur.  The function XloadQueryFont will
 
498
return a structure of a valid font if one can be found, otherwise it
 
499
will return 0. The functions below will get a specified font and if a
 
500
valid font is found, will set it in the graphics context.
 
501
 
 
502
(setq font-info  (XloadQueryFont display (get-c-string a-string)))
 
503
(if (not (eql 0 font-info))
 
504
        (XsetFont  display GC (Xfontstruct-fid font-info))
 
505
        (format t "~%can't open font ~a" a-string))
 
506
 
 
507
        First the font is loaded with XloadQueryFont.  This function
 
508
expects the display and a string whcih specifies the font (for
 
509
complete font information see the directories /usr/lib/X11/fonts).
 
510
After loading the font must be set in the specified graphics context.
 
511
XSetFont expects the font id.  This id resides in the XFontStruct
 
512
returned by XloadQueryFont (this field of the structure is known as
 
513
fid).
 
514
 
 
515
iv. XSetFunction
 
516
 
 
517
        Xwindows draws by applying bit operations on the pixel vlaues
 
518
on the screen along with a mask that it creates called the plan_mask.
 
519
Most often only the pixel already on the screen is manipulated.  This
 
520
defualt logical operation is GXcopy (which is the default).  However
 
521
to perform moer complicated operations such as drawing 'ghost' images
 
522
(drawing and erasing images with out affecting drawings in the
 
523
background) other functions could be used.  These functions are
 
524
specified with a call to XSetFunction.
 
525
 
 
526
(Xsetfunction  *default-display* *default-GC* GXxor)
 
527
 
 
528
        The above function will make X draw ghost images in mono color
 
529
screens using the function Xor.  The pixel value on the screen is
 
530
Xored with the pixel value of the plan_mask (which is derived from the
 
531
foregroudn color).  On color screens the foregorund color must be set
 
532
to (logxor foreground-pixel background-pixel) in order for ghosting
 
533
effects to occurr.  Below is the complete function for ghosting
 
534
effects.
 
535
 
 
536
(Xsetforeground  *default-display* *default-GC* (logxor foreground-pixel background-pixel ))
 
537
 
 
538
 
 
539
II.  Getting Information from the Graphics Context
 
540
 
 
541
 
 
542
        In the above function, the foreground-pixel and
 
543
background-pixel must be extracted from the graphics context.  In
 
544
order to get information from the graphcis context the function
 
545
XGetGCVlues must be used.  XGetGCVlues is an example of a X function
 
546
that expects a structure, and a value mask.  Below are functions for
 
547
extracted the foreground color from the graphics context.  Other
 
548
properties such as the background pixel value.
 
549
 
 
550
(setq  *GC-Values* (make-XGCValues))
 
551
(XGetGCValues display GC (+ GCForeground) *GC-Values*)
 
552
(XGCValues-foreground  *GC-Values*)
 
553
 
 
554
        A XGCValues structrue must be created and passed to
 
555
XGetGCValues.  The values that are requested are the mask passed to
 
556
XGetGCValues (in this case it is GCForeground).  XGetGCValues also
 
557
expects the display and the graphics context.  The values themselves
 
558
can be extracted from the structure XGCValues with one of it's
 
559
selector, just as in the case of XSizeHints.
 
560
 
 
561
 
 
562
 
 
563
 
 
564
 
 
565
D. Basic Drawing and Color Drawing
 
566
 
 
567
        Now that the tools for drawing can be specified, the drawings
 
568
themselves can be accomplished by drawing requests to the X server.
 
569
An example of a drawing request is XMapWindow as mentioned in Section
 
570
B.  More generic drawings line line drawings, arc drawings and text
 
571
drawings can also be done.
 
572
 
 
573
 
 
574
I.  Drawing Lines
 
575
 
 
576
        XDrawLine will draw lines in a drawable given the
 
577
specification in the graphics context.  For example:
 
578
 
 
579
(XDrawLine  display  window GC x1 y1 x2 y2)
 
580
(Xflush display)
 
581
 
 
582
        XDrawLine will draw a line from x1 y1 to x2 y2 where x and y
 
583
are the positions.  In this case 'window' is the destination drawable.
 
584
Thus with the specification in the GC, a line on a specified with will
 
585
be drawn.  Its cap style will also be drawn accordingly.  As in other
 
586
drawing request.  the display must be specified and a call to Xflush
 
587
must be made in order to request that the X server proccess the
 
588
request.
 
589
 
 
590
 
 
591
II. Drawing Rectangles
 
592
 
 
593
        Drawing Recatangles is similiar to drawing lines.  The only
 
594
difference is that the size of the recatangle must be specified.
 
595
 
 
596
 
 
597
         (XDrawRectangle *default-display* a-window *default-GC* 
 
598
                  x y width height)
 
599
        (Xflush *default-display* ) 
 
600
 
 
601
The function expects the x and y position and the width and height.
 
602
 
 
603
 
 
604
 
 
605
II. Drawing Arcs.
 
606
 
 
607
        Arcs can form enclosed areas such as elipses or cirlces or
 
608
they coould be a curved line.  The funcion XDrawArc will draw arcs.
 
609
 
 
610
 
 
611
(XdrawArc *default-display* a-window  *default-GC* 100 100 10 10 0 (* 360 64))
 
612
(Xflush *default-display* ) 
 
613
 
 
614
        This function call will draw a circle.  The Arc will be
 
615
bounded by a rectangle.  The points 100 100 correspond to the upper
 
616
left edge of the recatangle. 10 and 10 specifies the width and height
 
617
respectively.  The starting and ending position of the arc must also
 
618
be specified.  These two points are in sixty-fourths of a degrees.
 
619
The first angle is relative to the three-o'clock position and the
 
620
second is relative to the starting position.  Thus with the example
 
621
above, the starting point will be drawn zero degrees away from the 3
 
622
o'clock position, while the ending point will be 360 degrees away ( a
 
623
complete circle, since the arc is bounded by a square).  The ending
 
624
point of 360 degrees as all points in degrees must be multiplied by
 
625
64.
 
626
 
 
627
 
 
628
III.  Drawing Text
 
629
 
 
630
 
 
631
        With the font loaded in the Graphics Context as shown in
 
632
Section C, several functions can be called in order to draw text.
 
633
Only XDrawString will be dicussed here, but the other functions are
 
634
similiar.
 
635
 
 
636
(XDrawString  *default-display*   a-window  *default-GC*  10 15 (get-c-string "hello") 4)
 
637
(Xflush *default-display*)
 
638
 
 
639
        The above function will draw the string 'hello' at positions
 
640
10, 15 with the font specified in the default grpahics context.
 
641
XDrawString also expects the length of the string (in this case 4),
 
642
and the display.
 
643
 
 
644
        Often it is necesssary to the size of the string (the
 
645
rectangle that bounds the string). This can be done with a call to
 
646
XTextExtents.
 
647
 
 
648
        (XTextExtents   font_struct (get-c-string "hello") 4 direction_return    
 
649
                font_ascent_return  font_descent_return  overall_return )
 
650
 
 
651
        Font_struct is the structure returned by XLoadQueryFont.  This
 
652
can be kept as a global or it can be obtained from the Graphics
 
653
Context as shown in section C.  XTextExtents also expects the string
 
654
drawn and the length of the string.  It returns the direction,
 
655
font_ascent, font_descent, and the overall metric of the string.  Only
 
656
the overall_return will be important for most uses (the direction
 
657
specifies which direction the string is drawn - ie left to right, and
 
658
font_ascent, font_descent pretain only to the font itself, and not the
 
659
string).
 
660
 
 
661
        The overall metric information is the structure XCharStruct.
 
662
Some members of this structure is the descent, the ascent and the
 
663
width (an ascent tells how far above a baseline a character is drawn,
 
664
while the descent tells how far below).  After a call to XTextExtents,
 
665
the ascent will be have the maximum ascent of all the characters in
 
666
the string.  Likewise the descent will have the maximum descent of all
 
667
the characters.  The width will be the sum of the characer width of
 
668
all the characters in the string (thus the width of the string in
 
669
number of pixels).  From this information, the user shouldbe able to
 
670
position text precisely on the screen.
 
671
 
 
672
 
 
673
 
 
674
 
 
675
 
 
676
E. Handling Events
 
677
 
 
678
        So far only request to the X server to do output on the screen
 
679
have been discussed.  X also has a means of getting infomation about
 
680
what is inputed by a user as well.  The inputs can range from moving
 
681
or clicking the mouse to keys being pressed on the keyboard.  The
 
682
input also encompases events like a window being uncovered or exposed
 
683
by another window, or a window being resized.  
 
684
 
 
685
 
 
686
I.  Setting the Input
 
687
 
 
688
        These inputs are called Events.  The Events themseleves only
 
689
have meaning when they pertain to a window.  In other words, events
 
690
occur in windows.  Thus an attribute of the window must be set.  The
 
691
function XSelectInput must be used.
 
692
 
 
693
         (Xselectinput *default-display* a-window 
 
694
                    (+ ButtonpressMask PointerMotionMask ExposureMask))
 
695
 
 
696
The above function will tell X that in a-window only Buttonpress
 
697
Events, PointerMotion Events, and Exposure Event can occur.  As can be
 
698
seen this is specified using mask (for other mask see a Xlib manual or
 
699
the file X.lsp or X.h).
 
700
 
 
701
        After Specifiying the input, all events that occur in that
 
702
will go on the event queue.  The event queue is a queue of what events
 
703
have occured, the first one being on top.  The client can both get
 
704
information form the queue and manipulate the queue.  
 
705
 
 
706
II.  Getting Information form the Event Queue
 
707
 
 
708
        Several functions are provided for getting information the
 
709
event queue.  Below is a list of some of these functions along with a
 
710
description.
 
711
 
 
712
        XNextEvent              -- Waits for the next event, and returns that event.
 
713
        XPeekEvent              -- Sees what is next on the queue without changing the queue 
 
714
                                -- if no events exist it waits until one occurs.
 
715
        XPending                -- returns the number of events in the queue
 
716
        XPutBackEvent           -- puts an event on the queue
 
717
 
 
718
        XNextEvent is the most commonly used function, even though the
 
719
 
 
720
        other functions can be useful as well.  Only the call to
 
721
XNextEvent will be discribed because the other functions are similiar
 
722
to XNextEvent. The following functions will get an event from the
 
723
queue and retrieve the type of the event along with the window that it
 
724
occurs in.
 
725
 
 
726
        (XNextEvent  *default-display*  *default-event*)
 
727
        (setq type (XAnyEvent-type  *default-event*))
 
728
        (setq active-window (XAnyevent-window  *default-event*))
 
729
 
 
730
        XNextEvent returns a structure, XEvent.  This structure in
 
731
turn is a union of other structures, one for each type of event that
 
732
can occur.  In order to handle an event the appropriate structure must
 
733
be assessed.  For example, if the PointerMotion event needs to be
 
734
handled than the *default-event* must be assessed as a XMotionEvent
 
735
structure.  Below is an example of getting the x and y position of the
 
736
pointer when a PointerMotion Event has occured, and the pointer is in
 
737
the correct window.
 
738
 
 
739
        (if (and (eql type MotionNotify)
 
740
                (eql  active-window correct-window))
 
741
 
 
742
         (let   ((x (XMotionEvent-x  *default-event*))
 
743
                 (y (XMotionEvent-y  *default-event*)))
 
744
`                                                       ;;trace the mouse
 
745
                     (format t "~% pos-x: ~a  pos-y: ~a" x y)))
 
746
 
 
747
 
 
748
 
 
749
 
 
750
III.  Manipulating the Event Queue
 
751
 
 
752
        For most applications the client will never have to change the
 
753
event queue, besides removing events of the top or the queue, however
 
754
sometimes the queue needs to be cleared by the client.  The funciton
 
755
XSync can be used to do this.  For example:
 
756
 
 
757
         (Xsync *default-display* 1) 
 
758
 
 
759
 
 
760
 
 
761
 
 
762
 
 
763
                F. Conclusion
 
764
 
 
765
        With the commands demonstarted in this tutorial, most
 
766
applications can be managed.  Windows can be created, and graphics
 
767
operations can be performed.  For more complex applications a widget
 
768
set can be created similiar to the X Intrinsics library and the Athena
 
769
Widget Set.  For a lisp like implementation of widgets and an advance
 
770
aplications see the GWM application, in the GWM Manual by Colas
 
771
Nahaboo.  GWM is a generic window manager, that is similar to Xakcl.
 
772
It supports objects that are similiar to Widgets in most C Xwindows
 
773
libraries.
 
774
 
 
775
 
 
776
                G. Copyright
 
777
 
 
778
 
 
779
;;**********************************************************
 
780
;;Copyright 1987 by Digital Equipment Corporation, Maynard, Massachusetts,
 
781
;;and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
 
782
 
 
783
;;                        All Rights Reserved
 
784
 
 
785
;;Permission to use, copy, modify, and distribute this software and its 
 
786
;;documentation for any purpose and without fee is hereby granted, 
 
787
;;provided that the above copyright notice appear in all copies and that
 
788
;;both that copyright notice and this permission notice appear in 
 
789
;;supporting documentation, and that the names of Digital or MIT not be
 
790
;;used in advertising or publicity pertaining to distribution of the
 
791
;;software without specific, written prior permission.  
 
792
 
 
793
;;DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
 
794
;;ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
 
795
;;DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
 
796
;;ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 
797
;;WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
 
798
;;ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 
799
;;SOFTWARE.
 
800
 
 
801
;;*****************************************************************