« back to all changes in this revision
Viewing changes to man/sawfish.texi
- browse files at revision 1.2.10
- compare with another revision
- download diff
- download tarball
- view history from revision 1.2.10
- Committer: Bazaar Package Importer
- Author(s): Luis Rodrigo Gallardo Cruz
- Date: 2009-11-23 09:05:20 UTC
- mfrom: (0.1.1 upstream)
- mto: This revision was merged to the branch mainline in revision 17.
- Revision ID: james.westby@ubuntu.com-20091123090520-m588qe37wtxzr2b5
Tags: upstream-1.5.3
Import upstream version 1.5.3
- files added:
- CONTRIBUTING
- lisp/sawfish/wm/tabs
- m4
- files removed:
- BUGS
- etc
- src/.libexec
- src/.libexec/sawfish
- src/.libexec/sawfish/wm
- src/.libexec/sawfish/wm/util
- files modified:
- .gdbinit
added
removed
man/sawfish.texi
1
\input texinfo @c -*-Texinfo-*-
2
@setfilename sawfish.info
3
@settitle sawfish Programming Manual
4
@footnotestyle end
5
6
@set EDITION 0.14
7
@set VERSION 1.5.0
8
@set UPDATED 02 Apr 2009
9
@set UPDATE-MONTH Apr 2009
10
11
@ifinfo
12
@direntry
13
* sawfish: (sawfish). sawfish programming manual
14
@end direntry
15
16
This is Edition @value{EDITION}, last updated @value{UPDATED}, of
17
@cite{The sawfish Programming Manual}, for sawfish, Version
18
@value{VERSION}.
19
20
Copyright 1999 John Harper.
21
22
Permission is granted to make and distribute verbatim copies of
23
this manual provided the copyright notice and this permission notice
24
are preserved on all copies.
25
26
@ignore
27
Permission is granted to process this file through TeX and print the
28
results, provided the printed document carries copying permission
29
notice identical to this one except for the removal of this paragraph
30
(this paragraph not being relevant to the printed manual).
31
@end ignore
32
33
Permission is granted to copy and distribute modified versions of this
34
manual under the conditions for verbatim copying, provided that the entire
35
resulting derived work is distributed under the terms of a permission
36
notice identical to this one.
37
@end ifinfo
38
39
@titlepage
40
@title sawfish
41
@subtitle An Extensible X11 Window Manager
42
@subtitle Programming Manual
43
@subtitle Edition @value{EDITION}
44
@subtitle @value{UPDATE-MONTH}
45
@author John Harper
46
@page
47
@vskip 0pt plus 1filll
48
Copyright @copyright{} 1999 John Harper.
49
50
Permission is granted to make and distribute verbatim copies of
51
this manual provided the copyright notice and this permission notice
52
are preserved on all copies.
53
54
Permission is granted to copy and distribute modified versions of this
55
manual under the conditions for verbatim copying, provided that the entire
56
resulting derived work is distributed under the terms of a permission
57
notice identical to this one.
58
@end titlepage
59
60
@node Top, Copying, (dir), (dir)
61
62
@ifnottex
63
This document describes the Lisp programming interface to
64
@code{sawfish}, an extensible X11 window manager.
65
66
This is Edition @value{EDITION} of its documentation,
67
last updated @value{UPDATED} for Sawfish version @value{VERSION}.
68
@end ifnottex
69
70
@menu
71
* Copying:: Distribution conditions
72
* Introduction:: Brief introduction to sawfish
73
* News:: Feature history
74
75
* Colors:: Color type
76
* Fonts:: Font type
77
* Images:: Image type
78
* Cursors:: Cursor type
79
* Windows:: Window type
80
* Customization:: Supporting user-configuration
81
82
* Window Frames:: Decorating windows
83
* Viewports:: Subdivided desktop areas
84
* Workspaces:: Multiple desktop areas
85
* Multi-Head Environments:: Multiple monitors
86
* Window Placement:: Controlling placement of new windows
87
* Popup Menus:: Displaying menus
88
* Events:: Input event types
89
* Commands:: Functions you can invoke interactively
90
* Keymaps:: Bindings events to actions
91
* Event Loop:: Handling input events
92
* Miscellaneous Functions:: Useful features
93
* Standard Hooks:: Hooking into wm actions
94
* Standard Properties:: Window properties
95
* Session Management:: Saving state across sessions
96
* Low-level X Interface:: Accessing the server directly
97
98
* FAQ:: Frequently asked questions
99
100
* Function Index:: Menu of all documented functions
101
* Variable Index:: All variables which have been mentioned
102
* Concept Index:: Main index, references to all sections
103
@end menu
104
105
@node Copying, Introduction, Top, Top
106
@chapter Copying
107
@cindex Copying
108
109
Sawfish is copyright (C) 1999 John Harper and is released under the
110
terms of the GNU General Public License. See the included file
111
@file{COPYING} for the full text of the license (or @pxref{Copying, ,
112
Copying, emacs, The GNU Emacs Manual}).
113
114
@quotation
115
This is free software -- you are welcome to redistribute it and/or
116
modify it under the terms of the GNU General Public License as
117
published by the Free Software Foundation; either version 2, or
118
(at your option) any later version.
119
120
Sawfish is distributed in the hope that it will be useful, but
121
WITHOUT ANY WARRANTY; without even the implied warranty of
122
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
123
GNU General Public License for more details.
124
@end quotation
125
126
127
@node Introduction, News, Copying, Top
128
@chapter Introduction
129
@cindex Introduction
130
131
Sawfish is a lisp-extensible window manager for X11. Its aim is to
132
allow all areas of window management (decoration, manipulation) to be
133
customized as far as is possible, yet still remain as fast or faster
134
than existing window managers.
135
136
Despite this extensibility its policy is very minimal compared to most
137
window managers. It does not implement desktop backgrounds,
138
applications docks, or other things that may be achieved through
139
separate applications.
140
141
All high-level window management functions are implemented in Lisp for
142
future extensibility or redefinition. Also, most received events are
143
exported to the Lisp environment through key-bindings and hooks,
144
similar to in Emacs. These events include pointer behavior and many
145
internal X11 events.
146
147
Sawfish uses the librep Lisp environment (@pxref{Top, , Overview,
148
librep, The Librep Manual}), this is a run-time library implementing a
149
language similar to Emacs Lisp (@pxref{Top, , Overview, elisp, The
150
Emacs-Lisp Manual}), but with many extensions, and using lexical
151
instead of dynamic scope. This manual assumes at least a basic
152
knowledge of the language.
153
154
Homepage and mailing list are listed in @xref{FAQ}.
155
156
@node News, Colors, Introduction, Top
157
158
@include news.texi
159
160
161
@node Colors, Fonts, News, Top
162
@chapter Colors
163
@cindex Colors
164
165
Sawfish provides a primitive type allowing colors to be represented.
166
Each color object allows a single color value to be named and passed
167
between Lisp functions.
168
169
@defun colorp arg
170
Returns @code{t} when @var{arg} is a member of the color type.
171
@end defun
172
173
@defun get-color name &optional alpha
174
Returns the color object representing the color specified by the string
175
@var{name}. This is according to the standard X11 color specifiers,
176
either a named color from the @file{rgb.txt} database, or a string
177
defining the red, green and blue components of the color, either eight
178
or sixteen bits in hexadecimal, i.e. @samp{#RRGGBB} or
179
@samp{#RRRRGGGGBBBB}.
180
181
Optional argument @var{alpha} becomes the alpha value of
182
the returned color. It is passed through to @code{get-color-rgb}.
183
184
Signals an error if no known color has the name @var{name}.
185
@end defun
186
187
@defun get-color-rgb red green blue &optional alpha
188
Return the color object representing the color with RGB components as
189
specified (each component ranging from 0 to 65535).
190
191
Optional argument @var{alpha} becomes the alpha value of the returned
192
color. Use an integer value in the range from 0 to 65535. Integers
193
outside that range are not supported, while non-integers such as
194
@code{nil} are silently converted to 65535 (fully opaque).
195
@end defun
196
197
Given a color object, it's possible to find both the actual rgb values
198
defining the color and one of the names that X11 uses to refer to the
199
color.
200
201
@defun color-rgb color
202
Return a list of integers @code{(@var{red} @var{green} @var{blue}
203
@var{alpha})}, the actual color values of the color represented by
204
object COLOR. The individual values range from 0 to 65535.
205
@end defun
206
207
@defun color-rgb-8 color
208
Return a list of integers @code{(@var{red} @var{green} @var{blue}
209
@var{alpha})}, just like @code{color-rgb}. However, the color values
210
are scaled to fit a range from from 0 to 255.
211
@end defun
212
213
@defun color-name color
214
Return the name of the color represented by the color object
215
@var{color}. Note that this picks one name from the set of valid
216
names for this color; it may well be different to the name used when
217
the color was originally allocated.
218
219
The X11 name does not include alpha information.
220
@end defun
221
222
Where a color object is used to define the foreground color of a piece
223
of text, the @code{default-foreground} color provides the default value
224
used if no actual color is specified.
225
226
@defvar default-foreground
227
The color used for text where no other color is defined.
228
@end defvar
229
230
231
@node Fonts, Images, Colors, Top
232
@chapter Fonts
233
@cindex Fonts
234
235
As with the color type, the font type allows X11 fonts to be
236
manipulated by Lisp code.
237
238
@defun fontp arg
239
Returns @code{t} if @var{arg} is a font object.
240
@end defun
241
242
Sawfish supports two types of fonts: X11 core fonts (fontsets and
243
fontstructs) and Xft fonts. Calling code must look up fonts by
244
giving both a name and a type: an @code{xlfd} argument indicates the
245
core fonts, and @code{Xft} indicates Xft fonts. These types are
246
always literal strings.
247
248
@defun font-type-exists-p type
249
Returns true if fonts with the type described by the string @var{type}
250
can be loaded, false otherwise.
251
@end defun
252
253
@defun get-font-typed type name
254
Return a font object representing the X11 font specified by the string
255
@var{name}. Argument @var{type} indicates the type of font to look
256
for; it must be one of the strings @code{xlfd} for a X11 core fonts
257
(based on fontsets or a fontstructs), or @code{Xft} for an Xft font.
258
259
Signals an error if @var{type} is not one of the literal strings
260
listed above. Also signals an error if no font named @var{name}
261
can be found within the requested type.
262
@end defun
263
264
@defun get-font name
265
Return a font object representing the X11 core font (fontset or
266
fontstruct) specified by the string @var{name}.
267
268
Signals an error if no font named @var{name} is available among the
269
X11 core fonts.
270
@end defun
271
272
Several functions allow the attributes associated with a font object to
273
be found.
274
275
@defun font-name font
276
Returns the name of the X11 font represented by object @var{font} (a
277
string).
278
@end defun
279
280
@defun font-type font
281
Returns a string indicating the font's class. This is @code{xlfd}
282
for X11 core fonts, or @code{Xft} for Xft fonts.
283
@end defun
284
285
@defun font-height font
286
Returns the bounding height of glyphs in the font represented by object
287
@var{font}.
288
@end defun
289
290
@defun font-ascent &optional font
291
Returns the ascent of glyphs rendered using the font represented by
292
@var{font}. If no font argument is given, use the default font.
293
@end defun
294
295
@defun font-descent &optional font
296
Returns the descent of glyphs rendered using the font represented by
297
@var{font}. If no font argument is given, use the default font.
298
@end defun
299
300
@defun text-width string &optional font
301
Returns the number of horizontal pixels that would be required to
302
display the text @var{string} using font object @var{font} (or the
303
value of the @code{default-font} variable if @var{font} is undefined).
304
@end defun
305
306
As with colors, a default font may be specified, to be used where no
307
other font is specified.
308
309
@defvar default-font
310
Font object used when no other font has been specified.
311
@end defvar
312
313
Fonts can have Lisp properties associated with them (similar to the
314
property lists associated with symbols). Currently these aren't
315
actually used by the window manager.
316
317
@defun font-put font property value
318
Associate the lisp object @var{value} with the property named by the
319
symbol @var{property} of the font object @var{font}.
320
@end defun
321
322
@defun font-get font property
323
Return the value of the property named by the symbol @var{property} of
324
the font @var{font}, or @code{nil} if no such property exists.
325
@end defun
326
327
@defvar fonts-are-fontsets
328
True if the X fonts in use are fontsets. This will be false if
329
@code{setlocale} fails, or returns an ASCII locale, or if X doesn't
330
support the locale.
331
@end defvar
332
333
334
@node Images, Cursors, Fonts, Top
335
@chapter Images
336
@cindex Images
337
338
The image type allows arbitrary 24-bit images to be manipulated by the
339
window manager. Images may be both loaded from files, and rendered
340
dynamically.
341
342
@defun imagep arg
343
Returns @code{t} when @var{arg} is a member of the image type.
344
@end defun
345
346
@defun make-image file-name &optional plist
347
Creates and returns an image object containing the image defined by the
348
contents of the file named @var{file-name} (a string). The
349
@code{image-load-path} directory provides the search path used while
350
trying to find a directory containing the file named @var{file-name}.
351
352
All common image formats will likely be able to be loaded. But PNG,
353
JPEG and XPM should always be supported.
354
355
Argument @var{plist} becomes the property list of the returned image.
356
357
Signals an error if file called @var{file-name} may be found, or if an
358
image may not be constructed from the file.
359
@end defun
360
361
@defvar image-directory
362
Directory containing built-in Sawfish images. By default, this is
363
@code{@var{sawfish-directory}/images}.
364
@end defvar
365
366
@defvar image-load-path
367
A list of directory names. This defines the search path used when
368
loading images. By default, this is @code{("."
369
@var{image-directory})}. Modifying @var{image-directory} does not
370
modify @var{image-load-path}.
371
@end defvar
372
373
@defun make-sized-image width height &optional color
374
Create and return a new image, of size @var{width}, @var{height}. If
375
@var{color} is defined it specifies the color of all pixels in the
376
image. If undefined, all pixels will be black.
377
@end defun
378
379
@defun make-image-from-x-drawable id &optional mask-id
380
Create and return an new image. The image is constructed by copying
381
an X Drawable (identified by @var{id}) into a Sawfish image object.
382
The function automatically handles depth conversion.
383
384
If @var{mask-id} is given, it identifies another X Drawable. Black
385
pixels in this drawable indicate transparent pixels in the image
386
object (non-black pixels have no effect on the image object).
387
@end defun
388
389
@defun copy-image image
390
Returns a newly allocated image object, an exact copy of the image
391
object @var{image}.
392
@end defun
393
394
@defun image-dimensions image
395
Returns a cons-cell @code{(@var{width} . @var{height})} defining the
396
dimensions of the image represented by @var{image}.
397
@end defun
398
399
@defun flip-image-horizontally image
400
Flip the contents of @var{image} about the vertical axis.
401
This is a mutating operation that returns the modified argument.
402
@end defun
403
404
@defun flip-image-vertically image
405
Flip the contents of @var{image} about the horizontal axis.
406
This is a mutating operation that returns the modified argument.
407
@end defun
408
409
@defun flip-image-diagonally image
410
Flip the contents of @var{image} about an axis running from the
411
top-left corner to the bottom-right corner of the image.
412
This is a mutating operation that returns the modified argument.
413
@end defun
414
415
As with many of the other types, arbitrary state may be associated with
416
image objects.
417
418
@defun image-put image property value
419
Set the property named @var{property} (a symbol) of @var{image} to
420
@var{value}.
421
@end defun
422
423
@defun image-get image property
424
Return the property named @var{property} of @var{image}, or @code{nil}
425
if no such property exists.
426
@end defun
427
428
The only predefined property is the symbol @code{tiled}, used when an
429
image is displayed in a window decoration. When set to a non-nil value
430
the image is not scaled to the size of the decoration (the default),
431
but is tiled across the decoration.
432
433
When images are scaled across border decorations the pixels that are
434
actually scaled are defined by the @dfn{border} of the image. The
435
border defines the outer rectangle of pixels that are left as-is, and
436
the inner rectangle which is scaled.
437
438
@defun image-border image
439
Returns a list of integers @code{(@var{left} @var{right} @var{top}
440
@var{bottom})}, the border of the image object @var{image}.
441
442
The number associated with each edge of the image defines the number of
443
pixels adjacent to that edge that @emph{will not} be scaled.
444
@end defun
445
446
@defun set-image-border image left right top bottom
447
Sets the border of @var{image}.
448
449
The number associated with each edge of the image defines the number of
450
pixels adjacent to that edge that @emph{will not} be scaled.
451
@end defun
452
453
The shape of the image may also be specified, this defines which pixels
454
are treated as being transparent. Each image may define a single color
455
as marking transparent pixels.
456
457
Image shapes are not supported under GDK Pixbuf. Sawfish will
458
print a diagnostic message to @code{STDERR} if the function is called
459
without being supported.
460
461
@defun image-shape-color image
462
Return the color marking transparent pixels in @var{image}, or
463
@code{nil} if no such color has been specified.
464
@end defun
465
466
@defun set-image-shape-color image color
467
Specify that @var{color} marks transparent pixels in @var{image}.
468
@end defun
469
470
It's also possible to define @dfn{color modifiers} for each image.
471
These define the transformation applied to the value of each pixel when
472
it is displayed. Four different modifiers exist for each image, one for
473
each color component, and one for the image as a whole.
474
475
@defun image-modifier image type
476
Return the modifier defined by the symbol @var{type} of @var{image}, a
477
list of integers @code{(@var{gamma} @var{brightness} @var{contrast})}.
478
Each integer has a value between zero and 255 representing the weight
479
applied to the associated attribute when rendering the image.
480
481
The four types are @code{red}, @code{green}, @code{blue} and @code{nil}
482
(all colors). The argument must be @code{eq} to one of those symbols.
483
@end defun
484
485
@defun set-image-modifier image type gamma brightness contrast
486
Set the image modifier of @var{image} defined by @var{type}.
487
@var{Type} may be one of the values of (not the symbols) @code{red},
488
@code{green} or @code{blue}.
489
@end defun
490
491
There are also several other functions manipulating images:
492
493
@defun bevel-image image border upwards &optional bevel-percent
494
Transform the edgemost pixels of @var{image} to give it a ``bevelled''
495
effect. @var{BORDER} is an integer defining the width of the bevel. If
496
@var{upwards} is non-nil the bevel is raised, otherwise it is lowered.
497
498
If @var{bevel-percent} is defined it specifies the height or depth of
499
the drawn bevel. When undefined, the value of the parameter is taken
500
from the @code{default-bevel-percent} variable.
501
@end defun
502
503
@defvar default-bevel-percent
504
Default height of drawn bevels, as a percentage. Normally 50%.
505
@end defvar
506
507
@defun clear-image image &optional color
508
Set all pixels in @var{image} to @var{color} (or black if @var{color}
509
is undefined).
510
@end defun
511
512
@defun tile-image dest-image source-image
513
Tiles @var{source-image} into @var{dest-image}, starting from the
514
upper-left corner, working outwards.
515
@end defun
516
517
@defun scale-image image width height
518
Return a copy of @var{image}, scaled to @var{width} by @var{height}
519
pixels.
520
@end defun
521
522
@defun composite-images image1 image2 &optional x y
523
Copy the contents of @var{image2} into @var{image1}. @var{Image2} is
524
cropped to fit. Arguments @var{x} and @var{y} indicate the position
525
in @var{image1} of the top-left corner of @var{image2}. If not
526
supplied, they default to 0.
527
@end defun
528
529
@defun crop-image image x y width height
530
Return a new image that is a rectangular section of @var{image}. The
531
result image starts at pixel (@var{x}, @var{y}) in @var{image}, and
532
extends over @var{width} and @var{height} pixels in @var{image}.
533
534
When the cropped image extends beyond the boundary of @var{image}, the
535
behavior is undefined.
536
@end defun
537
538
The following functions allow users to manipulate images on a
539
pixel-by-pixel level. They all use a list representation for pixels:
540
(@var{r}, @var{g}, @var{b}, @var{a}) indicating the red, green, blue
541
and alpha components
542
543
@defun image-ref image x y
544
Return a list (@var{r}, @var{g}, @var{b}, @var{a}) of the red, green,
545
blue and alpha components of the pixel (@var{x}, @var{y}) in
546
@var{image}.
547
548
When the pixel position extends outside the bounds of the image, the
549
behavior is undefined.
550
@end defun
551
552
@defun image-set image x y pixel
553
Set the pixel at (@var{x}, @var{y}) in @var{image} to @var{pixel}.
554
@var{Pixel} is a list of four numbers (@var{r}, @var{g}, @var{b},
555
@var{a}), the red, green, blue and alpha components.
556
557
When the pixel position extends outside the bounds of the image, the
558
behavior is undefined.
559
@end defun
560
561
@defun image-map xform image
562
Transform each pixel in @var{image} in place by calling @var{xform} on
563
each pixel in the image.
564
565
@var{Xform} takes a single argument, a four element list (@var{r},
566
@var{g}, @var{b}, @var{a}) indicating the red, green, blue and alpha
567
components of a pixel. @var{Xform} should return the new value for
568
the pixel it was given. The return format is the same four-element
569
list.
570
571
@var{Xform} is allowed to return @code{nil}. In this case,
572
@code{image-map} immediately returns an invalid object.
573
@end defun
574
575
@defun image-fill generator image
576
Set each pixel in @var{image} based on the results of calling
577
@var{generator}.
578
579
@var{Generator} takes two arguments: the X and Y coordinates of a
580
pixel. It returns a four element list (@var{r}, @var{g}, @var{b},
581
@var{a}) indicating the red, green, blue and alpha components of a
582
pixel. This new pixel replaces the current pixel contents at (X, Y).
583
584
@var{Generator} is allowed to return @code{nil}. In this case,
585
@code{image-map} immediately returns an invalid object.
586
@end defun
587
588
@defun pixmap-cache-control max
589
Tell Sawfish to cache no more than @var{max} pixels. Returns a
590
four-element list indicating the current cache status:
591
@code{(@var{max-cached-pixels}, @var{cached-pixels}, @var{hits},
592
@var{misses})}.
593
@end defun
594
595
596
@node Cursors, Windows, Images, Top
597
@chapter Cursors
598
@cindex Cursors
599
600
Cursors define the shape and hot-spot of the mouse pointer's image. A
601
lisp type is provided for manipulating these objects. In addition,
602
Sawfish provides functions for manipulating the position of the
603
cursor.
604
605
@menu
606
* Cursor Appearance::
607
* Cursor Positioning::
608
@end menu
609
610
@node Cursor Appearance, Cursor Positioning, Cursors, Cursors
611
@section Cursor Appearance
612
613
@defun cursorp arg
614
Returns @code{t} if @var{arg} is a member of the cursor type.
615
@end defun
616
617
@defun get-cursor data
618
Returns the cursor object representing the cursor defined by
619
@var{data}. If @var{data} is a symbol, it's replaced by its
620
@code{cursor-shape} property.
621
622
Possible @var{data} values are an integer representing a glyph in the
623
standard X11 cursor font, or a four-element vector.
624
625
The format for a vector is @code{[@var{image} @var{mask} @var{fg}
626
@var{bg}]} where @var{image} and @var{mask} are the filenames of
627
standard X11 bitmaps, and @var{fg} and @var{bg} are colors (or names of
628
colors). All bitmap files are searched for using the
629
@code{image-load-path} variable.
630
@end defun
631
632
@defun recolor-cursor cursor fg bg
633
Change the colors of the cursor object @var{cursor} to @var{fg} and
634
@var{bg} (either color objects or the names of colors).
635
@end defun
636
637
@defun default-cursor &optional cursor
638
Set the cursor object displayed in the root window, and in parts of
639
window frames that have no other cursor specified, to @var{cursor}.
640
641
If called with no argument, simply return the current such cursor
642
object.
643
@end defun
644
645
So that the integer indices of glyphs in the X11 cursor font do not
646
have to be remembered, the @code{cursor-shape} properties of the
647
following symbols are automatically set:
648
649
@noindent
650
@code{X_cursor}, @code{arrow}, @code{based_arrow_down},
651
@code{based_arrow_up}, @code{boat}, @code{bogosity},
652
@code{bottom_left_corner}, @code{bottom_right_corner},
653
@code{bottom_side}, @code{bottom_tee}, @code{box_spiral},
654
@code{center_ptr}, @code{circle}, @code{clock}, @code{coffee_mug},
655
@code{cross}, @code{cross_reverse}, @code{crosshair},
656
@code{diamond_cross}, @code{dot}, @code{dotbox}, @code{double_arrow},
657
@code{draft_large}, @code{draft_small}, @code{draped_box},
658
@code{exchange}, @code{fleur}, @code{gobbler}, @code{gumby},
659
@code{hand1}, @code{hand2}, @code{heart}, @code{icon},
660
@code{iron_cross}, @code{left_ptr}, @code{left_side}, @code{left_tee},
661
@code{leftbutton}, @code{ll_angle}, @code{lr_angle}, @code{man},
662
@code{middlebutton}, @code{mouse}, @code{pencil}, @code{pirate},
663
@code{plus}, @code{question_arrow}, @code{right_ptr},
664
@code{right_side}, @code{right_tee}, @code{rightbutton},
665
@code{rtl_logo}, @code{sailboat}, @code{sb_down_arrow},
666
@code{sb_h_double_arrow}, @code{sb_left_arrow}, @code{sb_right_arrow},
667
@code{sb_up_arrow}, @code{sb_v_double_arrow}, @code{shuttle},
668
@code{sizing}, @code{spider}, @code{spraycan}, @code{star},
669
@code{target}, @code{tcross}, @code{top_left_arrow},
670
@code{top_left_corner}, @code{top_right_corner}, @code{top_side},
671
@code{top_tee}, @code{trek}, @code{ul_angle}, @code{umbrella},
672
@code{ur_angle}, @code{watch}, @code{xterm}.
673
674
The glyphs associated with these names are shown in Appendix I, of
675
Volume Two, @cite{Xlib Reference Manual}.
676
677
@node Cursor Positioning, , Cursor Appearance, Cursors
678
@section Cursor Positioning
679
680
Sawfish provides one basic command for adjusting the relative position
681
of the cursor.
682
683
@defun move-cursor right down
684
Move the cursor @var{right} pixels to the right across the screen, and
685
@var{down} pixels down the screen. The cursor stops at the edge of
686
the screen (although in multi-head environments, this may not be at
687
the edge of the display).
688
@end defun
689
690
There are also more specialized cursor movement commands.
691
692
@defun move-cursor-left-fine
693
@defunx move-cursor-right-fine
694
@defunx move-cursor-up-fine
695
@defunx move-cursor-down-fine
696
Move the cursor 1 pixel in the indicated direction.
697
@end defun
698
699
@defun move-cursor-left
700
@defunx move-cursor-right
701
@defunx move-cursor-up
702
@defunx move-cursor-down
703
Move the cursor @code{move-cursor-increment} pixels in the indicated
704
direction.
705
@end defun
706
707
@defvar move-cursor-increment 16
708
The @code{move-cursor-@var{DIRECTION}} functions move this cursor this
709
many pixels at a time.
710
@end defvar
711
712
@node Windows, Customization, Cursors, Top
713
@chapter Windows
714
@cindex Windows
715
716
One of the most important data types in sawfish is the window type. All
717
managed client windows have a single window object associated with
718
them.
719
720
@defun windowp arg
721
Returns @code{t} if @var{arg} is a member of the window type, and has a
722
client window associated with it.
723
@end defun
724
725
@defun managed-windows
726
Returns a list containing all managed window objects, in the order that
727
they were adopted by the window manager (first to last).
728
@end defun
729
730
@defun get-window-by-id xid
731
Return a window object with id @var{xid}, or @code{nil}.
732
@end defun
733
734
@defun get-window-by-name name
735
Return a window object with name @var{name}, or @code{nil}.
736
@end defun
737
738
@defun get-window-by-name-re name
739
Return a window object with name matching regular expression
740
@var{name}, or @code{nil}.
741
@end defun
742
743
@defun activate-window window
744
Do everything necessary to make @var{window} active, including raising
745
it, giving it focus, etc. Certain steps may be skipped (e.g., giving
746
focus) if the window doesn't allow that operation.
747
@end defun
748
749
@defun filter-windows pred
750
Return the list of windows (mapped or unmapped) that match the
751
predicate function @var{pred}.
752
@end defun
753
754
@defun map-windows function
755
Call @code{(@var{function} @var{window})} on all existing windows.
756
Returns the value of the last @var{function} invocation. If any
757
@var{function} returns @code{nil}, @code{map-windows} returns
758
@code{nil} immediately.
759
@end defun
760
761
@defun window-class window
762
Return the class that @var{window} belongs to as a string, or nil if
763
@var{window} has no associated class.
764
@end defun
765
766
@defun get-window-wm-protocols window
767
Return a list of symbols defining the X11 window manager protocols
768
supported by client @var{window}.
769
@end defun
770
@defun window-supports-wm-protocol-p window atom
771
Return true if @var{window} includes @var{atom} in its
772
@code{WM_PROTOCOLS} property.
773
@end defun
774
775
@menu
776
* Window Property Lists::
777
* Window Types::
778
* Window Attributes::
779
* Input Focus::
780
* X Properties::
781
* Window Stacking::
782
* Moving and Resizing Windows::
783
* Showing and Hiding Windows::
784
* Destroying Windows::
785
* Shading Windows::
786
* Iconifying Windows::
787
* Window Stickiness::
788
* Ignored Windows::
789
* Avoided Windows::
790
* Maximizing Windows::
791
* Animating Windows::
792
* Cycling Between Windows::
793
* Window Groups::
794
@end menu
795
796
797
@node Window Property Lists, Window Types, , Windows
798
@section Window Property Lists
799
@cindex Window property lists
800
@cindex Property lists, of windows
801
802
Many window manager extensions need to be able to associate Lisp data
803
with individual windows. For example, the module handling iconification
804
needs to associate a boolean value with each window---whether that
805
window is iconified or not.
806
807
To solve this problem, Sawfish gives each window a property list. These
808
are exactly analogous to the property lists stored with each symbol
809
(@pxref{Property Lists, , Property Lists, librep, The Librep Manual});
810
they allow values to be associated with Lisp symbols, for a particular
811
window.
812
813
Note that these properties are different to the properties that X
814
stores with each window, since these properties are internal to the
815
window manager (@pxref{X Properties}).
816
817
For a list of the standard window properties, see @ref{Standard Properties}.
818
819
@defun window-put window property value
820
Set the lisp property named @var{property} (a symbol) associated with
821
window object @var{window} to @var{value}. Note that these are Lisp
822
properties not X properties.
823
@end defun
824
825
@defun window-get window property &optional checker
826
Return the window property named @var{property} (a symbol) associated
827
with the window object @var{window}, or @code{nil} if no such property
828
exists. Note that these are Lisp properties not X properties.
829
830
If the optional third argument @var{checker} is non-nil, then @var{checker}
831
is returned if the requested property does not exist. This is used to
832
distinguish the assigned value of @code{nil} from property's absence.
833
A symbol is usually a good choice for @var{checker}.
834
@end defun
835
836
@defun map-window-properties function window
837
Call @code{(@var{function} @var{property} @var{value})} on each of the
838
Lisp properties bound to @var{window}. Returns the value of the last
839
@var{function} invocation. If any @var{function} returns @code{nil},
840
@code{map-window-properties} returns @code{nil} immediately.
841
@end defun
842
843
@defun window-plist window
844
Returns the property list of the window @var{window} which is of the form
845
@code{(prop value prop value ...)}.
846
847
Do not attempt to change properties by modifying the property list in place.
848
Use window-put instead.
849
@end defun
850
851
@defun window-remprop window property
852
Remove @var{property} of @var{window}. Returns @code{t} for success,
853
@code{nil} if the property did not exist.
854
@end defun
855
856
@node Window Types, Window Attributes, Window Property Lists, Windows
857
@section Window Types
858
@cindex Window types
859
@cindex Types, of windows
860
@cindex Windows, types of
861
862
Transient windows are pop-up or dialog windows associated with a main
863
application. They tend to have less window decorations, and are
864
intended to last a short time only.
865
866
@defun window-transient-p arg
867
Returns @code{t} if @var{arg} represents a transient window.
868
@end defun
869
870
@defun mark-window-as-transient w
871
Mark that the window associated with object @var{w} is a transient
872
window.
873
@end defun
874
875
@defun transient-of-p child parent
876
Return true if window @var{child} is directly a transient for window
877
@var{parent}, false otherwise.
878
@end defun
879
880
@defun indirect-transient-of-p descendant ancestor
881
Return true if window @var{descendant} is (directly or indirectly) a
882
transient for window @var{ancestor}, false otherwise.
883
@end defun
884
885
@defun transient-parents child &optional indirectly
886
Return the list of windows that window @var{child} is a transient
887
for. If @var{indirectly} is true, then return the list of all
888
ancestors rather than parents.
889
@end defun
890
891
@defun transient-children parent &optional indirectly
892
Return the list of windows that are transients for window
893
@var{parent}. If @var{indirectly} is true, then return the list of
894
all descendants rather than children.
895
@end defun
896
897
@defun transient-group window &optional by-depth
898
Return the list of windows which is either a transient window for
899
window @var{window}, or a window which @var{window} is a transient
900
for. This always includes W. The `transient window for' relation holds
901
for windows which are direct or indirect transients of the parent
902
window in question.
903
904
If the @var{by-depth} argument is true, then the retrurned list is in
905
stacking order.
906
@end defun
907
908
@defun map-transient-group fun window
909
Map the single argument function @var{fun} over all windows in the same
910
transient group as window @var{window}.
911
@end defun
912
913
@defun raise-window-and-transients window
914
Raise window @var{window} to its highest allowed position in the
915
stacking order. Also raise any transient windows that it has.
916
@end defun
917
918
@defun lower-window-and-transients window
919
Lower window @var{window} to its lowest allowed position in the
920
stacking order. Also lower any transient windows that it has.
921
@end defun
922
923
@defun raise-lower-window-and-transients window
924
If window @var{window} is at its highest possible position, then lower
925
it to its lowest possible position. Otherwise raise it as far as
926
allowed. Also changes the level of any transient windows it has.
927
@end defun
928
929
@defvr Customizable focus-windows-when-mapped
930
Focus on application windows when they first appear. Defaults to
931
true, must be true or false.
932
@end defvr
933
934
@defvar decorate-transients
935
Decorate dialog windows similarly to application windows. Defaults to
936
false.
937
@end defvar
938
939
Desktop windows are root windows or viewport windows.
940
941
@defun desktop-window-p arg
942
Returns @code{t} if @var{arg} represents a desktop window.
943
@end defun
944
945
@defun mark-window-as-desktop w
946
Mark that the window associated with object @var{w} is a desktop
947
window.
948
@end defun
949
950
@defvar desktop-window-properties
951
List of properties set (to true) on windows marked as desktops.
952
Defaults to
953
@lisp
954
'(fixed-position sticky sticky-viewport)
955
@end lisp
956
@end defvar
957
958
@defvar desktop-window-depth
959
The stacking depth of desktop windows. Defaults to -4.
960
@end defvar
961
962
Dock windows are simply those with the @code{dock-type} property.
963
GNOME panels are one example. Sawfish does not currently assign them
964
any special behavior.
965
966
@defun dock-window-p arg
967
Returns @code{t} if @var{arg} represents a dock window.
968
@end defun
969
970
@defun mark-window-as-dock w
971
Mark that the window associated with object @var{w} is a dock
972
window.
973
@end defun
974
975
@defvar dock-window-properties
976
List of properties set (to true) on windows marked as docks.
977
Defaults to
978
@lisp
979
'(window-list-skip cycle-skip fixed-position focus-click-through
980
avoid no-history never-iconify never-maximize sticky
981
sticky-viewport placed)
982
@end lisp
983
@end defvar
984
985
@defvar dock-window-depth
986
The stacking depth of dock windows. Defaults to 0.
987
@end defvar
988
989
@node Window Attributes, Input Focus, Window Types, Windows
990
@section Window Attributes
991
@cindex Window attributes
992
@cindex Attributes, of windows
993
@cindex Windows, attributes of
994
995
@defun window-name window
996
Return the name associated with @var{window}.
997
@end defun
998
999
@defun window-full-name window
1000
Return the full-name associated with @var{window}. This may or may not
1001
be the same as the normal name.
1002
@end defun
1003
1004
Sawfish provides functions to ensure that window names are unique.
1005
1006
@defun uniquify-name proposal existing
1007
Uniquify the string @var{proposal} against the list of strings
1008
@var{existing}. Uses the format string @code{uniquify-name-format} to
1009
generate unique names.
1010
@end defun
1011
1012
@defvar uniquify-name-format
1013
Format to create unique window names. Defaults to @code{"%s [%d]"}.
1014
@end defvar
1015
1016
@deffn Function uniquify-window-name window
1017
@deffnx Command uniquify-window-name window
1018
Force @var{window} to have a unique title.
1019
@end deffn
1020
1021
@defun window-icon-name window
1022
Return the icon name associated with @var{window}.
1023
@end defun
1024
1025
@defun window-mapped-p window
1026
Return @code{t} if the client window associated with object
1027
@var{window} is mapped. (Note that this doesn't necessarily mean that
1028
it is visible.)
1029
@end defun
1030
1031
@defun window-transient-p window
1032
Returns @code{nil} if @var{window} isn't marked as a transient window.
1033
Otherwise returns an integer, the xid of the parent window.
1034
@end defun
1035
1036
@defun window-shaped-p window
1037
Return @code{t} if @var{window} is shaped (possibly not rectangular).
1038
@end defun
1039
1040
@defun window-id window
1041
If window object @var{window} has a client window associated with,
1042
return an integer defining its xid, otherwise return @code{nil}.
1043
@end defun
1044
1045
@defun root-window-id
1046
Returns the numeric ID of the root window of the managed screen.
1047
@end defun
1048
1049
@defun window-group-id window
1050
If @var{window} is part of a group, return the X window id of the
1051
leader of that group. Otherwise return @code{nil}.
1052
@end defun
1053
1054
@defun window-wants-input-p window
1055
Return @code{t} when the client window associated with object
1056
@var{window} has asked for the input focus to be assigned to it when
1057
applicable (through the @code{input} field of its @code{WM_HINTS}
1058
property).
1059
@end defun
1060
1061
@defun window-really-wants-input-p window
1062
Return @code{nil} if the client window associated with object
1063
@var{window} should never be focused, @code{t} otherwise.
1064
@end defun
1065
1066
@defun window-dimensions window
1067
Returns a cons cell @code{(@var{width} . @var{height})} defining the
1068
dimensions of the client window associated with object @var{window}.
1069
@end defun
1070
1071
@defun window-position window
1072
Returns a cons-cell @code{(@var{x} . @var{y})} defining the position
1073
relative to the root window of @var{window}.
1074
@end defun
1075
1076
@defun window-size-hints window
1077
Return an alist defining the size-hints structure specified by the
1078
client window associated with @var{window}. Possible keys in the alist
1079
are @code{min-height}, @code{max-height}, @code{min-width},
1080
@code{max-width}, @code{height-inc}, @code{width-inc},
1081
@code{min-aspect}, @code{max-aspect}, @code{base-height},
1082
@code{base-width}, @code{user-position}, @code{program-position},
1083
@code{user-size}, @code{program-size}, @code{window-gravity},
1084
@code{border-size}.
1085
@end defun
1086
1087
@defun stacking-visibility window
1088
Returns @code{unobscured} if @code{window} is unobscured,
1089
@code{fully-obscured} if one or more windows completely obscure
1090
@code{window}, or @code{partially-obscured} if one or more window
1091
partially obscure @code{window}.
1092
1093
Deciding between fully and partially obscured can be expensive. If
1094
@code{window-obscured} satisfies your needs, use that in preference to
1095
@code{stacking-visibility}.
1096
@end defun
1097
1098
@defun window-obscured window
1099
Returns @code{nil} if @code{window} is unobscured, @code{t} if
1100
@code{window} is completely obscured by exactly one other window, or a
1101
list of windows that partially obscure @code{window}.
1102
1103
If a list of partially obscuring windows is returned, taken together
1104
they may or may not fully obscure @code{window}.
1105
@end defun
1106
1107
@deffn {Obsolete Function} window-visibility window
1108
Returns a symbol defining the current visibility of @var{window}.
1109
Possible returned symbols are @code{fully-obscured},
1110
@code{partially-obscured} or @code{unobscured}.
1111
1112
@code{window-visibility} is deprecated. It is unreliable when using
1113
the Composite extention, as every window is reported unobscured. Use
1114
@code{window-obscured} and @code{stacking-visibility} instead.
1115
@end deffn
1116
1117
@defun window-urgent-p window
1118
Return @code{t} if the ``Urgency'' hint of the window associated with
1119
@var{window} is set.
1120
@end defun
1121
1122
1123
@node Input Focus, X Properties, Window Attributes, Windows
1124
@section Input Focus
1125
@cindex Input focus
1126
@cindex Keyboard focus
1127
@cindex Focus, input
1128
@cindex Windows, input focus
1129
1130
The input focus defines exactly which client window will receive events
1131
generated by the keyboard.
1132
1133
@defun input-focus
1134
Returns the window object of the currently focused window, or
1135
@code{nil} if no window is focused.
1136
@end defun
1137
1138
@defun set-input-focus window
1139
Sets the focus to the client window associated with @var{window}.
1140
1141
If @var{window} is @code{nil}, then no window will have the focus.
1142
@end defun
1143
1144
The window manager is responsible for switching the input focus from
1145
client window to client window. Sawfish implements several
1146
@dfn{focus modes} that provide this behavior. Each focus mode is
1147
bound to a symbol; the implementation is bound to that symbol's
1148
@code{focus-mode} property slot.
1149
1150
@defvar focus-mode
1151
Defines the current method of using the mouse to assign the input
1152
focus. This is a symbol from the list @code{focus-modes}.
1153
@end defvar
1154
1155
@defvar focus-modes
1156
A list containing all names of focus modes. The built-in values are
1157
@code{enter-exit}, @code{enter-only}, @code{enter-click} and @code{click}.
1158
@end defvar
1159
1160
Focus mode @code{enter-exit} changes focus when the pointer enters a
1161
window or leaves the focused window. Focus mode @code{enter-only}
1162
changes focus when the pointer enters a window, but not when it leaves
1163
the focused window. Focus mode @code{click} changes focus when you
1164
click on a window. Focus mode @code{enter-click} is the union of
1165
@code{enter-only} and @code{click}, and changes focus on any
1166
of their conditions.
1167
1168
It is possible to add additional focus modes by defining your own
1169
handler function. The handler function must obey a
1170
``focus-mode-handler'' protocol.
1171
1172
@deftp {Function Protocol} focus-mode-handler window event-name &optional args
1173
A function that implements the @code{focus-mode-handler} protocol can
1174
be used to define a focus mode. A @code{focus-mode-handler} responds
1175
to events associated with windows.
1176
1177
Argument @var{window} is the window that received this event.
1178
1179
Argument @var{event-name} is one of the following symbols:
1180
1181
@table @code
1182
@item pointer-in
1183
@itemx pointer-out
1184
The pointer has entered or exited the window. The handler is
1185
responsible for checking whether an entered window wants input events.
1186
The desktop never receives @code{pointer-in} or @code{pointer-out};
1187
only normal windows do.
1188
1189
@item
1190
@item enter-root
1191
@itemx leave-root
1192
The pointer has entered or exited the desktop (which is the
1193
@var{window} argument). Normal windows never receive
1194
@code{enter-root} or @code{leave-root}.
1195
1196
@item focus-in
1197
@itemx focus-out
1198
The window argument has gotten or lost focus. Note that the
1199
@code{focus-in} handler is not responsible for updating the
1200
window-order list.
1201
1202
@item before-mode-change
1203
@itemx after-mode-change
1204
Sawfish sends these synthetic events to each window before/after
1205
changing that window's focus mode. When the global focus mode
1206
changes, all windows get these events.
1207
1208
@item add-window
1209
Sawfish sends this event to every window immediately after mapping it.
1210
Handlers can use this to initialize window-internal data structures.
1211
1212
@item warp-if-necessary
1213
Warp the cursor to the window if doing so would make the cursor
1214
position ``consistent'' with the focus mode. For example, in
1215
@code{enter-exit} mode we warp the cursor if it is not already in this
1216
window. In @code{enter-only} mode, we warp the cursor if it is in
1217
another window, but not if it is over the desktop---a window would not
1218
lose focus when the cursor moved from it to the desktop.
1219
1220
This event is implemented via @code{warp-cursor-to-window}, so Sawfish
1221
will not warp unless @code{warp-to-window-enabled} is true.
1222
1223
@item focus-revert
1224
The focused window has disappeared (the @var{window} argument is not
1225
used here). The focus mode may react by setting focus to some other
1226
window. If a focused transient window disappears, focus normally
1227
reverts to the window that the disappearing window was transient for.
1228
@code{focus-revert} is not invoked in that case.
1229
@end table
1230
1231
The protocol allows for any number of additional arguments, but does
1232
not define any. Any handler function must be prepared to receive and
1233
ignore them.
1234
1235
Unsupported events may be ignored. The return value of this function
1236
is ignored.
1237
@end deftp
1238
1239
@defun define-focus-mode name fun
1240
Defines a new focus mode called @var{name} (a symbol). The focus-mode
1241
handler @var{fun} implements this focus mode.
1242
1243
See the documentation for @code{focus-mode-handler} for more
1244
information.
1245
@end defun
1246
1247
@defun set-focus-mode window mode
1248
Set the focus mode of window @var{window} to @var{mode}.
1249
This triggers @code{before-mode-change} and @code{after-mode-change}
1250
focus-mode events on @var{window}.
1251
@end defun
1252
1253
@defun warp-pointer-if-necessary window
1254
Generate a @code{warp-if-necessary} event and sends it to the window's
1255
focus function.
1256
1257
Various functions call @code{warp-pointer-if-necessary} if they move
1258
the focused window out from underneath the pointer.
1259
@end defun
1260
1261
@defvar focus-click-through
1262
When in @code{click} focus mode, the focus-assigning click is only
1263
passed through to the client window if this variable is @code{t} (the
1264
default).
1265
1266
This option may be set on a per-window basis by setting the
1267
@code{focus-click-through} property of the window (using the
1268
@code{window-put} function).
1269
@end defvar
1270
1271
@defvar focus-ignore-pointer-events
1272
When true, pointer in/out events don't cause focus changes. This is
1273
independent of the current focus mode.
1274
@end defvar
1275
1276
@defvar focus-within-click-event
1277
When true, the current command is being called from within a
1278
click-to-focus button press event.
1279
1280
This is a fluid object, not an ordinary variable.
1281
@end defvar
1282
1283
Sawfish also maintains the order in which windows were recently
1284
focused.
1285
1286
@defun window-order &optional workspace allow-iconified all-viewports
1287
Return a list of windows, in most-recently-focused order.
1288
1289
If @var{workspace} is an integer, then only windows on that workspace
1290
are included, otherwise all workspaces are searched.
1291
1292
If @var{allow-iconified} is non-nil, iconified windows are included. If
1293
@code{all-viewports} is non-nil, then all viewports of the workspace(s)
1294
are scanned.
1295
@end defun
1296
1297
@defun window-order-push window
1298
Push window object @var{window} onto the top of the focus stack.
1299
@end defun
1300
1301
@defun window-order-pop window
1302
Remove window object @var{window} from the focus stack.
1303
@end defun
1304
1305
@defun window-order-most-recent &optional windows
1306
Return the most-recently focused window in the current workspace. If
1307
the optional argument @var{windows} is given, it must be a list of
1308
windows. In that case, the function will return the most-recently
1309
focused window from that list.
1310
@end defun
1311
1312
@defun window-order-focus-most-recent
1313
Focus the most-recently-focused window of the current workspace.
1314
@end defun
1315
1316
@defvar focus-dont-push
1317
When true, focusing a window doesn't change it's position in the stack of
1318
most-recently focused windows.
1319
@end defvar
1320
1321
@defun window-in-cycle-p window &keyword ignore-cycle-skip
1322
Returns @code{t} if the window @var{window} should be included when
1323
cycling between windows. Desktop windows and those with the
1324
@code{cycle-skip} property should normally not be included.
1325
1326
When @code{t}, the @var{ignore-cycle-skip} keyword argument
1327
forces the function to include windows with the @code{cycle-skip}
1328
property.
1329
@end defun
1330
1331
@defun focus-push-map window keymap
1332
@defunx focus-pop-map window
1333
Maintain a two-element keymap stack for @var{window}.
1334
1335
@code{focus-push-map} makes @var{keymap} current for @var{window}, but
1336
saves the existing keymap. We can restore this existing keymap with
1337
@code{focus-pop-map}.
1338
1339
These functions are intended to support click-to-focus. They enforce
1340
certain sanity rules: pushing into a two-element stack will only
1341
overwrite the top element, while popping a one-element stack has no
1342
effect.
1343
@end defun
1344
1345
@defun autoload-focus-mode name func
1346
MISSING. This does not seem to be used anywhere, and its behavior is
1347
unclear.
1348
@end defun
1349
1350
@defun select-window
1351
Waits for the user to left-click on a window, and returns that window.
1352
The mouse cursor changes shape, and all normal input events are
1353
suppressed until a window is selected.
1354
@end defun
1355
1356
@defvar select-window-cursor-shape
1357
The cursor shape to use when selecting a window. Defaults to
1358
@code{crosshair}.
1359
@end defvar
1360
1361
@node X Properties, Window Stacking, Input Focus, Windows
1362
@section X Properties
1363
@cindex X properties
1364
@cindex Properties, X
1365
@cindex Windows, X properties
1366
1367
The X window system associates properties with windows (these are
1368
totally separate to the properties that sawfish associates with window
1369
@emph{objects}, @pxref{Window Property Lists}). Most inter-client
1370
communication is performed through manipulation of these properties.
1371
1372
All functions defined below, that operate on X properties, accept their
1373
@var{window} parameter as either a window object (denoting the
1374
associated client window), the numeric xid of a window, or the symbol
1375
@code{root} denoting the root window.
1376
1377
Sawfish represents X atoms (both the names and data types of X
1378
properties) as symbols. There is an exact correspondence between the
1379
names of atoms and the name of the symbol representing them. For
1380
example, the X atom @samp{STRING} is represented by the lisp symbol
1381
@code{STRING}.
1382
1383
@defun list-x-properties window
1384
Return a list of symbols defining the X properties set on @var{window}.
1385
@end defun
1386
1387
@defun delete-x-property window property
1388
Deletes the X property named @var{property} (a symbol) associated with
1389
@var{window}.
1390
@end defun
1391
1392
@defun get-x-property window property
1393
Returns a list @code{(@var{type} @var{format} @var{data})} representing
1394
the X property @var{property} of @var{window}. If no such property
1395
exists, return nil.
1396
1397
@var{type} is the atom defining the type of the property. @var{format}
1398
is an integer, either 8, 16 or 32, defining the number of bits in each
1399
of the data items. @var{data} is an array, either a string for an 8-bit
1400
format property, or a vector of integers otherwise.
1401
1402
If @var{type} is @code{ATOM} and @var{format} is 32, then @var{data}
1403
will be a vector of symbols, representing the atoms read.
1404
@end defun
1405
1406
@defun set-x-property window property data type format
1407
Set the X property @var{property} of @var{window} to the array
1408
@var{data}, either a string or a vector of integers.
1409
1410
@var{type} is a symbol representing the atom defining the type of the
1411
property; @var{format} is either 8, 16 or 32 defining the number of
1412
bits in the data values.
1413
1414
If @var{type} is @code{ATOM} and @var{format} is 32, then any symbols
1415
in @var{data} will be converted to their numeric X atoms.
1416
@end defun
1417
1418
The standard X property formats don't allow for an array of strings to
1419
be stored, so these are often encoded as the strings concatenated,
1420
separated by zero characters. These are usually called @dfn{text
1421
properties}. Sawfish has two functions for manipulating them:
1422
1423
@defun get-x-text-property window property
1424
Similar to @code{get-x-property}, but returns either @code{nil} or a
1425
vector of strings.
1426
@end defun
1427
1428
@defun set-x-text-property window property data
1429
Sets the X text property @var{property} of @var{window} to the array
1430
of strings @var{data}.
1431
@end defun
1432
1433
It's also possible to detect when the value of any property associated
1434
with a managed window changes, using the @code{property-notify-hook}.
1435
@xref{Standard Hooks}. The following convenience function takes
1436
advantage of this hook:
1437
1438
@defun call-after-property-changed prop fun
1439
Arrange for function @var{fun} to be called with arguments
1440
@samp{(window property state)} when the X11 property named @var{prop}
1441
(a symbol) changes. @var{Prop} may also be a list of property names
1442
to monitor.
1443
@end defun
1444
1445
1446
@node Window Stacking, Moving and Resizing Windows, X Properties, Windows
1447
@section Window Stacking
1448
@cindex Window stacking
1449
@cindex Stacking, of windows
1450
@cindex Windows, stacking
1451
1452
The stacking order of the display defines the order in which windows
1453
are shown, from topmost to bottommost. Sawfish maintains this list.
1454
Raising or lowering windows changes their positions in this list.
1455
1456
@menu
1457
* Stacking Order::
1458
* Raising and Lowering Windows::
1459
@end menu
1460
1461
@node Stacking Order, Raising and Lowering Windows, Window Stacking, Window Stacking
1462
@subsection Stacking Order
1463
1464
@defun stacking-order
1465
Return a list of window objects defining the current stacking order of
1466
all client windows, from top-most to bottom-most.
1467
@end defun
1468
1469
@defun mapped-stacking-order
1470
Similar to @code{stacking-order}, but only returns windows that are
1471
mapped.
1472
@end defun
1473
1474
@defun restack-windows list
1475
Restack all client windows specified in the list of window objects
1476
@var{list} in the order they occur in the list (from top to bottom).
1477
The stacking order of any unspecified windows isn't affected.
1478
@end defun
1479
1480
Sawfish allows the stacking order to be managed as a sequence of
1481
layers, with windows being assigned a particular depth within the
1482
order. For any given window with depth @var{d}, it will be above all
1483
windows with depth less than @var{d}, and below all windows with depth
1484
greater than @var{d}. It may be above or below any other windows with
1485
depth @var{d}.
1486
1487
The @code{depth} property of each window is used to store this depth. A
1488
depth of zero is ``normal'', with negative depths stacked below, and
1489
positive depths stacked above this normal level.
1490
1491
@defun stacking-order-by-depth depth
1492
Similar to @code{stacking-order}, but only returns windows with depth
1493
@var{depth}.
1494
@end defun
1495
1496
@defun window-depth window
1497
Returns the depth of @var{window}.
1498
@end defun
1499
1500
@defun set-window-depth window depth
1501
Sets the stacking depth of @var{window} to @var{depth}, then restacks
1502
the windows to reflect this change.
1503
@end defun
1504
1505
@defun window-on-top-p window
1506
Returns @code{t} if @var{window} is at the top of its stacking depth.
1507
@end defun
1508
1509
@defun stack-window-below below above
1510
Change stacking order of window @var{below} so that it is immediately
1511
below window @var{above}.
1512
@end defun
1513
1514
@defun stack-window-above above below
1515
Change stacking order of window @var{above} so that it is immediately
1516
above window @var{below}.
1517
@end defun
1518
1519
@defmac save-stacking-order &rest forms
1520
Evaluate @var{forms} in an implicit @code{progn}, then restore the
1521
original window stacking order, returning the value of the
1522
@code{progn}.
1523
@end defmac
1524
1525
@defun restack-window w
1526
Assuming that the current stacking order is in a consistent state
1527
except, possibly, for the position of window @var{w}, restore the
1528
consistent state including window @var{w}. This is achieved by raising
1529
or lowering window W as appropriate.
1530
@end defun
1531
1532
@node Raising and Lowering Windows, , Stacking Order, Window Stacking
1533
@subsection Raising and Lowering Windows
1534
@cindex Windows, raising
1535
@cindex Windows, lowering
1536
1537
Over time, Sawfish has accumulated several subtle variations of
1538
functions for raising and lowering windows. One set of functions
1539
operates on single windows.
1540
1541
@deffn Function lower-window window
1542
@deffnx Command lower-single-window window
1543
Lower @var{window} to the bottom of its stacking depth.
1544
@end deffn
1545
1546
@deffn Function raise-window window
1547
@deffnx Command raise-single-window window
1548
Raise @var{window} to the top of its stacking depth.
1549
@end deffn
1550
1551
@deffn Function raise-lower-window window
1552
@deffnx Command raise-lower-single-window window
1553
If @var{window} is the highest in its stacking level, lower it to the
1554
bottom of this level, otherwise raise it to the top of its level.
1555
@end deffn
1556
1557
Notice how the function name and command name for each pair differs
1558
slightly. Another set of functions supports operating on multiple windows
1559
simultaneously. Again, the function name and command name for each
1560
pair is different.
1561
1562
@deffn Function lower-window* window
1563
@deffnx Command lower-window window
1564
Lower @var{window} and possibly associated windows to the bottom of
1565
their stacking depths.
1566
@end deffn
1567
1568
@deffn Function raise-window* window
1569
@deffnx Command raise-window window
1570
Raise @var{window} and possibly associated windows to the top of their
1571
stacking depth.
1572
@end deffn
1573
1574
@deffn Function raise-lower-window* window
1575
@deffnx Command raise-lower-window window
1576
If @var{window} is the highest in its stacking level, lower it and
1577
possibly associated windows to the bottom of their level, otherwise
1578
raise them to the top of their level.
1579
@end deffn
1580
1581
@defvar user-raise-type
1582
Indicates which windows the @code{lower-window*}, @code{raise-window*}
1583
and @code{raise-lower-window*} functions affect. This variable can be
1584
1585
@table @code
1586
@item none
1587
Only the specific argument window is affected.
1588
@item transients
1589
The specific argument window and all of its transients are affected.
1590
This is the default.
1591
@item group
1592
The specific argument window and all windows in its group are
1593
affected.
1594
@end table
1595
@end defvar
1596
1597
@defun maybe-raise-window w
1598
If window @var{w} supports the @code{_SAWFISH_WM_RAISE_WINDOW}
1599
protocol, ask it whether it wants to raise itself or not. Otherwise,
1600
raise the window unconditionally.
1601
@end defun
1602
1603
@defun maybe-lower-window w
1604
If window @var{w} supports the @code{_SAWFISH_WM_LOWER_WINDOW}
1605
protocol, ask it whether it wants to lower itself or not. Otherwise,
1606
lower the window unconditionally.
1607
@end defun
1608
1609
Sawfish has more general operations that raising a window to the top
1610
or lowering it to the bottom. It can place a window relative to one
1611
or more other managed windows.
1612
1613
@defun raise-windows w order
1614
@defunx lower-windows w order
1615
@defunx raise-lower-windows w order
1616
Raise (or lower) all windows in @var{order}, such that items earlier in
1617
the list are higher (or lower) than later items. The window @var{w}
1618
is special, always being the highest or lowest window, even if appears
1619
in the middle of @var{order}.
1620
1621
For @code{raise-lower-windows}, if @var{w} would be raised or lowered,
1622
then all the other windows are also raised or lowered.
1623
@end defun
1624
1625
There are also functions (and associated commands) to change a
1626
window's depth.
1627
1628
@deffn Function lower-window-depth window
1629
@deffnx Command lower-window-depth window
1630
Decrement the stacking depth of @var{window}.
1631
@end deffn
1632
1633
@deffn Function raise-window-depth window
1634
@deffnx Command raise-window-depth window
1635
Increment the stacking depth of @var{window}.
1636
@end deffn
1637
1638
Sawfish provides special support for ``click-to-focus'' mode, where
1639
you may or may not want to raise the window or pass the click to the
1640
underlying application.
1641
1642
@defun raise-and-pass-through-click w
1643
Raise the window that received the current event with
1644
@code{maybe-raise-window}. Then replay any pointer events that
1645
invoked the command.
1646
@end defun
1647
1648
@defun raise-and-pass-through-click-if-focused w
1649
Raise the window that received the current event (if it's focused)
1650
with @code{maybe-raise-window}. Then replay any pointer events that
1651
invoked the command.
1652
@end defun
1653
1654
@defun raise-or-pass-through-click w
1655
If the window that received the current event is not on top, raise it
1656
with @code{maybe-raise-window}. Otherwise replay any pointer events
1657
that invoked the command, sending them to the window.
1658
@end defun
1659
1660
When the above commands are called interactively, Sawfish will try to
1661
invoke them on the window that received the current event. Failing
1662
that, Sawfish will invoke them on the currently focused window.
1663
1664
@node Moving and Resizing Windows, Showing and Hiding Windows, Window Stacking, Windows
1665
@section Moving and Resizing Windows
1666
@cindex Moving and resizing windows
1667
@cindex Resizing and moving windows
1668
@cindex Windows, moving and resizing
1669
1670
As noted above (@pxref{Window Attributes}), the
1671
@code{window-dimensions} and @code{window-position} functions return
1672
the current configuration of a window.
1673
1674
@defun move-window-to window x y
1675
Move the top-left corner of the window frame of @var{window} to
1676
(@var{x}, @var{y}).
1677
@end defun
1678
1679
@defun resize-window-to window width height
1680
Set the dimensions of the client window associated with object
1681
@var{window} to (@var{width}, @var{height}).
1682
@end defun
1683
1684
@defun move-resize-window-to window x y width height
1685
Move the top-left corner of the window frame of @var{window} to
1686
(@var{x}, @var{y}), and set the dimensions of the frame to
1687
(@var{width}, @var{height}).
1688
@end defun
1689
1690
@defun resize-window-with-hints window cols rows &optional hints
1691
@defunx resize-window-with-hints* window width height &optional hints
1692
Resize the window associated with object @var{window} so that it has
1693
certain X and Y dimensions. For the first function, the dimensions
1694
are @var{cols} columns and @var{rows} rows. For the second function,
1695
the dimensions are @var{width} pixels and @var{height} pixels.
1696
1697
The @var{hints} parameters is either the size hints alist to use, or
1698
@code{nil} in which case the @code{window-size-hints} function is used
1699
to retrieve the window's hints.
1700
@end defun
1701
1702
Usually, however, it is left to the user to configure windows. The
1703
following functions may be called interactively: their sole argument is
1704
then either the window that received the current event or the currently
1705
focused window.
1706
1707
Sawfish honors the @code{min-aspect} and @code{max-aspect} window
1708
hints when interactively resizing a window.
1709
1710
@deffn Command move-window-interactively window
1711
Move @var{window} interactively using the mouse. Releasing any mouse
1712
button places the window at its current position.
1713
@end deffn
1714
1715
@deffn Command resize-window-interactively window
1716
Resize @var{window} interactively using the mouse. Releasing any mouse
1717
button places the window at its current position.
1718
1719
Note that this function selects the edge or edges of the window to move
1720
from the current position of the mouse when the resizing begins. The
1721
window is divided into a three-by-three grid; the rectangle containing
1722
the mouse pointer gives the direction to resize in. If the pointer is
1723
in the central rectangle the bottom and right edges are moved.
1724
@end deffn
1725
1726
@deffn Command move-selected-window
1727
Wait for the user to select a window using the mouse, then
1728
interactively move that window.
1729
@end deffn
1730
1731
@deffn Command resize-selected-window
1732
Wait for the user to select a window with the mouse, then interactively
1733
resize that window.
1734
@end deffn
1735
1736
The interactive move and resize behavior can be customized through the
1737
following variables:
1738
1739
@defvar move-outline-mode
1740
A symbol defining the visual method of interactively moving windows.
1741
Current options include @code{box} for a wire-frame grid, and
1742
@code{opaque} for full redisplay.
1743
@end defvar
1744
1745
@defvar resize-outline-mode
1746
A symbol defining the visual method of interactively resizing windows.
1747
Current options include @code{box} for a wire-frame grid, and
1748
@code{opaque} for full redisplay.
1749
@end defvar
1750
1751
@defvar move-show-position
1752
When non-nil, the current window position is shown in the center of the
1753
screen.
1754
@end defvar
1755
1756
@defvar resize-show-position
1757
When non-nil, the window size is shown in the center of the screen.
1758
@end defvar
1759
1760
@defvar move-snap-edges
1761
When non-nil, the window position is ``snapped'' to edges of other
1762
windows within close proximity.
1763
@end defvar
1764
1765
@defvar move-snap-epsilon
1766
The distance in pixels before snapping together two edges.
1767
@end defvar
1768
1769
Windows have a ``gravity'' property, which affect how they are placed
1770
in particular positions.
1771
1772
@defun window-gravity window &optional hints
1773
Returns the gravity of window. The order of precedence is Sawfish
1774
@code{gravity} window property, explicit @var{hints} argument, X
1775
window size hints. The default gravity when nothing else is specified
1776
is @code{north-west} (specified by ICCCM).
1777
@end defun
1778
1779
@node Showing and Hiding Windows, Destroying Windows, Moving and Resizing Windows, Windows
1780
@section Showing and Hiding Windows
1781
@cindex Showing and hiding windows
1782
@cindex Hiding and showing windows
1783
@cindex Windows, showing and hiding
1784
1785
Sawfish provides two low-level functions for withdrawing client windows
1786
from the display. These are used to implement both virtual workspaces
1787
(@pxref{Workspaces}) and iconification (@pxref{Iconifying Windows}).
1788
1789
@defun hide-window window
1790
Prevent object @var{window} from being displayed. See
1791
@code{show-window}.
1792
@end defun
1793
1794
@defun show-window window
1795
Ensure that @var{window} (if it has been mapped, and is within the
1796
screen boundary) is visible. See @code{hide-window}.
1797
@end defun
1798
1799
@defun window-visible-p window
1800
Returns @code{t} if object @var{window} has not been hidden by the
1801
@code{hide-window} function.
1802
@end defun
1803
1804
1805
@node Destroying Windows, Shading Windows, Showing and Hiding Windows, Windows
1806
@section Destroying Windows
1807
@cindex Destroying windows
1808
@cindex Windows, destroying
1809
1810
There are several methods through which X11 client windows may be
1811
removed from the display. These differ in the level ``politeness'' they
1812
show the window and its owning application.
1813
1814
@deffn Command delete-window window
1815
Delete @var{window}, i.e. send a @code{WM_DELETE_WINDOW} client-message
1816
if possible, or just kill the associated X11 client if not.
1817
@var{window} may be a window object or a numeric window id.
1818
@end deffn
1819
1820
@deffn Command delete-window-safely window
1821
If the application owning @var{window} supports it, send a
1822
@code{WM_DELETE_WINDOW} message to @var{window}. Otherwise just emit a
1823
beep.
1824
@end deffn
1825
1826
@deffn Command destroy-window window
1827
Destroy @var{window} without giving the owning application any warning.
1828
@var{window} may be a window object or a numeric window id.
1829
@end deffn
1830
1831
@defun x-kill-client window
1832
Force a close down of the X11 client that created the window specified
1833
by @var{window} (a window object, or numeric id).
1834
@end defun
1835
1836
When a managed window is destroyed, the @code{destroy-notify-hook} will
1837
subsequently be invoked (@pxref{Standard Hooks}).
1838
1839
@node Shading Windows, Iconifying Windows, Destroying Windows, Windows
1840
@section Shading Windows
1841
@cindex Shading windows
1842
@cindex Windows, shading
1843
1844
Many window managers allow a window to be @dfn{shaded}; when in this
1845
state only the title bar of the window is visible.
1846
1847
@defun window-shaded-p window
1848
Returns true when @var{window} is shaded, false otherwise.
1849
@end defun
1850
1851
@deffn Command shade-window window
1852
Arrange for only the title bar of @var{window} to be visible.
1853
@end deffn
1854
1855
@deffn Command unshade-window window
1856
If the window is shaded, restore it to it's original state.
1857
@end deffn
1858
1859
@deffn Command toggle-window-shaded
1860
Toggle the shaded state of the window.
1861
@end deffn
1862
1863
@defvar raise-windows-when-unshaded nil
1864
When true, raise windows when they are unshaded. Defaults to false.
1865
@end defvar
1866
1867
The @code{shaded} property of a window is set to @code{t} when the
1868
window is shaded. If a window is added with this property already set,
1869
then the window will appear in its shaded state.
1870
1871
1872
@node Iconifying Windows, Window Stickiness, Shading Windows, Windows
1873
@section Iconifying Windows
1874
@cindex Iconifying windows
1875
@cindex Windows, iconifying
1876
1877
X defines an iconic state for windows, often windows in this state are
1878
displayed as small icons. Sawfish does not display these icons, instead
1879
iconified windows are shown slightly differently in the menu of all
1880
windows.
1881
1882
@deffn Command iconify-window window
1883
Iconify the window associated with object @var{window}.
1884
@end deffn
1885
1886
@deffn Command uniconify-window window
1887
Return the window associated with @var{window} from its iconified state.
1888
@end deffn
1889
1890
@deffn Command toggle-window-iconified window
1891
Minimize the window associated with @var{window}, or restore it if it
1892
is already minimized.
1893
@end deffn
1894
1895
@deffn Command iconify-workspace-windows
1896
Minimize all windows in the current workspace.
1897
@end deffn
1898
1899
A window's iconic state may be tested through examination of its
1900
@code{iconified} property---when @code{t} the window is iconified.
1901
But it is preferable to use explicit testing functions instead:
1902
1903
@defun window-iconified-p window
1904
Returns true if the window associated with @var{window} is iconified,
1905
false otherwise.
1906
@end defun
1907
1908
@defun window-iconifiable-p window
1909
Returns true if the window associated with @var{window} can be
1910
iconified, false otherwise. Some reasons a window might not be
1911
iconifiable are: it has a @code{never-iconify} property; it is
1912
already iconified; it is not a desktop window; or it is marked
1913
@code{ignored} and @code{iconify-ignored} is not true.
1914
@end defun
1915
1916
@defvar iconify-ignored nil
1917
Unmanaged (@code{ignored}) windows may be iconified. Defaults to nil.
1918
@end defvar
1919
1920
Sawfish allows you to control certain behaviors when restoring
1921
minimized windows.
1922
1923
@defvar focus-windows-on-uniconify
1924
Windows are focused after being unminimized. Defaults to false.
1925
@end defvar
1926
1927
@defvar raise-windows-on-uniconify
1928
Windows are raised after being unminimized. Defaults to true.
1929
@end defvar
1930
1931
@defvar uniconify-to-current-workspace
1932
Move windows to the current workspace when they are unminimized.
1933
Defaults to true.
1934
@end defvar
1935
1936
When iconifying, it is possible to force other windows to iconify.
1937
1938
@defvr Customizable iconify-group-mode
1939
@defvrx Customizable uniconify-group-mode
1940
Policy for performing chains of minimizations or restorations. When a
1941
particular window is minimized or restored, it can cause other windows
1942
to be minimized or restored at the same time. Their allowed values
1943
are set to the following list. By default, both variables are bound
1944
to the symbol @code{transients}. but they are not required to have the
1945
same value.
1946
@end defvr
1947
1948
@table @code
1949
@item none
1950
No additional windows are minimized or restored.
1951
@item transients
1952
All transient windows associated with the target window are minimized
1953
or restored.
1954
@item group
1955
All windows in the target window's group are minimized or restored.
1956
@end table
1957
1958
Finally, it's possible to get the icon that would normally be
1959
displayed for an iconified window.
1960
1961
@defun window-icon-image window
1962
Return an image object representing the icon currently associated with
1963
@var{window}, or @code{nil} if there is no such image.
1964
@end defun
1965
1966
@node Window Stickiness, Ignored Windows, Iconifying Windows, Windows
1967
@section Window Stickiness
1968
@cindex Window stickiness
1969
@cindex Sticky, windows
1970
1971
Windows normally exist in a single workspace and a single viewport
1972
into that workspace. When changing workspace or viewport, the current
1973
windows disappear. This is sometimes not the correct policy; there
1974
are certain windows that should ``follow'' the user from window to
1975
window. These are typically windows that are not bound to a
1976
particular activity. The most common example is a dashboard window
1977
for calling other applications. Another example might be a diagnostic
1978
program such as a load monitory.
1979
1980
Each window has ``stickiness'' flags that govern this behavior. One
1981
flag controls stickiness across workspaces: sticky windows will appear
1982
in every workspace automatically. The other flag similarly governs
1983
stickiness across viewports. A window is ``sticky'' if either of
1984
these flags are set.
1985
1986
Sticky windows are often @code{ignored}, so they lack window
1987
decorations, and @code{avoid}ed so other windows do not cover them up.
1988
1989
@defun window-sticky-p/workspace window
1990
@defunx window-sticky-p/viewport window
1991
@defunx window-sticky-p window
1992
Returns true if @var{window} is sticky across a particular environment
1993
(workspaces, viewports, or either), false otherwise.
1994
@end defun
1995
1996
@defun make-window-sticky/workspace window
1997
@defunx make-window-sticky/viewport window
1998
@defunx make-window-sticky window
1999
Make the @var{window} sticky across some environment (workspaces,
2000
viewports, or both).
2001
@end defun
2002
2003
@defun make-window-unsticky/workspace window
2004
@defunx make-window-unsticky/viewport window
2005
@defunx make-window-unsticky window
2006
Make the @var{window} unsticky across some environment (workspaces,
2007
viewports or both).
2008
@end defun
2009
2010
@defun toggle-window-sticky window
2011
If @code{window-sticky-p} would report true for @var{window}, make
2012
@var{window} unsticky for all environments. Otherwise make it sticky
2013
for all environments.
2014
@end defun
2015
2016
@node Ignored Windows, Avoided Windows, Window Stickiness, Windows
2017
@section Ignored Windows
2018
@cindex Windows, ignored
2019
@cindex ignored
2020
2021
Sawfish has a general concept of ``ignored'' windows; the user does
2022
not interact normally with those windows. The concept is actually
2023
defined by five different window properties:
2024
2025
@table @code
2026
@item ignored
2027
The window does not receive frames.
2028
2029
@item never-focus
2030
The window never receives the input focus.
2031
2032
@item cycle-skip
2033
The window is ignored while window cycling.
2034
2035
@item window-list-skip
2036
The window will not be included in the window list.
2037
2038
@item task-list-skip
2039
The window will not be included in the task list.
2040
2041
@end table
2042
2043
A monitor application such as ``xload'' might have all five of these
2044
flags set.
2045
2046
Rather than directly manipulating the window properties, it is better
2047
to use the following access functions:
2048
2049
@defun window-ignored-p window
2050
Returns true if the window has the @code{ignored} property, false
2051
otherwise.
2052
@end defun
2053
2054
@deffn Command make-window-ignored window
2055
Ignore the window @var{window}.
2056
@end deffn
2057
2058
@deffn Command make-window-not-ignored window
2059
Unignore the window @var{window}.
2060
@end deffn
2061
2062
@deffn Command toggle-window-ignored window
2063
If @code{window-ignored-p} would return true for @var{window}, make it
2064
unignored. Otherwise make it ignored.
2065
@end deffn
2066
2067
The remaining flags only have toggle functions implemented right now:
2068
2069
@deffn Command toggle-window-never-focus window
2070
@deffnx Command toggle-window-cycle-skip window
2071
@deffnx Command toggle-window-list-skip window
2072
@deffnx Command toggle-task-list-skip window
2073
Toggle the appropriate flag on @var{window}.
2074
@end deffn
2075
2076
All five of the flags are available through the window menu's
2077
``Toggle'' entry.
2078
2079
@node Avoided Windows, Maximizing Windows, Ignored Windows, Windows
2080
@section Avoided Windows
2081
@cindex Windows, avoided
2082
@cindex avoid
2083
2084
``Avoided'' windows are kept unobscured by other windows
2085
wherever possible. It is involved in window placement (@pxref{Window
2086
Placement}) and maximization (@pxref{Maximizing Windows}).
2087
Most placement modes will attempt to place a new window avoiding
2088
overlap with them. Windows can be maximized avoiding overlap to
2089
avoided windows.
2090
2091
In this context, windows are categorized into three: windows with
2092
@code{avoid} property, those with
2093
@code{ignored} property (@pxref{Ignored Windows}), and the others.
2094
2095
It is possible to avoid overlap only with avoided windows, and
2096
also is possible @emph{not} to avoid overlap only with ignored windows.
2097
2098
Remember that the window with @code{avoid} property is @emph{avoided}
2099
by @emph{other} windows. Thus property name @code{avoid} should have
2100
been named ``avoided''. On the other hand, related functions and
2101
variables are named correctly, and no special care is necessary.
2102
2103
@defvar dont-avoid-ignored
2104
When non-nil (the default), ignored windows aren't avoided.
2105
@end defvar
2106
2107
@defvar avoid-by-default
2108
When non-nil, any windows are avoided. Defaults to nil.
2109
@end defvar
2110
2111
@defun window-avoided-p window
2112
Returns t if @var{window} is avoided by other windows.
2113
It is determined in the following order:
2114
2115
@enumerate
2116
@item A window with @code{avoid} property is always avoided.
2117
@item A window with @code{ignored} property is always @emph{not} avoided
2118
unless @code{dont-avoid-ignored} is non-nil.
2119
@item Otherwise, @code{avoid-by-default} determines if it should be avoided.
2120
@end enumerate
2121
@end defun
2122
2123
@defun avoided-windows &optional window
2124
Returns a list of all windows that are avoided. If
2125
@var{window} is defined, then it is excluded from the returned list.
2126
@end defun
2127
2128
@node Maximizing Windows, Animating Windows, Avoided Windows, Windows
2129
@section Maximizing Windows
2130
@cindex Maximizing windows
2131
@cindex Windows, maximizing
2132
2133
The dimensions of a window may be temporarily @dfn{maximized},
2134
stretching as far as possible within the screen in one or two dimensions.
2135
2136
@defun window-maximizable-p window &optional direcion hints
2137
Return @code{t} when @var{window} is maximizable. The window property
2138
@var{never-maximize} prevents maximization.
2139
2140
If defined, @var{direction} is a symbol, either @code{vertical} or
2141
@code{horizontal}, and maximization will only occur for that
2142
direction.
2143
2144
The optional argument @var{hints} overrides the window's hints.
2145
@end defun
2146
2147
@defun window-maximized-p window
2148
Return @code{t} when @var{window} is maximized in any direction.
2149
@end defun
2150
2151
@defun window-maximized-vertically-p window
2152
Return @code{t} when @var{window} is vertically maximized.
2153
@end defun
2154
2155
@defun window-maximized-horizontally-p window
2156
Return @code{t} when @var{window} is horizontally maximized.
2157
@end defun
2158
2159
@menu
2160
* Basic Maximizations::
2161
* Maximizing Without Overlap::
2162
* Maximizing Without Borders::
2163
* Unmaximizing::
2164
@end menu
2165
2166
@node Basic Maximizations, Maximizing Without Overlap, Maximizing Windows, Maximizing Windows
2167
@subsection Basic Maximizations
2168
2169
Ordinary maximization occurs on the current screen, and possibly
2170
rounding down to fit character sizes.
2171
2172
@deffn Function maximize-window window &optional direction only-1d
2173
@deffnx Command maximize-window window
2174
Maximize both dimensions of @var{window} on the screen.
2175
2176
If defined, @var{direction} is a symbol, either @code{vertical} or
2177
@code{horizontal}, and maximization will only occur for that
2178
direction.
2179
2180
The optional argument @var{only-1d} is for internal use. Don't use it.
2181
@end deffn
2182
2183
@deffn Function maximize-window-vertically window
2184
@deffnx Command maximize-window-vertically window
2185
Maximize the vertical dimension of @var{window} in the screen.
2186
@end deffn
2187
2188
@deffn Function maximize-window-horizontally window
2189
@deffnx Command maximize-window-horizontally window
2190
Maximize the horizontal dimension of @var{window} in the screen.
2191
@end deffn
2192
2193
@deffn Function maximize-window-toggle window &optional direction
2194
@deffnx Command maximize-window-toggle window
2195
Toggle the state of @var{window} between maximized and unmaximized
2196
in the screen.
2197
2198
If defined, @var{direction} is a symbol, either @code{vertical} or
2199
@code{horizontal}, and maximization will only occur for that
2200
direction.
2201
@end deffn
2202
2203
@deffn Function maximize-window-vertically-toggle window
2204
@deffnx Command maximize-window-vertically-toggle window
2205
Toggle the state of @var{window} between vertically maximized and
2206
unmaximized in the screen.
2207
@end deffn
2208
2209
@deffn Function maximize-window-horizontally-toggle window
2210
@deffnx Command maximize-window-horizontally-toggle window
2211
Toggle the state of @var{window} between horizontally maximized and
2212
unmaximized in the screen.
2213
@end deffn
2214
2215
@defvr Customizable move-lock-when-maximized
2216
When true (the default), Sawfish will not allow the user to manually
2217
resize maximized windows. It will also prevent the user from moving
2218
the windows along their maximized axes.
2219
2220
For example, a vertically maximized window is vertically locked, so a
2221
user can slide it left and right, but cannot move it up or down.
2222
@end defvr
2223
2224
@defun window-locked-vertically-p window
2225
Return @code{t} when @var{window} is vertically locked.
2226
@end defun
2227
2228
@defun frame-part-movable-p window part
2229
Return @code{t} if the @var{part} of @var{window} can be moved.
2230
2231
@var{part} is one of the symbols: @code{top-border},
2232
@code{bottom-border}, @code{left-border}, @code{right-border},
2233
@code{top-left-corner}, @code{top-right-corner},
2234
@code{bottom-left-corner}, @code{bottom-right-corner}, or
2235
@code{title}
2236
@end defun
2237
2238
@defvar maximize-raises
2239
When true (the default), maximizing a window raises it as well.
2240
@end defvar
2241
2242
@defvar maximize-always-expands
2243
In general, if a window's dimension is larger than the screen size,
2244
maximizing that dimension can actually shrink it to fit into the
2245
screen. When this variable is true (default false), maximizing a
2246
window's dimension will never shrink it.
2247
@end defvar
2248
2249
@node Maximizing Without Overlap, Maximizing Without Borders, Basic Maximizations, Maximizing Windows
2250
@subsection Maximizing Without Overlap
2251
2252
It is possible to maximize a window where it gets only large enough
2253
not to overlap with other windows.
2254
2255
@defvar maximize-avoid-avoided
2256
When true (the default), maximized window does not cover avoided
2257
windows. (@pxref{Avoided Windows})
2258
@end defvar
2259
2260
The ``fill'' category of maximizing commands provides a convenient way to
2261
maximize without overlap to any other windows, except ``ignored'' ones.
2262
(@pxref{Ignored Windows})
2263
2264
In addition, they don't shrink the window even if it is already bigger
2265
than the screen size.
2266
2267
@deffn Function maximize-fill-window window &optional direction
2268
@deffnx Command maximize-fill-window window
2269
Maximize both dimensions of @var{window} without overlapping other
2270
windows.
2271
2272
If defined, @var{direction} is a symbol, either @code{vertical} or
2273
@code{horizontal}, and maximization will only occur for that
2274
direction.
2275
@end deffn
2276
2277
@deffn Function maximize-fill-window-vertically window
2278
@deffnx Command maximize-fill-window-vertically window
2279
Maximize the vertical dimension of @var{window} in the screen without
2280
overlapping other windows.
2281
@end deffn
2282
2283
@deffn Function maximize-fill-window-horizontally window
2284
@deffnx Command maximize-fill-window-horizontally window
2285
Maximize the horizontal dimension of @var{window} in the screen
2286
without overlapping other windows.
2287
@end deffn
2288
2289
@deffn Function maximize-fill-window-toggle window
2290
@deffnx Command maximize-fill-window-toggle window
2291
Toggle the state of @var{window} between maximized and unmaximized in
2292
the screen without overlapping other windows.
2293
2294
If defined, @var{direction} is a symbol, either @code{vertical} or
2295
@code{horizontal}, and maximization will only occur for that
2296
direction.
2297
@end deffn
2298
2299
@deffn Function maximize-fill-window-vertically-toggle window
2300
@deffnx Command maximize-fill-window-vertically-toggle window
2301
Toggle the state of @var{window} between vertically maximized and
2302
unmaximized in the screen without overlapping other windows.
2303
@end deffn
2304
2305
@deffn Function maximize-fill-window-horizontally-toggle window
2306
@deffnx Command maximize-fill-window-horizontally-toggle window
2307
Toggle the state of @var{window} between horizontally maximized and
2308
unmaximized in the screen without overlapping other windows.
2309
@end deffn
2310
2311
@defvar maximize-ignore-when-filling
2312
For ``filling'' maximization, ``ignored'' windows are ignored when true
2313
(the default). (@pxref{Ignored Windows})
2314
@end defvar
2315
2316
@node Maximizing Without Borders, Unmaximizing, Maximizing Without Overlap, Maximizing Windows
2317
@subsection Maximizing Without Borders
2318
2319
The ``fullscreen'' and ``fullxinerama'' categories of maximizing
2320
commands maximize the window to some extent and remove all the
2321
window's decorations. If necessary, Sawfish will pad the bottom and
2322
right window edges to make the window fill the complete extent. (This
2323
is usually required for terminal windows, for example.)
2324
2325
The ``fullscreen'' category maximizes the window to the current
2326
screen.
2327
2328
@deffn Function maximize-window-fullscreen window
2329
@deffnx Command maximize-window-fullscreen window
2330
Maximize both dimensions of @var{window} on the screen, removing
2331
window decorations and making the window edges flush with the screen
2332
sides.
2333
2334
If defined, @var{direction} is a symbol, either @code{vertical} or
2335
@code{horizontal}, and maximization will only occur for that
2336
direction.
2337
@end deffn
2338
2339
@deffn Function maximize-window-fullscreen-toggle window
2340
@deffnx Command maximize-window-fullscreen-toggle window
2341
Toggle the state of @var{window} between maximized and unmaximized in
2342
the screen, removing window decorations and making the window edges
2343
flush with the screen sides.
2344
2345
If defined, @var{direction} is a symbol, either @code{vertical} or
2346
@code{horizontal}, and maximization will only occur for that
2347
direction.
2348
@end deffn
2349
2350
The ``fullxinerama'' category maximizes the window to the entire
2351
Xinerama display.
2352
2353
@deffn Function maximize-window-fullxinerama window
2354
@deffnx Command maximize-window-fullxinerama window
2355
Maximize both dimensions of @var{window} across all Xinerama screens,
2356
removing window decorations and making the window edges flush with the
2357
screen sides.
2358
2359
If defined, @var{direction} is a symbol, either @code{vertical} or
2360
@code{horizontal}, and maximization will only occur for that
2361
direction.
2362
@end deffn
2363
2364
@deffn Function maximize-window-fullxinerama-toggle window
2365
@deffnx Command maximize-window-fullxinerama-toggle window
2366
Toggle the state of @var{window} between maximized and unmaximized
2367
across all Xinerama screeens, removing window decorations and making
2368
the window edges flush with the screen sides.
2369
2370
If defined, @var{direction} is a symbol, either @code{vertical} or
2371
@code{horizontal}, and maximization will only occur for that
2372
direction.
2373
@end deffn
2374
2375
@node Unmaximizing, , Maximizing Without Borders, Maximizing Windows
2376
@subsection Unmaximizing
2377
2378
One command restores windows from all the different types of
2379
maximization.
2380
2381
@deffn Command unmaximize-window window &optional direction
2382
Restore the position and dimensions of @var{window} to their original,
2383
unmaximized, states.
2384
2385
Positions and dimensions that were not maximized are not affected by
2386
unmaximizing.
2387
2388
If defined, @var{direction} is a symbol, either @code{vertical} or
2389
@code{horizontal}, and maximization will only occur for that
2390
direction.
2391
@end deffn
2392
2393
@defun window-unmaximized-position window
2394
Returns a cons-cell @code{(@var{x} . @var{y})} indicating the position
2395
that the @code{window} would unmaximize to.
2396
2397
Sawfish preserves the positions of maximized axes only, so a
2398
vertically maximized window will be restored to its original @var{y}
2399
coordinate, but its @var{x} coordinate may have changed.
2400
@end defun
2401
2402
@defun window-unmaximized-dimensions window
2403
Returns a cons-cell @code{(@var{w} . @var{h})} indicating the
2404
dimensions that @code{window} would unmaximize to.
2405
2406
Sawfish preserves the dimensions of maximized axes only, so a
2407
vertically maximized window will be restored to its original @var{h}
2408
dimension, but its @var{w} coordinate may have changed.
2409
@end defun
2410
2411
@node Animating Windows, Cycling Between Windows, Maximizing Windows, Windows
2412
@section Animating Windows
2413
@cindex Windows, Animating
2414
2415
Sawfish provides certain window animation capabilities. They have
2416
been described as ``lame'', so they are off by default.
2417
2418
@defvar default-window-animator
2419
The default window animation mode, used if a window has no explicit
2420
animation set. Normally @code{none}.
2421
@end defvar
2422
2423
@defun define-window-animator name fun
2424
Define a window animator called @var{name} (a symbol) that is managed
2425
by function @var{fun}. @var{fun} is called as @samp{(fun window op
2426
[action])} when it should change the state of an animation sequence.
2427
@var{Op} may be one of the symbols @code{start}, @code{stop}.
2428
@end defun
2429
2430
@defun autoload-window-animator name struct
2431
Construct an autoloader for window animator @var{name} from structure
2432
@var{struct}.
2433
@end defun
2434
2435
@defun run-window-animator window action
2436
Invoke an animation for action @var{action} on @var{window}.
2437
@var{Action} may be one of the symbols @code{start}, @code{stop}.
2438
@end defun
2439
2440
@defun record-window-animator window animator
2441
Note that @var{window} currently has an animation running, being
2442
controlled by animator function @var{animator}.
2443
@end defun
2444
2445
@node Cycling Between Windows, Window Groups, Animating Windows, Windows
2446
@section Cycling Between Windows
2447
@cindex Windows, cycling between
2448
2449
Sawfish provides two categories of commands for cycling between
2450
windows. The first category cycles between windows in an order that
2451
is essentially fixed. The second category cycles between windows in a
2452
dynamic order.
2453
2454
@menu
2455
* Fixed Window Cycles::
2456
* Dynamic Window Cycles::
2457
@end menu
2458
2459
@node Fixed Window Cycles, Dynamic Window Cycles, Cycling Between Windows, Cycling Between Windows
2460
@subsection Fixed Window Cycles
2461
@cindex Window cycles, fixed
2462
2463
These commands organize the set of mangaged windows into loops. A
2464
loop may consist of all windows in a workspace, or it may consist of
2465
all windows anywhere. The positions of windows in this loop do not
2466
change, except when a new window is managed or unmanaged.
2467
2468
@defun next-workspace-window
2469
@defunx previous-workspace-window
2470
Switch focus to the ``next'' or ``previous'' window in the current
2471
workspace.
2472
@end defun
2473
2474
@defun next-window
2475
@defunx previous-window
2476
Switch focus to the ``next'' or ``previous'' window in this
2477
workspace. If this function reaches the ``end'' of the windows in
2478
this workspace, it switches to the next workspace and displays the
2479
first window there.
2480
@end defun
2481
2482
@node Dynamic Window Cycles, , Fixed Window Cycles, Cycling Between Windows
2483
@subsection Dynamic Window Cycles
2484
@cindex Window cycles, dynamic
2485
2486
These commands implement something much close to Microsoft Windows'
2487
@key{Alt-TAB} mechanism, working with a stack of recently used
2488
windows.
2489
2490
@defun cycle-windows
2491
@defunx cycle-windows-backwards
2492
Cycle through all cycleable windows.
2493
@end defun
2494
2495
@defun cycle-group
2496
@defunx cycle-group-backwards
2497
Cycle through all windows in this group.
2498
2499
This is somewhat comparable to the @key{Control-TAB} behavior of
2500
windows.
2501
@end defun
2502
2503
@defun cycle-prefix
2504
@defunx cycle-prefix-backwards
2505
Cycle through all windows whose titles match that of the initial
2506
window (up to, but not including, the first colon).
2507
@end defun
2508
2509
@defun cycle-class
2510
@defunx cycle-class-backwards
2511
Cycle through all windows whose classes match that of the initial
2512
window.
2513
@end defun
2514
2515
@defun cycle-dock
2516
@defunx cycle-dock-backwards
2517
Cycle through all windows in the dock, even those with the
2518
@code{cycle-skip} property.
2519
@end defun
2520
2521
Each of these cycling commands may include windows that are not
2522
visible on-screen.
2523
2524
@defvar cycle-include-iconified
2525
If true, Sawfish includes iconified windows when cycling. Defaults to
2526
true.
2527
@end defvar
2528
2529
@defvar cycle-all-workspaces
2530
If true, Sawfish includes windows on all workspaces when cycling.
2531
Defaults to false.
2532
@end defvar
2533
2534
@defvar cycle-all-viewports
2535
If true, Sawfish includes windows on all viewports when cycling.
2536
Defaults to false.
2537
@end defvar
2538
2539
It is possible to configure the cycling to get more feedback during
2540
the process.
2541
2542
@defvar cycle-show-window-names
2543
If true, Sawfish displays window names and icons while cycling through
2544
windows. Defaults to true.
2545
@end defvar
2546
2547
@defvar cycle-raise-windows t
2548
If true, Sawfish raises windows while they're temporarily selected
2549
during cycling, and invokes @code{warp-pointer-if-necessary}.
2550
Defaults to true.
2551
@end defvar
2552
2553
It is also possible for you to define your own stacking cycle
2554
commands, or even to alter the window stack to suit your tastes.
2555
2556
@defun define-cycle-command name body &rest rest
2557
Create a command that will not cause the current cycle operation
2558
to abort before execution.
2559
2560
All arguments are passed to define-command.
2561
@end defun
2562
2563
@defun define-cycle-command-pair forward-name reverse-name selector &rest rest
2564
Create a pair of commands for cycling through windows. The command named
2565
@var{forward-name} cycles forwards, while the command named
2566
@var{reverse-name} cycles backwards.
2567
2568
@var{Selector} is called when initializing the cycle environment, it
2569
should return the list of windows to cycle through, or the symbol `t'
2570
to denote all cyclable windows.
2571
2572
Any extra arguments are passed to each call to define-command.
2573
@end defun
2574
2575
@defun window-order &optional workspace allow-iconified all-viewports
2576
Return managed windows in most-recently used order.
2577
2578
If @var{workspace} is non-nil, then only managed windows in that
2579
workspace will be returned.
2580
2581
If @var{allow-iconified} is non-nil, then iconified windows will be
2582
returned instead of ignored.
2583
2584
If @var{all-viewports} is non-nil, then windows in all viewports will
2585
be returned, instead of just the current viewport.
2586
@end defun
2587
2588
@defun window-order-push w
2589
Push window @var{w} onto the top of the cycle stack.
2590
@end defun
2591
2592
@defun window-order-pop w
2593
Remove window @var{w} from the cycle stack.
2594
@end defun
2595
2596
@defun window-order-most-recent &key windows
2597
Return the most-recently focused window in the current workspace. If
2598
the @var{windows} argument is given it should be a list of windows, in
2599
this case the function will restrict its search to the elements of
2600
this list.
2601
@end defun
2602
2603
@defun window-order-focus-most-recent
2604
Switch input focus to the most-recently focused window in the current
2605
workspace.
2606
@end defun
2607
2608
@node Window Groups, , Cycling Between Windows, Windows
2609
@section Window Groups
2610
@cindex Groups, windows
2611
2612
Sawfish provides extra tools and commands for dealing with ICCCM
2613
groups. Most ``normal'' groups work the same way as they do in the
2614
ICCCM standard: windows have a group property that is set to the X
2615
window ID of the group leader. These are ``group IDs'', and they are
2616
always positive integers. In addition, Sawfish allows group IDs to
2617
be:
2618
2619
@table @asis
2620
@item negative integers
2621
These are anonymous user-defined groups.
2622
@item symbols
2623
These are named user-defined groups. Named user-defined groups are
2624
saved as part of window properties when saving sessions.
2625
@end table
2626
2627
@defun window-group-ids
2628
Return the list of all group ids.
2629
@end defun
2630
2631
There may be certain named groups that always exist, whether or not
2632
any window belongs to them.
2633
2634
@defvar peristent-group-ids
2635
A list of symbols naming groups that always exist.
2636
@end defvar
2637
2638
In any case, a window is limited to belonging to one group, and always
2639
belongs to one group.
2640
2641
@menu
2642
* Assigning Windows to Groups::
2643
* Operations on Groups::
2644
@end menu
2645
2646
@node Assigning Windows to Groups, Operations on Groups, Window Groups, Window Groups
2647
@subsection Assigning Windows to Groups
2648
@cindex Groups, assigning windows to
2649
2650
It is possible to change the group of a window in Sawfish. Use
2651
@code{add-window-to-group}, or if necessary you can set the window's
2652
@code{group} property explicitly.
2653
2654
@defun add-window-to-group window group-id
2655
Place @var{window} in group @var{group-id}, replacing any previous
2656
group membership. If @var{group-id} is @code{nil}, then Sawfish
2657
returns the window to whatever group membership was supplied by ICCCM.
2658
@end defun
2659
2660
@defun add-window-to-new-group window
2661
Place @var{window} into a new group, which will have @var{window} as
2662
its sole member. This is an anonymous user-defined group. The new
2663
group ID is returned.
2664
@end defun
2665
2666
The Sawfish group assignment never overrides the ICCCM group
2667
assignment, just suppresses it. The @code{window-actual-group-id}
2668
function implements this overriding.
2669
2670
@defun window-actual-group-id window
2671
Return the (Sawfish) group ID for @var{window}. This is, in order of
2672
preference:
2673
@itemize @bullet
2674
@item The group ID assigned by Sawfish
2675
@item The group ID passed in by ICCCM.
2676
@item The corresponding values for an owning window, if the given window is transient.
2677
@item The window's own window ID.
2678
@end itemize
2679
2680
This means that a window is, at the very least, part of its own group.
2681
@end defun
2682
2683
Each of the following functions operates on the ``actual group ID'' as
2684
returned by the above function.
2685
2686
@defun windows-by-group group-id &optional by-depth
2687
Return the list of windows in the group with id @var{group-id}.
2688
If @var{by-depth} is non-nil, then return the windows in order of
2689
stacking, from topmost to bottommost.
2690
@end defun
2691
2692
@defun windows-in-group w &optional by-depth
2693
Return the list of windows in the same group as window @var{w}.
2694
If @var{by-depth} is non-nil, then return the windows in order of
2695
stacking, from topmost to bottommost.
2696
@end defun
2697
2698
@defun map-window-group fun w
2699
Map the single argument function @var{fun} over all windows in the
2700
same group as window @var{w}. Note that @var{fun} needs to operate
2701
using side-effects, rather than returning values.
2702
@end defun
2703
2704
@defun map-other-window-groups fun w
2705
Map the single argument function @var{fun} over all windows not in the
2706
same group as window @var{w}. Note that @var{fun} needs to operate
2707
using side-effects, rather than returning values.
2708
@end defun
2709
2710
@defun window-group-menu &optional w
2711
Return a menu definition suitable for @code{popup-menu}. This menu
2712
will allow the user to assign the window @var{w} into any group of a
2713
managed window, or into a brand new group. The window's current group
2714
is checked or otherwise marked.
2715
@end defun
2716
2717
@node Operations on Groups, , Assigning Windows to Groups, Window Groups
2718
@subsection Operations on Groups
2719
@cindex Groups, operations on
2720
2721
Most of the window manipulation functions that operate on windows are
2722
also available for window groups. Each of these functions takes a
2723
window as argument; the affected group is that window's group.
2724
2725
@defun iconify-group w
2726
@defunx uniconify-group w
2727
@defunx iconify-transient-group w
2728
@defunx uniconify-transient-group w
2729
These operate like their single-window counterparts. They work by
2730
temporarily rebinding @code{iconify-group-mode} and
2731
@code{uniconify-group-mode}.
2732
@end defun
2733
2734
@defun make-group-sticky w
2735
@defunx make-group-unsticky w
2736
These operate like their single-window counterparts.
2737
@end defun
2738
2739
@defun toggle-group-sticky w
2740
If window @var{w} is sticky, all windows in its group have their
2741
stickyness removed. Otherwise all windows in its group become sticky.
2742
@end defun
2743
2744
@defun send-group-to-workspace w workspace
2745
@defunx send-group-to-next-workspace w count
2746
@defunx send-group-to-previous-workspace w count
2747
These operate like their single-window counterparts.
2748
@end defun
2749
2750
@defun send-group-to-current-workspace w
2751
All windows in the group of @var{w} are moved from their existing
2752
workspaces to the nearest workspace that @var{w} is in. Sticky
2753
windows are not affected. If the window had the input focus and it is
2754
visible after the move, it retains the input focus.
2755
@end defun
2756
2757
@defun move-group-to-current-viewport w
2758
@defunx move-group-viewport w
2759
@end defun
2760
2761
@defun move-group-left w
2762
@defunx move-group-right w
2763
@defunx move-group-up w
2764
@defunx move-group-down w
2765
These operate like their single-window counterparts.
2766
@end defun
2767
2768
@defun raise-group w
2769
@defunx lower-group w
2770
@defunx raise-lower-group w
2771
@defunx raise-group-depth w
2772
@defunx lower-group-depth w
2773
These operate like their single-window counterparts.
2774
@end defun
2775
2776
@defun set-group-frame-style w style
2777
This operates like its single-window counterpart.
2778
@end defun
2779
2780
@node Customization, Window Frames, Windows, Top
2781
@chapter Customization
2782
@cindex Customization
2783
2784
Sawfish provides two levels of configuration:
2785
2786
@enumerate
2787
@item @dfn{customization}: setting variables to change the behavior of
2788
existing features of the window manager, and,
2789
2790
@item @dfn{extensibility}: the ability to add entirely new features to
2791
the window manager through the creation of new Lisp modules.
2792
@end enumerate
2793
2794
Obviously the first of these requires a lot less specialized knowledge
2795
than the second. But even then, the user has to edit startup files
2796
containing the Lisp forms setting the variables. To remove this need
2797
for hand-editing, Sawfish has a specialized system allowing all
2798
customizations to be made through a GUI, and then automatically
2799
reloaded each time that the window manager is started.
2800
2801
@deffn Command customize &optional group
2802
Invoke the user-customization GUI. @var{group} defines the class of
2803
customization variables to configure, or all classes if @var{group} is
2804
undefined.
2805
@end deffn
2806
2807
The @file{sawfish-ui} program can be used to invoke the GUI manually;
2808
if GNOME is being used, then the GNOME Control Center can also be used
2809
to customize certain classes.
2810
2811
In order to provide these customization options however, an extra
2812
requirement is placed on the Lisp programmer. Instead of just using the
2813
@code{defvar} special form to declare variables, the @code{defcustom}
2814
macro must be used. This augments the variable with extra information
2815
for the GUI, including such things as its required data type.
2816
2817
@menu
2818
* Defgroup and Defcustom::
2819
* Customization Files::
2820
* Customized Variable Status::
2821
@end menu
2822
2823
@node Defgroup and Defcustom, Customization Files, Customization, Customization
2824
@section Defgroup and Defcustom
2825
@cindex defgroup
2826
@cindex defcustom
2827
2828
Customization options are organized into groups. Each group has a name
2829
and contains a set of related options. Groups can be assigned to
2830
parent groups using the @code{:group} parameter during construction.
2831
2832
@defmac defgroup group real-name &rest keys
2833
Declares a new customization group whose name is defined by the symbol
2834
@var{group}. The string @var{real-name} is the title of the group as
2835
seen by the user.
2836
2837
@var{keys} is a list, defining the properties of the group. The members
2838
of the list are grouped into pairs of elements, the first element names
2839
the property, the second defines its value.
2840
2841
@table @code
2842
@item :group @var{group}
2843
Specifies the parent customization group of this group. The value of
2844
this key is not evaluated.
2845
2846
@item :require @var{struct}
2847
Before displaying the customization UI for this group, @code{require}
2848
the structure @var{struct}. This guarantees that all customizable
2849
variables will be known at display time. The value of
2850
this key is not evaluated.
2851
2852
@item :layout @var{symbol}
2853
Use a particular UI widget to display this group. The value is a
2854
symbol, one of:
2855
2856
@table @code
2857
@item single
2858
Holds a single customizable item.
2859
@item vbox
2860
Holds any number of customizable items, arranging them vertically.
2861
This is the default.
2862
@item hbox
2863
Holds any number of customizable items, arranging them horizontally.
2864
@item frame
2865
Embed the items in a vbox in a frame.
2866
@item keymaps
2867
Use a special UI widget for customizing keymaps.
2868
@end table
2869
2870
The value of this key is not evaluated.
2871
@end table
2872
2873
This macro also creates an interactive function named
2874
@code{customize:@var{group}} allowing the GUI to be invoked to
2875
configure the new group.
2876
2877
While @code{defgroup} is a macro, there is a corresponding
2878
@code{custom-declare-group} function.
2879
@end defmac
2880
2881
@defmac defcustom variable value documentation &rest keys
2882
The first three arguments are analogous to the @code{defvar} special
2883
form, they declare a special variable stored in the symbol
2884
@var{variable}, whose value is set to @var{value} if the variable is
2885
currently unbound, with a documentation string @var{documentation}.
2886
2887
All other parameters are key-value pairs as with @code{defgroup}. The
2888
possible pairs are as follows:
2889
2890
@table @code
2891
@item :group @var{group}
2892
Specifies the customization group that this variable is a member of.
2893
This is a list of symbols, indicating a series of nested groups, e.g.,
2894
@code{(workspace edge-flip)}. A variable in a top-level customization
2895
group can also be specified as a plain symbol, e.g., @code{workspace}.
2896
The value of this key is not evaluated.
2897
2898
@item :type @var{type}
2899
Specifies the required type of the variable. The current possibilities
2900
are:
2901
2902
@item @code{(symbol [@var{option} @dots{}])}
2903
A symbol. The UI looks for a symbol property @code{:options} and
2904
interprets it as the list of valid symbols to select from. The
2905
@var{option} arguments allow you to define a list at eval time. It is
2906
also possible to change this list at run time by changing the custom
2907
symbol's @code{:options} property; see the access functions
2908
@code{custom-add-options} and @code{custom-set-options} for more
2909
information.
2910
2911
@item @code{(choice @var{option} @dots{})}
2912
One of the @var{option} elements. Each @var{option} is a symbol.
2913
Unlike the @code{symbol} type, there is no expectation that this list
2914
will change at run-time.
2915
2916
@item @code{string}
2917
An arbitrary string.
2918
2919
@item @code{(number [[@var{min}] @var{max}]}
2920
Integer number. Two additional arguments specify the minimum and
2921
maximum allowed values for the integer. One additional argument
2922
specified the maximum allowed value; the minimum defaults to zero.
2923
Zero additional arguments implies no minimum nor maximum.
2924
2925
@item @code{boolean}
2926
True (@code{t}) or false (@code{nil}) value.
2927
2928
@item @code{color}
2929
A color.
2930
2931
@item @code{font}
2932
A font name.
2933
2934
@item @code{file}
2935
A file name.
2936
2937
@item @code{program}
2938
A file name that must be an executable program.
2939
2940
@item @code{command}
2941
A Sawfish command.
2942
2943
@item @code{event}
2944
A Sawfish event.
2945
2946
@item @code{keymap}
2947
A Sawfish keymap.
2948
2949
@item @code{frame-style}
2950
The name of a defined Sawfish frame style.
2951
2952
@item @code{icon}
2953
An X icon.
2954
2955
@item @code{modifier-list}
2956
A list of X modifier keys.
2957
2958
@c @item @code{workspace-geometry}
2959
@c A @code{(@var{columns} . @var{rows})} pair.
2960
2961
@end table
2962
2963
Except where specified, the values of these keys are not evaluated.
2964
2965
@table @code
2966
@item :require @var{feature}
2967
Denotes that the feature @var{feature} must be loaded if the variable
2968
is set to a non-@code{nil} value by user customizations. This is
2969
necessary because customization options are loaded on startup, possibly
2970
before the modules that define them.
2971
The value of this key is not evaluated.
2972
2973
@item :allow-nil @var{bool}
2974
Specifies whether the variable may be @code{nil}, instead of a member
2975
of its actual type. This is only supported by the @code{string},
2976
@code{symbol}, @code{font} and @code{color} types.
2977
2978
@item :set @var{function}
2979
Specifies that the variable must be set by calling @var{function}
2980
instead of the default @code{custom-set-variable}. The function should
2981
accept three arguments: @code{(@var{variable} @var{value} &optional
2982
@var{require})}.
2983
2984
The usual action of this function is to translate the value into the
2985
correct type, then call @code{custom-set-variable}. This translation is
2986
necessary since many of the UI widgets accept strings representing more
2987
complex types (i.e. a color's name, instead of the actual object)
2988
2989
@item :get @var{function}
2990
Provides a function for reading the current value of the variable.
2991
Should return a value that's acceptable to the UI widget associated
2992
with the variable. Called with a single argument, the symbol containing
2993
the variable.
2994
2995
@item :before-set @var{function}
2996
@itemx :after-set @var{function}
2997
Functions called both immediately before and after setting the value of
2998
the variable. Called with a single parameter: the variable itself.
2999
3000
@item :range (@var{min} . @var{max})
3001
The allowed range for numeric variables. If @var{min} is @code{nil} the
3002
the default minimum allowed value is zero; if @var{max} is @code{nil}
3003
then the default maximum is unbounded. This is obsolete, since the
3004
@code{:number} type now supports range declarations.
3005
The value of this key is not evaluated.
3006
3007
@item :tooltop @var{string}
3008
A tooltip that appears when the user's mouse hovers over the widget
3009
item.
3010
3011
@item :depends @var{symbol}
3012
This widget item is only settable when the symbol-value for
3013
@var{symbol} is non-nil.
3014
3015
@end table
3016
3017
While @code{defcustom} is a macro, there is a corresponding
3018
@code{custom-declare-variable} function.
3019
@end defmac
3020
3021
Note that where necessary the types themselves define default
3022
@code{:set}, @code{:get} and @code{:widget} values that may be
3023
overridden by values in the @code{defcustom} call. Usually, however,
3024
this will not be necessary.
3025
3026
Consider the following example:
3027
3028
@lisp
3029
(defgroup move "Move/Resize")
3030
3031
(defcustom move-outline-mode 'opaque
3032
"The method of drawing windows being moved interactively."
3033
:type (set opaque box)
3034
:group move)
3035
3036
(defcustom move-snap-epsilon 8
3037
"Proximity in pixels before snapping to a window edge."
3038
:group move
3039
:type (number 0 64))
3040
@end lisp
3041
3042
@noindent
3043
This defines a group and two customization options.
3044
3045
There are two special accessor functions to make it easier to deal
3046
with lists of allowed symbols.
3047
3048
@defun custom-add-option variable option
3049
Add symbol value @var{option} to the list of symbols that can be
3050
stored in @var{variable}. The new option goes on the end of the
3051
list.
3052
@end defun
3053
3054
@defun custom-get-options variable
3055
Return the list of symbols that can be stored in @var{variable}.
3056
@end defun
3057
3058
@node Customization Files, Customized Variable Status, Defgroup and Defcustom, Customization
3059
@section Customization Files
3060
@cindex Customization files
3061
@cindex Files, customization
3062
3063
@defvar custom-user-file
3064
User configuration settings are stored in the file referenced by this
3065
variable. While this file contains valid Rep forms, users should not
3066
edit it directly: Sawfish will overwrite the file's contents each time
3067
a customization is made through the GUI.
3068
3069
By default, this variable is set to @code{"~/.sawfish/custom"}. The
3070
@code{--custom-file} command-line option sets it to a different file
3071
on program startup.
3072
@end defvar
3073
3074
@defvar custom-default-file
3075
Default customization settings are stored in the file referenced by
3076
this variable. These settings are only applied if the user has no
3077
personal settings. By default, this variable is set to
3078
@code{"sawfish/wm/custom-defaults.jl"} relative to the
3079
@code{sawfish-lisp-lib-directory} directory.
3080
@end defvar
3081
3082
@defun custom-load-user-file
3083
If the file referenced by @code{custom-user-file} exists, load it.
3084
Otherwise if @code{custom-default-file} is non-nil, interpret it as a
3085
filename and load it.
3086
@end defun
3087
3088
@node Customized Variable Status, , Customization Files, Customization
3089
@section Customized Variable Status
3090
3091
To get information about a customizable variable, you can use the
3092
following functions.
3093
3094
@defun variable-customized-p symbol
3095
Returns true if @var{symbol} has been customized by the user, false
3096
otherwise.
3097
@end defun
3098
3099
@defun variable-declared-p symbol
3100
@defunx variable-default-value symbol
3101
The @code{variable-declared-p} function returns true if the variable
3102
named @var{symbol} has a default value declared for it, false
3103
otherwise. The @code{variable-default-value} function returns the
3104
default value of that variable, or nil if no such default value
3105
exists.
3106
@end defun
3107
3108
@defun variable-type symbol
3109
Returns the customizable type of the variable named @var{symbol}.
3110
@end defun
3111
3112
@node Window Frames, Viewports, Customization, Top
3113
@chapter Window Frames
3114
@cindex Window frames
3115
@cindex Frames, of windows
3116
3117
Perhaps one of the most important features of a window manager is its
3118
ability to decorate client windows, typically seen as an added border,
3119
and then to allow the window to be manipulated through user input on
3120
the border.
3121
3122
Sawfish provides an extremely flexible method of decorating windows,
3123
the look and feel of the border may be specified completely. Also, no
3124
limits are placed on which windows are given which borders, if
3125
necessary a completely different border could be dynamically created
3126
for each window!
3127
3128
@menu
3129
* Frame Basics::
3130
* Frame Part Classes::
3131
* Frame Part Definition::
3132
* Frame Functions::
3133
* Frame Types::
3134
* Frame Styles::
3135
* Themes::
3136
* Removing Frame Parts::
3137
@end menu
3138
3139
@node Frame Basics, Frame Part Classes, , Window Frames
3140
@section Frame Basics
3141
@cindex Frame basics
3142
@cindex Window frames, basics
3143
3144
The @dfn{frame} of a client window is defined as all decorations added
3145
by the window manager. Usually these decorations will be immediately
3146
adjacent to the outer edges of the window, but there is no requirement
3147
to use this model.
3148
3149
In Sawfish, each window frame is constructed from a list of @dfn{frame
3150
parts}, conceptually rectangular objects with a specified position
3151
relative to the edges of the client window. When shaped images are used
3152
to define frame parts, they are still thought of as being rectangular,
3153
just with some pixels missing from the display.
3154
3155
Each frame part has a list of attributes associated with it, these
3156
include items defining the background of the part (i.e. a color or an
3157
image), and items defining the foreground of the part (i.e. probably
3158
some kind of text, with a color, font, etc@dots{}). Non-visual
3159
attributes may also be defined, such as, for example, the keymap
3160
mapping events occurring in the part to Lisp commands to execute
3161
(@pxref{Keymaps}).
3162
3163
So a window frame is defined in Lisp as a list of frame part
3164
definitions (@pxref{Frame Part Definition}). These frame parts are
3165
added to the client window (in the order they are defined, so later
3166
frame parts are above earlier parts at the same position), to produce
3167
the entire window frame.
3168
3169
3170
@node Frame Part Classes, Frame Part Definition, Frame Basics, Window Frames
3171
@section Frame Part Classes
3172
@cindex Frame part classes
3173
@cindex Window frames, frame part classes
3174
@cindex Classes, of frame parts
3175
3176
Although one of the aims of Sawfish is to provide as much flexibility
3177
as possible, this can sometimes be detrimental to the overall
3178
experience. For example, it would be easier for the user if all themes
3179
use consistent keymaps and cursor images in conceptually similar parts
3180
of window frames. That is, it would be better if all close buttons had
3181
the same mouse button bindings and the same mouse cursor displayed when
3182
the pointer is over them.
3183
3184
To achieve this, Sawfish defines a number of @dfn{classes} of frame
3185
parts, each with several default attributes. When defining a window
3186
frame, the definitions of each part then specifies which class it is a
3187
member of, and inherits the associated default attributes (provided
3188
that it hasn't explicitly specified values for these attributes).
3189
3190
@defvar frame-part-classes
3191
This variable is an association list, associating symbols naming frame
3192
part classes with an association list of default attributes for that
3193
class.
3194
@end defvar
3195
3196
The names of the pre-defined classes are as follows, their meanings
3197
should be self-explanatory:
3198
3199
@code{title}, @code{menu-button}, @code{close-button},
3200
@code{iconify-button}, @code{maximize-button}, @code{top-border},
3201
@code{left-border}, @code{right-border}, @code{bottom-border},
3202
@code{top-left-corner}, @code{top-right-corner},
3203
@code{bottom-left-corner}, @code{bottom-right-corner}.
3204
3205
@noindent
3206
Extra classes can be created by adding to @code{frame-part-classes}.
3207
However, it's likely that more than one theme may need to use the same
3208
class, and that the user may then wish to customize any extra keymaps
3209
used. The @code{def-frame-class} macro should be used to add new
3210
classes, since it handles these situations.
3211
3212
@defmac def-frame-class class alist-form &rest binding-forms @dots{}
3213
Creates a new frame part class named by the symbol @var{CLASS}.
3214
3215
The @var{ALIST-FORM} is evaluated to give an association list defining
3216
attributes for the class. Each key-value pairs is only set if no
3217
existing value exists for that key.
3218
3219
If @var{binding-forms} are given, they will be evaluated when no keymap
3220
already exists for the class. A keymap will be created, and stored in
3221
the variable named @samp{@var{class}-name}. This variable may then be
3222
used within the @var{binding-forms}.
3223
@end defmac
3224
3225
So to define a hypothetical @code{shade-button} class, the following
3226
might be used:
3227
3228
@lisp
3229
(def-frame-class shade-button '((cursor . left_ptr))
3230
(bind-keys shade-button-keymap
3231
"Button1-Off" 'toggle-window-shaded))
3232
@end lisp
3233
3234
In some cases it might be valuable to be able to override pre-defined
3235
frame part properties. For example, it might be your preference that
3236
text in window title bars is always blue.
3237
3238
@defun define-frame-class class alist-form &optional with-keymap
3239
Creates a new frame part class named by the symbol @var{class}.
3240
3241
Unlike @code{def-frame-class}, the trailing argument is just a boolean
3242
flag. This flag only indicates whether to create a keymap for the
3243
class. Any bindings have to be established through a separate call to
3244
@code{bind-keys}.
3245
3246
The function returns @code{t} if it was able to create and bind the
3247
empty keymap, @code{nil} otherwise. This allows us to check for
3248
errors.
3249
@end defun
3250
3251
@defvar override-frame-part-classes
3252
Similar to @code{frame-part-classes} except that the properties take
3253
precedence over values defined both in that variable and in the frame
3254
style itself.
3255
@end defvar
3256
3257
The following function may be used to simplify the customization of
3258
these two variables:
3259
3260
@defun set-frame-part-value class key value &optional override
3261
Associate @var{value} with property @var{key} for all frame parts of
3262
class @var{class}.
3263
3264
If @var{override} is non-nil, then the setting is installed in the
3265
@code{override-frame-part-classes} variable, otherwise it's stored in
3266
the @code{frame-part-classes} variable.
3267
@end defun
3268
3269
@noindent
3270
The following example would override the colors of all title bars:
3271
3272
@lisp
3273
(set-frame-part-value 'title 'background
3274
'("black" "white" "green" "blue") t)
3275
@end lisp
3276
3277
@noindent
3278
(See the next section for details about what is actually being set
3279
here.)
3280
3281
3282
@node Frame Part Definition, Frame Functions, Frame Part Classes, Window Frames
3283
@section Frame Part Definitions
3284
@cindex Frame part definitions
3285
@cindex Window frames, frame part definitions
3286
3287
Each frame part is defined as an association list (or alist), a list of
3288
cons cells, the car of each cell defines the attribute, the cdr defines
3289
the value given to that attribute. So, for example, the alist
3290
@code{((foo . 1) (bar . 2))} specifies two attributes: @code{foo} with
3291
value @code{1}, and @code{bar} with value @code{2}. @xref{Association
3292
Lists, , Association Lists, librep, The Librep Manual}.
3293
3294
The attributes that may be defined are as follows:
3295
3296
@table @code
3297
@item (class . @var{class})
3298
Specifies the frame part class of the part.
3299
3300
@item (background . @var{data})
3301
@itemx (background . (@var{normal} @var{focused} @var{highlighted} @var{clicked}))
3302
Specifies the background of the part. May be a color, an image, or a
3303
string naming a color. If a single element, then it is used for all
3304
states of the part, otherwise if a list, then each of the four elements
3305
defines the background for that particular state.
3306
3307
If an image is used it will be scaled to the size of the frame part,
3308
unless it's @code{tiled} property is set, in which case it will be
3309
tiled across the frame part.
3310
3311
@item (foreground . @var{data})
3312
@itemx (foreground . (@var{normal} @var{focused} @var{highlighted} @var{clicked}))
3313
Specifies a foreground color or image for the frame part, either for
3314
all states, or for each individual state.
3315
3316
Unlike the @code{background} attribute, by default images are not
3317
scaled when used to define the foreground of a frame part.
3318
3319
@item (scale-foreground . @var{value})
3320
When @var{value} is non-@code{nil}, the foreground image of the frame
3321
part will be scaled to the size of the part.
3322
3323
@item (font . @var{font})
3324
@itemx (font . (@var{normal} @var{focused} @var{highlighted} @var{clicked}))
3325
Specifies the font(s) of the part.
3326
3327
@item (text . @var{value})
3328
Specifies the string to draw in the foreground of the frame part
3329
(unless the @code{foreground} property is an image). Either a string,
3330
or a function, that will be called each time that the part is
3331
refreshed, that will return the string to draw.
3332
3333
@item (x-justify . @var{value})
3334
Defines the horizontal position of the foreground contents of the part
3335
(i.e. the text or foreground image). May be one of the symbols
3336
@code{left}, @code{right} or @code{center}, or a number. If a number it
3337
defines the number of pixels from the left edge if positive, or the
3338
right edge if negative.
3339
3340
@item (y-justify . @var{value})
3341
Similar to @code{x-justify}, but the accepted symbols are @code{top},
3342
@code{bottom} or @code{center} instead.
3343
3344
@item (renderer . @var{function})
3345
This attribute may be used instead of the @code{background} attribute.
3346
When the part needs to be drawn @var{function} will be called with an
3347
image in which to render the background, and the current state of the
3348
part, a symbol @code{focused}, @code{highlighted}, @code{clicked}, or
3349
@code{nil} (for the normal state).
3350
3351
@item (render-scale . @var{value})
3352
This attribute causes the size of the image used with the
3353
@code{renderer} property to be reduced by a factor of @var{value}, an
3354
integer.
3355
3356
@item (left-edge . @var{value})
3357
Defines the position of the left edge of the part, in relation to the
3358
left edge of the client window.
3359
3360
@item (right-edge . @var{value})
3361
Defines the position of the right edge of the part, in relation to the
3362
right edge of the client window.
3363
3364
@item (top-edge . @var{value})
3365
Defines the position of the top edge of the part, in relation to the
3366
top edge of the client window.
3367
3368
@item (bottom-edge . @var{value})
3369
Defines the position of the bottom edge of the part, in relation to the
3370
bottom edge of the client window.
3371
3372
@item (width . @var{value})
3373
Defines the width of the frame part.
3374
3375
@item (height . @var{value})
3376
Defines the height of the frame part.
3377
3378
@item (keymap . @var{value})
3379
Defines the keymap to use when evaluating events originating in this
3380
frame part.
3381
3382
@item (cursor . @var{cursor})
3383
Defines the cursor to display when the mouse is in this part. May be
3384
either a cursor object, or the argument to @code{get-cursor} to create
3385
the required cursor object.
3386
3387
@item (removable . @var{value})
3388
When specified and @var{value} is non-@code{nil}, this frame part may
3389
be removed from the frame without being detrimental to the overall
3390
appearance of the frame. This is only important for button classes,
3391
which may sometimes be removed at the request of the client window.
3392
3393
@item (below-client . @var{value})
3394
When specified and @var{value} is non-@code{nil}, then this frame part
3395
will be displayed beneath the client window. The default action is for
3396
frame parts to be stacked above the client window.
3397
3398
@item (hidden . @var{value})
3399
When specified and @var{value} is non-@code{nil}, don't display this
3400
frame part.
3401
3402
@end table
3403
3404
The values specified for the @code{background}, @code{foreground},
3405
@code{render-scale}, @code{font}, @code{left-edge}, @code{right-edge},
3406
@code{top-edge}, @code{bottom-edge}, @code{width}, @code{height},
3407
@code{cursor}, @code{below-client} and @code{hidden} attributes may
3408
actually be functions. In which case the function will be called (with
3409
a single argument, the window object) when the frame is constructed,
3410
the value returned will be used as the actual value of the attribute.
3411
3412
The coordinate system used for specifying the part's position is
3413
relative to the window edge that the position is defined against.
3414
Positive values count in from the window edge towards the center of the
3415
window, while negative values count out from the edge, away from the
3416
center of the window.
3417
3418
Consider the following example, a solid black title bar that is twenty
3419
pixels high, directly above the client window:
3420
3421
@lisp
3422
`((background . "black")
3423
(foreground . "white")
3424
(text . ,window-name)
3425
(x-justify . 30)
3426
(y-justify . center)
3427
(left-edge . 0)
3428
(right-edge . 0)
3429
(top-edge . -20)
3430
(height . 20)
3431
(class . title))
3432
@end lisp
3433
3434
@noindent
3435
The backquote operator is used since the definition is only mostly
3436
constant, the comma operator inserts the value of the
3437
@code{window-name} variable (a function giving the name of a window)
3438
into the definition; @pxref{Backquoting, , Backquoting, librep, The
3439
Librep Manual}).
3440
3441
This function is then used to dynamically specify the string drawn in
3442
the foreground. The window manager will automatically refresh the
3443
foreground of all frame parts of a window whenever any X property of
3444
that window changes.
3445
3446
Given a framed window, and a particular frame part class, it is
3447
possible to retrieve the values of individual attributes from the
3448
complete list of definitions (including inherited or overrided
3449
definitions).
3450
3451
@defun frame-part-get part property
3452
Returns the value of the property @var{property} for the frame part
3453
object @var{part}. Returns @code{nil} if no such attribute exists.
3454
@end defun
3455
3456
@defun frame-part-put part prop value
3457
Set the property @var{prop} of frame part @var{part} to @var{value}.
3458
@end defun
3459
3460
@defun frame-part-state part
3461
Return the current state for frame part @var{part}, one of the symbols
3462
@code{focused}, @code{highlighted}, @code{clicked},
3463
@code{inactive-highlighted}, @code{inactive-clicked}, or @code{nil} if
3464
the part is inactive.
3465
@end defun
3466
3467
@node Frame Functions, Frame Types, Frame Part Definition, Window Frames
3468
@section Frame Functions
3469
@cindex Frame functions
3470
@cindex Window frames, functions
3471
3472
@defun set-window-frame window frame-def
3473
Sets the frame of the client window associated with the object
3474
@var{window} to that defined by the list of frame part definitions
3475
@var{frame-def}. If the window is mapped the old frame will be
3476
destroyed and a new frame constructed.
3477
@end defun
3478
3479
@defun window-frame window
3480
Return the list of frame part definitions defining the frame associated
3481
with @var{window}.
3482
@end defun
3483
3484
@defun window-framed-p window
3485
Return @code{t} when @var{window} has been reparented to a frame
3486
created by the window manager.
3487
@end defun
3488
3489
@defun refresh-window window
3490
Refresh all the frame parts belonging to @var{window}.
3491
@end defun
3492
3493
@defun rebuild-frame window
3494
Recreates the window frame associated with @var{window}, from the
3495
previously defined frame definition. All frame parts are reinitialized
3496
and recalibrated.
3497
@end defun
3498
3499
@defun window-frame-dimensions window
3500
Return a cons cell @code{(@var{width} . @var{height})} defining the
3501
dimensions of the frame associated with @var{window}. These will always
3502
be greater than or equal to the dimensions of the client window.
3503
3504
If @var{window} is not framed, then this function returns the same
3505
values as @code{window-dimensions} would.
3506
@end defun
3507
3508
@defun window-frame-offset window
3509
Return a cons cell @code{(@var{x} . @var{y})} defining the offset from
3510
the origin of the client window associated with @var{window} to the
3511
origin of its frame.
3512
@end defun
3513
3514
@defun window-border-width window
3515
Return the width of the border of the window that @var{window}
3516
manages.
3517
@end defun
3518
3519
@defun clicked-frame-part
3520
Return a pointer to the frame part object that was clicked on as part
3521
of the current event. Returns @code{nil} if no frame part was clicked
3522
on.
3523
@end defun
3524
3525
@defun frame-part-dimensions part
3526
Return a cons cell @code{(@var{width} . @var{height})} of dimensions
3527
for frame part @var{part}.
3528
@end defun
3529
3530
@defun frame-part-position part
3531
Return a cons cell @code{(@var{x} . @var{x})} of the @emph{relative}
3532
position of frame part @var{part} against its window's frame
3533
origin.
3534
@end defun
3535
3536
@defun frame-part-window part
3537
Return the window object associated with this frame part.
3538
@end defun
3539
3540
@defun frame-part-x-window part
3541
Return the X11 window ID associated with this frame part.
3542
@end defun
3543
3544
@defun frame-draw-mutex lock
3545
Called with @var{lock} equal to @code{t}, frame part redraws will be
3546
delayed. The redraws will take place once the function is called with
3547
@var{lock} set to @code{nil}.
3548
@end defun
3549
3550
@defun map-frame-parts function window
3551
Call @code{(@var{function} @var{part})} on each the frame parts of
3552
@var{window} and return @code{nil}. If any @var{function} returns
3553
@code{nil}, @code{map-frame-parts} returns @code{nil} immediately.
3554
@end defun
3555
3556
@defun rebuild-frame-part part
3557
Build a new copy of the frame part @var{part} and install the copy in
3558
the owning window, replacing the old part.
3559
@end defun
3560
3561
@defun refresh-frame-part part
3562
The frame part @var{part} will be redrawn at the next opportunity.
3563
@end defun
3564
3565
3566
@node Frame Types, Frame Styles, Frame Functions, Window Frames
3567
@section Frame Types
3568
@cindex Frame types
3569
@cindex Window frames, types
3570
3571
In order to visually differentiate between different types of windows,
3572
several predefined types of window frame exist.
3573
3574
@defun window-type window
3575
Returns a symbol naming the frame type currently associated with
3576
@var{window}.
3577
@end defun
3578
3579
These frame types currently include the following:
3580
3581
@table @code
3582
@item default
3583
The normal frame type. Includes all decorations, both borders and the
3584
title bar.
3585
3586
@item transient
3587
The frame for a transient window. This usually does not include a title
3588
bar, but does have all four borders.
3589
3590
@item shaped
3591
Shaped windows are normally decorated with only a title-bar, since
3592
their boundary is not rectangular it makes no sense to surround them
3593
with a rectangular border.
3594
3595
@item shaped-transient
3596
A combination of the @code{shaped} and @code{transient} types, normally
3597
just a very small title border with no text.
3598
3599
@item shaded
3600
A shaded window (normally just the title bar).
3601
3602
@item shaded-transient
3603
A shaded transient window.
3604
3605
@item unframed
3606
No frame at all, just the client window itself. The predefined
3607
@code{nil-frame} variable contains a null frame that may be used for
3608
this frame type.
3609
@end table
3610
3611
@defun define-frame-type-mapper fun
3612
Function @var{fun} maps from @{@var{window}, @var{frame-type}@} to
3613
@var{frame-type}.
3614
3615
Each time we want to determine a window's frame-type (@code{shaded},
3616
@code{transient}, etc.), we calculate an initial frame type with
3617
@code{window-type} and run the results through each frame type mapper
3618
in sequence (most recent to oldest). The frame type returned from the
3619
final mapper function is ``the'' frame type.
3620
3621
This sequence of mappers allows us to override window frame types
3622
based on window properties. For example, any shaded window has to
3623
have @code{shaded} or @code{shaded-transient} type, regardless of what
3624
its normal type is.
3625
@end defun
3626
3627
@defun window-type-add-border type
3628
@defunx window-type-add-title type
3629
@defunx window-type-remove-border type
3630
@defunx window-type-remove-title type
3631
Given a window type of @var{type}, return the closest matching window
3632
type with the given property change. For example:
3633
3634
@lisp
3635
(window-type-add-title 'unframed)
3636
@result{} 'shaped
3637
@end lisp
3638
3639
@noindent
3640
This is because shaped windows normally have title bars but not
3641
borders, while unframed windows normally have neither.
3642
@end defun
3643
3644
@defun frame-type-menu window
3645
Returns a list of frame types, suitable for use by the graphical
3646
customizer. The frame type of @var{window} is automatically checked.
3647
@end defun
3648
3649
We provide a function to simplify monitoring of window changes to certain
3650
window states. This monitoring runs on top of the
3651
@code{window-state-change-hook}.
3652
3653
@defun call-after-state-changed states fun
3654
Arrange for function @var{fun} to be called with arguments
3655
@samp{(window changed-states)} when one of the states defined by the
3656
list of symbols @var{states} has been changed. @var{States} may also
3657
be a single symbol.
3658
@end defun
3659
3660
@node Frame Styles, Themes, Frame Types, Window Frames
3661
@section Frame Styles
3662
@cindex Frame styles
3663
@cindex Styles, frame
3664
@cindex Window frames, styles
3665
3666
Frame styles are used to encapsulate frames of the different types that
3667
have a single visual appearance. Each frame style associates a name
3668
with a function that creates a frame definition for a particular window
3669
and frame type combination.
3670
3671
Several window properties are used while choosing frame styles:
3672
3673
@defvr {Window Property} frame-style
3674
The user-chosen frame style of the window. If @code{nil}, Sawfish
3675
will use the default frame style.
3676
@end defvr
3677
3678
@defvr {Window Property} current-frame-style
3679
The current frame style of the window. This is not set explicitly;
3680
window update functions will change it behind the scenes.
3681
@end defvr
3682
3683
@defvr {Window Property} ignored
3684
When set, the window is not given a frame.
3685
@end defvr
3686
3687
It is possible to edit certain frame styles in place with
3688
@code{sawfish-themer}.
3689
3690
@defun frame-style-editable-p style
3691
Returns @code{t} if @var{style} can be edited interactively,
3692
@code{nil} otherwise.
3693
@end defun
3694
3695
@deffn {Command} edit-frame-style style
3696
Prompts for a frame style (defaulting to the value of @code{default-frame-style}),
3697
and runs @code{sawfish-themer-program} on it.
3698
@end deffn
3699
3700
@defun reload-frame-style name
3701
Reloads the frame style @var{name} from disk if it is already known to
3702
the system. All windows with that style are reframed.
3703
@end defun
3704
3705
@node Themes, Removing Frame Parts, Frame Styles, Window Frames
3706
@section Themes
3707
@cindex Themes
3708
@cindex Window frames, themes
3709
3710
Themes and frame styles are currently almost synonymous, the slight
3711
difference being that themes provide a mechanism for loading frame
3712
styles from the filing system as they are required. Although it is
3713
possible that themes may include other user-interface settings in a
3714
later version, at the moment it seems unlikely.
3715
3716
When a frame style is requested, if it is not already available (i.e.
3717
if the @code{add-frame-style} function hasn't been called for that
3718
style) then the window manager will attempt to load a theme of the same
3719
name from the filing system.
3720
3721
Each theme is stored in a directory; this directory must have the same
3722
name as the name of the theme itself. Within this directory there must
3723
be a Lisp script named @file{theme.jl} or @file{theme.jlc}. This script
3724
will be evaluated, it should provide a frame style of the same name as
3725
the theme (by calling @code{add-frame-style}).
3726
3727
While the theme script is evaluating the @code{image-load-path}
3728
variable is set to include the theme directory as its first element.
3729
This ensures that any image files stored in the directory can be loaded
3730
using the @code{make-image} function.
3731
3732
Since rep has no module system, any global variables defined within the
3733
theme must be prefixed by the name of the theme to ensure their
3734
uniqueness. For example, in the theme @code{foo}, a variable @code{bar}
3735
would actually be called @code{foo:bar}.
3736
3737
In most cases however, rep's lexical scoping can be used to avoid
3738
declaring any global variables or functions, the only usual exception
3739
is when declaring customization options with @code{defcustom}; these
3740
must be globally visible.
3741
3742
Since themes are generally passed around very casually, sawfish
3743
evaluates all theme code in a very restricted environment; the idea
3744
being that themes should only be able to affect the look of the window
3745
manager. Despite this, it is still possible for malicious themes to
3746
lock, and possibly crash, the window manager; in the first case sending
3747
a @code{SIGINT} signal may unblock it. Hopefully themes are unable to
3748
affect the rest of the user's environment, but there are no
3749
guarantees@dots{}
3750
3751
@defvar theme-load-path
3752
A list of directory names, provides the search path for locating theme
3753
directories. By default this includes the user's theme directory and
3754
the system theme directory.
3755
@end defvar
3756
3757
@defvar user-theme-directory
3758
The name of the user's theme directory, by default
3759
@file{~/.sawfish/themes}.
3760
@end defvar
3761
3762
@defvar system-theme-directory
3763
The name of the directory holding themes from the current Sawfish
3764
version, by default
3765
@lisp
3766
(expand-file-name "../themes" sawfish-lisp-lib-directory)
3767
@end lisp
3768
@end defvar
3769
3770
@defvar site-theme-directory
3771
The name of the directory holding system-wide themes, by default
3772
@lisp
3773
(expand-file-name "../../themes" sawfish-lisp-lib-directory)
3774
@end lisp
3775
@end defvar
3776
3777
@defvar theme-update-interval
3778
Number of seconds between checking if theme files have been modified.
3779
Default 60.
3780
@end defvar
3781
3782
@defvar themes-are-gaoled
3783
If @code{t}, non-nil themes are assumed to be malicious. They will be
3784
evaluated in a restricted environment.
3785
@end defvar
3786
3787
@node Removing Frame Parts, , Themes, Window Frames
3788
@section Removing Frame Parts
3789
@cindex Removing frame parts
3790
@cindex Frame parts, removing
3791
@cindex Window frames, removing frame parts
3792
3793
It is often useful to be able to disable certain parts of a window's
3794
frame. For example, a window may hint to the window manager that it
3795
doesn't want a maximize button. Sawfish allows all parts of a
3796
particular class to be disabled or enabled on a window by window basis.
3797
However, not all frame styles will support this (it depends on the
3798
frame part's @code{removable} property, @ref{Frame Part Definition}).
3799
3800
@defun add-frame-class window class
3801
Enable all frame parts that are a member of @var{class} in
3802
@var{window}.
3803
@end defun
3804
3805
@defun frame-class-removed-p window class
3806
Returns @code{t} if the frame part @var{class} has been removed from
3807
@var{window}, @code{nil} otherwise.
3808
@end defun
3809
3810
@defun remove-frame-class window class
3811
Disable all frame parts that are a member of @var{class} in
3812
@var{window} where possible.
3813
@end defun
3814
3815
@node Viewports, Workspaces, Window Frames, Top
3816
@chapter Viewports
3817
@cindex Viewports
3818
3819
It is sometimes useful to have a logical display that is larger than
3820
the computer screen. This is most often implemented by displaying
3821
only a portion of the logical display at any time. Sawfish does this
3822
using ``viewports''.
3823
3824
When viewports are enabled, the Sawfish logical display becomes
3825
potentially infinitely large in the two directions ``across'' and
3826
``down'' (to the maximum representable size of integers). Sawfish
3827
divides this logical display into a potentially infinite grid of
3828
cells. Each cell of the grid is the same size of the virtual display.
3829
3830
@defvar viewport-dimensions
3831
The current number of viewports across and down the virtual display.
3832
This is a cons cell @code{(@var{across} . @var{down})}. Defaults to
3833
@code{(1 . 1)}.
3834
@end defvar
3835
3836
@defun set-number-of-viewports width height
3837
Change @code{viewport-dimensions} to have the value
3838
@code{(@var{width} . @var{height})}.
3839
@end defun
3840
3841
Note that cell indices start at zero in each dimension. Indices are
3842
never negative.
3843
3844
@menu
3845
* Switching Viewports::
3846
* Windows and Viewports::
3847
@end menu
3848
3849
@node Switching Viewports, Windows and Viewports, Viewports, Viewports
3850
@section Switching Viewports
3851
3852
A user switches viewports by telling Sawfish to move the physical
3853
display from cell to cell. On a cell change, windows in previous
3854
cells are removed, and windows in the current cell appear. Windows
3855
that span two or more cells will appear in each cell, appropriately
3856
displaced.
3857
3858
@defun screen-viewport
3859
Returns the currently displayed viewport as a pair @code{(@var{x},
3860
@var{y})}.
3861
@end defun
3862
3863
@defun set-screen-viewport col row
3864
Change the physical display to view cell @code{(@var{col},
3865
@var{row})}.
3866
@end defun
3867
3868
@defun move-viewport right down
3869
Move the viewport to see the cell @var{right} slots to the right and
3870
@var{down} slots down. Either argument may be zero or negative.
3871
@end defun
3872
3873
@defvar viewport-boundary-mode
3874
How to act when switching via @code{set-screen-viewport} to a viewport
3875
that is outside of @code{viewport-dimensions}. When set to
3876
@code{wrap-around}, it loops in the vertical and horizontal axes
3877
enough times to keep the viewport within the defined dimensions. When
3878
set to @code{stop}, it refuses to switch to a viewport outside of
3879
@code{viewport-dimensions}. Defaults to @code{wrap-around}.
3880
@end defvar
3881
3882
@defun warp-viewport x y
3883
Change the position of the physical display, such that location
3884
@code{(@var{x}, @var{y})} is at the top-left of the display. The
3885
physical display may be showing more than one cell at this point.
3886
All windows are redisplayed as appropriate.
3887
@end defun
3888
3889
@defun set-viewport x y
3890
Change the position of the physical display, such that location
3891
@code{(@var{x}, @var{y})} is at the top-left of the display. The
3892
physical display may be showing more than one cell at this point.
3893
3894
Unlike @code{warp-viewport}, the change takes place by dividing the
3895
motion into @code{scroll-viewport-steps} steps, and redisplaying after
3896
each step in the motion.
3897
@end defun
3898
3899
@defvr Customizable scroll-viewport-steps
3900
Number of steps in which to divide a viewport change for
3901
@code{set-viewport}. Each step requires a redisplay. Defaults to 1,
3902
which causes an instantaneous change to the new viewport. The
3903
customization limit is 50.
3904
@end defvr
3905
3906
@node Windows and Viewports, , Switching Viewports, Viewports
3907
@section Windows and Viewports
3908
3909
@defun window-viewport window
3910
Returns a cons cell @code{(@var{col} . @var{row})} of the viewport
3911
holding the top-left corner of @var{window}.
3912
@end defun
3913
3914
@defun window-outside-viewport-p window
3915
Returns true if @var{window} is completely outside the current
3916
viewport in any direction.
3917
@end defun
3918
3919
@defun window-absolute-position window
3920
Returns a cons cell @code{(@var{x} . @var{y})} of the position of
3921
@var{window} in its containing viewport. The containing viewport may
3922
or may not be the current viewport.
3923
@end defun
3924
3925
@defun set-window-viewport window col row
3926
Move @var{window} to the cell at @code{(@var{col}, @var{row})}. The
3927
relative position of the window within the cells is preserved.
3928
@end defun
3929
3930
@defun move-window-viewport window col-delta row-delta
3931
Move @var{window} to the cell @var{col-delta} positions across and
3932
@var{row-delta} positions down from its current cell. The relative
3933
position of the window with its cells its preserved.
3934
@end defun
3935
3936
@defun move-window-to-current-viewport window
3937
Move @var{window} from its existing viewport to the current viewport.
3938
The window's relative position in the existing viewport is preserved
3939
after the move.
3940
@end defun
3941
3942
@defun move-viewport-to-window window
3943
Move the viewport to a cell that shows window @var{window}. For a
3944
window that spans multiple cells, this function will pick the cell
3945
showing the window's top-left corner.
3946
@end defun
3947
3948
@defvar uniconify-to-current-viewport
3949
When true, windows uniconify to the current viewport, rather than to
3950
the viewport they were iconified on. Defaults to true.
3951
@end defvar
3952
3953
@node Workspaces, Multi-Head Environments, Viewports, Top
3954
@chapter Workspaces
3955
@cindex Workspaces
3956
@cindex Desktop workspaces
3957
3958
Workspaces provide another way for users to organize their windows in
3959
Sawfish. Instead of stretching the screen real estate to the right
3960
and down, workplaces stack screens on top of each other. The user
3961
drills down into the stack, or pops up through the stack, seeing the
3962
appropriate windows in each workspace.
3963
3964
@menu
3965
* Workspace Intervals:: ``Interesting'' workspaces
3966
* Workspace Manipulation:: Creating, rearranging, deleting
3967
* Workspaces and Windows:: Adding, removing
3968
* Edge Flipping:: Moving workspaces using the mouse
3969
@end menu
3970
3971
@node Workspace Intervals, Workspace Manipulation, Workspaces, Workspaces
3972
@section Workspace Intervals
3973
3974
While the stack of workspaces conceptually goes from negative infinity
3975
to positive infinity, we normally present only the first non-empty
3976
workspace through the last non-empty workspace to the user. The
3977
non-empty interval is occasionally re-normalized to start with zero.
3978
3979
We typically refer to workplaces with lower IDs being to the ``left''
3980
of workplaces with higher IDs, as if on a number line.
3981
3982
@defvar current-workspace
3983
The ID of the currently active workspace. This is an integer. The
3984
``default'' workspace has ID 0.
3985
@end defvar
3986
3987
@defun workspace-limits
3988
Returns a pair @code{(@var{first-index} . @var{last-index})} defining
3989
the subset of the workspace continuum that is ``interesting'' to the
3990
user (typically, all those that have ever been explicitly created).
3991
@end defun
3992
3993
@defun workspace-id-to-logical space-id &optional limits
3994
Takes an absolute workspace ID and returns its position in the
3995
interval of ``interesting'' workspaces. If @var{limits} is provided,
3996
it must be a pair @code{(@var{first-index} . @var{last-index})} like
3997
that returned by @code{workspace-limits}. If it is not provided, the
3998
function uses the result of @code{workspace-limits} directly.
3999
@end defun
4000
4001
@defun workspace-id-from-logical offset &optional limits
4002
Takes an offset position into an interval of ``interesting''
4003
workspaces, and returns the workplace ID at that position. If
4004
@var{limits} is provided, it must be a pair @code{(@var{first-index}
4005
. @var{last-index})} like that returned by @code{workspace-limits}.
4006
If it is not provided, the function uses the result of
4007
@code{workspace-limits} directly.
4008
@end defun
4009
4010
@defun popup-workspace-list
4011
Display the menu containing the list of all workspaces.
4012
@end defun
4013
4014
@defun workspace-menu
4015
Returns a list of workspaces, suitable for display in a menu.
4016
@end defun
4017
4018
@defvr Customizable workspace-names
4019
A list of workspace names. When displaying the workspace menu, the
4020
first @var{N} workspaces use the corresponding list elements as their
4021
display names (where @var{N} is the length of the list). Normally
4022
they get the display name @samp{space N} for some value of N.
4023
@end defvr
4024
4025
@node Workspace Manipulation, Workspaces and Windows, Workspace Intervals, Workspaces
4026
@section Workspace Manipulation
4027
4028
Sawfish has various functions to create, rearrage and delete
4029
workspaces. Windows in a deleted workspace are not lost; they are
4030
moved to another workspace.
4031
4032
@defun select-workspace space &key dont-focus force
4033
Activate workspace @var{space}, making it current.
4034
4035
By default in @code{enter} and @code{click} focus modes, the most
4036
recently used window will receive focus. The caller can disable this
4037
behavior by passing a true @var{dont-focus} keyword argument.
4038
4039
If the @var{force} keyword argument is true, we will go through the
4040
activation process even if @var{space} already is current.
4041
@end defun
4042
4043
@defun select-workspace-from-first count
4044
Select the workspace in position @var{count} from the list of
4045
``interesting'' workspaces.
4046
@end defun
4047
4048
@defun select-workspace-and-viewport space col row
4049
Select workspace @var{space} and then switch to viewport
4050
@code{(@var{col}, @var{row})} in that workspace.
4051
@end defun
4052
4053
@defun insert-workspace &optional before
4054
Insert a new workspace, returning its index. The new index appears
4055
before the workspace indicated by @var{before}, or the current
4056
workspace if @var{before} is @code{nil}.
4057
@end defun
4058
4059
@defun insert-workspace-after
4060
Create a new workspace following the current workspace.
4061
@end defun
4062
4063
@defun insert-workspace-before
4064
Create a new workspace preceeding the current workspace.
4065
@end defun
4066
4067
@defun move-workspace space count
4068
Move the workspace @var{space} @var{count} positions forward, or
4069
@var{count} positions backwards if @var{count} is negative.
4070
@end defun
4071
4072
@defun move-workspace-forwards &optional count
4073
Move the current workspace one place to the right (or @var{count}
4074
places to the right if @var{count} is defined).
4075
@end defun
4076
4077
@defun move-workspace-backwards &optional count
4078
Move the current workspace one place to the left (or @var{count}
4079
places to the left if @var{count} is defined).
4080
@end defun
4081
4082
@defun next-workspace count
4083
@defunx previous-workspace count
4084
Switch from the current workspace (index @var{i}) to the workspace
4085
@var{i}+@var{count}. The @code{previous-workspace} function is
4086
identical to @code{(next-workspace (- @var{count}))}.
4087
4088
These functions do not have default values for their @var{count}
4089
arguments.
4090
@end defun
4091
4092
@defun remove-workspace &optional index
4093
Remove workspace @var{index} (or the current workspace if @var{index}
4094
is @code{nil}). All windows in that workspace are moved to the next
4095
workspace @var{index}+1. This will change the set of ``interesting''
4096
workspaces.
4097
@end defun
4098
4099
@defun merge-next-workspace
4100
Delete the current workspace. Its member windows are relocated to the
4101
next workspace.
4102
@end defun
4103
4104
@defun merge-previous-workspace
4105
Delete the current workspace. Its member windows are relocated to the
4106
previous workspace.
4107
@end defun
4108
4109
@defun set-number-of-workspaces wanted
4110
Add or remove workspaces until the number of ``interesting''
4111
workspaces is equal to @var{wanted}.
4112
4113
When adding workplaces, the new workplaces get indices higher than any
4114
existing indices. When removing workplaces, the lowest workplaces are
4115
always chosen for removal (their windows are merged into the new
4116
lowest-index workspace).
4117
@end defun
4118
4119
@defvar lock-first-workspace
4120
When true, preserve the outermost empty workspaces in the pager.
4121
Don't quietly remove them when they become empty. Defaults to true.
4122
@end defvar
4123
4124
@node Workspaces and Windows, Edge Flipping, Workspace Manipulation, Workspaces
4125
@section Workspaces and Windows
4126
4127
Workspaces do not need to have windows assigned to them, but most
4128
operations with workspaces involve adding and removing windows.
4129
4130
@defun all-workspaces
4131
Returns a list of indices for all workspaces that contain windows.
4132
Sticky windows appear in the current workspace.
4133
@end defun
4134
4135
@defun workspace-empty-p space
4136
Returns true if workspace @var{space} contains zero (non-sticky)
4137
windows.
4138
@end defun
4139
4140
@defun delete-empty-workspaces
4141
Delete any workspaces that don't contain any windows.
4142
@end defun
4143
4144
@defvar workspace-boundary-mode
4145
How to act when passing the first or last workspace, one of @code{stop},
4146
@code{wrap-around} or @code{keep-going}. Defaults to @code{stop}.
4147
@end defvar
4148
4149
Each window can be a member of any (positive) number of workspaces;
4150
their @code{workspaces} property contains a list of workspace ids.
4151
Sticky windows appear on all workspaces, and have their @code{sticky}
4152
property set (with a null @code{workspaces} property). If Sawfish
4153
begins managing a window with its @code{workspaces} property set, then
4154
the window is added to those workspaces automatically.
4155
4156
@defun window-in-workspace-p window space
4157
Returns true if @var{window} is a member of workspace @var{space},
4158
false otherwise.
4159
@end defun
4160
4161
@defun window-appears-in-workspace-p window space
4162
Returns true if @var{window} appears in workspace @var{space}, false
4163
otherwise. To appear, @var{window} has to be visible, but it can
4164
either be assigned to the workspace or be sticky.
4165
@end defun
4166
4167
@defun windows-share-workspace-p window1 window2
4168
Returns true if @var{window1} and @var{window2} are members of at
4169
least one common workspace.
4170
@end defun
4171
4172
@defun nearest-workspace-with-window window space
4173
Returns the nearest workspace to @var{space} that contains
4174
@var{window}.
4175
@end defun
4176
4177
@defun workspace-windows &optional space include-iconified
4178
Returns a list of all windows that are members of the current
4179
workspace (or @var{space} if it is not @code{nil}). The list normally
4180
does not contain iconified windows, but they can by included by
4181
specifying a true @var{include-iconified} argument.
4182
@end defun
4183
4184
@defun popup-window-menu
4185
Display the menu of all managed windows.
4186
@end defun
4187
4188
@defun move-window-to-workspace window old new &optional was-focused
4189
Move @var{window} from workspace @var{old} to workspace @var{new}.
4190
4191
We need the old workspace as an explicit argument because a window can
4192
be in more than one workspace. The function does the right thing if
4193
the window already appears in workspace @var{new}.
4194
4195
If @var{was-focused} is true and the window is visible, it gets the
4196
input focus in the new workspace.
4197
@end defun
4198
4199
@defun copy-window-to-workspace window old new &optional was-focused
4200
Arrange it so @var{window} appears in both @var{old} and @var{new}
4201
workspaces.
4202
4203
If @var{was-focused} is true and the window is visible, it gets the
4204
input focus in the new workspace.
4205
@end defun
4206
4207
@defun send-to-next-workspace window count &optional copy select
4208
Move the window @var{count} workspaces to the right. @var{Count} does
4209
not default to one.
4210
4211
The window is normally removed from the current workspace (if it is in
4212
that workspace), or from the first workspace it belongs to. Supplying
4213
a true @var{copy} argument causes Sawfish to copy the window instead.
4214
4215
If @var{select} is true, then we switch to the destination workspace.
4216
If the moved window had input focus before the move, it will have
4217
input focus after the move as well.
4218
@end defun
4219
4220
@defun send-to-previous-workspace window count &optional copy select
4221
Move the window @var{count} workspaces to the left. @var{Count} does
4222
not default to one.
4223
4224
The window is normally removed from the current workspace (if it is in
4225
that workspace), or from the first workspace it belongs to. Supplying
4226
a true @var{copy} argument causes Sawfish to copy the window instead.
4227
4228
If @var{select} is true, then we switch to the destination workspace.
4229
If the moved window had input focus before the move, it will have
4230
input focus after the move as well.
4231
4232
This is identical to @code{(send-to-next-workspace window count copy select)}.
4233
@end defun
4234
4235
@defun copy-to-next-workspace window count select
4236
Copy the window @var{count} workspaces to the left. @var{Count} does
4237
not default to one.
4238
4239
If @var{select} is true, then we switch to the destination workspace.
4240
If the moved window had input focus before the move, it will have
4241
input focus after the move as well.
4242
4243
This is identical to @code{(send-to-next-workspace window count t select)}.
4244
@end defun
4245
4246
@defun copy-to-previous-workspace window count &optional select
4247
Copy the window @var{count} workspaces to the right. @var{Count} does
4248
not default to one.
4249
4250
If @var{select} is true, then we switch to the destination workspace.
4251
If the moved window had input focus before the move, it will have
4252
input focus after the move as well.
4253
4254
This is identical to @code{(send-to-previous-workspace window count t select)}.
4255
@end defun
4256
4257
@defun send-window-to-workspace-from-first window count &optional copy select
4258
Move @var{window} to the workspace at position @var{count} in the
4259
``interesting'' list.
4260
4261
The window is normally removed from the current workspace (if it is in
4262
that workspace), or from the first workspace it belongs to. Supplying
4263
a true @var{copy} argument causes Sawfish to copy the window instead.
4264
4265
If @var{select} is true, then we switch to the destination workspace.
4266
If the moved window had input focus before the move, it will have
4267
input focus after the move as well.
4268
@end defun
4269
4270
@defvar workspace-send-boundary-mode
4271
How to act when passing the first or last workspace, while moving a
4272
window. One of @code{stop}, @code{keep-going}, @code{wrap-around}.
4273
Defaults to @code{stop}.
4274
@end defvar
4275
4276
@defun delete-window-instance window
4277
Remove the copy of @var{window} on the current workspace. If this is
4278
the last instance remaining, then delete the actual window. Note that
4279
this behavior differs from the merging that happens when you delete a
4280
workspace.
4281
@end defun
4282
4283
@defun map-window-workspaces fun window
4284
Map function @var{fun} over all workspaces containing @var{window}.
4285
@end defun
4286
4287
When a window appears on more than one workspace, some of its
4288
properties may be swapped in and out on demand when the current
4289
workspace is changed.
4290
4291
@defvar workspace-local-properties
4292
Window properties whose values may differ on differnet workspaces.
4293
Defaults to the empty list.
4294
@end defvar
4295
4296
@defvar add-swapped-properties props
4297
Add all properties in the list @var{props} to
4298
@var{workspace-local-properties}.
4299
@end defvar
4300
4301
It is possible to hide all ``normal'' windows across workspaces.
4302
``Normal'' in this case excludes desktop windows and dock windows, but
4303
includes sticky and ignored windows. The hidden windows are no longer
4304
considered ``viewable'' according to @code{window-viewable-p}.
4305
4306
@defun show-desktop
4307
Hide all windows except the desktop and dock windows.
4308
@end defun
4309
4310
@defun hide-desktop
4311
Undo the effects of the @code{show-desktop} command.
4312
@end defun
4313
4314
@defun showing-desktop-p
4315
Return true if non-desktop and non-dock windows are hidden, false
4316
otherwise.
4317
@end defun
4318
4319
@node Edge Flipping, , Workspaces and Windows, Workspaces
4320
@section Edge Flipping
4321
4322
Sawfish provides a way to flip between workspaces (or viewports)
4323
automatically by moving the mouse to the edge of the screen. The
4324
technique is called ``edge flipping''.
4325
4326
These definitions are stored in the @code{sawfish.wm.ext.edge-flip}
4327
structure. They can only be enabled through the customization
4328
interface.
4329
4330
@defvr Customizable edge-flip-enabled nil
4331
When true, select the next desktop when the pointer hits screen edge.
4332
Defaults to false.
4333
@end defvr
4334
4335
@defvr Customizable edge-flip-type
4336
Indicates what is selected when hitting the screen edge. Must be one
4337
of @code{viewport} or @code{workspace}. Defaults to @code{workspace}.
4338
@end defvr
4339
4340
@defvr Customizable edge-flip-only-when-moving
4341
When true, Sawfish only flips when the user is interactively moving a
4342
window. Defaults to false.
4343
@end defvr
4344
4345
This variable is not customizable, but it can be edited.
4346
4347
@defvar edge-flip-delay
4348
Milliseconds to delay before edge flipping. Defaults to 250.
4349
@end defvar
4350
4351
Flippers are implemented as invisible windows on the edges of the
4352
display (the windows overlap at the corners). When the pointer moves
4353
over any of these windows, Sawfish generates @code{enter-flipper-hook}
4354
and @code{leave-flipper-hook} events.
4355
4356
Programmers can add their own callbacks to perform other actions with
4357
the flippers. This depends on manually enabling the flippers, using
4358
the following functions in the @code{sawfish.wm.util.flippers}
4359
structure. Note that you may have to manually remove the
4360
@code{edge-flip-enter} and @code{edge-flip-leave} callbacks from the
4361
hooks before adding your own callbacks.
4362
4363
@defun enable-flippers
4364
Add edge windows used to implement flipping.
4365
@end defun
4366
4367
@defun disable-flippers
4368
Remove the edge windows used to implement flipping.
4369
@end defun
4370
4371
@node Multi-Head Environments, Window Placement, Workspaces, Top
4372
@chapter Multi-Head Environments
4373
@cindex Multi-head environments
4374
@cindex Environments, multi-head
4375
@cindex Monitors, multiple
4376
4377
Sawfish has special functions to support environments with multiple
4378
monitors displaying a single logical screen (as provided by Xinerama).
4379
4380
@defun find-head x y
4381
Return a ID for the display head that point (@var{x}, @var{y}) is in.
4382
The return value is an integer; the default head has ID zero. Returns
4383
@code{nil} if it cannot determine the head from @var{x} and @var{y}.
4384
@end defun
4385
4386
@defun head-count
4387
Return the number of display heads on the machine.
4388
@end defun
4389
4390
@defun head-dimensions id
4391
Return the cons cell @code{(@var{width} . @var{height})} of the
4392
dimensions of the display head indicated by @var{id}. @var{Id} must
4393
be a non-negative integer. Without Xinerama support, @var{id} must be
4394
zero and the function returns the screen size.
4395
@end defun
4396
4397
@defun head-offset id
4398
Return the cons cell @code{(@var{x} . @var{y})} of the
4399
dimensions of the display head indicated by @var{id}. @var{Id} must
4400
be a non-negative integer. Without Xinerama support, @var{id} must be
4401
zero and the function returns @code{(0 . 0)}.
4402
@end defun
4403
4404
@defun pointer-head
4405
Return the ID of the head containing the mouse pointer.
4406
@end defun
4407
4408
@defun current-head &optional window
4409
Return the ID of the head containing the window with input focus. If
4410
@var{window} is supplied and a window, return the head containing that
4411
window. If @var{window} is supplied and @var{nil}, return
4412
@code{(pointer-head)}.
4413
@end defun
4414
4415
@defun current-head-dimensions &optional window
4416
Return a cons-cell defining the size in pixels of the current head
4417
(that containing the window @var{window}, or the pointer if
4418
@var{window} is false). Returns the screen dimensions if no such head
4419
can be identified.
4420
@end defun
4421
4422
@defun current-head-offset &optional window
4423
Return a cons-cell defining the origin of the current head (that
4424
containing the window @var{window}, or the pointer if @var{window} is
4425
false). Returns @code{'(0 . 0)} if no such head can be identified.
4426
@end defun
4427
4428
4429
@node Window Placement, Popup Menus, Multi-Head Environments, Top
4430
@chapter Window Placement
4431
@cindex Placement of windows
4432
4433
Sawfish supports multiple ways of placing new windows on the display.
4434
There is a ``current'' placement mode for normal windows, and another
4435
mode for transient windows.
4436
4437
@defvar place-window-mode
4438
A symbol indicating the method of placing normal windows. This
4439
defaults to @code{top-left}.
4440
@end defvar
4441
4442
@defvar place-transient-mode
4443
A symbol indicating the method of placing transient windows. This
4444
defaults to @code{centered-on-parent}.
4445
@end defvar
4446
4447
@defun placement-mode name
4448
Return the placement mode object corresponding to @var{name}.
4449
@end defun
4450
4451
@defvar placement-modes
4452
List of names of all placement modes. Sawfish 1.3 ships with the
4453
following placement modes:
4454
4455
@itemize @bullet
4456
@item @code{randomly}
4457
The new window is placed at a random location on the screen.
4458
4459
@item @code{interactively}
4460
Prompt the user to select a position with the mouse. The new window
4461
is created such that its top-left corner is at that position.
4462
4463
@item @code{centered}
4464
The new window is created at the center of the screen.
4465
4466
@item @code{centered-on-parent}
4467
The new window has a parent, it is centered on that parent. If the
4468
new window instead has a focused window in the same group, it is
4469
centered on that focused window. Otherwise the new window is simply
4470
@code{centered}.
4471
4472
@item @code{under-pointer}
4473
Create the new window so that it's under the pointer, without going
4474
off the edge of the screen.
4475
4476
@item @code{first-fit}
4477
@item @code{best-fit}
4478
Look for positions where the new window would have a small overlap
4479
area with already visible windows. The @code{first-fit} algorithm
4480
uses the first ``good'' position found. The @code{best-fit} algorithm
4481
looks at all possible positions and picks the best of them.
4482
4483
@item @code{best-fit-group}
4484
As @code{best-fit}, but the new window is only checked for overlap
4485
with other windows in its group.
4486
4487
@item @code{first-fit-or-interactive}
4488
As @code{first-fit}, but if Sawfish cannot find a ``good'' position,
4489
it falls back to @code{interactively} mode.
4490
4491
@item @code{stagger}
4492
Attempts to place each new window below and to the right of the
4493
previous window. See @code{stagger-placement-step}.
4494
4495
@item @code{top-left}
4496
Interpret the top-left to bottom-right screen diagonal as a series of
4497
slots, each of which may have a window. Find the first empty slot and
4498
place the window there. @emph{Sawfish will shrink the window to
4499
prevent it from going past the right or bottom edge, or even beneath a
4500
special window like a panel.} If Sawfish is not allowed to shrink the
4501
window enough to prevent this, it instead places the window randomly.
4502
4503
@item @code{off-center}
4504
Tries to put windows in the center of the screen, but in such a way
4505
that the newly placed window doesn't fully obscure an existing
4506
window.
4507
4508
This is to handle the case where two windows of the same size are
4509
created one after the other, so that the user is sure to see (at least
4510
part of) both windows.
4511
4512
@item @code{none}
4513
Make no changes to the window's position. The window remains wherever
4514
the X server placed it initially.
4515
@end itemize
4516
4517
@end defvar
4518
4519
In all of these placement modes, the mode is responsible for taking
4520
the window object as an argument, and manipulating its position with,
4521
e.g., @code{move-window-to}.
4522
4523
The window to be placed avoids overlapping with already existing
4524
``avoided'' windows (@pxref{Avoided Windows}), unless
4525
the position is explicitly specified by coordinates, or placement mode
4526
@code{interactively} is used.
4527
4528
@defvar stagger-placement-step
4529
In @code{stagger} placement mode, the distance down and to the right
4530
from the previously placed window to the new one. This is measured
4531
in pixels.
4532
@end defvar
4533
4534
There are two circumstances in which Sawfish will place a window:
4535
either the window has just been created, or Sawfish has begun managing
4536
the window's display. In the latter case, the window will have the
4537
@code{placed} property.
4538
4539
@defvar ignore-program-positions
4540
When @code{t}, program position size hints are not considered when
4541
placing windows.
4542
@end defvar
4543
4544
You can define your own placement modes.
4545
4546
@defun define-placement-mode name fun &keywords for-normal for-dialogs
4547
Define a new window placement mode called @var{name} (a symbol). The
4548
function @var{fun} will be called with a single argument when a window
4549
should be placed using this mode. The single argument is the window
4550
to be placed.
4551
4552
If the @var{for-normal} keyword is @code{t}, then this placement mode
4553
is marked as valid for @code{place-window-mode}. The same applies to
4554
@var{for-dialogs} and @code{place-transient-mode}.
4555
@end defun
4556
4557
@defun autoload-placement-mode name module-name &keywords for-normal for-dialogs
4558
Define placement mode @var{name} (a symbol) to be loaded from
4559
structure @var{structure-name} (a symbol) when first referenced. The
4560
@var{keyword-args} are passed along to the call to
4561
@code{define-placement-mode} that creates the placement mode.
4562
@end defun
4563
4564
@node Popup Menus, Events, Window Placement, Top
4565
@chapter Popup Menus
4566
@cindex Popup menus
4567
@cindex Menus, popup
4568
4569
Popup menus are one of the two main methods through which the user may
4570
invoke Lisp code (the other is via keymaps, @pxref{Keymaps}). The
4571
@code{popup-menu} function is invoked with a list of menu item
4572
definitions and the associated Lisp function to call for each item.
4573
This starts a subprocess to display the menu, then at a later date the
4574
chosen menu item is received and evaluated.
4575
4576
Each menu item is specified by a list, the first element of which is a
4577
string providing the label for the menu item, the second element is a
4578
function to be called if that item is selected by the user. If this
4579
function has an interactive specification it will be invoked using the
4580
@code{call-command} function, otherwise @code{funcall} will be used.
4581
Alternatively the second element may be a lisp form to evaluate. So,
4582
for example, a single-level menu could be defined by:
4583
4584
@lisp
4585
(("Item 1" function-1)
4586
("Item 2" function-2)
4587
()
4588
("Item 3" function-3))
4589
@end lisp
4590
4591
@noindent
4592
The null item will create a separator line in the displayed menu.
4593
4594
If the cdr of first element of any item is a symbol, then the rest of
4595
the item is defined by the value of the named variable. If this value
4596
is functional then the definition is found by calling the function.
4597
4598
Consider the following definition:
4599
4600
@lisp
4601
(("Workspaces" . workspace-menu)
4602
("Windows" . window-menu)
4603
("Programs" . apps-menu)
4604
("Customize" . custom-menu)
4605
("About..." (customize 'about))
4606
()
4607
("Restart" restart)
4608
("Quit" quit))
4609
@end lisp
4610
4611
@noindent
4612
This is the definition of Sawfish's root menu. We can see that four
4613
submenus are created dynamically by dereferencing variables (in fact,
4614
three of this variables contain functions) (@code{workspace-menu},
4615
@code{window-menu}, @code{apps-menu} and @code{custom-menu}). Note that
4616
these must be special variables, i.e. initially declared using the
4617
@code{defvar} special form.
4618
4619
The @code{apps-menu} variable can thus be used to redefine the
4620
applications menu. The default definition is as follows:
4621
4622
@lisp
4623
(("xterm" (system "xterm &"))
4624
("Emacs" (system "emacs &"))
4625
("Netscape" (system "netscape &"))
4626
("The GIMP" (system "gimp &"))
4627
("XFIG" (system "xfig &"))
4628
("GV" (system "gv &"))
4629
("xcalc" (system "xcalc &")))
4630
@end lisp
4631
4632
@noindent
4633
The @code{system} function simply executes its single argument using
4634
@file{/bin/sh}.
4635
4636
When displaying a menu item, it is possible to also display the
4637
corresponding keyboard shortcut in the menu.
4638
4639
@defvar menus-include-shortcuts
4640
When true, menu items also display key-binding information. Defaults
4641
to false.
4642
@end defvar
4643
4644
The actual creation of a menu is performed by an auxiliary process,
4645
distributed with Sawfish. Since the overhead of starting the menu
4646
subprocess may be noticeable on some systems, it is possible to leave
4647
it running between menu requests.
4648
4649
@defvar menu-program
4650
Location of the program implementing Sawfish's menu interface.
4651
@end defvar
4652
4653
@defvar menu-program-stays-running
4654
This variable defines if, and for how long, the menu subprocess is
4655
allowed to remain executing for after the last menu has completed. If
4656
@code{nil}, the program is terminated immediately, if @code{t} it is
4657
left running indefinitely, if an integer then the program will run for
4658
that many seconds (unless another menu is displayed).
4659
@end defvar
4660
4661
The actual interface to invoke the external menu program is hidden in
4662
the @code{popup-menu} function.
4663
4664
@defun popup-menu spec
4665
Displays a menu defined by the list of item definitions @var{spec}.
4666
@end defun
4667
4668
In addition, Sawfish provides various canned menus, and functions to
4669
display those menus.
4670
4671
@defvar root-menu
4672
Contains the root menu definition.
4673
@end defvar
4674
4675
@defun popup-root-menu
4676
Display the main menu. By default, this is bound to Button2-click on
4677
the root window.
4678
@end defun
4679
4680
@defvar apps-menu
4681
The variable containing the definition of the applications submenu of
4682
the root menu. The default root menu includes this as a child menu.
4683
@end defvar
4684
4685
@defun popup-apps-menu
4686
Display the applications menu.
4687
@end defun
4688
4689
@defun window-ops-menu
4690
The variable containing the definition of all window operations.
4691
@end defun
4692
4693
@defun popup-window-menu
4694
Display the menu listing all window operations. This has several
4695
bindings by default. In particular, clicking on a window's menu
4696
button displays this menu.
4697
@end defun
4698
4699
@defvar window-ops-toggle-menu
4700
A list of flags describing windows, e.g., ``sticky'' or ``shaded''.
4701
This list is displayed in a menu, and by selecting items in this menu
4702
a user can turn the flags on and off for a given window.
4703
@end defvar
4704
4705
@defun add-window-menu-toggle label command &optional predicate
4706
Add additional flags to @code{window-ops-toggle-menu}. The
4707
@var{command} is a function (or a symbol pointing to a function) that
4708
gets run when the menu item is selected. If @var{predicate} is
4709
non-nil, it must be a function taking a window as argument. If
4710
@var{predicate} return true, the menu item will have a check mark next
4711
to it.
4712
@end defun
4713
4714
@node Events, Commands, Popup Menus, Top
4715
@chapter Events
4716
@cindex Events
4717
4718
Events refer to input events from X that the window manager receives,
4719
either for the root window, the window frames it creates, or grabbed
4720
from the client windows themselves. Each event induced by the mouse or
4721
keyboard has a Lisp representation.
4722
4723
@defun eventp object
4724
This function returns @code{t} if its argument is an input event.
4725
@end defun
4726
4727
@menu
4728
* Event Representation:: Objects versus string names
4729
* Event Modifiers:: Meta, Alt, Buttons
4730
* Event Actions:: Keys and Clicks
4731
* Event Matching::
4732
* Synthetic Events:: Creating events that seem real
4733
@end menu
4734
4735
@node Event Representation, Event Modifiers, Events, Events
4736
@section Event Representation
4737
4738
Each input event is represented by a cons cell containing two
4739
integers, and these integers encode the event. The encoding is opaque;
4740
the only way to access an event meaningfully is via the functions
4741
provided.
4742
4743
Each event has a string representation, called its ``name''. Names
4744
consist of zero or more modifiers, followed by a key or mouse action
4745
indicator. Modifiers are separated from succeeding elements by
4746
hyphens @samp{-}. For example, hitting @key{x} while holding down the
4747
@key{Control} and @key{Meta} keys would generate an event named
4748
@key{Control-Meta-x}. This notation is designed to closely match
4749
Emacs Lisp's notation.
4750
4751
Functions are available to convert between the name of an event and the
4752
actual event itself, and vice versa.
4753
4754
@defun lookup-event event-name
4755
Create and return a new input event whose name is @var{event-name}.
4756
4757
@lisp
4758
(lookup-event "C-x")
4759
@result{} (120 . 65540)
4760
4761
(lookup-event "C-M-Button1-Click1")
4762
@result{} (1 . 131340)
4763
@end lisp
4764
@end defun
4765
4766
@defun event-name event
4767
This function returns a string naming the input event @var{event}.
4768
4769
@lisp
4770
(event-name (lookup-event "C-x"))
4771
@result{} "C-x"
4772
@end lisp
4773
@end defun
4774
4775
@node Event Modifiers, Event Actions, Event Representation, Events
4776
@section Event Modifiers
4777
@cindex Event Modifiers
4778
@cindex Modifiers, for events
4779
4780
Sawfish event modifiers are copied directly from the standard X
4781
modifiers:
4782
4783
The standard X modifier names are provided, as well as four special
4784
modifiers @key{Meta}, @key{Alt} @key{Hyper} and @key{Super} that are
4785
mapped to the keysyms of the same name.
4786
4787
The following table lists the possible modifier prefixes:
4788
4789
@table @key
4790
@item Control
4791
@itemx C
4792
The control modifier
4793
4794
@item Meta
4795
@itemx M
4796
The meta modifier
4797
4798
@item Alt
4799
@itemx A
4800
The alt modifier
4801
4802
@item Shift
4803
@itemx S
4804
The shift modifier
4805
4806
@item Hyper
4807
@itemx H
4808
The hyper modifier
4809
4810
@item Super
4811
@itemx s
4812
The super modifier; note that this is a lowercase @kbd{s}
4813
4814
@item Mod@var{k}
4815
The standard X modifiers, for @var{k} between 1 and 5
4816
4817
@item Any
4818
A special modifier that matches any set of modifiers in events.
4819
@xref{Event Matching}.
4820
4821
@item Release
4822
A special modifier that matches key release events, not the default
4823
key press events. Mouse events never have @key{Release} modifiers;
4824
they have separate actions instead. @xref{Event Actions}.
4825
4826
@item Button@var{k}
4827
The @var{k}'th mouse button is currently pressed.
4828
4829
@item W
4830
A placeholder ``window manager'' modifier that can be bound to a real
4831
modifier on the fly. See @code{wm-modifier} below.
4832
@end table
4833
4834
The default Sawfish bindings use the @key{Meta} modifier. For
4835
convenience, if no X keysym generates @key{Meta}, Sawfish will treat
4836
the first defined modifier of @key{Alt}, @key{Hyper} and @key{Super}
4837
(in that order) as @key{Meta}. The mapping from keysyms to
4838
modifiers is exposed in the following variables:
4839
4840
@defvar meta-keysyms
4841
A list defining the names of the X keysyms generating the virtual
4842
@samp{Meta} or @samp{M} modifier.
4843
@end defvar
4844
4845
@defvar alt-keysyms
4846
A list defining the names of the X keysyms generating the virtual
4847
@samp{Alt} or @samp{A} modifier.
4848
@end defvar
4849
4850
@defvar hyper-keysyms
4851
A list defining the names of the X keysyms generating the virtual
4852
@samp{Hyper} or @samp{H} modifier.
4853
@end defvar
4854
4855
@defvar super-keysyms
4856
A list defining the names of the X keysyms generating the virtual
4857
@samp{Super} modifier.
4858
@end defvar
4859
4860
There are two functions to manipulate the placeholder ``window
4861
manager'' (@key{W}) modifier. Unfortunately, these are low-level
4862
functions that operate on integer encodings.
4863
4864
@defun wm-modifier
4865
Return the current value (an integer) of the placeholder ``window
4866
manager'' (@key{W}) modifier.
4867
@end defun
4868
4869
@defvr {Customizable} wm-modifier-value
4870
An integer encoding zero or more modifier keys that form the
4871
placeholder ``window manager'' (@key{W}) modifier. Setting this value
4872
through the customization UI automatically calls
4873
@code{set-wm-modifier}.
4874
@end defvr
4875
4876
@defun set-wm-modifier modifiers
4877
Set the value of the placeholder ``window manager'' (@key{W}) modifier
4878
to @var{modifiers} (an integer).
4879
@end defun
4880
4881
@node Event Actions, Event Matching, Event Modifiers, Events
4882
@section Event Actions
4883
4884
Sawfish recognizes keyboard actions and mouse actions.
4885
4886
@table @asis
4887
@item Key Press
4888
@itemx Key Release
4889
Keys pressed on the keyboard generate one or more key press events,
4890
followed by a key release event. Bindings normally recognize key
4891
press events only. To recognize key releases, add a @key{Release}
4892
modifier to the bound event.
4893
@end table
4894
4895
Generally keys have the same names as their X keysyms. The following
4896
unusual names are worth listing: @samp{SPC}, @samp{TAB}, @samp{RET},
4897
@samp{ESC}, @samp{BS}, @samp{DEL}, @samp{Up}, @samp{Down},
4898
@samp{Left}, @samp{Right}.
4899
4900
For example, pressing the @key{Delete} key while @key{Control} is held
4901
down generates a @kbd{Control-DEL} event, while releasing the @key{a}
4902
key while @key{Hyper} is held down generates a @kbd{H-Release-a}
4903
event.
4904
4905
@table @asis
4906
@item Button Clicks
4907
Button presses generate @key{Click} actions. If Sawfish receives
4908
several clicks in close succession (less than @code{multi-click-delay}
4909
milliseconds between clicks), the second and third events are
4910
@key{Click2} and @key{Click3}, respectively. Any further clicks are
4911
simple @key{Click} events. For consistency, @key{Click1} is a synonym
4912
for @key{Click}.
4913
4914
@item Button Releases
4915
Once the button has been released from a @key{ClickN} action, Sawfish
4916
receives a corresponding @key{OffN} action. The actions @key{Off} and
4917
@key{Off1} are synonyms.
4918
4919
@item Pointer Motion
4920
Pointer motion generates @key{Move} actions. The action does not
4921
indicate anything about the pointer position; use e.g.,
4922
@code{query-last-pointer} to find that information.
4923
@end table
4924
4925
@noindent
4926
For example, a single click of the left mouse button with the
4927
@key{Meta} key held would be described as @kbd{M-Button1-Click1}.
4928
After triple-clicking with the @key{Alt} key held down, Sawfish will
4929
receive a @kbd{Alt-Off3} event.
4930
4931
@defvar multi-click-delay
4932
An integer indicating the maximum number of milliseconds between
4933
successive clicks. Defaults to 250 milliseconds at startup; if
4934
@code{nil}, Sawfish uses 250 milliseconds.
4935
@end defvar
4936
4937
@node Event Matching, Synthetic Events, Event Actions, Events
4938
@section Event Matching
4939
@cindex Event Matching
4940
@cindex Matching, Events
4941
4942
There is a special function that matches event objects. If the
4943
actions of two event objects are not identical, the events do not
4944
match. If they are identical, then the events match if the modifiers
4945
are identical, or if one of the modifiers is @key{Any}.
4946
@xref{Event Modifiers}.
4947
4948
@defun event-match ev1 ev2
4949
Returns @code{t} if events @var{ev1} and @var{ev2} match, @code{nil}
4950
otherwise.
4951
@end defun
4952
4953
@node Synthetic Events, , Event Matching, Events
4954
@section Synthetic Events
4955
@cindex Synthetic Events
4956
@cindex Events, Synthetic
4957
@cindex Events, Synthesizing
4958
4959
It is possible to create an event inside Sawfish that mimics a real
4960
keyboard or mouse event.
4961
4962
@defun synthesize-event event window &optional propagate
4963
Generate a synthetic key press or button press and send it to the X
4964
window bound to the @var{window} object. This press is automatically
4965
followed by the appropriate release event.
4966
4967
The current pointer position becomes the position of the event.
4968
4969
@var{Event} is either an event object, or the string representation of
4970
an event (such as @code{"A-f"} or @code{"C-M-Button3-Click2"}).
4971
Strings are parsed into event objects before any work is done.
4972
@xref{Event Representation}.
4973
4974
If @var{propagate} is true, the event will propagate up the window
4975
ancestor chain until it is handled.
4976
@end defun
4977
4978
4979
@node Commands, Keymaps, Events, Top
4980
@chapter Commands
4981
@cindex Commands
4982
4983
A @dfn{command} is a Lisp function which may be called interactively,
4984
that is, as a result of being bound to an input event. To support
4985
this, we mark them with metadata that the runtime system can query.
4986
4987
@menu
4988
* Old-style Command Definition:: Emacs-Lisp style
4989
* New-style Command Definition:: Common-Lisp style
4990
* Interactive Calling Specification::
4991
* Operations on Commands:: Accessors and the like
4992
* Invoking Commands:: call-commmand, command hooks
4993
* Default Commands:: Sawfish ships with a few commands
4994
@end menu
4995
4996
@node Old-style Command Definition, New-style Command Definition, Commands, Commands
4997
@section Old-style Command Definition
4998
4999
The old-style command declaration syntax looks very much like that of
5000
GNU Emacs Lisp. Commands are defined like any other function (using
5001
@code{defun}), but the first form in the body must be an
5002
@dfn{interactive declaration}. This marks that the function may be
5003
called interactively and tells the @code{call-command} function how to
5004
compute the argument values to apply to the command.
5005
5006
The interactive declaration looks like a call to the special form
5007
@code{interactive}, in actual fact this special form always returns
5008
@code{nil} and has no side-effects. The only effect of this form is to
5009
show the @code{call-command} function that the function definition may
5010
be called interactively. The second element of the declaration form
5011
(after the @code{interactive} symbol) defines how the argument values
5012
applied to the command are computed.
5013
5014
The structure of an interactive declaration, then, is:
5015
5016
@lisp
5017
@findex interactive
5018
(interactive [@var{calling-spec}])
5019
@end lisp
5020
5021
When a command is defined this is how it includes the interactive
5022
declaration:
5023
5024
@lisp
5025
(defun some-command (arg1)
5026
"Optional documentation string."
5027
(interactive @dots{})
5028
@dots{}
5029
@end lisp
5030
5031
The @var{calling-spec} is defined in @xref{Interactive Calling
5032
Specification}.
5033
5034
@node New-style Command Definition, Interactive Calling Specification, Old-style Command Definition, Commands
5035
@section New-style Command Definition
5036
5037
The new syntax does not depend on special magic in @code{defun}.
5038
Instead, it uses keyword arguments to indicate the calling
5039
specification and other properties.
5040
5041
@defun define-command name fun #!key spec type doc doc-key class
5042
Define a window managed command called @var{name} (a symbol). The
5043
function @var{fun} will be called to execute the command.
5044
5045
@var{spec} and @var{type} may be used to define the arguments expected
5046
by the command; @var{spec} is an interactive specification and
5047
@var{type} is a custom-type specification. @xref{Interactive Calling
5048
Specification}.
5049
5050
@var{doc} is the documentation string associated with the command.
5051
The command-documentation may be stored in the doc file, rather than
5052
in the code itself; if it exists, the @var{doc-key} will be used to
5053
look up the doc file entry. If both arguments are provided, both will
5054
be stored. But the @code{command-documentation} function favors the
5055
built-in doc string over the doc file entry.
5056
5057
@var{class} is an annotation for the command. It allows the
5058
definition to mark the class as @code{'advanced}, for example. Other
5059
parts of Sawfish can then take advantage of this note.
5060
@end defun
5061
5062
@defun define-command-to-screen name fun #!key spec type doc doc-key class
5063
As @code{define-command}, but any printed output of @var{fun} is sent
5064
to the screen.
5065
@end defun
5066
5067
@defun autoload-command name module #!key spec type doc doc-key class
5068
Record that loading the module called @var{module} (a symbol) will provde a
5069
command called @var{name}.
5070
5071
The keyword values have the same meanings as for
5072
@code{define-command}. Defining those properties as part of the
5073
autoload provides useful feedback to the user without having to do
5074
loading.
5075
@end defun
5076
5077
@node Interactive Calling Specification, Operations on Commands, New-style Command Definition, Commands
5078
@section Interactive Calling Specification
5079
5080
The @var{calling-spec} argument to @code{interactive} or
5081
@code{define-command} defines the argument values applied to the
5082
command when it is called interactively. It may be one of:
5083
5084
@itemize @bullet
5085
@item @code{nil} or undefined (i.e. @code{(interactive)})
5086
No arguments are given to the command, this type of interactive
5087
declaration just shows that the function may be called interactively.
5088
5089
@item A string
5090
This is interpreted as zero or more lines (each separated by a newline
5091
character). Each line defines how to compute one argument value. The
5092
first one or two characters of each line is a prefix defining exactly
5093
how to compute the argument, the rest of the line is an optional
5094
argument which some prefixes may use. See below for a list of
5095
prefixes. A null line produces an argument value of @code{nil}.
5096
5097
@item Anything else
5098
The form is evaluated and expected to return a @emph{list} of
5099
arguments to apply to the command.
5100
@end itemize
5101
5102
The currently available prefixes are,
5103
5104
@table @samp
5105
@item e
5106
The event which caused this command to be invoked.
5107
5108
@item E
5109
The event which caused this command, cooked into a string.
5110
5111
@item p
5112
The prefix argument as a number, this will be 1 if no prefix argument
5113
has been entered.
5114
5115
@item P
5116
The raw prefix argument.
5117
5118
@item t
5119
The symbol @code{t}.
5120
5121
@item %f
5122
The window which currently has the input focus, or @code{nil} if no
5123
window is focused.
5124
5125
@item %w
5126
The result of calling the @code{current-event-window} function.
5127
5128
@item %W
5129
The result of calling the @code{current-event-window} function, or if
5130
this returns @code{nil} or @code{root}, the currently focused window.
5131
@end table
5132
5133
@node Operations on Commands, Invoking Commands, Interactive Calling Specification, Commands
5134
@section Operations on Commands
5135
5136
Once a command has been defined, we can extract certain information
5137
about it.
5138
5139
@defun commandp @var{object}
5140
This function returns @code{t} if its argument may be called interactively.
5141
If @var{object} is a function (i.e. a symbol or a lambda-expression) it
5142
is a command if it contains an interactive declaration
5143
5144
The only other object which is a command is a function call form; the
5145
use of these types of commands is discouraged but they can be useful
5146
sometimes.
5147
@end defun
5148
5149
@defun command-documentation name
5150
Return the documentation for the command @var{name}. It returns the
5151
first documentation found by looking at (in order): the documentation
5152
property of the command; the doc file entry associated with the doc
5153
key property; or the documentation for the function with the same
5154
name.
5155
@end defun
5156
5157
@defun command-spec name
5158
@defunx command-type name
5159
@defunx command-class name
5160
Return the specification, type or class (respectively) of the named
5161
command.
5162
@end defun
5163
5164
@node Invoking Commands, Default Commands, Operations on Commands, Commands
5165
@section Invoking Commands
5166
5167
When a command is to be invoked, the @code{call-command} function is
5168
used. This builds a list of argument values to apply to the command
5169
(using its interactive declaration) then calls the command.
5170
5171
@defun call-command command &optional prefix-arg
5172
This function calls the command @var{command} interactively. See the
5173
documentation of @code{commandp} above for what constitutes a command.
5174
5175
If the @var{prefix-argument} is non-nil it defines the value of the
5176
@code{current-prefix-arg} variable for this command, normally the value
5177
of this variable would be taken from the global @code{prefix-arg}
5178
variable.
5179
5180
There is a corresponding @code{call-command} command that prompts for
5181
a command to execute.
5182
@end defun
5183
5184
@defun apply-command name &rest args
5185
Call the function underlying the command @var{name}, passing in
5186
@var{args} as the arguments. This is useful for calling a command in
5187
a non-interactive context.
5188
@end defun
5189
5190
@defvar current-prefix-arg
5191
When invoking an interactive command, this is set to the current
5192
prefix argument.
5193
@end defvar
5194
5195
@defvar this-command
5196
The command currently being called, or @samp{nil} if no command is
5197
being called.
5198
@end defvar
5199
5200
@defvar last-command
5201
The command previously called, or @samp{nil} if there is no such
5202
command.
5203
@end defvar
5204
5205
@xref{Command Hooks}, for hooks run before and after commands.
5206
5207
@node Default Commands, , Invoking Commands, Commands
5208
@section Default Commands
5209
5210
Sawfish defines several commands by default.
5211
5212
@defun run-shell-command
5213
The command prompts the user for a string, and executes that string as
5214
under @code{system}.
5215
@end defun
5216
5217
@defun quit
5218
@defunx restart
5219
@defunx destroy-window
5220
@defunx kill-client
5221
@defunx no-operation
5222
Calls the function of the same name. @code{destroy-window} and
5223
@code{kill-client} both take @code{%W} as argument.
5224
@end defun
5225
5226
@node Keymaps, Event Loop, Commands, Top
5227
@chapter Keymaps
5228
@cindex Keymaps
5229
5230
Keymaps are used to associate events with commands. When an event
5231
occurs, the associated command is found and evaluated. A keymap is
5232
simply a list whose first element is the symbol @code{keymap}.
5233
5234
@defun keymapp arg
5235
Returns @code{t} if @var{arg} may be used as a keymap.
5236
@end defun
5237
5238
@defun make-keymap
5239
Returns a newly-created empty keymap.
5240
@end defun
5241
5242
@defun bind-keys keymap &rest bindings
5243
Installs zero or more key bindings into the keymap @var{keymap}, then
5244
returns @var{keymap}.
5245
5246
Each binding is defined by two elements in the list of @var{bindings},
5247
the first defines the name of the input event (or the event itself) and
5248
the second defines the command to be associated with the event.
5249
5250
For example to bind two keys in the keymap @var{keymap}; the event
5251
@kbd{C-f} to the command @code{foo} and the event @kbd{C-b} to the
5252
command @code{bar} the following form would be used,
5253
5254
@lisp
5255
(bind-keys @var{keymap}
5256
"C-f" 'foo
5257
"C-b" 'bar)
5258
@end lisp
5259
@end defun
5260
5261
@defun unbind-keys @var{keymap} &rest @var{keys}
5262
Removes the bindings of the events @var{keys} (these may be the names
5263
of the events or the event objects themselves) from the keymap
5264
@var{keymap}.
5265
@end defun
5266
5267
@defun search-keymap event keymap
5268
Search for a binding of the event @var{event} in @var{keymap}. If a
5269
binding is found a cons cell @code{(@var{command} . @var{event})} is
5270
returned.
5271
@end defun
5272
5273
There are several pre-defined keymaps that are always available:
5274
5275
@table @code
5276
@item global-keymap
5277
Keymap containing bindings active anywhere.
5278
5279
@item window-keymap
5280
Keymap containing bindings active when a client window is focused.
5281
5282
@item root-window-keymap
5283
Keymap containing bindings active when the pointer is in the root
5284
window.
5285
5286
@item title-keymap
5287
@itemx border-keymap
5288
Keymaps active in the title and borders of window frames.
5289
5290
@item close-button-keymap
5291
@itemx iconify-button-keymap
5292
@itemx maximize-button-keymap
5293
@itemx menu-button-keymap
5294
@itemx shade-button-keymap
5295
Keymaps active in the standard window frame buttons.
5296
5297
@item override-keymap
5298
Must be a keymap, a symbol, or @code{nil}. If it is a keymap,
5299
this becomes the keymap in which all lookups occur (overriding the window,
5300
root and global keymaps). If it is a symbol, Sawfish finds the
5301
symbol's value and tries again. If it is @code{nil}, Sawfish behaves
5302
normally.
5303
5304
@end table
5305
5306
5307
@node Event Loop, Miscellaneous Functions, Keymaps, Top
5308
@chapter Event Loop
5309
@cindex Event loop
5310
5311
The event loop reads all X events received on any of the windows that
5312
Sawfish is aware off. Many of these events invoke hooks, as described
5313
in @ref{Standard Hooks}. Keyboard and pointer events are translated to
5314
their Lisp equivalents (@pxref{Events}) and then used to scan all
5315
active keymaps for a binding. If a binding is found, the associated
5316
command is invoked through the @code{call-command} function.
5317
5318
The active keymaps are determined as follows:
5319
5320
@itemize @bullet
5321
@item If the variable @code{override-keymap} is non-nil, then this is
5322
the only keymap searched
5323
5324
@item Otherwise three keymaps are searched:
5325
5326
@enumerate
5327
@item the @code{keymap} property of the currently ``clicked'' frame
5328
part if there is one,
5329
5330
@item the @code{keymap} property of the currently focused window
5331
5332
@item the contents of the variable @code{global-keymap}.
5333
@end enumerate
5334
@end itemize
5335
5336
Note that for @code{ButtonRelease} events, the frame part's keymap is
5337
only searched if the pointer is actually within the frame part when the
5338
release event occurs.
5339
5340
If no binding may be found in any of the active keymaps, then the
5341
@code{unbound-key-hook} hook is called. This is an @code{or} type
5342
hook---the first function that returns non-nil will terminate the hook
5343
call.
5344
5345
@defun lookup-event-binding event
5346
Perform the usual binding lookup for the event object @var{object}.
5347
Returns the command found, or @code{nil} if no binding exists.
5348
@end defun
5349
5350
By default, both key-release events, and events that are bound to
5351
modifier keys (e.g. @key{Control_L}), are ignored. However, this
5352
behavior may be changed:
5353
5354
@defvar eval-modifier-events
5355
When non-nil, key events bound to modifier keys are evaluated.
5356
@end defvar
5357
5358
@defvar eval-key-release-events
5359
When non-nil, key-release events are evaluated.
5360
@end defvar
5361
5362
While a command is being evaluated, information about the event that
5363
caused it may be found:
5364
5365
@defun current-event
5366
Return the event which caused the current command to be invoked
5367
@end defun
5368
5369
@defun current-event-string
5370
Returns the string which the current event would usually insert.
5371
@end defun
5372
5373
@defun current-event-window &optional win
5374
Extract the owning window of the current X event (this is a window
5375
object, or the symbol @code{root} for the root window, or @code{nil}
5376
if there is no window or no event). This is stored internally as the
5377
current event window, and returned.
5378
@c FIXME-DLU: why does this function take a WIN parameter?
5379
@end defun
5380
5381
@defun last-event
5382
Return the previous event which occurred.
5383
@end defun
5384
5385
@defun proxy-current-event window &optional mask propagate
5386
Send the current X event to @var{window}, either a window object, a
5387
numeric window id, or the symbol @code{root}. If a @code{ButtonPress}
5388
event the pointer grab will be released first.
5389
5390
@var{Mask} may be an integer defining the X event mask to pass to the
5391
@code{XSendEvent} function. If not defined, a mask is chosen that would
5392
usually be used to select the type of event being proxied.
5393
5394
@var{Propagate} is a flag (@code{nil}/non-@code{nil}) passed directly
5395
to an underlying @code{XSendEvent} call. (And if someone would like
5396
to explain what @emph{that} means, please do so @enddots{}
5397
@end defun
5398
5399
@defun allow-events mode
5400
This is a wrapper for the @code{XAllowEvents} function. The @var{mode}
5401
parameter may be one of the following symbols: @code{async-pointer},
5402
@code{async-keyboard}, @code{sync-pointer}, @code{sync-keyboard},
5403
@code{replay-pointer}, @code{replay-keyboard}, @code{async-both},
5404
@code{sync-both}.
5405
5406
Events that have to be grabbed to be received (i.e. all bindings in the
5407
@code{global-keymap} and the @code{window-keymap}) are grabbed
5408
synchronously. This means that no more events will be received until
5409
either the command returns, or @code{allow-events} is called.
5410
5411
This is normally not important, but if the command expects to receive
5412
further events it must call @code{allow-events}. See the interactive
5413
move and resize functions for an example.
5414
@end defun
5415
5416
@defun forget-button-press
5417
Cause the next button press to be treated as a single click event, no
5418
matter how soon it occurs after the prevous button-press event.
5419
@end defun
5420
5421
@defun accept-x-input &optional mask
5422
Handle any X events received. If @var{mask} is non-nil then only events
5423
matching this numeric value are handled (see the X header files for
5424
details).
5425
@end defun
5426
5427
@defun x-events-queued
5428
Returns the number of X events waiting to be handled.
5429
@end defun
5430
5431
5432
@node Miscellaneous Functions, Standard Hooks, Event Loop, Top
5433
@chapter Miscellaneous Functions
5434
@cindex Miscellaneous functions
5435
5436
@menu
5437
* Pointer Functions::
5438
* Grab Functions::
5439
* Display Functions::
5440
* Gradient Functions::
5441
* Other Functions::
5442
@end menu
5443
5444
@node Pointer Functions, Grab Functions, , Miscellaneous Functions
5445
@section Pointer Functions
5446
@cindex Pointer functions
5447
@cindex Functions, pointer
5448
5449
@defun query-pointer &optional from-server
5450
Returns a cons cell @code{(@var{x} . @var{y})} representing the current
5451
mouse pointer position, relative to the origin of the root window.
5452
5453
If there is a mouse update current event, the position is read
5454
directly from that event. Otherwise it is read from the server. If
5455
@var{from-server} is non-nil then the position is read directly from
5456
the server in any case.
5457
@end defun
5458
5459
@defun query-pointer-window
5460
Returns the top-level window under the mouse pointer, or @code{nil} if
5461
the cursor is in the root window.
5462
@end defun
5463
5464
@defun query-last-pointer
5465
Returns a cons cell @code{(@var{x} . @var{y})} representing the second
5466
most recent mouse pointer position, relative to the root window.
5467
@end defun
5468
5469
@defun query-button-press-pointer
5470
Returns @code{(@var{mouse-x} . @var{mouse-y})} representing the mouse
5471
position relative to the root window at the last button-press event.
5472
5473
Use this function to track the displacement of the pointer during a
5474
drag.
5475
@end defun
5476
5477
@defun query-button-press-window
5478
Returns the window that the mouse was in when the button was pressed.
5479
@end defun
5480
5481
@defun warp-cursor x y
5482
Move the mouse pointer to position (@var{x}, @var{y}) relative to the
5483
origin of the root window.
5484
@end defun
5485
5486
@defun warp-cursor-to-window window &optional x y
5487
Move the mouse pointer to position (@var{x}, @var{y}) relative to the
5488
client window associated with object @var{window}.
5489
5490
If @var{x} and @var{y} are @code{nil}, then they are taken as the
5491
top-left corner of the window's frame.
5492
5493
If @code{warp-to-window-enabled} is @code{nil}, this function does
5494
nothing.
5495
@end defun
5496
5497
@defvar warp-to-window-offset
5498
Offset (%) from window edges when warping pointer. A negative number
5499
means outside the left window edge.
5500
@end defvar
5501
5502
@defvar warp-to-window-enabled
5503
When false, disable warping the cursor to windows.
5504
@end defvar
5505
5506
@defvar pointer-motion-threshold
5507
If set to an integer value, a pointer must move by this many pixels on
5508
either axis before Sawfish considers it to have moved. If the pointer
5509
has not moved by this amount, Sawfish will ignore @code{MotionNotify}
5510
events from X. The variable defaults to 2 pixels. If not an integer,
5511
Sawfish assumes a threshold of 0 pixels.
5512
@end defvar
5513
5514
5515
@node Grab Functions, Display Functions, Pointer Functions, Miscellaneous Functions
5516
@section Grab Functions
5517
@cindex Grab functions
5518
@cindex Functions, grab
5519
5520
@defun grab-server
5521
Prevent any other clients from accessing the X server.
5522
@end defun
5523
5524
@defun ungrab-server
5525
After a call to @code{grab-server} this will allow other clients to
5526
access the X server again.
5527
5528
Note that calls to @code{grab-server} and @code{ungrab-server}
5529
@emph{nest}.
5530
@end defun
5531
5532
@defmac with-server-grabbed &rest forms
5533
Evaluate forms with the server grabbed. Releases the grab afterwards.
5534
@end defmac
5535
5536
@defun call-with-server-ungrabbed thunk
5537
Return the result of calling the zero-parameter function
5538
@var{thunk}. If the server is currently grabbed, ungrab it first,
5539
restoring the original grab status after the call to @var{thunk}
5540
returns.
5541
@end defun
5542
5543
@defun server-grabbed-p
5544
Returns @code{t} if the X server is currently grabbed.
5545
@end defun
5546
5547
@defun grab-pointer &optional window cursor ptr-sync kbd-sync confine-to
5548
Grab the mouse pointer and direct all pointer events to window object
5549
@var{window}. If @var{cursor} is defined and a cursor object, display
5550
this while the pointer is grabbed.
5551
5552
If @var{window} is a window object corresponding to a
5553
visible window, the grab will be made on its frame.
5554
5555
If @var{window} is an integer, it specifies the window ID of the grab
5556
window.
5557
5558
Otherwise the grab will be made on the root window. This includes
5559
@var{window} corresponding to a non-viewable window.
5560
5561
@var{Confine-to}, if non-@code{nil}, is a visible window to confine
5562
the pointer to. It is interpreted similarly to the rules for
5563
@var{window}, except that the ``otherwise'' case is to not confine the
5564
pointer.
5565
5566
If the window id of a non-viewable window was specified for either
5567
@var{window} of @var{confine-to}, the grab will be made on the root
5568
window without confining the pointer.
5569
5570
If @var{ptr-sync} or @var{kbd-sync} is non-@var{nil}, the pointer or
5571
keyboard will be frozen, i.e., the device will not produce events
5572
until either the grab is released or events are re-enabled using
5573
@code{allow-events}.
5574
5575
Returns non-nil if the grab succeeded.
5576
@end defun
5577
5578
@defun ungrab-pointer
5579
Release the grab on the mouse pointer.
5580
@end defun
5581
5582
@defun grab-keyboard &optional window ptr-sync kbd-sync
5583
Grab the keyboard and direct all keyboard events to window object
5584
@var{window}.
5585
5586
If @var{window} is a window object corresponding to a
5587
visible window, the grab will be made on its frame.
5588
5589
If @var{window} is an integer, it specifies the window ID of the grab
5590
window.
5591
5592
Otherwise the grab will be made on the root window. This includes
5593
@var{window} corresponding to a non-viewable window.
5594
5595
If @var{ptr-sync} or @var{kbd-sync} is non-@var{nil}, the pointer or
5596
keyboard will be frozen, i.e., the device will not produce events
5597
until either the grab is released or events are re-enabled using
5598
@code{allow-events}.
5599
5600
Returns non-nil if the grab succeeded.
5601
@end defun
5602
5603
@defun ungrab-keyboard
5604
Release the grab on the keyboard.
5605
@end defun
5606
5607
@defun call-with-keyboard-grabbed thunk
5608
Call the zero-parameter function @var{thunk} with the keyboard
5609
grabbed. If unable to grab the keyboard then @var{thunk} won't be
5610
called.
5611
@end defun
5612
5613
5614
@node Display Functions, Gradient Functions, Grab Functions, Miscellaneous Functions
5615
@section Display Functions
5616
@cindex Display functions
5617
@cindex Functions, display
5618
5619
@defun screen-width
5620
Return the width of the root window.
5621
@end defun
5622
5623
@defun screen-height
5624
Return the height of the root window.
5625
@end defun
5626
5627
@defun screen-dimensions
5628
Return the screen dimensions in pixels as a cons cell
5629
@code{(@var{width} . @var{height})}.
5630
@end defun
5631
5632
@defun draw-window-outline mode x y width height
5633
Draw an outline of a window of dimensions (@var{width}, @var{height})
5634
at position (@var{x}, @var{y}) relative to the root window.
5635
5636
@var{mode} is a symbol defining the type of outline drawn, currently it
5637
may only be @code{box} for a 3x3 grid.
5638
5639
Use the @code{erase-window-outline} to erase the grid. Also note that
5640
since these functions draw directly on the root window the server
5641
should be grabbed until the outline is erased.
5642
@end defun
5643
5644
@defun erase-window-outline mode x y width height
5645
Erase a previously drawn outline of a window of dimensions
5646
(@var{width}, @var{height}) at position (@var{x}, @var{y}) relative to
5647
the root window.
5648
5649
@var{mode} is a symbol defining the type of outline drawn, currently it
5650
may only be @code{box} for a 3x3 grid.
5651
@end defun
5652
5653
@defun display-message &optional text attributes
5654
Display the string @var{text} in a window on the screen. If @var{text}
5655
is @code{nil} then any string previously displayed is removed. Returns
5656
the numeric id of the window displaying the message, or @code{nil} if
5657
no message is displayed.
5658
5659
@var{attributes} is an alist specifying how the string should be
5660
displayed; each element of the list is a cons cell @code{(@var{attr} .
5661
@var{value})} associating an attribute @var{attr} (a symbol) with it's
5662
value.
5663
5664
Possible attributes currently include:
5665
5666
@table @code
5667
@item font
5668
The font to use
5669
5670
@item foreground
5671
The color (or color name) to draw the text with
5672
5673
@item background
5674
The color (or color name) to draw the background with
5675
5676
@item x-justify
5677
The justification method for multi-line strings. One of the symbols
5678
@code{left}, @code{right}, or @code{center}
5679
5680
@item spacing
5681
The number of extra pixels of vertical spacing to leave between text
5682
lines.
5683
5684
@item position
5685
A cons cell defining the coordinates at which to display the message
5686
window. The cell is @code{(@var{x} . @var{y})}. @var{x} and @var{y} are
5687
integers or @code{nil} (for centered display). If negative they count
5688
in from the left and bottom edges respectively.
5689
5690
@item head
5691
The head on which to center the message when a position is not specified or
5692
given as nil. If not provided defaults to the head containing the window that
5693
has the input focus.
5694
@end table
5695
@end defun
5696
5697
5698
@node Gradient Functions, Other Functions, Display Functions, Miscellaneous Functions
5699
@section Gradient Functions
5700
@cindex Gradient functions
5701
@cindex Functions, gradients
5702
5703
The @code{gradient} feature allows color gradients to be drawn in
5704
images. (Evaluate @code{(require 'gradient)} to load this feature.)
5705
5706
@defun draw-vertical-gradient image from to
5707
Draw a vertical color gradient in @var{image}. The color at the top of
5708
the image will be @var{from}, the color at the bottom @var{to}, with a
5709
smooth transition between.
5710
@end defun
5711
5712
@defun draw-horizontal-gradient image from to
5713
Draw a horizontal color gradient in @var{image}, from left to right.
5714
The color at the left of the image will be @var{from}, the color at
5715
the right @var{to}, with a smooth transition between.
5716
@end defun
5717
5718
@defun draw-diagonal-gradient image from to
5719
Draw a horizontal color gradient in @var{image}, from the top-left
5720
corner to the bottom-right. The color at the top-left of the image
5721
will be @var{from}, the color at the bottom-right @var{to}, with a
5722
smooth transition between.
5723
@end defun
5724
5725
5726
@node Other Functions, , Gradient Functions, Miscellaneous Functions
5727
@section Other Functions
5728
@cindex Other functions
5729
@cindex Functions, other
5730
5731
@defun sync-server
5732
Flush all pending X requests, don't wait for them to finish.
5733
@end defun
5734
5735
@defun send-client-message window type data format
5736
Send an X @code{ClientMessage} event to @var{window} (a window object,
5737
the symbol @code{root} or a numeric xid).
5738
5739
The event will be of the type @var{type} (a symbol), contain the array
5740
of integers @var{data} (i.e. a vector or a string), and will be
5741
transferred as @var{format} sized quantities (8, 16 or 32).
5742
@end defun
5743
5744
@defun create-window parent x y width height
5745
Create an unmapped window that is a child of @var{parent} (a window
5746
object, an integer window id, or the symbol @code{root}), with the
5747
specified dimensions.
5748
5749
Returns the window id of the new window.
5750
@end defun
5751
5752
@defun exit-type
5753
If Sawfish is shutting down, this function returns one of the strings
5754
@code{"user-quit"}, @code{"user-restart"} or @code{"session-quit"}.
5755
If Sawfish is not shutting down, it returns @code{nil}.
5756
@end defun
5757
5758
@defun x-atom symbol
5759
Return the integer identifying the X atom with the same name as
5760
@var{symbol}.
5761
@end defun
5762
5763
@defun x-atom-name integer
5764
Return the symbol with the same name as the X atom identified by the
5765
integer @var{integer}.
5766
@end defun
5767
5768
@defvar canonical-display-name
5769
A string containing the canonical name of the X display. This
5770
includes the full host name and the screen number. For example:
5771
@code{"foo.bar.com:0.0"}.
5772
@end defvar
5773
5774
@defvar display-name
5775
A string containing the name of the X display, exactly as passed to
5776
Sawfish. For example: @code{":0"}, or @code{"foo:0.0"}.
5777
@end defvar
5778
5779
@defvar saved-command-line-args
5780
Holds a list of all of the command line arguments (including the
5781
executable name).
5782
@end defvar
5783
5784
@defvar sawfish-directory
5785
The home directory for Sawfish files. For example:
5786
@code{"/usr/share/sawfish"}.
5787
@end defvar
5788
5789
@defvar sawfish-exec-directory
5790
The directory for architechture-specific Sawfish executables. For
5791
example: @code{"/usr/lib/sawfish/1.3/i386-pc-linux-gnu"}.
5792
@end defvar
5793
5794
@defvar sawfish-lisp-lib-directory
5795
The top-level directory for Sawfish lisp files. For example:
5796
@code{"/usr/share/sawfish/1.3/lisp"}.
5797
@end defvar
5798
5799
@defvar sawfish-locale-directory
5800
The system directory where Sawfish can find locale files. This is not
5801
part of the Sawfish distribution. For example:
5802
@code{"/usr/share/locale"}.
5803
@end defvar
5804
5805
@defvar sawfish-site-lisp-directory
5806
The top-level directory for site-specific Sawfish lisp files. For
5807
example: @code{"/usr/share/sawfish/site-lisp"}.
5808
@end defvar
5809
5810
@defvar sawfish-version
5811
The version number of the running Sawfish.
5812
@end defvar
5813
5814
@defun primitive-play-sample filename
5815
Plays the sound file @var{filename} (which must be a string).
5816
@end defun
5817
5818
@defun call-with-error-handler thunk
5819
Call the zero-parameter function @var{thunk}. If an error occurs,
5820
trap it and pass its @code{car} and @code{cdr} to
5821
@code{error-handler-function}.
5822
@end defun
5823
5824
@defun load-module name
5825
Ensure that module @var{name} has been loaded. This does @emph{not}
5826
import its bindings or make them accessible.
5827
@end defun
5828
5829
@defun eval-in form struct-name
5830
Evaluates @var{form} in the structure named by @var{struct-name}.
5831
Compare this with @code{eval}, which takes a structure object as its
5832
second parameter, not a structure name.
5833
@end defun
5834
5835
@defvar *user-module*
5836
@code{*user-module*} is the default module for human interaction with
5837
Sawfish.
5838
@end defvar
5839
5840
@defun user-eval form
5841
@defunx user-require feature
5842
@code{user-eval} evaluates @code{form} in @code{*user-module*}.
5843
@code{user-require} evaluates @code{(require @var{feature})} in
5844
@code{*user-module*}.
5845
@end defun
5846
5847
@defun quote-menu-item string
5848
Escape any @samp{_} characters in @var{string} such that the result
5849
can be used as the label of a menu item.
5850
@end defun
5851
5852
@defun make-directory-recursively dir
5853
Create directory @var{dir}. Any missing parent directories will also
5854
be created.
5855
@end defun
5856
5857
@defun locate-file filename dirs
5858
Search for a file @var{filename} in any of the directories named by
5859
the list of strings @var{dirs}.
5860
@end defun
5861
5862
@defun clamp x lower upper
5863
Return @var{x} clamped between @var{lower} and @var{upper}. If
5864
@var{x} is less than @var{lower}, return @var{lower}; if it is larger
5865
than @var{upper} return @var{upper}. Otherwise return @var{x}.
5866
@end defun
5867
5868
@defun clamp* x y lower upper
5869
Return the interval (@var{x}, @var{x}+@var{w}) clamped between
5870
@var{lower} and @var{upper}. If @var{x} is less than @var{lower},
5871
return @var{lower}. If @var{x}+@var{w} is larger than @var{upper},
5872
return @var{upper}-@var{w}; this is a value of @var{x} that satisfies
5873
the upper bound, although it may violate the lower bound. Otherwise
5874
return @var{x}.
5875
@end defun
5876
5877
@defun uniquify-list lst
5878
Remove all duplicates values from @var{lst}, using @code{eq}. The
5879
order of elements is not preserved.
5880
@end defun
5881
5882
@node Standard Hooks, Standard Properties, Miscellaneous Functions, Top
5883
@chapter Standard Hooks
5884
@cindex Standard hooks
5885
@cindex Hooks, standard
5886
5887
Sawfish provides many hooks to allow extension of previously defined
5888
functions. Also, many X events are exported to the Lisp environment via
5889
the hooks mechanism. For more details on the hooks mechanism see
5890
@ref{Normal Hooks, , Normal Hooks, librep, The Librep Manual}.
5891
5892
As well as using the standard @code{call-hook} function, sawfish also
5893
provides the @code{call-window-hook} function. This is used to invoke
5894
hooks which refer to a single window. If the hook has a local value
5895
defined in the window's property list then this value is used, before
5896
the default value defined by the actual variable.
5897
5898
@defun call-window-hook hook window &optional args hook-type
5899
Call @var{hook} for @var{window} with further arguments @var{args}. See
5900
@code{call-hook} for a description of @var{hook-type}. Each function in
5901
the hook is called with arguments @code{(@var{window} . @var{args})}.
5902
@end defun
5903
5904
The available hooks are listed below.
5905
5906
@menu
5907
* Command Hooks::
5908
* Key Hooks::
5909
* Window Construction Hooks::
5910
* Window Destruction Hooks::
5911
* Window Mapping Hooks::
5912
* Window Motion Hooks::
5913
* Window Cycling Hooks::
5914
* X Hooks::
5915
* Pointer Motion Hooks::
5916
* Workspace Hooks::
5917
* Startup and Shutdown Hooks::
5918
* Other Hooks::
5919
@end menu
5920
5921
5922
@node Command Hooks, Key Hooks, Standard Hooks, Standard Hooks
5923
@section Command Hooks
5924
@cindex Command Hooks
5925
@cindex Hooks, Command
5926
5927
@defvr {Hook} pre-command-hook
5928
Called before each command is evaluated.
5929
@end defvr
5930
5931
@defvr {Hook} post-command-hook
5932
Called after each command is evaluated.
5933
@end defvr
5934
5935
5936
@node Key Hooks, Window Construction Hooks, Command Hooks, Standard Hooks
5937
@section Key Hooks
5938
@cindex Key Hooks
5939
@cindex Hooks, Key
5940
5941
@defvr {Hook} unbound-key-hook
5942
Called when an key or pointer event has been received which there is
5943
no binding for. The hook functions return no arguments. This is an
5944
@code{or}-type hookk---the first function that returns non-@code{nil}
5945
will terminate the hook call.
5946
5947
Under normal circumstances, an unbound key release causes a
5948
@code{throw} to top-level. Adding @emph{any} function to this hook
5949
suppresses that behavior.
5950
@end defvr
5951
5952
5953
@node Window Construction Hooks, Window Destruction Hooks, Key Hooks, Standard Hooks
5954
@section Window Construction Hooks
5955
@cindex Window Construction Hooks
5956
@cindex Hooks, Window Construction
5957
5958
@defvr {Window Hook} before-add-window-hook
5959
@defvrx {Window Hook} add-window-hook
5960
Called when the window is first adopted by the window manager. This
5961
occurs before the window is created, installed or placed. At this
5962
early stage, the only safe action is to set properties of the window
5963
(with @code{window-set}).
5964
5965
@code{add-window-hook} is a deprecated hook, replaced by
5966
@code{before-add-window-hook}. It is called immediately after
5967
@code{before-add-window-hook}.
5968
@end defvr
5969
5970
@defvr {Window Hook} after-add-window-hook
5971
Called when the window is first adopted by the window manager. This
5972
occurs after the window has been created, installed and placed.
5973
@end defvr
5974
5975
@defvr {Window Hook} after-framing-hook
5976
Called after a window gets a frame assigned, or after a window's
5977
frame is rebuilt.
5978
@end defvr
5979
5980
5981
@node Window Destruction Hooks, Window Mapping Hooks, Window Construction Hooks, Standard Hooks
5982
@section Window Destruction Hooks
5983
@cindex Window Destruction Hooks
5984
@cindex Hooks, Window Destruction
5985
5986
@defvr {Window Hook} destroy-notify-hook
5987
Called when the window is destroyed. Note that this may be called
5988
asynchronously to the normal event loop. In general, once the window
5989
manager knows the window has been destroyed, it will attempt to call
5990
this hook as soon as possible.
5991
@end defvr
5992
5993
5994
@node Window Mapping Hooks, Window Motion Hooks, Window Destruction Hooks, Standard Hooks
5995
@section Window Mapping Hooks
5996
@cindex Window Mapping Hooks
5997
@cindex Hooks, Window Mapping
5998
5999
@defvr {Window Hook} map-notify-hook
6000
@defvrx {Window Hook} unmap-notify-hook
6001
@defvrx {Window Hook} reparent-notify-hook
6002
@defvrx {Window Hook} shape-notify-hook
6003
Called with a window is mapped, unmapped, reparented, or has its shape
6004
changed, respectively.
6005
6006
Note that iconifying and uniconifying windows triggers unmapping and
6007
mapping, respectively.
6008
@end defvr
6009
6010
@defvr {Window Hook} iconify-window-hook
6011
@defvrx {Window Hook} uniconify-window-hook
6012
@defvrx {Window Hook} shade-window-hook
6013
@defvrx {Window Hook} unshade-window-hook
6014
@defvrx {Window Hook} window-maximized-hook
6015
@defvrx {Window Hook} window-unmaximized-hook
6016
@defvrx {Window Hook} window-depth-change-hook
6017
Called when a window is iconified, uniconified, shaded, unshaded,
6018
maximized, unmaximized, or has its depth changed, respectively.
6019
@end defvr
6020
6021
@defvr {Window Hook} visibility-notify-hook
6022
Called when a window's visibility changes. In addition to the window,
6023
the hook is called one one of the symbols @code{fully-obscured},
6024
@code{partially-obscured}, or @code{unobscured}.
6025
@end defvr
6026
6027
@defvr {Window Hook} place-window-hook
6028
Called the first time a window is mapped, or if the window does not
6029
have a true @code{placed} property. This is an @code{or}-type
6030
hook---the first function that returns non-@code{nil} will terminate
6031
the hook call.
6032
@end defvr
6033
6034
6035
@node Window Motion Hooks, Window Cycling Hooks, Window Mapping Hooks, Standard Hooks
6036
@section Window Motion Hooks
6037
@cindex Window Motion Hooks
6038
@cindex Hooks, Window Motion
6039
6040
@defvr {Window Hook} window-moved-hook
6041
@defvrx {Window Hook} window-resized-hook
6042
Called whenever the window is moved or resized.
6043
6044
This hook is called inside the @code{move-window-to} and
6045
@code{move-resize-window-to} functions, so any operation that moves
6046
the window will trigger this hook. The window motion does not have to
6047
be interactive.
6048
6049
Note that outline window sizing and movement does not use
6050
@code{move-window-to} or @code{move-resize-window-to}, except at the
6051
very end of the operation.
6052
6053
Compare with @code{while-moving-hook} and @code{while-resizing-hook}.
6054
@end defvr
6055
6056
@defvr {Window Hook} before-move-hook
6057
@defvrx {Window Hook} before-resize-hook
6058
Called before starting an interactive move or resize.
6059
@end defvr
6060
6061
@defvr {Window Hook} while-moving-hook
6062
@defvrx {Window Hook} while-resizing-hook
6063
Called during every pointer motion event during a move or resize.
6064
This includes outline window motion. The calls take place before the
6065
window or its outline are actually moved.
6066
6067
Compare with @code{window-moved-hook} and @code{window-resized-hook}.
6068
@end defvr
6069
6070
@defvr {Window Hook} after-move-hook
6071
@defvrx {Window Hook} after-resize-hook
6072
Called after completion of an interactive move or resize. In addition
6073
to the window, the hook is called with a list of symbols indicating how
6074
the window was moved or resized:
6075
@code{horizontal} and @code{vertical} for movement,
6076
@code{right}, @code{left}, @code{bottom} and @code{top} for resizing.
6077
@end defvr
6078
6079
@defvr {Window Hook} before-slide-hook
6080
Called before a window move when using key binding.
6081
@end defvr
6082
6083
6084
@defvr {Hook} after-restacking-hook
6085
Called after any window restacking operation, including (but possibly
6086
not limited to @code{restack-windows}, @code{x-raise-window} and
6087
@code{x-lower-window}. The hook functions take no arguments.
6088
@end defvr
6089
6090
@node Window Cycling Hooks, X Hooks, Window Motion Hooks, Standard Hooks
6091
@section Window Cycling Hooks
6092
@cindex Window Cycling Hooks
6093
@cindex Hooks, Window Cycling
6094
6095
@defvr {Window Hook} after-cycle-step-hook
6096
Called after each step of window cycling. (See @ref{Cycling Between Windows}.)
6097
@end defvr
6098
6099
@node X Hooks, Pointer Motion Hooks, Window Cycling Hooks, Standard Hooks
6100
@section X Hooks
6101
@cindex X Hooks
6102
@cindex Hooks, X
6103
6104
@defvr {Window Hook} configure-request-hook
6105
Called when an X
6106
@code{ConfigureRequest} event is received.
6107
In addition to the window, the hook is called with an association list
6108
of configure request properties. This alist may contain items
6109
@code{(stack . above)}, @code{(stack . below)},
6110
@code{(position . @var{coordinates})},
6111
and @code{(dimensions . @var{dimensions})}.
6112
@end defvr
6113
6114
@defvr {Window Hook} property-notify-hook
6115
Called whenever an X window property (not a Sawfish window property)
6116
changes. In addition to the window, the hook is called with the
6117
atom name and one of the symbols @code{new-value} or @code{deleted}.
6118
@end defvr
6119
6120
@defvr {Window Hook} window-state-change-hook
6121
Called whenver certain window manager hints change for a window.
6122
Currently only @code{urgency} is monitored. The hint is an additional
6123
argument to the hook.
6124
@end defvr
6125
6126
6127
@node Pointer Motion Hooks, Workspace Hooks, X Hooks, Standard Hooks
6128
@section Pointer Motion Hooks
6129
@cindex Pointer Motion Hooks
6130
@cindex Hooks, Pointer Motion
6131
6132
In the hooks below, @var{focus-mode} is one of the symbols
6133
@code{normal}, @code{grab} or @code{ungrab}.
6134
6135
@defvr {Window Hook} enter-notify-hook
6136
@defvrx {Window Hook} enter-frame-part-hook
6137
Called when the pointer enters a window (including the root window).
6138
6139
If the window was part of a frame, then @code{enter-frame-part-hook}
6140
is called with three arguments: the window, the frame part class
6141
(@pxref{Frame Part Classes}), and @var{focus-mode}.
6142
6143
Otherwise @code{enter-notify-hook} is called with two arguments: the
6144
window and @var{focus-mode}.
6145
6146
The root window is considered to be a valid window for this hook.
6147
Sawfish will report entering the root window.
6148
@end defvr
6149
6150
@defvr {Window Hook} leave-notify-hook
6151
@defvrx {Window Hook} leave-frame-part-hook
6152
Called when the pointer leaves a window (including the root window).
6153
6154
If the window was part of a frame, then @code{leave-frame-part-hook}
6155
is called with three arguments: the window, the frame part class
6156
(@pxref{Frame Part Classes}), and @var{focus-mode}.
6157
6158
Otherwise @code{leave-notify-hook} is called with two arguments: the
6159
window and @var{focus-mode}.
6160
6161
The root window is considered to be a valid window for this hook.
6162
Sawfish will report leaving the root window.
6163
@end defvr
6164
6165
@defvr {Window Hook} focus-in-hook
6166
Called when focus gains focus. The hook functions take two arguments:
6167
the window that received focus, and @var{focus-mode}.
6168
6169
If your @var{focus-mode} is set to @code{enter-exit}, your window
6170
focus is tightly bound to your pointer position; focus-related hooks
6171
and enter/leave hooks will be called in lockstep. For other values of
6172
@code{focus-mode}, Sawfish will trigger fewer focus-related hook calls
6173
than enter/leave hook calls.
6174
6175
This hook is never called for the root window, because the root window
6176
never gets focus.
6177
@end defvr
6178
6179
@defvr {Window Hook} focus-out-hook
6180
Called when a window loses focus. The hook functions take two
6181
arguments: the window that lost focus, and @var{focus-mode}.
6182
6183
If your @var{focus-mode} is set to @code{enter-exit}, your window
6184
focus is tightly bound to your pointer position; focus-related hooks
6185
and enter/leave hooks will be called in lockstep. For other values of
6186
@code{focus-mode}, Sawfish will trigger fewer focus-related hook calls
6187
than enter/leave hook calls.
6188
6189
This hook is never called for the root window, because the root window
6190
never gets focus.
6191
@end defvr
6192
6193
6194
@node Workspace Hooks, Startup and Shutdown Hooks, Pointer Motion Hooks, Standard Hooks
6195
@section Workspace Hooks
6196
@cindex Workspace Hooks
6197
@cindex Hooks, Workspace
6198
6199
@defvr {Hook} enter-workspace-hook
6200
@defvrx {Hook} leave-workspace-hook
6201
Called when switching from one workspace to another. This includes
6202
switching caused by adding or removing a workspace. The hook is
6203
called with a @emph{list} containing the workspace in question.
6204
@end defvr
6205
6206
@defvr {Window Hook} add-to-workspace-hook
6207
@defvrx {Window Hook} remove-from-workspace-hook
6208
Called when a window is added or removed from a workspace. In
6209
addition to the window, the hook is called with a @emph{list}
6210
containing the workspace being changed. If the window is in multiple
6211
workspaces, then removing triggers @code{remove-from-workspace-hook}
6212
for each workspace.
6213
@end defvr
6214
6215
@defvr {Hook} workspace-state-change-hook
6216
Called when any aspect of the workspaces change, including adding a
6217
workspace, removing a workspace, moving a workspace, inserting or
6218
removing a window from a workspace, etc. This hook is called with no
6219
arguments, so you should use one of the more specific hooks if
6220
possible.
6221
@end defvr
6222
6223
@defvr {Hook} viewport-resized-hook
6224
Called when the number of rows and columns in each virtual workspace is
6225
changed.
6226
@end defvr
6227
6228
@defvr {Hook} viewport-moved-hook
6229
Called when the origin of the viewport into the virtual workspace is
6230
moved.
6231
@end defvr
6232
6233
@defvr {Hook} enter-flipper-hook
6234
@defvrx {Hook} leave-flipper-hook
6235
When viewport edge-flipping is enabled, these hooks are called as the
6236
pointer enters and leaves the pixel-wide border on the edge of the
6237
screen. They're called with a single argument, one of the symbols
6238
@code{left}, @code{right}, @code{top}, @code{bottom} indicating the
6239
edge in question.
6240
@end defvr
6241
6242
6243
@node Startup and Shutdown Hooks, Other Hooks, Workspace Hooks, Standard Hooks
6244
@section Startup and Shutdown Hooks
6245
@cindex Startup and Shutdown Hooks
6246
@cindex Hooks, Startup and Shutdown
6247
6248
@defvr {Hook} after-initialization-hook
6249
Called after adopting the initial set of windows.
6250
@end defvr
6251
6252
@defvr {Window Hook} remove-window-hook
6253
Called on each window as Sawfish shuts down (possibly for a restart).
6254
The hook functions take no arguments.
6255
@end defvr
6256
6257
@defvr {Hook} before-exit-hook
6258
Called immediately before exiting.
6259
@end defvr
6260
6261
@defvr {Hook} sm-window-save-functions
6262
@defvrx {Hook} sm-restore-window-hook
6263
@defvrx {Hook} sm-after-restore-hook
6264
Session management hooks, @ref{Session Management}.
6265
@end defvr
6266
6267
6268
@node Other Hooks, , Startup and Shutdown Hooks, Standard Hooks
6269
@section Other Hooks
6270
@cindex Other Hooks
6271
@cindex Hooks, Other
6272
6273
@defvr {Hook} gtkrc-changed-hook
6274
When using the @code{gtkrc} module to load the current gtk style
6275
parameters, this hook is called when the style changes.
6276
@end defvr
6277
6278
@defvr {Window Hook} client-message-hook
6279
Called with arguments @code{(@var{window} @var{type}
6280
@var{data-array})}. This is an @code{or}-type hook---the first
6281
function that returns non-@code{nil} will terminate the hook call.
6282
@end defvr
6283
6284
6285
@node Standard Properties, Session Management, Standard Hooks, Top
6286
@chapter Standard Window Properties
6287
@cindex Standard window properties
6288
@cindex Window properties, standard
6289
6290
As described in an earlier section of this manual, each window has a
6291
property list, which may be used to associate arbitrary lisp data with
6292
symbolic keys (@pxref{Window Property Lists}). The following table
6293
documents a subset of the keys currently used.
6294
6295
@vtable @code
6296
6297
@item ignored
6298
When set, the window is ignored in many operations. @xref{Ignored
6299
Windows}.
6300
6301
@item avoid
6302
When set, the window will not be covered by other windows when they
6303
are maximized or newly placed. @xref{Avoided Windows}.
6304
6305
@item workspaces
6306
A list of integers defining the workspaces that the window is a member of, or
6307
nil if the window is sticky.
6308
@xref{Workspaces}.
6309
6310
@item sticky
6311
Whether the window should appear on all workspaces.
6312
6313
@item sticky-viewport
6314
When set, the window will appear in all viewports of its workspace.
6315
6316
@item keymap
6317
An optional, window-local, keymap. @xref{Keymaps}.
6318
6319
@item focus-click-through
6320
When set, and click-to-focus mode is enabled, the click that focuses a
6321
window is passed through to the client window.
6322
6323
@item ignore-window-input-hint
6324
When set the value of the window's input hint is ignored, i.e. the
6325
focus @emph{will} be given to the window when appropriate
6326
6327
@item never-focus
6328
When set the window will @emph{never} be given the input focus
6329
6330
@item focus-when-mapped
6331
Focus the window when it is mapped on to the display.
6332
6333
@item ignore-program-position
6334
When set the window's program-position property is ignored, use this
6335
with windows that set this hint incorrectly.
6336
6337
@item place-mode
6338
When set, the placement mode to be used with this window.
6339
6340
@item placement-weight
6341
When set, the weight assigned to the pixels in this window when doing
6342
fitted window placement.
6343
6344
@item type
6345
The frame-type of the window, or @code{nil}. @xref{Frame Types}.
6346
6347
@item frame-style
6348
The frame style explicitly chosen by the user, or unset. @xref{Frame
6349
Styles}.
6350
6351
@item current-frame-style
6352
The frame style currently used for the window. @xref{Frame Styles}.
6353
6354
@item removed-classes
6355
A list of frame part classes removed from the decorations of this
6356
window. @xref{Removing Frame Parts}.
6357
6358
@item shaded
6359
Is the window shaded? @xref{Shading Windows}.
6360
6361
@item hide-client
6362
Is the client window visible within its frame. Used to implement window
6363
shading.
6364
6365
@item depth
6366
An integer, the layer that the window is a member of. Layer zero is the
6367
depth of ``normal'' windows, negative depths are below this level,
6368
while positive depths are above. @xref{Window Stacking}.
6369
6370
@item placed
6371
Has the window been placed in a position yet? The
6372
@code{place-window-hook} is only called when this is unset.
6373
6374
@item iconified
6375
Is the window iconified? @xref{Iconifying Windows}.
6376
6377
@item gravity
6378
When set, overrides the window gravity field of the window's size
6379
hints. May be one of the symbols: @code{north-west}, @code{north},
6380
@code{north-east}, @code{west}, @code{center}, @code{east},
6381
@code{south-west}, @code{south}, @code{south-east}.
6382
6383
@item fixed-position
6384
When set, the user is not allowed to change the position of this window.
6385
6386
@item client-set-position
6387
When set, the program owning the window has manually moved the window
6388
after it was mapped.
6389
6390
@end vtable
6391
6392
6393
@node Session Management, Low-level X Interface, Standard Properties, Top
6394
@chapter Session Management
6395
@cindex Session management
6396
6397
Sawfish has fully integrated support for the X session management
6398
protocols. Also, this support is extensible to allow all Lisp modules
6399
to save and reload their own window state.
6400
6401
There are two methods of doing this. If the module only wants to save
6402
and restore the values of properties in each window's property list
6403
(i.e. those values set via @code{window-put}), then the following
6404
functions may be used:
6405
6406
@defun sm-add-saved-properties &rest properties
6407
@defunx sm-add-restored-properties &rest properties
6408
Arrange for all symbols @var{properties} to be saved or restored with
6409
the session.
6410
@end defun
6411
6412
@defvar sm-saved-window-properties
6413
@defvarx sm-restored-window-properties
6414
Lists of properties (symbols) to be saved or restored with each
6415
session.
6416
@end defvar
6417
6418
If a Lisp module chooses to use this method it may add a function to
6419
the @code{add-window-hook} to act on the reloaded properties when the
6420
session is reloaded.
6421
6422
For more complex window properties that can't be saved straight from
6423
the window's plist two hooks are available:
6424
6425
@defvar sm-window-save-functions
6426
A list of functions, each of which is called when the state of each
6427
window is saved. Each function is called with a single argument (the
6428
window) and should return a list of alist elements that will be saved
6429
in the state file. (As such, only values with valid read syntaxes may
6430
be included.)
6431
@end defvar
6432
6433
@defvar sm-restore-window-hook
6434
List of functions called when the state of a window is restored. Each
6435
is called with arguments @code{(@var{window} @var{alist})}, where
6436
@var{alist} defines the state saved for the window.
6437
6438
Each function should look for the properties it saved, and then take
6439
any action dependent on the values.
6440
@end defvar
6441
6442
The following hook is also called.
6443
6444
@defvar sm-after-restore-hook
6445
Hook called after loading a saved session.
6446
@end defvar
6447
6448
@defvar sm-save-directory
6449
The directory that will contain all Sawfish sessions. It must be a
6450
string. By default it is @code{"~/.sawfish/sessions"}.
6451
@end defvar
6452
6453
@defvar sm-sloppy-id-matching
6454
When loading sessions, the algorithm that matches saved session data
6455
to running clients requires that if one has a session id, then so must
6456
the other, and they must match. Setting this variable to true turns
6457
that feature off, allowing some broken clients to be session managed.
6458
Defaults to false.
6459
@end defvar
6460
6461
@node Low-level X Interface, FAQ, Session Management, Top
6462
@chapter Low-level X Interface
6463
6464
@menu
6465
* X Server::
6466
* X Windows::
6467
* X Selections::
6468
* X Keysyms::
6469
* X Bitmaps and Pixmaps::
6470
* X Drawing::
6471
* Available X Symbols::
6472
@end menu
6473
6474
6475
@node X Server, X Windows, Low-level X Interface, Low-level X Interface
6476
@section X Server
6477
6478
@defun x-server-timestamp &optional from-server store
6479
Return a recent X server timestamp as an integer.
6480
6481
If @var{from-server} is non-@var{nil}, the timestamp is read directly
6482
from the server; otherwise the most recent timestamp seen by the
6483
window manager (i.e., from an event) is returned.
6484
6485
If @var{store} is true, this becomes the most recent timestamp seen by
6486
the window manager.
6487
@end defun
6488
6489
6490
@node X Windows, X Selections, X Server, Low-level X Interface
6491
@section X Windows
6492
6493
@defun x-create-window (x . y) (width . height) bw attrs &optional event-handler
6494
Create a new X window at @code{(@var{x}, @var{y})} with dimensions
6495
@code{(@var{width}, @var{height})} and border width @var{bw}.
6496
@var{Attrs} is an alist mapping attribute names to values. Allowed
6497
attribute names are @code{background} and @code{border-color}.
6498
@end defun
6499
6500
@defun x-configure-window window attrs
6501
Reconfigure the window associated with @var{window}. @var{Attrs} is
6502
an alist mapping attribute names to values. Allowed attribute names
6503
are @code{x}, @code{y}, @code{width}, @code{height} and
6504
@code{border-width}.
6505
@end defun
6506
6507
@defun x-destroy-window window
6508
Destroy the X window @var{window}.
6509
@end defun
6510
6511
@defun x-map-window window &optional unraised
6512
Map the window associated with @var{window} to the display. If
6513
@var{unraised} is not specified, the window will be mapped at the top
6514
of the window stack.
6515
@end defun
6516
6517
@defun x-unmap-window window
6518
Unmap the window associated with @var{window}.
6519
@end defun
6520
6521
@defun x-window-id window
6522
Return the X window ID (an integer) associated with @var{window}.
6523
@end defun
6524
6525
@defun x-window-p obj
6526
Return @code{t} if @var{obj} is associated with an X window object.
6527
@end defun
6528
6529
@defun x-change-window-attributes window attrs
6530
Set attributes of the window associated with @var{window}.
6531
@var{Attrs} is an alist mapping attribute names (symbols) to values.
6532
Allowed attribute names are @code{background} and @code{border-color}.
6533
@end defun
6534
6535
6536
@node X Selections, X Keysyms, X Windows, Low-level X Interface
6537
@section X Selections
6538
6539
@defun x-get-selection sel
6540
Return the string corresponding to the current value of the X11
6541
selection defined by @var{sel}, or @code{nil} if the selection
6542
currently has no value. @var{Sel} should be one of
6543
@code{PRIMARY}, @code{SECONDARY} or @code{CLIPBOARD}.
6544
@end defun
6545
6546
@defun x-selection-active-p sel
6547
Returns t if the X11 selection defined by the symbol @var{sel} is
6548
available for reading. @var{Sel} should be one of @code{PRIMARY},
6549
@code{SECONDARY} or @code{CLIPBOARD}.
6550
@end defun
6551
6552
6553
@node X Keysyms, X Bitmaps and Pixmaps, X Selections, Low-level X Interface
6554
@section X Keysyms
6555
6556
@defun x-keysym-name ks
6557
Return the Lisp symbol naming the X11 keysym represented by the
6558
integer @var{ks}.
6559
@end defun
6560
6561
@defun x-lookup-keysym name
6562
Return the X11 keysym (an integer) named by the Lisp symbol
6563
@var{name}.
6564
@end defun
6565
6566
6567
@node X Bitmaps and Pixmaps, X Drawing, X Keysyms, Low-level X Interface
6568
@section X Windows
6569
6570
@defun x-bitmap-p
6571
Return @code{t} if @var{arg} is an X-bitmap object.
6572
@end defun
6573
6574
@defun x-create-bitmap (width . height)
6575
Create a bitmap of size @var{width}x@var{height}.
6576
@end defun
6577
6578
@defun x-create-pixmap (width . height)
6579
Create a pixmap of size @var{width}x@var{height}.
6580
@end defun
6581
6582
@defun x-destroy-drawable drawable
6583
Destroy the X drawable @var{drawable}.
6584
@end defun
6585
6586
@defun x-drawable-height drawable
6587
Return the height in pixels of @var{drawable}.
6588
@end defun
6589
6590
@defun x-drawable-id drawable
6591
Return the X11 drawable-ID (an integer) associated with
6592
@var{drawable}.
6593
@end defun
6594
6595
@defun x-drawable-p obj
6596
Return @code{t} if @var{obj} is an X drawable object.
6597
@end defun
6598
6599
@defun x-drawable-width drawable
6600
Return the width in pixels of @var{drawable}.
6601
@end defun
6602
6603
@defun x-grab-image-from-drawable drawable mask
6604
Return a new image object copied from @var{drawable}. @var{Mask} is a
6605
stencil mask for the image; black pixels in @var{mask} become
6606
transparent in the returned image.
6607
@end defun
6608
6609
@defun x-pixmap-p obj
6610
Return @code{t} if @var{obj} is an X pixmap object.
6611
@end defun
6612
6613
6614
@node X Drawing, Available X Symbols, X Bitmaps and Pixmaps, Low-level X Interface
6615
@section X Windows
6616
6617
@defun x-clear-window window
6618
Clear the window associated with @var{window} to its background color.
6619
@end defun
6620
6621
@defun x-copy-area window gc (x . y) (width . height) (dest-x . dest-y)
6622
Copy a region of @var{window} with top-left corner @code{(@var{x},
6623
@var{y})} and dimensions @code{(@var{width}, @var{height})} to the
6624
position @code{(@var{dest-x}, @var{dest-y})} using @var{gc}.
6625
@end defun
6626
6627
@defun x-create-gc window attrs
6628
Create a new GC for the specified window @var{window}. @var{Attrs} is
6629
an alist mapping attributes to values. Allowed attribute names are
6630
@code{foreground}, @code{background}, @code{line-width},
6631
@code{line-style}, @code{cap-style}, @code{join-style},
6632
@code{fill-style}, @code{fill-rule}, @code{arc-mode}, @code{tile},
6633
@code{stipple}, @code{ts-x-origin}, @code{ts-y-origin},
6634
@code{clip-mask}, @code{clip-x-origin}, @code{clip-y-origin} and
6635
@code{function}.
6636
@end defun
6637
6638
@defun x-change-gc gc attrs
6639
Sets attributes of the X Graphical Context. @var{Attrs} is an
6640
association list of attribute names and values. Allowed attribute
6641
names are @code{foreground}, @code{background}, @code{line-width},
6642
@code{line-style}, @code{cap-style}, @code{join-style},
6643
@code{fill-style}, @code{fill-rule}, @code{arc-mode}, @code{tile},
6644
@code{stipple}, @code{ts-x-origin}, @code{ts-y-origin},
6645
@code{clip-mask}, @code{clip-x-origin}, @code{clip-y-origin} and
6646
@code{function}.
6647
@end defun
6648
6649
@defun x-create-root-xor-gc
6650
Create a graphics context specialized for XOR-ing onto the root
6651
window. This is used for drawing outlines for window movement.
6652
@end defun
6653
6654
@defun x-destroy-gc gc
6655
Destroy the X graphics context @var{gc}.
6656
@end defun
6657
6658
@defun x-draw-arc window gc (x . y) (width . height) (angle1 . angle2)
6659
Draw a single circular or elliptical arc in @var{window} using the
6660
graphics context @var{gc}. The center of the circle or ellipse is the
6661
center of an imaginary rectangle at @code{(@var{x}, @var{y})}. The
6662
major and minor axes are the @code{(@var{width}, @var{height})} of
6663
that rectangle. The arc sweeps from @var{angle1} to @var{angle2};
6664
positive angles are rotated counter-clockwise from zero, and negative
6665
angles are rotated clockwise from zero.
6666
@end defun
6667
6668
@defun x-draw-image image window (x . y) &optional (width . height)
6669
Render the image object @var{image} in @var{window} at position
6670
@code{(@var{x}, @var{y})}. If @var{width} and @var{height} are
6671
defined the image is first scaled to these dimensions; otherwise it is
6672
drawn using its natural dimensions.
6673
@end defun
6674
6675
@defun x-draw-line window gc (x1 . y1) (x2 . y2)
6676
Draw a line from @code{(@var{x1}, @var{y1})} to @code{(@var{x2},
6677
@var{y2})} in @var{window} using the graphics context @var{gc}.
6678
@end defun
6679
6680
@defun x-draw-rectangle window gc (x . y) (width . height)
6681
Draw a rectangle with its top-left corner at @code{(@var{x}, @var{y})}
6682
and dimensions @code{(@var{width}, @var{height})} in @var{window}
6683
using the graphics context @var{gc}.
6684
@end defun
6685
6686
@defun x-draw-string window gc (x . y) string &optional font
6687
Draw the specified string at @code{(@var{x}, @var{y})} in @var{window}
6688
using the graphics context @var{gc}. If @var{font} is specified use
6689
that font.
6690
@end defun
6691
6692
@defun x-fill-arc window gc (x . y) (width . height) (angle1 . angle2)
6693
Draw a single filled circular or elliptical arc in @var{window} using
6694
the graphics context @var{gc}. The center of the circle or ellipse is
6695
the center of an imaginary rectangle at @code{(@var{x}, @var{y})}.
6696
The major and minor axes are the @code{(@var{width}, @var{height})} of
6697
that rectangle. The arc sweeps from @var{angle1} to @var{angle2};
6698
positive angles are rotated counter-clockwise from zero, and negative
6699
angles are rotated clockwise from zero.
6700
@end defun
6701
6702
@defun x-fill-polygon window gc points &optional draw-mode
6703
Draw a single filled polygon in @var{window} using
6704
the graphics context @var{gc}. @var{Points} is a list of
6705
@code{(@var{x}, @var{y})} pairs that defines the polygon vertices.
6706
6707
@var{Draw-mode} is a hint to the X server on how to draw the polygon;
6708
if supplied, it should be one of the symbols @code{convex} or
6709
@code{non-convex}. The default mode is ``Convex''.
6710
@end defun
6711
6712
@defun x-fill-rectangle window gc (x . y) (width . height)
6713
Draw a filled rectangle with its top-left corner at @code{(@var{x},
6714
@var{y})} and dimensions @code{(@var{width}, @var{height})} in
6715
@var{window} using the graphics context @var{gc}.
6716
@end defun
6717
6718
@defun x-gc-p obj
6719
Returns @code{t} if @var{obj} is an X GraphicsContext object.
6720
@end defun
6721
6722
@defun x-gc-set-dashes gc pixels-list &optional offset
6723
Set the dash style of graphics context @var{gc} to the value of
6724
@var{pixels-list}. @var{Pixels-list} is a list of cons cells
6725
@code{((pixels-on . pixels-off) ...)} indicating runs of on and off
6726
pixels in a dash segment. If @var{offset} is given, this should be an
6727
integer indicating the number of pixels to offset the dashes.
6728
@end defun
6729
6730
@defun x-window-back-buffer window
6731
Return the X object ID (an integer) for the back buffer associated
6732
with @var{window}. If no such back buffer exists, the function will
6733
attempt to create one.
6734
6735
If the function is unable to find or create a back buffer (possibly
6736
because the X server does not support them), it returns the window's
6737
own ID.
6738
@end defun
6739
6740
@defun x-window-swap-buffers window
6741
Swap the fore and back buffers of the window associated with
6742
@var{window}. If the X server does not support double buffers, the
6743
function quietly does nothing.
6744
@end defun
6745
6746
6747
@node Available X Symbols, , X Drawing, Low-level X Interface
6748
@section Available X Symbols
6749
6750
The following symbols can be used where X window attributes are
6751
expected:
6752
6753
@table @code
6754
@item border-width
6755
@itemx border-color
6756
@itemx expose
6757
@itemx convex
6758
@itemx non-convex
6759
@itemx line-width
6760
@itemx line-style
6761
@itemx cap-style
6762
@itemx join-style
6763
@itemx fill-style
6764
@itemx fill-rule
6765
@itemx arc-mode
6766
@itemx tile
6767
@itemx stipple
6768
@itemx ts-x-origin
6769
@itemx ts-y-origin
6770
@itemx clip-mask
6771
@itemx clip-x-origin
6772
@itemx clip-y-origin
6773
@end table
6774
6775
The following symbols can be used where X window attribute values are
6776
expected:
6777
6778
@table @code
6779
@item line-solid
6780
@itemx line-on-off-dash
6781
@itemx line-double-dash
6782
@itemx cap-not-last
6783
@itemx cap-butt
6784
@itemx cap-round
6785
@itemx cap-projecting
6786
@itemx join-miter
6787
@itemx join-round
6788
@itemx join-bevel
6789
@itemx fill-solid
6790
@itemx fill-tiled
6791
@itemx fill-stippled
6792
@itemx fill-opaque-stippled
6793
@itemx even-odd-rule
6794
@itemx winding-rule
6795
@itemx arc-chord
6796
@itemx arc-pie-slice
6797
@itemx function
6798
@itemx clear
6799
@itemx and
6800
@itemx and-reverse
6801
@itemx copy
6802
@itemx and-inverted
6803
@itemx no-op
6804
@itemx xor
6805
@itemx or
6806
@itemx nor
6807
@itemx equiv
6808
@itemx invert
6809
@itemx or-reverse
6810
@itemx copy-inverted
6811
@itemx or-inverted
6812
@itemx nand
6813
@itemx set
6814
@end table
6815
6816
6817
@node FAQ, Function Index, Low-level X Interface, Top
6818
6819
@include faq.texi
6820
6821
6822
@node Function Index, Variable Index, FAQ, Top
6823
@unnumbered Function Index
6824
6825
@printindex fn
6826
6827
6828
@node Variable Index, Concept Index, Function Index, Top
6829
@unnumbered Variable Index
6830
6831
@printindex vr
6832
6833
6834
@node Concept Index, , Variable Index, Top
6835
@unnumbered Concept Index
6836
6837
@printindex cp
6838
6839
6840
@contents
6841
@bye
Loggerhead is a web-based interface for Breezy
Version: 2.0.1