1 This is ../info/lispref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
55 49.1.3 Face Properties
56 ----------------------
58 You can examine and modify the properties of an existing face with the
61 The following symbols have predefined meanings:
64 The foreground color of the face.
67 The background color of the face.
70 The font used to display text covered by this face.
73 The display table of the face.
76 The pixmap displayed in the background of the face. Only used by
77 faces on GUI devices, currently X11, GTK, and Microsoft Windows.
80 Underline all text covered by this face.
83 Highlight all text covered by this face. Only used by faces on TTY
87 Dim all text covered by this face. Only used by faces on TTY
91 Blink all text covered by this face. Only used by faces on TTY
95 Reverse the foreground and background colors. Only used by faces
99 Description of what the face's normal use is. NOTE: This is not a
100 specifier, unlike all the other built-in properties, and cannot
101 contain locale-specific values.
103 -- Function: set-face-property face property value &optional locale
105 This function changes a property of a FACE.
107 For built-in properties, the actual value of the property is a
108 specifier and you cannot change this; but you can change the
109 specifications within the specifier, and that is what this
110 function will do. For user-defined properties, you can use this
111 function to either change the actual value of the property or, if
112 this value is a specifier, change the specifications within it.
114 If PROPERTY is a built-in property, the specifications to be added
115 to this property can be supplied in many different ways:
117 If VALUE is a simple instantiator (e.g. a string naming a
118 font or color) or a list of instantiators, then the
119 instantiator(s) will be added as a specification of the
120 property for the given LOCALE (which defaults to `global' if
123 If VALUE is a list of specifications (each of which is a cons
124 of a locale and a list of instantiators), then LOCALE must be
125 `nil' (it does not make sense to explicitly specify a locale
126 in this case), and specifications will be added as given.
128 If VALUE is a specifier (as would be returned by
129 `face-property' if no LOCALE argument is given), then some or
130 all of the specifications in the specifier will be added to
131 the property. In this case, the function is really
132 equivalent to `copy-specifier' and LOCALE has the same
133 semantics (if it is a particular locale, the specification
134 for the locale will be copied; if a locale type,
135 specifications for all locales of that type will be copied;
136 if `nil' or `all', then all specifications will be copied).
138 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
139 `append', `remove-tag-set-prepend', `remove-tag-set-append',
140 `remove-locale', `remove-locale-type', or `remove-all'. See
141 `copy-specifier' and `add-spec-to-specifier' for a description of
142 what each of these means. Most of the time, you do not need to
143 worry about this argument; the default behavior usually is fine.
145 In general, it is OK to pass an instance object (e.g. as returned
146 by `face-property-instance') as an instantiator in place of an
147 actual instantiator. In such a case, the instantiator used to
148 create that instance object will be used (for example, if you set
149 a font-instance object as the value of the `font' property, then
150 the font name used to create that object will be used instead).
151 If some cases, however, doing this conversion does not make sense,
152 and this will be noted in the documentation for particular types
155 If PROPERTY is not a built-in property, then this function will
156 simply set its value if LOCALE is `nil'. However, if LOCALE is
157 given, then this function will attempt to add VALUE as the
158 instantiator for the given LOCALE, using `add-spec-to-specifier'.
159 If the value of the property is not a specifier, it will
160 automatically be converted into a `generic' specifier.
162 -- Function: remove-face-property face property &optional locale
164 This function removes a property of a FACE.
166 For built-in properties, this is analogous to `remove-specifier'.
167 For more information, *Note Other Specification Functions::.
169 When PROPERTY is not a built-in property, this function will just
170 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
171 is other than that, this function will attempt to remove VALUE as
172 the instantiator for the given LOCALE with `remove-specifier'. If
173 the value of the property is not a specifier, it will be converted
174 into a `generic' specifier automatically.
176 -- Function: face-property face property &optional locale tag-set
178 This function returns FACE's value of the given PROPERTY.
180 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
181 returned. For built-in properties, this will be a specifier
182 object of a type appropriate to the property (e.g. a font or color
183 specifier). For other properties, this could be anything.
185 If LOCALE is supplied, then instead of returning the actual value,
186 the specification(s) for the given locale or locale type will be
187 returned. This will only work if the actual value of PROPERTY is
188 a specifier (this will always be the case for built-in properties,
189 but not or not may apply to user-defined properties). If the
190 actual value of PROPERTY is not a specifier, this value will
191 simply be returned regardless of LOCALE.
193 The return value will be a list of instantiators (e.g. strings
194 specifying a font or color name), or a list of specifications,
195 each of which is a cons of a locale and a list of instantiators.
196 Specifically, if LOCALE is a particular locale (a buffer, window,
197 frame, device, or `global'), a list of instantiators for that
198 locale will be returned. Otherwise, if LOCALE is a locale type
199 (one of the symbols `buffer', `window', `frame', or `device'), the
200 specifications for all locales of that type will be returned.
201 Finally, if LOCALE is `all', the specifications for all locales of
202 all types will be returned.
204 The specifications in a specifier determine what the value of
205 PROPERTY will be in a particular "domain" or set of circumstances,
206 which is typically a particular Emacs window along with the buffer
207 it contains and the frame and device it lies within. The value is
208 derived from the instantiator associated with the most specific
209 locale (in the order buffer, window, frame, device, and `global')
210 that matches the domain in question. In other words, given a
211 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
212 will first be searched for a specification whose locale is the
213 buffer contained within that window; then for a specification
214 whose locale is the window itself; then for a specification whose
215 locale is the frame that the window is contained within; etc. The
216 first instantiator that is valid for the domain (usually this
217 means that the instantiator is recognized by the device [i.e. the
218 X server or TTY device] that the domain is on). The function
219 `face-property-instance' actually does all this, and is used to
220 determine how to display the face.
222 -- Function: face-property-instance face property &optional domain
224 This function returns the instance of FACE's PROPERTY in the
227 Under most circumstances, DOMAIN will be a particular window, and
228 the returned instance describes how the specified property
229 actually is displayed for that window and the particular buffer in
230 it. Note that this may not be the same as how the property
231 appears when the buffer is displayed in a different window or
232 frame, or how the property appears in the same window if you
233 switch to another buffer in that window; and in those cases, the
234 returned instance would be different.
236 The returned instance will typically be a color-instance,
237 font-instance, or pixmap-instance object, and you can query it
238 using the appropriate object-specific functions. For example, you
239 could use `color-instance-rgb-components' to find out the RGB
240 (red, green, and blue) components of how the `background' property
241 of the `highlight' face is displayed in a particular window. The
242 results might be different from the results you would get for
243 another window (perhaps the user specified a different color for
244 the frame that window is on; or perhaps the same color was
245 specified but the window is on a different X server, and that X
246 server has different RGB values for the color from this one).
248 DOMAIN defaults to the selected window if omitted.
250 DOMAIN can be a frame or device, instead of a window. The value
251 returned for a such a domain is used in special circumstances when
252 a more specific domain does not apply; for example, a frame value
253 might be used for coloring a toolbar, which is conceptually
254 attached to a frame rather than a particular window. The value is
255 also useful in determining what the value would be for a
256 particular window within the frame or device, if it is not
257 overridden by a more specific specification.
259 If PROPERTY does not name a built-in property, its value will
260 simply be returned unless it is a specifier object, in which case
261 it will be instanced using `specifier-instance'.
263 Optional arguments DEFAULT and NO-FALLBACK are the same as in
264 `specifier-instance'. *Note Specifiers::.
267 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
269 49.1.4 Face Convenience Functions
270 ---------------------------------
272 -- Command: set-face-foreground face color &optional locale tag-set
274 -- Command: set-face-background face color &optional locale tag-set
276 These functions set the foreground (respectively, background)
277 color of face FACE to COLOR. The argument COLOR should be a
278 string (the name of a color) or a color object as returned by
279 `make-color' (*note Colors::).
281 -- Command: set-face-background-pixmap face pixmap &optional locale
283 This function sets the background pixmap of face FACE to PIXMAP.
284 The argument PIXMAP should be a string (the name of a bitmap or
285 pixmap file; the directories listed in the variable
286 `x-bitmap-file-path' will be searched) or a glyph object as
287 returned by `make-glyph' (*note Glyphs::). The argument may also
288 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
289 are the size in pixels, and DATA is a string, containing the raw
292 Similarly to how the glyph's image specifier works *Note Creating
293 Glyphs::, you don't create your own image specifier, but rather add
294 specifications to the existing one. Note that the image instance
295 that is generated in order to actually display the background
296 pixmap is of type `mono-pixmap', meaning that it's a two-color
297 image and the foreground and background of the image get filled in
298 with the corresponding colors from the face. (#### Is this still
301 -- Command: set-face-font face font &optional locale tag-set how-to-add
302 This function sets the font of face FACE. The argument FONT
303 should be a string or a font object as returned by `make-font'
306 -- Command: set-face-underline-p face underline-p &optional locale
308 This function sets the underline property of face FACE.
310 -- Function: face-foreground face &optional locale tag-set exact-p
311 -- Function: face-background face &optional locale tag-set exact-p
312 These functions return the foreground (respectively, background)
313 color specifier of face FACE. *Note Colors::.
315 -- Function: face-background-pixmap face &optional locale tag-set
317 This function returns the background-pixmap image specifier of face
320 -- Function: face-font face &optional locale tag-set exact-p
321 This function returns the font specifier of face FACE. (Note:
322 This is not the same as the function `face-font' in FSF Emacs.)
326 -- Function: face-font-name face &optional domain
327 This function returns the name of the font of face FACE, or `nil'
328 if it is unspecified. This is basically equivalent to `(font-name
329 (face-font FACE) DOMAIN)' except that it does not cause an error
330 if FACE's font is `nil'. (This function is named `face-font' in
333 -- Function: face-underline-p face &optional locale
334 This function returns the underline property of face FACE.
336 -- Function: face-foreground-instance face &optional domain
337 -- Function: face-background-instance face &optional domain
338 These functions return the foreground (respectively, background)
339 color specifier of face FACE. *Note Colors::.
341 -- Function: face-background-pixmap-instance face &optional domain
342 This function return the background-pixmap glyph object of face
345 -- Function: face-font-instance face &optional domain
346 This function returns the font specifier of face FACE. *Note
350 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
352 49.1.5 Other Face Display Functions
353 -----------------------------------
355 -- Command: invert-face face &optional locale
356 Swap the foreground and background colors of face FACE. If the
357 face doesn't specify both foreground and background, then its
358 foreground and background are set to the default background and
361 -- Function: face-equal face1 face2 &optional domain
362 This returns `t' if the faces FACE1 and FACE2 will display in the
363 same way. DOMAIN is as in `face-property-instance'.
365 -- Function: face-differs-from-default-p face &optional domain
366 This returns `t' if the face FACE displays differently from the
367 default face. DOMAIN is as in `face-property-instance'.
370 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
375 This section describes how to work with font specifier and font
376 instance objects, which encapsulate fonts in the window system.
380 * Font Specifiers:: Specifying how a font will appear.
381 * Font Instances:: What a font specifier gets instanced as.
382 * Font Instance Names:: The name of a font instance.
383 * Font Instance Size:: The size of a font instance.
384 * Font Instance Characteristics:: Display characteristics of font instances.
385 * Font Convenience Functions:: Convenience functions that automatically
386 instance and retrieve the properties
390 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
392 49.2.1 Font Specifiers
393 ----------------------
395 -- Function: font-specifier-p object
396 This predicate returns `t' if OBJECT is a font specifier, and
399 -- Function: make-font-specifier spec-list
400 Return a new `font' specifier object with the given specification
401 list. SPEC-LIST can be a list of specifications (each of which is
402 a cons of a locale and a list of instantiators), a single
403 instantiator, or a list of instantiators. *Note Specifiers::, for
404 more information about specifiers.
406 Valid instantiators for font specifiers are:
408 * A string naming a font (e.g. under X this might be
409 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
410 14-point upright medium-weight Courier font).
412 * A font instance (use that instance directly if the device
413 matches, or use the string that generated it).
415 * A vector of no elements (only on TTY's; this means to set no
416 font at all, thus using the "natural" font of the terminal's
419 * A vector of one element (a face to inherit from).
422 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
424 49.2.2 Font Instances
425 ---------------------
427 -- Function: font-instance-p object
428 This predicate returns `t' if OBJECT is a font instance, and `nil'
431 -- Function: make-font-instance name &optional device noerror
432 This function creates a new font-instance object of the specified
433 name. DEVICE specifies the device this object applies to and
434 defaults to the selected device. An error is signalled if the
435 font is unknown or cannot be allocated; however, if NOERROR is
436 non-`nil', `nil' is simply returned in this case.
438 The returned object is a normal, first-class lisp object. The way
439 you "deallocate" the font is the way you deallocate any other lisp
440 object: you drop all pointers to it and allow it to be garbage
441 collected. When these objects are GCed, the underlying X data is
445 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
447 49.2.3 Font Instance Names
448 --------------------------
450 -- Function: list-fonts pattern &optional device
451 This function returns a list of font names matching the given
452 pattern. DEVICE specifies which device to search for names, and
453 defaults to the currently selected device.
455 -- Function: font-instance-name font-instance
456 This function returns the name used to allocate FONT-INSTANCE.
458 -- Function: font-instance-truename font-instance
459 This function returns the canonical name of the given font
460 instance. Font names are patterns which may match any number of
461 fonts, of which the first found is used. This returns an
462 unambiguous name for that font (but not necessarily its only
466 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
468 49.2.4 Font Instance Size
469 -------------------------
471 -- Function: x-font-size font
472 This function returns the nominal size of the given font. This is
473 done by parsing its name, so it's likely to lose. X fonts can be
474 specified (by the user) in either pixels or 10ths of points, and
475 this returns the first one it finds, so you have to decide which
476 units the returned value is measured in yourself ...
478 -- Function: x-find-larger-font font &optional device
479 This function loads a new, slightly larger version of the given
480 font (or font name). Returns the font if it succeeds, `nil'
481 otherwise. If scalable fonts are available, this returns a font
482 which is 1 point larger. Otherwise, it returns the next larger
483 version of this font that is defined.
485 -- Function: x-find-smaller-font font &optional device
486 This function loads a new, slightly smaller version of the given
487 font (or font name). Returns the font if it succeeds, `nil'
488 otherwise. If scalable fonts are available, this returns a font
489 which is 1 point smaller. Otherwise, it returns the next smaller
490 version of this font that is defined.
493 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
495 49.2.5 Font Instance Characteristics
496 ------------------------------------
498 -- Function: font-instance-properties font-instance
499 This function returns the properties (an alist or `nil') of
502 -- Function: x-make-font-bold font &optional device
503 Given an X font specification, this attempts to make a "bold" font.
504 If it fails, it returns `nil'.
506 -- Function: x-make-font-unbold font &optional device
507 Given an X font specification, this attempts to make a non-bold
508 font. If it fails, it returns `nil'.
510 -- Function: x-make-font-italic font &optional device
511 Given an X font specification, this attempts to make an "italic"
512 font. If it fails, it returns `nil'.
514 -- Function: x-make-font-unitalic font &optional device
515 Given an X font specification, this attempts to make a non-italic
516 font. If it fails, it returns `nil'.
518 -- Function: x-make-font-bold-italic font &optional device
519 Given an X font specification, this attempts to make a
520 "bold-italic" font. If it fails, it returns `nil'.
523 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
525 49.2.6 Font Convenience Functions
526 ---------------------------------
528 -- Function: font-name font &optional domain
529 This function returns the name of the FONT in the specified
530 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
531 is normally a window and defaults to the selected window if
532 omitted. This is equivalent to using `specifier-instance' and
533 applying `font-instance-name' to the result.
535 -- Function: font-truename font &optional domain
536 This function returns the truename of the FONT in the specified
537 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
538 is normally a window and defaults to the selected window if
539 omitted. This is equivalent to using `specifier-instance' and
540 applying `font-instance-truename' to the result.
542 -- Function: font-properties font &optional domain
543 This function returns the properties of the FONT in the specified
544 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
545 is normally a window and defaults to the selected window if
546 omitted. This is equivalent to using `specifier-instance' and
547 applying `font-instance-properties' to the result.
550 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
557 * Color Specifiers:: Specifying how a color will appear.
558 * Color Instances:: What a color specifier gets instanced as.
559 * Color Instance Properties:: Properties of color instances.
560 * Color Convenience Functions:: Convenience functions that automatically
561 instance and retrieve the properties
562 of a color specifier.
565 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
567 49.3.1 Color Specifiers
568 -----------------------
570 -- Function: color-specifier-p object
571 This function returns non-`nil' if OBJECT is a color specifier.
573 -- Function: make-color-specifier spec-list
574 Return a new `color' specifier object with the given specification
575 list. SPEC-LIST can be a list of specifications (each of which is
576 a cons of a locale and a list of instantiators), a single
577 instantiator, or a list of instantiators. *Note Specifiers::, for
578 a detailed description of how specifiers work.
580 Valid instantiators for color specifiers are:
582 * A string naming a color (e.g. under X this might be
583 "lightseagreen2" or "#F534B2").
585 * A color instance (use that instance directly if the device
586 matches, or use the string that generated it).
588 * A vector of no elements (only on TTY's; this means to set no
589 color at all, thus using the "natural" color of the
592 * A vector of one or two elements: a face to inherit from, and
593 optionally a symbol naming which property of that face to
594 inherit, either `foreground' or `background' (if omitted,
595 defaults to the same property that this color specifier is
596 used for; if this specifier is not part of a face, the
597 instantiator would not be valid).
599 -- Function: make-face-boolean-specifier spec-list
600 Return a new `face-boolean' specifier object with the given spec
601 list. SPEC-LIST can be a list of specifications (each of which is
602 a cons of a locale and a list of instantiators), a single
603 instantiator, or a list of instantiators. *Note Specifiers::, for
604 a detailed description of how specifiers work.
606 Valid instantiators for face-boolean specifiers are
610 * A vector of two or three elements: a face to inherit from,
611 optionally a symbol naming the property of that face to
612 inherit from (if omitted, defaults to the same property that
613 this face-boolean specifier is used for; if this specifier is
614 not part of a face, the instantiator would not be valid), and
615 optionally a value which, if non-`nil', means to invert the
616 sense of the inherited property.
620 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
622 49.3.2 Color Instances
623 ----------------------
625 A "color-instance object" is an object describing the way a color
626 specifier is instanced in a particular domain. Functions such as
627 `face-background-instance' return a color-instance object. For example,
629 (face-background-instance 'default (next-window))
630 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
632 The color-instance object returned describes the way the background
633 color of the `default' face is displayed in the next window after the
636 -- Function: color-instance-p object
637 This function returns non-`nil' if OBJECT is a color-instance.
640 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
642 49.3.3 Color Instance Properties
643 --------------------------------
645 -- Function: color-instance-name color-instance
646 This function returns the name used to allocate COLOR-INSTANCE.
648 -- Function: color-instance-rgb-components color-instance
649 This function returns a three element list containing the red,
650 green, and blue color components of COLOR-INSTANCE.
652 (color-instance-rgb-components
653 (face-background-instance 'default (next-window)))
654 => (65535 58596 46517)
657 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
659 49.3.4 Color Convenience Functions
660 ----------------------------------
662 -- Function: color-name color &optional domain
663 This function returns the name of the COLOR in the specified
664 DOMAIN, if any. COLOR should be a color specifier object and
665 DOMAIN is normally a window and defaults to the selected window if
666 omitted. This is equivalent to using `specifier-instance' and
667 applying `color-instance-name' to the result.
669 -- Function: color-rgb-components color &optional domain
670 This function returns the RGB components of the COLOR in the
671 specified DOMAIN, if any. COLOR should be a color specifier
672 object and DOMAIN is normally a window and defaults to the
673 selected window if omitted. This is equivalent to using
674 `specifier-instance' and applying `color-instance-rgb-components'
677 (color-rgb-components (face-background 'default (next-window)))
678 => (65535 58596 46517)
681 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
686 A "glyph" is an object that is used for pixmaps, widgets, and images of
687 all sorts, as well as for things that "act" like pixmaps, such as
688 non-textual strings ("annotations") displayed in a buffer or in the
689 margins. It is used in begin-glyphs and end-glyphs attached to
690 extents, marginal and textual annotations, overlay arrows
691 (`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
692 icons, truncation and continuation markers, and the like. Basically,
693 any place there is an image or something that acts like an image, there
694 will be a glyph object representing it.
696 -- Function: glyphp object
697 This function returns `t' if OBJECT is a glyph.
701 * Glyph Intro:: Glyphs are abstract image specifications.
702 * Images:: Specifying the appearance of glyphs.
703 * Using Glyphs:: Creating and displaying glyphs.
704 * Manipulating Glyphs:: Getting and setting glyph properties.
705 * Glyph Examples:: Examples of how to work with glyphs.
708 File: lispref.info, Node: Glyph Intro, Next: Images, Up: Glyphs
710 50.1 Glyph Introduction
711 =======================
713 In XEmacs, "glyph" does *not* refer to a single unit of textual display
714 (the XEmacs term for that is "rune", and runes are confined to the
715 internal implementation of redisplay), but rather is an object
716 encapsulating a graphical element, such as an image or widget (an
717 active GUI element such as a button or text entry field; X11 calls this
718 a "widget", while MS Windows uses the term "control"). This graphical
719 element could appear in a buffer, a margin, a gutter, or a toolbar, or
720 even externally to XEmacs as a mouse pointer or an icon, for example.
722 On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is
723 not "just" an image. The actual image that is displayed (as opposed to
724 its position or clipping) is defined by an "image specifier" object
725 contained within the glyph. The separation between an image specifier
726 object and a glyph object is made because the glyph includes other
727 properties than just the actual image: e.g. the face it is displayed in,
728 the alignment of the image, _etc_. Also, an image specifier is used in
729 at least one place in XEmacs in lieu of a glyph, namely the backing
732 An image specifier is used because glyphs often have locale-specific
733 semantics. The most important example is semantics determined by the
734 display device: you can't usefully display a JPEG on stdout, or a color
735 image on a monochrome display. But because the image property is a
736 specifier in XEmacs, you can specify that a given glyph appear as a
737 monochrome image on monochrome displays, a color image on color
738 displays, and as a string on TTYs. (Specifying a string for the `tty'
739 device locale would give behavior like the `ALT' attribute of an `IMG'
740 element in HTML.) Another is semantics determined by the buffer or
741 mode. (Unfortunately, currently there are no compelling examples of
744 All this means that only one global glyph needs to exist for a
745 particular purpose (e.g. the icon used to represent an iconified frame,
746 the mouse pointer used over particular areas of a frame, etc.). Often
747 you need not (and should not!) create your own glyph, but rather modify
750 In working with glyphs it is important to keep in mind the
751 distinction between a locale and a domain. A "locale" is specified by
752 the programmer, and is an abstract link between a specification (for a
753 glyph, its visual appearance) and a displayable object. The displayable
754 object may be a buffer or a window, or an object containing buffers or
755 windows such as frame, device, or console. A "domain" is an actual
756 display context, which must be concrete enough to enable XEmacs to
757 identify the device type. (Buffers may be displayed in windows on
758 different devices, even simultaneously, so a buffer cannot be a domain.
759 Similarly, the global locale cannot be a domain.) *Note Specifiers::,
760 for more information about specifier locales and domains.
763 File: lispref.info, Node: Images, Next: Using Glyphs, Prev: Glyph Intro, Up: Glyphs
770 * Image Specifiers:: Specifying an image's appearance.
771 * Image Instantiator Conversion:: Lazy realization of graphics.
772 * Image Instantiator Formats:: A catalog of image descriptors.
773 * Image Instances:: Classes of graphical objects.
776 File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
778 50.2.1 Image Specifiers
779 -----------------------
781 An image specifier is a description of the actual graphical realization
782 of a glyph. For example, a typical image description is _the file
783 system path to a PNG file_. Since redisplay doesn't know about files,
784 and in any case the image may need to be manipulated (_e.g._, a face's
785 background pixmap must be clipped and tiled), the PNG file must be
786 converted internally to a window system bitmap or pixmap object. We
787 describe this process by writing that when XEmacs displays the image,
788 it "instantiates" the "image instantiator" into an "image instance".
789 Image instances are an internal object type (similar to font instances
790 and color instances), describing how the image appears in a particular
791 domain. On the other hand, image instantiators, which are just
792 descriptions of how the image should appear, are represented using Lisp
795 Furthermore the graphical realization will vary, and for some devices
796 may not even be a bitmapped graphic. These variations may be controlled
797 by the program by specifying different "image instantiators" in
798 different locales. This is implemented with an "image specifier", a
799 specifier whose specifications are image instantiators.
801 Image specifiers are rarely if ever found by themselves. However, an
802 image specifier results from calling `glyph-image' on a glyph, or
803 retrieving the `background-pixmap' property of a face, and you can
804 check if some random object is an image specifier.
806 -- Function: image-specifier-p object
807 This function returns non-`nil' if OBJECT is an image specifier.
809 -- Function: make-image-specifier spec-list
810 This function creates a new image specifier object and initializes
811 it according to SPEC-LIST. *Note Specifiers::.
813 This function exists mainly for completeness. In practice, you
814 rarely, if ever, need to actually create an image specifier. Instead,
815 they are implicitly created by the initialization of glyphs and faces,
816 and the specifier member of these objects cannot be changed after
817 initialization; you may only set the specifications it contains.
819 Image instantiators come in many formats: `xbm', `xpm', `gif',
820 `jpeg', etc. These denote the format of the data describing the image.
821 The resulting image instances also come in many types--`mono-pixmap',
822 `color-pixmap', `text', `pointer', etc. This refers to the behavior of
823 the image and the sorts of places it can appear. (For example, a
824 color-pixmap image has fixed colors specified for it, while a
825 mono-pixmap image comes in two unspecified shades "foreground" and
826 "background" that are determined from the face of the glyph or
827 surrounding text; a text image appears as a string of text and has an
828 unspecified foreground, background, and font; a pointer image behaves
829 like a mono-pixmap image but can only be used as a mouse pointer
830 [mono-pixmap images cannot be used as mouse pointers]; etc.)
832 It is important to keep the distinction between image instantiator
833 format and image instance type in mind. Typically, a given image
834 instantiator format can result in many different image instance types.
835 For example, `xpm' can be instanced as `color-pixmap', `mono-pixmap',
836 or `pointer'; whereas `cursor-font' can be instanced only as `pointer'.
837 On the other hand, a particular image instance type can be generated
838 by many different image instantiator formats (e.g. `color-pixmap' can
839 be generated by `xpm', `gif', `jpeg', etc.).
841 *Note Image Instances::, for a more detailed discussion of image
844 An image instantiator should be a string or a vector of the form
846 `[FORMAT :KEYWORD VALUE ...]'
848 i.e. a format symbol followed by zero or more alternating
851 The form of an instantiator can be checked with
852 `valid-instantiator-p' with a TYPE of `image', *Note Specifier
853 Validation Functions::.
855 For a complete list of the format symbols and their usage, *Note
856 Image Instantiator Formats::.
858 If the instantiator is a string, it will be converted into a vector
859 by looking it up according to the specs in the
860 `console-type-image-conversion-list' for the console type of the domain
861 (usually a window; sometimes a frame or device) over which the image is
864 If the instantiator specifies data from a file, the data will be
865 read in at the time that the instantiator is added to the image
866 specifier (which may be well before the image is actually displayed),
867 and the instantiator will be converted into one of the inline-data
868 forms, with the filename retained using a `:file' keyword. This
869 implies that the file must exist when the instantiator is added to the
870 image, but does not need to exist at any other time (e.g. it may safely
871 be a temporary file).
873 The available keywords are given below. Note that some keywords are
874 generally available (for example, the `:data' keyword may be used with
875 any format except `nothing'), while others are only available for one
876 format (`resource-id' is unique to the `mswindows-resource' format).
879 Inline image data. If available for a given format, it may be
880 specified directly by the program, or it may be a cache of file
881 data previously read. When present, it is used to instantiate the
882 image in preference to the file named by the `:file' property.
884 The format of inline data is image-format-specific. For example,
885 in pixmap formats, the value should be a string, which is
886 interpreted as an octet-stream representing a bitmap or pixmap.
887 But for text formats, it's string containing the text to be
888 displayed, and for resource formats, it's a string containing the
889 name of the resource.
892 Data contained in a file. The value is the name of this file. If
893 both `:data' and `:file' are specified, the image is created from
894 what is specified in `:data' and the string in `:file' becomes the
895 value of the `image-instance-file-name' function when applied to
896 the resulting image-instance. Note that there is nothing to stop a
897 program from changing either the `:file' or the `:data' property,
898 and there is no way to detect such mischief. This means that the
899 data will _not_ be automatically reread if you change the `file'
900 property; you must force it by removing the `:data' property.
901 (One way to do this is replacing the whole specification with a new
902 vector.) This keyword is not valid for instantiator formats
903 `nothing', `string', `formatted-string', `cursor-font', `font',
907 Inline data for `xbm' and `xface'. This specifies a mask to be
908 used with the bitmap. Pixels which are not set in the mask will
909 not be written to the imaging device. The format is a list of
910 width, height, and bits, as for `:data'.
913 For `xbm' and `xface'. This specifies a file containing the mask
914 data. If neither a mask file nor inline mask data is given for an
915 XBM image, and the XBM image comes from a file, XEmacs will look
916 for a mask file with the same name as the image file but with
917 `Mask' or `msk' appended. For example, if you specify the XBM file
918 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
919 associated mask file `left_ptrmsk' will automatically be picked up.
922 Only for `mswindows-resource'. This must be either an integer
923 (which directly specifies a resource number) or a string. See the
924 description of `mswindows-resource' for valid strings. *Note
925 Image Instantiator Formats::.
929 For `xbm', `xface', `cursor-font', and `font'. These keywords
930 allow you to explicitly specify foreground and background colors.
931 The value should be anything acceptable to `make-color-instance'.
932 This will cause an external format that would by default be
933 instantiated as a `mono-pixmap' to instead be instantiated as a
934 two-color color-pixmap. This can be used to override the colors
935 specified by a glyph's face, for example. If the image is
936 instantiated as a pointer, they specify its foreground and/or
937 background, instead of the defaults of black and white.
941 For `xbm' and `xface'. These keywords specify a hotspot if the
942 image is instantiated as a `pointer'. Note that if the XBM image
943 file specifies a hotspot, it will automatically be picked up if no
944 explicit hotspot is given.
947 Only for `xpm'. This specifies an alist that maps strings that
948 specify symbolic color names to the actual color to be used for
949 that symbolic color (in the form of a string or a color-specifier
950 object). If this is not specified, the contents of
951 `xpm-color-symbols' are used to generate the alist.
954 Only for `mswindows-resource'. This must be a symbol, either
955 `cursor', `icon', or `bitmap', specifying the type of resource to
959 For `inherit' and the widget formats. This specifies the face to
960 inherit from. For widgets this specifies the face to use for
961 display. It defaults to gui-element-face.
975 These keywords, accepted as menu item specs, are also accepted by
976 images instantiated as `widget'. For their semantics, *Note Menu
980 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instantiator Formats, Prev: Image Specifiers, Up: Images
982 50.2.2 Image Instantiator Conversion
983 ------------------------------------
985 Conversion is applied to image instantiators at the time they are added
986 to an image specifier or at the time they are passed to
987 `make-image-instance'.
989 -- Function: set-console-type-image-conversion-list console-type list
990 This function sets the image-conversion-list for consoles of the
991 given CONSOLE-TYPE. The image-conversion-list specifies how image
992 instantiators that are strings should be interpreted. Each
993 element of the list should be a list of two elements (a regular
994 expression string and a vector) or a list of three elements (the
995 preceding two plus an integer index into the vector). The string
996 is converted to the vector associated with the first matching
997 regular expression. If a vector index is specified, the string
998 itself is substituted into that position in the vector.
1000 Note: The conversion above is applied when the image instantiator
1001 is added to an image specifier, not when the specifier is actually
1002 instantiated. Therefore, changing the image-conversion-list only
1003 affects newly-added instantiators. Existing instantiators in
1004 glyphs and image specifiers will not be affected.
1006 -- Function: console-type-image-conversion-list console-type
1007 This function returns the image-conversion-list for consoles of
1008 the given CONSOLE-TYPE.
1011 File: lispref.info, Node: Image Instantiator Formats, Next: Image Instances, Prev: Image Instantiator Conversion, Up: Images
1013 50.2.3 Image Instantiator Formats
1014 ---------------------------------
1016 The "format" field of an image instantiator should be a symbol denoting
1017 a valid format. Which formats are valid will depend on the features
1018 (such as image decoding libraries) available, on platform support (MS
1019 Windows resource IDs make no sense on other platforms), and on the
1022 -- Function: valid-image-instantiator-format-p format &optional locale
1023 This function returns non-`nil' if FORMAT is a valid image
1024 instantiator format.
1026 If LOCALE is non-`nil' then the format is checked in that locale.
1027 If LOCALE is `nil' the current console is used.
1029 Note that the return value for many formats listed above depends on
1030 whether XEmacs was compiled with support for that format.
1032 -- Function: image-instantiator-format-list
1033 This function returns a list of valid image-instantiator formats.
1035 Here is a table of image-instantiator formats, giving the keywords
1036 that are usable with each, and the kinds of instances that may result.
1039 Don't display anything; no keywords are valid for this format.
1040 Can only be instanced as `nothing'.
1043 Display this image as a text string. Can only be instanced as
1044 `text', although support for instancing as `mono-pixmap' should be
1045 added. The valid keyword is `:data'. The value should be a
1046 string, and it is interpreted as a string of characters.
1049 Display this image as a text string with replaceable fields,
1050 similar to a modeline format string. The valid keyword is `:data'.
1051 The value should be a string, and it is interpreted as a string of
1052 characters containing format sequences.
1054 Not currently implemented.
1057 An X bitmap; available only if X support was compiled into this
1060 If used in a buffer glyph, icon glyph, or face background pixmap,
1061 it will be instantiated as `mono-pixmap' unless the `:foreground'
1062 or `:background' keywords are present. In the latter case it will
1063 be instantiated as `color-pixmap' with the two specified colors.
1064 (Probably if `:foreground' or `:background' is omitted, it
1065 defaults to black or white respectively.) If used in a pointer
1066 glyph, it will be instantiated as an `pointer'.
1068 The valid keywords and their values are
1070 A list containing the height and width of the bitmap as
1071 integers, and a string interpreted as a bit vector according
1072 to the X11 standard XBM bitmap format, in that order.
1075 The name of a file containing standard XBM-format data. If
1076 it contains a hotspot specification, it will be parsed and
1077 used if the hotspot is not explicitly specified.
1080 A list containing the height and width of the bitmap as
1081 integers, and a string interpreted as a bit vector according
1082 to the X11 standard XBM bitmap format, in that order. This
1083 bitmap is interpreted as the clipping region for the bitmap
1084 contained in the `:data' property.
1087 The name of a file containing standard XBM-format data.
1088 Interpreted as the clipping region for the bitmap contained
1089 in the `:data' property.
1093 These keywords allow you to explicitly specify foreground and
1094 background colors. The values should be acceptable to
1095 `make-color-instance'.
1099 Integers denoting the hotspot (mouse pointer position), with
1100 (0,0) at the top left corner. If given, these override any
1101 specification in the XBM file.
1104 An XPM pixmap; only available if XPM support was compiled into
1107 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
1109 XPM is an add-on library for X that was designed to rectify the
1110 shortcomings of the XBM format. Many icons and labels used in the
1111 XEmacs GUI are still distributed in XPM format (although we are
1112 moving to standardize on the PNG format). It is therefore highly
1113 desirable that XPM be available in your XEmacs.
1115 Most implementations of X include the XPM library as a standard
1116 part. If your vendor does not, it is highly recommended that you
1117 download it and install it. You can get it from the XEmacs FTP
1118 site and mirrors, as well as from most sites that distribute X11.
1120 The valid keywords and their values are
1122 A string interpreted as the contents of a standard XPM file.
1125 The name of a file containing standard XPM-format data. If
1126 it contains a hotspot specification, it will be parsed and
1127 used if the hotspot is not explicitly specified.
1131 Integers denoting the hotspot (mouse pointer position), with
1132 (0,0) at the top left corner. If given, these override any
1133 specification in the XBM file. (This may not be true. The
1134 original documentation doesn't mention them in connection
1135 with XPM, but a pointer needs a hotspot.)
1138 An alist that maps the one- or two-character strings that
1139 specify symbolic color names in the XPM file to the actual
1140 color to be used for that symbolic color (in the form of a
1141 string acceptable as a color instantiator, *Note Color
1142 Specifiers::, or a color-specifier object). If this is not
1143 specified, the contents of `xpm-color-symbols' are used to
1147 An X-Face bitmap, used to encode people's faces in e-mail messages;
1148 only available if X-Face support was compiled into this XEmacs.
1150 Will be instanced as `mono-pixmap', `color-pixmap', or `pointer',
1151 depending on the target instance type and the presence of color
1154 The valid keywords and their values are
1156 A list containing the height and width of the bitmap as
1157 integers, and a string interpreted as a bit vector according
1158 to the X11 standard XBM bitmap format, in that order.
1161 The name of a file containing standard XBM-format data. If
1162 it contains a hotspot specification, it will be parsed and
1163 used if the hotspot is not explicitly specified.
1166 A list containing the height and width of the bitmap as
1167 integers, and a string interpreted as a bit vector according
1168 to the X11 standard XBM bitmap format, in that order. This
1169 bitmap is interpreted as the clipping region for the bitmap
1170 contained in the `:data' property.
1173 The name of a file containing standard XBM-format data.
1174 Interpreted as the clipping region for the bitmap contained
1175 in the `:data' property.
1179 These keywords allow you to explicitly specify foreground and
1180 background colors. The values should be acceptable to
1181 `make-color-instance'.
1185 Integers denoting the hotspot (mouse pointer position), with
1186 (0,0) at the top left corner. If given, these override any
1187 specification in the XBM file.
1193 These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format,
1194 and TIFF-format images, respectively. They are available only if
1195 appropriate decoding support was built into XEmacs. XEmacs
1196 includes GIF decoding functions as a standard part of it, so if
1197 you have X support, you will normally have GIF support, unless you
1198 explicitly disable it at configure time. If you have development
1199 support (both the libraries and the relevant C header files)
1200 available when XEmacs is built, the JPEG, PNG, and TIFF libraries
1201 will automatically be detected (in the "usual places") and linked
1204 Note that PNG is the standard format for images distributed with
1205 XEmacs, so it is highly recommended that PNG support be built in.
1207 All of these instantiators will be instanced as `color-pixmap'.
1209 The valid keywords and their values are
1211 A string interpreted as the contents of a file containing
1212 data in the appropriate standard format.
1215 The name of a file containing standard-format data.
1218 Most window systems provide a set of standard cursors, which in
1219 X11 is called a cursor font. Can only be instanced as `pointer'.
1220 This should probably be fixed.
1222 The valid keyword is `:data'. Its value should be a string
1223 containing one of the standard cursor-font names, such as `watch'
1224 or `right_ptr' under X. More specifically, in the X Window System
1225 it may be any of the standard cursor names from appendix B of the
1226 Xlib manual, provided in the file `<X11/cursorfont.h>' by most
1227 distributions, minus the `XC_' prefix. For MS Windows, use
1228 `mswindows-resource' instantiator format, not `cursor-font'.
1229 Other window systems may have different lists.
1232 A glyph from a font; i.e. the name of a font, and glyph index into
1233 it of the form `FONT fontname index [[mask-font] mask-index]'.
1234 Only if X support was compiled into this XEmacs. Currently can
1235 only be instanced as `pointer'. This should probably be fixed.
1237 `mswindows-resource'
1238 An MS Windows pointer resource. Specifies a resource to retrieve
1239 directly from the system (an OEM resource) or from a file,
1240 particularly an executable file. Can be instanced as `pointer' or
1243 The valid keywords and their values are
1246 A string naming the type (`cursor', `bitmap', or `icon') of
1247 the resource. Required.
1250 A string containing the name of the file containing the
1251 resource (often an executable). If a system resource,
1252 `:file' should be omitted.
1255 A string containing the name of a resource. Required if
1256 `:file' is not specified.
1258 This must be either an integer (which directly specifies a
1259 resource number) or a string. Valid strings are
1263 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
1264 "reduce", "zoom", "restore", "reduced", "zoomd", "restored",
1265 "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow",
1266 "combo", "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi",
1267 "size", "btsize", "check", "checkboxes", and "btncorners".
1271 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
1272 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
1276 "sample", "hand", "ques", "bang", "note", and "winlogo".
1279 An embedded windowing system window. Can only be instanced as
1280 `subwindow'. Not implemented.
1283 A button widget; either a push button, radio button or toggle
1284 button. Can only be instanced as `widget'.
1287 A drop list of selectable items in a widget, for editing text.
1288 Can only be instanced as `widget'.
1291 A text editing widget. Can only be instanced as `widget'.
1294 A static, text-only, widget; for displaying text. Can only be
1295 instanced as `widget'.
1298 A widget for controlling the positioning of children underneath it.
1299 Through the use of nested layouts, a widget hierarchy can be
1300 created which can have the appearance of any standard dialog box
1301 or similar arrangement; all of this is counted as one "glyph" and
1302 could appear in many of the places that expect a single glyph.
1303 Can only be instanced as `widget'.
1306 The native version of a layout widget. Can only be instanced as
1310 A sliding widget, for showing progress. Can only be instanced as
1314 A tab widget; a series of user selectable tabs. Can only be
1315 instanced as `widget'.
1318 A folding widget. Can only be instanced as `widget'.
1321 A scrollbar widget. Can only be instanced as `widget'.
1324 XEmacs tries to guess what format the data is in. If X support
1325 exists, the data string will be checked to see if it names a
1326 filename. If so, and this filename contains XBM or XPM data, the
1327 appropriate sort of pixmap or pointer will be created. [This
1328 includes picking up any specified hotspot or associated mask
1329 file.] Otherwise, if `pointer' is one of the allowable
1330 image-instance types and the string names a valid cursor-font
1331 name, the image will be created as a pointer. Otherwise, the
1332 image will be displayed as text. If no X support exists, the
1333 image will always be displayed as text.
1336 Inherit from the background-pixmap property of a face. Can only be
1337 instanced as `mono-pixmap'.
1339 There are two convenience variables for use with the XBM and XPM
1342 -- Variable: xpm-color-symbols
1343 This variable holds definitions of logical color-names used when
1344 reading XPM files. Elements of this list should be of the form
1345 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
1346 string, which is the name of the color to define; the
1347 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
1348 string to be passed to `make-color-instance' (*note Colors::). If
1349 a loaded XPM file references a symbolic color called COLOR-NAME,
1350 it will display as the computed color instead.
1352 The default value of this variable defines the logical color names
1353 `"foreground"' and `"background"' to be the colors of the
1356 -- Variable: x-bitmap-file-path
1357 A list of the directories in which X bitmap files may be found.
1358 If `nil', this is initialized from the `"*bitmapFilePath"'
1359 resource. This is used by the `make-image-instance' function
1360 (however, note that if the environment variable `XBMLANGPATH' is
1361 set, it is consulted first).
1364 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Formats, Up: Images
1366 50.2.4 Image Instances
1367 ----------------------
1369 Image-instance objects encapsulate the way a particular image (pixmap,
1370 etc.) is displayed on a particular device.
1372 In most circumstances, you do not need to directly create image
1373 instances; use a glyph instead. However, it may occasionally be useful
1374 to explicitly create image instances, if you want more control over the
1375 instantiation process.
1377 -- Function: image-instance-p object
1378 This function returns non-`nil' if OBJECT is an image instance.
1382 * Image Instance Types:: Each image instances has a particular type.
1383 * Image Instance Functions:: Functions for working with image instances.
1386 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
1388 50.2.4.1 Image Instance Types
1389 .............................
1391 Image instances come in a number of different types. The type of an
1392 image instance specifies the nature of the image: Whether it is a text
1393 string, a mono pixmap, a color pixmap, etc.
1395 The valid image instance types are
1398 Nothing is displayed.
1401 Displayed as text. The foreground and background colors and the
1402 font of the text are specified independent of the pixmap.
1403 Typically these attributes will come from the face of the
1404 surrounding text, unless a face is specified for the glyph in
1405 which the image appears.
1408 Displayed as a mono pixmap (a pixmap with only two colors where the
1409 foreground and background can be specified independent of the
1410 pixmap; typically the pixmap assumes the foreground and background
1411 colors of the text around it, unless a face is specified for the
1412 glyph in which the image appears).
1415 Displayed as a color pixmap.
1418 Used as the mouse pointer for a window.
1421 A child window that is treated as an image. This allows (e.g.)
1422 another program to be responsible for drawing into the window.
1423 Not currently implemented.
1426 An active GUI element implemented as a "widget" or "control" of the
1427 underlying window system.
1429 The following functions are used to check whether an image instance
1430 type is valid in the running XEmacs.
1432 -- Function: valid-image-instance-type-p type
1433 This function returns non-`nil' if TYPE is a valid image instance
1436 -- Function: image-instance-type-list
1437 This function returns a list of the valid image instance types.
1439 The following functions are used to determine the type of an image
1442 -- Function: image-instance-type image-instance
1443 Return the type of the given image instance. The return value
1444 will be one of `nothing', `text', `mono-pixmap', `color-pixmap',
1445 `pointer', `subwindow', or `widget'.
1447 -- Function: text-image-instance-p object
1448 Return non-`nil' if OBJECT is an image instance of type `text'.
1450 -- Function: mono-pixmap-image-instance-p object
1451 Return non-`nil' if OBJECT is an image instance of type
1454 -- Function: color-pixmap-image-instance-p object
1455 Return non-`nil' if OBJECT is an image instance of type
1458 -- Function: pointer-image-instance-p object
1459 Return non-`nil' if OBJECT is an image instance of type `pointer'.
1461 -- Function: subwindow-image-instance-p object
1462 Return non-`nil' if OBJECT is an image instance of type
1465 -- Function: nothing-image-instance-p object
1466 Return non-`nil' if OBJECT is an image instance of type `nothing'.
1468 -- Function: widget-image-instance-p object
1469 Return non-`nil' if OBJECT is an image instance of type `widget'.
1472 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
1474 50.2.4.2 Image Instance Functions
1475 .................................
1477 -- Function: make-image-instance data &optional domain dest-types
1479 This function creates a new image-instance object.
1481 DATA is an image instantiator, which describes the image (*note
1482 Image Specifiers::).
1484 DEST-TYPES should be a list of allowed image instance types that
1485 can be generated. The DEST-TYPES list is unordered. If multiple
1486 destination types are possible for a given instantiator, the "most
1487 natural" type for the instantiator's format is chosen. These are
1491 `mono-pixmap', then `color-pixmap', then `pointer'.
1498 `color-pixmap', then `mono-pixmap', then `pointer'.
1501 `formatted-string formats'
1502 `text', then `mono-pixmap' (not currently implemented), then
1503 `color-pixmap' (not currently implemented).
1505 `mswindows-resource'
1506 For pointer resources, `pointer'.
1508 For the others, `color-pixmap'.
1510 The other formats can only be instantiated as one type.
1512 If you want to control more specifically the order of the types
1513 into which an image is instantiated, call `make-image-instance'
1514 repeatedly until it succeeds, passing less and less preferred
1515 destination types each time.
1517 If DEST-TYPES is omitted, all possible types are allowed.
1519 DOMAIN specifies the domain to which the image instance will be
1520 attached. This domain is termed the "governing domain". The type
1521 of the governing domain depends on the image instantiator format.
1522 (Although, more correctly, it should probably depend on the image
1523 instance type.) For example, pixmap image instances are specific
1524 to a device, but widget image instances are specific to a
1525 particular XEmacs window because in order to display such a widget
1526 when two windows onto the same buffer want to display the widget,
1527 two separate underlying widgets must be created. (That's because
1528 a widget is actually a child window-system window, and all
1529 window-system windows have a unique existence on the screen.)
1530 This means that the governing domain for a pixmap image instance
1531 will be some device (most likely, the only existing device),
1532 whereas the governing domain for a widget image instance will be
1535 If you specify an overly general DOMAIN (e.g. a frame when a
1536 window was wanted), an error is signaled. If you specify an overly
1537 specific DOMAIN (e.g. a window when a device was wanted), the
1538 corresponding general domain is fetched and used instead. For
1539 `make-image-instance', it makes no difference whether you specify
1540 an overly specific domain or the properly general domain derived
1541 from it. However, it does matter when creating an image instance
1542 by instantiating a specifier or glyph (e.g. with
1543 `glyph-image-instance'), because the more specific domain causes
1544 spec lookup to start there and proceed to more general domains.
1545 (It would also matter when creating an image instance with an
1546 instantiator format of `inherit', but we currently disallow this.)
1548 If omitted, DOMAIN defaults to the selected window.
1550 NOERROR controls what happens when the image cannot be generated.
1551 If `nil', an error message is generated. If `t', no messages are
1552 generated and this function returns `nil'. If anything else, a
1553 warning message is generated and this function returns `nil'.
1555 -- Function: colorize-image-instance image-instance foreground
1557 This function makes the image instance be displayed in the given
1558 colors. Image instances come in two varieties: bitmaps, which are
1559 1 bit deep which are rendered in the prevailing foreground and
1560 background colors; and pixmaps, which are of arbitrary depth
1561 (including 1) and which have the colors explicitly specified.
1562 This function converts a bitmap to a pixmap. If the image
1563 instance was a pixmap already, nothing is done (and `nil' is
1564 returned). Otherwise `t' is returned.
1566 The following functions are
1568 -- Function: image-instance-name image-instance
1569 This function returns the name of the given image instance. The
1570 name is typically taken from the `:file' property of the
1571 instantiator if present, otherwise from the `:data' property.
1573 -- Function: image-instance-domain image-instance
1574 Return the governing domain of the given IMAGE-INSTANCE. The
1575 governing domain of an image instance is the domain that the image
1576 instance is specific to. It is _NOT_ necessarily the domain that
1577 was given to the call to `specifier-instance' that resulted in the
1578 creation of this image instance. See `make-image-instance' for
1579 more information on governing domains.
1581 -- Function: image-instance-string image-instance
1582 This function returns the string of the given image instance.
1583 This will only be non-`nil' for text image instances.
1585 -- Function: image-instance-file-name image-instance
1586 This function returns the file name from which IMAGE-INSTANCE was
1589 -- Function: image-instance-mask-file-name image-instance
1590 This function returns the file name from which IMAGE-INSTANCE's
1591 mask was read, if known.
1593 Pixmaps are considered to be three-dimensional. The height and
1594 width of the pixel array that is displayed, and the color depth of its
1595 pixels, are accessed with these functions.
1597 -- Function: image-instance-depth image-instance
1598 This function returns the depth of the image instance. This is 0
1599 for a mono pixmap, or a positive integer for a color pixmap.
1601 -- Function: image-instance-height image-instance
1602 This function returns the height of the image instance, in pixels.
1604 -- Function: image-instance-width image-instance
1605 This function returns the width of the image instance, in pixels.
1607 The hotspot is a point relative to the origin of the pixmap. When
1608 an image is used as a mouse pointer, the hotspot is the point on the
1609 image that sits over the location that the pointer points to. This is,
1610 for example, the tip of the arrow or the center of the crosshairs.
1612 These functions access the coordinates of the hotspot. They simply
1613 return `nil' for a non-pointer image instance.
1615 -- Function: image-instance-hotspot-x image-instance
1616 This function returns the X coordinate of the image instance's
1619 -- Function: image-instance-hotspot-y image-instance
1620 This function returns the Y coordinate of the image instance's
1623 Mono pixmaps and pointers may have their foreground and background
1624 colors set when instanced. Use these functions to access color
1627 -- Function: image-instance-foreground image-instance
1628 This function returns the foreground color of IMAGE-INSTANCE, if
1629 applicable. This will be a color instance or `nil'. (It will only
1630 be non-`nil' for colorized mono pixmaps and for pointers.)
1632 -- Function: image-instance-background image-instance
1633 This function returns the background color of IMAGE-INSTANCE, if
1634 applicable. This will be a color instance or `nil'. (It will only
1635 be non-`nil' for colorized mono pixmaps and for pointers.)
1638 File: lispref.info, Node: Using Glyphs, Next: Manipulating Glyphs, Prev: Images, Up: Glyphs
1643 Glyph usage is unfortunately somewhat arcane. (For discussion of
1644 rationale, *Note Glyphs: (Internals)Glyphs.) Because they are not
1645 "text," they cannot be inserted directly into a buffer. Instead, they
1646 are values of properties of extents attached to buffers or strings,
1647 values of global variables such as mouse pointers, or as a component of
1648 a complex data structure such as a toolbar initializer. Although these
1649 uses could probably streamlined, each structure has its own
1650 requirements. Since glyphs are very flexible, it is possible to create
1651 applications like the `edit-toolbar' and `xpm-mode' libraries which
1652 display glyphs in a buffer (for reference while editing) that are
1653 normally used in a different context.
1655 Usage of glyphs can roughly be categorized as follows:
1658 Glyphs that are inserted in a buffer may be used for their own
1659 sake (for example, image display in `w3'), as an accurate
1660 representation of text that can't be displayed in usual fonts
1661 (equation display in `preview-latex'), or as annotations (such as
1662 a marginal indication of a bookmark). Glyphs are attached to
1663 buffers via extents.
1666 Glyphs can be used to create XEmacs-specific "fonts". For example,
1667 the character that indicates truncation of lines is implemented as
1668 the `truncation-glyph'. It is also possible to have XEmacs
1669 display a certain character using a custom glyph, via display
1673 Glyphs are used to control the appearance of various other
1674 components of the frame. They can be inserted in the modeline,
1675 like the favicons used in Web browsers. They are used to specify
1676 the labels on toolbar buttons. Finally, they can be inserted in
1677 the gutters. (The difference between a glyph inserted in a gutter
1678 and a marginal annotation is that the marginal annotation is tied
1679 to the text in the buffer. If the buffer line scrolls out of
1680 view, the marginal annotation will, as well. A gutter glyph does
1681 not move with the text.)
1683 Unfortunately, all these uses are special cases, and have their own
1684 APIs, in contrast to glyphs in a buffer.
1687 External glyphs simply allow a consistent API for images. The
1688 images are then passed to external software such as the window
1689 system itself (mouse cursor shapes) and the window manager (icons
1690 to represent minimized windows). XEmacs has no role in managing
1693 *Subwindow and widget glyphs*
1694 These do not constitute a context of use, but rather an important
1695 class of glyph types. The difference between these and other
1696 glyphs is that while their geometry is determined by XEmacs, their
1697 behavior is managed separately, by internal mechanisms in the case
1698 of widgets, and (possibly) by another process in the case of
1701 Some simple concrete examples showing how to insert a glyph in a
1702 buffer are presented later. *Note Glyph Examples::.
1704 "Creating Glyphs" explains how to create glyphs. Creating a glyph
1705 using `make-glyph' does not specify _where_ the glyph will be used, it
1706 only specifies _what_ the glyph will look like. The next four sections
1707 explain how to embed glyphs in different display contexts. Finally,
1708 the last two sections explain the special considerations of using
1709 glyphs whose behavior is not determined by the code creating them, but
1710 by the glyph itself (a "widget" in X11 or "control" in MS Windows or
1711 Aqua), or even by a separate process.
1715 * Creating Glyphs:: Creating new glyphs.
1716 * Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
1717 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
1718 * Frame Glyphs:: Displaying glyphs in GUI components of the frame.
1719 * External Glyphs:: Icons and mouse pointers for the window system.
1720 * Native GUI Widgets:: Complex active elements treated as a single glyph.
1721 * Subwindows:: Externally-controlled subwindows in buffers.
1724 File: lispref.info, Node: Creating Glyphs, Next: Buffer Glyphs, Up: Using Glyphs
1726 50.3.1 Creating Glyphs
1727 ----------------------
1729 -- Function: make-glyph &optional spec-list type
1730 This function creates a new glyph object of type TYPE.
1732 The optional SPEC-LIST is used to initialize the glyph's image.
1733 It can be any spec-list of "image instantiator" accepted by
1734 `canonicalize-spec-list', *Note Adding Specifications::. An
1735 individual image instantiator may be a string, which is converted
1736 to a vector according to `console-type-image-conversion-list', or a
1737 vector. The vector's first element specifies the _external_ format
1738 of the data, such as a string, a PNG file, or an MS Windows
1739 resource. This is followed by properties (keyword-value pairs)
1740 specifying such information as the name of a file containing an
1741 image, or pixmap data directly. *Note Image Specifiers::.
1743 The optional TYPE specifies the type of the glyph. TYPE should be
1744 one of `buffer' (used for glyphs in an extent, the modeline, the
1745 toolbar, or elsewhere in a frame), `pointer' (used for the
1746 mouse-pointer), or `icon' (used for a frame's icon), and defaults
1749 SPEC-LIST is the initializer for the glyph's `image' property, which
1750 is an image specifier. (Note that "image" as used in the context of a
1751 glyph's `image' property or in the terms "image specifier", "image
1752 instantiator", or "image instance" does not refer to what people
1753 normally think of as an image (which in XEmacs is called a "pixmap"),
1754 but to any graphical element--a pixmap, a widget, or even a block of
1755 text, when used in the places that call for a glyph.)
1757 The most common form of SPEC-LIST is a single image instantiator.
1758 (*Compatibility note:* in GNU Emacs 21, a string used to instantiate an
1759 image is interpreted as the name of an image file, which is searched
1760 for and instantiated.) The conversion controlled by
1761 `console-type-image-conversion-list' typically attempts to look up the
1762 string as a file name in XEmacs's data directory path, and if this
1763 fails, defaults to displaying the string as a text image instance
1764 (_i.e._. the string itself.
1766 Fine control of a particular specification is provided by using a
1767 vector as the image instantiator. More complicated instantiators allow
1768 lists of instantiators to be specified (which are tried in order), or
1769 mappings from locales to lists of instantiators, _etc_. *Note
1770 Specifiers::, for more information about specification formats.
1772 As well as using SPEC-LIST to initialize the glyph, you can set
1773 specifications using `set-glyph-image'. The glyph itself is not
1774 actually a specifier, but rather is an object containing an image
1775 specifier (as well as other properties seldom set by user code).
1776 Therefore, you cannot set or access specifications for the glyph's image
1777 by directly using `set-specifier', `specifier-instance' or the like on
1778 the glyph; instead use them on `(glyph-image GLYPH)' or use the
1779 convenience functions `set-glyph-image', `glyph-image-instance', and
1782 Glyph types reflect the fact that glyphs are used in contexts like
1783 pointers and window manager icons, which are defined by external
1784 programs such as the window system or window manager. These require
1785 somewhat different _internal_ format, which is opaque to the user.
1787 It is extremely rare that you will ever have to specify a value for
1788 TYPE, which should be one of `buffer' (used for glyphs in an extent,
1789 the modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
1790 for the mouse-pointer), or `icon' (used for a frame's icon), and
1791 defaults to `buffer'. The only cases where it needs to be specified is
1792 when creating icon or pointer glyphs, and in both cases the necessary
1793 glyphs have already been created at startup and are accessed through
1794 the appropriate variables, e.g. `text-pointer-glyph' (or in general, any
1795 `*-pointer-glyph') and `frame-icon-glyph'. User code should never need
1796 to create `pointer' or `icon' glyphs. *Note Glyph Types::.
1798 There are a few other glyph creation functions, normally used only
1799 internally or at XEmacs initialization.
1801 -- Function: make-glyph-internal &optional type
1802 This function creates a new, uninitialized glyph of type TYPE.
1804 -- Function: make-pointer-glyph &optional spec-list
1805 Return a new `pointer-glyph' object with the specification list
1806 SPEC-LIST. This function is equivalent to calling `make-glyph'
1807 with a TYPE of `pointer'.
1809 `make-pointer-glyph' is normally used only by XEmacs initialization
1810 code. It is extremely unlikely that you will ever need to create a
1811 pointer glyph. Instead, you probably want to be calling
1812 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
1814 -- Function: make-icon-glyph &optional spec-list
1815 Return a new `icon-glyph' object with the specification list
1816 SPEC-LIST. This function is equivalent to calling `make-glyph'
1817 with a TYPE of `icon'.
1819 `make-icon-glyph' is normally used only by XEmacs initialization
1820 code. It is extremely unlikely that you will ever need to create a icon
1821 glyph. Instead, you probably want to be calling `set-glyph-image' on
1822 the existing glyph, `frame-icon-glyph'.
1825 File: lispref.info, Node: Buffer Glyphs, Next: Redisplay Glyphs, Prev: Creating Glyphs, Up: Using Glyphs
1827 50.3.2 Buffer Glyphs
1828 --------------------
1830 Creating a glyph using `make-glyph' does not specify _where_ the glyph
1831 will be used, it only specifies _what_ the glyph will look like. Once
1832 you have created a glyph, you specify where it will be used by
1833 attaching it to an extent as a _begin-glyph_ or _end-glyph_.
1836 To insert a glyph into a buffer, create an extent in the buffer
1837 and then use `set-extent-begin-glyph' or `set-extent-end-glyph' to
1838 set a glyph to be displayed at the corresponding edge of the
1839 extent. (It is common to create zero-width extents for this
1843 To insert a glyph into the left or right margin of a buffer, first
1844 make sure the margin is visible by setting a value for the
1845 specifiers `left-margin-width' or `right-margin-width'. (Not
1846 strictly necessary when using margin glyphs with layout policy
1847 `whitespace'.) Follow the same procedure above for inserting a
1848 glyph in a buffer, then set a non-default layout policy for the
1849 glyph using `set-extent-begin-glyph-layout' or
1850 `set-extent-end-glyph-layout'. Alternatively, use the high-level
1851 annotations API (see `make-annotation'). (In fact, you can also
1852 use the annotations API for glyphs in a buffer, by setting a
1853 layout policy of `text'.)
1857 File: lispref.info, Node: Redisplay Glyphs, Next: Frame Glyphs, Prev: Buffer Glyphs, Up: Using Glyphs
1859 50.3.3 Redisplay Glyphs
1860 -----------------------
1862 To use a glyph to control the shape of miscellaneous redisplay effects
1863 such as the truncation and continuation markers, set the appropriate
1864 existing glyph variables with `set-glyph-image'. See
1865 `continuation-glyph', `control-arrow-glyph', `hscroll-glyph',
1866 `invisible-text-glyph', `octal-escape-glyph', and `truncation-glyph'.
1867 See also `overlay-arrow-string', an odd redisplay leftover which can be
1868 set to a glyph you created, and will cause the glyph to be displayed on
1869 top of the text position specified in the marker stored in
1870 `overlay-arrow-position'.
1872 To use a glyph in a display table (i.e. to control the appearance of
1873 any individual character), create the appropriate character glyphs and
1874 then set a specification for the specifier `current-display-table',
1875 which controls the appearance of characters. You can also set an
1876 overriding display table for use with text displayed in a particular
1877 face; see `set-face-display-table' and `make-display-table'. ####
1878 Note: Display tables do not currently support general Mule characters.
1879 They will be overhauled at some point to support this and to provide
1880 other features required under Mule. *Note Display Tables::.
1882 Glyphs are not actually used as the background pixmaps of faces, but
1883 the API is similar. The background pixmap of a face is actually an
1884 image specifier - probably the only place in XEmacs where an image
1885 specifier occurs outside of a glyph. If you would like to use a
1886 glyph's image as a background pixmap, you can extract it with
1887 `glyph-image', and then add it to a face. *Note Face Convenience
1890 -- Glyph: truncation-glyph
1891 This variable specifies what is displayed at the end of truncated
1894 -- Glyph: continuation-glyph
1895 This variable specifies what is displayed at the end of wrapped
1898 -- Glyph: octal-escape-glyph
1899 This variable specifies what to prefix character codes displayed
1902 -- Glyph: hscroll-glyph
1903 This variable specifies what to display at the beginning of
1904 horizontally scrolled lines.
1906 -- Glyph: invisible-text-glyph
1907 This variable specifies what to use to indicate the presence of
1908 invisible text. This is the glyph that is displayed when an
1909 ellipsis is called for, according to `selective-display-ellipses'
1910 or `buffer-invisibility-spec'). Normally this is three dots
1913 -- Glyph: control-arrow-glyph
1914 This variable specifies what to use as an arrow for control
1918 File: lispref.info, Node: Frame Glyphs, Next: External Glyphs, Prev: Redisplay Glyphs, Up: Using Glyphs
1923 There are also a number of special objects whose appearance is specified
1924 by a glyph. Most of these a global objects that you update with
1925 `set-glyph-image', such as mouse pointers. Frame icons, toolbar button
1926 icons, and the modeline are the main non-text objects which accept
1930 A glyph may be displayed in the modeline by inserting the glyph as
1931 one of the elements of the modeline format. (Unfortunately you
1932 can't currently put a begin glyph or end glyph on one of the
1933 modeline extents--they're ignored.)
1936 To insert a glyph into a toolbar, specify it as the icon part of a
1937 toolbar button, which in turn must be part of a toolbar
1938 instantiator (typically set on the specifier `default-toolbar').
1939 See `default-toolbar' for more information. (As a convenience, you
1940 may use a symbol in place of the glyph list in the toolbar button
1941 instantiator; the symbol is evalled to get the glyph list. This
1942 facilitates both creating the toolbar instantiator and modifying
1943 individual glyphs in a toolbar later on. For example, you can
1944 change the way that the Mail toolbar button looks by modifying the
1945 value of the variable `toolbar-mail-icon' (in general,
1946 `toolbar-*-icon') and then calling `(set-specifier-dirty-flag
1947 default-toolbar)'. (#### Unfortunately this doesn't quite work
1948 the way it should; the change will appear in new frames, but not
1949 existing ones, because once an image has been displayed the pixmap
1950 replaces the symbol for those domains.)
1953 To insert a glyph into a gutter, use `set-extent-begin-glyph' or
1954 `set-extent-end-glyph' to set a glyph to be displayed at the
1955 corresponding edge of extent in a string, similar to the way you
1956 insert glyphs in a buffer. Then insert the string into the gutter
1957 *Note Specifying a Gutter::. Glyphs that are frequently used in
1958 this way are `tab control' and `progress bar' glyphs.
1962 File: lispref.info, Node: External Glyphs, Next: Native GUI Widgets, Prev: Frame Glyphs, Up: Using Glyphs
1964 50.3.5 External Glyphs
1965 ----------------------
1967 There are two special kinds of glyph that are not displayed by XEmacs.
1968 Instead, they are used to set the appearance of iconified frames and the
1969 mouse pointer. Because these uses are constrained by the window system,
1970 icons and pointers have their own special types *Note Glyph Types::.
1972 You may use a glyph as the icon for a frame. Do not create a new
1973 glyph; instead, change the specifications for the existing glyph
1974 `frame-icon-glyph' with `set-glyph-image'. This is a unique,
1975 predefined object. Although the natural usage is to set specifications
1976 for the global locale or a frame locale, you can also arrange for a
1977 special icon when a frame's selected window displays a particular buffer
1978 by using a buffer locale.
1980 The shape of the mouse pointer when over a particular section of a
1981 frame is controlled using various glyph variables. Since the image of
1982 a glyph is a specifier, it can be controlled on a per-buffer,
1983 per-frame, per-window, or per-device basis.
1985 To use a glyph as the mouse pointer, in general you do not create a
1986 new glyph, but rather you change the specifications of various existing
1987 glyphs, such as `text-pointer-glyph' for the pointer used over text,
1988 `modeline-pointer-glyph' for the pointer used over the modeline, etc.
1989 Do an apropos over `pointer-glyph' to find all of them. (Note also
1990 that you can temporarily set the mouse pointer to some specific shape
1991 by using `set-frame-pointer', which takes an image instance, as
1992 obtained from calling `glyph-image-instance' on a glyph of type
1993 `pointer' - either one of the above-mentioned variables or one you
1994 created yourself. (See below for what it means to create a glyph of
1995 type `pointer'.) This pointer will last only until the next mouse
1996 motion event is processed or certain other things happen, such as
1997 creating or deleting a window. (In fact, the above-mentioned pointer
1998 glyph variables are implemented as part of the default handler for
1999 mouse motion events. If you want to customize this behavior, take a
2000 look at `mode-motion-hook', or `mouse-motion-handler' if you really
2001 want to get low-level.)
2003 You should use `set-glyph-image' to set the following variables,
2006 -- Glyph: text-pointer-glyph
2007 This variable specifies the shape of the mouse pointer when over
2010 -- Glyph: nontext-pointer-glyph
2011 This variable specifies the shape of the mouse pointer when over a
2012 buffer, but not over text. If unspecified in a particular domain,
2013 `text-pointer-glyph' is used.
2015 -- Glyph: modeline-pointer-glyph
2016 This variable specifies the shape of the mouse pointer when over
2017 the modeline. If unspecified in a particular domain,
2018 `nontext-pointer-glyph' is used.
2020 -- Glyph: selection-pointer-glyph
2021 This variable specifies the shape of the mouse pointer when over a
2022 selectable text region. If unspecified in a particular domain,
2023 `text-pointer-glyph' is used.
2025 -- Glyph: gc-pointer-glyph
2026 This variable specifies the shape of the mouse pointer when a
2027 garbage collection is in progress. If the selected window is on a
2028 window system and this glyph specifies a value (i.e. a pointer
2029 image instance) in the domain of the selected window, the pointer
2030 will be changed as specified during garbage collection.
2031 Otherwise, a message will be printed in the echo area, as
2032 controlled by `gc-message'.
2034 -- Glyph: busy-pointer-glyph
2035 This variable specifies the shape of the mouse pointer when XEmacs
2036 is busy. If unspecified in a particular domain, the pointer is
2037 not changed when XEmacs is busy.
2039 -- Glyph: menubar-pointer-glyph
2040 This variable specifies the shape of the mouse pointer when over
2041 the menubar. If unspecified in a particular domain, the
2042 window-system-provided default pointer is used.
2044 -- Glyph: scrollbar-pointer-glyph
2045 This variable specifies the shape of the mouse pointer when over a
2046 scrollbar. If unspecified in a particular domain, the
2047 window-system-provided default pointer is used.
2049 -- Glyph: toolbar-pointer-glyph
2050 This variable specifies the shape of the mouse pointer when over a
2051 toolbar. If unspecified in a particular domain,
2052 `nontext-pointer-glyph' is used.
2054 Internally, these variables are implemented in
2055 `default-mouse-motion-handler', and thus only take effect when the
2056 mouse moves. That function calls `set-frame-pointer', which sets the
2057 current mouse pointer for a frame.
2059 -- Function: set-frame-pointer frame image-instance
2060 This function sets the mouse pointer of FRAME to the given pointer
2061 image instance. You should not call this function directly. (If
2062 you do, the pointer will change again the next time the mouse
2066 File: lispref.info, Node: Native GUI Widgets, Next: Subwindows, Prev: External Glyphs, Up: Using Glyphs
2068 50.3.6 Native GUI Widgets
2069 -------------------------
2071 A "native widget" is a primitive GUI object defined either by the host
2072 GUI platform or an external toolkit, and accessed from Lisp as a
2077 * Introduction to Widgets:: Native widgets provide tight integration of
2078 GUI features with the platform GUI.
2079 * Lisp API to Native Widgets:: Native widgets are glyphs.
2080 * Layouts:: Specifying composite widgets from Lisp.
2081 * Primitive Widgets:: Catalogue of available native widgets.
2084 File: lispref.info, Node: Introduction to Widgets, Next: Lisp API to Native Widgets, Up: Native GUI Widgets
2086 50.3.6.1 Introduction to Native Widgets and Subwindow Glyphs
2087 ............................................................
2089 Traditionally Emacsen have hidden the GUI apparatus from the Lisp
2090 programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
2091 objects, called "native widgets", in text was added to Lisp. They are
2092 handled as _glyphs_. Unlike traditional XEmacs glyphs such images and
2093 strings, native widgets are opaque to XEmacs, and must be able to
2094 redraw themselves because they are implemented as subwindows, not as
2095 graphics drawn by XEmacs into the text window.
2097 Primitive widgets are coded in C using the underlying GUI toolkit,
2098 and thus are beyond the scope of the _XEmacs Lisp Reference Manual_.
2099 However, composite widgets can be created in Lisp using "layouts,"
2100 which are horizontal or vertical arrays of subwidgets. For example, the
2101 search dialog is formatted using layouts.
2104 File: lispref.info, Node: Lisp API to Native Widgets, Next: Layouts, Prev: Introduction to Widgets, Up: Native GUI Widgets
2106 50.3.6.2 Lisp API to Native Widgets
2107 ...................................
2109 Native widgets are manipulated as _glyphs_ (*note Glyphs::). Thus they
2110 are created using `make-glyph', with a format of one of the widget
2111 types and a `:data' property specific to the widget being instanced.
2113 However, there is a technical difference between widgets and other
2114 kinds of glyphs that is theoretically important. Because widgets are
2115 active (that is, they can respond to user input events themselves), it
2116 is possible for the user to become aware that two appearances of the
2117 "same" glyph are actually separate instances. For example, if a user
2118 changes an image glyph from red to blue, and the buffer containing the
2119 glyph appears in more than one window, the user will perceive all the
2120 appearances to change from red to blue simultaneously. However, suppose
2121 the glyph is a button glyph (_e.g._, as used in the Customize buffer
2122 for the Set, Save, and Done buttons). Then if the Customize buffer
2123 appears in several windows at the same time, and the user clicks on the
2124 button, she will only perceive the button to be depressed in the window
2125 where she clicked the button.
2127 It seems from this example that it is unlikely to be a problem in
2128 practice. When the user is faced with an active widget, it seems likely
2129 that attention will focus on the widget being manipulated, and having
2130 other instances of the widget respond simultaneously might be more
2131 disconcerting than the actual case.
2134 File: lispref.info, Node: Layouts, Next: Primitive Widgets, Prev: Lisp API to Native Widgets, Up: Native GUI Widgets
2139 An XEmacs "layout" is a one-dimensional array of glyphs. It is a
2140 widget for controlling the positioning of children underneath it.
2141 Through the use of nested layouts, a widget hierarchy can be created
2142 which can have the appearance of any standard dialog box or similar
2143 arrangement; all of this is counted as one "glyph" and could appear in
2144 many of the places that expect a single glyph. (There are also "native
2145 layouts", but these are undocumented, as are their uses.)
2147 A layout descriptor is an image instantiator, _i.e._, a vector of
2148 the form `[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]' with format
2149 `layout', and properties
2152 Specifies the orientation of the contained array of glyphs. The
2153 value must be one of the symbols `horizontal' or `vertical'.
2155 `:horizontally-justify'
2156 Specifies the horizontal justification of the items in the array.
2157 The value must be one of the symbols `:right', `:center', or
2160 `:vertically-justify'
2161 Specifies the vertical justification of the items in the array.
2162 The value must be one of the symbols `:top', `:center', or
2166 Specifies justification. #### not understood.
2169 A glyph to place in the border. The value must be an image
2173 The glyphs controlled by the layout. The value must be a list of
2174 image instantiators.
2176 Here is the specification of the search dialog widget created by
2177 `make-search-dialog' in the `dialog-items' library, which makes use of
2182 :orientation horizontal
2183 :vertically-justify top
2184 :horizontally-justify center
2185 :border [string :data "Search"]
2187 ([layout :orientation vertical
2188 :justify top ; implies left also
2190 ([string :data "Search for:"]
2191 [button :descriptor "Match Case"
2193 :selected (not case-fold-search)
2194 :callback (setq case-fold-search
2195 (not case-fold-search))]
2196 [button :descriptor "Regular Expression"
2198 :selected search-dialog-regexp
2199 :callback (setq search-dialog-regexp
2200 (not search-dialog-regexp))]
2201 [button :descriptor "Forwards"
2203 :selected search-dialog-direction
2204 :callback (setq search-dialog-direction t)]
2205 [button :descriptor "Backwards"
2207 :selected (not search-dialog-direction)
2208 :callback (setq search-dialog-direction nil)]
2210 [layout :orientation vertical
2211 :vertically-justify top
2212 :horizontally-justify right
2214 ([edit-field :width 15 :descriptor "" :active t
2216 [button :width 10 :descriptor "Find Next"
2218 (lambda (image-instance event)
2219 (search-dialog-callback ,parent
2222 [button :width 10 :descriptor "Cancel"
2224 (lambda (image-instance event)
2225 (isearch-dehighlight)
2227 (event-channel event)))])])])
2230 File: lispref.info, Node: Primitive Widgets, Prev: Layouts, Up: Native GUI Widgets
2232 50.3.6.4 Primitive Widgets
2233 ..........................
2236 A button widget; either a push button, radio button or toggle
2240 A drop list of selectable items in a widget, for editing text.
2243 A text editing widget.
2246 A static, text-only, widget; for displaying text.
2249 A sliding widget, for showing progress.
2252 A tab widget; a series of user selectable tabs.
2258 A scrollbar widget. (#### Probably not the same as the scrollbar
2259 controlling an Emacs window.)
2262 File: lispref.info, Node: Subwindows, Prev: Native GUI Widgets, Up: Using Glyphs
2267 Subwindows are not currently implemented.
2269 -- Function: subwindowp object
2270 This function returns non-`nil' if OBJECT is a subwindow.
2273 File: lispref.info, Node: Manipulating Glyphs, Next: Glyph Examples, Prev: Using Glyphs, Up: Glyphs
2275 50.4 Manipulating Glyphs
2276 ========================
2278 Each glyphs has properties that may be accessed. Most of these can
2279 also be set after the glyph is initialized, with the exception of the
2280 glyph's type. This is not a real restriction, as it is almost never
2281 useful to create glyphs of types other than `buffer'.
2285 * Glyph Properties:: Accessing and modifying a glyph's properties.
2286 * Glyph Convenience Functions:: Accessing particular properties of a glyph.
2287 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
2288 * Glyph Types:: Each glyph has a particular type.
2291 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Up: Manipulating Glyphs
2293 50.4.1 Glyph Properties
2294 -----------------------
2296 Each glyph has a list of properties, which control all of the aspects of
2297 the glyph's appearance. The following symbols have predefined meanings:
2300 The image used to display the glyph.
2303 Percent above baseline that glyph is to be displayed. Only for
2304 glyphs displayed inside of a buffer.
2307 Whether the glyph contributes to the height of the line it's on.
2308 Only for glyphs displayed inside of a buffer.
2311 Face of this glyph (_not_ a specifier).
2313 -- Function: set-glyph-property glyph property value &optional locale
2315 This function changes a property of a GLYPH.
2317 For built-in properties, the actual value of the property is a
2318 specifier and you cannot change this; but you can change the
2319 specifications within the specifier, and that is what this
2320 function will do. The glyph face is an exception; it is a face
2321 name (a symbol) or a face object, not a specifier. (The face
2322 properties themselves are typically specifiers.) For user-defined
2323 properties, you can use this function to either change the actual
2324 value of the property or, if this value is a specifier, change the
2325 specifications within it.
2327 If PROPERTY is a built-in property, the specifications to be added
2328 to this property can be supplied in many different ways:
2330 * If VALUE is a simple instantiator (e.g. a string naming a
2331 pixmap filename) or a list of instantiators, then the
2332 instantiator(s) will be added as a specification of the
2333 property for the given LOCALE (which defaults to `global' if
2336 * If VALUE is a list of specifications (each of which is a cons
2337 of a locale and a list of instantiators), then LOCALE must be
2338 `nil' (it does not make sense to explicitly specify a locale
2339 in this case), and specifications will be added as given.
2341 * If VALUE is a specifier (as would be returned by
2342 `glyph-property' if no LOCALE argument is given), then some
2343 or all of the specifications in the specifier will be added
2344 to the property. In this case, the function is really
2345 equivalent to `copy-specifier' and LOCALE has the same
2346 semantics (if it is a particular locale, the specification
2347 for the locale will be copied; if a locale type,
2348 specifications for all locales of that type will be copied;
2349 if `nil' or `all', then all specifications will be copied).
2351 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
2352 `append', `remove-tag-set-prepend', `remove-tag-set-append',
2353 `remove-locale', `remove-locale-type', or `remove-all'. See
2354 `copy-specifier' and `add-spec-to-specifier' for a description of
2355 what each of these means. Most of the time, you do not need to
2356 worry about this argument; the default behavior usually is fine.
2358 In general, it is OK to pass an instance object (e.g. as returned
2359 by `glyph-property-instance') as an instantiator in place of an
2360 actual instantiator. In such a case, the instantiator used to
2361 create that instance object will be used (for example, if you set
2362 a font-instance object as the value of the `font' property, then
2363 the font name used to create that object will be used instead).
2364 In some cases, however, doing this conversion does not make sense,
2365 and this will be noted in the documentation for particular types
2366 of instance objects.
2368 If PROPERTY is not a built-in property, then this function will
2369 simply set its value if LOCALE is `nil'. However, if LOCALE is
2370 given, then this function will attempt to add VALUE as the
2371 instantiator for the given LOCALE, using `add-spec-to-specifier'.
2372 If the value of the property is not a specifier, it will
2373 automatically be converted into a `generic' specifier.
2375 -- Function: glyph-property glyph property &optional locale
2376 This function returns GLYPH's value of the given PROPERTY.
2378 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
2379 be returned. For built-in properties, this will be a specifier
2380 object of a type appropriate to the property (e.g. a font or color
2381 specifier). For other properties, this could be anything.
2383 If LOCALE is supplied, then instead of returning the actual value,
2384 the specification(s) for the given locale or locale type will be
2385 returned. This will only work if the actual value of PROPERTY is
2386 a specifier (this will always be the case for built-in properties,
2387 but may or may not apply to user-defined properties). If the
2388 actual value of PROPERTY is not a specifier, this value will
2389 simply be returned regardless of LOCALE.
2391 The return value will be a list of instantiators (e.g. vectors
2392 specifying pixmap data), or a list of specifications, each of
2393 which is a cons of a locale and a list of instantiators.
2394 Specifically, if LOCALE is a particular locale (a buffer, window,
2395 frame, device, or `global'), a list of instantiators for that
2396 locale will be returned. Otherwise, if LOCALE is a locale type
2397 (one of the symbols `buffer', `window', `frame', or `device'), the
2398 specifications for all locales of that type will be returned.
2399 Finally, if LOCALE is `all', the specifications for all locales of
2400 all types will be returned.
2402 The specifications in a specifier determine what the value of
2403 PROPERTY will be in a particular "domain" or set of circumstances,
2404 which is typically a particular Emacs window along with the buffer
2405 it contains and the frame and device it lies within. The value is
2406 derived from the instantiator associated with the most specific
2407 locale (in the order buffer, window, frame, device, and `global')
2408 that matches the domain in question. In other words, given a
2409 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
2410 will first be searched for a specification whose locale is the
2411 buffer contained within that window; then for a specification
2412 whose locale is the window itself; then for a specification whose
2413 locale is the frame that the window is contained within; etc. The
2414 first instantiator that is valid for the domain (usually this
2415 means that the instantiator is recognized by the device [i.e. the
2416 X server or TTY device] that the domain is on). The function
2417 `glyph-property-instance' actually does all this, and is used to
2418 determine how to display the glyph.
2420 -- Function: glyph-property-instance glyph property &optional domain
2422 This function returns the instance of GLYPH's PROPERTY in the
2425 Under most circumstances, DOMAIN will be a particular window, and
2426 the returned instance describes how the specified property
2427 actually is displayed for that window and the particular buffer in
2428 it. Note that this may not be the same as how the property
2429 appears when the buffer is displayed in a different window or
2430 frame, or how the property appears in the same window if you
2431 switch to another buffer in that window; and in those cases, the
2432 returned instance would be different.
2434 The returned instance is an image-instance object, and you can
2435 query it using the appropriate image instance functions. For
2436 example, you could use `image-instance-depth' to find out the
2437 depth (number of color planes) of a pixmap displayed in a
2438 particular window. The results might be different from the
2439 results you would get for another window (perhaps the user
2440 specified a different image for the frame that window is on; or
2441 perhaps the same image was specified but the window is on a
2442 different X server, and that X server has different color
2443 capabilities from this one).
2445 DOMAIN defaults to the selected window if omitted.
2447 DOMAIN can be a frame or device, instead of a window. The value
2448 returned for such a domain is used in special circumstances when a
2449 more specific domain does not apply; for example, a frame value
2450 might be used for coloring a toolbar, which is conceptually
2451 attached to a frame rather than a particular window. The value is
2452 also useful in determining what the value would be for a
2453 particular window within the frame or device, if it is not
2454 overridden by a more specific specification.
2456 If PROPERTY does not name a built-in property, its value will
2457 simply be returned unless it is a specifier object, in which case
2458 it will be instanced using `specifier-instance'.
2460 Optional arguments DEFAULT and NO-FALLBACK are the same as in
2461 `specifier-instance'. *Note Specifiers::.
2463 -- Function: remove-glyph-property glyph property &optional locale
2465 This function removes a property from a glyph. For built-in
2466 properties, this is analogous to `remove-specifier'. *Note
2467 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
2468 TAG-SET, and EXACT-P arguments.
2471 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Manipulating Glyphs
2473 50.4.2 Glyph Convenience Functions
2474 ----------------------------------
2476 The following functions are provided for working with specific
2477 properties of a glyph. Note that these are exactly like calling the
2478 general functions described above and passing in the appropriate value
2481 Remember that if you want to determine the "value" of a specific
2482 glyph property, you probably want to use the `*-instance' functions.
2483 For example, to determine whether a glyph contributes to its line
2484 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
2485 latter will return a boolean specifier or a list of specifications, and
2486 you probably aren't concerned with these.)
2488 -- Function: glyph-image glyph &optional locale
2489 This function is equivalent to calling `glyph-property' with a
2490 property of `image'. The return value will be an image specifier
2491 if LOCALE is `nil' or omitted; otherwise, it will be a
2492 specification or list of specifications.
2494 -- Function: set-glyph-image glyph spec &optional locale tag-set
2496 This function is equivalent to calling `set-glyph-property' with a
2497 property of `image'.
2499 -- Function: glyph-image-instance glyph &optional domain default
2501 This function returns the instance of GLYPH's image in the given
2502 DOMAIN, and is equivalent to calling `glyph-property-instance'
2503 with a property of `image'. The return value will be an image
2506 Normally DOMAIN will be a window or `nil' (meaning the selected
2507 window), and an instance object describing how the image appears
2508 in that particular window and buffer will be returned.
2510 -- Function: glyph-contrib-p glyph &optional locale
2511 This function is equivalent to calling `glyph-property' with a
2512 property of `contrib-p'. The return value will be a boolean
2513 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
2514 specification or list of specifications.
2516 -- Function: set-glyph-contrib-p glyph spec &optional locale tag-set
2518 This function is equivalent to calling `set-glyph-property' with a
2519 property of `contrib-p'.
2521 -- Function: glyph-contrib-p-instance glyph &optional domain default
2523 This function returns whether the glyph contributes to its line
2524 height in the given DOMAIN, and is equivalent to calling
2525 `glyph-property-instance' with a property of `contrib-p'. The
2526 return value will be either `nil' or `t'. (Normally DOMAIN will be
2527 a window or `nil', meaning the selected window.)
2529 -- Function: glyph-baseline glyph &optional locale
2530 This function is equivalent to calling `glyph-property' with a
2531 property of `baseline'. The return value will be a specifier if
2532 LOCALE is `nil' or omitted; otherwise, it will be a specification
2533 or list of specifications.
2535 -- Function: set-glyph-baseline glyph spec &optional locale tag-set
2537 This function is equivalent to calling `set-glyph-property' with a
2538 property of `baseline'.
2540 -- Function: glyph-baseline-instance glyph &optional domain default
2542 This function returns the instance of GLYPH's baseline value in
2543 the given DOMAIN, and is equivalent to calling
2544 `glyph-property-instance' with a property of `baseline'. The
2545 return value will be an integer or `nil'.
2547 Normally DOMAIN will be a window or `nil' (meaning the selected
2548 window), and an instance object describing the baseline value
2549 appears in that particular window and buffer will be returned.
2551 -- Function: glyph-face glyph
2552 This function returns the face of GLYPH. (Remember, this is not a
2553 specifier, but a simple property.)
2555 -- Function: set-glyph-face glyph face
2556 This function changes the face of GLYPH to FACE.
2559 File: lispref.info, Node: Glyph Dimensions, Next: Glyph Types, Prev: Glyph Convenience Functions, Up: Manipulating Glyphs
2561 50.4.3 Glyph Dimensions
2562 -----------------------
2564 -- Function: glyph-width glyph &optional window
2565 This function returns the width of GLYPH on WINDOW. This may not
2566 be exact as it does not take into account all of the context that
2569 -- Function: glyph-ascent glyph &optional window
2570 This function returns the ascent value of GLYPH on WINDOW. This
2571 may not be exact as it does not take into account all of the
2572 context that redisplay will.
2574 -- Function: glyph-descent glyph &optional window
2575 This function returns the descent value of GLYPH on WINDOW. This
2576 may not be exact as it does not take into account all of the
2577 context that redisplay will.
2579 -- Function: glyph-height glyph &optional window
2580 This function returns the height of GLYPH on WINDOW. (This is
2581 equivalent to the sum of the ascent and descent values.) This may
2582 not be exact as it does not take into account all of the context
2583 that redisplay will.
2586 File: lispref.info, Node: Glyph Types, Prev: Glyph Dimensions, Up: Manipulating Glyphs
2591 Each glyph has a particular type, which controls how the glyph's image
2592 is generated. Each glyph type has a corresponding list of allowable
2593 image instance types that can be generated. When you call
2594 `glyph-image-instance' to retrieve the image instance of a glyph,
2595 XEmacs does the equivalent of calling `make-image-instance' and passing
2596 in DEST-TYPES the list of allowable image instance types for the
2599 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
2600 extent, in the modeline, and in the toolbar. Their image can be
2601 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
2604 * `pointer' glyphs can be used to specify the mouse pointer. Their
2605 image can be instantiated as `pointer'.
2607 * `icon' glyphs can be used to specify the icon used when a frame is
2608 iconified. Their image can be instantiated as `mono-pixmap' and
2611 -- Function: glyph-type glyph
2612 This function returns the type of the given glyph. The return
2613 value will be a symbol, one of `buffer', `pointer', or `icon'.
2615 -- Function: valid-glyph-type-p glyph-type
2616 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
2618 -- Function: glyph-type-list
2619 This function returns a list of valid glyph types.
2621 -- Function: buffer-glyph-p object
2622 This function returns non-`nil' if OBJECT is a glyph of type
2625 -- Function: icon-glyph-p object
2626 This function returns non-`nil' if OBJECT is a glyph of type
2629 -- Function: pointer-glyph-p object
2630 This function returns non-`nil' if OBJECT is a glyph of type
2634 File: lispref.info, Node: Glyph Examples, Prev: Manipulating Glyphs, Up: Glyphs
2639 For many applications, displaying graphics is a simple process: you
2640 create a glyph, and then you insert it into a buffer.
2642 The easiest way to create a glyph is to use a file that contains a
2643 graphical image, such as a JPEG, TIFF, or PNG file:
2645 ;; Create a glyph from a JPEG file:
2646 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2648 ;; Create a glyph from a XPM file:
2649 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
2651 ;; Create a glyph from a PNG file:
2652 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
2654 ;; Create a glyph from a TIFF file:
2655 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
2657 The parameters passed to `make-glyph' are called "Image Specifiers",
2658 and can handle more image types than those shown above. You can also
2659 put the raw image data into a string (e.g., if you put the contents of
2660 a JPEG file into a string), and use that to create a glyph. *Note
2661 Image Specifiers::, for more information.
2663 *Caution*: In order for XEmacs to read a particular graphics file
2664 format, support for that format must have been compiled into
2665 XEmacs. It's possible, although somewhat unlikely, for XEmacs to
2666 have been compiled without support for any of the various graphics
2667 file formats. To see what graphics formats your particular
2668 version of XEmacs supports, use `M-x describe-installation'.
2670 To programmatically query whether or not a particular file format
2671 is supported, you can use the `featurep' function, with one of:
2672 `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'. For an
2673 up-to-date list, *Note Image Specifiers::. Example:
2675 ;; Returns `t' if TIFF is supported:
2680 ;; Returns a list of `t' or `nil', depending on whether or not the
2681 ;; corresponding feature is supported:
2682 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
2683 '(gif tiff jpeg xpm png))
2686 Once you have a glyph, you can then insert it into a buffer.
2689 ;; Use this function to insert a glyph at the left edge of point in the
2690 ;; current buffer. Any existing glyph at this location is replaced.
2691 (defun insert-glyph (gl)
2692 "Insert a glyph at the left edge of point."
2693 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
2694 ;; to (hopefully) not conflict with any
2695 ;; other properties. Change it if
2698 ;; First, check to see if one of our extents already exists at
2699 ;; point. For ease-of-programming, we are creating and using our
2700 ;; own extents (multiple extents are allowed to exist/overlap at the
2701 ;; same point, and it's quite possible for other applications to
2702 ;; embed extents in the current buffer without your knowledge).
2703 ;; Basically, if an extent, with the property stored in "prop",
2704 ;; exists at point, we assume that it is one of ours, and we re-use
2705 ;; it (this is why it is important for the property stored in "prop"
2706 ;; to be unique, and only used by us).
2707 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
2709 ;; If an extent does not already exist, create a zero-length
2710 ;; extent, and give it our special property.
2711 (setq extent (make-extent (point) (point) (current-buffer)))
2712 (set-extent-property extent prop t)
2714 ;; Display the glyph by storing it as the extent's "begin-glyph".
2715 (set-extent-property extent 'begin-glyph gl)
2718 ;; You can then use this function like:
2719 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2720 ;; This will insert the glyph at point.
2722 ;; Here's an example of how to insert two glyphs side-by-side, at point
2723 ;; (using the above code):
2725 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
2726 ;; Create a new extent at point. We can't simply call "insert-glyph",
2727 ;; as "insert-glyph" will simply replace the first glyph with the
2729 (setq extent (make-extent (point) (point) (current-buffer)))
2730 ;; Here, we're only setting the 'myimage property in case we need
2731 ;; to later identify/locate/reuse this particular extent.
2732 (set-extent-property extent 'myimage t)
2733 (set-extent-property extent 'begin-glyph
2734 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
2737 Here are the gory details:
2739 * Glyphs are displayed by attaching them to extents (see *Note
2740 Extents::), either to the beginning or the end of extents.
2742 Note that extents can be used for many things, and not just for
2743 displaying images (although, in the above example, we are creating
2744 our own extent for the sole purpose of displaying an image).
2745 Also, note that multiple extents are allowed to exist at the same
2746 position, and they can overlap.
2748 * Glyphs are often displayed inside the text area (alongside text).
2749 This is the default.
2751 Although glyphs can also be displayed in the margins, how to do
2752 this will not be described here. For more information on this, see
2753 *Note Annotation Basics:: (look for information on "layout types")
2754 and *Note Extent Properties:: (look for `begin-glyph-layout' and
2755 `end-glyph-layout').
2757 * The easiest way to insert a glyph into text is to create a
2758 zero-length extent at the point where you want the glyph to appear.
2760 Note that zero-length extents are attached to the character to the
2761 right of the extent; deleting this character will also delete the
2764 * It's often a good idea to assign a unique property to the
2765 newly-created extent, in case you later want to locate it, and
2766 replace any existing glyph with a different one (or just delete
2767 the existing one). In the above example, we are using "myimage"
2768 as our (hopefully) unique property name.
2770 If you need to locate all of the extents, you'll have to use
2771 functions like `extent-list' or `next-extent', or provide
2772 additional parameters to the `extent-at' function. Assigning a
2773 unique property to the extent makes it easy to locate your
2774 extents; for example, `extent-list' can return only those extents
2775 with a particular property. *Note Finding Extents::, and *Note
2776 Mapping Over Extents::, for more information.
2778 * Glyphs are displayed by assigning then to the `begin-glyph' or
2779 `end-glyph' property of the extent. For zero-length extents, it
2780 doesn't really matter if you assign the glyph to the `begin-glyph'
2781 or `end-glyph' property, as they are both at the same location;
2782 however, for non-zero-length extents (extents that cover one or
2783 more characters of text), it does matter which one you use.
2785 Assigning `nil' to the `begin-glyph' or `end-glyph' property will
2786 delete any existing glyph. In this case, you may also want to
2787 delete the extent, assuming that the extent is used for no other
2790 * If you happen to insert two glyphs, side-by-side, note that the
2791 example `insert-glyph' function will have trouble, if it's again
2792 used at the same point (it can only locate one of the two extents).
2793 *Note Finding Extents::, and *Note Mapping Over Extents::, for more
2794 information on locating extents in a buffer.
2796 * Among other things, glyphs provide a way of displaying graphics
2797 alongside text. Note, however, that glyphs only provide a way of
2798 displaying graphics; glyphs are not actually part of the text, and
2799 are only displayed alongside the text. If you save the text in
2800 the buffer, the graphics are not saved. The low-level glyph code
2801 does not provide a way of saving graphics with the text. If you
2802 need to save graphics and text, you have to write your own code to
2803 do this, and this topic is outside the scope of this discussion.
2807 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
2812 An "annotation" is a pixmap or string that is not part of a buffer's
2813 text but is displayed next to a particular location in a buffer.
2814 Annotations can be displayed intermixed with text, in any whitespace at
2815 the beginning or end of a line, or in a special area at the left or
2816 right side of the frame called a "margin", whose size is controllable.
2817 Annotations are implemented using extents (*note Extents::); but you
2818 can work with annotations without knowing how extents work.
2822 * Annotation Basics:: Introduction to annotations.
2823 * Annotation Primitives:: Creating and deleting annotations.
2824 * Annotation Properties:: Retrieving and changing the characteristics
2826 * Margin Primitives:: Controlling the size of the margins.
2827 * Locating Annotations:: Looking for annotations in a buffer.
2828 * Annotation Hooks:: Hooks called at certain times during an
2829 annotation's lifetime.
2832 File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
2834 51.1 Annotation Basics
2835 ======================
2837 Marginal annotations are notes associated with a particular location in
2838 a buffer. They may be displayed in a margin created on the left-hand or
2839 right-hand side of the frame, in any whitespace at the beginning or end
2840 of a line, or inside of the text itself. Every annotation may have an
2841 associated action to be performed when the annotation is selected. The
2842 term "annotation" is used to refer to an individual note. The term
2843 "margin" is generically used to refer to the whitespace before the
2844 first character on a line or after the last character on a line.
2846 Each annotation has the following characteristics:
2848 This is a glyph object and is used as the displayed representation
2852 If given, this glyph is used as the displayed representation of
2853 the annotation when the mouse is pressed down over the annotation.
2856 The face with which to display the glyph.
2859 Which side of the text (left or right) the annotation is displayed
2863 If non-`nil', this field must contain a function capable of being
2864 the first argument to `funcall'. This function is normally
2865 evaluated with a single argument, the value of the DATA field,
2866 each time the annotation is selected. However, if the WITH-EVENT
2867 parameter to `make-annotation' is non-`nil', the function is
2868 called with two arguments. The first argument is the same as
2869 before, and the second argument is the event (a button-up event,
2870 usually) that activated the annotation.
2873 Not used internally. This field can contain any E-Lisp object.
2874 It is passed as the first argument to ACTION described above.
2877 A menu displayed when the right mouse button is pressed over the
2880 The margin is divided into "outside" and "inside". The outside
2881 margin is space on the left or right side of the frame which normal text
2882 cannot be displayed in. The inside margin is that space between the
2883 leftmost or rightmost point at which text can be displayed and where the
2884 first or last character actually is.
2886 There are four different "layout types" which affect the exact
2887 location an annotation appears.
2890 The annotation is placed in the outside margin area. as close as
2891 possible to the edge of the frame. If the outside margin is not
2892 wide enough for an annotation to fit, it is not displayed.
2895 The annotation is placed in the inside margin area, as close as
2896 possible to the edge of the frame. If the inside margin is not
2897 wide enough for the annotation to fit, it will be displayed using
2898 any available outside margin space if and only if the specifier
2899 `use-left-overflow' or `use-right-overflow' (depending on which
2900 side the annotation appears in) is non-`nil'.
2903 The annotation is placed in the inside margin area, as close as
2904 possible to the first or last non-whitespace character on a line.
2905 If the inside margin is not wide enough for the annotation to fit,
2906 it will be displayed if and only if the specifier
2907 `use-left-overflow' or `use-right-overflow' (depending on which
2908 side the annotation appears in) is non-`nil'.
2911 The annotation is placed at the position it is inserted. It will
2912 create enough space for itself inside of the text area. It does
2913 not take up a place in the logical buffer, only in the display of
2916 The current layout policy is that all `whitespace' annotations are
2917 displayed first. Next, all `inside-margin' annotations are displayed
2918 using any remaining space. Finally as many `outside-margin'
2919 annotations are displayed as possible. The `text' annotations will
2920 always display as they create their own space to display in.
2923 File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
2925 51.2 Annotation Primitives
2926 ==========================
2928 -- Function: make-annotation glyph &optional position layout buffer
2929 with-event d-glyph rightp
2930 This function creates a marginal annotation at position POSITION in
2931 BUFFER. The annotation is displayed using GLYPH, which should be
2932 a glyph object or a string, and is positioned using layout policy
2933 LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
2934 `whitespace' is used. If BUFFER is `nil', the current buffer is
2937 If WITH-EVENT is non-`nil', then when an annotation is activated,
2938 the triggering event is passed as the second arg to the annotation
2939 function. If D-GLYPH is non-`nil' then it is used as the glyph
2940 that will be displayed when button1 is down. If RIGHTP is
2941 non-`nil' then the glyph will be displayed on the right side of
2942 the buffer instead of the left.
2944 The newly created annotation is returned.
2946 -- Function: delete-annotation annotation
2947 This function removes ANNOTATION from its buffer. This does not
2948 modify the buffer text.
2950 -- Function: annotationp annotation
2951 This function returns `t' if ANNOTATION is an annotation, `nil'
2955 File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
2957 51.3 Annotation Properties
2958 ==========================
2960 -- Function: annotation-glyph annotation
2961 This function returns the glyph object used to display ANNOTATION.
2963 -- Function: set-annotation-glyph annotation glyph &optional layout
2965 This function sets the glyph of ANNOTATION to GLYPH, which should
2966 be a glyph object. If LAYOUT is non-`nil', set the layout policy
2967 of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
2968 side of the buffer at which the annotation is displayed to the
2969 given side. The new value of `annotation-glyph' is returned.
2971 -- Function: annotation-down-glyph annotation
2972 This function returns the glyph used to display ANNOTATION when
2973 the left mouse button is depressed on the annotation.
2975 -- Function: set-annotation-down-glyph annotation glyph
2976 This function returns the glyph used to display ANNOTATION when
2977 the left mouse button is depressed on the annotation to GLYPH,
2978 which should be a glyph object.
2980 -- Function: annotation-face annotation
2981 This function returns the face associated with ANNOTATION.
2983 -- Function: set-annotation-face annotation face
2984 This function sets the face associated with ANNOTATION to FACE.
2986 -- Function: annotation-layout annotation
2987 This function returns the layout policy of ANNOTATION.
2989 -- Function: set-annotation-layout annotation layout
2990 This function sets the layout policy of ANNOTATION to LAYOUT.
2992 -- Function: annotation-side annotation
2993 This function returns the side of the buffer that ANNOTATION is
2994 displayed on. Return value is a symbol, either `left' or `right'.
2996 -- Function: annotation-data annotation
2997 This function returns the data associated with ANNOTATION.
2999 -- Function: set-annotation-data annotation data
3000 This function sets the data field of ANNOTATION to DATA. DATA is
3003 -- Function: annotation-action annotation
3004 This function returns the action associated with ANNOTATION.
3006 -- Function: set-annotation-action annotation action
3007 This function sets the action field of ANNOTATION to ACTION.
3008 ACTION is returned..
3010 -- Function: annotation-menu annotation
3011 This function returns the menu associated with ANNOTATION.
3013 -- Function: set-annotation-menu annotation menu
3014 This function sets the menu associated with ANNOTATION to MENU.
3015 This menu will be displayed when the right mouse button is pressed
3016 over the annotation.
3018 -- Function: annotation-visible annotation
3019 This function returns `t' if there is enough available space to
3020 display ANNOTATION, `nil' otherwise.
3022 -- Function: annotation-width annotation
3023 This function returns the width of ANNOTATION in pixels.
3025 -- Function: hide-annotation annotation
3026 This function removes ANNOTATION's glyph, making it invisible.
3028 -- Function: reveal-annotation annotation
3029 This function restores ANNOTATION's glyph, making it visible.
3032 File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
3034 51.4 Locating Annotations
3035 =========================
3037 -- Function: annotations-in-region start end buffer
3038 This function returns a list of all annotations in BUFFER which
3039 are between START and END inclusively.
3041 -- Function: annotations-at &optional position buffer
3042 This function returns a list of all annotations at POSITION in
3043 BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
3044 the current buffer is used.
3046 -- Function: annotation-list &optional buffer
3047 This function returns a list of all annotations in BUFFER. If
3048 BUFFER is `nil', the current buffer is used.
3050 -- Function: all-annotations
3051 This function returns a list of all annotations in all buffers in
3055 File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
3057 51.5 Margin Primitives
3058 ======================
3060 The margin widths are controllable on a buffer-local, window-local,
3061 frame-local, device-local, or device-type-local basis through the use
3062 of specifiers. *Note Specifiers::.
3064 -- Specifier: left-margin-width
3065 This is a specifier variable controlling the width of the left
3066 outside margin, in characters. Use `set-specifier' to change its
3069 -- Specifier: right-margin-width
3070 This is a specifier variable controlling the width of the right
3071 outside margin, in characters. Use `set-specifier' to change its
3074 -- Specifier: use-left-overflow
3075 If non-`nil', use the left outside margin as extra whitespace when
3076 displaying `whitespace' and `inside-margin' annotations. Defaults
3077 to `nil'. This is a specifier variable; use `set-specifier' to
3080 -- Specifier: use-right-overflow
3081 If non-`nil', use the right outside margin as extra whitespace when
3082 displaying `whitespace' and `inside-margin' annotations. Defaults
3083 to `nil'. This is a specifier variable; use `set-specifier' to
3086 -- Function: window-left-margin-pixel-width &optional window
3087 This function returns the width in pixels of the left outside
3088 margin of WINDOW. If WINDOW is `nil', the selected window is
3091 -- Function: window-right-margin-pixel-width &optional window
3092 This function returns the width in pixels of the right outside
3093 margin of WINDOW. If WINDOW is `nil', the selected window is
3096 The margin colors are controlled by the faces `left-margin' and
3097 `right-margin'. These can be set using the X resources
3098 `Emacs.left-margin.background' and `Emacs.left-margin.foreground';
3099 likewise for the right margin.
3102 File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
3104 51.6 Annotation Hooks
3105 =====================
3107 The following three hooks are provided for use with the marginal
3110 `before-delete-annotation-hook'
3111 This hook is called immediately before an annotation is destroyed.
3112 It is passed a single argument, the annotation being destroyed.
3114 `after-delete-annotation-hook'
3115 This normal hook is called immediately after an annotation is
3118 `make-annotation-hook'
3119 This hook is called immediately after an annotation is created.
3120 It is passed a single argument, the newly created annotation.
3123 File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
3128 This chapter describes a number of other features related to the display
3129 that XEmacs presents to the user.
3133 * Refresh Screen:: Clearing the screen and redrawing everything on it.
3134 * Truncation:: Folding or wrapping long text lines.
3135 * The Echo Area:: Where messages are displayed.
3136 * Warnings:: Display of Warnings.
3137 * Invisible Text:: Hiding part of the buffer text.
3138 * Selective Display:: Hiding part of the buffer text (the old way).
3139 * Overlay Arrow:: Display of an arrow to indicate position.
3140 * Temporary Displays:: Displays that go away automatically.
3141 * Blinking:: How XEmacs shows the matching open parenthesis.
3142 * Usual Display:: The usual conventions for displaying nonprinting chars.
3143 * Display Tables:: How to specify other conventions.
3144 * Beeping:: Audible signal to the user.
3147 File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
3149 52.1 Refreshing the Screen
3150 ==========================
3152 The function `redraw-frame' redisplays the entire contents of a given
3153 frame. *Note Frames::.
3155 -- Function: redraw-frame &optional frame no-preempt
3156 This function clears and redisplays frame FRAME.
3158 FRAME defaults to the selected frame if omitted.
3160 Normally, redisplay is preempted as normal if input arrives.
3161 However, if optional second arg NO-PREEMPT is non-`nil', redisplay
3162 will not stop for input and is guaranteed to proceed to completion.
3164 Even more powerful is `redraw-display':
3166 -- Command: redraw-display &optional device
3167 This function redraws all frames on DEVICE marked as having their
3168 image garbled. DEVICE defaults to the selected device. If DEVICE
3169 is `t', all devices will have their frames checked.
3171 Processing user input takes absolute priority over redisplay. If you
3172 call these functions when input is available, they do nothing
3173 immediately, but a full redisplay does happen eventually--after all the
3174 input has been processed.
3176 Normally, suspending and resuming XEmacs also refreshes the screen.
3177 Some terminal emulators record separate contents for display-oriented
3178 programs such as XEmacs and for ordinary sequential display. If you are
3179 using such a terminal, you might want to inhibit the redisplay on
3180 resumption. *Note Suspending XEmacs::.
3182 -- Variable: no-redraw-on-reenter
3183 This variable controls whether XEmacs redraws the entire screen
3184 after it has been suspended and resumed. Non-`nil' means yes,
3187 The above functions do not actually cause the display to be updated;
3188 rather, they clear out the internal display records that XEmacs
3189 maintains, so that the next time the display is updated it will be
3190 redrawn from scratch. Normally this occurs the next time that
3191 `next-event' or `sit-for' is called; however, a display update will not
3192 occur if there is input pending. *Note Command Loop::.
3194 -- Function: force-cursor-redisplay &optional frame
3195 This function causes an immediate update of the cursor on FRAME,
3196 which defaults to the selected frame.
3199 File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
3204 When a line of text extends beyond the right edge of a window, the line
3205 can either be truncated or continued on the next line. When a line is
3206 truncated, this is normally shown with a `\' in the rightmost column of
3207 the window on X displays, and with a `$' on TTY devices. When a line
3208 is continued or "wrapped" onto the next line, this is shown with a
3209 curved arrow in the rightmost column of the window (or with a `\' on
3210 TTY devices). The additional screen lines used to display a long text
3211 line are called "continuation" lines.
3213 Normally, whenever line truncation is in effect for a particular
3214 window, a horizontal scrollbar is displayed in that window if the
3215 device supports scrollbars. *Note Scrollbars::.
3217 Note that continuation is different from filling; continuation
3218 happens on the screen only, not in the buffer contents, and it breaks a
3219 line precisely at the right margin, not at a word boundary. *Note
3222 -- User Option: truncate-lines
3223 This buffer-local variable controls how XEmacs displays lines that
3224 extend beyond the right edge of the window. If it is non-`nil',
3225 then XEmacs does not display continuation lines; rather each line
3226 of text occupies exactly one screen line, and a backslash appears
3227 at the edge of any line that extends to or beyond the edge of the
3228 window. The default is `nil'.
3230 If the variable `truncate-partial-width-windows' is non-`nil',
3231 then truncation is always used for side-by-side windows (within one
3232 frame) regardless of the value of `truncate-lines'.
3234 -- User Option: default-truncate-lines
3235 This variable is the default value for `truncate-lines', for
3236 buffers that do not have local values for it.
3238 -- User Option: truncate-partial-width-windows
3239 This variable controls display of lines that extend beyond the
3240 right edge of the window, in side-by-side windows (*note Splitting
3241 Windows::). If it is non-`nil', these lines are truncated;
3242 otherwise, `truncate-lines' says what to do with them.
3244 The backslash and curved arrow used to indicate truncated or
3245 continued lines are only defaults, and can be changed. These images
3246 are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
3247 flexibility in how glyphs can be controlled. (This differs from FSF
3248 Emacs, which uses display tables to control these images.)
3250 For details, *Note Redisplay Glyphs::.
3253 File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
3258 The "echo area" is used for displaying messages made with the `message'
3259 primitive, and for echoing keystrokes. It is not the same as the
3260 minibuffer, despite the fact that the minibuffer appears (when active)
3261 in the same place on the screen as the echo area. The `XEmacs Lisp
3262 Reference Manual' specifies the rules for resolving conflicts between
3263 the echo area and the minibuffer for use of that screen space (*note
3264 The Minibuffer: (xemacs)Minibuffer.). Error messages appear in the
3265 echo area; see *Note Errors::.
3267 You can write output in the echo area by using the Lisp printing
3268 functions with `t' as the stream (*note Output Functions::), or as
3271 -- Function: message string &rest arguments
3272 This function displays a one-line message in the echo area. The
3273 argument STRING is similar to a C language `printf' control
3274 string. See `format' in *Note String Conversion::, for the details
3275 on the conversion specifications. `message' returns the
3278 In batch mode, `message' prints the message text on the standard
3279 error stream, followed by a newline.
3281 If STRING is `nil', `message' clears the echo area. If the
3282 minibuffer is active, this brings the minibuffer contents back onto
3283 the screen immediately.
3285 (message "Minibuffer depth is %d."
3287 -| Minibuffer depth is 0.
3288 => "Minibuffer depth is 0."
3290 ---------- Echo Area ----------
3291 Minibuffer depth is 0.
3292 ---------- Echo Area ----------
3294 In addition to only displaying a message, XEmacs allows you to
3295 "label" your messages, giving you fine-grained control of their
3296 display. Message label is a symbol denoting the message type. Some
3297 standard labels are:
3299 * `message'--default label used by the `message' function;
3301 * `error'--default label used for reporting errors;
3303 * `progress'--progress indicators like `Converting... 45%' (not
3306 * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
3309 * `command'--helper command messages like `Mark set' (not logged by
3312 * `no-log'--messages that should never be logged
3314 Several messages may be stacked in the echo area at once. Lisp
3315 programs may access these messages, or remove them as appropriate, via
3318 -- Function: display-message label message &optional frame stdout-p
3319 This function displays MESSAGE (a string) labeled as LABEL, as
3322 The FRAME argument specifies the frame to whose minibuffer the
3323 message should be printed. This is currently unimplemented. The
3324 STDOUT-P argument is used internally.
3326 (display-message 'command "Mark set")
3328 -- Function: lmessage label string &rest arguments
3329 This function displays a message STRING with label LABEL. It is
3330 similar to `message' in that it accepts a `printf'-like strings
3331 and any number of arguments.
3333 ;; Display a command message.
3334 (lmessage 'command "Comment column set to %d" comment-column)
3336 ;; Display a progress message.
3337 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
3339 ;; Display a message that should not be logged.
3340 (lmessage 'no-log "Done")
3342 -- Function: clear-message &optional label frame stdout-p no-restore
3343 This function remove any message with the given LABEL from the
3344 message-stack, erasing it from the echo area if it's currently
3347 If a message remains at the head of the message-stack and
3348 NO-RESTORE is `nil', it will be displayed. The string which
3349 remains in the echo area will be returned, or `nil' if the
3350 message-stack is now empty. If LABEL is `nil', the entire
3351 message-stack is cleared.
3353 ;; Show a message, wait for 2 seconds, and restore old minibuffer
3355 (message "A message")
3358 (lmessage 'my-label "Newsflash! Newsflash!")
3359 -| Newsflash! Newsflash!
3360 => "Newsflash! Newsflash!"
3362 (clear-message 'my-label)
3366 Unless you need the return value or you need to specify a label,
3367 you should just use `(message nil)'.
3369 -- Function: current-message &optional frame
3370 This function returns the current message in the echo area, or
3371 `nil'. The FRAME argument is currently unused.
3373 Some of the messages displayed in the echo area are also recorded in
3374 the ` *Message-Log*' buffer. Exactly which messages will be recorded
3375 can be tuned using the following variables.
3377 -- User Option: log-message-max-size
3378 This variable specifies the maximum size of the ` *Message-log*'
3381 -- Variable: log-message-ignore-labels
3382 This variable specifies the labels whose messages will not be
3383 logged. It should be a list of symbols.
3385 -- Variable: log-message-ignore-regexps
3386 This variable specifies the regular expressions matching messages
3387 that will not be logged. It should be a list of regular
3390 Normally, packages that generate messages that might need to be
3391 ignored should label them with `progress', `prompt', or `no-log',
3392 so they can be filtered by `log-message-ignore-labels'.
3394 -- Variable: echo-keystrokes
3395 This variable determines how much time should elapse before command
3396 characters echo. Its value must be a number, which specifies the
3397 number of seconds to wait before echoing. If the user types a
3398 prefix key (such as `C-x') and then delays this many seconds
3399 before continuing, the prefix key is echoed in the echo area. Any
3400 subsequent characters in the same command will be echoed as well.
3402 If the value is zero, then command input is not echoed.
3404 -- Variable: cursor-in-echo-area
3405 This variable controls where the cursor appears when a message is
3406 displayed in the echo area. If it is non-`nil', then the cursor
3407 appears at the end of the message. Otherwise, the cursor appears
3408 at point--not in the echo area at all.
3410 The value is normally `nil'; Lisp programs bind it to `t' for
3411 brief periods of time.
3414 File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
3419 XEmacs contains a facility for unified display of various warnings.
3420 Unlike errors, warnings are displayed in the situations when XEmacs
3421 encounters a problem that is recoverable, but which should be fixed for
3422 safe future operation.
3424 For example, warnings are printed by the startup code when it
3425 encounters problems with X keysyms, when there is an error in `.emacs',
3426 and in other problematic situations. Unlike messages, warnings are
3427 displayed in a separate buffer, and include an explanatory message that
3428 may span across several lines. Here is an example of how a warning is
3431 (1) (initialization/error) An error has occurred while loading ~/.emacs:
3433 Symbol's value as variable is void: bogus-variable
3435 To ensure normal operation, you should investigate the cause of the error
3436 in your initialization file and remove it. Use the `-debug-init' option
3437 to XEmacs to view a complete error backtrace.
3439 Each warning has a "class" and a "priority level". The class is a
3440 symbol describing what sort of warning this is, such as
3441 `initialization', `resource' or `key-mapping'.
3443 The warning priority level specifies how important the warning is.
3444 The recognized warning levels, in increased order of priority, are:
3445 `debug', `info', `notice', `warning', `error', `critical', `alert' and
3448 -- Function: display-warning class message &optional level
3449 This function displays a warning message MESSAGE (a string).
3450 CLASS should be a warning class symbol, as described above, or a
3451 list of such symbols. LEVEL describes the warning priority level.
3452 If unspecified, it default to `warning'.
3454 (display-warning 'resource
3455 "Bad resource specification encountered:
3460 You should replace the * with a . in order to get proper behavior when
3461 you use the specifier and/or `set-face-*' functions.")
3463 ---------- Warning buffer ----------
3464 (1) (resource/warning) Bad resource specification encountered:
3469 You should replace the * with a . in order to get proper behavior when
3470 you use the specifier and/or `set-face-*' functions.
3471 ---------- Warning buffer ----------
3473 -- Function: lwarn class level message &rest args
3474 This function displays a formatted labeled warning message. As
3475 above, CLASS should be the warning class symbol, or a list of such
3476 symbols, and LEVEL should specify the warning priority level
3477 (`warning' by default).
3479 Unlike in `display-warning', MESSAGE may be a formatted message,
3480 which will be, together with the rest of the arguments, passed to
3483 (lwarn 'message-log 'warning
3484 "Error caught in `remove-message-hook': %s"
3485 (error-message-string e))
3487 -- Variable: log-warning-minimum-level
3488 This variable specifies the minimum level of warnings that should
3489 be generated. Warnings with level lower than defined by this
3490 variable are completely ignored, as if they never happened.
3492 -- Variable: display-warning-minimum-level
3493 This variable specifies the minimum level of warnings that should
3494 be displayed. Unlike `log-warning-minimum-level', setting this
3495 function does not suppress warnings entirely--they are still
3496 generated in the `*Warnings*' buffer, only they are not displayed
3499 -- Variable: log-warning-suppressed-classes
3500 This variable specifies a list of classes that should not be
3501 logged or displayed. If any of the class symbols associated with
3502 a warning is the same as any of the symbols listed here, the
3503 warning will be completely ignored, as it they never happened.
3505 -- Variable: display-warning-suppressed-classes
3506 This variable specifies a list of classes that should not be
3507 logged or displayed. If any of the class symbols associated with
3508 a warning is the same as any of the symbols listed here, the
3509 warning will not be displayed. The warning will still logged in
3510 the *Warnings* buffer (unless also contained in
3511 `log-warning-suppressed-classes'), but the buffer will not be
3512 automatically popped up.
3515 File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
3520 You can make characters "invisible", so that they do not appear on the
3521 screen, with the `invisible' property. This can be either a text
3522 property or a property of an overlay.
3524 In the simplest case, any non-`nil' `invisible' property makes a
3525 character invisible. This is the default case--if you don't alter the
3526 default value of `buffer-invisibility-spec', this is how the
3527 `invisibility' property works. This feature is much like selective
3528 display (*note Selective Display::), but more general and cleaner.
3530 More generally, you can use the variable `buffer-invisibility-spec'
3531 to control which values of the `invisible' property make text
3532 invisible. This permits you to classify the text into different subsets
3533 in advance, by giving them different `invisible' values, and
3534 subsequently make various subsets visible or invisible by changing the
3535 value of `buffer-invisibility-spec'.
3537 Controlling visibility with `buffer-invisibility-spec' is especially
3538 useful in a program to display the list of entries in a data base. It
3539 permits the implementation of convenient filtering commands to view
3540 just a part of the entries in the data base. Setting this variable is
3541 very fast, much faster than scanning all the text in the buffer looking
3542 for properties to change.
3544 -- Variable: buffer-invisibility-spec
3545 This variable specifies which kinds of `invisible' properties
3546 actually make a character invisible.
3549 A character is invisible if its `invisible' property is
3550 non-`nil'. This is the default.
3553 Each element of the list makes certain characters invisible.
3554 Ultimately, a character is invisible if any of the elements
3555 of this list applies to it. The list can have two kinds of
3559 A character is invisible if its `invisible' property
3560 value is ATOM or if it is a list with ATOM as a member.
3563 A character is invisible if its `invisible' property
3564 value is ATOM or if it is a list with ATOM as a member.
3565 Moreover, if this character is at the end of a line and
3566 is followed by a visible newline, it displays an
3569 Ordinarily, commands that operate on text or move point do not care
3570 whether the text is invisible. However, the user-level line motion
3571 commands explicitly ignore invisible newlines. Since this causes a
3572 slow-down of these commands it is turned off by default, controlled by
3573 the variable `line-move-ignore-invisible'.
3576 File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
3578 52.6 Selective Display
3579 ======================
3581 "Selective display" is a pair of features that hide certain lines on
3584 The first variant, explicit selective display, is designed for use in
3585 a Lisp program. The program controls which lines are hidden by altering
3586 the text. Outline mode has traditionally used this variant. It has
3587 been partially replaced by the invisible text feature (*note Invisible
3588 Text::); there is a new version of Outline mode which uses that instead.
3590 In the second variant, the choice of lines to hide is made
3591 automatically based on indentation. This variant is designed to be a
3594 The way you control explicit selective display is by replacing a
3595 newline (control-j) with a carriage return (control-m). The text that
3596 was formerly a line following that newline is now invisible. Strictly
3597 speaking, it is temporarily no longer a line at all, since only newlines
3598 can separate lines; it is now part of the previous line.
3600 Selective display does not directly affect editing commands. For
3601 example, `C-f' (`forward-char') moves point unhesitatingly into
3602 invisible text. However, the replacement of newline characters with
3603 carriage return characters affects some editing commands. For example,
3604 `next-line' skips invisible lines, since it searches only for newlines.
3605 Modes that use selective display can also define commands that take
3606 account of the newlines, or that make parts of the text visible or
3609 When you write a selectively displayed buffer into a file, all the
3610 control-m's are output as newlines. This means that when you next read
3611 in the file, it looks OK, with nothing invisible. The selective display
3612 effect is seen only within XEmacs.
3614 -- Variable: selective-display
3615 This buffer-local variable enables selective display. This means
3616 that lines, or portions of lines, may be made invisible.
3618 * If the value of `selective-display' is `t', then any portion
3619 of a line that follows a control-m is not displayed.
3621 * If the value of `selective-display' is a positive integer,
3622 then lines that start with more than that many columns of
3623 indentation are not displayed.
3625 When some portion of a buffer is invisible, the vertical movement
3626 commands operate as if that portion did not exist, allowing a
3627 single `next-line' command to skip any number of invisible lines.
3628 However, character movement commands (such as `forward-char') do
3629 not skip the invisible portion, and it is possible (if tricky) to
3630 insert or delete text in an invisible portion.
3632 In the examples below, we show the _display appearance_ of the
3633 buffer `foo', which changes with the value of `selective-display'.
3634 The _contents_ of the buffer do not change.
3636 (setq selective-display nil)
3639 ---------- Buffer: foo ----------
3646 ---------- Buffer: foo ----------
3648 (setq selective-display 2)
3651 ---------- Buffer: foo ----------
3656 ---------- Buffer: foo ----------
3658 -- Variable: selective-display-ellipses
3659 If this buffer-local variable is non-`nil', then XEmacs displays
3660 `...' at the end of a line that is followed by invisible text.
3661 This example is a continuation of the previous one.
3663 (setq selective-display-ellipses t)
3666 ---------- Buffer: foo ----------
3671 ---------- Buffer: foo ----------
3673 You can use a display table to substitute other text for the
3674 ellipsis (`...'). *Note Display Tables::.
3677 File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
3679 52.7 The Overlay Arrow
3680 ======================
3682 The "overlay arrow" is useful for directing the user's attention to a
3683 particular line in a buffer. For example, in the modes used for
3684 interface to debuggers, the overlay arrow indicates the line of code
3685 about to be executed.
3687 -- Variable: overlay-arrow-string
3688 This variable holds the string to display to call attention to a
3689 particular line, or `nil' if the arrow feature is not in use.
3690 Despite its name, the value of this variable can be either a string
3691 or a glyph (*note Glyphs::).
3693 -- Variable: overlay-arrow-position
3694 This variable holds a marker that indicates where to display the
3695 overlay arrow. It should point at the beginning of a line. The
3696 arrow text appears at the beginning of that line, overlaying any
3697 text that would otherwise appear. Since the arrow is usually
3698 short, and the line usually begins with indentation, normally
3699 nothing significant is overwritten.
3701 The overlay string is displayed only in the buffer that this marker
3702 points into. Thus, only one buffer can have an overlay arrow at
3705 You can do the same job by creating an extent with a `begin-glyph'
3706 property. *Note Extent Properties::.
3709 File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
3711 52.8 Temporary Displays
3712 =======================
3714 Temporary displays are used by commands to put output into a buffer and
3715 then present it to the user for perusal rather than for editing. Many
3716 of the help commands use this feature.
3718 -- Special Form: with-output-to-temp-buffer buffer-name forms...
3719 This function executes FORMS while arranging to insert any output
3720 they print into the buffer named BUFFER-NAME. The buffer is then
3721 shown in some window for viewing, displayed but not selected.
3723 The string BUFFER-NAME specifies the temporary buffer, which need
3724 not already exist. The argument must be a string, not a buffer.
3725 The buffer is erased initially (with no questions asked), and it is
3726 marked as unmodified after `with-output-to-temp-buffer' exits.
3728 `with-output-to-temp-buffer' binds `standard-output' to the
3729 temporary buffer, then it evaluates the forms in FORMS. Output
3730 using the Lisp output functions within FORMS goes by default to
3731 that buffer (but screen display and messages in the echo area,
3732 although they are "output" in the general sense of the word, are
3733 not affected). *Note Output Functions::.
3735 The value of the last form in FORMS is returned.
3737 ---------- Buffer: foo ----------
3738 This is the contents of foo.
3739 ---------- Buffer: foo ----------
3741 (with-output-to-temp-buffer "foo"
3743 (print standard-output))
3746 ---------- Buffer: foo ----------
3751 ---------- Buffer: foo ----------
3753 -- Variable: temp-buffer-show-function
3754 If this variable is non-`nil', `with-output-to-temp-buffer' calls
3755 it as a function to do the job of displaying a help buffer. The
3756 function gets one argument, which is the buffer it should display.
3758 In Emacs versions 18 and earlier, this variable was called
3759 `temp-buffer-show-hook'.
3761 -- Function: momentary-string-display string position &optional char
3763 This function momentarily displays STRING in the current buffer at
3764 POSITION. It has no effect on the undo list or on the buffer's
3765 modification status.
3767 The momentary display remains until the next input event. If the
3768 next input event is CHAR, `momentary-string-display' ignores it
3769 and returns. Otherwise, that event remains buffered for
3770 subsequent use as input. Thus, typing CHAR will simply remove the
3771 string from the display, while typing (say) `C-f' will remove the
3772 string from the display and later (presumably) move point forward.
3773 The argument CHAR is a space by default.
3775 The return value of `momentary-string-display' is not meaningful.
3777 You can do the same job in a more general way by creating an extent
3778 with a begin-glyph property. *Note Extent Properties::.
3780 If MESSAGE is non-`nil', it is displayed in the echo area while
3781 STRING is displayed in the buffer. If it is `nil', a default
3782 message says to type CHAR to continue.
3784 In this example, point is initially located at the beginning of the
3787 ---------- Buffer: foo ----------
3788 This is the contents of foo.
3790 ---------- Buffer: foo ----------
3792 (momentary-string-display
3793 "**** Important Message! ****"
3795 "Type RET when done reading")
3798 ---------- Buffer: foo ----------
3799 This is the contents of foo.
3800 **** Important Message! ****Second line.
3801 ---------- Buffer: foo ----------
3803 ---------- Echo Area ----------
3804 Type RET when done reading
3805 ---------- Echo Area ----------
3807 This function works by actually changing the text in the buffer.
3808 As a result, if you later undo in this buffer, you will see the
3809 message come and go.
3812 File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
3814 52.9 Blinking Parentheses
3815 =========================
3817 This section describes the mechanism by which XEmacs shows a matching
3818 open parenthesis when the user inserts a close parenthesis.
3820 -- Variable: blink-paren-function
3821 The value of this variable should be a function (of no arguments)
3822 to be called whenever a character with close parenthesis syntax is
3823 inserted. The value of `blink-paren-function' may be `nil', in
3824 which case nothing is done.
3826 *Please note:* This variable was named `blink-paren-hook' in
3827 older Emacs versions, but since it is not called with the
3828 standard convention for hooks, it was renamed to
3829 `blink-paren-function' in version 19.
3831 -- Variable: blink-matching-paren
3832 If this variable is `nil', then `blink-matching-open' does nothing.
3834 -- Variable: blink-matching-paren-distance
3835 This variable specifies the maximum distance to scan for a matching
3836 parenthesis before giving up.
3838 -- Variable: blink-matching-paren-delay
3839 This variable specifies the number of seconds for the cursor to
3840 remain at the matching parenthesis. A fraction of a second often
3841 gives good results, but the default is 1, which works on all
3844 -- Command: blink-matching-open
3845 This function is the default value of `blink-paren-function'. It
3846 assumes that point follows a character with close parenthesis
3847 syntax and moves the cursor momentarily to the matching opening
3848 character. If that character is not already on the screen, it
3849 displays the character's context in the echo area. To avoid long
3850 delays, this function does not search farther than
3851 `blink-matching-paren-distance' characters.
3853 Here is an example of calling this function explicitly.
3855 (defun interactive-blink-matching-open ()
3856 "Indicate momentarily the start of sexp before point."
3858 (let ((blink-matching-paren-distance
3860 (blink-matching-paren t))
3861 (blink-matching-open)))
3864 File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
3866 52.10 Usual Display Conventions
3867 ===============================
3869 The usual display conventions define how to display each character
3870 code. You can override these conventions by setting up a display table
3871 (*note Display Tables::). Here are the usual display conventions:
3873 * Character codes 32 through 126 map to glyph codes 32 through 126.
3874 Normally this means they display as themselves.
3876 * Character code 9 is a horizontal tab. It displays as whitespace
3877 up to a position determined by `tab-width'.
3879 * Character code 10 is a newline.
3881 * All other codes in the range 0 through 31, and code 127, display
3882 in one of two ways according to the value of `ctl-arrow'. If it is
3883 non-`nil', these codes map to sequences of two glyphs, where the
3884 first glyph is the ASCII code for `^'. (A display table can
3885 specify a glyph to use instead of `^'.) Otherwise, these codes map
3886 just like the codes in the range 128 to 255.
3888 * Character codes 128 through 255 map to sequences of four glyphs,
3889 where the first glyph is the ASCII code for `\', and the others are
3890 digit characters representing the code in octal. (A display table
3891 can specify a glyph to use instead of `\'.)
3893 The usual display conventions apply even when there is a display
3894 table, for any character whose entry in the active display table is
3895 `nil'. Thus, when you set up a display table, you need only specify
3896 the characters for which you want unusual behavior.
3898 These variables affect the way certain characters are displayed on
3899 the screen. Since they change the number of columns the characters
3900 occupy, they also affect the indentation functions.
3902 -- User Option: ctl-arrow
3903 This buffer-local variable controls how control characters are
3904 displayed. If it is non-`nil', they are displayed as a caret
3905 followed by the character: `^A'. If it is `nil', they are
3906 displayed as a backslash followed by three octal digits: `\001'.
3908 -- Variable: default-ctl-arrow
3909 The value of this variable is the default value for `ctl-arrow' in
3910 buffers that do not override it. *Note Default Value::.
3912 -- User Option: tab-width
3913 The value of this variable is the spacing between tab stops used
3914 for displaying tab characters in Emacs buffers. The default is 8.
3915 Note that this feature is completely independent from the
3916 user-settable tab stops used by the command `tab-to-tab-stop'.
3917 *Note Indent Tabs::.
3920 File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
3922 52.11 Display Tables
3923 ====================
3925 You can use the "display table" feature to control how all 256 possible
3926 character codes display on the screen. This is useful for displaying
3927 European languages that have letters not in the ASCII character set.
3929 The display table maps each character code into a sequence of
3930 "runes", each rune being an image that takes up one character position
3931 on the screen. You can also define how to display each rune on your
3932 terminal, using the "rune table".
3936 * Display Table Format:: What a display table consists of.
3937 * Active Display Table:: How XEmacs selects a display table to use.
3938 * Character Descriptors:: Format of an individual element of a
3942 File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
3944 52.11.1 Display Table Format
3945 ----------------------------
3947 A display table is an array of 256 elements. (In FSF Emacs, a display
3948 table is 262 elements. The six extra elements specify the truncation
3949 and continuation glyphs, etc. This method is very kludgey, and in
3950 XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
3951 used. *Note Truncation::.)
3953 -- Function: make-display-table
3954 This creates and returns a display table. The table initially has
3955 `nil' in all elements.
3957 The 256 elements correspond to character codes; the Nth element says
3958 how to display the character code N. The value should be `nil', a
3959 string, a glyph, or a vector of strings and glyphs (*note Character
3960 Descriptors::). If an element is `nil', it says to display that
3961 character according to the usual display conventions (*note Usual
3964 If you use the display table to change the display of newline
3965 characters, the whole buffer will be displayed as one long "line."
3967 For example, here is how to construct a display table that mimics the
3968 effect of setting `ctl-arrow' to a non-`nil' value:
3970 (setq disptab (make-display-table))
3973 (or (= i ?\t) (= i ?\n)
3974 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
3976 (aset disptab 127 "^?"))
3979 File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
3981 52.11.2 Active Display Table
3982 ----------------------------
3984 The active display table is controlled by the variable
3985 `current-display-table'. This is a specifier, which means that you can
3986 specify separate values for it in individual buffers, windows, frames,
3987 and devices, as well as a global value. It also means that you cannot
3988 set this variable using `setq'; use `set-specifier' instead. *Note
3989 Specifiers::. (FSF Emacs uses `window-display-table',
3990 `buffer-display-table', `standard-display-table', etc. to control the
3991 display table. However, specifiers are a cleaner and more powerful way
3992 of doing the same thing. FSF Emacs also uses a different format for
3993 the contents of a display table, using additional indirection to a
3994 "glyph table" and such. Note that "glyph" has a different meaning in
3997 -- Variable: current-display-table
3998 The display table currently in use. This is a specifier.
4000 Display tables are used to control how characters are displayed.
4001 Each time that redisplay processes a character, it is looked up in
4002 all the display tables that apply (obtained by calling
4003 `specifier-instance' on `current-display-table' and any overriding
4004 display tables specified in currently active faces). The first
4005 entry found that matches the character determines how the
4006 character is displayed. If there is no matching entry, the
4007 default display method is used. (Non-control characters are
4008 displayed as themselves and control characters are displayed
4009 according to the buffer-local variable `ctl-arrow'. Control
4010 characters are further affected by `control-arrow-glyph' and
4011 `octal-escape-glyph'.)
4013 Each instantiator in this specifier and the display-table
4014 specifiers in faces is a display table or a list of such tables.
4015 If a list, each table will be searched in turn for an entry
4016 matching a particular character. Each display table is one of
4018 * A vector, specifying values for characters starting at 0.
4020 * A char table, either of type `char' or `generic'.
4024 Each entry in a display table should be one of
4026 * nil (this entry is ignored and the search continues).
4028 * A character (use this character; if it happens to be the same
4029 as the original character, default processing happens,
4030 otherwise redisplay attempts to display this character
4031 directly; #### At some point recursive display-table lookup
4032 will be implemented).
4034 * A string (display each character in the string directly; ####
4035 At some point recursive display-table lookup will be
4038 * A glyph (display the glyph; #### At some point recursive
4039 display-table lookup will be implemented when a string glyph
4040 is being processed).
4042 * A cons of the form (format "STRING") where STRING is a
4043 printf-like spec used to process the character. ####
4044 Unfortunately no formatting directives other than %% are
4047 * A vector (each element of the vector is processed recursively;
4048 in such a case, nil elements in the vector are simply
4051 #### At some point in the near future, display tables are
4052 likely to be expanded to include other features, such as
4053 referencing characters in particular fonts and allowing the
4054 character search to continue all the way up the chain of
4055 specifier instantiators. These features are necessary to
4056 properly display Unicode characters.
4058 Individual faces can also specify an overriding display table; this
4059 is set using `set-face-display-table'. *Note Faces::.
4061 If no display table can be determined for a particular window, then
4062 XEmacs uses the usual display conventions. *Note Usual Display::.
4065 File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
4067 52.11.3 Character Descriptors
4068 -----------------------------
4070 Each element of the display-table vector describes how to display a
4071 particular character and is called a "character descriptor". A
4072 character descriptor can be:
4075 Display this particular string wherever the character is to be
4079 Display this particular glyph wherever the character is to be
4083 The vector may contain strings and/or glyphs. Display the
4084 elements of the vector one after another wherever the character is
4088 Display according to the standard interpretation (*note Usual
4092 File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
4097 You can make XEmacs ring a bell, play a sound, or blink the screen to
4098 attract the user's attention. Be conservative about how often you do
4099 this; frequent bells can become irritating. Also be careful not to use
4100 beeping alone when signaling an error is appropriate. (*Note Errors::.)
4102 -- Function: ding &optional dont-terminate sound device
4103 This function beeps, or flashes the screen (see `visible-bell'
4104 below). It also terminates any keyboard macro currently executing
4105 unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
4106 should be a symbol specifying which sound to make. This sound
4107 will be played if `visible-bell' is `nil'. (This only works if
4108 sound support was compiled into the executable and you are running
4109 on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
4110 PC. Otherwise you just get a beep.) The optional third argument
4111 specifies what device to make the sound on, and defaults to the
4114 -- Function: beep &optional dont-terminate sound device
4115 This is a synonym for `ding'.
4117 -- User Option: visible-bell
4118 This variable determines whether XEmacs should flash the screen to
4119 represent a bell. Non-`nil' means yes, `nil' means no. On TTY
4120 devices, this is effective only if the Termcap entry for the
4121 terminal type has the visible bell flag (`vb') set.
4123 -- Variable: sound-alist
4124 This variable holds an alist associating names with sounds. When
4125 `beep' or `ding' is called with one of the name symbols, the
4126 associated sound will be generated instead of the standard beep.
4128 Each element of `sound-alist' is a list describing a sound. The
4129 first element of the list is the name of the sound being defined.
4130 Subsequent elements of the list are alternating keyword/value
4134 A string of raw sound data, or the name of another sound to
4135 play. The symbol `t' here means use the default X beep.
4138 An integer from 0-100, defaulting to `bell-volume'.
4141 If using the default X beep, the pitch (Hz) to generate.
4144 If using the default X beep, the duration (milliseconds).
4146 For compatibility, elements of `sound-alist' may also be:
4148 * `( sound-name . <sound> )'
4150 * `( sound-name <volume> <sound> )'
4152 You should probably add things to this list by calling the function
4157 - You can only play audio data if running on the console screen
4158 of a Sun SparcStation, SGI, or HP9000s700.
4160 - The pitch, duration, and volume options are available
4161 everywhere, but many X servers ignore the `pitch' option.
4163 The following beep-types are used by XEmacs itself:
4166 when an auto-save does not succeed
4169 when the XEmacs command loop catches an error
4172 when you type a key that is undefined
4175 when you use an undefined mouse-click combination
4178 during completing-read
4181 when you type something other than 'y' or 'n'
4184 when you type something other than 'yes' or 'no'
4187 used when nothing else is appropriate.
4189 Other lisp packages may use other beep types, but these are the
4190 ones that the C kernel of XEmacs uses.
4192 -- User Option: bell-volume
4193 This variable specifies the default volume for sounds, from 0 to
4196 -- Command: load-default-sounds
4197 This function loads and installs some sound files as beep-types.
4199 -- Command: load-sound-file filename sound-name &optional volume
4200 This function reads in an audio file and adds it to `sound-alist'.
4201 The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
4202 should be a symbol, specifying the name of the sound. If VOLUME
4203 is specified, the sound will be played at that volume; otherwise,
4204 the value of `bell-volume' will be used.
4206 -- Function: play-sound sound &optional volume device
4207 This function plays sound SOUND, which should be a symbol
4208 mentioned in `sound-alist'. If VOLUME is specified, it overrides
4209 the value (if any) specified in `sound-alist'. DEVICE specifies
4210 the device to play the sound on, and defaults to the selected
4213 -- Command: play-sound-file file &optional volume device
4214 This function plays the named sound file at volume VOLUME, which
4215 defaults to `bell-volume'. DEVICE specifies the device to play
4216 the sound on, and defaults to the selected device.
4219 File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
4224 -- Function: hash-table-p object
4225 This function returns `t' if OBJECT is a hash table, else `nil'.
4229 * Introduction to Hash Tables:: Hash tables are fast data structures for
4230 implementing simple tables (i.e. finite
4231 mappings from keys to values).
4232 * Working With Hash Tables:: Hash table functions.
4233 * Weak Hash Tables:: Hash tables with special garbage-collection
4237 File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
4239 53.1 Introduction to Hash Tables
4240 ================================
4242 A "hash table" is a data structure that provides mappings from
4243 arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
4244 called "values". A key/value pair is sometimes called an "entry" in
4245 the hash table. There are many ways other than hash tables of
4246 implementing the same sort of mapping, e.g. association lists (*note
4247 Association Lists::) and property lists (*note Property Lists::), but
4248 hash tables provide much faster lookup when there are many entries in
4249 the mapping. Hash tables are an implementation of the abstract data
4250 type "dictionary", also known as "associative array".
4252 Internally, hash tables are hashed using the "linear probing" hash
4253 table implementation method. This method hashes each key to a
4254 particular spot in the hash table, and then scans forward sequentially
4255 until a blank entry is found. To look up a key, hash to the appropriate
4256 spot, then search forward for the key until either a key is found or a
4257 blank entry stops the search. This method is used in preference to
4258 double hashing because of changes in recent hardware. The penalty for
4259 non-sequential access to memory has been increasing, and this
4260 compensates for the problem of clustering that linear probing entails.
4262 When hash tables are created, the user may (but is not required to)
4263 specify initial properties that influence performance.
4265 Use the `:size' parameter to specify the number of entries that are
4266 likely to be stored in the hash table, to avoid the overhead of resizing
4267 the table. But if the pre-allocated space for the entries is never
4268 used, it is simply wasted and makes XEmacs slower. Excess unused hash
4269 table entries exact a small continuous performance penalty, since they
4270 must be scanned at every garbage collection. If the number of entries
4271 in the hash table is unknown, simply avoid using the `:size' keyword.
4273 Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
4274 the algorithm for deciding when to rehash the hash table. For
4275 temporary hash tables that are going to be very heavily used, use a
4276 small rehash threshold, for example, 0.4 and a large rehash size, for
4277 example 2.0. For permanent hash tables that will be infrequently used,
4278 specify a large rehash threshold, for example 0.8.
4280 Hash tables can also be created by the lisp reader using structure
4281 syntax, for example:
4282 #s(hash-table size 20 data (foo 1 bar 2))
4284 The structure syntax accepts the same keywords as `make-hash-table'
4285 (without the `:' character), as well as the additional keyword `data',
4286 which specifies the initial hash table contents.
4288 -- Function: make-hash-table &key `test' `size' `rehash-size'
4289 `rehash-threshold' `weakness'
4290 This function returns a new empty hash table object.
4292 Keyword `:test' can be `eq', `eql' (default) or `equal'.
4293 Comparison between keys is done using this function. If speed is
4294 important, consider using `eq'. When storing strings in the hash
4295 table, you will likely need to use `equal'.
4297 Keyword `:size' specifies the number of keys likely to be inserted.
4298 This number of entries can be inserted without enlarging the hash
4301 Keyword `:rehash-size' must be a float greater than 1.0, and
4302 specifies the factor by which to increase the size of the hash
4303 table when enlarging.
4305 Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
4306 and specifies the load factor of the hash table which triggers
4309 Non-standard keyword `:weakness' can be `nil' (default), `t',
4310 `key-and-value', `key', `value' or `key-or-value'. `t' is an
4311 alias for `key-and-value'.
4313 A key-and-value-weak hash table, also known as a fully-weak or
4314 simply as a weak hash table, is one whose pointers do not count as
4315 GC referents: for any key-value pair in the hash table, if the only
4316 remaining pointer to either the key or the value is in a weak hash
4317 table, then the pair will be removed from the hash table, and the
4318 key and value collected. A non-weak hash table (or any other
4319 pointer) would prevent the object from being collected.
4321 A key-weak hash table is similar to a fully-weak hash table except
4322 that a key-value pair will be removed only if the key remains
4323 unmarked outside of weak hash tables. The pair will remain in the
4324 hash table if the key is pointed to by something other than a weak
4325 hash table, even if the value is not.
4327 A value-weak hash table is similar to a fully-weak hash table
4328 except that a key-value pair will be removed only if the value
4329 remains unmarked outside of weak hash tables. The pair will
4330 remain in the hash table if the value is pointed to by something
4331 other than a weak hash table, even if the key is not.
4333 A key-or-value-weak hash table is similar to a fully-weak hash
4334 table except that a key-value pair will be removed only if the
4335 value and the key remain unmarked outside of weak hash tables.
4336 The pair will remain in the hash table if the value or key are
4337 pointed to by something other than a weak hash table, even if the
4340 -- Function: copy-hash-table hash-table
4341 This function returns a new hash table which contains the same
4342 keys and values as HASH-TABLE. The keys and values will not
4343 themselves be copied.
4345 -- Function: hash-table-count hash-table
4346 This function returns the number of entries in HASH-TABLE.
4348 -- Function: hash-table-test hash-table
4349 This function returns the test function of HASH-TABLE. This can
4350 be one of `eq', `eql' or `equal'.
4352 -- Function: hash-table-size hash-table
4353 This function returns the current number of slots in HASH-TABLE,
4354 whether occupied or not.
4356 -- Function: hash-table-rehash-size hash-table
4357 This function returns the current rehash size of HASH-TABLE. This
4358 is a float greater than 1.0; the factor by which HASH-TABLE is
4359 enlarged when the rehash threshold is exceeded.
4361 -- Function: hash-table-rehash-threshold hash-table
4362 This function returns the current rehash threshold of HASH-TABLE.
4363 This is a float between 0.0 and 1.0; the maximum "load factor" of
4364 HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
4366 -- Function: hash-table-weakness hash-table
4367 This function returns the weakness of HASH-TABLE. This can be one
4368 of `nil', `t', `key' or `value'.
4371 File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
4373 53.2 Working With Hash Tables
4374 =============================
4376 -- Function: puthash key value hash-table
4377 This function hashes KEY to VALUE in HASH-TABLE.
4379 -- Function: gethash key hash-table &optional default
4380 This function finds the hash value for KEY in HASH-TABLE. If
4381 there is no entry for KEY in HASH-TABLE, DEFAULT is returned
4382 (which in turn defaults to `nil').
4384 -- Function: remhash key hash-table
4385 This function removes the entry for KEY from HASH-TABLE. Does
4386 nothing if there is no entry for KEY in HASH-TABLE.
4388 -- Function: clrhash hash-table
4389 This function removes all entries from HASH-TABLE, leaving it
4392 -- Function: maphash function hash-table
4393 This function maps FUNCTION over entries in HASH-TABLE, calling it
4394 with two args, each key and value in the hash table.
4396 FUNCTION may not modify HASH-TABLE, with the one exception that
4397 FUNCTION may remhash or puthash the entry currently being
4398 processed by FUNCTION.
4401 File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
4403 53.3 Weak Hash Tables
4404 =====================
4406 A "weak hash table" is a special variety of hash table whose elements
4407 do not count as GC referents. For any key-value pair in such a hash
4408 table, if either the key or value (or in some cases, if one particular
4409 one of the two) has no references to it outside of weak hash tables
4410 (and similar structures such as weak lists), the pair will be removed
4411 from the table, and the key and value collected. A non-weak hash table
4412 (or any other pointer) would prevent the objects from being collected.
4414 Weak hash tables are useful for keeping track of information in a
4415 non-obtrusive way, for example to implement caching. If the cache
4416 contains objects such as buffers, markers, image instances, etc. that
4417 will eventually disappear and get garbage-collected, using a weak hash
4418 table ensures that these objects are collected normally rather than
4419 remaining around forever, long past their actual period of use.
4420 (Otherwise, you'd have to explicitly map over the hash table every so
4421 often and remove unnecessary elements.)
4423 There are four types of weak hash tables:
4425 key-and-value-weak hash tables
4426 In these hash tables, also known as fully weak or simply as weak
4427 hash tables, a pair disappears if either the key or the value is
4428 unreferenced outside of the table.
4430 key-weak hash tables
4431 In these hash tables, a pair disappears if the key is unreferenced
4432 outside of the table, regardless of how the value is referenced.
4434 value-weak hash tables
4435 In these hash tables, a pair disappears if the value is
4436 unreferenced outside of the table, regardless of how the key is
4439 key-or-value-weak hash tables
4440 In these hash tables, a pair disappears if both the key and the
4441 value are unreferenced outside of the table.
4443 Also see *Note Weak Lists::.
4445 Weak hash tables are created by specifying the `:weakness' keyword to
4449 File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
4454 A range table is a table that efficiently associated values with ranges
4457 Note that range tables have a read syntax, like this:
4459 #s(range-table data ((-3 2) foo (5 20) bar))
4461 This maps integers in the range (-3, 2) to `foo' and integers in the
4462 range (5, 20) to `bar'.
4464 -- Function: range-table-p object
4465 Return non-`nil' if OBJECT is a range table.
4469 * Introduction to Range Tables:: Range tables efficiently map ranges of
4471 * Working With Range Tables:: Range table functions.
4474 File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
4476 54.1 Introduction to Range Tables
4477 =================================
4479 -- Function: make-range-table
4480 Make a new, empty range table.
4482 -- Function: copy-range-table range-table
4483 This function returns a new range table which contains the same
4484 values for the same ranges as RANGE-TABLE. The values will not
4485 themselves be copied.
4488 File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
4490 54.2 Working With Range Tables
4491 ==============================
4493 -- Function: get-range-table pos range-table &optional default
4494 This function finds value for position POS in RANGE-TABLE. If
4495 there is no corresponding value, return DEFAULT (defaults to
4498 -- Function: put-range-table start end value range-table
4499 This function sets the value for range (START, END) to be VALUE in
4502 -- Function: remove-range-table start end range-table
4503 This function removes the value for range (START, END) in
4506 -- Function: clear-range-table range-table
4507 This function flushes RANGE-TABLE.
4509 -- Function: map-range-table function range-table
4510 This function maps FUNCTION over entries in RANGE-TABLE, calling
4511 it with three args, the beginning and end of the range and the
4512 corresponding value.
4515 File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
4520 -- Function: databasep object
4521 This function returns non-`nil' if OBJECT is a database.
4525 * Connecting to a Database::
4526 * Working With a Database::
4527 * Other Database Functions::
4530 File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
4532 55.1 Connecting to a Database
4533 =============================
4535 -- Function: open-database file &optional type subtype access mode
4536 This function opens database FILE, using database method TYPE and
4537 SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
4538 can be any combination of `r' `w' and `+', for read, write, and
4541 TYPE can have the value `'dbm' or `'berkeley-db' to select the
4542 type of database file to use. (Note: XEmacs may not support both
4545 For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
4548 For a TYPE of `'berkeley-db', the following subtypes are
4549 available: `'hash', `'btree', and `'recno'. See the manpages for
4550 the Berkeley DB functions for more information about these types.
4552 -- Function: close-database database
4553 This function closes database DATABASE.
4555 -- Function: database-live-p object
4556 This function returns `t' if OBJECT is an active database, else
4560 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
4562 55.2 Working With a Database
4563 ============================
4565 -- Function: get-database key database &optional default
4566 This function finds the value for KEY in DATABASE. If there is no
4567 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
4570 -- Function: map-database function database
4571 This function maps FUNCTION over entries in DATABASE, calling it
4572 with two args, each key and value in the database.
4574 -- Function: put-database key value database &optional replace
4575 This function stores KEY and VALUE in DATABASE. If optional
4576 fourth arg REPLACE is non-`nil', replace any existing entry in the
4579 -- Function: remove-database key database
4580 This function removes KEY from DATABASE.
4583 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
4585 55.3 Other Database Functions
4586 =============================
4588 -- Function: database-file-name database
4589 This function returns the filename associated with DATABASE.
4591 -- Function: database-last-error &optional database
4592 This function returns the last error associated with DATABASE.
4594 -- Function: database-subtype database
4595 This function returns the subtype of DATABASE, if any.
4597 -- Function: database-type database
4598 This function returns the type of DATABASE.
4601 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
4606 In the terminology of operating systems, a "process" is a space in
4607 which a program can execute. XEmacs runs in a process. XEmacs Lisp
4608 programs can invoke other programs in processes of their own. These are
4609 called "subprocesses" or "child processes" of the XEmacs process, which
4610 is their "parent process".
4612 A subprocess of XEmacs may be "synchronous" or "asynchronous",
4613 depending on how it is created. When you create a synchronous
4614 subprocess, the Lisp program waits for the subprocess to terminate
4615 before continuing execution. When you create an asynchronous
4616 subprocess, it can run in parallel with the Lisp program. This kind of
4617 subprocess is represented within XEmacs by a Lisp object which is also
4618 called a "process". Lisp programs can use this object to communicate
4619 with the subprocess or to control it. For example, you can send
4620 signals, obtain status information, receive output from the process, or
4623 -- Function: processp object
4624 This function returns `t' if OBJECT is a process, `nil' otherwise.
4628 * Subprocess Creation:: Functions that start subprocesses.
4629 * Synchronous Processes:: Details of using synchronous subprocesses.
4630 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
4631 for data sent to and from a subprocess.
4632 * Asynchronous Processes:: Starting up an asynchronous subprocess.
4633 * Deleting Processes:: Eliminating an asynchronous subprocess.
4634 * Process Information:: Accessing run-status and other attributes.
4635 * Input to Processes:: Sending input to an asynchronous subprocess.
4636 * Signals to Processes:: Stopping, continuing or interrupting
4637 an asynchronous subprocess.
4638 * Output from Processes:: Collecting output from an asynchronous subprocess.
4639 * Sentinels:: Sentinels run when process run-status changes.
4640 * Process Window Size:: Changing the logical window size of a process.
4641 * Transaction Queues:: Transaction-based communication with subprocesses.
4642 * Network:: Opening network connections.
4645 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
4647 56.1 Functions that Create Subprocesses
4648 =======================================
4650 There are three functions that create a new subprocess in which to run
4651 a program. One of them, `start-process', creates an asynchronous
4652 process and returns a process object (*note Asynchronous Processes::).
4653 The other two, `call-process' and `call-process-region', create a
4654 synchronous process and do not return a process object (*note
4655 Synchronous Processes::).
4657 Synchronous and asynchronous processes are explained in the following
4658 sections. Since the three functions are all called in a similar
4659 fashion, their common arguments are described here.
4661 In all cases, the function's PROGRAM argument specifies the program
4662 to be run. An error is signaled if the file is not found or cannot be
4663 executed. If the file name is relative, the variable `exec-path'
4664 contains a list of directories to search. Emacs initializes
4665 `exec-path' when it starts up, based on the value of the environment
4666 variable `PATH'. The standard file name constructs, `~', `.', and
4667 `..', are interpreted as usual in `exec-path', but environment variable
4668 substitutions (`$HOME', etc.) are not recognized; use
4669 `substitute-in-file-name' to perform them (*note File Name Expansion::).
4671 Each of the subprocess-creating functions has a BUFFER-OR-NAME
4672 argument which specifies where the standard output from the program will
4673 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
4674 a filter function handles it. (*Note Filter Functions::, and *Note
4675 Read and Print::.) Normally, you should avoid having multiple
4676 processes send output to the same buffer because their output would be
4677 intermixed randomly.
4679 All three of the subprocess-creating functions have a `&rest'
4680 argument, ARGS. The ARGS must all be strings, and they are supplied to
4681 PROGRAM as separate command line arguments. Wildcard characters and
4682 other shell constructs are not allowed in these strings, since they are
4683 passed directly to the specified program.
4685 *Please note:* The argument PROGRAM contains only the name of the
4686 program; it may not contain any command-line arguments. You must use
4687 ARGS to provide those.
4689 If you want to use features of the shell, then invoke the shell
4690 directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
4693 The subprocess gets its current directory from the value of
4694 `default-directory' (*note File Name Expansion::).
4696 The subprocess inherits its environment from XEmacs; but you can
4697 specify overrides for it with `process-environment'. *Note System
4700 -- Variable: exec-directory
4701 The value of this variable is the name of a directory (a string)
4702 that contains programs that come with XEmacs, that are intended
4703 for XEmacs to invoke. The program `wakeup' is an example of such
4704 a program; the `display-time' command uses it to get a reminder
4707 -- User Option: exec-path
4708 The value of this variable is a list of directories to search for
4709 programs to run in subprocesses. Each element is either the name
4710 of a directory (i.e., a string), or `nil', which stands for the
4711 default directory (which is the value of `default-directory').
4713 The value of `exec-path' is used by `call-process' and
4714 `start-process' when the PROGRAM argument is not an absolute file
4718 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
4720 56.2 Creating a Synchronous Process
4721 ===================================
4723 After a "synchronous process" is created, XEmacs waits for the process
4724 to terminate before continuing. Starting Dired is an example of this:
4725 it runs `ls' in a synchronous process, then modifies the output
4726 slightly. Because the process is synchronous, the entire directory
4727 listing arrives in the buffer before XEmacs tries to do anything with
4730 While Emacs waits for the synchronous subprocess to terminate, the
4731 user can quit by typing `C-g'. The first `C-g' tries to kill the
4732 subprocess with a `SIGINT' signal; but it waits until the subprocess
4733 actually terminates before quitting. If during that time the user
4734 types another `C-g', that kills the subprocess instantly with `SIGKILL'
4735 and quits immediately. *Note Quitting::.
4737 The synchronous subprocess functions returned `nil' in version 18.
4738 In version 19, they return an indication of how the process terminated.
4740 -- Function: call-process program &optional infile destination display
4742 This function calls PROGRAM in a separate process and waits for it
4745 The standard input for the process comes from file INFILE if
4746 INFILE is not `nil' and from `/dev/null' otherwise. The argument
4747 DESTINATION says where to put the process output. Here are the
4751 Insert the output in that buffer, before point. This
4752 includes both the standard output stream and the standard
4753 error stream of the process.
4756 Find or create a buffer with that name, then insert the
4757 output in that buffer, before point.
4760 Insert the output in the current buffer, before point.
4766 Discard the output, and return immediately without waiting
4767 for the subprocess to finish.
4769 In this case, the process is not truly synchronous, since it
4770 can run in parallel with Emacs; but you can think of it as
4771 synchronous in that Emacs is essentially finished with the
4772 subprocess as soon as this function returns.
4774 (REAL-DESTINATION ERROR-DESTINATION)
4775 Keep the standard output stream separate from the standard
4776 error stream; deal with the ordinary output as specified by
4777 REAL-DESTINATION, and dispose of the error output according
4778 to ERROR-DESTINATION. The value `nil' means discard it, `t'
4779 means mix it with the ordinary output, and a string specifies
4780 a file name to redirect error output into.
4782 You can't directly specify a buffer to put the error output
4783 in; that is too difficult to implement. But you can achieve
4784 this result by sending the error output to a temporary file
4785 and then inserting the file into a buffer.
4787 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
4788 as output is inserted. Otherwise the function does no redisplay,
4789 and the results become visible on the screen only when XEmacs
4790 redisplays that buffer in the normal course of events.
4792 The remaining arguments, ARGS, are strings that specify command
4793 line arguments for the program.
4795 The value returned by `call-process' (unless you told it not to
4796 wait) indicates the reason for process termination. A number
4797 gives the exit status of the subprocess; 0 means success, and any
4798 other value means failure. If the process terminated with a
4799 signal, `call-process' returns a string describing the signal.
4801 In the examples below, the buffer `foo' is current.
4803 (call-process "pwd" nil t)
4806 ---------- Buffer: foo ----------
4807 /usr/user/lewis/manual
4808 ---------- Buffer: foo ----------
4810 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
4813 ---------- Buffer: bar ----------
4814 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
4816 ---------- Buffer: bar ----------
4818 The `insert-directory' function contains a good example of the use
4821 (call-process insert-directory-program nil t nil switches
4822 (if full-directory-p
4823 (concat (file-name-as-directory file) ".")
4826 -- Function: call-process-region start end program &optional deletep
4827 destination displayp &rest args
4828 This function sends the text between START to END as standard
4829 input to a process running PROGRAM. It deletes the text sent if
4830 DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
4831 the output in the current buffer.
4833 The arguments DESTINATION and DISPLAYP control what to do with the
4834 output from the subprocess, and whether to update the display as
4835 it comes in. For details, see the description of `call-process',
4836 above. If DESTINATION is the integer 0, `call-process-region'
4837 discards the output and returns `nil' immediately, without waiting
4838 for the subprocess to finish.
4840 The remaining arguments, ARGS, are strings that specify command
4841 line arguments for the program.
4843 The return value of `call-process-region' is just like that of
4844 `call-process': `nil' if you told it to return without waiting;
4845 otherwise, a number or string which indicates how the subprocess
4848 In the following example, we use `call-process-region' to run the
4849 `cat' utility, with standard input being the first five characters
4850 in buffer `foo' (the word `input'). `cat' copies its standard
4851 input into its standard output. Since the argument DESTINATION is
4852 `t', this output is inserted in the current buffer.
4854 ---------- Buffer: foo ----------
4856 ---------- Buffer: foo ----------
4858 (call-process-region 1 6 "cat" nil t)
4861 ---------- Buffer: foo ----------
4863 ---------- Buffer: foo ----------
4865 The `shell-command-on-region' command uses `call-process-region'
4868 (call-process-region
4870 shell-file-name ; Name of program.
4871 nil ; Do not delete region.
4872 buffer ; Send output to `buffer'.
4873 nil ; No redisplay during output.
4874 "-c" command) ; Arguments for the shell.
4877 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
4879 56.3 MS-DOS Subprocesses
4880 ========================
4882 On MS-DOS, you must indicate whether the data going to and from a
4883 synchronous subprocess are text or binary. Text data requires
4884 translation between the end-of-line convention used within Emacs (a
4885 single newline character) and the convention used outside Emacs (the
4886 two-character sequence, CRLF).
4888 The variable `binary-process-input' applies to input sent to the
4889 subprocess, and `binary-process-output' applies to output received from
4890 it. A non-`nil' value means the data is non-text; `nil' means the data
4891 is text, and calls for conversion.
4893 -- Variable: binary-process-input
4894 If this variable is `nil', convert newlines to CRLF sequences in
4895 the input to a synchronous subprocess.
4897 -- Variable: binary-process-output
4898 If this variable is `nil', convert CRLF sequences to newlines in
4899 the output from a synchronous subprocess.
4901 *Note Files and MS-DOS::, for related information.
4904 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
4906 56.4 Creating an Asynchronous Process
4907 =====================================
4909 After an "asynchronous process" is created, Emacs and the Lisp program
4910 both continue running immediately. The process may thereafter run in
4911 parallel with Emacs, and the two may communicate with each other using
4912 the functions described in following sections. Here we describe how to
4913 create an asynchronous process with `start-process'.
4915 -- Function: start-process name buffer-or-name program &rest args
4916 This function creates a new asynchronous subprocess and starts the
4917 program PROGRAM running in it. It returns a process object that
4918 stands for the new subprocess in Lisp. The argument NAME
4919 specifies the name for the process object; if a process with this
4920 name already exists, then NAME is modified (by adding `<1>', etc.)
4921 to be unique. The buffer BUFFER-OR-NAME is the buffer to
4922 associate with the process.
4924 The remaining arguments, ARGS, are strings that specify command
4925 line arguments for the program.
4927 In the example below, the first process is started and runs
4928 (rather, sleeps) for 100 seconds. Meanwhile, the second process
4929 is started, and given the name `my-process<1>' for the sake of
4930 uniqueness. It inserts the directory listing at the end of the
4931 buffer `foo', before the first process finishes. Then it
4932 finishes, and a message to that effect is inserted in the buffer.
4933 Much later, the first process finishes, and another message is
4934 inserted in the buffer for it.
4936 (start-process "my-process" "foo" "sleep" "100")
4937 => #<process my-process>
4939 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
4940 => #<process my-process<1>>
4942 ---------- Buffer: foo ----------
4944 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
4945 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
4947 Process my-process<1> finished
4949 Process my-process finished
4950 ---------- Buffer: foo ----------
4952 -- Function: start-process-shell-command name buffer-or-name command
4954 This function is like `start-process' except that it uses a shell
4955 to execute the specified command. The argument COMMAND is a shell
4956 command name, and COMMAND-ARGS are the arguments for the shell
4959 -- Variable: process-connection-type
4960 This variable controls the type of device used to communicate with
4961 asynchronous subprocesses. If it is non-`nil', then PTYs are
4962 used, when available. Otherwise, pipes are used.
4964 PTYs are usually preferable for processes visible to the user, as
4965 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
4966 to work between the process and its children whereas pipes do not.
4967 For subprocesses used for internal purposes by programs, it is
4968 often better to use a pipe, because they are more efficient. In
4969 addition, the total number of PTYs is limited on many systems and
4970 it is good not to waste them. A rule of thumb is to use ptys for
4971 processes the user interacts with directly, and pipes for
4972 processes that are hidden from the user.
4974 The value `process-connection-type' is used when `start-process'
4975 is called. So you can specify how to communicate with one
4976 subprocess by binding the variable around the call to
4979 (let ((process-connection-type nil)) ; Use a pipe.
4980 (start-process ...))
4982 To determine whether a given subprocess actually got a pipe or a
4983 PTY, use the function `process-tty-name' (*note Process
4986 Lisp functions that manipulate processes usually accept a PROCESS
4987 argument. Besides using an actual process object for this argument, you
4988 can use a process name, a buffer object, the name of a buffer, or
4989 `nil'. Specifying a buffer or buffer name for the PROCESS argument
4990 means use the process associated with the buffer (or the most recent
4991 one, if there is more than one). `nil' means use the process
4992 associated with the current buffer. *Note Process Information::.
4993 *Note Process Buffers::.
4996 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
4998 56.5 Deleting Processes
4999 =======================
5001 "Deleting a process" disconnects XEmacs immediately from the
5002 subprocess, and removes it from the list of active processes. It sends
5003 a signal to the subprocess to make the subprocess terminate, but this is
5004 not guaranteed to happen immediately. The process object itself
5005 continues to exist as long as other Lisp objects point to it.
5007 You can delete a process explicitly at any time. Processes are
5008 deleted automatically after they terminate, but not necessarily right
5009 away. If you delete a terminated process explicitly before it is
5010 deleted automatically, no harm results.
5012 -- Variable: delete-exited-processes
5013 This variable controls automatic deletion of processes that have
5014 terminated (due to calling `exit' or to a signal). If it is
5015 `nil', then they continue to exist until the user runs
5016 `list-processes'. Otherwise, they are deleted immediately after
5019 -- Function: delete-process name
5020 This function deletes the process associated with NAME, killing it
5021 with a `SIGHUP' signal. The argument NAME may be a process, the
5022 name of a process, a buffer, or the name of a buffer.
5024 (delete-process "*shell*")
5027 -- Function: process-kill-without-query process &optional
5029 This function declares that XEmacs need not query the user if
5030 PROCESS is still running when XEmacs is exited. The process will
5031 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
5032 _will_ query the user (this is the default). The return value is
5033 `t' if a query was formerly required, and `nil' otherwise.
5035 (process-kill-without-query (get-process "shell"))
5039 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
5041 56.6 Process Information
5042 ========================
5044 Several functions return information about processes. `list-processes'
5045 is provided for interactive use.
5047 -- Command: list-processes
5048 This command displays a listing of all living processes. In
5049 addition, it finally deletes any process whose status was `Exited'
5050 or `Signaled'. It returns `nil'.
5052 -- Function: process-list
5053 This function returns a list of all processes that have not been
5057 => (#<process display-time> #<process shell>)
5059 -- Function: get-process process-name
5060 This function returns the process named PROCESS-NAME. If
5061 PROCESS-NAME is a string and there is no process with that name,
5062 the value is `nil'. If PROCESS-NAME is actually a process, it is
5063 returned as given. (That is not very useful, so the argument is
5064 usually a name.) For example:
5066 (get-process "shell")
5069 -- Function: process-command process
5070 This function returns the command that was executed to start
5071 PROCESS. This is a list of strings, the first string being the
5072 program executed and the rest of the strings being the arguments
5073 that were given to the program.
5075 (process-command (get-process "shell"))
5076 => ("/bin/csh" "-i")
5078 -- Function: process-id process
5079 This function returns the PID of PROCESS. This is an integer that
5080 distinguishes the process PROCESS from all other processes running
5081 on the same computer at the current time. The PID of a process is
5082 chosen by the operating system kernel when the process is started
5083 and remains constant as long as the process exists.
5085 -- Function: process-name process
5086 This function returns the name of PROCESS.
5088 -- Function: process-status process
5089 This function returns the status of PROCESS as a symbol. The
5090 argument PROCESS must be a process, a buffer, a process name
5091 (string) or a buffer name (string).
5093 The possible values for an actual subprocess are:
5096 for a process that is running.
5099 for a process that is stopped but continuable.
5102 for a process that has exited.
5105 for a process that has received a fatal signal.
5108 for a network connection that is open.
5111 for a network connection that is closed. Once a connection
5112 is closed, you cannot reopen it, though you might be able to
5113 open a new connection to the same place.
5116 if PROCESS does not identify an existing process.
5118 (process-status "shell")
5120 (process-status (get-buffer "*shell*"))
5127 For a network connection, `process-status' returns one of the
5128 symbols `open' or `closed'. The latter means that the other side
5129 closed the connection, or XEmacs did `delete-process'.
5131 In earlier Emacs versions (prior to version 19), the status of a
5132 network connection was `run' if open, and `exit' if closed.
5134 -- Function: process-kill-without-query-p process
5135 This function returns whether PROCESS will be killed without
5136 querying the user, if it is running when XEmacs is exited. The
5137 default value is `nil'.
5139 -- Function: process-exit-status process
5140 This function returns the exit status of PROCESS or the signal
5141 number that killed it. (Use the result of `process-status' to
5142 determine which of those it is.) If PROCESS has not yet
5143 terminated, the value is 0.
5145 -- Function: process-tty-name process
5146 This function returns the terminal name that PROCESS is using for
5147 its communication with Emacs--or `nil' if it is using pipes
5148 instead of a terminal (see `process-connection-type' in *Note
5149 Asynchronous Processes::).
5152 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
5154 56.7 Sending Input to Processes
5155 ===============================
5157 Asynchronous subprocesses receive input when it is sent to them by
5158 XEmacs, which is done with the functions in this section. You must
5159 specify the process to send input to, and the input data to send. The
5160 data appears on the "standard input" of the subprocess.
5162 Some operating systems have limited space for buffered input in a
5163 PTY. On these systems, XEmacs sends long input in chunks, with EOF
5164 characters added amidst the other characters, to force the operating
5165 system to periodically drain the input buffer. For most programs,
5166 these EOFs do no harm.
5168 -- Function: process-send-string process string &optional start end
5169 This function sends PROCESS the contents of STRING as standard
5172 The argument PROCESS may be a process or the name of a process, or
5173 a buffer or the name of a buffer, in which case the buffer's
5174 process is used. If it is `nil', the current buffer's process is
5177 Optional arguments START and END specify part of STRING; see
5180 The function returns `nil'.
5182 (process-send-string "shell<1>" "ls\n")
5186 ---------- Buffer: *shell* ----------
5188 introduction.texi syntax-tables.texi~
5189 introduction.texi~ text.texi
5190 introduction.txt text.texi~
5192 ---------- Buffer: *shell* ----------
5194 -- Function: process-send-region process start end &optional buffer
5195 This function sends the text in the region defined by START and
5196 END as standard input to PROCESS.
5198 The argument PROCESS may be a process or the name of a process, or
5199 a buffer or the name of a buffer, in which case the buffer's
5200 process is used. If it is `nil', the current buffer's process is
5203 An error is signaled unless both START and END are integers or
5204 markers that indicate positions in the current buffer. (It is
5205 unimportant which number is larger.)
5207 -- Function: process-send-eof &optional process
5208 This function makes PROCESS see an end-of-file in its input. The
5209 EOF comes after any text already sent to it.
5211 PROCESS may be a process, a buffer, the name of a process or
5212 buffer, or `nil', indicating the current buffer's process. An
5213 error is signaled if PROCESS does not identify any process.
5215 The function returns the process object identified by PROCESS.
5217 (process-send-eof "shell")
5221 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
5223 56.8 Sending Signals to Processes
5224 =================================
5226 "Sending a signal" to a subprocess is a way of interrupting its
5227 activities. There are several different signals, each with its own
5228 meaning. The set of signals and their names is defined by the operating
5229 system. For example, the signal `SIGINT' means that the user has typed
5230 `C-c', or that some analogous thing has happened.
5232 Each signal has a standard effect on the subprocess. Most signals
5233 kill the subprocess, but some stop or resume execution instead. Most
5234 signals can optionally be handled by programs; if the program handles
5235 the signal, then we can say nothing in general about its effects.
5237 The set of signals and their names is defined by the operating
5238 system; XEmacs has facilities for sending only a few of the signals
5239 that are defined. XEmacs can send signals only to its own subprocesses.
5241 You can send signals explicitly by calling the functions in this
5242 section. XEmacs also sends signals automatically at certain times:
5243 killing a buffer sends a `SIGHUP' signal to all its associated
5244 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
5245 processes. (`SIGHUP' is a signal that indicates that the connection
5246 between the user and the process is broken, for example if a connection
5247 via a telephone line is hung up.)
5249 Each of the signal-sending functions takes two optional arguments:
5250 PROCESS and CURRENT-GROUP.
5252 The argument PROCESS must be either a process or a buffer, the name
5253 of one, or `nil'. If it is `nil', the process defaults to the process
5254 associated with the current buffer. An error is signaled if PROCESS
5255 does not identify a process.
5257 The argument CURRENT-GROUP is a flag that makes a difference when
5258 you are running a job-control shell as an XEmacs subprocess. If it is
5259 non-`nil', then the signal is sent to the current foreground process
5260 group of the terminal that XEmacs uses to communicate with the
5261 subprocess. If the process is a job-control shell, this means the
5262 shell's current subjob. If it is `nil', the signal is sent to the
5263 process group of the immediate subprocess of XEmacs. If the subprocess
5264 is a job-control shell, this is the shell itself.
5266 The flag CURRENT-GROUP has no effect when a pipe is used to
5267 communicate with the subprocess, because the operating system does not
5268 support the distinction in the case of pipes. For the same reason,
5269 job-control shells won't work when a pipe is used. See
5270 `process-connection-type' in *Note Asynchronous Processes::.
5272 Some of the functions below take a SIGNAL argument, which identifies
5273 a signal to be sent. It must be either an integer or a symbol which
5274 names the signal, like `SIGSEGV'.
5276 -- Function: process-send-signal signal &optional process current-group
5277 This function sends the signal SIGNAL to the process PROCESS. The
5278 following functions can be implemented in terms of
5279 `process-send-signal'.
5281 -- Function: interrupt-process &optional process current-group
5282 This function interrupts the process PROCESS by sending the signal
5283 `SIGINT'. Outside of XEmacs, typing the "interrupt character"
5284 (normally `C-c') sends this signal. When the argument
5285 CURRENT-GROUP is non-`nil', you can think of this function as
5286 "typing `C-c'" on the terminal by which XEmacs talks to the
5289 -- Function: kill-process &optional process current-group
5290 This function kills the process PROCESS by sending the signal
5291 `SIGKILL'. This signal kills the subprocess immediately, and
5292 cannot be handled by the subprocess.
5294 -- Function: quit-process &optional process current-group
5295 This function sends the signal `SIGQUIT' to the process PROCESS.
5296 This signal is the one sent by the "quit character" (usually
5297 `C-\') when you are not inside XEmacs.
5299 -- Function: stop-process &optional process current-group
5300 This function stops the process PROCESS by sending the signal
5301 `SIGTSTP'. Use `continue-process' to resume its execution.
5303 On systems with job control, the "stop character" (usually `C-z')
5304 sends this signal (outside of XEmacs). When CURRENT-GROUP is
5305 non-`nil', you can think of this function as "typing `C-z'" on the
5306 terminal XEmacs uses to communicate with the subprocess.
5308 -- Function: continue-process &optional process current-group
5309 This function resumes execution of the process PROCESS by sending
5310 it the signal `SIGCONT'. This presumes that PROCESS was stopped
5313 -- Command: signal-process pid signal
5314 This function sends a signal to the process with process id PID,
5315 which need not be a child of XEmacs. The argument SIGNAL
5316 specifies which signal to send.
5319 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
5321 56.9 Receiving Output from Processes
5322 ====================================
5324 There are two ways to receive the output that a subprocess writes to
5325 its standard output stream. The output can be inserted in a buffer,
5326 which is called the associated buffer of the process, or a function
5327 called the "filter function" can be called to act on the output. If
5328 the process has no buffer and no filter function, its output is
5333 * Process Buffers:: If no filter, output is put in a buffer.
5334 * Filter Functions:: Filter functions accept output from the process.
5335 * Accepting Output:: Explicitly permitting subprocess output.
5336 Waiting for subprocess output.
5339 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
5341 56.9.1 Process Buffers
5342 ----------------------
5344 A process can (and usually does) have an "associated buffer", which is
5345 an ordinary Emacs buffer that is used for two purposes: storing the
5346 output from the process, and deciding when to kill the process. You
5347 can also use the buffer to identify a process to operate on, since in
5348 normal practice only one process is associated with any given buffer.
5349 Many applications of processes also use the buffer for editing input to
5350 be sent to the process, but this is not built into XEmacs Lisp.
5352 Unless the process has a filter function (*note Filter Functions::),
5353 its output is inserted in the associated buffer. The position to insert
5354 the output is determined by the `process-mark', which is then updated
5355 to point to the end of the text just inserted. Usually, but not
5356 always, the `process-mark' is at the end of the buffer.
5358 -- Function: process-buffer process
5359 This function returns the associated buffer of the process PROCESS.
5361 (process-buffer (get-process "shell"))
5362 => #<buffer *shell*>
5364 -- Function: process-mark process
5365 This function returns the process marker for PROCESS, which is the
5366 marker that says where to insert output from the process.
5368 If PROCESS does not have a buffer, `process-mark' returns a marker
5369 that points nowhere.
5371 Insertion of process output in a buffer uses this marker to decide
5372 where to insert, and updates it to point after the inserted text.
5373 That is why successive batches of output are inserted
5376 Filter functions normally should use this marker in the same
5377 fashion as is done by direct insertion of output in the buffer. A
5378 good example of a filter function that uses `process-mark' is
5379 found at the end of the following section.
5381 When the user is expected to enter input in the process buffer for
5382 transmission to the process, the process marker is useful for
5383 distinguishing the new input from previous output.
5385 -- Function: set-process-buffer process buffer
5386 This function sets the buffer associated with PROCESS to BUFFER.
5387 If BUFFER is `nil', the process becomes associated with no buffer.
5389 -- Function: get-buffer-process buffer-or-name
5390 This function returns the process associated with BUFFER-OR-NAME.
5391 If there are several processes associated with BUFFER-OR-NAME,
5392 then one is chosen. (Presently, the one chosen is the one most
5393 recently created.) It is usually a bad idea to have more than one
5394 process associated with the same buffer.
5396 (get-buffer-process "*shell*")
5399 Killing the process's buffer deletes the process, which kills the
5400 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
5403 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
5405 56.9.2 Process Filter Functions
5406 -------------------------------
5408 A process "filter function" is a function that receives the standard
5409 output from the associated process. If a process has a filter, then
5410 _all_ output from that process is passed to the filter. The process
5411 buffer is used directly for output from the process only when there is
5414 A filter function must accept two arguments: the associated process
5415 and a string, which is the output. The function is then free to do
5416 whatever it chooses with the output.
5418 A filter function runs only while XEmacs is waiting (e.g., for
5419 terminal input, or for time to elapse, or for process output). This
5420 avoids the timing errors that could result from running filters at
5421 random places in the middle of other Lisp programs. You may explicitly
5422 cause Emacs to wait, so that filter functions will run, by calling
5423 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
5424 (*note Accepting Output::). Emacs is also waiting when the command loop
5427 Quitting is normally inhibited within a filter function--otherwise,
5428 the effect of typing `C-g' at command level or to quit a user command
5429 would be unpredictable. If you want to permit quitting inside a filter
5430 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
5432 If an error happens during execution of a filter function, it is
5433 caught automatically, so that it doesn't stop the execution of whatever
5434 program was running when the filter function was started. However, if
5435 `debug-on-error' is non-`nil', the error-catching is turned off. This
5436 makes it possible to use the Lisp debugger to debug the filter
5437 function. *Note Debugger::.
5439 Many filter functions sometimes or always insert the text in the
5440 process's buffer, mimicking the actions of XEmacs when there is no
5441 filter. Such filter functions need to use `set-buffer' in order to be
5442 sure to insert in that buffer. To avoid setting the current buffer
5443 semipermanently, these filter functions must use `unwind-protect' to
5444 make sure to restore the previous current buffer. They should also
5445 update the process marker, and in some cases update the value of point.
5446 Here is how to do these things:
5448 (defun ordinary-insertion-filter (process string)
5449 (let ((old-buffer (current-buffer)))
5452 (set-buffer (process-buffer process))
5453 (setq moving (= (point) (process-mark process)))
5455 ;; Insert the text, moving the process-marker.
5456 (goto-char (process-mark process))
5458 (set-marker (process-mark process) (point)))
5459 (if moving (goto-char (process-mark process))))
5460 (set-buffer old-buffer))))
5462 The reason to use an explicit `unwind-protect' rather than letting
5463 `save-excursion' restore the current buffer is so as to preserve the
5464 change in point made by `goto-char'.
5466 To make the filter force the process buffer to be visible whenever
5467 new text arrives, insert the following line just before the
5470 (display-buffer (process-buffer process))
5472 To force point to move to the end of the new output no matter where
5473 it was previously, eliminate the variable `moving' and call `goto-char'
5476 In earlier Emacs versions, every filter function that did regexp
5477 searching or matching had to explicitly save and restore the match data.
5478 Now Emacs does this automatically; filter functions never need to do it
5479 explicitly. *Note Match Data::.
5481 A filter function that writes the output into the buffer of the
5482 process should check whether the buffer is still alive. If it tries to
5483 insert into a dead buffer, it will get an error. If the buffer is dead,
5484 `(buffer-name (process-buffer PROCESS))' returns `nil'.
5486 The output to the function may come in chunks of any size. A program
5487 that produces the same output twice in a row may send it as one batch
5488 of 200 characters one time, and five batches of 40 characters the next.
5490 -- Function: set-process-filter process filter
5491 This function gives PROCESS the filter function FILTER. If FILTER
5492 is `nil', then the process will have no filter. If FILTER is `t',
5493 then no output from the process will be accepted until the filter
5494 is changed. (Output received during this time is not discarded,
5495 but is queued, and will be processed as soon as the filter is
5498 -- Function: process-filter process
5499 This function returns the filter function of PROCESS, or `nil' if
5500 it has none. `t' means that output processing has been stopped.
5502 Here is an example of use of a filter function:
5504 (defun keep-output (process output)
5505 (setq kept (cons output kept)))
5509 (set-process-filter (get-process "shell") 'keep-output)
5511 (process-send-string "shell" "ls ~/other\n")
5514 => ("lewis@slug[8] % "
5515 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
5516 address.txt backup.psf kolstad.psf
5517 backup.bib~ david.mss resume-Dec-86.mss~
5518 backup.err david.psf resume-Dec.psf
5519 backup.mss dland syllabus.mss
5521 "#backups.mss# backup.mss~ kolstad.mss
5525 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
5527 56.9.3 Accepting Output from Processes
5528 --------------------------------------
5530 Output from asynchronous subprocesses normally arrives only while
5531 XEmacs is waiting for some sort of external event, such as elapsed time
5532 or terminal input. Occasionally it is useful in a Lisp program to
5533 explicitly permit output to arrive at a specific point, or even to wait
5534 until output arrives from a process.
5536 -- Function: accept-process-output &optional process seconds millisec
5537 This function allows XEmacs to read pending output from processes.
5538 The output is inserted in the associated buffers or given to
5539 their filter functions. If PROCESS is non-`nil' then this
5540 function does not return until some output has been received from
5543 The arguments SECONDS and MILLISEC let you specify timeout
5544 periods. The former specifies a period measured in seconds and the
5545 latter specifies one measured in milliseconds. The two time
5546 periods thus specified are added together, and
5547 `accept-process-output' returns after that much time whether or
5548 not there has been any subprocess output. Note that SECONDS is
5549 allowed to be a floating-point number; thus, there is no need to
5550 ever use MILLISEC. (It is retained for compatibility purposes.)
5552 The function `accept-process-output' returns non-`nil' if it did
5553 get some output, or `nil' if the timeout expired before output
5557 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
5559 56.10 Sentinels: Detecting Process Status Changes
5560 =================================================
5562 A "process sentinel" is a function that is called whenever the
5563 associated process changes status for any reason, including signals
5564 (whether sent by XEmacs or caused by the process's own actions) that
5565 terminate, stop, or continue the process. The process sentinel is also
5566 called if the process exits. The sentinel receives two arguments: the
5567 process for which the event occurred, and a string describing the type
5570 The string describing the event looks like one of the following:
5574 * `"exited abnormally with code EXITCODE\n"'.
5576 * `"NAME-OF-SIGNAL\n"'.
5578 * `"NAME-OF-SIGNAL (core dumped)\n"'.
5580 A sentinel runs only while XEmacs is waiting (e.g., for terminal
5581 input, or for time to elapse, or for process output). This avoids the
5582 timing errors that could result from running them at random places in
5583 the middle of other Lisp programs. A program can wait, so that
5584 sentinels will run, by calling `sit-for' or `sleep-for' (*note
5585 Waiting::), or `accept-process-output' (*note Accepting Output::).
5586 Emacs is also waiting when the command loop is reading input.
5588 Quitting is normally inhibited within a sentinel--otherwise, the
5589 effect of typing `C-g' at command level or to quit a user command would
5590 be unpredictable. If you want to permit quitting inside a sentinel,
5591 bind `inhibit-quit' to `nil'. *Note Quitting::.
5593 A sentinel that writes the output into the buffer of the process
5594 should check whether the buffer is still alive. If it tries to insert
5595 into a dead buffer, it will get an error. If the buffer is dead,
5596 `(buffer-name (process-buffer PROCESS))' returns `nil'.
5598 If an error happens during execution of a sentinel, it is caught
5599 automatically, so that it doesn't stop the execution of whatever
5600 programs was running when the sentinel was started. However, if
5601 `debug-on-error' is non-`nil', the error-catching is turned off. This
5602 makes it possible to use the Lisp debugger to debug the sentinel.
5605 In earlier Emacs versions, every sentinel that did regexp searching
5606 or matching had to explicitly save and restore the match data. Now
5607 Emacs does this automatically; sentinels never need to do it explicitly.
5610 -- Function: set-process-sentinel process sentinel
5611 This function associates SENTINEL with PROCESS. If SENTINEL is
5612 `nil', then the process will have no sentinel. The default
5613 behavior when there is no sentinel is to insert a message in the
5614 process's buffer when the process status changes.
5616 (defun msg-me (process event)
5618 (format "Process: %s had the event `%s'" process event)))
5619 (set-process-sentinel (get-process "shell") 'msg-me)
5621 (kill-process (get-process "shell"))
5622 -| Process: #<process shell> had the event `killed'
5625 -- Function: process-sentinel process
5626 This function returns the sentinel of PROCESS, or `nil' if it has
5629 -- Function: waiting-for-user-input-p
5630 While a sentinel or filter function is running, this function
5631 returns non-`nil' if XEmacs was waiting for keyboard input from
5632 the user at the time the sentinel or filter function was called,
5633 `nil' if it was not.
5636 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
5638 56.11 Process Window Size
5639 =========================
5641 -- Function: set-process-window-size process height width
5642 This function tells PROCESS that its logical window size is HEIGHT
5643 by WIDTH characters. This is principally useful with pty's.
5646 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
5648 56.12 Transaction Queues
5649 ========================
5651 You can use a "transaction queue" for more convenient communication
5652 with subprocesses using transactions. First use `tq-create' to create
5653 a transaction queue communicating with a specified process. Then you
5654 can call `tq-enqueue' to send a transaction.
5656 -- Function: tq-create process
5657 This function creates and returns a transaction queue
5658 communicating with PROCESS. The argument PROCESS should be a
5659 subprocess capable of sending and receiving streams of bytes. It
5660 may be a child process, or it may be a TCP connection to a server,
5661 possibly on another machine.
5663 -- Function: tq-enqueue queue question regexp closure fn
5664 This function sends a transaction to queue QUEUE. Specifying the
5665 queue has the effect of specifying the subprocess to talk to.
5667 The argument QUESTION is the outgoing message that starts the
5668 transaction. The argument FN is the function to call when the
5669 corresponding answer comes back; it is called with two arguments:
5670 CLOSURE, and the answer received.
5672 The argument REGEXP is a regular expression that should match the
5673 entire answer, but nothing less; that's how `tq-enqueue' determines
5674 where the answer ends.
5676 The return value of `tq-enqueue' itself is not meaningful.
5678 -- Function: tq-close queue
5679 Shut down transaction queue QUEUE, waiting for all pending
5680 transactions to complete, and then terminate the connection or
5683 Transaction queues are implemented by means of a filter function.
5684 *Note Filter Functions::.
5687 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
5689 56.13 Network Connections
5690 =========================
5692 XEmacs Lisp programs can open TCP network connections to other
5693 processes on the same machine or other machines. A network connection
5694 is handled by Lisp much like a subprocess, and is represented by a
5695 process object. However, the process you are communicating with is not
5696 a child of the XEmacs process, so you can't kill it or send it signals.
5697 All you can do is send and receive data. `delete-process' closes the
5698 connection, but does not kill the process at the other end; that
5699 process must decide what to do about closure of the connection.
5701 You can distinguish process objects representing network connections
5702 from those representing subprocesses with the `process-status'
5703 function. It always returns either `open' or `closed' for a network
5704 connection, and it never returns either of those values for a real
5705 subprocess. *Note Process Information::.
5707 -- Function: open-network-stream name buffer-or-name host service
5709 This function opens a TCP connection for a service to a host. It
5710 returns a process object to represent the connection.
5712 Input and output work as for other process objects.
5713 `delete-process' closes the connection.
5715 The NAME argument specifies the name for the process object. It
5716 is modified as necessary to make it unique.
5718 The BUFFER-OR-NAME argument is the buffer to associate with the
5719 connection. It can be a buffer or the name of one. Output from
5720 the connection is inserted in the buffer, unless you specify a
5721 filter function to handle the output. If BUFFER-OR-NAME is `nil',
5722 it means that the connection is not associated with any buffer.
5724 The arguments HOST and SERVICE specify where to connect to; HOST
5725 is the host name or IP address (a string), and SERVICE is the name
5726 of a defined network service (a string) or a port number (an
5729 Optional fifth arg PROTOCOL is the network protocol to use.
5730 Currently only `tcp' (Transmission Control Protocol) and `udp'
5731 (User Datagram Protocol) are supported. When omitted, `tcp' is
5734 Output via `process-send-string' and input via buffer or filter
5735 (see `set-process-filter') are stream-oriented. That means UDP
5736 datagrams are not guaranteed to be sent and received in discrete
5737 packets. (But small datagrams around 500 bytes that are not
5738 truncated by `process-send-string' are usually fine.) Note further
5739 that the UDP protocol does not guard against lost packets.
5742 File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
5744 57 Operating System Interface
5745 *****************************
5747 This chapter is about starting and getting out of Emacs, access to
5748 values in the operating system environment, and terminal input, output,
5751 *Note Building XEmacs::, for related information. See also *Note
5752 Display::, for additional operating system status information
5753 pertaining to the terminal and the screen.
5757 * Starting Up:: Customizing XEmacs start-up processing.
5758 * Getting Out:: How exiting works (permanent or temporary).
5759 * System Environment:: Distinguish the name and kind of system.
5760 * User Identification:: Finding the name and user id of the user.
5761 * Time of Day:: Getting the current time.
5762 * Time Conversion:: Converting a time from numeric form to a string, or
5763 to calendrical data (or vice versa).
5764 * Timers:: Setting a timer to call a function at a certain time.
5765 * Terminal Input:: Recording terminal input for debugging.
5766 * Terminal Output:: Recording terminal output for debugging.
5767 * Flow Control:: How to turn output flow control on or off.
5768 * Batch Mode:: Running XEmacs without terminal interaction.
5771 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
5773 57.1 Starting Up XEmacs
5774 =======================
5776 This section describes what XEmacs does when it is started, and how you
5777 can customize these actions.
5781 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
5782 * Init File:: Details on reading the init file (`.emacs').
5783 * Terminal-Specific:: How the terminal-specific Lisp file is read.
5784 * Command Line Arguments:: How command line arguments are processed,
5785 and how you can customize them.
5788 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
5790 57.1.1 Summary: Sequence of Actions at Start Up
5791 -----------------------------------------------
5793 The order of operations performed (in `startup.el') by XEmacs when it
5794 is started up is as follows:
5796 1. It loads the initialization library for the window system, if you
5797 are using a window system. This library's name is
5798 `term/WINDOWSYSTEM-win.el'.
5800 2. It processes the initial options. (Some of them are handled even
5803 3. It initializes the X window frame and faces, if appropriate.
5805 4. It runs the normal hook `before-init-hook'.
5807 5. It loads the library `site-start', unless the option
5808 `-no-site-file' was specified. The library's file name is usually
5811 6. It loads the file `~/.emacs' unless `-q' was specified on the
5812 command line. (This is not done in `-batch' mode.) The `-u'
5813 option can specify the user name whose home directory should be
5814 used instead of `~'.
5816 7. It loads the library `default' unless `inhibit-default-init' is
5817 non-`nil'. (This is not done in `-batch' mode or if `-q' was
5818 specified on the command line.) The library's file name is
5819 usually `default.el'.
5821 8. It runs the normal hook `after-init-hook'.
5823 9. It sets the major mode according to `initial-major-mode', provided
5824 the buffer `*scratch*' is still current and still in Fundamental
5827 10. It loads the terminal-specific Lisp file, if any, except when in
5828 batch mode or using a window system.
5830 11. It displays the initial echo area message, unless you have
5831 suppressed that with `inhibit-startup-echo-area-message'.
5833 12. It processes the action arguments from the command line.
5835 13. It runs `term-setup-hook'.
5837 14. It calls `frame-notice-user-settings', which modifies the
5838 parameters of the selected frame according to whatever the init
5841 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
5843 16. It displays copyleft, nonwarranty, and basic use information,
5844 provided there were no remaining command line arguments (a few
5845 steps above) and the value of `inhibit-startup-message' is `nil'.
5847 -- User Option: inhibit-startup-message
5848 This variable inhibits the initial startup messages (the
5849 nonwarranty, etc.). If it is non-`nil', then the messages are not
5852 This variable exists so you can set it in your personal init file,
5853 once you are familiar with the contents of the startup message.
5854 Do not set this variable in the init file of a new user, or in a
5855 way that affects more than one user, because that would prevent
5856 new users from receiving the information they are supposed to see.
5858 -- User Option: inhibit-startup-echo-area-message
5859 This variable controls the display of the startup echo area
5860 message. You can suppress the startup echo area message by adding
5861 text with this form to your `.emacs' file:
5863 (setq inhibit-startup-echo-area-message
5866 Simply setting `inhibit-startup-echo-area-message' to your login
5867 name is not sufficient to inhibit the message; Emacs explicitly
5868 checks whether `.emacs' contains an expression as shown above.
5869 Your login name must appear in the expression as a Lisp string
5872 This way, you can easily inhibit the message for yourself if you
5873 wish, but thoughtless copying of your `.emacs' file will not
5874 inhibit the message for someone else.
5877 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
5879 57.1.2 The Init File: `.emacs'
5880 ------------------------------
5882 When you start XEmacs, it normally attempts to load the file `.emacs'
5883 from your home directory. This file, if it exists, must contain Lisp
5884 code. It is called your "init file". The command line switches `-q'
5885 and `-u' affect the use of the init file; `-q' says not to load an init
5886 file, and `-u' says to load a specified user's init file instead of
5887 yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
5889 A site may have a "default init file", which is the library named
5890 `default.el'. XEmacs finds the `default.el' file through the standard
5891 search path for libraries (*note How Programs Do Loading::). The
5892 XEmacs distribution does not come with this file; sites may provide one
5893 for local customizations. If the default init file exists, it is
5894 loaded whenever you start Emacs, except in batch mode or if `-q' is
5895 specified. But your own personal init file, if any, is loaded first; if
5896 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
5897 not subsequently load the `default.el' file.
5899 Another file for site-customization is `site-start.el'. Emacs loads
5900 this _before_ the user's init file. You can inhibit the loading of
5901 this file with the option `-no-site-file'.
5903 -- Variable: site-run-file
5904 This variable specifies the site-customization file to load before
5905 the user's init file. Its normal value is `"site-start"'.
5907 If there is a great deal of code in your `.emacs' file, you should
5908 move it into another file named `SOMETHING.el', byte-compile it (*note
5909 Byte Compilation::), and make your `.emacs' file load the other file
5910 using `load' (*note Loading::).
5912 *Note Init File Examples: (xemacs)Init File Examples, for examples
5913 of how to make various commonly desired customizations in your `.emacs'
5916 -- User Option: inhibit-default-init
5917 This variable prevents XEmacs from loading the default
5918 initialization library file for your session of XEmacs. If its
5919 value is non-`nil', then the default library is not loaded. The
5920 default value is `nil'.
5922 -- Variable: before-init-hook
5923 -- Variable: after-init-hook
5924 These two normal hooks are run just before, and just after,
5925 loading of the user's init file, `default.el', and/or
5929 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
5931 57.1.3 Terminal-Specific Initialization
5932 ---------------------------------------
5934 Each terminal type can have its own Lisp library that XEmacs loads when
5935 run on that type of terminal. For a terminal type named TERMTYPE, the
5936 library is called `term/TERMTYPE'. XEmacs finds the file by searching
5937 the `load-path' directories as it does for other files, and trying the
5938 `.elc' and `.el' suffixes. Normally, terminal-specific Lisp library is
5939 located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
5940 directory in which most XEmacs Lisp libraries are kept.
5942 The library's name is constructed by concatenating the value of the
5943 variable `term-file-prefix' and the terminal type. Normally,
5944 `term-file-prefix' has the value `"term/"'; changing this is not
5947 The usual function of a terminal-specific library is to enable
5948 special keys to send sequences that XEmacs can recognize. It may also
5949 need to set or add to `function-key-map' if the Termcap entry does not
5950 specify all the terminal's function keys. *Note Terminal Input::.
5952 When the name of the terminal type contains a hyphen, only the part
5953 of the name before the first hyphen is significant in choosing the
5954 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
5955 the `term/aaa' library. If necessary, the library can evaluate
5956 `(getenv "TERM")' to find the full name of the terminal type.
5958 Your `.emacs' file can prevent the loading of the terminal-specific
5959 library by setting the variable `term-file-prefix' to `nil'. This
5960 feature is useful when experimenting with your own peculiar
5963 You can also arrange to override some of the actions of the
5964 terminal-specific library by setting the variable `term-setup-hook'.
5965 This is a normal hook which XEmacs runs using `run-hooks' at the end of
5966 XEmacs initialization, after loading both your `.emacs' file and any
5967 terminal-specific libraries. You can use this variable to define
5968 initializations for terminals that do not have their own libraries.
5971 -- Variable: term-file-prefix
5972 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
5973 terminal-specific initialization file as follows:
5975 (load (concat term-file-prefix (getenv "TERM")))
5977 You may set the `term-file-prefix' variable to `nil' in your
5978 `.emacs' file if you do not wish to load the
5979 terminal-initialization file. To do this, put the following in
5980 your `.emacs' file: `(setq term-file-prefix nil)'.
5982 -- Variable: term-setup-hook
5983 This variable is a normal hook that XEmacs runs after loading your
5984 `.emacs' file, the default initialization file (if any) and the
5985 terminal-specific Lisp file.
5987 You can use `term-setup-hook' to override the definitions made by a
5988 terminal-specific file.
5990 -- Variable: window-setup-hook
5991 This variable is a normal hook which XEmacs runs after loading your
5992 `.emacs' file and the default initialization file (if any), after
5993 loading terminal-specific Lisp code, and after running the hook
5997 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
5999 57.1.4 Command Line Arguments
6000 -----------------------------
6002 You can use command line arguments to request various actions when you
6003 start XEmacs. Since you do not need to start XEmacs more than once per
6004 day, and will often leave your XEmacs session running longer than that,
6005 command line arguments are hardly ever used. As a practical matter, it
6006 is best to avoid making the habit of using them, since this habit would
6007 encourage you to kill and restart XEmacs unnecessarily often. These
6008 options exist for two reasons: to be compatible with other editors (for
6009 invocation by other programs) and to enable shell scripts to run
6010 specific Lisp programs.
6012 This section describes how Emacs processes command line arguments,
6013 and how you can customize them.
6015 -- Function: command-line
6016 This function parses the command line that XEmacs was called with,
6017 processes it, loads the user's `.emacs' file and displays the
6020 -- Variable: command-line-processed
6021 The value of this variable is `t' once the command line has been
6024 If you redump XEmacs by calling `dump-emacs', you may wish to set
6025 this variable to `nil' first in order to cause the new dumped
6026 XEmacs to process its new command line arguments.
6028 -- Variable: command-switch-alist
6029 The value of this variable is an alist of user-defined command-line
6030 options and associated handler functions. This variable exists so
6031 you can add elements to it.
6033 A "command line option" is an argument on the command line of the
6038 The elements of the `command-switch-alist' look like this:
6040 (OPTION . HANDLER-FUNCTION)
6042 The HANDLER-FUNCTION is called to handle OPTION and receives the
6043 option name as its sole argument.
6045 In some cases, the option is followed in the command line by an
6046 argument. In these cases, the HANDLER-FUNCTION can find all the
6047 remaining command-line arguments in the variable
6048 `command-line-args-left'. (The entire list of command-line
6049 arguments is in `command-line-args'.)
6051 The command line arguments are parsed by the `command-line-1'
6052 function in the `startup.el' file. See also *Note Command Line
6053 Switches and Arguments: (xemacs)Command Switches.
6055 -- Variable: command-line-args
6056 The value of this variable is the list of command line arguments
6059 -- Variable: command-line-functions
6060 This variable's value is a list of functions for handling an
6061 unrecognized command-line argument. Each time the next argument
6062 to be processed has no special meaning, the functions in this list
6063 are called, in order of appearance, until one of them returns a
6066 These functions are called with no arguments. They can access the
6067 command-line argument under consideration through the variable
6068 `argi'. The remaining arguments (not including the current one)
6069 are in the variable `command-line-args-left'.
6071 When a function recognizes and processes the argument in `argi', it
6072 should return a non-`nil' value to say it has dealt with that
6073 argument. If it has also dealt with some of the following
6074 arguments, it can indicate that by deleting them from
6075 `command-line-args-left'.
6077 If all of these functions return `nil', then the argument is used
6078 as a file name to visit.
6081 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
6083 57.2 Getting out of XEmacs
6084 ==========================
6086 There are two ways to get out of XEmacs: you can kill the XEmacs job,
6087 which exits permanently, or you can suspend it, which permits you to
6088 reenter the XEmacs process later. As a practical matter, you seldom
6089 kill XEmacs--only when you are about to log out. Suspending is much
6094 * Killing XEmacs:: Exiting XEmacs irreversibly.
6095 * Suspending XEmacs:: Exiting XEmacs reversibly.
6098 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
6100 57.2.1 Killing XEmacs
6101 ---------------------
6103 Killing XEmacs means ending the execution of the XEmacs process. The
6104 parent process normally resumes control. The low-level primitive for
6105 killing XEmacs is `kill-emacs'.
6107 -- Command: kill-emacs &optional exit-data
6108 This function exits the XEmacs process and kills it.
6110 If EXIT-DATA is an integer, then it is used as the exit status of
6111 the XEmacs process. (This is useful primarily in batch operation;
6112 see *Note Batch Mode::.)
6114 If EXIT-DATA is a string, its contents are stuffed into the
6115 terminal input buffer so that the shell (or whatever program next
6116 reads input) can read them.
6118 All the information in the XEmacs process, aside from files that have
6119 been saved, is lost when the XEmacs is killed. Because killing XEmacs
6120 inadvertently can lose a lot of work, XEmacs queries for confirmation
6121 before actually terminating if you have buffers that need saving or
6122 subprocesses that are running. This is done in the function
6123 `save-buffers-kill-emacs'.
6125 -- Variable: kill-emacs-query-functions
6126 After asking the standard questions, `save-buffers-kill-emacs'
6127 calls the functions in the list `kill-buffer-query-functions', in
6128 order of appearance, with no arguments. These functions can ask
6129 for additional confirmation from the user. If any of them returns
6130 non-`nil', XEmacs is not killed.
6132 -- Variable: kill-emacs-hook
6133 This variable is a normal hook; once `save-buffers-kill-emacs' is
6134 finished with all file saving and confirmation, it runs the
6135 functions in this hook.
6138 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
6140 57.2.2 Suspending XEmacs
6141 ------------------------
6143 "Suspending XEmacs" means stopping XEmacs temporarily and returning
6144 control to its superior process, which is usually the shell. This
6145 allows you to resume editing later in the same XEmacs process, with the
6146 same buffers, the same kill ring, the same undo history, and so on. To
6147 resume XEmacs, use the appropriate command in the parent shell--most
6150 Some operating systems do not support suspension of jobs; on these
6151 systems, "suspension" actually creates a new shell temporarily as a
6152 subprocess of XEmacs. Then you would exit the shell to return to
6155 Suspension is not useful with window systems such as X, because the
6156 XEmacs job may not have a parent that can resume it again, and in any
6157 case you can give input to some other job such as a shell merely by
6158 moving to a different window. Therefore, suspending is not allowed
6159 when XEmacs is an X client.
6161 -- Command: suspend-emacs &optional stuffstring
6162 This function stops XEmacs and returns control to the superior
6163 process. If and when the superior process resumes XEmacs,
6164 `suspend-emacs' returns `nil' to its caller in Lisp.
6166 If optional arg STUFFSTRING is non-`nil', its characters are sent
6167 to be read as terminal input by XEmacs's superior shell. The
6168 characters in STUFFSTRING are not echoed by the superior shell;
6169 only the results appear.
6171 Before suspending, `suspend-emacs' runs the normal hook
6172 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
6173 normal hook; its value was a single function, and if its value was
6174 non-`nil', then `suspend-emacs' returned immediately without
6175 actually suspending anything.
6177 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
6178 `suspend-resume-hook'. *Note Hooks::.
6180 The next redisplay after resumption will redraw the entire screen,
6181 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
6184 In the following example, note that `pwd' is not echoed after
6185 XEmacs is suspended. But it is read and executed by the shell.
6190 (add-hook 'suspend-hook
6191 (function (lambda ()
6194 (error "Suspend cancelled")))))
6196 (or (y-or-n-p "Really suspend? ")
6197 (error "Suspend cancelled")))
6198 (add-hook 'suspend-resume-hook
6199 (function (lambda () (message "Resumed!"))))
6200 => (lambda nil (message "Resumed!"))
6201 (suspend-emacs "pwd")
6203 ---------- Buffer: Minibuffer ----------
6205 ---------- Buffer: Minibuffer ----------
6207 ---------- Parent Shell ----------
6208 lewis@slug[23] % /user/lewis/manual
6211 ---------- Echo Area ----------
6214 -- Variable: suspend-hook
6215 This variable is a normal hook run before suspending.
6217 -- Variable: suspend-resume-hook
6218 This variable is a normal hook run after suspending.
6221 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
6223 57.3 Operating System Environment
6224 =================================
6226 XEmacs provides access to variables in the operating system environment
6227 through various functions. These variables include the name of the
6228 system, the user's UID, and so on.
6230 -- Variable: system-type
6231 The value of this variable is a symbol indicating the type of
6232 operating system XEmacs is operating on. Here is a table of the
6242 Data General DGUX operating system.
6245 A GNU system using the GNU HURD and Mach.
6248 Hewlett-Packard HPUX operating system.
6251 Silicon Graphics Irix system.
6254 A GNU system using the Linux kernel.
6257 Microsoft MS-DOS "operating system."
6260 NeXT Mach-based system.
6263 Masscomp RTU, UCB universe.
6272 Microsoft windows NT.
6277 We do not wish to add new symbols to make finer distinctions
6278 unless it is absolutely necessary! In fact, we hope to eliminate
6279 some of these alternatives in the future. We recommend using
6280 `system-configuration' to distinguish between different operating
6283 -- Variable: system-configuration
6284 This variable holds the three-part configuration name for the
6285 hardware/software configuration of your system, as a string. The
6286 convenient way to test parts of this string is with `string-match'.
6288 -- Function: system-name
6289 This function returns the name of the machine you are running on.
6291 => "prep.ai.mit.edu"
6293 The symbol `system-name' is a variable as well as a function. In
6294 fact, the function returns whatever value the variable `system-name'
6295 currently holds. Thus, you can set the variable `system-name' in case
6296 Emacs is confused about the name of your system. The variable is also
6297 useful for constructing frame titles (*note Frame Titles::).
6299 -- Variable: mail-host-address
6300 If this variable is non-`nil', it is used instead of `system-name'
6301 for purposes of generating email addresses. For example, it is
6302 used when constructing the default value of `user-mail-address'.
6303 *Note User Identification::. (Since this is done when XEmacs
6304 starts up, the value actually used is the one saved when XEmacs
6305 was dumped. *Note Building XEmacs::.)
6307 -- Command: getenv var &optional interactivep
6308 This function returns the value of the environment variable VAR,
6309 as a string. Within XEmacs, the environment variable values are
6310 kept in the Lisp variable `process-environment'.
6312 When invoked interactively, `getenv' prints the value in the echo
6318 lewis@slug[10] % printenv
6319 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
6325 -- Command: setenv variable &optional value unset
6326 This command sets the value of the environment variable named
6327 VARIABLE to VALUE. Both arguments should be strings. This
6328 function works by modifying `process-environment'; binding that
6329 variable with `let' is also reasonable practice.
6331 -- Variable: process-environment
6332 This variable is a list of strings, each describing one environment
6333 variable. The functions `getenv' and `setenv' work by
6334 manipulating this variable.
6337 => ("l=/usr/stanford/lib/gnuemacs/lisp"
6338 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
6344 -- Variable: path-separator
6345 This variable holds a string which says which character separates
6346 directories in a search path (as found in an environment
6347 variable). Its value is `":"' for Unix and GNU systems, and `";"'
6348 for MS-DOS and Windows NT.
6350 -- Variable: invocation-name
6351 This variable holds the program name under which Emacs was
6352 invoked. The value is a string, and does not include a directory
6355 -- Variable: invocation-directory
6356 This variable holds the directory from which the Emacs executable
6357 was invoked, or perhaps `nil' if that directory cannot be
6360 -- Variable: installation-directory
6361 If non-`nil', this is a directory within which to look for the
6362 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
6363 can't find those directories in their standard installed
6364 locations, but can find them in a directory related somehow to the
6365 one containing the Emacs executable.
6367 -- Function: load-average &optional use-floats
6368 This function returns a list of the current 1-minute, 5-minute and
6369 15-minute load averages. The values are integers that are 100
6370 times the system load averages. (The load averages indicate the
6371 number of processes trying to run.)
6373 When USE-FLOATS is non-`nil', floats will be returned instead of
6374 integers. These floats are not multiplied by 100.
6379 => (1.69921875 1.58984375 1.640625)
6381 lewis@rocky[5] % uptime
6382 8:06pm up 16 day(s), 21:57, 40 users,
6383 load average: 1.68, 1.59, 1.64
6385 If the 5-minute or 15-minute load averages are not available,
6386 return a shortened list, containing only those averages which are
6389 On some systems, this function may require special privileges to
6390 run, or it may be unimplemented for the particular system type.
6391 In that case, the function will signal an error.
6393 -- Function: emacs-pid
6394 This function returns the process ID of the Emacs process.
6397 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
6399 57.4 User Identification
6400 ========================
6402 -- Variable: user-mail-address
6403 This holds the nominal email address of the user who is using
6404 Emacs. When Emacs starts up, it computes a default value that is
6405 usually right, but users often set this themselves when the
6406 default value is not right.
6408 -- Function: user-login-name &optional uid
6409 If you don't specify UID, this function returns the name under
6410 which the user is logged in. If the environment variable `LOGNAME'
6411 is set, that value is used. Otherwise, if the environment variable
6412 `USER' is set, that value is used. Otherwise, the value is based
6413 on the effective UID, not the real UID.
6415 If you specify UID, the value is the user name that corresponds to
6416 UID (which should be an integer).
6421 -- Function: user-real-login-name
6422 This function returns the user name corresponding to Emacs's real
6423 UID. This ignores the effective UID and ignores the environment
6424 variables `LOGNAME' and `USER'.
6426 -- Variable: user-full-name
6427 This variable holds the name of the user running this Emacs. It is
6428 initialized at startup time from the value of `NAME' environment
6429 variable. You can change the value of this variable to alter the
6430 result of the `user-full-name' function.
6432 -- Function: user-full-name &optional user
6433 This function returns the full name of USER. If USER is `nil', it
6434 defaults to the user running this Emacs. In that case, the value
6435 of `user-full-name' variable, if non-`nil', will be used.
6437 If USER is specified explicitly, `user-full-name' variable is
6442 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
6444 => "Hrvoje \"Niksa\" Niksic"
6445 (user-full-name "hniksic")
6448 The symbols `user-login-name', `user-real-login-name' and
6449 `user-full-name' are variables as well as functions. The functions
6450 return the same values that the variables hold. These variables allow
6451 you to "fake out" Emacs by telling the functions what to return. The
6452 variables are also useful for constructing frame titles (*note Frame
6455 -- Function: user-real-uid
6456 This function returns the real UID of the user.
6461 -- Function: user-uid
6462 This function returns the effective UID of the user.
6464 -- Function: user-home-directory
6465 This function returns the "`HOME'" directory of the user, and is
6466 intended to replace occurrences of "`(getenv "HOME")'". Under
6467 Unix systems, the following is done:
6469 1. Return the value of "`(getenv "HOME")'", if set.
6471 2. Return "/", as a fallback, but issue a warning. (Future
6472 versions of XEmacs will also attempt to lookup the `HOME'
6473 directory via `getpwent()', but this has not yet been
6476 Under MS Windows, this is done:
6478 1. Return the value of "`(getenv "HOME")'", if set.
6480 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
6481 both set, return the concatenation (the following description
6482 uses MS Windows environment variable substitution syntax):
6483 `%HOMEDRIVE%%HOMEDIR%'.
6485 3. Return "C:\", as a fallback, but issue a warning.
6488 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
6493 This section explains how to determine the current time and the time
6496 -- Function: current-time-string &optional time-value
6497 This function returns the current time and date as a
6498 humanly-readable string. The format of the string is unvarying;
6499 the number of characters used for each part is always the same, so
6500 you can reliably use `substring' to extract pieces of it. It is
6501 wise to count the characters from the beginning of the string
6502 rather than from the end, as additional information may be added
6505 The argument TIME-VALUE, if given, specifies a time to format
6506 instead of the current time. The argument should be a list whose
6507 first two elements are integers. Thus, you can use times obtained
6508 from `current-time' (see below) and from `file-attributes' (*note
6511 (current-time-string)
6512 => "Wed Oct 14 22:21:05 1987"
6514 -- Function: current-time
6515 This function returns the system's time value as a list of three
6516 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
6517 combine to give the number of seconds since 0:00 January 1, 1970,
6518 which is HIGH * 2**16 + LOW.
6520 The third element, MICROSEC, gives the microseconds since the
6521 start of the current second (or 0 for systems that return time
6522 only on the resolution of a second).
6524 The first two elements can be compared with file time values such
6525 as you get with the function `file-attributes'. *Note File
6528 -- Function: current-time-zone &optional time-value
6529 This function returns a list describing the time zone that the
6532 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
6533 giving the number of seconds ahead of UTC (east of Greenwich). A
6534 negative value means west of Greenwich. The second element, NAME
6535 is a string giving the name of the time zone. Both elements
6536 change when daylight savings time begins or ends; if the user has
6537 specified a time zone that does not use a seasonal time
6538 adjustment, then the value is constant through time.
6540 If the operating system doesn't supply all the information
6541 necessary to compute the value, both elements of the list are
6544 The argument TIME-VALUE, if given, specifies a time to analyze
6545 instead of the current time. The argument should be a cons cell
6546 containing two integers, or a list whose first two elements are
6547 integers. Thus, you can use times obtained from `current-time'
6548 (see above) and from `file-attributes' (*note File Attributes::).
6551 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
6553 57.6 Time Conversion
6554 ====================
6556 These functions convert time values (lists of two or three integers) to
6557 strings or to calendrical information. There is also a function to
6558 convert calendrical information to a time value. You can get time
6559 values from the functions `current-time' (*note Time of Day::) and
6560 `file-attributes' (*note File Attributes::).
6562 -- Function: format-time-string format-string &optional time
6563 This function converts TIME to a string according to
6564 FORMAT-STRING. If TIME is omitted, it defaults to the current
6565 time. The argument FORMAT-STRING may contain `%'-sequences which
6566 say to substitute parts of the time. Here is a table of what the
6570 This stands for the abbreviated name of the day of week.
6573 This stands for the full name of the day of week.
6576 This stands for the abbreviated name of the month.
6579 This stands for the full name of the month.
6582 This is a synonym for `%x %X'.
6585 This has a locale-specific meaning. In the default locale
6586 (named C), it is equivalent to `%A, %B %e, %Y'.
6589 This stands for the day of month, zero-padded.
6592 This is a synonym for `%m/%d/%y'.
6595 This stands for the day of month, blank-padded.
6598 This is a synonym for `%b'.
6601 This stands for the hour (00-23).
6604 This stands for the hour (00-12).
6607 This stands for the day of the year (001-366).
6610 This stands for the hour (0-23), blank padded.
6613 This stands for the hour (1-12), blank padded.
6616 This stands for the month (01-12).
6619 This stands for the minute (00-59).
6622 This stands for a newline.
6625 This stands for `AM' or `PM', as appropriate.
6628 This is a synonym for `%I:%M:%S %p'.
6631 This is a synonym for `%H:%M'.
6634 This stands for the seconds (00-60).
6637 This stands for a tab character.
6640 This is a synonym for `%H:%M:%S'.
6643 This stands for the week of the year (01-52), assuming that
6644 weeks start on Sunday.
6647 This stands for the numeric day of week (0-6). Sunday is day
6651 This stands for the week of the year (01-52), assuming that
6652 weeks start on Monday.
6655 This has a locale-specific meaning. In the default locale
6656 (named C), it is equivalent to `%D'.
6659 This has a locale-specific meaning. In the default locale
6660 (named C), it is equivalent to `%T'.
6663 This stands for the year without century (00-99).
6666 This stands for the year with century.
6669 This stands for the time zone abbreviation.
6671 -- Function: decode-time &optional specified-time
6672 This function converts a time value into calendrical information.
6673 The optional SPECIFIED-TIME should be a list of (HIGH LOW .
6674 IGNORED) or (HIGH . LOW), as from `current-time' and
6675 `file-attributes', or `nil' to use the current time.
6677 The return value is a list of nine elements, as follows:
6679 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
6681 Here is what the elements mean:
6684 The number of seconds past the minute, as an integer between
6688 The number of minutes past the hour, as an integer between 0
6692 The hour of the day, as an integer between 0 and 23.
6695 The day of the month, as an integer between 1 and 31.
6698 The month of the year, as an integer between 1 and 12.
6701 The year, an integer typically greater than 1900.
6704 The day of week, as an integer between 0 and 6, where 0
6708 `t' if daylight savings time is effect, otherwise `nil'.
6711 An integer indicating the time zone, as the number of seconds
6714 Note that Common Lisp has different meanings for DOW and ZONE.
6716 -- Function: encode-time seconds minutes hour day month year &optional
6718 This function is the inverse of `decode-time'. It converts seven
6719 items of calendrical data into a time value. For the meanings of
6720 the arguments, see the table above under `decode-time'.
6722 Year numbers less than 100 are treated just like other year
6723 numbers. If you want them to stand for years above 1900, you must
6724 alter them yourself before you call `encode-time'.
6726 The optional argument ZONE defaults to the current time zone and
6727 its daylight savings time rules. If specified, it can be either a
6728 list (as you would get from `current-time-zone') or an integer (as
6729 you would get from `decode-time'). The specified zone is used
6730 without any further alteration for daylight savings time.
6733 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
6735 57.7 Timers for Delayed Execution
6736 =================================
6738 You can set up a timer to call a function at a specified future time.
6740 -- Function: add-timeout secs function object &optional resignal
6741 This function adds a timeout, to be signaled after the timeout
6742 period has elapsed. SECS is a number of seconds, expressed as an
6743 integer or a float. FUNCTION will be called after that many
6744 seconds have elapsed, with one argument, the given OBJECT. If the
6745 optional RESIGNAL argument is provided, then after this timeout
6746 expires, `add-timeout' will automatically be called again with
6747 RESIGNAL as the first argument.
6749 This function returns an object which is the "id" of this
6750 particular timeout. You can pass that object to `disable-timeout'
6751 to turn off the timeout before it has been signalled.
6753 The number of seconds may be expressed as a floating-point number,
6754 in which case some fractional part of a second will be used.
6755 Caveat: the usable timeout granularity will vary from system to
6758 Adding a timeout causes a timeout event to be returned by
6759 `next-event', and the function will be invoked by
6760 `dispatch-event', so if XEmacs is in a tight loop, the function
6761 will not be invoked until the next call to sit-for or until the
6762 return to top-level (the same is true of process filters).
6764 WARNING: if you are thinking of calling add-timeout from inside of
6765 a callback function as a way of resignalling a timeout, think
6766 again. There is a race condition. That's why the RESIGNAL
6769 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
6770 different semantics.)
6772 -- Function: disable-timeout id
6773 Cancel the requested action for ID, which should be a value
6774 previously returned by `add-timeout'. This cancels the effect of
6775 that call to `add-timeout'; the arrival of the specified time will
6776 not cause anything special to happen. (NOTE: In FSF Emacs, this
6777 function is called `cancel-timer'.)
6780 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
6785 This section describes functions and variables for recording or
6786 manipulating terminal input. See *Note Display::, for related
6791 * Input Modes:: Options for how input is processed.
6792 * Translating Input:: Low level conversion of some characters or events
6794 * Recording Input:: Saving histories of recent or all input events.
6797 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
6802 -- Function: set-input-mode interrupt flow meta &optional quit-char
6804 This function sets the mode for reading keyboard input. If
6805 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
6806 `nil', then it uses CBREAK mode. When XEmacs communicates
6807 directly with X, it ignores this argument and uses interrupts if
6808 that is the way it knows how to communicate.
6810 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
6811 flow control for output to the terminal. This has no effect except
6812 in CBREAK mode. *Note Flow Control::.
6814 The default setting is system dependent. Some systems always use
6815 CBREAK mode regardless of what is specified.
6817 The argument META controls support for input character codes above
6818 127. If META is `t', XEmacs converts characters with the 8th bit
6819 set into Meta characters. If META is `nil', XEmacs disregards the
6820 8th bit; this is necessary when the terminal uses it as a parity
6821 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
6822 input unchanged. This is good for terminals using European 8-bit
6825 If QUIT-CHAR is non-`nil', it specifies the character to use for
6826 quitting. Normally this character is `C-g'. *Note Quitting::.
6828 The `current-input-mode' function returns the input mode settings
6829 XEmacs is currently using.
6831 -- Function: current-input-mode &optional console
6832 This function returns current mode for reading keyboard input. It
6833 returns a list, corresponding to the arguments of `set-input-mode',
6834 of the form `(INTERRUPT FLOW META QUIT)' in which:
6836 is non-`nil' when XEmacs is using interrupt-driven input. If
6837 `nil', Emacs is using CBREAK mode.
6840 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
6841 control for output to the terminal. This value has no effect
6842 unless INTERRUPT is non-`nil'.
6845 is `t' if XEmacs treats the eighth bit of input characters as
6846 the meta bit; `nil' means XEmacs clears the eighth bit of
6847 every input character; any other value means XEmacs uses all
6848 eight bits as the basic character code.
6851 is the character XEmacs currently uses for quitting, usually
6855 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
6857 57.8.2 Translating Input Events
6858 -------------------------------
6860 This section describes features for translating input events into other
6861 input events before they become part of key sequences.
6863 -- Variable: function-key-map
6864 This variable holds a keymap that describes the character sequences
6865 sent by function keys on an ordinary character terminal. This
6866 keymap uses the same data structure as other keymaps, but is used
6867 differently: it specifies translations to make while reading
6870 If `function-key-map' "binds" a key sequence K to a vector V, then
6871 when K appears as a subsequence _anywhere_ in a key sequence, it
6872 is replaced with the events in V.
6874 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
6875 key is pressed. Therefore, we want XEmacs to translate that
6876 sequence of events into the single event `pf1'. We accomplish
6877 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
6880 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
6881 P'; later the function `read-key-sequence' translates this back
6882 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
6884 Entries in `function-key-map' are ignored if they conflict with
6885 bindings made in the minor mode, local, or global keymaps. The
6886 intent is that the character sequences that function keys send
6887 should not have command bindings in their own right.
6889 The value of `function-key-map' is usually set up automatically
6890 according to the terminal's Terminfo or Termcap entry, but
6891 sometimes those need help from terminal-specific Lisp files.
6892 XEmacs comes with terminal-specific files for many common
6893 terminals; their main purpose is to make entries in
6894 `function-key-map' beyond those that can be deduced from Termcap
6895 and Terminfo. *Note Terminal-Specific::.
6897 Emacs versions 18 and earlier used totally different means of
6898 detecting the character sequences that represent function keys.
6900 -- Variable: key-translation-map
6901 This variable is another keymap used just like `function-key-map'
6902 to translate input events into other events. It differs from
6903 `function-key-map' in two ways:
6905 * `key-translation-map' goes to work after `function-key-map' is
6906 finished; it receives the results of translation by
6909 * `key-translation-map' overrides actual key bindings.
6911 The intent of `key-translation-map' is for users to map one
6912 character set to another, including ordinary characters normally
6913 bound to `self-insert-command'.
6915 You can use `function-key-map' or `key-translation-map' for more
6916 than simple aliases, by using a function, instead of a key sequence, as
6917 the "translation" of a key. Then this function is called to compute
6918 the translation of that key.
6920 The key translation function receives one argument, which is the
6921 prompt that was specified in `read-key-sequence'--or `nil' if the key
6922 sequence is being read by the editor command loop. In most cases you
6923 can ignore the prompt value.
6925 If the function reads input itself, it can have the effect of
6926 altering the event that follows. For example, here's how to define
6927 `C-c h' to turn the character that follows into a Hyper character:
6929 (defun hyperify (prompt)
6930 (let ((e (read-event)))
6931 (vector (if (numberp e)
6932 (logior (lsh 1 20) e)
6933 (if (memq 'hyper (event-modifiers e))
6935 (add-event-modifier "H-" e))))))
6937 (defun add-event-modifier (string e)
6938 (let ((symbol (if (symbolp e) e (car e))))
6939 (setq symbol (intern (concat string
6940 (symbol-name symbol))))
6943 (cons symbol (cdr e)))))
6945 (define-key function-key-map "\C-ch" 'hyperify)
6947 The `iso-transl' library uses this feature to provide a way of
6948 inputting non-ASCII Latin-1 characters.
6951 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
6953 57.8.3 Recording Input
6954 ----------------------
6956 -- Function: recent-keys &optional number
6957 This function returns a vector containing recent input events from
6958 the keyboard or mouse. By default, 100 events are recorded, which
6959 is how many `recent-keys' returns.
6961 All input events are included, whether or not they were used as
6962 parts of key sequences. Thus, you always get the last 100 inputs,
6963 not counting keyboard macros. (Events from keyboard macros are
6964 excluded because they are less interesting for debugging; it
6965 should be enough to see the events that invoked the macros.)
6967 If NUMBER is specified, not more than NUMBER events will be
6968 returned. You may change the number of stored events using
6969 `set-recent-keys-ring-size'.
6971 -- Function: recent-keys-ring-size
6972 This function returns the number of recent events stored
6973 internally. This is also the maximum number of events
6974 `recent-keys' can return. By default, 100 events are stored.
6976 -- Function: set-recent-keys-ring-size size
6977 This function changes the number of events stored by XEmacs and
6978 returned by `recent-keys'.
6980 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
6981 remember last 250 events and will make `recent-keys' return last
6982 250 events by default.
6984 -- Command: open-dribble-file filename
6985 This function opens a "dribble file" named FILENAME. When a
6986 dribble file is open, each input event from the keyboard or mouse
6987 (but not those from keyboard macros) is written in that file. A
6988 non-character event is expressed using its printed representation
6989 surrounded by `<...>'.
6991 You close the dribble file by calling this function with an
6994 This function is normally used to record the input necessary to
6995 trigger an XEmacs bug, for the sake of a bug report.
6997 (open-dribble-file "~/dribble")
7000 See also the `open-termscript' function (*note Terminal Output::).
7003 File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
7005 57.9 Terminal Output
7006 ====================
7008 The terminal output functions send output to the terminal or keep track
7009 of output sent to the terminal. The function `device-baud-rate' tells
7010 you what XEmacs thinks is the output speed of the terminal.
7012 -- Function: device-baud-rate &optional device
7013 This function's value is the output speed of the terminal
7014 associated with DEVICE, as far as XEmacs knows. DEVICE defaults
7015 to the selected device (usually the only device) if omitted.
7016 Changing this value does not change the speed of actual data
7017 transmission, but the value is used for calculations such as
7018 padding. This value has no effect for window-system devices.
7019 (This is different in FSF Emacs, where the baud rate also affects
7020 decisions about whether to scroll part of the screen or repaint,
7021 even when using a window system.)
7023 The value is measured in bits per second.
7025 XEmacs attempts to automatically initialize the baud rate by querying
7026 the terminal. If you are running across a network, however, and
7027 different parts of the network work are at different baud rates, the
7028 value returned by XEmacs may be different from the value used by your
7029 local terminal. Some network protocols communicate the local terminal
7030 speed to the remote machine, so that XEmacs and other programs can get
7031 the proper value, but others do not. If XEmacs has the wrong value, it
7032 makes decisions that are less than optimal. To fix the problem, use
7033 `set-device-baud-rate'.
7035 -- Function: set-device-baud-rate device baud-rate
7036 This function sets the output speed of DEVICE. See
7037 `device-baud-rate'. DEVICE defaults to the selected device
7038 (usually the only device) if `nil'.
7040 -- Function: send-string-to-terminal char-or-string &optional stdout-p
7042 This function sends CHAR-OR-STRING to the terminal without
7043 alteration. Control characters in CHAR-OR-STRING have
7044 terminal-dependent effects.
7046 If DEVICE is `nil', this function writes to XEmacs's stderr, or to
7047 stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
7048 tty or stream device, and the function writes to the device's
7049 normal or error output, according to STDOUT-P.
7051 One use of this function is to define function keys on terminals
7052 that have downloadable function key definitions. For example,
7053 this is how on certain terminals to define function key 4 to move
7054 forward four characters (by transmitting the characters `C-u C-f'
7057 (send-string-to-terminal "\eF4\^U\^F")
7060 -- Command: open-termscript filename
7061 This function is used to open a "termscript file" that will record
7062 all the characters sent by XEmacs to the terminal. (If there are
7063 multiple tty or stream devices, all characters sent to all such
7064 devices are recorded.) The function returns `nil'. Termscript
7065 files are useful for investigating problems where XEmacs garbles
7066 the screen, problems that are due to incorrect Termcap entries or
7067 to undesirable settings of terminal options more often than to
7068 actual XEmacs bugs. Once you are certain which characters were
7069 actually output, you can determine reliably whether they
7070 correspond to the Termcap specifications in use.
7072 A `nil' value for FILENAME stops recording terminal output.
7074 See also `open-dribble-file' in *Note Terminal Input::.
7076 (open-termscript "../junk/termscript")