1
% dwdoc.tex Gordon S. Novak Jr.
2
% 08 Oct 92; 08 Oct 93; 16 Nov 94; 05 Jan 95
4
\documentstyle[12pt]{article}
5
\setlength{\oddsidemargin}{0 in}
6
\setlength{\textwidth}{6.5 in}
7
\setlength{\textheight}{9.0 in}
8
\setlength{\parskip}{0.1 in}
9
\setlength{\parindent}{0.0 in}
10
\setlength{\topmargin}{-0.4in}
15
\begin{center}\Large{{\bf Interface from GCL to X Windows}} \\
19
\large{Gordon S. Novak Jr. \\
20
Department of Computer Sciences \\
21
University of Texas at Austin \\
25
Software copyright \copyright 1994 by Gordon S. Novak Jr. and
26
The University of Texas at Austin. Distribution and use are allowed
27
under the Gnu Public License. Also see the copyright section at the end
28
of this document for the copyright on X Consortium software.
32
\section{Introduction}
34
This document describes a relatively easy-to-use interface between
35
XGCL (X version of Gnu Common Lisp) and X windows. The interface
36
consists of two parts:
38
\item Hiep Huu Nguyen has written (and adapted from X Consortium software)
39
an interface between GCL and Xlib, the X library in C.
40
Xlib functions can be called directly if desired, but most users will find
41
the {\tt dwindow} functions easier to use. There is little documentation
42
of these functions, but the Xlib documentation can be consulted, and
43
the {\tt dwindow} functions can be examined as examples.
45
\item The {\tt dwindow} functions described in this document, which call
46
the Xlib functions and provide an easier interface for Lisp programs.
48
The source file for the interface (written in GLISP) is
49
{\tt dwindow.lsp}; this file is compiled into a file in plain Lisp,
50
{\tt dwtrans.lsp}. {\tt dwtrans.lsp} is compiled as part of XGCL.
52
The functions in this package use the convention that the coordinate
53
{\tt (0 0)} is the lower-left corner of a window, with positive {\tt y}
54
being upward. This is different from the convention used by
55
X, which assumes that {\tt (0 0)} is the upper left corner and
56
that positive {\tt y} is downward.
58
In the descriptions below, some function arguments are shown with a type,
59
e.g. {\tt arg:type}, to indicate the expected type of the argument.
60
The type {\tt vector} is a list {\tt (x y)} of integers. The argument
61
{\tt w} that is used with many functions is of type {\tt window}
62
({\tt window} is a Lisp data structure used by the {\tt dwindow} functions).
64
Both the Xlib and {\tt dwindow} functions are in the package {\tt xlib:}.
65
The file {\tt imports.lsp} may be used to import the {\tt dwindow} symbols
66
to the {\tt :user} package.
69
\section{Examples and Utilities}
71
\subsection{{\tt dwtest}}
73
The file {\tt dwtest.lsp} contains example functions that illustrate
74
the use of the {\tt dwindow} package. The function call {\tt (wtesta)}
75
creates a small window for testing. {\tt (wtestb)} through
76
{\tt (wtestk)} perform drawing and mouse interaction tests using the
77
window. These functions may be consulted as examples of the use of
78
commonly used {\tt dwindow} functions.
80
\subsection{{\tt pcalc}}
82
The file {\tt pcalc.lsp} implements
83
a pocket calculator as a {\tt picmenu}; its entry is {\tt (pcalc)}.
85
\subsection{{\tt draw}}
87
The file {\tt drawtrans.lsp} contains an interactive drawing program;
88
its entry is {\tt (draw 'foo)} where {\tt foo} is the name of the drawing.
89
The file {\tt ice-cream.lsp} can be loaded, followed by
90
{\tt (draw 'ice-cream)} to examine an example drawing.
91
{\tt draw} can produce a Lisp program or a set of \LaTeX \ commands to
92
recreate the drawing; use {\tt origin to zero} before making a program.
93
{\tt (draw-out file names)} will write definitions of drawings in the
94
list {\tt names} to the file {\tt file}.
99
The function {\tt menu} provides an easy interface to make a pop-up menu,
100
get a selection from it, and destroy it: \\
103
{\tt \hspace*{0.5in} (menu items \&optional title)} \\
106
Example: {\tt (menu '(red white blue))}
108
This simple call is all that is needed in most cases.
109
More sophisticated menu features are described below.
111
The {\tt items} in a menu is a list; each item may be a symbol, a {\tt cons}
112
of a symbol or string and the corresponding value, or a {\tt cons} of a
113
function name and the corresponding value. In the latter case, the function
114
is expected to draw the corresponding menu item.
116
If a function name is specified as the first element of a menu item, the
117
drawing function should have arguments {\tt (fn w x y)}, where {\tt w}
118
is the window and {\tt x} and {\tt y} are the lower-left corner of the
119
drawing area. The property list of the function name should have the
120
property {\tt display-size}, which should be a list {\tt (width height)}
121
in pixels of the displayed symbol.
123
Menus can be associated with a particular window; if no window is specified,
124
the menu is associated with the window where the mouse cursor is located
125
when the menu is initialized (which might not be a Lisp user's window). If a
126
menu is associated with a user window, it may be {\em permanent} (left
127
displayed after a selection is made) and may be {\em flat} (drawn directly
128
on the containing window, rather than having its own window).
130
A menu can be created by {\tt menu-create} : \\
134
(menu-create items \&optional title w:window x y perm flat font)} \\
137
{\tt title}, if specified, is displayed over the menu.
138
{\tt w} is an existing {\tt window}; if specified, the menu is put
139
within this window at the {\tt x y} offsets specified (adjusted if necessary
140
to keep the menu inside the window). If no {\tt w}
141
is specified, or if {\tt x} is {\tt nil}, the menu is put where the cursor
142
is the first time the menu is displayed.
143
{\tt perm} is non-{\tt nil} if the menu is to be permanent, {\em i.e.}, is to
144
be left displayed after a selection has been made.
145
{\tt flat} is non-{\tt nil} if the menu is to be drawn directly on the
147
{\tt font} is a symbol or string that names the font to be used; the
148
default is a {\tt 9x15} typewriter font.
150
The menu is returned as the value of {\tt menu-create}. Such a menu can
151
be saved; selections can be made from a menu {\tt m} as follows: \\
154
{\tt \hspace*{0.5in} (menu-select m \&optional inside)} \ \ \ \ \ or
155
{\tt \hspace*{0.5in} (menu-select! m)} \\
158
{\tt menu-select} will return {\tt nil} if the mouse is clicked outside the
159
menu, or is moved outside after it has been inside (or if {\tt inside} is
160
not {\tt nil}), provided that the menu is contained within a user-created
162
{\tt menu-select!} requires that a choice be made.
164
In order to avoid wasting storage, unused menus should be destroyed:
165
{\tt (menu-destroy m)}. The simple {\tt menu} function destroys its
166
menu after it is used.
168
{\tt \hspace*{0.5in} (menu-size m)} \\
169
{\tt \hspace*{0.5in} (menu-moveto-xy m x y)} \\
170
{\tt \hspace*{0.5in} (menu-reposition m)} \
172
{\tt menu-reposition} will reposition a {\tt flat} menu within its parent
173
window by allowing the user to position a ghost box using the mouse.
174
{\tt menu-size} returns the size of the menu as a vector, {\tt (x y)}.
175
{\tt menu-moveto-xy} adjusts the offsets to move a {\tt flat} menu to
176
the specified position within its parent window. These functions and
177
{\tt menu-destroy} work for picmenus and barmenus as well.
179
{\tt \hspace*{0.5in} (menu-item-position m name \&optional location)} \\
182
{\tt menu-item-position} returns a vector {\tt (x y)} that gives the
183
coordinates of the menu item whose name is {\tt name}. {\tt location}
184
may be {\tt center}, {\tt left}, {\tt right}, {\tt top}, or {\tt bottom};
185
the default is the lower-left corner of the menu item. {\tt center}
186
specifies the center of the box containing the menu item; the other
187
{\tt location} values are at the center of the specified edge of the box.
189
\subsection{Picmenus}
191
A {\tt picmenu} (picture menu) is analogous to a menu, but involves a
192
user-defined picture containing sensitive spots or ``buttons''.
193
The test function {\tt (wteste)} shows an example of a {\tt picmenu}.
194
A {\tt picmenu} is created by: \\
197
{\tt \hspace*{0.5in} (picmenu-create buttons width height drawfn \\
198
\hspace*{1.5in} \&optional title dotflg w:window x y perm flat font boxflg)} \\
202
If a picmenu is to be used more than once, the common parts can be made
203
into a {\tt picmenu-spec} and reused:
206
{\tt \hspace*{0.5in} (picmenu-create-spec buttons width height drawfn \\
207
\hspace*{1.5in} \&optional dotflg font)} \\
210
{\tt \hspace*{0.5in} (picmenu-create-from-spec spec:picmenu-spec \\
211
\hspace*{1.5in} \&optional title w:window x y perm flat boxflg)} \\
214
{\tt width} and {\tt height} are the size of the area occupied by the
215
picture. {\tt (drawfn w x y)} should draw the picture at the offset
216
{\tt x y}. Note that the {\tt draw} utility can be used to
217
make the drawing function, including {\tt picmenu} buttons.
218
{\tt dotflg} is non-{\tt nil} if it is desired that small boxes be
219
automatically added to the sensitive points when the picture is drawn.
220
{\tt boxflg} is non-{\tt nil} if a box is to be drawn around the picmenu
221
when the picture is drawn (this is only needed for flat
222
picmenus). If {\tt perm} is non-nil, the drawing program is not called when
223
a selection is to be made, so that an external program must draw the
224
{\tt picmenu}; this avoids the need to redraw a complex picture.
225
The remaining arguments are as described for menus.
227
Each of the {\tt buttons} in a picmenu is a list: \\
230
{\tt \hspace*{0.5in} (name offset size highlightfn unhighlightfn)} \\
233
{\tt name} is the name of the button; it is the value returned when that
235
{\tt offset} is a vector {\tt (x y)} that gives the offset of the center
236
of the button from the lower-left corner of the picture.
237
The remainder of the button list may be omitted.
238
{\tt size} is an optional list {\tt (width height)} that gives the size of the
239
sensitive area of the button; the default size is {\tt (12\ 12)}.
240
{\tt (highlightfn w x y)} and {\tt (unhighlightfn w x y)} (where {\tt (x y)}
241
is the center of the button in the coordinates of {\tt w}) are optional
242
functions to highlight the button area when the cursor is moved into it and
243
unhighlight the button when the cursor is moved out; the default is to
244
display a box of the specified {\tt size}.
246
{\tt \hspace*{0.5in} (picmenu-select m \&optional inside)} \\
247
If the {\tt picmenu} is not {\tt flat}, its window should be destroyed
248
following the selection using {\tt menu-destroy}.
250
{\tt \hspace*{0.5in} (picmenu-item-position m name \&optional location)} \\
253
{\tt \hspace*{0.5in} (picmenu-delete-named-button m name:symbol)} \\
254
This deletes a button from a displayed {\tt picmenu}. The set of
255
deleted buttons is reset to {\tt nil} when the picmenu is drawn.
257
\subsection{Barmenus}
259
A {\tt barmenu} displays a bar graph whose size can be adjusted using
263
(barmenu-create maxval initval barwidth \\
264
\hspace*{1.5in} \&optional title horizontal subtrackfn subtrackparms \\
265
\hspace*{1.5in} parentw x y perm flat color)}
267
A value is selected by: {\tt (barmenu-select m:barmenu \&optional inside)} \\
268
If the {\tt barmenu} is not {\tt flat}, its window should be destroyed
269
following the selection using {\tt menu-destroy}.
271
The user must first click the mouse in the bar area; then
272
the size of the displayed bar is adjusted as the user moves the mouse
273
pointer. In addition, the {\tt subtrackfn} is called with arguments
274
of the size of the bar followed by the {\tt subtrackparms}; this can
275
be used, for example, to display a numeric value in addition to the
279
\subsection{Menu Sets and Menu Conns}
281
A {\tt menu-set} is a set of multiple menus, picmenus, or barmenus
282
that are simultaneously active within the same window. Menu-sets
283
can be used to implement graphical user interfaces. A {\tt menu-conns}
284
is a menu-set that includes connections between menus; this can be
285
used to implement interfaces that allow the user to construct a network
288
The source file for menu-sets is the GLISP file {\tt menu-set.lsp};
289
this file is translated as part of the file {\tt drawtrans.lsp} in
290
plain Lisp. Examples of the use of menu sets are given at the top
291
of the file {\tt menu-set.lsp}. In the following descriptions,
292
{\tt ms} is a {\tt menu-set} and {\tt mc} is a {\tt menu-conns}.
294
{\tt \hspace*{0.5in} (menu-set-create w)} creates a menu set to be displayed
295
in the window {\tt w}.
297
{\tt \hspace*{0.5in} (menu-set-name symbol)} makes a {\tt gensym} name that
298
begins with {\tt symbol}.
300
{\tt \hspace*{0.5in} (menu-set-add-menu ms name:symbol sym title items} \\
301
\hspace*{1.5in} {\tt \&optional offset:vector)}
303
This function adds a menu to a menu-set. {\tt sym} is arbitrary
304
information that is saved with the menu.
306
{\tt \hspace*{0.5in} (menu-set-add-picmenu ms name sym title spec:picmenu-spec} \\
307
\hspace*{1.5in} {\tt \&optional offset:vector nobox)}
309
{\tt \hspace*{0.5in} (menu-set-add-component ms name \&optional offset:vector)}
311
This adds a component that has a {\tt picmenu-spec} defined on the
312
property list of {\tt name}.
314
{\tt \hspace*{0.5in} (menu-set-add-barmenu ms name sym barmenu title} \\
315
\hspace*{1.5in} {\tt \&optional offset:vector)}
317
{\tt \hspace*{0.5in} (menu-set-draw ms)} draws all the menus.
319
{\tt \hspace*{0.5in} (menu-set-select ms \&optional redraw enabled)}
321
{\tt menu-set-select} gets a selection from a menu-set. If {\tt redraw}
322
is non-{\tt nil}, the menu-set is drawn. {\tt enabled} may be a list
323
of names of menus that are enabled for selection. The result is
324
{\tt (selection menu-name)}, or {\tt ((x y) BACKGROUND button)}
325
for a click outside any menu.
328
{\tt \hspace*{0.5in} (menu-conns-create ms)} creates a {\tt menu-conns}
329
from a {\tt menu-set}.
331
{\tt \hspace*{0.5in} (menu-conns-add-conn mc)}
333
This function allows the user to select two ports from menus of the
334
{\tt menu-conns}. It then draws a line between the ports and adds the
335
connection to the {\tt connections} of the {\tt menu-conns}.
337
{\tt \hspace*{0.5in} (menu-conns-move mc)}
339
This function allows the user to select a menu and move it.
340
The {\tt menu-set} and connections are redrawn afterwards.
342
{\tt \hspace*{0.5in} (menu-conns-find-conn mc pt:vector)} \\
343
This finds the connection selected by the point {\tt pt}, if any.
344
This is useful to allow the user to delete a connection:
346
{\tt \hspace*{0.5in} (menu-conns-delete-conn mc conn)}
348
{\tt \hspace*{0.5in} (menu-conns-find-conns mc menuname port)} \\
349
This returns all the connections from the specified {\tt port} (selection)
350
of the menu whose name is {\tt menuname}.
355
{\tt \hspace*{0.5in} (window-create width height \&optional title parentw
359
{\tt window-create} makes a new window of the specified {\tt width} and
360
{\tt height}. {\tt title}, if specified, becomes the displayed title
361
of the window. If {\tt parentw} is specified, it should be the
362
{\tt window-parent} property of an existing window, which becomes the parent
363
window of the new window. {\tt x} and {\tt y} are the offset of the
364
new window from the parent window. {\tt font} is the font to be used
365
for printing in the window; the default is given by
366
{\tt *window-default-font-name*}, initially {\tt courier-bold-12}.
368
{\tt \hspace*{0.5in} (window-open w)} causes a window to be displayed
371
{\tt \hspace*{0.5in} (window-close w)} removes the window from the display;
374
{\tt \hspace*{0.5in} (window-destroy w)}
376
{\tt \hspace*{0.5in} (window-moveto-xy w x y)}
378
{\tt \hspace*{0.5in} (window-geometry w)} queries X for the window geometry.
379
The result is a list, \linebreak
380
{\tt (x y width height border-width)} .
382
{\tt \hspace*{0.5in} (window-size w)} returns a list {\tt (width height)} .
385
Note that the width and height are cached within the structure so that no call
386
to X is needed to examine them. However, if the window is resized, it is
387
necessary to call {\tt (window-reset-geometry\ w)} to reset the local
388
parameters to their correct values.
390
% ; Paint in window with mouse \\ % these are not really working...
391
% {\tt \hspace*{0.5in} (window-paint w)} \\
393
% {\tt \hspace*{0.5in} (window-move w)} \\
395
% {\tt \hspace*{0.5in} (dowindowcom w)} \\
397
The following functions provide access to the parts of the {\tt window} data
398
structure; most applications will not need to use them. \\
401
{\tt \hspace*{0.5in} (window-gcontext w)} \\
402
{\tt \hspace*{0.5in} (window-parent w)} \\
403
{\tt \hspace*{0.5in} (window-drawable-height w)} \\
404
{\tt \hspace*{0.5in} (window-drawable-width w)} \\
405
{\tt \hspace*{0.5in} (window-label w)} \\
406
{\tt \hspace*{0.5in} (window-font w)} \\
407
{\tt \hspace*{0.5in} (window-screen-height)} \\
410
\section{Drawing Functions}
412
{\tt \hspace*{0.5in} (window-clear w)} clears the window to the background
415
{\tt \hspace*{0.5in} (window-force-output \&optional w)}
418
Communication between the running program and X windows is done through a
419
stream; actual drawing on the display is done asynchronously.
420
{\tt window-force-output} causes the current drawing commands, if any,
421
to be sent to X. Without this, commands may be left in the stream buffer and
422
may appear not to have been executed. The argument {\tt w} is not used.
424
In all of the drawing functions, the {\tt linewidth} argument is optional
425
and defaults to {\tt 1}.
428
{\tt \hspace*{0.5in} (window-draw-line w from:vector to:vector linewidth)} \\
430
(window-draw-line-xy w x1 y1 x2 y2 \&optional linewidth op)} \\
431
\hspace*{1.0in} {\tt op} may be {\tt xor} or {\tt erase}.
435
(window-draw-arrow-xy w x1 y1 x2 y2 \&optional linewidth size)} \\
437
(window-draw-arrow2-xy w x1 y1 x2 y2 \&optional linewidth size)} \\
439
(window-draw-arrowhead-xy w x1 y1 x2 y2 \&optional linewidth size)}
442
These draw a line with an arrowhead at the second point, a line with an
443
arrowhead at both points, or an arrowhead alone at the second point,
444
respectively. {\tt size} is the arrowhead size; the default is
445
{\tt (+ 20 (* linewidth 5))}.
448
{\tt \hspace*{0.5in} (window-draw-box-xy w x y width height linewidth)} \\
449
{\tt \hspace*{0.5in} (window-xor-box-xy w x y width height linewidth)} \\
450
{\tt \hspace*{0.5in} (window-draw-box w offset:vector size:vector linewidth)} \\
451
{\tt \hspace*{0.5in} (window-draw-box-corners w x1 y1 x2 y2 linewidth)} \\
452
\hspace*{1.0in} where {\tt (x1 y1)} and {\tt (x2 y2)} are opposite corners. \\
453
{\tt \hspace*{0.5in} (window-draw-rcbox-xy w x y width height radius linewidth)} \\
454
\hspace*{1.0in} draws a box with rounded corners.
456
{\tt \hspace*{0.5in} (window-draw-arc-xy w x y radiusx radiusy anglea angleb linewidth)}
459
{\tt anglea} is the angle, in degrees, at which the arc is started.
460
{\tt angleb} is the angle, in degrees, that specifies the amount of arc
461
to be drawn, counterclockwise from the starting position.
464
{\tt \hspace*{0.5in} (window-draw-circle-xy w x y radius linewidth)} \\
465
{\tt \hspace*{0.5in} (window-draw-circle w center:vector radius linewidth)} \\
466
{\tt \hspace*{0.5in} (window-draw-ellipse-xy w x y radiusx radiusy linewidth)} \\
467
{\tt \hspace*{0.5in} (window-draw-dot-xy w x y)}
470
{\tt \hspace*{0.5in} (window-erase-area-xy w left bottom width height)} \\
471
{\tt \hspace*{0.5in} (window-erase-area w offset:vector size:vector)} \\
472
{\tt \hspace*{0.5in} (window-copy-area-xy w fromx fromy tox toy width height)} \\
473
{\tt \hspace*{0.5in} (window-invert-area w offset:vector size:vector)} \\
474
{\tt \hspace*{0.5in} (window-invert-area-xy w left bottom width height)}
477
{\tt \hspace*{0.5in} (window-printat-xy w s x y)} \\
478
{\tt \hspace*{0.5in} (window-printat w s at:vector)} \\
479
{\tt \hspace*{0.5in} (window-prettyprintat-xy w s x y)} \\
480
{\tt \hspace*{0.5in} (window-prettyprintat w s at:vector)} \\
483
The argument {\tt s} is printed at the specified position.
484
{\tt s} is stringified if necessary.
485
Currently, the pretty-print versions are the same as the plain versions.
488
{\tt \hspace*{0.5in} (window-draw-border w)} draws a border just
491
\section{Fonts, Operations, Colors}
493
{\tt \hspace*{0.5in} (window-set-font w font)}
496
The font symbols that are currently defined are {\tt courier-bold-12},
497
{\tt 8x10}, and {\tt 9x15} . The global variable {\tt *window-fonts*}
498
contains correspondences between font symbols and font strings.
499
A font string may also be specified instead of a font symbol.
501
{\tt \hspace*{0.5in} (window-string-width w s)} \\
502
{\tt \hspace*{0.5in} (window-string-extents w s)} \\
503
These give the width and the vertical size {\tt (ascent descent)} in pixels
504
of the specified string {\tt s} using the font of the specified window.
505
{\tt s} is stringified if necessary.
507
Operations on a window other than direct drawing are performed by
508
setting a condition for the window, performing the operation, and then
509
unsetting the condition with {\tt window-unset}. {\tt window-reset}
510
will reset a window to its ``standard'' setting; it is useful primarily
511
for cases in which a program bug causes window settings to be in an
515
{\tt \hspace*{0.5in} (window-set-xor w)} \\
516
{\tt \hspace*{0.5in} (window-set-erase w)} \\
517
{\tt \hspace*{0.5in} (window-set-copy w)} \\
518
{\tt \hspace*{0.5in} (window-set-invert w)} \\
519
{\tt \hspace*{0.5in} (window-unset w)} \\
520
{\tt \hspace*{0.5in} (window-reset w)} \\
522
{\tt \hspace*{0.5in} (window-set-line-width w width)} \\
523
{\tt \hspace*{0.5in} (window-set-line-attr w width \&optional line-style cap-style join-style)} \\
524
{\tt \hspace*{0.5in} (window-std-line-attr w)} \\
526
{\tt \hspace*{0.5in} (window-foreground w)} \\
527
{\tt \hspace*{0.5in} (window-set-foreground w fg-color)} \\
528
{\tt \hspace*{0.5in} (window-background w)} \\
529
{\tt \hspace*{0.5in} (window-set-background w bg-color)} \\
534
The color of the foreground (things that are drawn, such as lines or
535
characters) is set by:
537
{\tt \hspace*{0.5in} (window-set-color w rgb \&optional background)} \\
539
{\tt rgb} is a list {\tt (red green blue)} of 16-bit unsigned integers in
540
the range {\tt 0} to {\tt 65535}. {\tt background} is non-{\tt nil}
541
to set the background color rather than the foreground color.
543
Colors are a scarce resource; there is only a finite number of
544
available colors, such as 256 colors. If you only use a small, fixed set
545
of colors, the finite set of colors will not be a problem. However,
546
if you create a lot of colors that are used only briefly, it will be
547
necessary to release them after they are no longer needed.
548
{\tt window-set-color} will leave the global variable {\tt *window-xcolor*}
549
set to an integer value that denotes an X color; this value should be
550
saved and used as the argument to {\tt window-free-color} to release
551
the color after it is no longer needed.
553
{\tt \hspace*{0.5in} (window-free-color w \&optional xcolor)} \\
555
{\tt window-free-color} frees either the last color used, as given by
556
{\tt *window-xcolor*}, or the specified color.
559
\subsection{Character Input}
561
Characters can be input within a window by the call:
563
{\tt \hspace*{0.5in} (window-input-string w str x y \&optional size)} \\
565
{\tt window-input-string} will print the initial string {\tt str},
567
at the specified position in the window; {\tt str}, if not modified
568
by the user, will also be the initial part of the result. A caret
569
is displayed showing the location of the next input character.
570
Characters are echoed as they are typed; backspacing erases characters,
571
including those from the initial string {\tt str}. An area of width
572
{\tt size} (default 100) is erased to the right of the initial caret.
575
\section{Mouse Interaction}
577
{\tt \hspace*{0.5in} (window-get-point w)} \\
578
{\tt \hspace*{0.5in} (window-get-crosshairs w)} \\
579
{\tt \hspace*{0.5in} (window-get-cross w)} \\
580
These functions get a point position by mouse click; they return {\tt (x y)} .
582
The following function gets a point position by mouse click. It returns
583
{\tt (button (x y))} where {\tt button} is {\tt 1} for the left button,
584
{\tt 2} for middle, {\tt 3} for right.
586
{\tt \hspace*{0.5in} (window-get-click w)} \\
588
The following function gets a point position by mouse click within a specified
589
region. It returns {\tt (button (x y))} or {\tt NIL} if the mouse leaves
590
the region. If {\tt boxflg} is {\tt t}, a box will be drawn outside the
591
region while the mouse is being tracked.
593
{\tt \hspace*{0.5in} (window-track-mouse-in-region w x y sizex sizey \&optional boxflg)} \\
596
The following functions get a point position indicated by drawing a line
597
from a specified origin position to the cursor position; they return
598
{\tt (x y)} at the cursor position when a mouse button is clicked.
599
The {\tt latex} version restricts the slope of the line to be a slope that
600
\LaTeX \ can draw; if {\tt flg} is non-{\tt nil}, the slope is restricted
601
to be a \LaTeX \ {\tt vector} slope.
603
{\tt \hspace*{0.5in} (window-get-line-position w orgx orgy)} \\
604
{\tt \hspace*{0.5in} (window-get-latex-position w orgx orgy flg)} \\
606
The following function gets a position by moving a ``ghost'' icon,
607
defined by the icon drawing function {\tt fn}. This allows exact positioning
608
of an object by the user.
610
{\tt \hspace*{0.5in} (window-get-icon-position w fn args \&optional (dx 0)
614
The function {\tt fn} has arguments {\tt (fn w x y . args)} , where {\tt x}
615
and {\tt y} are the offset within the window {\tt w} at which the icon is
616
to be drawn, and {\tt args} is a list of arbitrary arguments, e.g., the size
617
of the icon, that are passed through to the drawing function.
618
The icon is drawn in {\tt xor} mode, so it must be drawn using
619
only ``plain'' drawing functions, without resetting window attributes.
620
The returned value is {\tt (x y)} at the cursor position when a button
621
is clicked. {\tt dx} and {\tt dy}, if specified, are offsets of {\tt x}
622
and {\tt y} from the cursor position.
624
The following function gets a position by moving a ``ghost'' box icon.
626
{\tt \hspace*{0.5in} (window-get-box-position w width height \&optional (dx 0) (dy 0))} \\
629
By default, the lower-left corner of the box is placed at the cursor position;
630
{\tt dx} and {\tt dy} may be used to offset the box from the cursor, e.g.,
631
to move the box by a different corner. The returned value is {\tt (x y)}
632
at the cursor position when a button is clicked.
634
The following function gets coordinates of a box of arbitrary size and
637
{\tt \hspace*{0.5in} (window-get-region w)} \\
640
The user first clicks for one corner of the box, moves the
641
mouse and clicks again for the opposite corner, then moves the box into
642
the desired position. The returned value is \linebreak
643
{\tt ((x y) (width height))},
644
where {\tt (x y)} is the lower-left corner of the box.
646
The following function gets the size of a box by mouse selection,
647
echoing the size in pixels below the box. {\tt offsety}
648
should be at least {\tt 30} to leave room to display the size of the box.
650
{\tt \hspace*{0.5in} (window-get-box-size w offsetx offsety)} \\
653
The following function adjusts one side of a box.
655
{\tt \hspace*{0.5in} (window-adjust-box-side w x y width height side)} \\
658
{\tt side} specifies the side of the box to be adjusted: {\tt left},
659
{\tt right}, {\tt top}, or {\tt bottom}. The result is
660
{\tt ((x y) (width height))} for the resulting box.
662
{\tt \hspace*{0.5in} (window-get-circle w \&optional center:vector)} \\
663
{\tt \hspace*{0.5in} (window-get-ellipse w \&optional center:vector)} \\
664
These functions interactively get a circle or ellipse. For an ellipse,
665
a circle is gotten first for the horizontal size; then the vertical
666
size of the ellipse is adjusted.
667
{\tt window-get-circle} returns {\tt ((x y) radius)}.
668
{\tt window-get-ellipse} returns {\tt ((x y) (xradius yradius))}.
670
% {\tt \hspace*{0.5in} (window-sync w)} will clear the event queue of any
671
% previous motion events.
673
{\tt window-track-mouse} is the basic function for following the mouse
674
and performing some action as it moves. This function is used in
675
the implementation of menus and the mouse-interaction functions described in
678
{\tt \hspace*{0.5in} (window-track-mouse w fn \&optional outflg)}
681
Each time the mouse position changes or a mouse button is pressed,
682
the function {\tt fn} is called with
683
arguments {\tt (x y code)} where {\tt x} and {\tt y} are the cursor
684
position, {\tt code} is a button code ({\tt 0} if no button, {\tt 1} for
685
the left button, {\tt 2} for the middle button, or {\tt 3} for the right
686
button). {\tt window-track-mouse} continues to track the mouse until {\tt fn}
687
returns a value other than {\tt nil}, at which time {\tt window-track-mouse}
688
returns that value. Usually, it is a good idea for {\tt fn} to return a
689
value other than {\tt nil} upon a mouse click. If the argument {\tt outflg}
690
is non-{\tt nil}, the function {\tt fn} will be called for button clicks
691
outside the window {\tt w}; note, however, that such clicks will not be
692
seen if the containing window intercepts them, so that this feature will
693
work only if the window {\tt w} is inside another Lisp user window.
696
\section{Miscellaneous Functions}
698
{\tt \hspace*{0.5in} (stringify x)} makes its argument into a string.
700
{\tt \hspace*{0.5in} (window-destroy-selected-window)} waits 3 seconds,
701
then destroys the window containing the mouse cursor. This function
702
should be used with care; it can destroy a non-user window, causing
703
processes associated with the window to be destroyed. It is useful
704
primarily in debugging, to get rid of a window that is left on the screen
711
{\tt dec.copyright} & Copyright and license for DEC/MIT files \\
712
{\tt draw.lsp} & GLISP source code for interactive drawing utility \\
713
{\tt drawtrans.lsp} & {\tt draw.lsp} translated into plain Lisp \\
714
{\tt draw-gates.lsp} & Code to draw {\tt nand} gates etc. \\
715
{\tt dwdoc.tex} & \LaTeX \ source for this document \\
716
{\tt dwindow.lsp} & GLISP source code for {\tt dwindow} functions \\
717
{\tt dwtest.lsp} & Examples of use of {\tt dwindow} functions \\
718
{\tt dwtrans.lsp} & {\tt dwindow.lsp} translated into plain Lisp \\
719
{\tt gnu.license} & GNU General Public License \\
720
{\tt ice-cream.lsp} & Drawing of an ice cream cone made with {\tt draw} \\
721
{\tt imports.lsp} & file to import symbols to {\tt :user} package \\
722
{\tt menu-set.lsp} & GLISP source code for menu-set functions \\
723
{\tt pcalc.lsp} & Pocket calculator implemented as a {\tt picmenu} \\
732
(window (listobject (parent drawable)
734
(drawable-height integer)
735
(drawable-width integer)
743
(menu (listobject (menu-window window)
745
(parent-window drawable)
746
(parent-offset-x integer)
747
(parent-offset-y integer)
748
(picture-width integer)
749
(picture-height integer)
754
(item-height integer)
755
(items (listof symbol)) )
761
(picmenu (listobject (menu-window window)
763
(parent-window drawable)
764
(parent-offset-x integer)
765
(parent-offset-y integer)
766
(picture-width integer)
767
(picture-height integer)
770
(spec (transparent picmenu-spec))
772
(deleted-buttons (listof symbol)) )
778
(picmenu-spec (listobject (drawing-width integer)
779
(drawing-height integer)
780
(buttons (listof picmenu-button))
783
(menu-font symbol) ))
789
(picmenu-button (list (name symbol)
792
(highlightfn anything)
793
(unhighlightfn anything))
799
(barmenu (listobject (menu-window window)
801
(parent-window drawable)
802
(parent-offset-x integer)
803
(parent-offset-y integer)
804
(picture-width integer)
805
(picture-height integer)
813
(subtrackfn anything)
814
(subtrackparms (listof anything)))
822
The following copyright notice applies to the portions of the software
823
that were adapted from X Consortium software:
825
;;**********************************************************
826
;;Copyright 1987 by Digital Equipment Corporation, Maynard, Massachusetts,
827
;;and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
829
;; All Rights Reserved
831
;;Permission to use, copy, modify, and distribute this software and its
832
;;documentation for any purpose and without fee is hereby granted,
833
;;provided that the above copyright notice appear in all copies and that
834
;;both that copyright notice and this permission notice appear in
835
;;supporting documentation, and that the names of Digital or MIT not be
836
;;used in advertising or publicity pertaining to distribution of the
837
;;software without specific, written prior permission.
839
;;DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
840
;;ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
841
;;DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
842
;;ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
843
;;WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
844
;;ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
847
;;*****************************************************************
854
% Previous UT copyright:
856
; Copyright 1992, The University of Texas at Austin (UTA). All rights
857
; reserved. By using this software the USER indicates that he or she
858
; has read, understood and will comply with the following:
860
; -UTA hereby grants USER nonexclusive permission to use, copy and/or
861
; modify this software for internal, noncommercial, research purposes only.
862
; Any distribution, including commercial sale or license, of this software,
863
; copies of the software, its associated documentation and/or modifications
864
; of either is strictly prohibited without the prior consent of UTA. Title
865
; to copyright to this software and its associated documentation shall at
866
; all times remain with UTA. Appropriate copyright notice shall be placed
867
; on all software copies, and a complete copy of this notice shall be
868
; included in all copies of the associated documentation. No right is
869
; granted to use in advertising, publicity or otherwise any trademark,
870
; service mark, or the name of UTA. Software and/or its associated
871
; documentation identified as "confidential," if any, will be protected
872
; from unauthorized use/disclosure with the same degree of care USER
873
; regularly employs to safeguard its own such information.
875
; -This software and any associated documentation is provided "as is," and
876
; UTA MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
877
; THOSE OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THAT
878
; USE OF THE SOFTWARE, MODIFICATIONS, OR ASSOCIATED DOCUMENTATION WILL
879
; NOT INFRINGE ANY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER INTELLECTUAL
880
; PROPERTY RIGHTS OF A THIRD PARTY. UTA, the University of Texas System,
881
; its Regents, officers, and employees shall not be liable under any
882
; circumstances for any direct, indirect, special, incidental, or
883
; consequential damages with respect to any claim by USER or any third
884
; party on account of or arising from the use, or inability to use, this
885
; software or its associated documentation, even if UTA has been advised
886
; of the possibility of those damages.
888
; -Submit software operation questions to: Gordon S. Novak Jr., Department
889
; of Computer Sciences, UT, Austin, TX 78712, novak@cs.utexas.edu .
891
; -Submit commercialization requests to: Office of the Executive Vice
892
; President and Provost, UT Austin, 201 Main Bldg., Austin, TX, 78712,
893
; ATTN: Technology Licensing Specialist.
added
removed
xgcl-2/dwdoc.tex
