1 This is ../info/lispref.info, produced by makeinfo version 4.6 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: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
58 - Function: x-font-size font
59 This function returns the nominal size of the given font. This is
60 done by parsing its name, so it's likely to lose. X fonts can be
61 specified (by the user) in either pixels or 10ths of points, and
62 this returns the first one it finds, so you have to decide which
63 units the returned value is measured in yourself ...
65 - Function: x-find-larger-font font &optional device
66 This function loads a new, slightly larger version of the given
67 font (or font name). Returns the font if it succeeds, `nil'
68 otherwise. If scalable fonts are available, this returns a font
69 which is 1 point larger. Otherwise, it returns the next larger
70 version of this font that is defined.
72 - Function: x-find-smaller-font font &optional device
73 This function loads a new, slightly smaller version of the given
74 font (or font name). Returns the font if it succeeds, `nil'
75 otherwise. If scalable fonts are available, this returns a font
76 which is 1 point smaller. Otherwise, it returns the next smaller
77 version of this font that is defined.
80 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
82 Font Instance Characteristics
83 -----------------------------
85 - Function: font-instance-properties font-instance
86 This function returns the properties (an alist or `nil') of
89 - Function: x-make-font-bold font &optional device
90 Given an X font specification, this attempts to make a "bold" font.
91 If it fails, it returns `nil'.
93 - Function: x-make-font-unbold font &optional device
94 Given an X font specification, this attempts to make a non-bold
95 font. If it fails, it returns `nil'.
97 - Function: x-make-font-italic font &optional device
98 Given an X font specification, this attempts to make an "italic"
99 font. If it fails, it returns `nil'.
101 - Function: x-make-font-unitalic font &optional device
102 Given an X font specification, this attempts to make a non-italic
103 font. If it fails, it returns `nil'.
105 - Function: x-make-font-bold-italic font &optional device
106 Given an X font specification, this attempts to make a
107 "bold-italic" font. If it fails, it returns `nil'.
110 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
112 Font Convenience Functions
113 --------------------------
115 - Function: font-name font &optional domain
116 This function returns the name of the FONT in the specified
117 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
118 is normally a window and defaults to the selected window if
119 omitted. This is equivalent to using `specifier-instance' and
120 applying `font-instance-name' to the result.
122 - Function: font-truename font &optional domain
123 This function returns the truename of the FONT in the specified
124 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
125 is normally a window and defaults to the selected window if
126 omitted. This is equivalent to using `specifier-instance' and
127 applying `font-instance-truename' to the result.
129 - Function: font-properties font &optional domain
130 This function returns the properties of the FONT in the specified
131 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
132 is normally a window and defaults to the selected window if
133 omitted. This is equivalent to using `specifier-instance' and
134 applying `font-instance-properties' to the result.
137 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
144 * Color Specifiers:: Specifying how a color will appear.
145 * Color Instances:: What a color specifier gets instanced as.
146 * Color Instance Properties:: Properties of color instances.
147 * Color Convenience Functions:: Convenience functions that automatically
148 instance and retrieve the properties
149 of a color specifier.
152 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
157 - Function: color-specifier-p object
158 This function returns non-`nil' if OBJECT is a color specifier.
160 - Function: make-color-specifier spec-list
161 Return a new `color' specifier object with the given specification
162 list. SPEC-LIST can be a list of specifications (each of which is
163 a cons of a locale and a list of instantiators), a single
164 instantiator, or a list of instantiators. *Note Specifiers::, for
165 a detailed description of how specifiers work.
167 Valid instantiators for color specifiers are:
169 * A string naming a color (e.g. under X this might be
170 "lightseagreen2" or "#F534B2").
172 * A color instance (use that instance directly if the device
173 matches, or use the string that generated it).
175 * A vector of no elements (only on TTY's; this means to set no
176 color at all, thus using the "natural" color of the
179 * A vector of one or two elements: a face to inherit from, and
180 optionally a symbol naming which property of that face to
181 inherit, either `foreground' or `background' (if omitted,
182 defaults to the same property that this color specifier is
183 used for; if this specifier is not part of a face, the
184 instantiator would not be valid).
186 - Function: make-face-boolean-specifier spec-list
187 Return a new `face-boolean' specifier object with the given spec
188 list. SPEC-LIST can be a list of specifications (each of which is
189 a cons of a locale and a list of instantiators), a single
190 instantiator, or a list of instantiators. *Note Specifiers::, for
191 a detailed description of how specifiers work.
193 Valid instantiators for face-boolean specifiers are
197 * A vector of two or three elements: a face to inherit from,
198 optionally a symbol naming the property of that face to
199 inherit from (if omitted, defaults to the same property that
200 this face-boolean specifier is used for; if this specifier is
201 not part of a face, the instantiator would not be valid), and
202 optionally a value which, if non-`nil', means to invert the
203 sense of the inherited property.
207 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
212 A "color-instance object" is an object describing the way a color
213 specifier is instanced in a particular domain. Functions such as
214 `face-background-instance' return a color-instance object. For example,
216 (face-background-instance 'default (next-window))
217 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
219 The color-instance object returned describes the way the background
220 color of the `default' face is displayed in the next window after the
223 - Function: color-instance-p object
224 This function returns non-`nil' if OBJECT is a color-instance.
227 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
229 Color Instance Properties
230 -------------------------
232 - Function: color-instance-name color-instance
233 This function returns the name used to allocate COLOR-INSTANCE.
235 - Function: color-instance-rgb-components color-instance
236 This function returns a three element list containing the red,
237 green, and blue color components of COLOR-INSTANCE.
239 (color-instance-rgb-components
240 (face-background-instance 'default (next-window)))
241 => (65535 58596 46517)
244 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
246 Color Convenience Functions
247 ---------------------------
249 - Function: color-name color &optional domain
250 This function returns the name of the COLOR in the specified
251 DOMAIN, if any. COLOR should be a color specifier object and
252 DOMAIN is normally a window and defaults to the selected window if
253 omitted. This is equivalent to using `specifier-instance' and
254 applying `color-instance-name' to the result.
256 - Function: color-rgb-components color &optional domain
257 This function returns the RGB components of the COLOR in the
258 specified DOMAIN, if any. COLOR should be a color specifier
259 object and DOMAIN is normally a window and defaults to the
260 selected window if omitted. This is equivalent to using
261 `specifier-instance' and applying `color-instance-rgb-components'
264 (color-rgb-components (face-background 'default (next-window)))
265 => (65535 58596 46517)
268 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
273 A "glyph" is an object that is used for pixmaps, widgets and images of
274 all sorts, as well as for things that "act" like pixmaps, such as
275 non-textual strings ("annotations") displayed in a buffer or in the
276 margins. It is used in begin-glyphs and end-glyphs attached to
277 extents, marginal and textual annotations, overlay arrows
278 (`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
279 icons, truncation and continuation markers, and the like. (Basically,
280 any place there is an image or something that acts like an image, there
281 will be a glyph object representing it.)
283 The actual image that is displayed (as opposed to its position or
284 clipping) is defined by an "image specifier" object contained within
285 the glyph. The separation between an image specifier object and a
286 glyph object is made because the glyph includes other properties than
287 just the actual image: e.g. the face it is displayed in (for text
288 images), the alignment of the image (when it is in a buffer), etc.
290 - Function: glyphp object
291 This function returns `t' if OBJECT is a glyph.
295 * Glyph Functions:: Functions for working with glyphs.
296 * Images:: Graphical images displayed in a frame.
297 * Glyph Types:: Each glyph has a particular type.
298 * Mouse Pointer:: Controlling the mouse pointer.
299 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
300 * Subwindows:: Inserting an externally-controlled subwindow
302 * Glyph Examples:: Examples of how to work with glyphs.
305 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
312 * Creating Glyphs:: Creating new glyphs.
313 * Glyph Properties:: Accessing and modifying a glyph's properties.
314 * Glyph Convenience Functions::
315 Convenience functions for accessing particular
316 properties of a glyph.
317 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
320 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
325 - Function: make-glyph &optional spec-list type
326 This function creates a new glyph object of type TYPE.
328 SPEC-LIST is used to initialize the glyph's image. It is
329 typically an image instantiator (a string or a vector; *Note Image
330 Specifiers::), but can also be a list of such instantiators (each
331 one in turn is tried until an image is successfully produced), a
332 cons of a locale (frame, buffer, etc.) and an instantiator, a list
333 of such conses, or any other form accepted by
334 `canonicalize-spec-list'. *Note Specifiers::, for more
335 information about specifiers.
337 TYPE specifies the type of the glyph, which specifies in which
338 contexts the glyph can be used, and controls the allowable image
339 types into which the glyph's image can be instantiated. TYPE
340 should be one of `buffer' (used for glyphs in an extent, the
341 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
342 for the mouse-pointer), or `icon' (used for a frame's icon), and
343 defaults to `buffer'. *Note Glyph Types::.
345 A glyph in XEmacs does *NOT* refer to a single unit of textual
346 display (the XEmacs term for this is "rune"), but rather is an
347 object encapsulating a graphical element, such as an image or
348 widget (an element such as a button or text field; "widget" is the
349 term for this under X Windows, and it's called a "control" under
350 MS Windows). This graphical element could appear in a buffer, a
351 margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
354 Creating a glyph using `make-glyph' does not specify _where_ the
355 glyph will be used, but it does specify _what_ the glyph will look
356 like. In particular, SPEC-LIST is used to specify this, and it's
357 used to initialize the glyph's `image' property, which is an image
358 specifier. (Note that "image" as used in the context of a glyph's
359 `image' property or in the terms "image specifier", "image
360 instantiator", or "image instance" does not refer to what people
361 normally think of as an image (which in XEmacs is called a
362 "pixmap"), but to any graphical element--a pixmap, a widget, or
363 even a block of text, when used in the places that call for a
364 glyph.) The format of the SPEC-LIST is typically an image
365 instantiator (a string or a vector; *Note Image Specifiers::), but
366 can also be a list of such instantiators (each one in turn is
367 tried until an image is successfully produced), a cons of a locale
368 (frame, buffer, etc.) and an instantiator, a list of such conses,
369 or any other form accepted by `canonicalize-spec-list'. *Note
370 Specifiers::, for more information about specifiers.
372 If you're not familiar with specifiers, you should be in order to
373 understand how glyphs work. The clearest introduction to
374 specifiers is in the Lispref manual, available under Info. (Choose
375 Help->Info->Info Contents on the menubar or type C-h i.) You can
376 also see `make-specifier' for a capsule summary. What's important
377 to keep in mind is that a specifier lets you set a different value
378 for any particular buffer, window, frame, device, or console.
379 This allows for a great deal of flexibility; in particular, only
380 one global glyph needs to exist for a particular purpose (e.g. the
381 icon used to represent an iconified frame, the mouse pointer used
382 over particular areas of a frame, etc.), and in these cases you do
383 not create your own glyph, but rather modify the existing one.
385 As well as using SPEC-LIST to initialize the glyph, you can set
386 specifications using `set-glyph-image'. Note that, due to a
387 possibly questionable historical design decision, a glyph itself
388 is not actually a specifier, but rather is an object containing an
389 image specifier (as well as other, seldom-used properties).
390 Therefore, you cannot set or access specifications for the glyph's
391 image by directly using `set-specifier', `specifier-instance' or
392 the like on the glyph; instead use them on `(glyph-image GLYPH)'
393 or use the convenience functions `set-glyph-image',
394 `glyph-image-instance', and `glyph-image'.
396 Once you have created a glyph, you specify where it will be used as
399 * To insert a glyph into a buffer, create an extent in the
400 buffer and then use `set-extent-begin-glyph' or
401 `set-extent-end-glyph' to set a glyph to be displayed at the
402 corresponding edge of the extent. (It is common to create
403 zero-width extents for this purpose.)
405 * To insert a glyph into the left or right margin of a buffer,
406 first make sure the margin is visible by setting a value for
407 the specifiers `left-margin-width' or `right-margin-width'.
408 (Not strictly necessary when using margin glyphs with layout
409 policy `whitespace'.) Then follow the same procedure above
410 for inserting a glyph in a buffer, and then set a non-default
411 layout policy for the glyph using
412 `set-extent-begin-glyph-layout' or
413 `set-extent-end-glyph-layout'. Alternatively, use the
414 high-level annotations API (see `make-annotation'). (In point
415 of fact, you can also use the annotations API for glyphs in a
416 buffer, by setting a layout policy of `text'.)
418 * To insert a glyph into the modeline, just put the glyph
419 directly as one of the modeline elements. (Unfortunately you
420 can't currently put a begin glyph or end glyph on one of the
421 modeline extents--they're ignored.)
423 * To insert a glyph into a toolbar, specify it as part of a
424 toolbar instantiator (typically set on the specifier
425 `default-toolbar'). See `default-toolbar' for more
426 information. (Note that it is standard practice to use a
427 symbol in place of the glyph list in the toolbar
428 instantiator; the symbol is evalled to get the glyph list.
429 This facilitates both creating the toolbar instantiator and
430 modifying individual glyphs in a toolbar later on. For
431 example, you can change the way that the Mail toolbar button
432 looks by modifying the value of the variable
433 `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
434 calling `(set-specifier-dirty-flag default-toolbar)'. (####
435 Unfortunately this doesn't quite work the way it should; the
436 change will appear in new frames, but not existing ones.
438 * To insert a glyph into a gutter, create or modify a gutter
439 instantiator (typically set on the specifier
440 `default-gutter'). Gutter instantiators consist of strings
441 or lists of strings, so to insert a glyph, create an extent
442 over the string, and use `set-extent-begin-glyph' or
443 `set-extent-end-glyph' to set a glyph to be displayed at the
444 corresponding edge of the extent, just like for glyphs in a
447 * To use a glyph as the icon for a frame, you do not actually
448 create a new glyph; rather, you change the specifications for
449 the existing glyph `frame-icon-glyph'. (Remember that,
450 because of the specifier nature of glyphs, you can set
451 different values for any particular buffer or frame.)
453 * To use a glyph as the mouse pointer, in general you do not
454 create a new glyph, but rather you change the specifications
455 of various existing glyphs, such as `text-pointer-glyph' for
456 the pointer used over text, `modeline-pointer-glyph' for the
457 pointer used over the modeline, etc. Do an apropos over
458 `*-pointer-glyph' to find all of them. (Note also that you
459 can temporarily set the mouse pointer to some specific shape
460 by using `set-frame-pointer', which takes an image instance,
461 as obtained from calling `glyph-image-instance' on a glyph of
462 type `pointer' - either one of the above-mentioned variables
463 or one you created yourself. (See below for what it means to
464 create a glyph of type `pointer'.) This pointer will last
465 only until the next mouse motion event is processed or
466 certain other things happen, such as creating or deleting a
467 window. (In fact, the above-mentioned pointer glyph variables
468 are implemented as part of the default handler for mouse
469 motion events. If you want to customize this behavior, take a
470 look at `mode-motion-hook', or `mouse-motion-handler' if you
471 really want to get low-level.)
473 * To use a glyph to control the shape of miscellaneous
474 redisplay effects such as the truncation and continuation
475 markers, set the appropriate existing glyph variables, as for
476 icons and pointers above. See `continuation-glyph',
477 `control-arrow-glyph', `hscroll-glyph',
478 `invisible-text-glyph', `octal-escape-glyph', and
479 `truncation-glyph'. See also `overlay-arrow-string', an odd
480 redisplay leftover which can be set to a glyph you created,
481 and will cause the glyph to be displayed on top of the text
482 position specified in the marker stored in
483 `overlay-arrow-position'.
485 * To use a glyph in a display table (i.e. to control the
486 appearance of any individual character), create the
487 appropriate character glyphs and then set a specification for
488 the specifier `current-display-table', which controls the
489 appearance of characters. You can also set an overriding
490 display table for use with text displayed in a particular
491 face; see `set-face-display-table' and `make-display-table'.
492 #### Note: Display tables do not currently support general
493 Mule characters. They will be overhauled at some point to
494 support this and to provide other features required under
497 * To use a glyph as the background pixmap of a face: Note that
498 the background pixmap of a face is actually an image
499 specifier - probably the only place in XEmacs where an image
500 specifier occurs outside of a glyph. Similarly to how the
501 glyph's image specifier works, you don't create your own
502 image specifier, but rather add specifications to the
503 existing one (using `set-face-background-pixmap'). Note that
504 the image instance that is generated in order to actually
505 display the background pixmap is of type `mono-pixmap',
506 meaning that it's a two-color image and the foreground and
507 background of the image get filled in with the corresponding
508 colors from the face.
510 It is extremely rare that you will ever have to specify a value for
511 TYPE, which should be one of `buffer' (used for glyphs in an
512 extent, the modeline, the toolbar, or elsewhere in a buffer),
513 `pointer' (used for the mouse-pointer), or `icon' (used for a
514 frame's icon), and defaults to `buffer'. The only cases where it
515 needs to be specified is when creating icon or pointer glyphs, and
516 in both cases the necessary glyphs have already been created at
517 startup and are accessed through the appropriate variables, e.g.
518 `text-pointer-glyph' (or in general, `*-pointer-glyph') and
519 `frame-icon-glyph'. *Note Glyph Types::.
521 - Function: make-glyph-internal &optional type
522 This function creates a new, uninitialized glyph of type TYPE.
524 - Function: make-pointer-glyph &optional spec-list
525 Return a new `pointer-glyph' object with the specification list
526 SPEC-LIST. This function is equivalent to calling `make-glyph'
527 with a TYPE of `pointer'.
529 It is extremely unlikely that you will ever need to create a
530 pointer glyph. Instead, you probably want to be calling
531 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
533 - Function: make-icon-glyph &optional spec-list
534 Return a new `pointer-glyph' object with the specification list
535 SPEC-LIST. This function is equivalent to calling `make-glyph'
536 with a TYPE of `icon'.
538 It is extremely unlikely that you will ever need to create a
539 pointer glyph. Instead, you probably want to be calling
540 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
543 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
548 Each glyph has a list of properties, which control all of the aspects of
549 the glyph's appearance. The following symbols have predefined meanings:
552 The image used to display the glyph.
555 Percent above baseline that glyph is to be displayed. Only for
556 glyphs displayed inside of a buffer.
559 Whether the glyph contributes to the height of the line it's on.
560 Only for glyphs displayed inside of a buffer.
563 Face of this glyph (_not_ a specifier).
565 - Function: set-glyph-property glyph property value &optional locale
567 This function changes a property of a GLYPH.
569 For built-in properties, the actual value of the property is a
570 specifier and you cannot change this; but you can change the
571 specifications within the specifier, and that is what this
572 function will do. For user-defined properties, you can use this
573 function to either change the actual value of the property or, if
574 this value is a specifier, change the specifications within it.
576 If PROPERTY is a built-in property, the specifications to be added
577 to this property can be supplied in many different ways:
579 * If VALUE is a simple instantiator (e.g. a string naming a
580 pixmap filename) or a list of instantiators, then the
581 instantiator(s) will be added as a specification of the
582 property for the given LOCALE (which defaults to `global' if
585 * If VALUE is a list of specifications (each of which is a cons
586 of a locale and a list of instantiators), then LOCALE must be
587 `nil' (it does not make sense to explicitly specify a locale
588 in this case), and specifications will be added as given.
590 * If VALUE is a specifier (as would be returned by
591 `glyph-property' if no LOCALE argument is given), then some
592 or all of the specifications in the specifier will be added
593 to the property. In this case, the function is really
594 equivalent to `copy-specifier' and LOCALE has the same
595 semantics (if it is a particular locale, the specification
596 for the locale will be copied; if a locale type,
597 specifications for all locales of that type will be copied;
598 if `nil' or `all', then all specifications will be copied).
600 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
601 `append', `remove-tag-set-prepend', `remove-tag-set-append',
602 `remove-locale', `remove-locale-type', or `remove-all'. See
603 `copy-specifier' and `add-spec-to-specifier' for a description of
604 what each of these means. Most of the time, you do not need to
605 worry about this argument; the default behavior usually is fine.
607 In general, it is OK to pass an instance object (e.g. as returned
608 by `glyph-property-instance') as an instantiator in place of an
609 actual instantiator. In such a case, the instantiator used to
610 create that instance object will be used (for example, if you set
611 a font-instance object as the value of the `font' property, then
612 the font name used to create that object will be used instead).
613 If some cases, however, doing this conversion does not make sense,
614 and this will be noted in the documentation for particular types
617 If PROPERTY is not a built-in property, then this function will
618 simply set its value if LOCALE is `nil'. However, if LOCALE is
619 given, then this function will attempt to add VALUE as the
620 instantiator for the given LOCALE, using `add-spec-to-specifier'.
621 If the value of the property is not a specifier, it will
622 automatically be converted into a `generic' specifier.
624 - Function: glyph-property glyph property &optional locale
625 This function returns GLYPH's value of the given PROPERTY.
627 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
628 be returned. For built-in properties, this will be a specifier
629 object of a type appropriate to the property (e.g. a font or color
630 specifier). For other properties, this could be anything.
632 If LOCALE is supplied, then instead of returning the actual value,
633 the specification(s) for the given locale or locale type will be
634 returned. This will only work if the actual value of PROPERTY is
635 a specifier (this will always be the case for built-in properties,
636 but may or may not apply to user-defined properties). If the
637 actual value of PROPERTY is not a specifier, this value will
638 simply be returned regardless of LOCALE.
640 The return value will be a list of instantiators (e.g. vectors
641 specifying pixmap data), or a list of specifications, each of
642 which is a cons of a locale and a list of instantiators.
643 Specifically, if LOCALE is a particular locale (a buffer, window,
644 frame, device, or `global'), a list of instantiators for that
645 locale will be returned. Otherwise, if LOCALE is a locale type
646 (one of the symbols `buffer', `window', `frame', or `device'), the
647 specifications for all locales of that type will be returned.
648 Finally, if LOCALE is `all', the specifications for all locales of
649 all types will be returned.
651 The specifications in a specifier determine what the value of
652 PROPERTY will be in a particular "domain" or set of circumstances,
653 which is typically a particular Emacs window along with the buffer
654 it contains and the frame and device it lies within. The value is
655 derived from the instantiator associated with the most specific
656 locale (in the order buffer, window, frame, device, and `global')
657 that matches the domain in question. In other words, given a
658 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
659 will first be searched for a specification whose locale is the
660 buffer contained within that window; then for a specification
661 whose locale is the window itself; then for a specification whose
662 locale is the frame that the window is contained within; etc. The
663 first instantiator that is valid for the domain (usually this
664 means that the instantiator is recognized by the device [i.e. the
665 X server or TTY device] that the domain is on). The function
666 `glyph-property-instance' actually does all this, and is used to
667 determine how to display the glyph.
669 - Function: glyph-property-instance glyph property &optional domain
671 This function returns the instance of GLYPH's PROPERTY in the
674 Under most circumstances, DOMAIN will be a particular window, and
675 the returned instance describes how the specified property
676 actually is displayed for that window and the particular buffer in
677 it. Note that this may not be the same as how the property
678 appears when the buffer is displayed in a different window or
679 frame, or how the property appears in the same window if you
680 switch to another buffer in that window; and in those cases, the
681 returned instance would be different.
683 The returned instance is an image-instance object, and you can
684 query it using the appropriate image instance functions. For
685 example, you could use `image-instance-depth' to find out the
686 depth (number of color planes) of a pixmap displayed in a
687 particular window. The results might be different from the
688 results you would get for another window (perhaps the user
689 specified a different image for the frame that window is on; or
690 perhaps the same image was specified but the window is on a
691 different X server, and that X server has different color
692 capabilities from this one).
694 DOMAIN defaults to the selected window if omitted.
696 DOMAIN can be a frame or device, instead of a window. The value
697 returned for such a domain is used in special circumstances when a
698 more specific domain does not apply; for example, a frame value
699 might be used for coloring a toolbar, which is conceptually
700 attached to a frame rather than a particular window. The value is
701 also useful in determining what the value would be for a
702 particular window within the frame or device, if it is not
703 overridden by a more specific specification.
705 If PROPERTY does not name a built-in property, its value will
706 simply be returned unless it is a specifier object, in which case
707 it will be instanced using `specifier-instance'.
709 Optional arguments DEFAULT and NO-FALLBACK are the same as in
710 `specifier-instance'. *Note Specifiers::.
712 - Function: remove-glyph-property glyph property &optional locale
714 This function removes a property from a glyph. For built-in
715 properties, this is analogous to `remove-specifier'. *Note
716 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
717 TAG-SET, and EXACT-P arguments.
720 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
722 Glyph Convenience Functions
723 ---------------------------
725 The following functions are provided for working with specific
726 properties of a glyph. Note that these are exactly like calling the
727 general functions described above and passing in the appropriate value
730 Remember that if you want to determine the "value" of a specific
731 glyph property, you probably want to use the `*-instance' functions.
732 For example, to determine whether a glyph contributes to its line
733 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
734 latter will return a boolean specifier or a list of specifications, and
735 you probably aren't concerned with these.)
737 - Function: glyph-image glyph &optional locale
738 This function is equivalent to calling `glyph-property' with a
739 property of `image'. The return value will be an image specifier
740 if LOCALE is `nil' or omitted; otherwise, it will be a
741 specification or list of specifications.
743 - Function: set-glyph-image glyph spec &optional locale tag-set
745 This function is equivalent to calling `set-glyph-property' with a
748 - Function: glyph-image-instance glyph &optional domain default
750 This function returns the instance of GLYPH's image in the given
751 DOMAIN, and is equivalent to calling `glyph-property-instance'
752 with a property of `image'. The return value will be an image
755 Normally DOMAIN will be a window or `nil' (meaning the selected
756 window), and an instance object describing how the image appears
757 in that particular window and buffer will be returned.
759 - Function: glyph-contrib-p glyph &optional locale
760 This function is equivalent to calling `glyph-property' with a
761 property of `contrib-p'. The return value will be a boolean
762 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
763 specification or list of specifications.
765 - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
767 This function is equivalent to calling `set-glyph-property' with a
768 property of `contrib-p'.
770 - Function: glyph-contrib-p-instance glyph &optional domain default
772 This function returns whether the glyph contributes to its line
773 height in the given DOMAIN, and is equivalent to calling
774 `glyph-property-instance' with a property of `contrib-p'. The
775 return value will be either `nil' or `t'. (Normally DOMAIN will be
776 a window or `nil', meaning the selected window.)
778 - Function: glyph-baseline glyph &optional locale
779 This function is equivalent to calling `glyph-property' with a
780 property of `baseline'. The return value will be a specifier if
781 LOCALE is `nil' or omitted; otherwise, it will be a specification
782 or list of specifications.
784 - Function: set-glyph-baseline glyph spec &optional locale tag-set
786 This function is equivalent to calling `set-glyph-property' with a
787 property of `baseline'.
789 - Function: glyph-baseline-instance glyph &optional domain default
791 This function returns the instance of GLYPH's baseline value in
792 the given DOMAIN, and is equivalent to calling
793 `glyph-property-instance' with a property of `baseline'. The
794 return value will be an integer or `nil'.
796 Normally DOMAIN will be a window or `nil' (meaning the selected
797 window), and an instance object describing the baseline value
798 appears in that particular window and buffer will be returned.
800 - Function: glyph-face glyph
801 This function returns the face of GLYPH. (Remember, this is not a
802 specifier, but a simple property.)
804 - Function: set-glyph-face glyph face
805 This function changes the face of GLYPH to FACE.
808 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
813 - Function: glyph-width glyph &optional window
814 This function returns the width of GLYPH on WINDOW. This may not
815 be exact as it does not take into account all of the context that
818 - Function: glyph-ascent glyph &optional window
819 This function returns the ascent value of GLYPH on WINDOW. This
820 may not be exact as it does not take into account all of the
821 context that redisplay will.
823 - Function: glyph-descent glyph &optional window
824 This function returns the descent value of GLYPH on WINDOW. This
825 may not be exact as it does not take into account all of the
826 context that redisplay will.
828 - Function: glyph-height glyph &optional window
829 This function returns the height of GLYPH on WINDOW. (This is
830 equivalent to the sum of the ascent and descent values.) This may
831 not be exact as it does not take into account all of the context
835 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
842 * Image Specifiers:: Specifying how an image will appear.
843 * Image Instantiator Conversion::
844 Conversion is applied to image instantiators
845 at the time they are added to an
846 image specifier or at the time they
847 are passed to `make-image-instance'.
848 * Image Instances:: What an image specifier gets instanced as.
851 File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
856 An image specifier is used to describe the actual image of a glyph. It
857 works like other specifiers (*note Specifiers::), in that it contains a
858 number of specifications describing how the image should appear in a
859 variety of circumstances. These specifications are called "image
860 instantiators". When XEmacs wants to display the image, it instantiates
861 the image into an "image instance". Image instances are their own
862 primitive object type (similar to font instances and color instances),
863 describing how the image appears in a particular domain. (On the other
864 hand, image instantiators, which are just descriptions of how the image
865 should appear, are represented using strings or vectors.)
867 - Function: image-specifier-p object
868 This function returns non-`nil' if OBJECT is an image specifier.
869 Usually, an image specifier results from calling `glyph-image' on
872 - Function: make-image-specifier spec-list
873 This function creates a new image specifier object and initializes
874 it according to SPEC-LIST. *Note Specifiers::.
876 Note that, in practice, you rarely, if ever, need to actually
877 create an image specifier! (This function exists mainly for
878 completeness.) Pretty much the only use for image specifiers is to
879 control how glyphs are displayed, and the image specifier
880 associated with a glyph (the `image' property of a glyph) is
881 created automatically when a glyph is created and need not (and
882 cannot, for that matter) ever be changed (*note Glyphs::). In
883 fact, the design decision to create a separate image specifier
884 type, rather than make glyphs themselves be specifiers, is
885 debatable--the other properties of glyphs are rarely used and could
886 conceivably have been incorporated into the glyph's instantiator.
887 The rarely used glyph types (buffer, pointer, icon) could also
888 have been incorporated into the instantiator.
890 Image instantiators come in many formats: `xbm', `xpm', `gif',
891 `jpeg', etc. This describes the format of the data describing the
892 image. The resulting image instances also come in many
893 types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
894 refers to the behavior of the image and the sorts of places it can
895 appear. (For example, a color-pixmap image has fixed colors specified
896 for it, while a mono-pixmap image comes in two unspecified shades
897 "foreground" and "background" that are determined from the face of the
898 glyph or surrounding text; a text image appears as a string of text and
899 has an unspecified foreground, background, and font; a pointer image
900 behaves like a mono-pixmap image but can only be used as a mouse
901 pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
902 is important to keep the distinction between image instantiator format
903 and image instance type in mind. Typically, a given image instantiator
904 format can result in many different image instance types (for example,
905 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
906 whereas `cursor-font' can be instanced only as `pointer'), and a
907 particular image instance type can be generated by many different image
908 instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
909 `gif', `jpeg', etc.).
911 *Note Image Instances::, for a more detailed discussion of image
914 An image instantiator should be a string or a vector of the form
916 `[FORMAT :KEYWORD VALUE ...]'
918 i.e. a format symbol followed by zero or more alternating
919 keyword-value pairs. The "format" field should be a symbol, one of
922 Don't display anything; no keywords are valid for this. Can only
923 be instanced as `nothing'.
926 Display this image as a text string. Can only be instanced as
927 `text', although support for instancing as `mono-pixmap' should be
931 Display this image as a text string with replaceable fields,
932 similar to a modeline format string; not currently implemented.
935 An X bitmap; only if X support was compiled into this XEmacs. Can
936 be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
939 An XPM pixmap; only if XPM support was compiled into this XEmacs.
940 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
941 XPM is an add-on library for X that was designed to rectify the
942 shortcomings of the XBM format. Most implementations of X include
943 the XPM library as a standard part. If your vendor does not, it
944 is highly recommended that you download it and install it. You
945 can get it from the standard XEmacs FTP site, among other places.
948 An X-Face bitmap, used to encode people's faces in e-mail messages;
949 only if X-Face support was compiled into this XEmacs. Can be
950 instanced as `mono-pixmap', `color-pixmap', or `pointer'.
953 A GIF87 or GIF89 image; only if GIF support was compiled into this
954 XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
955 includes GIF decoding functions as a standard part of it, so if
956 you have X support, you will normally have GIF support, unless you
957 explicitly disable it at configure time.
960 A JPEG-format image; only if JPEG support was compiled into this
961 XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
962 libraries present on your system when XEmacs is built, XEmacs will
963 automatically detect this and use them, unless you explicitly
964 disable it at configure time.
967 A PNG/GIF24 image; only if PNG support was compiled into this
968 XEmacs. Can be instanced as `color-pixmap'.
971 A TIFF-format image; only if TIFF support was compiled into this
975 One of the standard cursor-font names, such as `watch' or
976 `right_ptr' under X. Under X, this is, more specifically, any of
977 the standard cursor names from appendix B of the Xlib manual [also
978 known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
979 other window systems, the valid names will be specific to the type
980 of window system. Can only be instanced as `pointer'.
983 A glyph from a font; i.e. the name of a font, and glyph index into
984 it of the form `FONT fontname index [[mask-font] mask-index]'.
985 Only if X support was compiled into this XEmacs. Currently can
986 only be instanced as `pointer', although this should probably be
990 An MS Windows pointer resource. Specifies a resource to retrieve
991 directly from the system (an OEM resource) or from a file,
992 particularly an executable file. If the resource is to be
993 retrieved from a file, use :file and optionally :resource-id.
994 Otherwise use :resource-id. Always specify :resource-type to
995 specify the type (cursor, bitmap or icon) of the resource.
996 Possible values for :resource-id are listed below. Can be
997 instanced as `pointer' or `color-pixmap'.
1000 An embedded windowing system window. Can only be instanced as
1004 A button widget; either a push button, radio button or toggle
1005 button. Can only be instanced as `widget'.
1008 A drop list of selectable items in a widget, for editing text.
1009 Can only be instanced as `widget'.
1012 A text editing widget. Can only be instanced as `widget'.
1015 A static, text-only, widget; for displaying text. Can only be
1016 instanced as `widget'.
1019 A widget for controlling the positioning of children underneath it.
1020 Through the use of nested layouts, a widget hierarchy can be
1021 created which can have the appearance of any standard dialog box
1022 or similar arrangement; all of this is counted as one "glyph" and
1023 could appear in many of the places that expect a single glyph.
1024 Can only be instanced as `widget'.
1027 The native version of a layout widget. Can only be instanced as
1031 A sliding widget, for showing progress. Can only be instanced as
1035 A tab widget; a series of user selectable tabs. Can only be
1036 instanced as `widget'.
1039 A folding widget. Can only be instanced as `widget'.
1042 A scrollbar widget. Can only be instanced as `widget'.
1045 XEmacs tries to guess what format the data is in. If X support
1046 exists, the data string will be checked to see if it names a
1047 filename. If so, and this filename contains XBM or XPM data, the
1048 appropriate sort of pixmap or pointer will be created. [This
1049 includes picking up any specified hotspot or associated mask
1050 file.] Otherwise, if `pointer' is one of the allowable
1051 image-instance types and the string names a valid cursor-font
1052 name, the image will be created as a pointer. Otherwise, the
1053 image will be displayed as text. If no X support exists, the
1054 image will always be displayed as text.
1057 Inherit from the background-pixmap property of a face. Can only be
1058 instanced as `mono-pixmap'.
1060 The valid keywords are:
1063 Inline data. For most formats above, this should be a string. For
1064 XBM images, this should be a list of three elements: width,
1065 height, and a string of bit data. This keyword is not valid for
1066 instantiator format `nothing'.
1069 Data is contained in a file. The value is the name of this file.
1070 If both `:data' and `:file' are specified, the image is created
1071 from what is specified in `:data' and the string in `:file'
1072 becomes the value of the `image-instance-file-name' function when
1073 applied to the resulting image-instance. This keyword is not
1074 valid for instantiator formats `nothing', `string',
1075 `formatted-string', `cursor-font', `font', and `autodetect'.
1079 For `xbm', `xface', `cursor-font', and `font'. These keywords
1080 allow you to explicitly specify foreground and background colors.
1081 The argument should be anything acceptable to
1082 `make-color-instance'. This will cause what would be a
1083 `mono-pixmap' to instead be colorized as a two-color color-pixmap,
1084 and specifies the foreground and/or background colors for a pointer
1085 instead of black and white.
1088 For `xbm' and `xface'. This specifies a mask to be used with the
1089 bitmap. The format is a list of width, height, and bits, like for
1093 For `xbm' and `xface'. This specifies a file containing the mask
1094 data. If neither a mask file nor inline mask data is given for an
1095 XBM image, and the XBM image comes from a file, XEmacs will look
1096 for a mask file with the same name as the image file but with
1097 `Mask' or `msk' appended. For example, if you specify the XBM file
1098 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
1099 associated mask file `left_ptrmsk' will automatically be picked up.
1103 For `xbm' and `xface'. These keywords specify a hotspot if the
1104 image is instantiated as a `pointer'. Note that if the XBM image
1105 file specifies a hotspot, it will automatically be picked up if no
1106 explicit hotspot is given.
1109 Only for `xpm'. This specifies an alist that maps strings that
1110 specify symbolic color names to the actual color to be used for
1111 that symbolic color (in the form of a string or a color-specifier
1112 object). If this is not specified, the contents of
1113 `xpm-color-symbols' are used to generate the alist.
1116 Only for `mswindows-resource'. This must be either an integer
1117 (which directly specifies a resource number) or a string. Valid
1122 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
1123 "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
1124 "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
1125 "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
1126 "check", "checkboxes", and "btncorners".
1130 "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
1131 "sizewe", "sizens", "sizeall", and "no".
1135 "sample", "hand", "ques", "bang", "note", and "winlogo".
1138 Only for `mswindows-resource'. This must be a symbol, either
1139 `cursor', `icon', or `bitmap', specifying the type of resource to
1143 Only for `inherit'. This specifies the face to inherit from. For
1144 widgets this also specifies the face to use for display. It
1145 defaults to gui-element-face.
1147 Keywords accepted as menu item specs are also accepted by widgets.
1148 These are `:selected', `:active', `:suffix', `:keys', `:style',
1149 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
1150 `:label' and `:callback'.
1152 If instead of a vector, the instantiator is a string, it will be
1153 converted into a vector by looking it up according to the specs in the
1154 `console-type-image-conversion-list' for the console type of the domain
1155 (usually a window; sometimes a frame or device) over which the image is
1158 If the instantiator specifies data from a file, the data will be
1159 read in at the time that the instantiator is added to the image
1160 specifier (which may be well before the image is actually displayed),
1161 and the instantiator will be converted into one of the inline-data
1162 forms, with the filename retained using a `:file' keyword. This
1163 implies that the file must exist when the instantiator is added to the
1164 image, but does not need to exist at any other time (e.g. it may safely
1165 be a temporary file).
1167 - Function: valid-image-instantiator-format-p format &optional locale
1168 This function returns non-`nil' if FORMAT is a valid image
1169 instantiator format.
1171 If LOCALE is non-`nil' then the format is checked in that locale.
1172 If LOCALE is `nil' the current console is used.
1174 Note that the return value for many formats listed above depends on
1175 whether XEmacs was compiled with support for that format.
1177 - Function: image-instantiator-format-list
1178 This function return a list of valid image-instantiator formats.
1180 - Variable: xpm-color-symbols
1181 This variable holds definitions of logical color-names used when
1182 reading XPM files. Elements of this list should be of the form
1183 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
1184 string, which is the name of the color to define; the
1185 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
1186 string to be passed to `make-color-instance' (*note Colors::). If
1187 a loaded XPM file references a symbolic color called COLOR-NAME,
1188 it will display as the computed color instead.
1190 The default value of this variable defines the logical color names
1191 `"foreground"' and `"background"' to be the colors of the
1194 - Variable: x-bitmap-file-path
1195 A list of the directories in which X bitmap files may be found.
1196 If `nil', this is initialized from the `"*bitmapFilePath"'
1197 resource. This is used by the `make-image-instance' function
1198 (however, note that if the environment variable `XBMLANGPATH' is
1199 set, it is consulted first).
1202 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
1204 Image Instantiator Conversion
1205 -----------------------------
1207 - Function: set-console-type-image-conversion-list console-type list
1208 This function sets the image-conversion-list for consoles of the
1209 given CONSOLE-TYPE. The image-conversion-list specifies how image
1210 instantiators that are strings should be interpreted. Each
1211 element of the list should be a list of two elements (a regular
1212 expression string and a vector) or a list of three elements (the
1213 preceding two plus an integer index into the vector). The string
1214 is converted to the vector associated with the first matching
1215 regular expression. If a vector index is specified, the string
1216 itself is substituted into that position in the vector.
1218 Note: The conversion above is applied when the image instantiator
1219 is added to an image specifier, not when the specifier is actually
1220 instantiated. Therefore, changing the image-conversion-list only
1221 affects newly-added instantiators. Existing instantiators in
1222 glyphs and image specifiers will not be affected.
1224 - Function: console-type-image-conversion-list console-type
1225 This function returns the image-conversion-list for consoles of
1226 the given CONSOLE-TYPE.
1229 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
1234 Image-instance objects encapsulate the way a particular image (pixmap,
1235 etc.) is displayed on a particular device.
1237 In most circumstances, you do not need to directly create image
1238 instances; use a glyph instead. However, it may occasionally be useful
1239 to explicitly create image instances, if you want more control over the
1240 instantiation process.
1242 - Function: image-instance-p object
1243 This function returns non-`nil' if OBJECT is an image instance.
1247 * Image Instance Types:: Each image instances has a particular type.
1248 * Image Instance Functions:: Functions for working with image instances.
1251 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
1253 Image Instance Types
1254 ....................
1256 Image instances come in a number of different types. The type of an
1257 image instance specifies the nature of the image: Whether it is a text
1258 string, a mono pixmap, a color pixmap, etc.
1260 The valid image instance types are
1263 Nothing is displayed.
1266 Displayed as text. The foreground and background colors and the
1267 font of the text are specified independent of the pixmap.
1268 Typically these attributes will come from the face of the
1269 surrounding text, unless a face is specified for the glyph in
1270 which the image appears.
1273 Displayed as a mono pixmap (a pixmap with only two colors where the
1274 foreground and background can be specified independent of the
1275 pixmap; typically the pixmap assumes the foreground and background
1276 colors of the text around it, unless a face is specified for the
1277 glyph in which the image appears).
1280 Displayed as a color pixmap.
1283 Used as the mouse pointer for a window.
1286 A child window that is treated as an image. This allows (e.g.)
1287 another program to be responsible for drawing into the window.
1288 Not currently implemented.
1290 - Function: valid-image-instance-type-p type
1291 This function returns non-`nil' if TYPE is a valid image instance
1294 - Function: image-instance-type-list
1295 This function returns a list of the valid image instance types.
1297 - Function: image-instance-type image-instance
1298 This function returns the type of the given image instance. The
1299 return value will be one of `nothing', `text', `mono-pixmap',
1300 `color-pixmap', `pointer', or `subwindow'.
1302 - Function: text-image-instance-p object
1303 This function returns non-`nil' if OBJECT is an image instance of
1306 - Function: mono-pixmap-image-instance-p object
1307 This function returns non-`nil' if OBJECT is an image instance of
1310 - Function: color-pixmap-image-instance-p object
1311 This function returns non-`nil' if OBJECT is an image instance of
1312 type `color-pixmap'.
1314 - Function: pointer-image-instance-p object
1315 This function returns non-`nil' if OBJECT is an image instance of
1318 - Function: subwindow-image-instance-p object
1319 This function returns non-`nil' if OBJECT is an image instance of
1322 - Function: nothing-image-instance-p object
1323 This function returns non-`nil' if OBJECT is an image instance of
1326 - Function: widget-image-instance-p object
1327 Return `t' if OBJECT is an image instance of type `widget'.
1330 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
1332 Image Instance Functions
1333 ........................
1335 - Function: make-image-instance data &optional domain dest-types
1337 This function creates a new image-instance object.
1339 DATA is an image instantiator, which describes the image (*note
1340 Image Specifiers::).
1342 DEST-TYPES should be a list of allowed image instance types that
1343 can be generated. The DEST-TYPES list is unordered. If multiple
1344 destination types are possible for a given instantiator, the "most
1345 natural" type for the instantiator's format is chosen. (For XBM,
1346 the most natural types are `mono-pixmap', followed by
1347 `color-pixmap', followed by `pointer'. For the other normal image
1348 formats, the most natural types are `color-pixmap', followed by
1349 `mono-pixmap', followed by `pointer'. For the string and
1350 formatted-string formats, the most natural types are `text',
1351 followed by `mono-pixmap' (not currently implemented), followed by
1352 `color-pixmap' (not currently implemented). For MS Windows
1353 resources, the most natural type for pointer resources is
1354 `pointer', and for the others it's `color-pixmap'. The other
1355 formats can only be instantiated as one type. (If you want to
1356 control more specifically the order of the types into which an
1357 image is instantiated, just call `make-image-instance' repeatedly
1358 until it succeeds, passing less and less preferred destination
1361 If DEST-TYPES is omitted, all possible types are allowed.
1363 DOMAIN specifies the domain to which the image instance will be
1364 attached. This domain is termed the "governing domain". The type
1365 of the governing domain depends on the image instantiator format.
1366 (Although, more correctly, it should probably depend on the image
1367 instance type.) For example, pixmap image instances are specific
1368 to a device, but widget image instances are specific to a
1369 particular XEmacs window because in order to display such a widget
1370 when two windows onto the same buffer want to display the widget,
1371 two separate underlying widgets must be created. (That's because a
1372 widget is actually a child window-system window, and all
1373 window-system windows have a unique existence on the screen.) This
1374 means that the governing domain for a pixmap image instance will
1375 be some device (most likely, the only existing device), whereas
1376 the governing domain for a widget image instance will be some
1379 If you specify an overly general DOMAIN (e.g. a frame when a
1380 window was wanted), an error is signaled. If you specify an overly
1381 specific DOMAIN (e.g. a window when a device was wanted), the
1382 corresponding general domain is fetched and used instead. For
1383 `make-image-instance', it makes no difference whether you specify
1384 an overly specific domain or the properly general domain derived
1385 from it. However, it does matter when creating an image instance
1386 by instantiating a specifier or glyph (e.g. with
1387 `glyph-image-instance'), because the more specific domain causes
1388 spec lookup to start there and proceed to more general domains. (It
1389 would also matter when creating an image instance with an
1390 instantiator format of `inherit', but we currently disallow this.
1391 #### We should fix this.) n If omitted, DOMAIN defaults to the
1394 NOERROR controls what happens when the image cannot be generated.
1395 If `nil', an error message is generated. If `t', no messages are
1396 generated and this function returns `nil'. If anything else, a
1397 warning message is generated and this function returns `nil'.
1399 - Function: colorize-image-instance image-instance foreground
1401 This function makes the image instance be displayed in the given
1402 colors. Image instances come in two varieties: bitmaps, which are
1403 1 bit deep which are rendered in the prevailing foreground and
1404 background colors; and pixmaps, which are of arbitrary depth
1405 (including 1) and which have the colors explicitly specified.
1406 This function converts a bitmap to a pixmap. If the image
1407 instance was a pixmap already, nothing is done (and `nil' is
1408 returned). Otherwise `t' is returned.
1410 - Function: image-instance-name image-instance
1411 This function returns the name of the given image instance.
1413 - Function: image-instance-domain image-instance
1414 Return the governing domain of the given IMAGE-INSTANCE. The
1415 governing domain of an image instance is the domain that the image
1416 instance is specific to. It is _NOT_ necessarily the domain that
1417 was given to the call to `specifier-instance' that resulted in the
1418 creation of this image instance. See `make-image-instance' for
1419 more information on governing domains.
1421 - Function: image-instance-string image-instance
1422 This function returns the string of the given image instance.
1423 This will only be non-`nil' for text image instances.
1425 - Function: image-instance-file-name image-instance
1426 This function returns the file name from which IMAGE-INSTANCE was
1429 - Function: image-instance-mask-file-name image-instance
1430 This function returns the file name from which IMAGE-INSTANCE's
1431 mask was read, if known.
1433 - Function: image-instance-depth image-instance
1434 This function returns the depth of the image instance. This is 0
1435 for a mono pixmap, or a positive integer for a color pixmap.
1437 - Function: image-instance-height image-instance
1438 This function returns the height of the image instance, in pixels.
1440 - Function: image-instance-width image-instance
1441 This function returns the width of the image instance, in pixels.
1443 - Function: image-instance-hotspot-x image-instance
1444 This function returns the X coordinate of the image instance's
1445 hotspot, if known. This is a point relative to the origin of the
1446 pixmap. When an image is used as a mouse pointer, the hotspot is
1447 the point on the image that sits over the location that the
1448 pointer points to. This is, for example, the tip of the arrow or
1449 the center of the crosshairs.
1451 This will always be `nil' for a non-pointer image instance.
1453 - Function: image-instance-hotspot-y image-instance
1454 This function returns the Y coordinate of the image instance's
1457 - Function: image-instance-foreground image-instance
1458 This function returns the foreground color of IMAGE-INSTANCE, if
1459 applicable. This will be a color instance or `nil'. (It will only
1460 be non-`nil' for colorized mono pixmaps and for pointers.)
1462 - Function: image-instance-background image-instance
1463 This function returns the background color of IMAGE-INSTANCE, if
1464 applicable. This will be a color instance or `nil'. (It will only
1465 be non-`nil' for colorized mono pixmaps and for pointers.)
1468 File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
1473 Each glyph has a particular type, which controls how the glyph's image
1474 is generated. Each glyph type has a corresponding list of allowable
1475 image instance types that can be generated. When you call
1476 `glyph-image-instance' to retrieve the image instance of a glyph,
1477 XEmacs does the equivalent of calling `make-image-instance' and passing
1478 in DEST-TYPES the list of allowable image instance types for the
1481 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
1482 extent, in the modeline, and in the toolbar. Their image can be
1483 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
1486 * `pointer' glyphs can be used to specify the mouse pointer. Their
1487 image can be instantiated as `pointer'.
1489 * `icon' glyphs can be used to specify the icon used when a frame is
1490 iconified. Their image can be instantiated as `mono-pixmap' and
1493 - Function: glyph-type glyph
1494 This function returns the type of the given glyph. The return
1495 value will be a symbol, one of `buffer', `pointer', or `icon'.
1497 - Function: valid-glyph-type-p glyph-type
1498 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
1500 - Function: glyph-type-list
1501 This function returns a list of valid glyph types.
1503 - Function: buffer-glyph-p object
1504 This function returns non-`nil' if OBJECT is a glyph of type
1507 - Function: icon-glyph-p object
1508 This function returns non-`nil' if OBJECT is a glyph of type
1511 - Function: pointer-glyph-p object
1512 This function returns non-`nil' if OBJECT is a glyph of type
1516 File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
1521 The shape of the mouse pointer when over a particular section of a frame
1522 is controlled using various glyph variables. Since the image of a glyph
1523 is a specifier, it can be controlled on a per-buffer, per-frame,
1524 per-window, or per-device basis.
1526 You should use `set-glyph-image' to set the following variables,
1529 - Glyph: text-pointer-glyph
1530 This variable specifies the shape of the mouse pointer when over
1533 - Glyph: nontext-pointer-glyph
1534 This variable specifies the shape of the mouse pointer when over a
1535 buffer, but not over text. If unspecified in a particular domain,
1536 `text-pointer-glyph' is used.
1538 - Glyph: modeline-pointer-glyph
1539 This variable specifies the shape of the mouse pointer when over
1540 the modeline. If unspecified in a particular domain,
1541 `nontext-pointer-glyph' is used.
1543 - Glyph: selection-pointer-glyph
1544 This variable specifies the shape of the mouse pointer when over a
1545 selectable text region. If unspecified in a particular domain,
1546 `text-pointer-glyph' is used.
1548 - Glyph: gc-pointer-glyph
1549 This variable specifies the shape of the mouse pointer when a
1550 garbage collection is in progress. If the selected window is on a
1551 window system and this glyph specifies a value (i.e. a pointer
1552 image instance) in the domain of the selected window, the pointer
1553 will be changed as specified during garbage collection.
1554 Otherwise, a message will be printed in the echo area, as
1555 controlled by `gc-message'.
1557 - Glyph: busy-pointer-glyph
1558 This variable specifies the shape of the mouse pointer when XEmacs
1559 is busy. If unspecified in a particular domain, the pointer is
1560 not changed when XEmacs is busy.
1562 - Glyph: menubar-pointer-glyph
1563 This variable specifies the shape of the mouse pointer when over
1564 the menubar. If unspecified in a particular domain, the
1565 window-system-provided default pointer is used.
1567 - Glyph: scrollbar-pointer-glyph
1568 This variable specifies the shape of the mouse pointer when over a
1569 scrollbar. If unspecified in a particular domain, the
1570 window-system-provided default pointer is used.
1572 - Glyph: toolbar-pointer-glyph
1573 This variable specifies the shape of the mouse pointer when over a
1574 toolbar. If unspecified in a particular domain,
1575 `nontext-pointer-glyph' is used.
1577 Internally, these variables are implemented in
1578 `default-mouse-motion-handler', and thus only take effect when the
1579 mouse moves. That function calls `set-frame-pointer', which sets the
1580 current mouse pointer for a frame.
1582 - Function: set-frame-pointer frame image-instance
1583 This function sets the mouse pointer of FRAME to the given pointer
1584 image instance. You should not call this function directly. (If
1585 you do, the pointer will change again the next time the mouse
1589 File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
1594 - Glyph: truncation-glyph
1595 This variable specifies what is displayed at the end of truncated
1598 - Glyph: continuation-glyph
1599 This variable specifies what is displayed at the end of wrapped
1602 - Glyph: octal-escape-glyph
1603 This variable specifies what to prefix character codes displayed
1606 - Glyph: hscroll-glyph
1607 This variable specifies what to display at the beginning of
1608 horizontally scrolled lines.
1610 - Glyph: invisible-text-glyph
1611 This variable specifies what to use to indicate the presence of
1612 invisible text. This is the glyph that is displayed when an
1613 ellipsis is called for, according to `selective-display-ellipses'
1614 or `buffer-invisibility-spec'). Normally this is three dots
1617 - Glyph: control-arrow-glyph
1618 This variable specifies what to use as an arrow for control
1622 File: lispref.info, Node: Subwindows, Next: Glyph Examples, Prev: Redisplay Glyphs, Up: Glyphs
1627 Subwindows are not currently implemented.
1629 - Function: subwindowp object
1630 This function returns non-`nil' if OBJECT is a subwindow.
1633 File: lispref.info, Node: Glyph Examples, Prev: Subwindows, Up: Glyphs
1638 For many applications, displaying graphics is a simple process: you
1639 create a glyph, and then you insert it into a buffer.
1641 The easiest way to create a glyph is to use a file that contains a
1642 graphical image, such as a JPEG, TIFF, or PNG file:
1644 ;; Create a glyph from a JPEG file:
1645 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1647 ;; Create a glyph from a XPM file:
1648 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
1650 ;; Create a glyph from a PNG file:
1651 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
1653 ;; Create a glyph from a TIFF file:
1654 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
1656 The parameters passed to `make-glyph' are called "Image Specifiers",
1657 and can handle more image types than those shown above. You can also
1658 put the raw image data into a string (e.g., if you put the contents of
1659 a JPEG file into a string), and use that to create a glyph. *Note
1660 Image Specifiers::, for more information.
1662 *Caution*: In order for XEmacs to read a particular graphics file
1663 format, support for that format must have been compiled into
1664 XEmacs. It's possible, although somewhat unlikely, for XEmacs to
1665 have been compiled without support for any of the various graphics
1666 file formats. To see what graphics formats your particular
1667 version of XEmacs supports, use `M-x describe-installation'.
1669 To programmatically query whether or not a particular file format
1670 is supported, you can use the `featurep' function, with one of:
1671 `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'. For an
1672 up-to-date list, *Note Image Specifiers::. Example:
1674 ;; Returns `t' if TIFF is supported:
1679 ;; Returns a list of `t' or `nil', depending on whether or not the
1680 ;; corresponding feature is supported:
1681 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
1682 '(gif tiff jpeg xpm png))
1685 Once you have a glyph, you can then insert it into a buffer.
1688 ;; Use this function to insert a glyph at the left edge of point in the
1689 ;; current buffer. Any existing glyph at this location is replaced.
1690 (defun insert-glyph (gl)
1691 "Insert a glyph at the left edge of point."
1692 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
1693 ;; to (hopefully) not conflict with any
1694 ;; other properties. Change it if
1697 ;; First, check to see if one of our extents already exists at
1698 ;; point. For ease-of-programming, we are creating and using our
1699 ;; own extents (multiple extents are allowed to exist/overlap at the
1700 ;; same point, and it's quite possible for other applications to
1701 ;; embed extents in the current buffer without your knowledge).
1702 ;; Basically, if an extent, with the property stored in "prop",
1703 ;; exists at point, we assume that it is one of ours, and we re-use
1704 ;; it (this is why it is important for the property stored in "prop"
1705 ;; to be unique, and only used by us).
1706 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
1708 ;; If an extent does not already exist, create a zero-length
1709 ;; extent, and give it our special property.
1710 (setq extent (make-extent (point) (point) (current-buffer)))
1711 (set-extent-property extent prop t)
1713 ;; Display the glyph by storing it as the extent's "begin-glyph".
1714 (set-extent-property extent 'begin-glyph gl)
1717 ;; You can then use this function like:
1718 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1719 ;; This will insert the glyph at point.
1721 ;; Here's an example of how to insert two glyphs side-by-side, at point
1722 ;; (using the above code):
1724 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
1725 ;; Create a new extent at point. We can't simply call "insert-glyph",
1726 ;; as "insert-glyph" will simply replace the first glyph with the
1728 (setq extent (make-extent (point) (point) (current-buffer)))
1729 ;; Here, we're only setting the 'myimage property in case we need
1730 ;; to later identify/locate/reuse this particular extent.
1731 (set-extent-property extent 'myimage t)
1732 (set-extent-property extent 'begin-glyph
1733 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
1736 Here are the gory details:
1738 * Glyphs are displayed by attaching them to extents (see *Note
1739 Extents::), either to the beginning or the end of extents.
1741 Note that extents can be used for many things, and not just for
1742 displaying images (although, in the above example, we are creating
1743 our own extent for the sole purpose of displaying an image).
1744 Also, note that multiple extents are allowed to exist at the same
1745 position, and they can overlap.
1747 * Glyphs are often displayed inside the text area (alongside text).
1748 This is the default.
1750 Although glyphs can also be displayed in the margins, how to do
1751 this will not be described here. For more information on this, see
1752 *Note Annotation Basics:: (look for information on "layout types")
1753 and *Note Extent Properties:: (look for `begin-glyph-layout' and
1754 `end-glyph-layout').
1756 * The easiest way to insert a glyph into text is to create a
1757 zero-length extent at the point where you want the glyph to appear.
1759 Note that zero-length extents are attached to the character to the
1760 right of the extent; deleting this character will also delete the
1763 * It's often a good idea to assign a unique property to the
1764 newly-created extent, in case you later want to locate it, and
1765 replace any existing glyph with a different one (or just delete
1766 the existing one). In the above example, we are using "myimage"
1767 as our (hopefully) unique property name.
1769 If you need to locate all of the extents, you'll have to use
1770 functions like `extent-list' or `next-extent', or provide
1771 additional parameters to the `extent-at' function. Assigning a
1772 unique property to the extent makes it easy to locate your
1773 extents; for example, `extent-list' can return only those extents
1774 with a particular property. *Note Finding Extents::, and *Note
1775 Mapping Over Extents::, for more information.
1777 * Glyphs are displayed by assigning then to the `begin-glyph' or
1778 `end-glyph' property of the extent. For zero-length extents, it
1779 doesn't really matter if you assign the glyph to the `begin-glyph'
1780 or `end-glyph' property, as they are both at the same location;
1781 however, for non-zero-length extents (extents that cover one or
1782 more characters of text), it does matter which one you use.
1784 Assigning `nil' to the `begin-glyph' or `end-glyph' property will
1785 delete any existing glyph. In this case, you may also want to
1786 delete the extent, assuming that the extent is used for no other
1789 * If you happen to insert two glyphs, side-by-side, note that the
1790 example `insert-glyph' function will have trouble, if it's again
1791 used at the same point (it can only locate one of the two extents).
1792 *Note Finding Extents::, and *Note Mapping Over Extents::, for more
1793 information on locating extents in a buffer.
1795 * Among other things, glyphs provide a way of displaying graphics
1796 alongside text. Note, however, that glyphs only provide a way of
1797 displaying graphics; glyphs are not actually part of the text, and
1798 are only displayed alongside the text. If you save the text in
1799 the buffer, the graphics are not saved. The low-level glyph code
1800 does not provide a way of saving graphics with the text. If you
1801 need to save graphics and text, you have to write your own code to
1802 do this, and this topic is outside the scope of this discussion.
1806 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
1811 An "annotation" is a pixmap or string that is not part of a buffer's
1812 text but is displayed next to a particular location in a buffer.
1813 Annotations can be displayed intermixed with text, in any whitespace at
1814 the beginning or end of a line, or in a special area at the left or
1815 right side of the frame called a "margin", whose size is controllable.
1816 Annotations are implemented using extents (*note Extents::); but you
1817 can work with annotations without knowing how extents work.
1821 * Annotation Basics:: Introduction to annotations.
1822 * Annotation Primitives:: Creating and deleting annotations.
1823 * Annotation Properties:: Retrieving and changing the characteristics
1825 * Margin Primitives:: Controlling the size of the margins.
1826 * Locating Annotations:: Looking for annotations in a buffer.
1827 * Annotation Hooks:: Hooks called at certain times during an
1828 annotation's lifetime.
1831 File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
1836 Marginal annotations are notes associated with a particular location in
1837 a buffer. They may be displayed in a margin created on the left-hand or
1838 right-hand side of the frame, in any whitespace at the beginning or end
1839 of a line, or inside of the text itself. Every annotation may have an
1840 associated action to be performed when the annotation is selected. The
1841 term "annotation" is used to refer to an individual note. The term
1842 "margin" is generically used to refer to the whitespace before the
1843 first character on a line or after the last character on a line.
1845 Each annotation has the following characteristics:
1847 This is a glyph object and is used as the displayed representation
1851 If given, this glyph is used as the displayed representation of
1852 the annotation when the mouse is pressed down over the annotation.
1855 The face with which to display the glyph.
1858 Which side of the text (left or right) the annotation is displayed
1862 If non-`nil', this field must contain a function capable of being
1863 the first argument to `funcall'. This function is normally
1864 evaluated with a single argument, the value of the DATA field,
1865 each time the annotation is selected. However, if the WITH-EVENT
1866 parameter to `make-annotation' is non-`nil', the function is
1867 called with two arguments. The first argument is the same as
1868 before, and the second argument is the event (a button-up event,
1869 usually) that activated the annotation.
1872 Not used internally. This field can contain any E-Lisp object.
1873 It is passed as the first argument to ACTION described above.
1876 A menu displayed when the right mouse button is pressed over the
1879 The margin is divided into "outside" and "inside". The outside
1880 margin is space on the left or right side of the frame which normal text
1881 cannot be displayed in. The inside margin is that space between the
1882 leftmost or rightmost point at which text can be displayed and where the
1883 first or last character actually is.
1885 There are four different "layout types" which affect the exact
1886 location an annotation appears.
1889 The annotation is placed in the outside margin area. as close as
1890 possible to the edge of the frame. If the outside margin is not
1891 wide enough for an annotation to fit, it is not displayed.
1894 The annotation is placed in the inside margin area, as close as
1895 possible to the edge of the frame. If the inside margin is not
1896 wide enough for the annotation to fit, it will be displayed using
1897 any available outside margin space if and only if the specifier
1898 `use-left-overflow' or `use-right-overflow' (depending on which
1899 side the annotation appears in) is non-`nil'.
1902 The annotation is placed in the inside margin area, as close as
1903 possible to the first or last non-whitespace character on a line.
1904 If the inside margin is not wide enough for the annotation to fit,
1905 it will be displayed if and only if the specifier
1906 `use-left-overflow' or `use-right-overflow' (depending on which
1907 side the annotation appears in) is non-`nil'.
1910 The annotation is placed at the position it is inserted. It will
1911 create enough space for itself inside of the text area. It does
1912 not take up a place in the logical buffer, only in the display of
1915 The current layout policy is that all `whitespace' annotations are
1916 displayed first. Next, all `inside-margin' annotations are displayed
1917 using any remaining space. Finally as many `outside-margin'
1918 annotations are displayed as possible. The `text' annotations will
1919 always display as they create their own space to display in.
1922 File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
1924 Annotation Primitives
1925 =====================
1927 - Function: make-annotation glyph &optional position layout buffer
1928 with-event d-glyph rightp
1929 This function creates a marginal annotation at position POSITION in
1930 BUFFER. The annotation is displayed using GLYPH, which should be
1931 a glyph object or a string, and is positioned using layout policy
1932 LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
1933 `whitespace' is used. If BUFFER is `nil', the current buffer is
1936 If WITH-EVENT is non-`nil', then when an annotation is activated,
1937 the triggering event is passed as the second arg to the annotation
1938 function. If D-GLYPH is non-`nil' then it is used as the glyph
1939 that will be displayed when button1 is down. If RIGHTP is
1940 non-`nil' then the glyph will be displayed on the right side of
1941 the buffer instead of the left.
1943 The newly created annotation is returned.
1945 - Function: delete-annotation annotation
1946 This function removes ANNOTATION from its buffer. This does not
1947 modify the buffer text.
1949 - Function: annotationp annotation
1950 This function returns `t' if ANNOTATION is an annotation, `nil'
1954 File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
1956 Annotation Properties
1957 =====================
1959 - Function: annotation-glyph annotation
1960 This function returns the glyph object used to display ANNOTATION.
1962 - Function: set-annotation-glyph annotation glyph &optional layout side
1963 This function sets the glyph of ANNOTATION to GLYPH, which should
1964 be a glyph object. If LAYOUT is non-`nil', set the layout policy
1965 of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
1966 side of the buffer at which the annotation is displayed to the
1967 given side. The new value of `annotation-glyph' is returned.
1969 - Function: annotation-down-glyph annotation
1970 This function returns the glyph used to display ANNOTATION when
1971 the left mouse button is depressed on the annotation.
1973 - Function: set-annotation-down-glyph annotation glyph
1974 This function returns the glyph used to display ANNOTATION when
1975 the left mouse button is depressed on the annotation to GLYPH,
1976 which should be a glyph object.
1978 - Function: annotation-face annotation
1979 This function returns the face associated with ANNOTATION.
1981 - Function: set-annotation-face annotation face
1982 This function sets the face associated with ANNOTATION to FACE.
1984 - Function: annotation-layout annotation
1985 This function returns the layout policy of ANNOTATION.
1987 - Function: set-annotation-layout annotation layout
1988 This function sets the layout policy of ANNOTATION to LAYOUT.
1990 - Function: annotation-side annotation
1991 This function returns the side of the buffer that ANNOTATION is
1992 displayed on. Return value is a symbol, either `left' or `right'.
1994 - Function: annotation-data annotation
1995 This function returns the data associated with ANNOTATION.
1997 - Function: set-annotation-data annotation data
1998 This function sets the data field of ANNOTATION to DATA. DATA is
2001 - Function: annotation-action annotation
2002 This function returns the action associated with ANNOTATION.
2004 - Function: set-annotation-action annotation action
2005 This function sets the action field of ANNOTATION to ACTION.
2006 ACTION is returned..
2008 - Function: annotation-menu annotation
2009 This function returns the menu associated with ANNOTATION.
2011 - Function: set-annotation-menu annotation menu
2012 This function sets the menu associated with ANNOTATION to MENU.
2013 This menu will be displayed when the right mouse button is pressed
2014 over the annotation.
2016 - Function: annotation-visible annotation
2017 This function returns `t' if there is enough available space to
2018 display ANNOTATION, `nil' otherwise.
2020 - Function: annotation-width annotation
2021 This function returns the width of ANNOTATION in pixels.
2023 - Function: hide-annotation annotation
2024 This function removes ANNOTATION's glyph, making it invisible.
2026 - Function: reveal-annotation annotation
2027 This function restores ANNOTATION's glyph, making it visible.
2030 File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
2032 Locating Annotations
2033 ====================
2035 - Function: annotations-in-region start end buffer
2036 This function returns a list of all annotations in BUFFER which
2037 are between START and END inclusively.
2039 - Function: annotations-at &optional position buffer
2040 This function returns a list of all annotations at POSITION in
2041 BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
2042 the current buffer is used.
2044 - Function: annotation-list &optional buffer
2045 This function returns a list of all annotations in BUFFER. If
2046 BUFFER is `nil', the current buffer is used.
2048 - Function: all-annotations
2049 This function returns a list of all annotations in all buffers in
2053 File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
2058 The margin widths are controllable on a buffer-local, window-local,
2059 frame-local, device-local, or device-type-local basis through the use
2060 of specifiers. *Note Specifiers::.
2062 - Specifier: left-margin-width
2063 This is a specifier variable controlling the width of the left
2064 outside margin, in characters. Use `set-specifier' to change its
2067 - Specifier: right-margin-width
2068 This is a specifier variable controlling the width of the right
2069 outside margin, in characters. Use `set-specifier' to change its
2072 - Specifier: use-left-overflow
2073 If non-`nil', use the left outside margin as extra whitespace when
2074 displaying `whitespace' and `inside-margin' annotations. Defaults
2075 to `nil'. This is a specifier variable; use `set-specifier' to
2078 - Specifier: use-right-overflow
2079 If non-`nil', use the right outside margin as extra whitespace when
2080 displaying `whitespace' and `inside-margin' annotations. Defaults
2081 to `nil'. This is a specifier variable; use `set-specifier' to
2084 - Function: window-left-margin-pixel-width &optional window
2085 This function returns the width in pixels of the left outside
2086 margin of WINDOW. If WINDOW is `nil', the selected window is
2089 - Function: window-right-margin-pixel-width &optional window
2090 This function returns the width in pixels of the right outside
2091 margin of WINDOW. If WINDOW is `nil', the selected window is
2094 The margin colors are controlled by the faces `left-margin' and
2095 `right-margin'. These can be set using the X resources
2096 `Emacs.left-margin.background' and `Emacs.left-margin.foreground';
2097 likewise for the right margin.
2100 File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
2105 The following three hooks are provided for use with the marginal
2108 `before-delete-annotation-hook'
2109 This hook is called immediately before an annotation is destroyed.
2110 It is passed a single argument, the annotation being destroyed.
2112 `after-delete-annotation-hook'
2113 This normal hook is called immediately after an annotation is
2116 `make-annotation-hook'
2117 This hook is called immediately after an annotation is created.
2118 It is passed a single argument, the newly created annotation.
2121 File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
2126 This chapter describes a number of other features related to the display
2127 that XEmacs presents to the user.
2131 * Refresh Screen:: Clearing the screen and redrawing everything on it.
2132 * Truncation:: Folding or wrapping long text lines.
2133 * The Echo Area:: Where messages are displayed.
2134 * Warnings:: Display of Warnings.
2135 * Invisible Text:: Hiding part of the buffer text.
2136 * Selective Display:: Hiding part of the buffer text (the old way).
2137 * Overlay Arrow:: Display of an arrow to indicate position.
2138 * Temporary Displays:: Displays that go away automatically.
2139 * Blinking:: How XEmacs shows the matching open parenthesis.
2140 * Usual Display:: The usual conventions for displaying nonprinting chars.
2141 * Display Tables:: How to specify other conventions.
2142 * Beeping:: Audible signal to the user.
2145 File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
2147 Refreshing the Screen
2148 =====================
2150 The function `redraw-frame' redisplays the entire contents of a given
2151 frame. *Note Frames::.
2153 - Function: redraw-frame &optional frame no-preempt
2154 This function clears and redisplays frame FRAME.
2156 FRAME defaults to the selected frame if omitted.
2158 Normally, redisplay is preempted as normal if input arrives.
2159 However, if optional second arg NO-PREEMPT is non-`nil', redisplay
2160 will not stop for input and is guaranteed to proceed to completion.
2162 Even more powerful is `redraw-display':
2164 - Command: redraw-display &optional device
2165 This function redraws all frames on DEVICE marked as having their
2166 image garbled. DEVICE defaults to the selected device. If DEVICE
2167 is `t', all devices will have their frames checked.
2169 Processing user input takes absolute priority over redisplay. If you
2170 call these functions when input is available, they do nothing
2171 immediately, but a full redisplay does happen eventually--after all the
2172 input has been processed.
2174 Normally, suspending and resuming XEmacs also refreshes the screen.
2175 Some terminal emulators record separate contents for display-oriented
2176 programs such as XEmacs and for ordinary sequential display. If you are
2177 using such a terminal, you might want to inhibit the redisplay on
2178 resumption. *Note Suspending XEmacs::.
2180 - Variable: no-redraw-on-reenter
2181 This variable controls whether XEmacs redraws the entire screen
2182 after it has been suspended and resumed. Non-`nil' means yes,
2185 The above functions do not actually cause the display to be updated;
2186 rather, they clear out the internal display records that XEmacs
2187 maintains, so that the next time the display is updated it will be
2188 redrawn from scratch. Normally this occurs the next time that
2189 `next-event' or `sit-for' is called; however, a display update will not
2190 occur if there is input pending. *Note Command Loop::.
2192 - Function: force-cursor-redisplay &optional frame
2193 This function causes an immediate update of the cursor on FRAME,
2194 which defaults to the selected frame.
2197 File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
2202 When a line of text extends beyond the right edge of a window, the line
2203 can either be truncated or continued on the next line. When a line is
2204 truncated, this is normally shown with a `\' in the rightmost column of
2205 the window on X displays, and with a `$' on TTY devices. When a line
2206 is continued or "wrapped" onto the next line, this is shown with a
2207 curved arrow in the rightmost column of the window (or with a `\' on
2208 TTY devices). The additional screen lines used to display a long text
2209 line are called "continuation" lines.
2211 Normally, whenever line truncation is in effect for a particular
2212 window, a horizontal scrollbar is displayed in that window if the
2213 device supports scrollbars. *Note Scrollbars::.
2215 Note that continuation is different from filling; continuation
2216 happens on the screen only, not in the buffer contents, and it breaks a
2217 line precisely at the right margin, not at a word boundary. *Note
2220 - User Option: truncate-lines
2221 This buffer-local variable controls how XEmacs displays lines that
2222 extend beyond the right edge of the window. If it is non-`nil',
2223 then XEmacs does not display continuation lines; rather each line
2224 of text occupies exactly one screen line, and a backslash appears
2225 at the edge of any line that extends to or beyond the edge of the
2226 window. The default is `nil'.
2228 If the variable `truncate-partial-width-windows' is non-`nil',
2229 then truncation is always used for side-by-side windows (within one
2230 frame) regardless of the value of `truncate-lines'.
2232 - User Option: default-truncate-lines
2233 This variable is the default value for `truncate-lines', for
2234 buffers that do not have local values for it.
2236 - User Option: truncate-partial-width-windows
2237 This variable controls display of lines that extend beyond the
2238 right edge of the window, in side-by-side windows (*note Splitting
2239 Windows::). If it is non-`nil', these lines are truncated;
2240 otherwise, `truncate-lines' says what to do with them.
2242 The backslash and curved arrow used to indicate truncated or
2243 continued lines are only defaults, and can be changed. These images
2244 are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
2245 flexibility in how glyphs can be controlled. (This differs from FSF
2246 Emacs, which uses display tables to control these images.)
2248 For details, *Note Redisplay Glyphs::.
2251 File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
2256 The "echo area" is used for displaying messages made with the `message'
2257 primitive, and for echoing keystrokes. It is not the same as the
2258 minibuffer, despite the fact that the minibuffer appears (when active)
2259 in the same place on the screen as the echo area. The `XEmacs Lisp
2260 Reference Manual' specifies the rules for resolving conflicts between
2261 the echo area and the minibuffer for use of that screen space (*note
2262 The Minibuffer: (xemacs)Minibuffer.). Error messages appear in the
2263 echo area; see *Note Errors::.
2265 You can write output in the echo area by using the Lisp printing
2266 functions with `t' as the stream (*note Output Functions::), or as
2269 - Function: message string &rest arguments
2270 This function displays a one-line message in the echo area. The
2271 argument STRING is similar to a C language `printf' control
2272 string. See `format' in *Note String Conversion::, for the details
2273 on the conversion specifications. `message' returns the
2276 In batch mode, `message' prints the message text on the standard
2277 error stream, followed by a newline.
2279 If STRING is `nil', `message' clears the echo area. If the
2280 minibuffer is active, this brings the minibuffer contents back onto
2281 the screen immediately.
2283 (message "Minibuffer depth is %d."
2285 -| Minibuffer depth is 0.
2286 => "Minibuffer depth is 0."
2288 ---------- Echo Area ----------
2289 Minibuffer depth is 0.
2290 ---------- Echo Area ----------
2292 In addition to only displaying a message, XEmacs allows you to
2293 "label" your messages, giving you fine-grained control of their
2294 display. Message label is a symbol denoting the message type. Some
2295 standard labels are:
2297 * `message'--default label used by the `message' function;
2299 * `error'--default label used for reporting errors;
2301 * `progress'--progress indicators like `Converting... 45%' (not
2304 * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
2307 * `command'--helper command messages like `Mark set' (not logged by
2310 * `no-log'--messages that should never be logged
2312 Several messages may be stacked in the echo area at once. Lisp
2313 programs may access these messages, or remove them as appropriate, via
2316 - Function: display-message label message &optional frame stdout-p
2317 This function displays MESSAGE (a string) labeled as LABEL, as
2320 The FRAME argument specifies the frame to whose minibuffer the
2321 message should be printed. This is currently unimplemented. The
2322 STDOUT-P argument is used internally.
2324 (display-message 'command "Mark set")
2326 - Function: lmessage label string &rest arguments
2327 This function displays a message STRING with label LABEL. It is
2328 similar to `message' in that it accepts a `printf'-like strings
2329 and any number of arguments.
2331 ;; Display a command message.
2332 (lmessage 'command "Comment column set to %d" comment-column)
2334 ;; Display a progress message.
2335 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
2337 ;; Display a message that should not be logged.
2338 (lmessage 'no-log "Done")
2340 - Function: clear-message &optional label frame stdout-p no-restore
2341 This function remove any message with the given LABEL from the
2342 message-stack, erasing it from the echo area if it's currently
2345 If a message remains at the head of the message-stack and
2346 NO-RESTORE is `nil', it will be displayed. The string which
2347 remains in the echo area will be returned, or `nil' if the
2348 message-stack is now empty. If LABEL is `nil', the entire
2349 message-stack is cleared.
2351 ;; Show a message, wait for 2 seconds, and restore old minibuffer
2353 (message "A message")
2356 (lmessage 'my-label "Newsflash! Newsflash!")
2357 -| Newsflash! Newsflash!
2358 => "Newsflash! Newsflash!"
2360 (clear-message 'my-label)
2364 Unless you need the return value or you need to specify a label,
2365 you should just use `(message nil)'.
2367 - Function: current-message &optional frame
2368 This function returns the current message in the echo area, or
2369 `nil'. The FRAME argument is currently unused.
2371 Some of the messages displayed in the echo area are also recorded in
2372 the ` *Message-Log*' buffer. Exactly which messages will be recorded
2373 can be tuned using the following variables.
2375 - User Option: log-message-max-size
2376 This variable specifies the maximum size of the ` *Message-log*'
2379 - Variable: log-message-ignore-labels
2380 This variable specifies the labels whose messages will not be
2381 logged. It should be a list of symbols.
2383 - Variable: log-message-ignore-regexps
2384 This variable specifies the regular expressions matching messages
2385 that will not be logged. It should be a list of regular
2388 Normally, packages that generate messages that might need to be
2389 ignored should label them with `progress', `prompt', or `no-log',
2390 so they can be filtered by `log-message-ignore-labels'.
2392 - Variable: echo-keystrokes
2393 This variable determines how much time should elapse before command
2394 characters echo. Its value must be a number, which specifies the
2395 number of seconds to wait before echoing. If the user types a
2396 prefix key (such as `C-x') and then delays this many seconds
2397 before continuing, the prefix key is echoed in the echo area. Any
2398 subsequent characters in the same command will be echoed as well.
2400 If the value is zero, then command input is not echoed.
2402 - Variable: cursor-in-echo-area
2403 This variable controls where the cursor appears when a message is
2404 displayed in the echo area. If it is non-`nil', then the cursor
2405 appears at the end of the message. Otherwise, the cursor appears
2406 at point--not in the echo area at all.
2408 The value is normally `nil'; Lisp programs bind it to `t' for
2409 brief periods of time.
2412 File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
2417 XEmacs contains a facility for unified display of various warnings.
2418 Unlike errors, warnings are displayed in the situations when XEmacs
2419 encounters a problem that is recoverable, but which should be fixed for
2420 safe future operation.
2422 For example, warnings are printed by the startup code when it
2423 encounters problems with X keysyms, when there is an error in `.emacs',
2424 and in other problematic situations. Unlike messages, warnings are
2425 displayed in a separate buffer, and include an explanatory message that
2426 may span across several lines. Here is an example of how a warning is
2429 (1) (initialization/error) An error has occurred while loading ~/.emacs:
2431 Symbol's value as variable is void: bogus-variable
2433 To ensure normal operation, you should investigate the cause of the error
2434 in your initialization file and remove it. Use the `-debug-init' option
2435 to XEmacs to view a complete error backtrace.
2437 Each warning has a "class" and a "priority level". The class is a
2438 symbol describing what sort of warning this is, such as
2439 `initialization', `resource' or `key-mapping'.
2441 The warning priority level specifies how important the warning is.
2442 The recognized warning levels, in increased order of priority, are:
2443 `debug', `info', `notice', `warning', `error', `critical', `alert' and
2446 - Function: display-warning class message &optional level
2447 This function displays a warning message MESSAGE (a string).
2448 CLASS should be a warning class symbol, as described above, or a
2449 list of such symbols. LEVEL describes the warning priority level.
2450 If unspecified, it default to `warning'.
2452 (display-warning 'resource
2453 "Bad resource specification encountered:
2458 You should replace the * with a . in order to get proper behavior when
2459 you use the specifier and/or `set-face-*' functions.")
2461 ---------- Warning buffer ----------
2462 (1) (resource/warning) Bad resource specification encountered:
2467 You should replace the * with a . in order to get proper behavior when
2468 you use the specifier and/or `set-face-*' functions.
2469 ---------- Warning buffer ----------
2471 - Function: lwarn class level message &rest args
2472 This function displays a formatted labeled warning message. As
2473 above, CLASS should be the warning class symbol, or a list of such
2474 symbols, and LEVEL should specify the warning priority level
2475 (`warning' by default).
2477 Unlike in `display-warning', MESSAGE may be a formatted message,
2478 which will be, together with the rest of the arguments, passed to
2481 (lwarn 'message-log 'warning
2482 "Error caught in `remove-message-hook': %s"
2483 (error-message-string e))
2485 - Variable: log-warning-minimum-level
2486 This variable specifies the minimum level of warnings that should
2487 be generated. Warnings with level lower than defined by this
2488 variable are completely ignored, as if they never happened.
2490 - Variable: display-warning-minimum-level
2491 This variable specifies the minimum level of warnings that should
2492 be displayed. Unlike `log-warning-minimum-level', setting this
2493 function does not suppress warnings entirely--they are still
2494 generated in the `*Warnings*' buffer, only they are not displayed
2497 - Variable: log-warning-suppressed-classes
2498 This variable specifies a list of classes that should not be
2499 logged or displayed. If any of the class symbols associated with
2500 a warning is the same as any of the symbols listed here, the
2501 warning will be completely ignored, as it they never happened.
2503 - Variable: display-warning-suppressed-classes
2504 This variable specifies a list of classes that should not be
2505 logged or displayed. If any of the class symbols associated with
2506 a warning is the same as any of the symbols listed here, the
2507 warning will not be displayed. The warning will still logged in
2508 the *Warnings* buffer (unless also contained in
2509 `log-warning-suppressed-classes'), but the buffer will not be
2510 automatically popped up.
2513 File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
2518 You can make characters "invisible", so that they do not appear on the
2519 screen, with the `invisible' property. This can be either a text
2520 property or a property of an overlay.
2522 In the simplest case, any non-`nil' `invisible' property makes a
2523 character invisible. This is the default case--if you don't alter the
2524 default value of `buffer-invisibility-spec', this is how the
2525 `invisibility' property works. This feature is much like selective
2526 display (*note Selective Display::), but more general and cleaner.
2528 More generally, you can use the variable `buffer-invisibility-spec'
2529 to control which values of the `invisible' property make text
2530 invisible. This permits you to classify the text into different subsets
2531 in advance, by giving them different `invisible' values, and
2532 subsequently make various subsets visible or invisible by changing the
2533 value of `buffer-invisibility-spec'.
2535 Controlling visibility with `buffer-invisibility-spec' is especially
2536 useful in a program to display the list of entries in a data base. It
2537 permits the implementation of convenient filtering commands to view
2538 just a part of the entries in the data base. Setting this variable is
2539 very fast, much faster than scanning all the text in the buffer looking
2540 for properties to change.
2542 - Variable: buffer-invisibility-spec
2543 This variable specifies which kinds of `invisible' properties
2544 actually make a character invisible.
2547 A character is invisible if its `invisible' property is
2548 non-`nil'. This is the default.
2551 Each element of the list makes certain characters invisible.
2552 Ultimately, a character is invisible if any of the elements
2553 of this list applies to it. The list can have two kinds of
2557 A character is invisible if its `invisible' property
2558 value is ATOM or if it is a list with ATOM as a member.
2561 A character is invisible if its `invisible' property
2562 value is ATOM or if it is a list with ATOM as a member.
2563 Moreover, if this character is at the end of a line and
2564 is followed by a visible newline, it displays an
2567 Ordinarily, commands that operate on text or move point do not care
2568 whether the text is invisible. However, the user-level line motion
2569 commands explicitly ignore invisible newlines. Since this causes a
2570 slow-down of these commands it is turned off by default, controlled by
2571 the variable `line-move-ignore-invisible'.
2574 File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
2579 "Selective display" is a pair of features that hide certain lines on
2582 The first variant, explicit selective display, is designed for use in
2583 a Lisp program. The program controls which lines are hidden by altering
2584 the text. Outline mode has traditionally used this variant. It has
2585 been partially replaced by the invisible text feature (*note Invisible
2586 Text::); there is a new version of Outline mode which uses that instead.
2588 In the second variant, the choice of lines to hide is made
2589 automatically based on indentation. This variant is designed to be a
2592 The way you control explicit selective display is by replacing a
2593 newline (control-j) with a carriage return (control-m). The text that
2594 was formerly a line following that newline is now invisible. Strictly
2595 speaking, it is temporarily no longer a line at all, since only newlines
2596 can separate lines; it is now part of the previous line.
2598 Selective display does not directly affect editing commands. For
2599 example, `C-f' (`forward-char') moves point unhesitatingly into
2600 invisible text. However, the replacement of newline characters with
2601 carriage return characters affects some editing commands. For example,
2602 `next-line' skips invisible lines, since it searches only for newlines.
2603 Modes that use selective display can also define commands that take
2604 account of the newlines, or that make parts of the text visible or
2607 When you write a selectively displayed buffer into a file, all the
2608 control-m's are output as newlines. This means that when you next read
2609 in the file, it looks OK, with nothing invisible. The selective display
2610 effect is seen only within XEmacs.
2612 - Variable: selective-display
2613 This buffer-local variable enables selective display. This means
2614 that lines, or portions of lines, may be made invisible.
2616 * If the value of `selective-display' is `t', then any portion
2617 of a line that follows a control-m is not displayed.
2619 * If the value of `selective-display' is a positive integer,
2620 then lines that start with more than that many columns of
2621 indentation are not displayed.
2623 When some portion of a buffer is invisible, the vertical movement
2624 commands operate as if that portion did not exist, allowing a
2625 single `next-line' command to skip any number of invisible lines.
2626 However, character movement commands (such as `forward-char') do
2627 not skip the invisible portion, and it is possible (if tricky) to
2628 insert or delete text in an invisible portion.
2630 In the examples below, we show the _display appearance_ of the
2631 buffer `foo', which changes with the value of `selective-display'.
2632 The _contents_ of the buffer do not change.
2634 (setq selective-display nil)
2637 ---------- Buffer: foo ----------
2644 ---------- Buffer: foo ----------
2646 (setq selective-display 2)
2649 ---------- Buffer: foo ----------
2654 ---------- Buffer: foo ----------
2656 - Variable: selective-display-ellipses
2657 If this buffer-local variable is non-`nil', then XEmacs displays
2658 `...' at the end of a line that is followed by invisible text.
2659 This example is a continuation of the previous one.
2661 (setq selective-display-ellipses t)
2664 ---------- Buffer: foo ----------
2669 ---------- Buffer: foo ----------
2671 You can use a display table to substitute other text for the
2672 ellipsis (`...'). *Note Display Tables::.
2675 File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
2680 The "overlay arrow" is useful for directing the user's attention to a
2681 particular line in a buffer. For example, in the modes used for
2682 interface to debuggers, the overlay arrow indicates the line of code
2683 about to be executed.
2685 - Variable: overlay-arrow-string
2686 This variable holds the string to display to call attention to a
2687 particular line, or `nil' if the arrow feature is not in use.
2688 Despite its name, the value of this variable can be either a string
2689 or a glyph (*note Glyphs::).
2691 - Variable: overlay-arrow-position
2692 This variable holds a marker that indicates where to display the
2693 overlay arrow. It should point at the beginning of a line. The
2694 arrow text appears at the beginning of that line, overlaying any
2695 text that would otherwise appear. Since the arrow is usually
2696 short, and the line usually begins with indentation, normally
2697 nothing significant is overwritten.
2699 The overlay string is displayed only in the buffer that this marker
2700 points into. Thus, only one buffer can have an overlay arrow at
2703 You can do the same job by creating an extent with a `begin-glyph'
2704 property. *Note Extent Properties::.
2707 File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
2712 Temporary displays are used by commands to put output into a buffer and
2713 then present it to the user for perusal rather than for editing. Many
2714 of the help commands use this feature.
2716 - Special Form: with-output-to-temp-buffer buffer-name forms...
2717 This function executes FORMS while arranging to insert any output
2718 they print into the buffer named BUFFER-NAME. The buffer is then
2719 shown in some window for viewing, displayed but not selected.
2721 The string BUFFER-NAME specifies the temporary buffer, which need
2722 not already exist. The argument must be a string, not a buffer.
2723 The buffer is erased initially (with no questions asked), and it is
2724 marked as unmodified after `with-output-to-temp-buffer' exits.
2726 `with-output-to-temp-buffer' binds `standard-output' to the
2727 temporary buffer, then it evaluates the forms in FORMS. Output
2728 using the Lisp output functions within FORMS goes by default to
2729 that buffer (but screen display and messages in the echo area,
2730 although they are "output" in the general sense of the word, are
2731 not affected). *Note Output Functions::.
2733 The value of the last form in FORMS is returned.
2735 ---------- Buffer: foo ----------
2736 This is the contents of foo.
2737 ---------- Buffer: foo ----------
2739 (with-output-to-temp-buffer "foo"
2741 (print standard-output))
2744 ---------- Buffer: foo ----------
2749 ---------- Buffer: foo ----------
2751 - Variable: temp-buffer-show-function
2752 If this variable is non-`nil', `with-output-to-temp-buffer' calls
2753 it as a function to do the job of displaying a help buffer. The
2754 function gets one argument, which is the buffer it should display.
2756 In Emacs versions 18 and earlier, this variable was called
2757 `temp-buffer-show-hook'.
2759 - Function: momentary-string-display string position &optional char
2761 This function momentarily displays STRING in the current buffer at
2762 POSITION. It has no effect on the undo list or on the buffer's
2763 modification status.
2765 The momentary display remains until the next input event. If the
2766 next input event is CHAR, `momentary-string-display' ignores it
2767 and returns. Otherwise, that event remains buffered for
2768 subsequent use as input. Thus, typing CHAR will simply remove the
2769 string from the display, while typing (say) `C-f' will remove the
2770 string from the display and later (presumably) move point forward.
2771 The argument CHAR is a space by default.
2773 The return value of `momentary-string-display' is not meaningful.
2775 You can do the same job in a more general way by creating an extent
2776 with a begin-glyph property. *Note Extent Properties::.
2778 If MESSAGE is non-`nil', it is displayed in the echo area while
2779 STRING is displayed in the buffer. If it is `nil', a default
2780 message says to type CHAR to continue.
2782 In this example, point is initially located at the beginning of the
2785 ---------- Buffer: foo ----------
2786 This is the contents of foo.
2788 ---------- Buffer: foo ----------
2790 (momentary-string-display
2791 "**** Important Message! ****"
2793 "Type RET when done reading")
2796 ---------- Buffer: foo ----------
2797 This is the contents of foo.
2798 **** Important Message! ****Second line.
2799 ---------- Buffer: foo ----------
2801 ---------- Echo Area ----------
2802 Type RET when done reading
2803 ---------- Echo Area ----------
2805 This function works by actually changing the text in the buffer.
2806 As a result, if you later undo in this buffer, you will see the
2807 message come and go.
2810 File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
2812 Blinking Parentheses
2813 ====================
2815 This section describes the mechanism by which XEmacs shows a matching
2816 open parenthesis when the user inserts a close parenthesis.
2818 - Variable: blink-paren-function
2819 The value of this variable should be a function (of no arguments)
2820 to be called whenever a character with close parenthesis syntax is
2821 inserted. The value of `blink-paren-function' may be `nil', in
2822 which case nothing is done.
2824 *Please note:* This variable was named `blink-paren-hook' in
2825 older Emacs versions, but since it is not called with the
2826 standard convention for hooks, it was renamed to
2827 `blink-paren-function' in version 19.
2829 - Variable: blink-matching-paren
2830 If this variable is `nil', then `blink-matching-open' does nothing.
2832 - Variable: blink-matching-paren-distance
2833 This variable specifies the maximum distance to scan for a matching
2834 parenthesis before giving up.
2836 - Variable: blink-matching-paren-delay
2837 This variable specifies the number of seconds for the cursor to
2838 remain at the matching parenthesis. A fraction of a second often
2839 gives good results, but the default is 1, which works on all
2842 - Command: blink-matching-open
2843 This function is the default value of `blink-paren-function'. It
2844 assumes that point follows a character with close parenthesis
2845 syntax and moves the cursor momentarily to the matching opening
2846 character. If that character is not already on the screen, it
2847 displays the character's context in the echo area. To avoid long
2848 delays, this function does not search farther than
2849 `blink-matching-paren-distance' characters.
2851 Here is an example of calling this function explicitly.
2853 (defun interactive-blink-matching-open ()
2854 "Indicate momentarily the start of sexp before point."
2856 (let ((blink-matching-paren-distance
2858 (blink-matching-paren t))
2859 (blink-matching-open)))
2862 File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
2864 Usual Display Conventions
2865 =========================
2867 The usual display conventions define how to display each character
2868 code. You can override these conventions by setting up a display table
2869 (*note Display Tables::). Here are the usual display conventions:
2871 * Character codes 32 through 126 map to glyph codes 32 through 126.
2872 Normally this means they display as themselves.
2874 * Character code 9 is a horizontal tab. It displays as whitespace
2875 up to a position determined by `tab-width'.
2877 * Character code 10 is a newline.
2879 * All other codes in the range 0 through 31, and code 127, display
2880 in one of two ways according to the value of `ctl-arrow'. If it is
2881 non-`nil', these codes map to sequences of two glyphs, where the
2882 first glyph is the ASCII code for `^'. (A display table can
2883 specify a glyph to use instead of `^'.) Otherwise, these codes map
2884 just like the codes in the range 128 to 255.
2886 * Character codes 128 through 255 map to sequences of four glyphs,
2887 where the first glyph is the ASCII code for `\', and the others are
2888 digit characters representing the code in octal. (A display table
2889 can specify a glyph to use instead of `\'.)
2891 The usual display conventions apply even when there is a display
2892 table, for any character whose entry in the active display table is
2893 `nil'. Thus, when you set up a display table, you need only specify
2894 the characters for which you want unusual behavior.
2896 These variables affect the way certain characters are displayed on
2897 the screen. Since they change the number of columns the characters
2898 occupy, they also affect the indentation functions.
2900 - User Option: ctl-arrow
2901 This buffer-local variable controls how control characters are
2902 displayed. If it is non-`nil', they are displayed as a caret
2903 followed by the character: `^A'. If it is `nil', they are
2904 displayed as a backslash followed by three octal digits: `\001'.
2906 - Variable: default-ctl-arrow
2907 The value of this variable is the default value for `ctl-arrow' in
2908 buffers that do not override it. *Note Default Value::.
2910 - User Option: tab-width
2911 The value of this variable is the spacing between tab stops used
2912 for displaying tab characters in Emacs buffers. The default is 8.
2913 Note that this feature is completely independent from the
2914 user-settable tab stops used by the command `tab-to-tab-stop'.
2915 *Note Indent Tabs::.
2918 File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
2923 You can use the "display table" feature to control how all 256 possible
2924 character codes display on the screen. This is useful for displaying
2925 European languages that have letters not in the ASCII character set.
2927 The display table maps each character code into a sequence of
2928 "runes", each rune being an image that takes up one character position
2929 on the screen. You can also define how to display each rune on your
2930 terminal, using the "rune table".
2934 * Display Table Format:: What a display table consists of.
2935 * Active Display Table:: How XEmacs selects a display table to use.
2936 * Character Descriptors:: Format of an individual element of a
2940 File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
2942 Display Table Format
2943 --------------------
2945 A display table is an array of 256 elements. (In FSF Emacs, a display
2946 table is 262 elements. The six extra elements specify the truncation
2947 and continuation glyphs, etc. This method is very kludgey, and in
2948 XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
2949 used. *Note Truncation::.)
2951 - Function: make-display-table
2952 This creates and returns a display table. The table initially has
2953 `nil' in all elements.
2955 The 256 elements correspond to character codes; the Nth element says
2956 how to display the character code N. The value should be `nil', a
2957 string, a glyph, or a vector of strings and glyphs (*note Character
2958 Descriptors::). If an element is `nil', it says to display that
2959 character according to the usual display conventions (*note Usual
2962 If you use the display table to change the display of newline
2963 characters, the whole buffer will be displayed as one long "line."
2965 For example, here is how to construct a display table that mimics the
2966 effect of setting `ctl-arrow' to a non-`nil' value:
2968 (setq disptab (make-display-table))
2971 (or (= i ?\t) (= i ?\n)
2972 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
2974 (aset disptab 127 "^?"))
2977 File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
2979 Active Display Table
2980 --------------------
2982 The active display table is controlled by the variable
2983 `current-display-table'. This is a specifier, which means that you can
2984 specify separate values for it in individual buffers, windows, frames,
2985 and devices, as well as a global value. It also means that you cannot
2986 set this variable using `setq'; use `set-specifier' instead. *Note
2987 Specifiers::. (FSF Emacs uses `window-display-table',
2988 `buffer-display-table', `standard-display-table', etc. to control the
2989 display table. However, specifiers are a cleaner and more powerful way
2990 of doing the same thing. FSF Emacs also uses a different format for
2991 the contents of a display table, using additional indirection to a
2992 "glyph table" and such. Note that "glyph" has a different meaning in
2995 - Variable: current-display-table
2996 The display table currently in use. This is a specifier.
2998 Display tables are used to control how characters are displayed.
2999 Each time that redisplay processes a character, it is looked up in
3000 all the display tables that apply (obtained by calling
3001 `specifier-instance' on `current-display-table' and any overriding
3002 display tables specified in currently active faces). The first
3003 entry found that matches the character determines how the
3004 character is displayed. If there is no matching entry, the
3005 default display method is used. (Non-control characters are
3006 displayed as themselves and control characters are displayed
3007 according to the buffer-local variable `ctl-arrow'. Control
3008 characters are further affected by `control-arrow-glyph' and
3009 `octal-escape-glyph'.)
3011 Each instantiator in this specifier and the display-table
3012 specifiers in faces is a display table or a list of such tables.
3013 If a list, each table will be searched in turn for an entry
3014 matching a particular character. Each display table is one of
3016 * A vector, specifying values for characters starting at 0.
3018 * A char table, either of type `char' or `generic'.
3022 Each entry in a display table should be one of
3024 * nil (this entry is ignored and the search continues).
3026 * A character (use this character; if it happens to be the same
3027 as the original character, default processing happens,
3028 otherwise redisplay attempts to display this character
3029 directly; #### At some point recursive display-table lookup
3030 will be implemented).
3032 * A string (display each character in the string directly; ####
3033 At some point recursive display-table lookup will be
3036 * A glyph (display the glyph; #### At some point recursive
3037 display-table lookup will be implemented when a string glyph
3038 is being processed).
3040 * A cons of the form (format "STRING") where STRING is a
3041 printf-like spec used to process the character. ####
3042 Unfortunately no formatting directives other than %% are
3045 * A vector (each element of the vector is processed recursively;
3046 in such a case, nil elements in the vector are simply
3049 #### At some point in the near future, display tables are
3050 likely to be expanded to include other features, such as
3051 referencing characters in particular fonts and allowing the
3052 character search to continue all the way up the chain of
3053 specifier instantiators. These features are necessary to
3054 properly display Unicode characters.
3056 Individual faces can also specify an overriding display table; this
3057 is set using `set-face-display-table'. *Note Faces::.
3059 If no display table can be determined for a particular window, then
3060 XEmacs uses the usual display conventions. *Note Usual Display::.
3063 File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
3065 Character Descriptors
3066 ---------------------
3068 Each element of the display-table vector describes how to display a
3069 particular character and is called a "character descriptor". A
3070 character descriptor can be:
3073 Display this particular string wherever the character is to be
3077 Display this particular glyph wherever the character is to be
3081 The vector may contain strings and/or glyphs. Display the
3082 elements of the vector one after another wherever the character is
3086 Display according to the standard interpretation (*note Usual
3090 File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
3095 You can make XEmacs ring a bell, play a sound, or blink the screen to
3096 attract the user's attention. Be conservative about how often you do
3097 this; frequent bells can become irritating. Also be careful not to use
3098 beeping alone when signaling an error is appropriate. (*Note Errors::.)
3100 - Function: ding &optional dont-terminate sound device
3101 This function beeps, or flashes the screen (see `visible-bell'
3102 below). It also terminates any keyboard macro currently executing
3103 unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
3104 should be a symbol specifying which sound to make. This sound
3105 will be played if `visible-bell' is `nil'. (This only works if
3106 sound support was compiled into the executable and you are running
3107 on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
3108 PC. Otherwise you just get a beep.) The optional third argument
3109 specifies what device to make the sound on, and defaults to the
3112 - Function: beep &optional dont-terminate sound device
3113 This is a synonym for `ding'.
3115 - User Option: visible-bell
3116 This variable determines whether XEmacs should flash the screen to
3117 represent a bell. Non-`nil' means yes, `nil' means no. On TTY
3118 devices, this is effective only if the Termcap entry for the
3119 terminal type has the visible bell flag (`vb') set.
3121 - Variable: sound-alist
3122 This variable holds an alist associating names with sounds. When
3123 `beep' or `ding' is called with one of the name symbols, the
3124 associated sound will be generated instead of the standard beep.
3126 Each element of `sound-alist' is a list describing a sound. The
3127 first element of the list is the name of the sound being defined.
3128 Subsequent elements of the list are alternating keyword/value
3132 A string of raw sound data, or the name of another sound to
3133 play. The symbol `t' here means use the default X beep.
3136 An integer from 0-100, defaulting to `bell-volume'.
3139 If using the default X beep, the pitch (Hz) to generate.
3142 If using the default X beep, the duration (milliseconds).
3144 For compatibility, elements of `sound-alist' may also be:
3146 * `( sound-name . <sound> )'
3148 * `( sound-name <volume> <sound> )'
3150 You should probably add things to this list by calling the function
3155 - You can only play audio data if running on the console screen
3156 of a Sun SparcStation, SGI, or HP9000s700.
3158 - The pitch, duration, and volume options are available
3159 everywhere, but many X servers ignore the `pitch' option.
3161 The following beep-types are used by XEmacs itself:
3164 when an auto-save does not succeed
3167 when the XEmacs command loop catches an error
3170 when you type a key that is undefined
3173 when you use an undefined mouse-click combination
3176 during completing-read
3179 when you type something other than 'y' or 'n'
3182 when you type something other than 'yes' or 'no'
3185 used when nothing else is appropriate.
3187 Other lisp packages may use other beep types, but these are the
3188 ones that the C kernel of XEmacs uses.
3190 - User Option: bell-volume
3191 This variable specifies the default volume for sounds, from 0 to
3194 - Command: load-default-sounds
3195 This function loads and installs some sound files as beep-types.
3197 - Command: load-sound-file filename sound-name &optional volume
3198 This function reads in an audio file and adds it to `sound-alist'.
3199 The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
3200 should be a symbol, specifying the name of the sound. If VOLUME
3201 is specified, the sound will be played at that volume; otherwise,
3202 the value of `bell-volume' will be used.
3204 - Function: play-sound sound &optional volume device
3205 This function plays sound SOUND, which should be a symbol
3206 mentioned in `sound-alist'. If VOLUME is specified, it overrides
3207 the value (if any) specified in `sound-alist'. DEVICE specifies
3208 the device to play the sound on, and defaults to the selected
3211 - Command: play-sound-file file &optional volume device
3212 This function plays the named sound file at volume VOLUME, which
3213 defaults to `bell-volume'. DEVICE specifies the device to play
3214 the sound on, and defaults to the selected device.
3217 File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
3222 - Function: hash-table-p object
3223 This function returns `t' if OBJECT is a hash table, else `nil'.
3227 * Introduction to Hash Tables:: Hash tables are fast data structures for
3228 implementing simple tables (i.e. finite
3229 mappings from keys to values).
3230 * Working With Hash Tables:: Hash table functions.
3231 * Weak Hash Tables:: Hash tables with special garbage-collection
3235 File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
3237 Introduction to Hash Tables
3238 ===========================
3240 A "hash table" is a data structure that provides mappings from
3241 arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
3242 called "values". A key/value pair is sometimes called an "entry" in
3243 the hash table. There are many ways other than hash tables of
3244 implementing the same sort of mapping, e.g. association lists (*note
3245 Association Lists::) and property lists (*note Property Lists::), but
3246 hash tables provide much faster lookup when there are many entries in
3247 the mapping. Hash tables are an implementation of the abstract data
3248 type "dictionary", also known as "associative array".
3250 Internally, hash tables are hashed using the "linear probing" hash
3251 table implementation method. This method hashes each key to a
3252 particular spot in the hash table, and then scans forward sequentially
3253 until a blank entry is found. To look up a key, hash to the appropriate
3254 spot, then search forward for the key until either a key is found or a
3255 blank entry stops the search. This method is used in preference to
3256 double hashing because of changes in recent hardware. The penalty for
3257 non-sequential access to memory has been increasing, and this
3258 compensates for the problem of clustering that linear probing entails.
3260 When hash tables are created, the user may (but is not required to)
3261 specify initial properties that influence performance.
3263 Use the `:size' parameter to specify the number of entries that are
3264 likely to be stored in the hash table, to avoid the overhead of resizing
3265 the table. But if the pre-allocated space for the entries is never
3266 used, it is simply wasted and makes XEmacs slower. Excess unused hash
3267 table entries exact a small continuous performance penalty, since they
3268 must be scanned at every garbage collection. If the number of entries
3269 in the hash table is unknown, simply avoid using the `:size' keyword.
3271 Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
3272 the algorithm for deciding when to rehash the hash table. For
3273 temporary hash tables that are going to be very heavily used, use a
3274 small rehash threshold, for example, 0.4 and a large rehash size, for
3275 example 2.0. For permanent hash tables that will be infrequently used,
3276 specify a large rehash threshold, for example 0.8.
3278 Hash tables can also be created by the lisp reader using structure
3279 syntax, for example:
3280 #s(hash-table size 20 data (foo 1 bar 2))
3282 The structure syntax accepts the same keywords as `make-hash-table'
3283 (without the `:' character), as well as the additional keyword `data',
3284 which specifies the initial hash table contents.
3286 - Function: make-hash-table &key `test' `size' `rehash-size'
3287 `rehash-threshold' `weakness'
3288 This function returns a new empty hash table object.
3290 Keyword `:test' can be `eq', `eql' (default) or `equal'.
3291 Comparison between keys is done using this function. If speed is
3292 important, consider using `eq'. When storing strings in the hash
3293 table, you will likely need to use `equal'.
3295 Keyword `:size' specifies the number of keys likely to be inserted.
3296 This number of entries can be inserted without enlarging the hash
3299 Keyword `:rehash-size' must be a float greater than 1.0, and
3300 specifies the factor by which to increase the size of the hash
3301 table when enlarging.
3303 Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
3304 and specifies the load factor of the hash table which triggers
3307 Non-standard keyword `:weakness' can be `nil' (default), `t',
3308 `key-and-value', `key', `value' or `key-or-value'. `t' is an
3309 alias for `key-and-value'.
3311 A key-and-value-weak hash table, also known as a fully-weak or
3312 simply as a weak hash table, is one whose pointers do not count as
3313 GC referents: for any key-value pair in the hash table, if the only
3314 remaining pointer to either the key or the value is in a weak hash
3315 table, then the pair will be removed from the hash table, and the
3316 key and value collected. A non-weak hash table (or any other
3317 pointer) would prevent the object from being collected.
3319 A key-weak hash table is similar to a fully-weak hash table except
3320 that a key-value pair will be removed only if the key remains
3321 unmarked outside of weak hash tables. The pair will remain in the
3322 hash table if the key is pointed to by something other than a weak
3323 hash table, even if the value is not.
3325 A value-weak hash table is similar to a fully-weak hash table
3326 except that a key-value pair will be removed only if the value
3327 remains unmarked outside of weak hash tables. The pair will
3328 remain in the hash table if the value is pointed to by something
3329 other than a weak hash table, even if the key is not.
3331 A key-or-value-weak hash table is similar to a fully-weak hash
3332 table except that a key-value pair will be removed only if the
3333 value and the key remain unmarked outside of weak hash tables.
3334 The pair will remain in the hash table if the value or key are
3335 pointed to by something other than a weak hash table, even if the
3338 - Function: copy-hash-table hash-table
3339 This function returns a new hash table which contains the same
3340 keys and values as HASH-TABLE. The keys and values will not
3341 themselves be copied.
3343 - Function: hash-table-count hash-table
3344 This function returns the number of entries in HASH-TABLE.
3346 - Function: hash-table-test hash-table
3347 This function returns the test function of HASH-TABLE. This can
3348 be one of `eq', `eql' or `equal'.
3350 - Function: hash-table-size hash-table
3351 This function returns the current number of slots in HASH-TABLE,
3352 whether occupied or not.
3354 - Function: hash-table-rehash-size hash-table
3355 This function returns the current rehash size of HASH-TABLE. This
3356 is a float greater than 1.0; the factor by which HASH-TABLE is
3357 enlarged when the rehash threshold is exceeded.
3359 - Function: hash-table-rehash-threshold hash-table
3360 This function returns the current rehash threshold of HASH-TABLE.
3361 This is a float between 0.0 and 1.0; the maximum "load factor" of
3362 HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
3364 - Function: hash-table-weakness hash-table
3365 This function returns the weakness of HASH-TABLE. This can be one
3366 of `nil', `t', `key' or `value'.
3369 File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
3371 Working With Hash Tables
3372 ========================
3374 - Function: puthash key value hash-table
3375 This function hashes KEY to VALUE in HASH-TABLE.
3377 - Function: gethash key hash-table &optional default
3378 This function finds the hash value for KEY in HASH-TABLE. If
3379 there is no entry for KEY in HASH-TABLE, DEFAULT is returned
3380 (which in turn defaults to `nil').
3382 - Function: remhash key hash-table
3383 This function removes the entry for KEY from HASH-TABLE. Does
3384 nothing if there is no entry for KEY in HASH-TABLE.
3386 - Function: clrhash hash-table
3387 This function removes all entries from HASH-TABLE, leaving it
3390 - Function: maphash function hash-table
3391 This function maps FUNCTION over entries in HASH-TABLE, calling it
3392 with two args, each key and value in the hash table.
3394 FUNCTION may not modify HASH-TABLE, with the one exception that
3395 FUNCTION may remhash or puthash the entry currently being
3396 processed by FUNCTION.
3399 File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
3404 A "weak hash table" is a special variety of hash table whose elements
3405 do not count as GC referents. For any key-value pair in such a hash
3406 table, if either the key or value (or in some cases, if one particular
3407 one of the two) has no references to it outside of weak hash tables
3408 (and similar structures such as weak lists), the pair will be removed
3409 from the table, and the key and value collected. A non-weak hash table
3410 (or any other pointer) would prevent the objects from being collected.
3412 Weak hash tables are useful for keeping track of information in a
3413 non-obtrusive way, for example to implement caching. If the cache
3414 contains objects such as buffers, markers, image instances, etc. that
3415 will eventually disappear and get garbage-collected, using a weak hash
3416 table ensures that these objects are collected normally rather than
3417 remaining around forever, long past their actual period of use.
3418 (Otherwise, you'd have to explicitly map over the hash table every so
3419 often and remove unnecessary elements.)
3421 There are four types of weak hash tables:
3423 key-and-value-weak hash tables
3424 In these hash tables, also known as fully weak or simply as weak
3425 hash tables, a pair disappears if either the key or the value is
3426 unreferenced outside of the table.
3428 key-weak hash tables
3429 In these hash tables, a pair disappears if the key is unreferenced
3430 outside of the table, regardless of how the value is referenced.
3432 value-weak hash tables
3433 In these hash tables, a pair disappears if the value is
3434 unreferenced outside of the table, regardless of how the key is
3437 key-or-value-weak hash tables
3438 In these hash tables, a pair disappears if both the key and the
3439 value are unreferenced outside of the table.
3441 Also see *Note Weak Lists::.
3443 Weak hash tables are created by specifying the `:weakness' keyword to
3447 File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
3452 A range table is a table that efficiently associated values with ranges
3455 Note that range tables have a read syntax, like this:
3457 #s(range-table data ((-3 2) foo (5 20) bar))
3459 This maps integers in the range (-3, 2) to `foo' and integers in the
3460 range (5, 20) to `bar'.
3462 - Function: range-table-p object
3463 Return non-`nil' if OBJECT is a range table.
3467 * Introduction to Range Tables:: Range tables efficiently map ranges of
3469 * Working With Range Tables:: Range table functions.
3472 File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
3474 Introduction to Range Tables
3475 ============================
3477 - Function: make-range-table
3478 Make a new, empty range table.
3480 - Function: copy-range-table range-table
3481 This function returns a new range table which contains the same
3482 values for the same ranges as RANGE-TABLE. The values will not
3483 themselves be copied.
3486 File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
3488 Working With Range Tables
3489 =========================
3491 - Function: get-range-table pos range-table &optional default
3492 This function finds value for position POS in RANGE-TABLE. If
3493 there is no corresponding value, return DEFAULT (defaults to
3496 - Function: put-range-table start end value range-table
3497 This function sets the value for range (START, END) to be VALUE in
3500 - Function: remove-range-table start end range-table
3501 This function removes the value for range (START, END) in
3504 - Function: clear-range-table range-table
3505 This function flushes RANGE-TABLE.
3507 - Function: map-range-table function range-table
3508 This function maps FUNCTION over entries in RANGE-TABLE, calling
3509 it with three args, the beginning and end of the range and the
3510 corresponding value.
3513 File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
3518 - Function: databasep object
3519 This function returns non-`nil' if OBJECT is a database.
3523 * Connecting to a Database::
3524 * Working With a Database::
3525 * Other Database Functions::
3528 File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
3530 Connecting to a Database
3531 ========================
3533 - Function: open-database file &optional type subtype access mode
3534 This function opens database FILE, using database method TYPE and
3535 SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
3536 can be any combination of `r' `w' and `+', for read, write, and
3539 TYPE can have the value `'dbm' or `'berkeley-db' to select the
3540 type of database file to use. (Note: XEmacs may not support both
3543 For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
3546 For a TYPE of `'berkeley-db', the following subtypes are
3547 available: `'hash', `'btree', and `'recno'. See the manpages for
3548 the Berkeley DB functions for more information about these types.
3550 - Function: close-database database
3551 This function closes database DATABASE.
3553 - Function: database-live-p object
3554 This function returns `t' if OBJECT is an active database, else
3558 File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
3560 Working With a Database
3561 =======================
3563 - Function: get-database key database &optional default
3564 This function finds the value for KEY in DATABASE. If there is no
3565 corresponding value, DEFAULT is returned (`nil' if DEFAULT is
3568 - Function: map-database function database
3569 This function maps FUNCTION over entries in DATABASE, calling it
3570 with two args, each key and value in the database.
3572 - Function: put-database key value database &optional replace
3573 This function stores KEY and VALUE in DATABASE. If optional
3574 fourth arg REPLACE is non-`nil', replace any existing entry in the
3577 - Function: remove-database key database
3578 This function removes KEY from DATABASE.
3581 File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
3583 Other Database Functions
3584 ========================
3586 - Function: database-file-name database
3587 This function returns the filename associated with DATABASE.
3589 - Function: database-last-error &optional database
3590 This function returns the last error associated with DATABASE.
3592 - Function: database-subtype database
3593 This function returns the subtype of DATABASE, if any.
3595 - Function: database-type database
3596 This function returns the type of DATABASE.
3599 File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
3604 In the terminology of operating systems, a "process" is a space in
3605 which a program can execute. XEmacs runs in a process. XEmacs Lisp
3606 programs can invoke other programs in processes of their own. These are
3607 called "subprocesses" or "child processes" of the XEmacs process, which
3608 is their "parent process".
3610 A subprocess of XEmacs may be "synchronous" or "asynchronous",
3611 depending on how it is created. When you create a synchronous
3612 subprocess, the Lisp program waits for the subprocess to terminate
3613 before continuing execution. When you create an asynchronous
3614 subprocess, it can run in parallel with the Lisp program. This kind of
3615 subprocess is represented within XEmacs by a Lisp object which is also
3616 called a "process". Lisp programs can use this object to communicate
3617 with the subprocess or to control it. For example, you can send
3618 signals, obtain status information, receive output from the process, or
3621 - Function: processp object
3622 This function returns `t' if OBJECT is a process, `nil' otherwise.
3626 * Subprocess Creation:: Functions that start subprocesses.
3627 * Synchronous Processes:: Details of using synchronous subprocesses.
3628 * MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
3629 for data sent to and from a subprocess.
3630 * Asynchronous Processes:: Starting up an asynchronous subprocess.
3631 * Deleting Processes:: Eliminating an asynchronous subprocess.
3632 * Process Information:: Accessing run-status and other attributes.
3633 * Input to Processes:: Sending input to an asynchronous subprocess.
3634 * Signals to Processes:: Stopping, continuing or interrupting
3635 an asynchronous subprocess.
3636 * Output from Processes:: Collecting output from an asynchronous subprocess.
3637 * Sentinels:: Sentinels run when process run-status changes.
3638 * Process Window Size:: Changing the logical window size of a process.
3639 * Transaction Queues:: Transaction-based communication with subprocesses.
3640 * Network:: Opening network connections.
3643 File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
3645 Functions that Create Subprocesses
3646 ==================================
3648 There are three functions that create a new subprocess in which to run
3649 a program. One of them, `start-process', creates an asynchronous
3650 process and returns a process object (*note Asynchronous Processes::).
3651 The other two, `call-process' and `call-process-region', create a
3652 synchronous process and do not return a process object (*note
3653 Synchronous Processes::).
3655 Synchronous and asynchronous processes are explained in the following
3656 sections. Since the three functions are all called in a similar
3657 fashion, their common arguments are described here.
3659 In all cases, the function's PROGRAM argument specifies the program
3660 to be run. An error is signaled if the file is not found or cannot be
3661 executed. If the file name is relative, the variable `exec-path'
3662 contains a list of directories to search. Emacs initializes
3663 `exec-path' when it starts up, based on the value of the environment
3664 variable `PATH'. The standard file name constructs, `~', `.', and
3665 `..', are interpreted as usual in `exec-path', but environment variable
3666 substitutions (`$HOME', etc.) are not recognized; use
3667 `substitute-in-file-name' to perform them (*note File Name Expansion::).
3669 Each of the subprocess-creating functions has a BUFFER-OR-NAME
3670 argument which specifies where the standard output from the program will
3671 go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
3672 a filter function handles it. (*Note Filter Functions::, and *Note
3673 Read and Print::.) Normally, you should avoid having multiple
3674 processes send output to the same buffer because their output would be
3675 intermixed randomly.
3677 All three of the subprocess-creating functions have a `&rest'
3678 argument, ARGS. The ARGS must all be strings, and they are supplied to
3679 PROGRAM as separate command line arguments. Wildcard characters and
3680 other shell constructs are not allowed in these strings, since they are
3681 passed directly to the specified program.
3683 *Please note:* The argument PROGRAM contains only the name of the
3684 program; it may not contain any command-line arguments. You must use
3685 ARGS to provide those.
3687 If you want to use features of the shell, then invoke the shell
3688 directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
3691 The subprocess gets its current directory from the value of
3692 `default-directory' (*note File Name Expansion::).
3694 The subprocess inherits its environment from XEmacs; but you can
3695 specify overrides for it with `process-environment'. *Note System
3698 - Variable: exec-directory
3699 The value of this variable is the name of a directory (a string)
3700 that contains programs that come with XEmacs, that are intended
3701 for XEmacs to invoke. The program `wakeup' is an example of such
3702 a program; the `display-time' command uses it to get a reminder
3705 - User Option: exec-path
3706 The value of this variable is a list of directories to search for
3707 programs to run in subprocesses. Each element is either the name
3708 of a directory (i.e., a string), or `nil', which stands for the
3709 default directory (which is the value of `default-directory').
3711 The value of `exec-path' is used by `call-process' and
3712 `start-process' when the PROGRAM argument is not an absolute file
3716 File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
3718 Creating a Synchronous Process
3719 ==============================
3721 After a "synchronous process" is created, XEmacs waits for the process
3722 to terminate before continuing. Starting Dired is an example of this:
3723 it runs `ls' in a synchronous process, then modifies the output
3724 slightly. Because the process is synchronous, the entire directory
3725 listing arrives in the buffer before XEmacs tries to do anything with
3728 While Emacs waits for the synchronous subprocess to terminate, the
3729 user can quit by typing `C-g'. The first `C-g' tries to kill the
3730 subprocess with a `SIGINT' signal; but it waits until the subprocess
3731 actually terminates before quitting. If during that time the user
3732 types another `C-g', that kills the subprocess instantly with `SIGKILL'
3733 and quits immediately. *Note Quitting::.
3735 The synchronous subprocess functions returned `nil' in version 18.
3736 In version 19, they return an indication of how the process terminated.
3738 - Function: call-process program &optional infile destination display
3740 This function calls PROGRAM in a separate process and waits for it
3743 The standard input for the process comes from file INFILE if
3744 INFILE is not `nil' and from `/dev/null' otherwise. The argument
3745 DESTINATION says where to put the process output. Here are the
3749 Insert the output in that buffer, before point. This
3750 includes both the standard output stream and the standard
3751 error stream of the process.
3754 Find or create a buffer with that name, then insert the
3755 output in that buffer, before point.
3758 Insert the output in the current buffer, before point.
3764 Discard the output, and return immediately without waiting
3765 for the subprocess to finish.
3767 In this case, the process is not truly synchronous, since it
3768 can run in parallel with Emacs; but you can think of it as
3769 synchronous in that Emacs is essentially finished with the
3770 subprocess as soon as this function returns.
3772 (REAL-DESTINATION ERROR-DESTINATION)
3773 Keep the standard output stream separate from the standard
3774 error stream; deal with the ordinary output as specified by
3775 REAL-DESTINATION, and dispose of the error output according
3776 to ERROR-DESTINATION. The value `nil' means discard it, `t'
3777 means mix it with the ordinary output, and a string specifies
3778 a file name to redirect error output into.
3780 You can't directly specify a buffer to put the error output
3781 in; that is too difficult to implement. But you can achieve
3782 this result by sending the error output to a temporary file
3783 and then inserting the file into a buffer.
3785 If DISPLAY is non-`nil', then `call-process' redisplays the buffer
3786 as output is inserted. Otherwise the function does no redisplay,
3787 and the results become visible on the screen only when XEmacs
3788 redisplays that buffer in the normal course of events.
3790 The remaining arguments, ARGS, are strings that specify command
3791 line arguments for the program.
3793 The value returned by `call-process' (unless you told it not to
3794 wait) indicates the reason for process termination. A number
3795 gives the exit status of the subprocess; 0 means success, and any
3796 other value means failure. If the process terminated with a
3797 signal, `call-process' returns a string describing the signal.
3799 In the examples below, the buffer `foo' is current.
3801 (call-process "pwd" nil t)
3804 ---------- Buffer: foo ----------
3805 /usr/user/lewis/manual
3806 ---------- Buffer: foo ----------
3808 (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
3811 ---------- Buffer: bar ----------
3812 lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
3814 ---------- Buffer: bar ----------
3816 The `insert-directory' function contains a good example of the use
3819 (call-process insert-directory-program nil t nil switches
3820 (if full-directory-p
3821 (concat (file-name-as-directory file) ".")
3824 - Function: call-process-region start end program &optional deletep
3825 destination displayp &rest args
3826 This function sends the text between START to END as standard
3827 input to a process running PROGRAM. It deletes the text sent if
3828 DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
3829 the output in the current buffer.
3831 The arguments DESTINATION and DISPLAYP control what to do with the
3832 output from the subprocess, and whether to update the display as
3833 it comes in. For details, see the description of `call-process',
3834 above. If DESTINATION is the integer 0, `call-process-region'
3835 discards the output and returns `nil' immediately, without waiting
3836 for the subprocess to finish.
3838 The remaining arguments, ARGS, are strings that specify command
3839 line arguments for the program.
3841 The return value of `call-process-region' is just like that of
3842 `call-process': `nil' if you told it to return without waiting;
3843 otherwise, a number or string which indicates how the subprocess
3846 In the following example, we use `call-process-region' to run the
3847 `cat' utility, with standard input being the first five characters
3848 in buffer `foo' (the word `input'). `cat' copies its standard
3849 input into its standard output. Since the argument DESTINATION is
3850 `t', this output is inserted in the current buffer.
3852 ---------- Buffer: foo ----------
3854 ---------- Buffer: foo ----------
3856 (call-process-region 1 6 "cat" nil t)
3859 ---------- Buffer: foo ----------
3861 ---------- Buffer: foo ----------
3863 The `shell-command-on-region' command uses `call-process-region'
3866 (call-process-region
3868 shell-file-name ; Name of program.
3869 nil ; Do not delete region.
3870 buffer ; Send output to `buffer'.
3871 nil ; No redisplay during output.
3872 "-c" command) ; Arguments for the shell.
3875 File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
3880 On MS-DOS, you must indicate whether the data going to and from a
3881 synchronous subprocess are text or binary. Text data requires
3882 translation between the end-of-line convention used within Emacs (a
3883 single newline character) and the convention used outside Emacs (the
3884 two-character sequence, CRLF).
3886 The variable `binary-process-input' applies to input sent to the
3887 subprocess, and `binary-process-output' applies to output received from
3888 it. A non-`nil' value means the data is non-text; `nil' means the data
3889 is text, and calls for conversion.
3891 - Variable: binary-process-input
3892 If this variable is `nil', convert newlines to CRLF sequences in
3893 the input to a synchronous subprocess.
3895 - Variable: binary-process-output
3896 If this variable is `nil', convert CRLF sequences to newlines in
3897 the output from a synchronous subprocess.
3899 *Note Files and MS-DOS::, for related information.
3902 File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
3904 Creating an Asynchronous Process
3905 ================================
3907 After an "asynchronous process" is created, Emacs and the Lisp program
3908 both continue running immediately. The process may thereafter run in
3909 parallel with Emacs, and the two may communicate with each other using
3910 the functions described in following sections. Here we describe how to
3911 create an asynchronous process with `start-process'.
3913 - Function: start-process name buffer-or-name program &rest args
3914 This function creates a new asynchronous subprocess and starts the
3915 program PROGRAM running in it. It returns a process object that
3916 stands for the new subprocess in Lisp. The argument NAME
3917 specifies the name for the process object; if a process with this
3918 name already exists, then NAME is modified (by adding `<1>', etc.)
3919 to be unique. The buffer BUFFER-OR-NAME is the buffer to
3920 associate with the process.
3922 The remaining arguments, ARGS, are strings that specify command
3923 line arguments for the program.
3925 In the example below, the first process is started and runs
3926 (rather, sleeps) for 100 seconds. Meanwhile, the second process
3927 is started, and given the name `my-process<1>' for the sake of
3928 uniqueness. It inserts the directory listing at the end of the
3929 buffer `foo', before the first process finishes. Then it
3930 finishes, and a message to that effect is inserted in the buffer.
3931 Much later, the first process finishes, and another message is
3932 inserted in the buffer for it.
3934 (start-process "my-process" "foo" "sleep" "100")
3935 => #<process my-process>
3937 (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
3938 => #<process my-process<1>>
3940 ---------- Buffer: foo ----------
3942 lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
3943 -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
3945 Process my-process<1> finished
3947 Process my-process finished
3948 ---------- Buffer: foo ----------
3950 - Function: start-process-shell-command name buffer-or-name command
3952 This function is like `start-process' except that it uses a shell
3953 to execute the specified command. The argument COMMAND is a shell
3954 command name, and COMMAND-ARGS are the arguments for the shell
3957 - Variable: process-connection-type
3958 This variable controls the type of device used to communicate with
3959 asynchronous subprocesses. If it is non-`nil', then PTYs are
3960 used, when available. Otherwise, pipes are used.
3962 PTYs are usually preferable for processes visible to the user, as
3963 in Shell mode, because they allow job control (`C-c', `C-z', etc.)
3964 to work between the process and its children whereas pipes do not.
3965 For subprocesses used for internal purposes by programs, it is
3966 often better to use a pipe, because they are more efficient. In
3967 addition, the total number of PTYs is limited on many systems and
3968 it is good not to waste them. A rule of thumb is to use ptys for
3969 processes the user interacts with directly, and pipes for
3970 processes that are hidden from the user.
3972 The value `process-connection-type' is used when `start-process'
3973 is called. So you can specify how to communicate with one
3974 subprocess by binding the variable around the call to
3977 (let ((process-connection-type nil)) ; Use a pipe.
3978 (start-process ...))
3980 To determine whether a given subprocess actually got a pipe or a
3981 PTY, use the function `process-tty-name' (*note Process
3984 Lisp functions that manipulate processes usually accept a PROCESS
3985 argument. Besides using an actual process object for this argument, you
3986 can use a process name, a buffer object, the name of a buffer, or
3987 `nil'. Specifying a buffer or buffer name for the PROCESS argument
3988 means use the process associated with the buffer (or the most recent
3989 one, if there is more than one). `nil' means use the process
3990 associated with the current buffer. *Note Process Information::.
3991 *Note Process Buffers::.
3994 File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
3999 "Deleting a process" disconnects XEmacs immediately from the
4000 subprocess, and removes it from the list of active processes. It sends
4001 a signal to the subprocess to make the subprocess terminate, but this is
4002 not guaranteed to happen immediately. The process object itself
4003 continues to exist as long as other Lisp objects point to it.
4005 You can delete a process explicitly at any time. Processes are
4006 deleted automatically after they terminate, but not necessarily right
4007 away. If you delete a terminated process explicitly before it is
4008 deleted automatically, no harm results.
4010 - Variable: delete-exited-processes
4011 This variable controls automatic deletion of processes that have
4012 terminated (due to calling `exit' or to a signal). If it is
4013 `nil', then they continue to exist until the user runs
4014 `list-processes'. Otherwise, they are deleted immediately after
4017 - Function: delete-process name
4018 This function deletes the process associated with NAME, killing it
4019 with a `SIGHUP' signal. The argument NAME may be a process, the
4020 name of a process, a buffer, or the name of a buffer.
4022 (delete-process "*shell*")
4025 - Function: process-kill-without-query process &optional
4027 This function declares that XEmacs need not query the user if
4028 PROCESS is still running when XEmacs is exited. The process will
4029 be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
4030 _will_ query the user (this is the default). The return value is
4031 `t' if a query was formerly required, and `nil' otherwise.
4033 (process-kill-without-query (get-process "shell"))
4037 File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
4042 Several functions return information about processes. `list-processes'
4043 is provided for interactive use.
4045 - Command: list-processes
4046 This command displays a listing of all living processes. In
4047 addition, it finally deletes any process whose status was `Exited'
4048 or `Signaled'. It returns `nil'.
4050 - Function: process-list
4051 This function returns a list of all processes that have not been
4055 => (#<process display-time> #<process shell>)
4057 - Function: get-process process-name
4058 This function returns the process named PROCESS-NAME. If
4059 PROCESS-NAME is a string and there is no process with that name,
4060 the value is `nil'. If PROCESS-NAME is actually a process, it is
4061 returned as given. (That is not very useful, so the argument is
4062 usually a name.) For example:
4064 (get-process "shell")
4067 - Function: process-command process
4068 This function returns the command that was executed to start
4069 PROCESS. This is a list of strings, the first string being the
4070 program executed and the rest of the strings being the arguments
4071 that were given to the program.
4073 (process-command (get-process "shell"))
4074 => ("/bin/csh" "-i")
4076 - Function: process-id process
4077 This function returns the PID of PROCESS. This is an integer that
4078 distinguishes the process PROCESS from all other processes running
4079 on the same computer at the current time. The PID of a process is
4080 chosen by the operating system kernel when the process is started
4081 and remains constant as long as the process exists.
4083 - Function: process-name process
4084 This function returns the name of PROCESS.
4086 - Function: process-status process
4087 This function returns the status of PROCESS as a symbol. The
4088 argument PROCESS must be a process, a buffer, a process name
4089 (string) or a buffer name (string).
4091 The possible values for an actual subprocess are:
4094 for a process that is running.
4097 for a process that is stopped but continuable.
4100 for a process that has exited.
4103 for a process that has received a fatal signal.
4106 for a network connection that is open.
4109 for a network connection that is closed. Once a connection
4110 is closed, you cannot reopen it, though you might be able to
4111 open a new connection to the same place.
4114 if PROCESS does not identify an existing process.
4116 (process-status "shell")
4118 (process-status (get-buffer "*shell*"))
4125 For a network connection, `process-status' returns one of the
4126 symbols `open' or `closed'. The latter means that the other side
4127 closed the connection, or XEmacs did `delete-process'.
4129 In earlier Emacs versions (prior to version 19), the status of a
4130 network connection was `run' if open, and `exit' if closed.
4132 - Function: process-kill-without-query-p process
4133 This function returns whether PROCESS will be killed without
4134 querying the user, if it is running when XEmacs is exited. The
4135 default value is `nil'.
4137 - Function: process-exit-status process
4138 This function returns the exit status of PROCESS or the signal
4139 number that killed it. (Use the result of `process-status' to
4140 determine which of those it is.) If PROCESS has not yet
4141 terminated, the value is 0.
4143 - Function: process-tty-name process
4144 This function returns the terminal name that PROCESS is using for
4145 its communication with Emacs--or `nil' if it is using pipes
4146 instead of a terminal (see `process-connection-type' in *Note
4147 Asynchronous Processes::).
4150 File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
4152 Sending Input to Processes
4153 ==========================
4155 Asynchronous subprocesses receive input when it is sent to them by
4156 XEmacs, which is done with the functions in this section. You must
4157 specify the process to send input to, and the input data to send. The
4158 data appears on the "standard input" of the subprocess.
4160 Some operating systems have limited space for buffered input in a
4161 PTY. On these systems, XEmacs sends long input in chunks, with EOF
4162 characters added amidst the other characters, to force the operating
4163 system to periodically drain the input buffer. For most programs,
4164 these EOFs do no harm.
4166 - Function: process-send-string process string &optional start end
4167 This function sends PROCESS the contents of STRING as standard
4170 The argument PROCESS may be a process or the name of a process, or
4171 a buffer or the name of a buffer, in which case the buffer's
4172 process is used. If it is `nil', the current buffer's process is
4175 Optional arguments START and END specify part of STRING; see
4178 The function returns `nil'.
4180 (process-send-string "shell<1>" "ls\n")
4184 ---------- Buffer: *shell* ----------
4186 introduction.texi syntax-tables.texi~
4187 introduction.texi~ text.texi
4188 introduction.txt text.texi~
4190 ---------- Buffer: *shell* ----------
4192 - Function: process-send-region process start end &optional buffer
4193 This function sends the text in the region defined by START and
4194 END as standard input to PROCESS.
4196 The argument PROCESS may be a process or the name of a process, or
4197 a buffer or the name of a buffer, in which case the buffer's
4198 process is used. If it is `nil', the current buffer's process is
4201 An error is signaled unless both START and END are integers or
4202 markers that indicate positions in the current buffer. (It is
4203 unimportant which number is larger.)
4205 - Function: process-send-eof &optional process
4206 This function makes PROCESS see an end-of-file in its input. The
4207 EOF comes after any text already sent to it.
4209 PROCESS may be a process, a buffer, the name of a process or
4210 buffer, or `nil', indicating the current buffer's process. An
4211 error is signaled if PROCESS does not identify any process.
4213 The function returns the process object identified by PROCESS.
4215 (process-send-eof "shell")
4219 File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
4221 Sending Signals to Processes
4222 ============================
4224 "Sending a signal" to a subprocess is a way of interrupting its
4225 activities. There are several different signals, each with its own
4226 meaning. The set of signals and their names is defined by the operating
4227 system. For example, the signal `SIGINT' means that the user has typed
4228 `C-c', or that some analogous thing has happened.
4230 Each signal has a standard effect on the subprocess. Most signals
4231 kill the subprocess, but some stop or resume execution instead. Most
4232 signals can optionally be handled by programs; if the program handles
4233 the signal, then we can say nothing in general about its effects.
4235 The set of signals and their names is defined by the operating
4236 system; XEmacs has facilities for sending only a few of the signals
4237 that are defined. XEmacs can send signals only to its own subprocesses.
4239 You can send signals explicitly by calling the functions in this
4240 section. XEmacs also sends signals automatically at certain times:
4241 killing a buffer sends a `SIGHUP' signal to all its associated
4242 processes; killing XEmacs sends a `SIGHUP' signal to all remaining
4243 processes. (`SIGHUP' is a signal that indicates that the connection
4244 between the user and the process is broken, for example if a connection
4245 via a telephone line is hung up.)
4247 Each of the signal-sending functions takes two optional arguments:
4248 PROCESS and CURRENT-GROUP.
4250 The argument PROCESS must be either a process or a buffer, the name
4251 of one, or `nil'. If it is `nil', the process defaults to the process
4252 associated with the current buffer. An error is signaled if PROCESS
4253 does not identify a process.
4255 The argument CURRENT-GROUP is a flag that makes a difference when
4256 you are running a job-control shell as an XEmacs subprocess. If it is
4257 non-`nil', then the signal is sent to the current foreground process
4258 group of the terminal that XEmacs uses to communicate with the
4259 subprocess. If the process is a job-control shell, this means the
4260 shell's current subjob. If it is `nil', the signal is sent to the
4261 process group of the immediate subprocess of XEmacs. If the subprocess
4262 is a job-control shell, this is the shell itself.
4264 The flag CURRENT-GROUP has no effect when a pipe is used to
4265 communicate with the subprocess, because the operating system does not
4266 support the distinction in the case of pipes. For the same reason,
4267 job-control shells won't work when a pipe is used. See
4268 `process-connection-type' in *Note Asynchronous Processes::.
4270 Some of the functions below take a SIGNAL argument, which identifies
4271 a signal to be sent. It must be either an integer or a symbol which
4272 names the signal, like `SIGSEGV'.
4274 - Function: process-send-signal signal &optional process current-group
4275 This function sends the signal SIGNAL to the process PROCESS. The
4276 following functions can be implemented in terms of
4277 `process-send-signal'.
4279 - Function: interrupt-process &optional process current-group
4280 This function interrupts the process PROCESS by sending the signal
4281 `SIGINT'. Outside of XEmacs, typing the "interrupt character"
4282 (normally `C-c') sends this signal. When the argument
4283 CURRENT-GROUP is non-`nil', you can think of this function as
4284 "typing `C-c'" on the terminal by which XEmacs talks to the
4287 - Function: kill-process &optional process current-group
4288 This function kills the process PROCESS by sending the signal
4289 `SIGKILL'. This signal kills the subprocess immediately, and
4290 cannot be handled by the subprocess.
4292 - Function: quit-process &optional process current-group
4293 This function sends the signal `SIGQUIT' to the process PROCESS.
4294 This signal is the one sent by the "quit character" (usually
4295 `C-\') when you are not inside XEmacs.
4297 - Function: stop-process &optional process current-group
4298 This function stops the process PROCESS by sending the signal
4299 `SIGTSTP'. Use `continue-process' to resume its execution.
4301 On systems with job control, the "stop character" (usually `C-z')
4302 sends this signal (outside of XEmacs). When CURRENT-GROUP is
4303 non-`nil', you can think of this function as "typing `C-z'" on the
4304 terminal XEmacs uses to communicate with the subprocess.
4306 - Function: continue-process &optional process current-group
4307 This function resumes execution of the process PROCESS by sending
4308 it the signal `SIGCONT'. This presumes that PROCESS was stopped
4311 - Command: signal-process pid signal
4312 This function sends a signal to the process with process id PID,
4313 which need not be a child of XEmacs. The argument SIGNAL
4314 specifies which signal to send.
4317 File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
4319 Receiving Output from Processes
4320 ===============================
4322 There are two ways to receive the output that a subprocess writes to
4323 its standard output stream. The output can be inserted in a buffer,
4324 which is called the associated buffer of the process, or a function
4325 called the "filter function" can be called to act on the output. If
4326 the process has no buffer and no filter function, its output is
4331 * Process Buffers:: If no filter, output is put in a buffer.
4332 * Filter Functions:: Filter functions accept output from the process.
4333 * Accepting Output:: Explicitly permitting subprocess output.
4334 Waiting for subprocess output.
4337 File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
4342 A process can (and usually does) have an "associated buffer", which is
4343 an ordinary Emacs buffer that is used for two purposes: storing the
4344 output from the process, and deciding when to kill the process. You
4345 can also use the buffer to identify a process to operate on, since in
4346 normal practice only one process is associated with any given buffer.
4347 Many applications of processes also use the buffer for editing input to
4348 be sent to the process, but this is not built into XEmacs Lisp.
4350 Unless the process has a filter function (*note Filter Functions::),
4351 its output is inserted in the associated buffer. The position to insert
4352 the output is determined by the `process-mark', which is then updated
4353 to point to the end of the text just inserted. Usually, but not
4354 always, the `process-mark' is at the end of the buffer.
4356 - Function: process-buffer process
4357 This function returns the associated buffer of the process PROCESS.
4359 (process-buffer (get-process "shell"))
4360 => #<buffer *shell*>
4362 - Function: process-mark process
4363 This function returns the process marker for PROCESS, which is the
4364 marker that says where to insert output from the process.
4366 If PROCESS does not have a buffer, `process-mark' returns a marker
4367 that points nowhere.
4369 Insertion of process output in a buffer uses this marker to decide
4370 where to insert, and updates it to point after the inserted text.
4371 That is why successive batches of output are inserted
4374 Filter functions normally should use this marker in the same
4375 fashion as is done by direct insertion of output in the buffer. A
4376 good example of a filter function that uses `process-mark' is
4377 found at the end of the following section.
4379 When the user is expected to enter input in the process buffer for
4380 transmission to the process, the process marker is useful for
4381 distinguishing the new input from previous output.
4383 - Function: set-process-buffer process buffer
4384 This function sets the buffer associated with PROCESS to BUFFER.
4385 If BUFFER is `nil', the process becomes associated with no buffer.
4387 - Function: get-buffer-process buffer-or-name
4388 This function returns the process associated with BUFFER-OR-NAME.
4389 If there are several processes associated with BUFFER-OR-NAME,
4390 then one is chosen. (Presently, the one chosen is the one most
4391 recently created.) It is usually a bad idea to have more than one
4392 process associated with the same buffer.
4394 (get-buffer-process "*shell*")
4397 Killing the process's buffer deletes the process, which kills the
4398 subprocess with a `SIGHUP' signal (*note Signals to Processes::).
4401 File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
4403 Process Filter Functions
4404 ------------------------
4406 A process "filter function" is a function that receives the standard
4407 output from the associated process. If a process has a filter, then
4408 _all_ output from that process is passed to the filter. The process
4409 buffer is used directly for output from the process only when there is
4412 A filter function must accept two arguments: the associated process
4413 and a string, which is the output. The function is then free to do
4414 whatever it chooses with the output.
4416 A filter function runs only while XEmacs is waiting (e.g., for
4417 terminal input, or for time to elapse, or for process output). This
4418 avoids the timing errors that could result from running filters at
4419 random places in the middle of other Lisp programs. You may explicitly
4420 cause Emacs to wait, so that filter functions will run, by calling
4421 `sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
4422 (*note Accepting Output::). Emacs is also waiting when the command loop
4425 Quitting is normally inhibited within a filter function--otherwise,
4426 the effect of typing `C-g' at command level or to quit a user command
4427 would be unpredictable. If you want to permit quitting inside a filter
4428 function, bind `inhibit-quit' to `nil'. *Note Quitting::.
4430 If an error happens during execution of a filter function, it is
4431 caught automatically, so that it doesn't stop the execution of whatever
4432 program was running when the filter function was started. However, if
4433 `debug-on-error' is non-`nil', the error-catching is turned off. This
4434 makes it possible to use the Lisp debugger to debug the filter
4435 function. *Note Debugger::.
4437 Many filter functions sometimes or always insert the text in the
4438 process's buffer, mimicking the actions of XEmacs when there is no
4439 filter. Such filter functions need to use `set-buffer' in order to be
4440 sure to insert in that buffer. To avoid setting the current buffer
4441 semipermanently, these filter functions must use `unwind-protect' to
4442 make sure to restore the previous current buffer. They should also
4443 update the process marker, and in some cases update the value of point.
4444 Here is how to do these things:
4446 (defun ordinary-insertion-filter (process string)
4447 (let ((old-buffer (current-buffer)))
4450 (set-buffer (process-buffer process))
4451 (setq moving (= (point) (process-mark process)))
4453 ;; Insert the text, moving the process-marker.
4454 (goto-char (process-mark process))
4456 (set-marker (process-mark process) (point)))
4457 (if moving (goto-char (process-mark process))))
4458 (set-buffer old-buffer))))
4460 The reason to use an explicit `unwind-protect' rather than letting
4461 `save-excursion' restore the current buffer is so as to preserve the
4462 change in point made by `goto-char'.
4464 To make the filter force the process buffer to be visible whenever
4465 new text arrives, insert the following line just before the
4468 (display-buffer (process-buffer process))
4470 To force point to move to the end of the new output no matter where
4471 it was previously, eliminate the variable `moving' and call `goto-char'
4474 In earlier Emacs versions, every filter function that did regexp
4475 searching or matching had to explicitly save and restore the match data.
4476 Now Emacs does this automatically; filter functions never need to do it
4477 explicitly. *Note Match Data::.
4479 A filter function that writes the output into the buffer of the
4480 process should check whether the buffer is still alive. If it tries to
4481 insert into a dead buffer, it will get an error. If the buffer is dead,
4482 `(buffer-name (process-buffer PROCESS))' returns `nil'.
4484 The output to the function may come in chunks of any size. A program
4485 that produces the same output twice in a row may send it as one batch
4486 of 200 characters one time, and five batches of 40 characters the next.
4488 - Function: set-process-filter process filter
4489 This function gives PROCESS the filter function FILTER. If FILTER
4490 is `nil', then the process will have no filter. If FILTER is `t',
4491 then no output from the process will be accepted until the filter
4492 is changed. (Output received during this time is not discarded,
4493 but is queued, and will be processed as soon as the filter is
4496 - Function: process-filter process
4497 This function returns the filter function of PROCESS, or `nil' if
4498 it has none. `t' means that output processing has been stopped.
4500 Here is an example of use of a filter function:
4502 (defun keep-output (process output)
4503 (setq kept (cons output kept)))
4507 (set-process-filter (get-process "shell") 'keep-output)
4509 (process-send-string "shell" "ls ~/other\n")
4512 => ("lewis@slug[8] % "
4513 "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
4514 address.txt backup.psf kolstad.psf
4515 backup.bib~ david.mss resume-Dec-86.mss~
4516 backup.err david.psf resume-Dec.psf
4517 backup.mss dland syllabus.mss
4519 "#backups.mss# backup.mss~ kolstad.mss
4523 File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
4525 Accepting Output from Processes
4526 -------------------------------
4528 Output from asynchronous subprocesses normally arrives only while
4529 XEmacs is waiting for some sort of external event, such as elapsed time
4530 or terminal input. Occasionally it is useful in a Lisp program to
4531 explicitly permit output to arrive at a specific point, or even to wait
4532 until output arrives from a process.
4534 - Function: accept-process-output &optional process seconds millisec
4535 This function allows XEmacs to read pending output from processes.
4536 The output is inserted in the associated buffers or given to
4537 their filter functions. If PROCESS is non-`nil' then this
4538 function does not return until some output has been received from
4541 The arguments SECONDS and MILLISEC let you specify timeout
4542 periods. The former specifies a period measured in seconds and the
4543 latter specifies one measured in milliseconds. The two time
4544 periods thus specified are added together, and
4545 `accept-process-output' returns after that much time whether or
4546 not there has been any subprocess output. Note that SECONDS is
4547 allowed to be a floating-point number; thus, there is no need to
4548 ever use MILLISEC. (It is retained for compatibility purposes.)
4550 The function `accept-process-output' returns non-`nil' if it did
4551 get some output, or `nil' if the timeout expired before output
4555 File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
4557 Sentinels: Detecting Process Status Changes
4558 ===========================================
4560 A "process sentinel" is a function that is called whenever the
4561 associated process changes status for any reason, including signals
4562 (whether sent by XEmacs or caused by the process's own actions) that
4563 terminate, stop, or continue the process. The process sentinel is also
4564 called if the process exits. The sentinel receives two arguments: the
4565 process for which the event occurred, and a string describing the type
4568 The string describing the event looks like one of the following:
4572 * `"exited abnormally with code EXITCODE\n"'.
4574 * `"NAME-OF-SIGNAL\n"'.
4576 * `"NAME-OF-SIGNAL (core dumped)\n"'.
4578 A sentinel runs only while XEmacs is waiting (e.g., for terminal
4579 input, or for time to elapse, or for process output). This avoids the
4580 timing errors that could result from running them at random places in
4581 the middle of other Lisp programs. A program can wait, so that
4582 sentinels will run, by calling `sit-for' or `sleep-for' (*note
4583 Waiting::), or `accept-process-output' (*note Accepting Output::).
4584 Emacs is also waiting when the command loop is reading input.
4586 Quitting is normally inhibited within a sentinel--otherwise, the
4587 effect of typing `C-g' at command level or to quit a user command would
4588 be unpredictable. If you want to permit quitting inside a sentinel,
4589 bind `inhibit-quit' to `nil'. *Note Quitting::.
4591 A sentinel that writes the output into the buffer of the process
4592 should check whether the buffer is still alive. If it tries to insert
4593 into a dead buffer, it will get an error. If the buffer is dead,
4594 `(buffer-name (process-buffer PROCESS))' returns `nil'.
4596 If an error happens during execution of a sentinel, it is caught
4597 automatically, so that it doesn't stop the execution of whatever
4598 programs was running when the sentinel was started. However, if
4599 `debug-on-error' is non-`nil', the error-catching is turned off. This
4600 makes it possible to use the Lisp debugger to debug the sentinel.
4603 In earlier Emacs versions, every sentinel that did regexp searching
4604 or matching had to explicitly save and restore the match data. Now
4605 Emacs does this automatically; sentinels never need to do it explicitly.
4608 - Function: set-process-sentinel process sentinel
4609 This function associates SENTINEL with PROCESS. If SENTINEL is
4610 `nil', then the process will have no sentinel. The default
4611 behavior when there is no sentinel is to insert a message in the
4612 process's buffer when the process status changes.
4614 (defun msg-me (process event)
4616 (format "Process: %s had the event `%s'" process event)))
4617 (set-process-sentinel (get-process "shell") 'msg-me)
4619 (kill-process (get-process "shell"))
4620 -| Process: #<process shell> had the event `killed'
4623 - Function: process-sentinel process
4624 This function returns the sentinel of PROCESS, or `nil' if it has
4627 - Function: waiting-for-user-input-p
4628 While a sentinel or filter function is running, this function
4629 returns non-`nil' if XEmacs was waiting for keyboard input from
4630 the user at the time the sentinel or filter function was called,
4631 `nil' if it was not.
4634 File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
4639 - Function: set-process-window-size process height width
4640 This function tells PROCESS that its logical window size is HEIGHT
4641 by WIDTH characters. This is principally useful with pty's.
4644 File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
4649 You can use a "transaction queue" for more convenient communication
4650 with subprocesses using transactions. First use `tq-create' to create
4651 a transaction queue communicating with a specified process. Then you
4652 can call `tq-enqueue' to send a transaction.
4654 - Function: tq-create process
4655 This function creates and returns a transaction queue
4656 communicating with PROCESS. The argument PROCESS should be a
4657 subprocess capable of sending and receiving streams of bytes. It
4658 may be a child process, or it may be a TCP connection to a server,
4659 possibly on another machine.
4661 - Function: tq-enqueue queue question regexp closure fn
4662 This function sends a transaction to queue QUEUE. Specifying the
4663 queue has the effect of specifying the subprocess to talk to.
4665 The argument QUESTION is the outgoing message that starts the
4666 transaction. The argument FN is the function to call when the
4667 corresponding answer comes back; it is called with two arguments:
4668 CLOSURE, and the answer received.
4670 The argument REGEXP is a regular expression that should match the
4671 entire answer, but nothing less; that's how `tq-enqueue' determines
4672 where the answer ends.
4674 The return value of `tq-enqueue' itself is not meaningful.
4676 - Function: tq-close queue
4677 Shut down transaction queue QUEUE, waiting for all pending
4678 transactions to complete, and then terminate the connection or
4681 Transaction queues are implemented by means of a filter function.
4682 *Note Filter Functions::.
4685 File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
4690 XEmacs Lisp programs can open TCP network connections to other
4691 processes on the same machine or other machines. A network connection
4692 is handled by Lisp much like a subprocess, and is represented by a
4693 process object. However, the process you are communicating with is not
4694 a child of the XEmacs process, so you can't kill it or send it signals.
4695 All you can do is send and receive data. `delete-process' closes the
4696 connection, but does not kill the process at the other end; that
4697 process must decide what to do about closure of the connection.
4699 You can distinguish process objects representing network connections
4700 from those representing subprocesses with the `process-status'
4701 function. It always returns either `open' or `closed' for a network
4702 connection, and it never returns either of those values for a real
4703 subprocess. *Note Process Information::.
4705 - Function: open-network-stream name buffer-or-name host service
4707 This function opens a TCP connection for a service to a host. It
4708 returns a process object to represent the connection.
4710 Input and output work as for other process objects.
4711 `delete-process' closes the connection.
4713 The NAME argument specifies the name for the process object. It
4714 is modified as necessary to make it unique.
4716 The BUFFER-OR-NAME argument is the buffer to associate with the
4717 connection. It can be a buffer or the name of one. Output from
4718 the connection is inserted in the buffer, unless you specify a
4719 filter function to handle the output. If BUFFER-OR-NAME is `nil',
4720 it means that the connection is not associated with any buffer.
4722 The arguments HOST and SERVICE specify where to connect to; HOST
4723 is the host name or IP address (a string), and SERVICE is the name
4724 of a defined network service (a string) or a port number (an
4727 Optional fifth arg PROTOCOL is the network protocol to use.
4728 Currently only `tcp' (Transmission Control Protocol) and `udp'
4729 (User Datagram Protocol) are supported. When omitted, `tcp' is
4732 Output via `process-send-string' and input via buffer or filter
4733 (see `set-process-filter') are stream-oriented. That means UDP
4734 datagrams are not guaranteed to be sent and received in discrete
4735 packets. (But small datagrams around 500 bytes that are not
4736 truncated by `process-send-string' are usually fine.) Note further
4737 that the UDP protocol does not guard against lost packets.
4740 File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
4742 Operating System Interface
4743 **************************
4745 This chapter is about starting and getting out of Emacs, access to
4746 values in the operating system environment, and terminal input, output,
4749 *Note Building XEmacs::, for related information. See also *Note
4750 Display::, for additional operating system status information
4751 pertaining to the terminal and the screen.
4755 * Starting Up:: Customizing XEmacs start-up processing.
4756 * Getting Out:: How exiting works (permanent or temporary).
4757 * System Environment:: Distinguish the name and kind of system.
4758 * User Identification:: Finding the name and user id of the user.
4759 * Time of Day:: Getting the current time.
4760 * Time Conversion:: Converting a time from numeric form to a string, or
4761 to calendrical data (or vice versa).
4762 * Timers:: Setting a timer to call a function at a certain time.
4763 * Terminal Input:: Recording terminal input for debugging.
4764 * Terminal Output:: Recording terminal output for debugging.
4765 * Flow Control:: How to turn output flow control on or off.
4766 * Batch Mode:: Running XEmacs without terminal interaction.
4769 File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
4774 This section describes what XEmacs does when it is started, and how you
4775 can customize these actions.
4779 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
4780 * Init File:: Details on reading the init file (`.emacs').
4781 * Terminal-Specific:: How the terminal-specific Lisp file is read.
4782 * Command Line Arguments:: How command line arguments are processed,
4783 and how you can customize them.
4786 File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
4788 Summary: Sequence of Actions at Start Up
4789 ----------------------------------------
4791 The order of operations performed (in `startup.el') by XEmacs when it
4792 is started up is as follows:
4794 1. It loads the initialization library for the window system, if you
4795 are using a window system. This library's name is
4796 `term/WINDOWSYSTEM-win.el'.
4798 2. It processes the initial options. (Some of them are handled even
4801 3. It initializes the X window frame and faces, if appropriate.
4803 4. It runs the normal hook `before-init-hook'.
4805 5. It loads the library `site-start', unless the option
4806 `-no-site-file' was specified. The library's file name is usually
4809 6. It loads the file `~/.emacs' unless `-q' was specified on the
4810 command line. (This is not done in `-batch' mode.) The `-u'
4811 option can specify the user name whose home directory should be
4812 used instead of `~'.
4814 7. It loads the library `default' unless `inhibit-default-init' is
4815 non-`nil'. (This is not done in `-batch' mode or if `-q' was
4816 specified on the command line.) The library's file name is
4817 usually `default.el'.
4819 8. It runs the normal hook `after-init-hook'.
4821 9. It sets the major mode according to `initial-major-mode', provided
4822 the buffer `*scratch*' is still current and still in Fundamental
4825 10. It loads the terminal-specific Lisp file, if any, except when in
4826 batch mode or using a window system.
4828 11. It displays the initial echo area message, unless you have
4829 suppressed that with `inhibit-startup-echo-area-message'.
4831 12. It processes the action arguments from the command line.
4833 13. It runs `term-setup-hook'.
4835 14. It calls `frame-notice-user-settings', which modifies the
4836 parameters of the selected frame according to whatever the init
4839 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
4841 16. It displays copyleft, nonwarranty, and basic use information,
4842 provided there were no remaining command line arguments (a few
4843 steps above) and the value of `inhibit-startup-message' is `nil'.
4845 - User Option: inhibit-startup-message
4846 This variable inhibits the initial startup messages (the
4847 nonwarranty, etc.). If it is non-`nil', then the messages are not
4850 This variable exists so you can set it in your personal init file,
4851 once you are familiar with the contents of the startup message.
4852 Do not set this variable in the init file of a new user, or in a
4853 way that affects more than one user, because that would prevent
4854 new users from receiving the information they are supposed to see.
4856 - User Option: inhibit-startup-echo-area-message
4857 This variable controls the display of the startup echo area
4858 message. You can suppress the startup echo area message by adding
4859 text with this form to your `.emacs' file:
4861 (setq inhibit-startup-echo-area-message
4864 Simply setting `inhibit-startup-echo-area-message' to your login
4865 name is not sufficient to inhibit the message; Emacs explicitly
4866 checks whether `.emacs' contains an expression as shown above.
4867 Your login name must appear in the expression as a Lisp string
4870 This way, you can easily inhibit the message for yourself if you
4871 wish, but thoughtless copying of your `.emacs' file will not
4872 inhibit the message for someone else.
4875 File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
4877 The Init File: `.emacs'
4878 -----------------------
4880 When you start XEmacs, it normally attempts to load the file `.emacs'
4881 from your home directory. This file, if it exists, must contain Lisp
4882 code. It is called your "init file". The command line switches `-q'
4883 and `-u' affect the use of the init file; `-q' says not to load an init
4884 file, and `-u' says to load a specified user's init file instead of
4885 yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
4887 A site may have a "default init file", which is the library named
4888 `default.el'. XEmacs finds the `default.el' file through the standard
4889 search path for libraries (*note How Programs Do Loading::). The
4890 XEmacs distribution does not come with this file; sites may provide one
4891 for local customizations. If the default init file exists, it is
4892 loaded whenever you start Emacs, except in batch mode or if `-q' is
4893 specified. But your own personal init file, if any, is loaded first; if
4894 it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
4895 not subsequently load the `default.el' file.
4897 Another file for site-customization is `site-start.el'. Emacs loads
4898 this _before_ the user's init file. You can inhibit the loading of
4899 this file with the option `-no-site-file'.
4901 - Variable: site-run-file
4902 This variable specifies the site-customization file to load before
4903 the user's init file. Its normal value is `"site-start"'.
4905 If there is a great deal of code in your `.emacs' file, you should
4906 move it into another file named `SOMETHING.el', byte-compile it (*note
4907 Byte Compilation::), and make your `.emacs' file load the other file
4908 using `load' (*note Loading::).
4910 *Note Init File Examples: (xemacs)Init File Examples, for examples
4911 of how to make various commonly desired customizations in your `.emacs'
4914 - User Option: inhibit-default-init
4915 This variable prevents XEmacs from loading the default
4916 initialization library file for your session of XEmacs. If its
4917 value is non-`nil', then the default library is not loaded. The
4918 default value is `nil'.
4920 - Variable: before-init-hook
4921 - Variable: after-init-hook
4922 These two normal hooks are run just before, and just after,
4923 loading of the user's init file, `default.el', and/or
4927 File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
4929 Terminal-Specific Initialization
4930 --------------------------------
4932 Each terminal type can have its own Lisp library that XEmacs loads when
4933 run on that type of terminal. For a terminal type named TERMTYPE, the
4934 library is called `term/TERMTYPE'. XEmacs finds the file by searching
4935 the `load-path' directories as it does for other files, and trying the
4936 `.elc' and `.el' suffixes. Normally, terminal-specific Lisp library is
4937 located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
4938 directory in which most XEmacs Lisp libraries are kept.
4940 The library's name is constructed by concatenating the value of the
4941 variable `term-file-prefix' and the terminal type. Normally,
4942 `term-file-prefix' has the value `"term/"'; changing this is not
4945 The usual function of a terminal-specific library is to enable
4946 special keys to send sequences that XEmacs can recognize. It may also
4947 need to set or add to `function-key-map' if the Termcap entry does not
4948 specify all the terminal's function keys. *Note Terminal Input::.
4950 When the name of the terminal type contains a hyphen, only the part
4951 of the name before the first hyphen is significant in choosing the
4952 library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
4953 the `term/aaa' library. If necessary, the library can evaluate
4954 `(getenv "TERM")' to find the full name of the terminal type.
4956 Your `.emacs' file can prevent the loading of the terminal-specific
4957 library by setting the variable `term-file-prefix' to `nil'. This
4958 feature is useful when experimenting with your own peculiar
4961 You can also arrange to override some of the actions of the
4962 terminal-specific library by setting the variable `term-setup-hook'.
4963 This is a normal hook which XEmacs runs using `run-hooks' at the end of
4964 XEmacs initialization, after loading both your `.emacs' file and any
4965 terminal-specific libraries. You can use this variable to define
4966 initializations for terminals that do not have their own libraries.
4969 - Variable: term-file-prefix
4970 If the `term-file-prefix' variable is non-`nil', XEmacs loads a
4971 terminal-specific initialization file as follows:
4973 (load (concat term-file-prefix (getenv "TERM")))
4975 You may set the `term-file-prefix' variable to `nil' in your
4976 `.emacs' file if you do not wish to load the
4977 terminal-initialization file. To do this, put the following in
4978 your `.emacs' file: `(setq term-file-prefix nil)'.
4980 - Variable: term-setup-hook
4981 This variable is a normal hook that XEmacs runs after loading your
4982 `.emacs' file, the default initialization file (if any) and the
4983 terminal-specific Lisp file.
4985 You can use `term-setup-hook' to override the definitions made by a
4986 terminal-specific file.
4988 - Variable: window-setup-hook
4989 This variable is a normal hook which XEmacs runs after loading your
4990 `.emacs' file and the default initialization file (if any), after
4991 loading terminal-specific Lisp code, and after running the hook
4995 File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
4997 Command Line Arguments
4998 ----------------------
5000 You can use command line arguments to request various actions when you
5001 start XEmacs. Since you do not need to start XEmacs more than once per
5002 day, and will often leave your XEmacs session running longer than that,
5003 command line arguments are hardly ever used. As a practical matter, it
5004 is best to avoid making the habit of using them, since this habit would
5005 encourage you to kill and restart XEmacs unnecessarily often. These
5006 options exist for two reasons: to be compatible with other editors (for
5007 invocation by other programs) and to enable shell scripts to run
5008 specific Lisp programs.
5010 This section describes how Emacs processes command line arguments,
5011 and how you can customize them.
5013 - Function: command-line
5014 This function parses the command line that XEmacs was called with,
5015 processes it, loads the user's `.emacs' file and displays the
5018 - Variable: command-line-processed
5019 The value of this variable is `t' once the command line has been
5022 If you redump XEmacs by calling `dump-emacs', you may wish to set
5023 this variable to `nil' first in order to cause the new dumped
5024 XEmacs to process its new command line arguments.
5026 - Variable: command-switch-alist
5027 The value of this variable is an alist of user-defined command-line
5028 options and associated handler functions. This variable exists so
5029 you can add elements to it.
5031 A "command line option" is an argument on the command line of the
5036 The elements of the `command-switch-alist' look like this:
5038 (OPTION . HANDLER-FUNCTION)
5040 The HANDLER-FUNCTION is called to handle OPTION and receives the
5041 option name as its sole argument.
5043 In some cases, the option is followed in the command line by an
5044 argument. In these cases, the HANDLER-FUNCTION can find all the
5045 remaining command-line arguments in the variable
5046 `command-line-args-left'. (The entire list of command-line
5047 arguments is in `command-line-args'.)
5049 The command line arguments are parsed by the `command-line-1'
5050 function in the `startup.el' file. See also *Note Command Line
5051 Switches and Arguments: (xemacs)Command Switches.
5053 - Variable: command-line-args
5054 The value of this variable is the list of command line arguments
5057 - Variable: command-line-functions
5058 This variable's value is a list of functions for handling an
5059 unrecognized command-line argument. Each time the next argument
5060 to be processed has no special meaning, the functions in this list
5061 are called, in order of appearance, until one of them returns a
5064 These functions are called with no arguments. They can access the
5065 command-line argument under consideration through the variable
5066 `argi'. The remaining arguments (not including the current one)
5067 are in the variable `command-line-args-left'.
5069 When a function recognizes and processes the argument in `argi', it
5070 should return a non-`nil' value to say it has dealt with that
5071 argument. If it has also dealt with some of the following
5072 arguments, it can indicate that by deleting them from
5073 `command-line-args-left'.
5075 If all of these functions return `nil', then the argument is used
5076 as a file name to visit.
5079 File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
5081 Getting out of XEmacs
5082 =====================
5084 There are two ways to get out of XEmacs: you can kill the XEmacs job,
5085 which exits permanently, or you can suspend it, which permits you to
5086 reenter the XEmacs process later. As a practical matter, you seldom
5087 kill XEmacs--only when you are about to log out. Suspending is much
5092 * Killing XEmacs:: Exiting XEmacs irreversibly.
5093 * Suspending XEmacs:: Exiting XEmacs reversibly.
5096 File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
5101 Killing XEmacs means ending the execution of the XEmacs process. The
5102 parent process normally resumes control. The low-level primitive for
5103 killing XEmacs is `kill-emacs'.
5105 - Command: kill-emacs &optional exit-data
5106 This function exits the XEmacs process and kills it.
5108 If EXIT-DATA is an integer, then it is used as the exit status of
5109 the XEmacs process. (This is useful primarily in batch operation;
5110 see *Note Batch Mode::.)
5112 If EXIT-DATA is a string, its contents are stuffed into the
5113 terminal input buffer so that the shell (or whatever program next
5114 reads input) can read them.
5116 All the information in the XEmacs process, aside from files that have
5117 been saved, is lost when the XEmacs is killed. Because killing XEmacs
5118 inadvertently can lose a lot of work, XEmacs queries for confirmation
5119 before actually terminating if you have buffers that need saving or
5120 subprocesses that are running. This is done in the function
5121 `save-buffers-kill-emacs'.
5123 - Variable: kill-emacs-query-functions
5124 After asking the standard questions, `save-buffers-kill-emacs'
5125 calls the functions in the list `kill-buffer-query-functions', in
5126 order of appearance, with no arguments. These functions can ask
5127 for additional confirmation from the user. If any of them returns
5128 non-`nil', XEmacs is not killed.
5130 - Variable: kill-emacs-hook
5131 This variable is a normal hook; once `save-buffers-kill-emacs' is
5132 finished with all file saving and confirmation, it runs the
5133 functions in this hook.
5136 File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
5141 "Suspending XEmacs" means stopping XEmacs temporarily and returning
5142 control to its superior process, which is usually the shell. This
5143 allows you to resume editing later in the same XEmacs process, with the
5144 same buffers, the same kill ring, the same undo history, and so on. To
5145 resume XEmacs, use the appropriate command in the parent shell--most
5148 Some operating systems do not support suspension of jobs; on these
5149 systems, "suspension" actually creates a new shell temporarily as a
5150 subprocess of XEmacs. Then you would exit the shell to return to
5153 Suspension is not useful with window systems such as X, because the
5154 XEmacs job may not have a parent that can resume it again, and in any
5155 case you can give input to some other job such as a shell merely by
5156 moving to a different window. Therefore, suspending is not allowed
5157 when XEmacs is an X client.
5159 - Command: suspend-emacs &optional stuffstring
5160 This function stops XEmacs and returns control to the superior
5161 process. If and when the superior process resumes XEmacs,
5162 `suspend-emacs' returns `nil' to its caller in Lisp.
5164 If optional arg STUFFSTRING is non-`nil', its characters are sent
5165 to be read as terminal input by XEmacs's superior shell. The
5166 characters in STUFFSTRING are not echoed by the superior shell;
5167 only the results appear.
5169 Before suspending, `suspend-emacs' runs the normal hook
5170 `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
5171 normal hook; its value was a single function, and if its value was
5172 non-`nil', then `suspend-emacs' returned immediately without
5173 actually suspending anything.
5175 After the user resumes XEmacs, `suspend-emacs' runs the normal hook
5176 `suspend-resume-hook'. *Note Hooks::.
5178 The next redisplay after resumption will redraw the entire screen,
5179 unless the variable `no-redraw-on-reenter' is non-`nil' (*note
5182 In the following example, note that `pwd' is not echoed after
5183 XEmacs is suspended. But it is read and executed by the shell.
5188 (add-hook 'suspend-hook
5189 (function (lambda ()
5192 (error "Suspend cancelled")))))
5194 (or (y-or-n-p "Really suspend? ")
5195 (error "Suspend cancelled")))
5196 (add-hook 'suspend-resume-hook
5197 (function (lambda () (message "Resumed!"))))
5198 => (lambda nil (message "Resumed!"))
5199 (suspend-emacs "pwd")
5201 ---------- Buffer: Minibuffer ----------
5203 ---------- Buffer: Minibuffer ----------
5205 ---------- Parent Shell ----------
5206 lewis@slug[23] % /user/lewis/manual
5209 ---------- Echo Area ----------
5212 - Variable: suspend-hook
5213 This variable is a normal hook run before suspending.
5215 - Variable: suspend-resume-hook
5216 This variable is a normal hook run after suspending.
5219 File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
5221 Operating System Environment
5222 ============================
5224 XEmacs provides access to variables in the operating system environment
5225 through various functions. These variables include the name of the
5226 system, the user's UID, and so on.
5228 - Variable: system-type
5229 The value of this variable is a symbol indicating the type of
5230 operating system XEmacs is operating on. Here is a table of the
5240 Data General DGUX operating system.
5243 A GNU system using the GNU HURD and Mach.
5246 Hewlett-Packard HPUX operating system.
5249 Silicon Graphics Irix system.
5252 A GNU system using the Linux kernel.
5255 Microsoft MS-DOS "operating system."
5258 NeXT Mach-based system.
5261 Masscomp RTU, UCB universe.
5270 Microsoft windows NT.
5275 We do not wish to add new symbols to make finer distinctions
5276 unless it is absolutely necessary! In fact, we hope to eliminate
5277 some of these alternatives in the future. We recommend using
5278 `system-configuration' to distinguish between different operating
5281 - Variable: system-configuration
5282 This variable holds the three-part configuration name for the
5283 hardware/software configuration of your system, as a string. The
5284 convenient way to test parts of this string is with `string-match'.
5286 - Function: system-name
5287 This function returns the name of the machine you are running on.
5289 => "prep.ai.mit.edu"
5291 The symbol `system-name' is a variable as well as a function. In
5292 fact, the function returns whatever value the variable `system-name'
5293 currently holds. Thus, you can set the variable `system-name' in case
5294 Emacs is confused about the name of your system. The variable is also
5295 useful for constructing frame titles (*note Frame Titles::).
5297 - Variable: mail-host-address
5298 If this variable is non-`nil', it is used instead of `system-name'
5299 for purposes of generating email addresses. For example, it is
5300 used when constructing the default value of `user-mail-address'.
5301 *Note User Identification::. (Since this is done when XEmacs
5302 starts up, the value actually used is the one saved when XEmacs
5303 was dumped. *Note Building XEmacs::.)
5305 - Command: getenv var &optional interactivep
5306 This function returns the value of the environment variable VAR,
5307 as a string. Within XEmacs, the environment variable values are
5308 kept in the Lisp variable `process-environment'.
5310 When invoked interactively, `getenv' prints the value in the echo
5316 lewis@slug[10] % printenv
5317 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
5323 - Command: setenv variable &optional value unset
5324 This command sets the value of the environment variable named
5325 VARIABLE to VALUE. Both arguments should be strings. This
5326 function works by modifying `process-environment'; binding that
5327 variable with `let' is also reasonable practice.
5329 - Variable: process-environment
5330 This variable is a list of strings, each describing one environment
5331 variable. The functions `getenv' and `setenv' work by
5332 manipulating this variable.
5335 => ("l=/usr/stanford/lib/gnuemacs/lisp"
5336 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
5342 - Variable: path-separator
5343 This variable holds a string which says which character separates
5344 directories in a search path (as found in an environment
5345 variable). Its value is `":"' for Unix and GNU systems, and `";"'
5346 for MS-DOS and Windows NT.
5348 - Variable: invocation-name
5349 This variable holds the program name under which Emacs was
5350 invoked. The value is a string, and does not include a directory
5353 - Variable: invocation-directory
5354 This variable holds the directory from which the Emacs executable
5355 was invoked, or perhaps `nil' if that directory cannot be
5358 - Variable: installation-directory
5359 If non-`nil', this is a directory within which to look for the
5360 `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
5361 can't find those directories in their standard installed
5362 locations, but can find them in a directory related somehow to the
5363 one containing the Emacs executable.
5365 - Function: load-average &optional use-floats
5366 This function returns a list of the current 1-minute, 5-minute and
5367 15-minute load averages. The values are integers that are 100
5368 times the system load averages. (The load averages indicate the
5369 number of processes trying to run.)
5371 When USE-FLOATS is non-`nil', floats will be returned instead of
5372 integers. These floats are not multiplied by 100.
5377 => (1.69921875 1.58984375 1.640625)
5379 lewis@rocky[5] % uptime
5380 8:06pm up 16 day(s), 21:57, 40 users,
5381 load average: 1.68, 1.59, 1.64
5383 If the 5-minute or 15-minute load averages are not available,
5384 return a shortened list, containing only those averages which are
5387 On some systems, this function may require special privileges to
5388 run, or it may be unimplemented for the particular system type.
5389 In that case, the function will signal an error.
5391 - Function: emacs-pid
5392 This function returns the process ID of the Emacs process.
5395 File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
5400 - Variable: user-mail-address
5401 This holds the nominal email address of the user who is using
5402 Emacs. When Emacs starts up, it computes a default value that is
5403 usually right, but users often set this themselves when the
5404 default value is not right.
5406 - Function: user-login-name &optional uid
5407 If you don't specify UID, this function returns the name under
5408 which the user is logged in. If the environment variable `LOGNAME'
5409 is set, that value is used. Otherwise, if the environment variable
5410 `USER' is set, that value is used. Otherwise, the value is based
5411 on the effective UID, not the real UID.
5413 If you specify UID, the value is the user name that corresponds to
5414 UID (which should be an integer).
5419 - Function: user-real-login-name
5420 This function returns the user name corresponding to Emacs's real
5421 UID. This ignores the effective UID and ignores the environment
5422 variables `LOGNAME' and `USER'.
5424 - Variable: user-full-name
5425 This variable holds the name of the user running this Emacs. It is
5426 initialized at startup time from the value of `NAME' environment
5427 variable. You can change the value of this variable to alter the
5428 result of the `user-full-name' function.
5430 - Function: user-full-name &optional user
5431 This function returns the full name of USER. If USER is `nil', it
5432 defaults to the user running this Emacs. In that case, the value
5433 of `user-full-name' variable, if non-`nil', will be used.
5435 If USER is specified explicitly, `user-full-name' variable is
5440 (setq user-full-name "Hrvoje \"Niksa\" Niksic")
5442 => "Hrvoje \"Niksa\" Niksic"
5443 (user-full-name "hniksic")
5446 The symbols `user-login-name', `user-real-login-name' and
5447 `user-full-name' are variables as well as functions. The functions
5448 return the same values that the variables hold. These variables allow
5449 you to "fake out" Emacs by telling the functions what to return. The
5450 variables are also useful for constructing frame titles (*note Frame
5453 - Function: user-real-uid
5454 This function returns the real UID of the user.
5459 - Function: user-uid
5460 This function returns the effective UID of the user.
5462 - Function: user-home-directory
5463 This function returns the "`HOME'" directory of the user, and is
5464 intended to replace occurrences of "`(getenv "HOME")'". Under
5465 Unix systems, the following is done:
5467 1. Return the value of "`(getenv "HOME")'", if set.
5469 2. Return "/", as a fallback, but issue a warning. (Future
5470 versions of XEmacs will also attempt to lookup the `HOME'
5471 directory via `getpwent()', but this has not yet been
5474 Under MS Windows, this is done:
5476 1. Return the value of "`(getenv "HOME")'", if set.
5478 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
5479 both set, return the concatenation (the following description
5480 uses MS Windows environment variable substitution syntax):
5481 `%HOMEDRIVE%%HOMEDIR%'.
5483 3. Return "C:\", as a fallback, but issue a warning.
5486 File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
5491 This section explains how to determine the current time and the time
5494 - Function: current-time-string &optional time-value
5495 This function returns the current time and date as a
5496 humanly-readable string. The format of the string is unvarying;
5497 the number of characters used for each part is always the same, so
5498 you can reliably use `substring' to extract pieces of it. It is
5499 wise to count the characters from the beginning of the string
5500 rather than from the end, as additional information may be added
5503 The argument TIME-VALUE, if given, specifies a time to format
5504 instead of the current time. The argument should be a list whose
5505 first two elements are integers. Thus, you can use times obtained
5506 from `current-time' (see below) and from `file-attributes' (*note
5509 (current-time-string)
5510 => "Wed Oct 14 22:21:05 1987"
5512 - Function: current-time
5513 This function returns the system's time value as a list of three
5514 integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
5515 combine to give the number of seconds since 0:00 January 1, 1970,
5516 which is HIGH * 2**16 + LOW.
5518 The third element, MICROSEC, gives the microseconds since the
5519 start of the current second (or 0 for systems that return time
5520 only on the resolution of a second).
5522 The first two elements can be compared with file time values such
5523 as you get with the function `file-attributes'. *Note File
5526 - Function: current-time-zone &optional time-value
5527 This function returns a list describing the time zone that the
5530 The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
5531 giving the number of seconds ahead of UTC (east of Greenwich). A
5532 negative value means west of Greenwich. The second element, NAME
5533 is a string giving the name of the time zone. Both elements
5534 change when daylight savings time begins or ends; if the user has
5535 specified a time zone that does not use a seasonal time
5536 adjustment, then the value is constant through time.
5538 If the operating system doesn't supply all the information
5539 necessary to compute the value, both elements of the list are
5542 The argument TIME-VALUE, if given, specifies a time to analyze
5543 instead of the current time. The argument should be a cons cell
5544 containing two integers, or a list whose first two elements are
5545 integers. Thus, you can use times obtained from `current-time'
5546 (see above) and from `file-attributes' (*note File Attributes::).
5549 File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
5554 These functions convert time values (lists of two or three integers) to
5555 strings or to calendrical information. There is also a function to
5556 convert calendrical information to a time value. You can get time
5557 values from the functions `current-time' (*note Time of Day::) and
5558 `file-attributes' (*note File Attributes::).
5560 - Function: format-time-string format-string &optional time
5561 This function converts TIME to a string according to
5562 FORMAT-STRING. If TIME is omitted, it defaults to the current
5563 time. The argument FORMAT-STRING may contain `%'-sequences which
5564 say to substitute parts of the time. Here is a table of what the
5568 This stands for the abbreviated name of the day of week.
5571 This stands for the full name of the day of week.
5574 This stands for the abbreviated name of the month.
5577 This stands for the full name of the month.
5580 This is a synonym for `%x %X'.
5583 This has a locale-specific meaning. In the default locale
5584 (named C), it is equivalent to `%A, %B %e, %Y'.
5587 This stands for the day of month, zero-padded.
5590 This is a synonym for `%m/%d/%y'.
5593 This stands for the day of month, blank-padded.
5596 This is a synonym for `%b'.
5599 This stands for the hour (00-23).
5602 This stands for the hour (00-12).
5605 This stands for the day of the year (001-366).
5608 This stands for the hour (0-23), blank padded.
5611 This stands for the hour (1-12), blank padded.
5614 This stands for the month (01-12).
5617 This stands for the minute (00-59).
5620 This stands for a newline.
5623 This stands for `AM' or `PM', as appropriate.
5626 This is a synonym for `%I:%M:%S %p'.
5629 This is a synonym for `%H:%M'.
5632 This stands for the seconds (00-60).
5635 This stands for a tab character.
5638 This is a synonym for `%H:%M:%S'.
5641 This stands for the week of the year (01-52), assuming that
5642 weeks start on Sunday.
5645 This stands for the numeric day of week (0-6). Sunday is day
5649 This stands for the week of the year (01-52), assuming that
5650 weeks start on Monday.
5653 This has a locale-specific meaning. In the default locale
5654 (named C), it is equivalent to `%D'.
5657 This has a locale-specific meaning. In the default locale
5658 (named C), it is equivalent to `%T'.
5661 This stands for the year without century (00-99).
5664 This stands for the year with century.
5667 This stands for the time zone abbreviation.
5669 - Function: decode-time &optional specified-time
5670 This function converts a time value into calendrical information.
5671 The optional SPECIFIED-TIME should be a list of (HIGH LOW .
5672 IGNORED) or (HIGH . LOW), as from `current-time' and
5673 `file-attributes', or `nil' to use the current time.
5675 The return value is a list of nine elements, as follows:
5677 (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
5679 Here is what the elements mean:
5682 The number of seconds past the minute, as an integer between
5686 The number of minutes past the hour, as an integer between 0
5690 The hour of the day, as an integer between 0 and 23.
5693 The day of the month, as an integer between 1 and 31.
5696 The month of the year, as an integer between 1 and 12.
5699 The year, an integer typically greater than 1900.
5702 The day of week, as an integer between 0 and 6, where 0
5706 `t' if daylight savings time is effect, otherwise `nil'.
5709 An integer indicating the time zone, as the number of seconds
5712 Note that Common Lisp has different meanings for DOW and ZONE.
5714 - Function: encode-time seconds minutes hour day month year &optional
5716 This function is the inverse of `decode-time'. It converts seven
5717 items of calendrical data into a time value. For the meanings of
5718 the arguments, see the table above under `decode-time'.
5720 Year numbers less than 100 are treated just like other year
5721 numbers. If you want them to stand for years above 1900, you must
5722 alter them yourself before you call `encode-time'.
5724 The optional argument ZONE defaults to the current time zone and
5725 its daylight savings time rules. If specified, it can be either a
5726 list (as you would get from `current-time-zone') or an integer (as
5727 you would get from `decode-time'). The specified zone is used
5728 without any further alteration for daylight savings time.
5731 File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
5733 Timers for Delayed Execution
5734 ============================
5736 You can set up a timer to call a function at a specified future time.
5738 - Function: add-timeout secs function object &optional resignal
5739 This function adds a timeout, to be signaled after the timeout
5740 period has elapsed. SECS is a number of seconds, expressed as an
5741 integer or a float. FUNCTION will be called after that many
5742 seconds have elapsed, with one argument, the given OBJECT. If the
5743 optional RESIGNAL argument is provided, then after this timeout
5744 expires, `add-timeout' will automatically be called again with
5745 RESIGNAL as the first argument.
5747 This function returns an object which is the "id" of this
5748 particular timeout. You can pass that object to `disable-timeout'
5749 to turn off the timeout before it has been signalled.
5751 The number of seconds may be expressed as a floating-point number,
5752 in which case some fractional part of a second will be used.
5753 Caveat: the usable timeout granularity will vary from system to
5756 Adding a timeout causes a timeout event to be returned by
5757 `next-event', and the function will be invoked by
5758 `dispatch-event', so if XEmacs is in a tight loop, the function
5759 will not be invoked until the next call to sit-for or until the
5760 return to top-level (the same is true of process filters).
5762 WARNING: if you are thinking of calling add-timeout from inside of
5763 a callback function as a way of resignalling a timeout, think
5764 again. There is a race condition. That's why the RESIGNAL
5767 (NOTE: In FSF Emacs, this function is called `run-at-time' and has
5768 different semantics.)
5770 - Function: disable-timeout id
5771 Cancel the requested action for ID, which should be a value
5772 previously returned by `add-timeout'. This cancels the effect of
5773 that call to `add-timeout'; the arrival of the specified time will
5774 not cause anything special to happen. (NOTE: In FSF Emacs, this
5775 function is called `cancel-timer'.)
5778 File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
5783 This section describes functions and variables for recording or
5784 manipulating terminal input. See *Note Display::, for related
5789 * Input Modes:: Options for how input is processed.
5790 * Translating Input:: Low level conversion of some characters or events
5792 * Recording Input:: Saving histories of recent or all input events.
5795 File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
5800 - Function: set-input-mode interrupt flow meta &optional quit-char
5802 This function sets the mode for reading keyboard input. If
5803 INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
5804 `nil', then it uses CBREAK mode. When XEmacs communicates
5805 directly with X, it ignores this argument and uses interrupts if
5806 that is the way it knows how to communicate.
5808 If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
5809 flow control for output to the terminal. This has no effect except
5810 in CBREAK mode. *Note Flow Control::.
5812 The default setting is system dependent. Some systems always use
5813 CBREAK mode regardless of what is specified.
5815 The argument META controls support for input character codes above
5816 127. If META is `t', XEmacs converts characters with the 8th bit
5817 set into Meta characters. If META is `nil', XEmacs disregards the
5818 8th bit; this is necessary when the terminal uses it as a parity
5819 bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
5820 input unchanged. This is good for terminals using European 8-bit
5823 If QUIT-CHAR is non-`nil', it specifies the character to use for
5824 quitting. Normally this character is `C-g'. *Note Quitting::.
5826 The `current-input-mode' function returns the input mode settings
5827 XEmacs is currently using.
5829 - Function: current-input-mode &optional console
5830 This function returns current mode for reading keyboard input. It
5831 returns a list, corresponding to the arguments of `set-input-mode',
5832 of the form `(INTERRUPT FLOW META QUIT)' in which:
5834 is non-`nil' when XEmacs is using interrupt-driven input. If
5835 `nil', Emacs is using CBREAK mode.
5838 is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
5839 control for output to the terminal. This value has no effect
5840 unless INTERRUPT is non-`nil'.
5843 is `t' if XEmacs treats the eighth bit of input characters as
5844 the meta bit; `nil' means XEmacs clears the eighth bit of
5845 every input character; any other value means XEmacs uses all
5846 eight bits as the basic character code.
5849 is the character XEmacs currently uses for quitting, usually
5853 File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
5855 Translating Input Events
5856 ------------------------
5858 This section describes features for translating input events into other
5859 input events before they become part of key sequences.
5861 - Variable: function-key-map
5862 This variable holds a keymap that describes the character sequences
5863 sent by function keys on an ordinary character terminal. This
5864 keymap uses the same data structure as other keymaps, but is used
5865 differently: it specifies translations to make while reading
5868 If `function-key-map' "binds" a key sequence K to a vector V, then
5869 when K appears as a subsequence _anywhere_ in a key sequence, it
5870 is replaced with the events in V.
5872 For example, VT100 terminals send `<ESC> O P' when the keypad PF1
5873 key is pressed. Therefore, we want XEmacs to translate that
5874 sequence of events into the single event `pf1'. We accomplish
5875 this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
5878 Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
5879 P'; later the function `read-key-sequence' translates this back
5880 into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
5882 Entries in `function-key-map' are ignored if they conflict with
5883 bindings made in the minor mode, local, or global keymaps. The
5884 intent is that the character sequences that function keys send
5885 should not have command bindings in their own right.
5887 The value of `function-key-map' is usually set up automatically
5888 according to the terminal's Terminfo or Termcap entry, but
5889 sometimes those need help from terminal-specific Lisp files.
5890 XEmacs comes with terminal-specific files for many common
5891 terminals; their main purpose is to make entries in
5892 `function-key-map' beyond those that can be deduced from Termcap
5893 and Terminfo. *Note Terminal-Specific::.
5895 Emacs versions 18 and earlier used totally different means of
5896 detecting the character sequences that represent function keys.
5898 - Variable: key-translation-map
5899 This variable is another keymap used just like `function-key-map'
5900 to translate input events into other events. It differs from
5901 `function-key-map' in two ways:
5903 * `key-translation-map' goes to work after `function-key-map' is
5904 finished; it receives the results of translation by
5907 * `key-translation-map' overrides actual key bindings.
5909 The intent of `key-translation-map' is for users to map one
5910 character set to another, including ordinary characters normally
5911 bound to `self-insert-command'.
5913 You can use `function-key-map' or `key-translation-map' for more
5914 than simple aliases, by using a function, instead of a key sequence, as
5915 the "translation" of a key. Then this function is called to compute
5916 the translation of that key.
5918 The key translation function receives one argument, which is the
5919 prompt that was specified in `read-key-sequence'--or `nil' if the key
5920 sequence is being read by the editor command loop. In most cases you
5921 can ignore the prompt value.
5923 If the function reads input itself, it can have the effect of
5924 altering the event that follows. For example, here's how to define
5925 `C-c h' to turn the character that follows into a Hyper character:
5927 (defun hyperify (prompt)
5928 (let ((e (read-event)))
5929 (vector (if (numberp e)
5930 (logior (lsh 1 20) e)
5931 (if (memq 'hyper (event-modifiers e))
5933 (add-event-modifier "H-" e))))))
5935 (defun add-event-modifier (string e)
5936 (let ((symbol (if (symbolp e) e (car e))))
5937 (setq symbol (intern (concat string
5938 (symbol-name symbol))))
5941 (cons symbol (cdr e)))))
5943 (define-key function-key-map "\C-ch" 'hyperify)
5945 The `iso-transl' library uses this feature to provide a way of
5946 inputting non-ASCII Latin-1 characters.
5949 File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
5954 - Function: recent-keys &optional number
5955 This function returns a vector containing recent input events from
5956 the keyboard or mouse. By default, 100 events are recorded, which
5957 is how many `recent-keys' returns.
5959 All input events are included, whether or not they were used as
5960 parts of key sequences. Thus, you always get the last 100 inputs,
5961 not counting keyboard macros. (Events from keyboard macros are
5962 excluded because they are less interesting for debugging; it
5963 should be enough to see the events that invoked the macros.)
5965 If NUMBER is specified, not more than NUMBER events will be
5966 returned. You may change the number of stored events using
5967 `set-recent-keys-ring-size'.
5969 - Function: recent-keys-ring-size
5970 This function returns the number of recent events stored
5971 internally. This is also the maximum number of events
5972 `recent-keys' can return. By default, 100 events are stored.
5974 - Function: set-recent-keys-ring-size size
5975 This function changes the number of events stored by XEmacs and
5976 returned by `recent-keys'.
5978 For example, `(set-recent-keys-ring-size 250)' will make XEmacs
5979 remember last 250 events and will make `recent-keys' return last
5980 250 events by default.
5982 - Command: open-dribble-file filename
5983 This function opens a "dribble file" named FILENAME. When a
5984 dribble file is open, each input event from the keyboard or mouse
5985 (but not those from keyboard macros) is written in that file. A
5986 non-character event is expressed using its printed representation
5987 surrounded by `<...>'.
5989 You close the dribble file by calling this function with an
5992 This function is normally used to record the input necessary to
5993 trigger an XEmacs bug, for the sake of a bug report.
5995 (open-dribble-file "~/dribble")
5998 See also the `open-termscript' function (*note Terminal Output::).
6001 File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
6006 The terminal output functions send output to the terminal or keep track
6007 of output sent to the terminal. The function `device-baud-rate' tells
6008 you what XEmacs thinks is the output speed of the terminal.
6010 - Function: device-baud-rate &optional device
6011 This function's value is the output speed of the terminal
6012 associated with DEVICE, as far as XEmacs knows. DEVICE defaults
6013 to the selected device (usually the only device) if omitted.
6014 Changing this value does not change the speed of actual data
6015 transmission, but the value is used for calculations such as
6016 padding. This value has no effect for window-system devices.
6017 (This is different in FSF Emacs, where the baud rate also affects
6018 decisions about whether to scroll part of the screen or repaint,
6019 even when using a window system.)
6021 The value is measured in bits per second.
6023 XEmacs attempts to automatically initialize the baud rate by querying
6024 the terminal. If you are running across a network, however, and
6025 different parts of the network work are at different baud rates, the
6026 value returned by XEmacs may be different from the value used by your
6027 local terminal. Some network protocols communicate the local terminal
6028 speed to the remote machine, so that XEmacs and other programs can get
6029 the proper value, but others do not. If XEmacs has the wrong value, it
6030 makes decisions that are less than optimal. To fix the problem, use
6031 `set-device-baud-rate'.
6033 - Function: set-device-baud-rate device baud-rate
6034 This function sets the output speed of DEVICE. See
6035 `device-baud-rate'. DEVICE defaults to the selected device
6036 (usually the only device) if `nil'.
6038 - Function: send-string-to-terminal char-or-string &optional stdout-p
6040 This function sends CHAR-OR-STRING to the terminal without
6041 alteration. Control characters in CHAR-OR-STRING have
6042 terminal-dependent effects.
6044 If DEVICE is `nil', this function writes to XEmacs's stderr, or to
6045 stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
6046 tty or stream device, and the function writes to the device's
6047 normal or error output, according to STDOUT-P.
6049 One use of this function is to define function keys on terminals
6050 that have downloadable function key definitions. For example,
6051 this is how on certain terminals to define function key 4 to move
6052 forward four characters (by transmitting the characters `C-u C-f'
6055 (send-string-to-terminal "\eF4\^U\^F")
6058 - Command: open-termscript filename
6059 This function is used to open a "termscript file" that will record
6060 all the characters sent by XEmacs to the terminal. (If there are
6061 multiple tty or stream devices, all characters sent to all such
6062 devices are recorded.) The function returns `nil'. Termscript
6063 files are useful for investigating problems where XEmacs garbles
6064 the screen, problems that are due to incorrect Termcap entries or
6065 to undesirable settings of terminal options more often than to
6066 actual XEmacs bugs. Once you are certain which characters were
6067 actually output, you can determine reliably whether they
6068 correspond to the Termcap specifications in use.
6070 A `nil' value for FILENAME stops recording terminal output.
6072 See also `open-dribble-file' in *Note Terminal Input::.
6074 (open-termscript "../junk/termscript")
6078 File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
6083 This section attempts to answer the question "Why does XEmacs choose to
6084 use flow-control characters in its command character set?" For a
6085 second view on this issue, read the comments on flow control in the
6086 `emacs/INSTALL' file from the distribution; for help with Termcap
6087 entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
6089 At one time, most terminals did not need flow control, and none used
6090 `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
6091 `C-q' as command characters was uncontroversial. XEmacs, for economy
6092 of keystrokes and portability, used nearly all the ASCII control
6093 characters, with mnemonic meanings when possible; thus, `C-s' for
6094 search and `C-q' for quote.
6096 Later, some terminals were introduced which required these characters
6097 for flow control. They were not very good terminals for full-screen
6098 editing, so XEmacs maintainers did not pay attention. In later years,
6099 flow control with `C-s' and `C-q' became widespread among terminals,
6100 but by this time it was usually an option. And the majority of users,
6101 who can turn flow control off, were unwilling to switch to less
6102 mnemonic key bindings for the sake of flow control.
6104 So which usage is "right", XEmacs's or that of some terminal and
6105 concentrator manufacturers? This question has no simple answer.
6107 One reason why we are reluctant to cater to the problems caused by
6108 `C-s' and `C-q' is that they are gratuitous. There are other
6109 techniques (albeit less common in practice) for flow control that
6110 preserve transparency of the character stream. Note also that their use
6111 for flow control is not an official standard. Interestingly, on the
6112 model 33 teletype with a paper tape punch (which is very old), `C-s'
6113 and `C-q' were sent by the computer to turn the punch on and off!
6115 As X servers and other window systems replace character-only
6116 terminals, this problem is gradually being cured. For the mean time,
6117 XEmacs provides a convenient way of enabling flow control if you want
6118 it: call the function `enable-flow-control'.
6120 - Command: enable-flow-control &optional argument
6121 This function enables use of `C-s' and `C-q' for output flow
6122 control, and provides the characters `C-\' and `C-^' as aliases
6123 for them using `keyboard-translate-table' (*note Translating
6126 With optional argument ARGUMENT (interactively the prefix
6127 argument), enable flow control mode if ARGUMENT is positive; else
6130 You can use the function `enable-flow-control-on' in your `.emacs'
6131 file to enable flow control automatically on certain terminal types.
6133 - Function: enable-flow-control-on &rest termtypes
6134 This function enables flow control, and the aliases `C-\' and
6135 `C-^', if the terminal type is one of TERMTYPES. For example:
6137 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
6139 Here is how `enable-flow-control' does its job:
6141 1. It sets CBREAK mode for terminal input, and tells the operating
6142 system to handle flow control, with `(set-input-mode nil t)'.
6144 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
6145 into `C-s' and `C-q'. Except at its very lowest level, XEmacs
6146 never knows that the characters typed were anything but `C-s' and
6147 `C-q', so you can in effect type them as `C-\' and `C-^' even when
6148 they are input for other commands. *Note Translating Input::.
6150 If the terminal is the source of the flow control characters, then
6151 once you enable kernel flow control handling, you probably can make do
6152 with less padding than normal for that terminal. You can reduce the
6153 amount of padding by customizing the Termcap entry. You can also
6154 reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
6155 a smaller speed when calculating the padding needed. *Note Terminal
6159 File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
6164 The command line option `-batch' causes XEmacs to run noninteractively.
6165 In this mode, XEmacs does not read commands from the terminal, it does
6166 not alter the terminal modes, and it does not expect to be outputting
6167 to an erasable screen. The idea is that you specify Lisp programs to
6168 run; when they are finished, XEmacs should exit. The way to specify
6169 the programs to run is with `-l FILE', which loads the library named
6170 FILE, and `-f FUNCTION', which calls FUNCTION with no arguments.
6172 Any Lisp program output that would normally go to the echo area,
6173 either using `message' or using `prin1', etc., with `t' as the stream,
6174 goes instead to XEmacs's standard error descriptor when in batch mode.
6175 Thus, XEmacs behaves much like a noninteractive application program.
6176 (The echo area output that XEmacs itself normally generates, such as
6177 command echoing, is suppressed entirely.)
6179 - Function: noninteractive
6180 This function returns non-`nil' when XEmacs is running in batch
6183 - Variable: noninteractive
6184 This variable is non-`nil' when XEmacs is running in batch mode.
6185 Setting this variable to `nil', however, will not change whether
6186 XEmacs is running in batch mode, and will not change the return
6187 value of the `noninteractive' function.
6190 File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
6192 Functions Specific to the X Window System
6193 *****************************************
6195 XEmacs provides the concept of "devices", which generalizes connections
6196 to an X server, a TTY device, etc. Most information about an X server
6197 that XEmacs is connected to can be determined through general console
6198 and device functions. *Note Consoles and Devices::. However, there
6199 are some features of the X Window System that do not generalize well,
6200 and they are covered specially here.
6204 * X Selections:: Transferring text to and from other X clients.
6205 * X Server:: Information about the X server connected to
6206 a particular device.
6207 * X Miscellaneous:: Other X-specific functions and variables.
6210 File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
6215 The X server records a set of "selections" which permit transfer of
6216 data between application programs. The various selections are
6217 distinguished by "selection types", represented in XEmacs by symbols.
6218 X clients including XEmacs can read or set the selection for any given
6221 - Function: x-own-selection data &optional type
6222 This function sets a "selection" in the X server. It takes two
6223 arguments: a value, DATA, and the selection type TYPE to assign it
6224 to. DATA may be a string, a cons of two markers, or an extent.
6225 In the latter cases, the selection is considered to be the text
6226 between the markers, or between the extent's endpoints.
6228 Each possible TYPE has its own selection value, which changes
6229 independently. The usual values of TYPE are `PRIMARY' and
6230 `SECONDARY'; these are symbols with upper-case names, in accord
6231 with X Windows conventions. The default is `PRIMARY'.
6233 (In FSF Emacs, this function is called `x-set-selection' and takes
6234 different arguments.)
6236 - Function: x-get-selection
6237 This function accesses selections set up by XEmacs or by other X
6238 clients. It returns the value of the current primary selection.
6240 - Function: x-disown-selection &optional secondary-p
6241 Assuming we own the selection, this function disowns it. If
6242 SECONDARY-P is non-`nil', the secondary selection instead of the
6243 primary selection is discarded.
6245 The X server also has a set of numbered "cut buffers" which can
6246 store text or other data being moved between applications. Cut buffers
6247 are considered obsolete, but XEmacs supports them for the sake of X
6248 clients that still use them.
6250 - Function: x-get-cutbuffer &optional n
6251 This function returns the contents of cut buffer number N. (This
6252 function is called `x-get-cut-buffer' in FSF Emacs.)
6254 - Function: x-store-cutbuffer string &optional push
6255 This function stores STRING into the first cut buffer (cut buffer
6258 Normally, the contents of the first cut buffer are simply replaced
6259 by STRING. However, if optional argument PUSH is non-`nil', the
6260 cut buffers are rotated. This means that the previous value of
6261 the first cut buffer moves to the second cut buffer, and the
6262 second to the third, and so on, moving the other values down
6263 through the series of cut buffers, kill-ring-style. There are 8
6264 cut buffers altogether.
6266 Cut buffers are considered obsolete; you should use selections
6269 This function has no effect if support for cut buffers was not
6272 This function is called `x-set-cut-buffer' in FSF Emacs.
6275 File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
6280 This section describes how to access and change the overall status of
6281 the X server XEmacs is using.
6285 * Resources:: Getting resource values from the server.
6286 * Server Data:: Getting info about the X server.
6287 * Grabs:: Restricting access to the server by other apps.
6290 File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
6295 - Function: default-x-device
6296 This function return the default X device for resourcing. This is
6297 the first-created X device that still exists.
6299 - Function: x-get-resource name class type &optional locale device
6301 This function retrieves a resource value from the X resource
6304 * The first arg is the name of the resource to retrieve, such as
6307 * The second arg is the class of the resource to retrieve, like
6310 * The third arg should be one of the symbols `string',
6311 `integer', `natnum', or `boolean', specifying the type of
6312 object that the database is searched for.
6314 * The fourth arg is the locale to search for the resources on,
6315 and can currently be a buffer, a frame, a device, or the
6316 symbol `global'. If omitted, it defaults to `global'.
6318 * The fifth arg is the device to search for the resources on.
6319 (The resource database for a particular device is constructed
6320 by combining non-device- specific resources such any
6321 command-line resources specified and any app-defaults files
6322 found [or the fallback resources supplied by XEmacs, if no
6323 app-defaults file is found] with device-specific resources
6324 such as those supplied using `xrdb'.) If omitted, it defaults
6325 to the device of LOCALE, if a device can be derived (i.e. if
6326 LOCALE is a frame or device), and otherwise defaults to the
6327 value of `default-x-device'.
6329 * The sixth arg NOERROR, if non-`nil', means do not signal an
6330 error if a bogus resource specification was retrieved (e.g.
6331 if a non-integer was given when an integer was requested).
6332 In this case, a warning is issued instead.
6334 The resource names passed to this function are looked up relative
6337 If you want to search for a subresource, you just need to specify
6338 the resource levels in NAME and CLASS. For example, NAME could be
6339 `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
6343 1. If LOCALE is a buffer, a call
6345 `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
6347 is an interface to a C call something like
6349 `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
6350 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
6353 2. If LOCALE is a frame, a call
6355 `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
6357 is an interface to a C call something like
6359 `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
6360 "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
6363 3. If LOCALE is a device, a call
6365 `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
6367 is an interface to a C call something like
6369 `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
6370 "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
6373 4. If LOCALE is the symbol `global', a call
6375 `(x-get-resource "foreground" "Foreground" 'string 'global)'
6377 is an interface to a C call something like
6379 `XrmGetResource (db, "xemacs.foreground",
6383 Note that for `global', no prefix is added other than that of the
6384 application itself; thus, you can use this locale to retrieve
6385 arbitrary application resources, if you really want to.
6387 The returned value of this function is `nil' if the queried
6388 resource is not found. If TYPE is `string', a string is returned,
6389 and if it is `integer', an integer is returned. If TYPE is
6390 `boolean', then the returned value is the list `(t)' for true,
6391 `(nil)' for false, and is `nil' to mean "unspecified".
6393 - Function: x-put-resource resource-line &optional device
6394 This function adds a resource to the resource database for DEVICE.
6395 RESOURCE-LINE specifies the resource to add and should be a
6396 standard resource specification.
6398 - Variable: x-emacs-application-class
6399 This variable holds The X application class of the XEmacs process.
6400 This controls, among other things, the name of the "app-defaults"
6401 file that XEmacs will use. For changes to this variable to take
6402 effect, they must be made before the connection to the X server is
6403 initialized, that is, this variable may only be changed before
6404 XEmacs is dumped, or by setting it in the file
6405 `lisp/term/x-win.el'.
6407 By default, this variable is `nil' at startup. When the connection
6408 to the X server is first initialized, the X resource database will
6409 be consulted and the value will be set according to whether any
6410 resources are found for the application class "XEmacs".
6413 File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
6415 Data about the X Server
6416 -----------------------
6418 This section describes functions and a variable that you can use to get
6419 information about the capabilities and origin of the X server
6420 corresponding to a particular device. The device argument is generally
6421 optional and defaults to the selected device.
6423 - Function: x-server-version &optional device
6424 This function returns the list of version numbers of the X server
6425 DEVICE is on. The returned value is a list of three integers: the
6426 major and minor version numbers of the X protocol in use, and the
6427 vendor-specific release number.
6429 - Function: x-server-vendor &optional device
6430 This function returns the vendor supporting the X server DEVICE is
6433 - Function: x-display-visual-class &optional device
6434 This function returns the visual class of the display DEVICE is
6435 on. The value is one of the symbols `static-gray', `gray-scale',
6436 `static-color', `pseudo-color', `true-color', and `direct-color'.
6437 (Note that this is different from previous versions of XEmacs,
6438 which returned `StaticGray', `GrayScale', etc.)
6441 File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
6443 Restricting Access to the Server by Other Apps
6444 ----------------------------------------------
6446 - Function: x-grab-keyboard &optional device
6447 This function grabs the keyboard on the given device (defaulting
6448 to the selected one). So long as the keyboard is grabbed, all
6449 keyboard events will be delivered to XEmacs--it is not possible
6450 for other X clients to eavesdrop on them. Ungrab the keyboard
6451 with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
6452 if the grab was successful; `nil' otherwise.
6454 - Function: x-ungrab-keyboard &optional device
6455 This function releases a keyboard grab made with `x-grab-keyboard'.
6457 - Function: x-grab-pointer &optional device cursor ignore-keyboard
6458 This function grabs the pointer and restricts it to its current
6459 window. If optional DEVICE argument is `nil', the selected device
6460 will be used. If optional CURSOR argument is non-`nil', change
6461 the pointer shape to that until `x-ungrab-pointer' is called (it
6462 should be an object returned by the `make-cursor' function). If
6463 the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
6464 all keyboard events during the grab. Returns `t' if the grab is
6465 successful, `nil' otherwise.
6467 - Function: x-ungrab-pointer &optional device
6468 This function releases a pointer grab made with `x-grab-pointer'.
6469 If optional first arg DEVICE is `nil' the selected device is used.
6470 If it is `t' the pointer will be released on all X devices.
6473 File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
6475 Miscellaneous X Functions and Variables
6476 =======================================
6478 - Variable: x-bitmap-file-path
6479 This variable holds a list of the directories in which X bitmap
6480 files may be found. If `nil', this is initialized from the
6481 `"*bitmapFilePath"' resource. This is used by the
6482 `make-image-instance' function (however, note that if the
6483 environment variable `XBMLANGPATH' is set, it is consulted first).
6485 - Variable: x-library-search-path
6486 This variable holds the search path used by `read-color' to find
6489 - Function: x-valid-keysym-name-p keysym
6490 This function returns true if KEYSYM names a keysym that the X
6491 library knows about. Valid keysyms are listed in the files
6492 `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
6493 whatever the equivalents are on your system.
6495 - Function: x-window-id &optional frame
6496 This function returns the ID of the X11 window. This gives us a
6497 chance to manipulate the Emacs window from within a different
6498 program. Since the ID is an unsigned long, we return it as a
6501 - Variable: x-allow-sendevents
6502 If non-`nil', synthetic events are allowed. `nil' means they are
6503 ignored. Beware: allowing XEmacs to process SendEvents opens a
6506 - Function: x-debug-mode arg &optional device
6507 With a true arg, make the connection to the X server synchronous.
6508 With false, make it asynchronous. Synchronous connections are
6509 much slower, but are useful for debugging. (If you get X errors,
6510 make the connection synchronous, and use a debugger to set a
6511 breakpoint on `x_error_handler'. Your backtrace of the C stack
6512 will now be useful. In asynchronous mode, the stack above
6513 `x_error_handler' isn't helpful because of buffering.) If DEVICE
6514 is not specified, the selected device is assumed.
6516 Calling this function is the same as calling the C function
6517 `XSynchronize', or starting the program with the `-sync' command
6520 - Variable: x-debug-events
6521 If non-zero, debug information about events that XEmacs sees is
6522 displayed. Information is displayed on stderr. Currently defined
6525 * 1 == non-verbose output
6527 * 2 == verbose output
6530 File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
6537 * XEmacs ToolTalk API Summary::
6538 * Sending Messages::
6539 * Receiving Messages::
6542 File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
6544 XEmacs ToolTalk API Summary
6545 ===========================
6547 The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
6548 to the standard C ToolTalk API. Only the message and pattern parts of
6549 the API are supported at present; more of the API could be added if
6550 needed. The Lisp interface departs from the C API in a few ways:
6552 * ToolTalk is initialized automatically at XEmacs startup-time.
6553 Messages can only be sent other ToolTalk applications connected to
6554 the same X11 server that XEmacs is running on.
6556 * There are fewer entry points; polymorphic functions with keyword
6557 arguments are used instead.
6559 * The callback interface is simpler and marginally less functional.
6560 A single callback may be associated with a message or a pattern;
6561 the callback is specified with a Lisp symbol (the symbol should
6562 have a function binding).
6564 * The session attribute for messages and patterns is always
6565 initialized to the default session.
6567 * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
6568 can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
6569 simplifies building lists that represent messages and patterns.
6572 File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
6579 * Example of Sending Messages::
6580 * Elisp Interface for Sending Messages::
6583 File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
6585 Example of Sending Messages
6586 ---------------------------
6588 Here's a simple example that sends a query to another application and
6589 then displays its reply. Both the query and the reply are stored in
6590 the first argument of the message.
6592 (defun tooltalk-random-query-handler (msg)
6593 (let ((state (get-tooltalk-message-attribute msg 'state)))
6595 ((eq state 'TT_HANDLED)
6596 (message (get-tooltalk-message-attribute msg arg_val 0)))
6597 ((memq state '(TT_FAILED TT_REJECTED))
6598 (message "Random query turns up nothing")))))
6600 (defvar random-query-message
6603 address TT_PROCEDURE
6605 args '((TT_INOUT "?" "string"))
6606 callback tooltalk-random-query-handler))
6608 (let ((m (make-tooltalk-message random-query-message)))
6609 (send-tooltalk-message m))
6612 File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
6614 Elisp Interface for Sending Messages
6615 ------------------------------------
6617 - Function: make-tooltalk-message attributes
6618 Create a ToolTalk message and initialize its attributes. The
6619 value of ATTRIBUTES must be a list of alternating keyword/values,
6620 where keywords are symbols that name valid message attributes.
6623 (make-tooltalk-message
6626 address TT_PROCEDURE
6628 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
6630 Values must always be strings, integers, or symbols that represent
6631 ToolTalk constants. Attribute names are the same as those
6632 supported by `set-tooltalk-message-attribute', plus `args'.
6634 The value of `args' should be a list of message arguments where
6635 each message argument has the following form:
6637 `(mode [value [type]])' or just `value'
6639 Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
6640 a string. If TYPE isn't specified then `int' is used if VALUE is
6641 a number; otherwise `string' is used. If TYPE is `string' then
6642 VALUE is converted to a string (if it isn't a string already) with
6643 `prin1-to-string'. If only a value is specified then MODE
6644 defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
6645 don't need to be specified. You can find out more about the
6646 semantics and uses of ToolTalk message arguments in chapter 4 of
6647 the `ToolTalk Programmer's Guide'.
6650 - Function: send-tooltalk-message msg
6651 Send the message on its way. Once the message has been sent it's
6652 almost always a good idea to get rid of it with
6653 `destroy-tooltalk-message'.
6656 - Function: return-tooltalk-message msg &optional mode
6657 Send a reply to this message. The second argument can be `reply',
6658 `reject' or `fail'; the default is `reply'. Before sending a
6659 reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
6660 should have been filled in--see `set-tooltalk-message-attribute'.
6663 - Function: get-tooltalk-message-attribute msg attribute &optional argn
6664 Returns the indicated ToolTalk message attribute. Attributes are
6665 identified by symbols with the same name (underscores and all) as
6666 the suffix of the ToolTalk `tt_message_<attribute>' function that
6667 extracts the value. String attribute values are copied and
6668 enumerated type values (except disposition) are converted to
6669 symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
6670 represented by fixnums (small integers), `opnum' is converted to a
6671 string, and `disposition' is converted to a fixnum. We convert
6672 `opnum' (a C int) to a string (e.g. `123' => `"123"') because
6673 there's no guarantee that opnums will fit within the range of
6674 XEmacs Lisp integers.
6676 [TBD] Use the `plist' attribute instead of C API `user' attribute
6677 for user-defined message data. To retrieve the value of a message
6678 property, specify the indicator for ARGN. For example, to get the
6679 value of a property called `rflag', use
6681 (get-tooltalk-message-attribute msg 'plist 'rflag)
6683 To get the value of a message argument use one of the `arg_val'
6684 (strings), `arg_ival' (integers), or `arg_bval' (strings with
6685 embedded nulls), attributes. For example, to get the integer
6686 value of the third argument:
6688 (get-tooltalk-message-attribute msg 'arg_ival 2)
6690 As you can see, argument numbers are zero-based. The type of each
6691 arguments can be retrieved with the `arg_type' attribute; however
6692 ToolTalk doesn't define any semantics for the string value of
6693 `arg_type'. Conventionally `string' is used for strings and `int'
6694 for 32 bit integers. Note that XEmacs Lisp stores the lengths of
6695 strings explicitly (unlike C) so treating the value returned by
6696 `arg_bval' like a string is fine.
6699 - Function: set-tooltalk-message-attribute value msg attribute
6701 Initialize one ToolTalk message attribute.
6703 Attribute names and values are the same as for
6704 `get-tooltalk-message-attribute'. A property list is provided for
6705 user data (instead of the `user' message attribute); see
6706 `get-tooltalk-message-attribute'.
6708 Callbacks are handled slightly differently than in the C ToolTalk
6709 API. The value of CALLBACK should be the name of a function of one
6710 argument. It will be called each time the state of the message
6711 changes. This is usually used to notice when the message's state
6712 has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
6713 argument values can be used.
6715 If one of the argument attributes is specified as `arg_val',
6716 `arg_ival', or `arg_bval', then ARGN must be the number of an
6717 already created argument. Arguments can be added to a message
6718 with `add-tooltalk-message-arg'.
6721 - Function: add-tooltalk-message-arg msg mode type &optional value
6722 Append one new argument to the message. MODE must be one of
6723 `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
6724 can be a string or an integer. ToolTalk doesn't define any
6725 semantics for TYPE, so only the participants in the protocol
6726 you're using need to agree what types mean (if anything).
6727 Conventionally `string' is used for strings and `int' for 32 bit
6728 integers. Arguments can initialized by providing a value or with
6729 `set-tooltalk-message-attribute'; the latter is necessary if you
6730 want to initialize the argument with a string that can contain
6731 embedded nulls (use `arg_bval').
6734 - Function: create-tooltalk-message &optional no-callback
6735 Create a new ToolTalk message. The message's session attribute is
6736 initialized to the default session. Other attributes can be
6737 initialized with `set-tooltalk-message-attribute'.
6738 `make-tooltalk-message' is the preferred way to create and
6739 initialize a message.
6741 Optional arg NO-CALLBACK says don't add a C-level callback at all.
6742 Normally don't do that; just don't specify the Lisp callback when
6743 calling `make-tooltalk-message'.
6746 - Function: destroy-tooltalk-message msg
6747 Apply `tt_message_destroy' to the message. It's not necessary to
6748 destroy messages after they've been processed by a message or
6749 pattern callback, the Lisp/ToolTalk callback machinery does this
6753 File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
6760 * Example of Receiving Messages::
6761 * Elisp Interface for Receiving Messages::
6764 File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
6766 Example of Receiving Messages
6767 -----------------------------
6769 Here's a simple example of a handler for a message that tells XEmacs to
6770 display a string in the mini-buffer area. The message operation is
6771 called `emacs-display-string'. Its first (0th) argument is the string
6774 (defun tooltalk-display-string-handler (msg)
6775 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
6777 (defvar display-string-pattern
6778 '(category TT_HANDLE
6780 op "emacs-display-string"
6781 callback tooltalk-display-string-handler))
6783 (let ((p (make-tooltalk-pattern display-string-pattern)))
6784 (register-tooltalk-pattern p))
6787 File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
6789 Elisp Interface for Receiving Messages
6790 --------------------------------------
6792 - Function: make-tooltalk-pattern attributes
6793 Create a ToolTalk pattern and initialize its attributes. The
6794 value of attributes must be a list of alternating keyword/values,
6795 where keywords are symbols that name valid pattern attributes or
6796 lists of valid attributes. For example:
6798 (make-tooltalk-pattern
6799 '(category TT_OBSERVE
6801 op ("operation1" "operation2")
6802 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
6804 Attribute names are the same as those supported by
6805 `add-tooltalk-pattern-attribute', plus `'args'.
6807 Values must always be strings, integers, or symbols that represent
6808 ToolTalk constants or lists of same. When a list of values is
6809 provided all of the list elements are added to the attribute. In
6810 the example above, messages whose `op' attribute is `"operation1"'
6811 or `"operation2"' would match the pattern.
6813 The value of ARGS should be a list of pattern arguments where each
6814 pattern argument has the following form:
6816 `(mode [value [type]])' or just `value'
6818 Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
6819 a string. If TYPE isn't specified then `int' is used if VALUE is
6820 a number; otherwise `string' is used. If TYPE is `string' then
6821 VALUE is converted to a string (if it isn't a string already) with
6822 `prin1-to-string'. If only a value is specified then MODE
6823 defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
6824 don't need to be specified. You can find out more about the
6825 semantics and uses of ToolTalk pattern arguments in chapter 3 of
6826 the `ToolTalk Programmer's Guide'.
6829 - Function: register-tooltalk-pattern pattern
6830 XEmacs will begin receiving messages that match this pattern.
6832 - Function: unregister-tooltalk-pattern pattern
6833 XEmacs will stop receiving messages that match this pattern.
6835 - Function: add-tooltalk-pattern-attribute value pattern indicator
6836 Add one value to the indicated pattern attribute. The names of
6837 attributes are the same as the ToolTalk accessors used to set them
6838 less the `tooltalk_pattern_' prefix and the `_add' suffix. For
6839 example, the name of the attribute for the
6840 `tt_pattern_disposition_add' attribute is `disposition'. The
6841 `category' attribute is handled specially, since a pattern can only
6842 be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
6844 Callbacks are handled slightly differently than in the C ToolTalk
6845 API. The value of CALLBACK should be the name of a function of one
6846 argument. It will be called each time the pattern matches an
6849 - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value
6850 Add one fully-specified argument to a ToolTalk pattern. MODE must
6851 be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE must be a
6852 string. VALUE can be an integer, string or `nil'. If VALUE is an
6853 integer then an integer argument (`tt_pattern_iarg_add') is added;
6854 otherwise a string argument is added. At present there's no way
6855 to add a binary data argument.
6858 - Function: create-tooltalk-pattern
6859 Create a new ToolTalk pattern and initialize its session attribute
6860 to be the default session.
6862 - Function: destroy-tooltalk-pattern pattern
6863 Apply `tt_pattern_destroy' to the pattern. This effectively
6864 unregisters the pattern.
6866 - Function: describe-tooltalk-message msg &optional stream
6867 Print the message's attributes and arguments to STREAM. This is
6868 often useful for debugging.
6871 File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
6876 XEmacs can be linked with a LDAP client library to provide Elisp
6877 primitives to access directory servers using the Lightweight Directory
6882 * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
6883 * XEmacs LDAP API:: Lisp access to LDAP functions
6884 * Syntax of Search Filters:: A brief summary of RFC 1558
6887 File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
6889 Building XEmacs with LDAP support
6890 =================================
6892 LDAP support must be added to XEmacs at build time since it requires
6893 linking to an external LDAP client library. As of 21.2, XEmacs has been
6894 successfully built and tested with
6896 * OpenLDAP 1.2 (<http://www.openldap.org/>)
6898 * University of Michigan's LDAP 3.3
6899 (<http://www.umich.edu/~dirsvcs/ldap/>)
6901 * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
6903 Other libraries conforming to RFC 1823 will probably work also but
6904 may require some minor tweaking at C level.
6906 The standard XEmacs configure script auto-detects an installed LDAP
6907 library provided the library itself and the corresponding header files
6908 can be found in the library and include paths. A successful detection
6909 will be signalled in the final output of the configure script.
6912 File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
6917 XEmacs LDAP API consists of two layers: a low-level layer which tries
6918 to stay as close as possible to the C API (where practical) and a
6919 higher-level layer which provides more convenient primitives to
6920 effectively use LDAP.
6922 The low-level API should be used directly for very specific purposes
6923 (such as multiple operations on a connection) only. The higher-level
6924 functions provide a more convenient way to access LDAP directories
6925 hiding the subtleties of handling the connection, translating arguments
6926 and ensuring compliance with LDAP internationalization rules and formats
6927 (currently partly implemented only).
6931 * LDAP Variables:: Lisp variables related to LDAP
6932 * The High-Level LDAP API:: High-level LDAP lisp functions
6933 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
6934 * LDAP Internationalization:: I18n variables and functions
6937 File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
6942 - Variable: ldap-default-host
6943 The default LDAP server hostname. A TCP port number can be
6944 appended to that name using a colon as a separator.
6946 - Variable: ldap-default-port
6947 Default TCP port for LDAP connections. Initialized from the LDAP
6948 library. Default value is 389.
6950 - Variable: ldap-default-base
6951 Default base for LDAP searches. This is a string using the syntax
6952 of RFC 1779. For instance, "o=ACME, c=US" limits the search to the
6953 Acme organization in the United States.
6955 - Variable: ldap-host-parameters-alist
6956 An alist of per host options for LDAP transactions. The list
6957 elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
6958 name of an LDAP server. A TCP port number can be appended to that
6959 name using a colon as a separator. PROPN and VALN are
6960 property/value pairs describing parameters for the server. Valid
6963 The distinguished name of the user to bind as. This may look
6964 like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details.
6967 The password to use for authentication.
6970 The authentication method to use, possible values depend on
6971 the LDAP library XEmacs was compiled with, they may include
6972 `simple', `krbv41' and `krbv42'.
6975 The base for the search. This may look like `cÿ, o¬me', see
6976 RFC 1779 for syntax details.
6979 One of the symbols `base', `onelevel' or `subtree' indicating
6980 the scope of the search limited to a base object, to a single
6981 level or to the whole subtree.
6984 The dereference policy is one of the symbols `never',
6985 `always', `search' or `find' and defines how aliases are
6988 Aliases are never dereferenced
6991 Aliases are always dereferenced
6994 Aliases are dereferenced when searching
6997 Aliases are dereferenced when locating the base object
7001 The timeout limit for the connection in seconds.
7004 The maximum number of matches to return for searches
7005 performed on this connection.
7007 - Variable: ldap-verbose
7008 If non-`nil', LDAP operations will echo progress messages.
7012 File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
7014 The High-Level LDAP API
7015 -----------------------
7017 The following functions provide the most convenient interface to perform
7018 LDAP operations. All of them open a connection to a host, perform an
7019 operation (add/search/modify/delete) on one or several entries and
7020 cleanly close the connection thus insulating the user from all the
7021 details of the low-level interface such as LDAP Lisp objects *note The
7022 Low-Level LDAP API::.
7024 Note that `ldap-search' which used to be the name of the high-level
7025 search function in XEmacs 21.1 is now obsolete. For consistency in the
7026 naming as well as backward compatibility, that function now acts as a
7027 wrapper that calls either `ldap-search-basic' (low-level search
7028 function) or `ldap-search-entries' (high-level search function)
7029 according to the actual parameters. A direct call to one of these two
7030 functions is preferred since it is faster and unambiguous.
7032 - Command: ldap-search-entries filter &optional host attributes
7034 Perform an LDAP search. FILTER is the search filter *note Syntax
7035 of Search Filters:: HOST is the LDAP host on which to perform the
7036 search. ATTRIBUTES is the specific attributes to retrieve, `nil'
7037 means retrieve all. ATTRSONLY if non-`nil' retrieves the
7038 attributes only without their associated values. If WITHDN is
7039 non-`nil' each entry in the result will be prepended with its
7040 distinguished name DN. Additional search parameters can be
7041 specified through `ldap-host-parameters-alist'. The function
7042 returns a list of matching entries. Each entry is itself an alist
7043 of attribute/value pairs optionally preceded by the DN of the
7044 entry according to the value of WITHDN.
7046 - Function: ldap-add-entries entries &optional host binddn passwd
7047 Add entries to an LDAP directory. ENTRIES is a list of entry
7048 specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)'
7049 where DN the distinguished name of an entry to add, the following
7050 are cons cells containing attribute/value string pairs. HOST is
7051 the LDAP host, defaulting to `ldap-default-host'. BINDDN is the
7052 DN to bind as to the server. PASSWD is the corresponding password.
7054 - Function: ldap-modify-entries entry-mods &optional host binddn passwd
7055 Modify entries of an LDAP directory. ENTRY_MODS is a list of
7056 entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)'
7057 where DN is the distinguished name of the entry to modify, the
7058 following are modification specifications. A modification
7059 specification is itself a list of the form `(MOD-OP ATTR VALUE1
7060 VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
7061 depending on MOD-OP. MOD-OP is the type of modification, one of
7062 the symbols `add', `delete' or `replace'. ATTR is the LDAP
7063 attribute type to modify. HOST is the LDAP host, defaulting to
7064 `ldap-default-host'. BINDDN is the DN to bind as to the server.
7065 PASSWD is the corresponding password.
7067 - Function: ldap-delete-entries dn &optional host binddn passwd
7068 Delete an entry from an LDAP directory. DN is the distinguished
7069 name of an entry to delete or a list of those. HOST is the LDAP
7070 host, defaulting to `ldap-default-host'. BINDDN is the DN to bind
7071 as to the server. PASSWD is the corresponding password.
7074 File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
7076 The Low-Level LDAP API
7077 ----------------------
7079 The low-level API should be used directly for very specific purposes
7080 (such as multiple operations on a connection) only. The higher-level
7081 functions provide a more convenient way to access LDAP directories
7082 hiding the subtleties of handling the connection, translating arguments
7083 and ensuring compliance with LDAP internationalization rules and formats
7084 (currently partly implemented only). See *note The High-Level LDAP API::
7086 Note that the former functions `ldap-*-internal' functions have been
7087 renamed in XEmacs 21.2
7091 * The LDAP Lisp Object::
7092 * Opening and Closing a LDAP Connection::
7093 * Low-level Operations on a LDAP Server::
projects / chise / xemacs-chise.git.1 / blob