1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
58 An image specifier is used to describe the actual image of a glyph.
59 It works like other specifiers (*note Specifiers::.), in that it
60 contains a number of specifications describing how the image should
61 appear in a variety of circumstances. These specifications are called
62 "image instantiators". When XEmacs wants to display the image, it
63 instantiates the image into an "image instance". Image instances are
64 their own primitive object type (similar to font instances and color
65 instances), describing how the image appears in a particular domain.
66 (On the other hand, image instantiators, which are just descriptions of
67 how the image should appear, are represented using strings or vectors.)
69 - Function: image-specifier-p OBJECT
70 This function returns non-`nil' if OBJECT is an image specifier.
71 Usually, an image specifier results from calling `glyph-image' on
74 - Function: make-image-specifier SPEC-LIST
75 This function creates a new image specifier object and initializes
76 it according to SPEC-LIST. It is unlikely that you will ever want
77 to do this, but this function is provided for completeness and for
78 experimentation purposes. *Note Specifiers::.
80 Image instantiators come in many formats: `xbm', `xpm', `gif',
81 `jpeg', etc. This describes the format of the data describing the
82 image. The resulting image instances also come in many types -
83 `mono-pixmap', `color-pixmap', `text', `pointer', etc. This refers to
84 the behavior of the image and the sorts of places it can appear. (For
85 example, a color-pixmap image has fixed colors specified for it, while
86 a mono-pixmap image comes in two unspecified shades "foreground" and
87 "background" that are determined from the face of the glyph or
88 surrounding text; a text image appears as a string of text and has an
89 unspecified foreground, background, and font; a pointer image behaves
90 like a mono-pixmap image but can only be used as a mouse pointer
91 [mono-pixmap images cannot be used as mouse pointers]; etc.) It is
92 important to keep the distinction between image instantiator format and
93 image instance type in mind. Typically, a given image instantiator
94 format can result in many different image instance types (for example,
95 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
96 whereas `cursor-font' can be instanced only as `pointer'), and a
97 particular image instance type can be generated by many different image
98 instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
101 *Note Image Instances::, for a more detailed discussion of image
104 An image instantiator should be a string or a vector of the form
106 `[FORMAT :KEYWORD VALUE ...]'
108 i.e. a format symbol followed by zero or more alternating
109 keyword-value pairs. The "format" field should be a symbol, one of
112 (Don't display anything; no keywords are valid for this. Can only
113 be instanced as `nothing'.)
116 (Display this image as a text string. Can only be instanced as
117 `text', although support for instancing as `mono-pixmap' should be
121 (Display this image as a text string with replaceable fields,
122 similar to a modeline format string; not currently implemented.)
125 (An X bitmap; only if X support was compiled into this XEmacs.
126 Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
129 (An XPM pixmap; only if XPM support was compiled into this XEmacs.
130 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
131 XPM is an add-on library for X that was designed to rectify the
132 shortcomings of the XBM format. Most implementations of X include
133 the XPM library as a standard part. If your vendor does not, it
134 is highly recommended that you download it and install it. You
135 can get it from the standard XEmacs FTP site, among other places.)
138 (An X-Face bitmap, used to encode people's faces in e-mail
139 messages; only if X-Face support was compiled into this XEmacs.
140 Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
143 (A GIF87 or GIF89 image; only if GIF support was compiled into this
144 XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
145 includes GIF decoding functions as a standard part of it, so if
146 you have X support, you will normally have GIF support, unless you
147 explicitly disable it at configure time.)
150 (A JPEG-format image; only if JPEG support was compiled into this
151 XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
152 libraries present on your system when XEmacs is built, XEmacs will
153 automatically detect this and use them, unless you explicitly
154 disable it at configure time.)
157 (A PNG/GIF24 image; only if PNG support was compiled into this
158 XEmacs. Can be instanced as `color-pixmap'.)
161 (A TIFF-format image; only if TIFF support was compiled into this
162 XEmacs. Not currently implemented.)
165 (One of the standard cursor-font names, such as `watch' or
166 `right_ptr' under X. Under X, this is, more specifically, any of
167 the standard cursor names from appendix B of the Xlib manual [also
168 known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
169 other window systems, the valid names will be specific to the type
170 of window system. Can only be instanced as `pointer'.)
173 (A glyph from a font; i.e. the name of a font, and glyph index
174 into it of the form `FONT fontname index [[mask-font] mask-index]'.
175 Only if X support was compiled into this XEmacs. Currently can
176 only be instanced as `pointer', although this should probably be
180 (An embedded X window; not currently implemented.)
183 (XEmacs tries to guess what format the data is in. If X support
184 exists, the data string will be checked to see if it names a
185 filename. If so, and this filename contains XBM or XPM data, the
186 appropriate sort of pixmap or pointer will be created. [This
187 includes picking up any specified hotspot or associated mask
188 file.] Otherwise, if `pointer' is one of the allowable
189 image-instance types and the string names a valid cursor-font
190 name, the image will be created as a pointer. Otherwise, the
191 image will be displayed as text. If no X support exists, the
192 image will always be displayed as text.)
194 The valid keywords are:
197 (Inline data. For most formats above, this should be a string.
198 For XBM images, this should be a list of three elements: width,
199 height, and a string of bit data. This keyword is not valid for
200 instantiator format `nothing'.)
203 (Data is contained in a file. The value is the name of this file.
204 If both `:data' and `:file' are specified, the image is created
205 from what is specified in `:data' and the string in `:file'
206 becomes the value of the `image-instance-file-name' function when
207 applied to the resulting image-instance. This keyword is not
208 valid for instantiator formats `nothing', `string',
209 `formatted-string', `cursor-font', `font', and `autodetect'.)
213 (For `xbm', `xface', `cursor-font', and `font'. These keywords
214 allow you to explicitly specify foreground and background colors.
215 The argument should be anything acceptable to
216 `make-color-instance'. This will cause what would be a
217 `mono-pixmap' to instead be colorized as a two-color color-pixmap,
218 and specifies the foreground and/or background colors for a pointer
219 instead of black and white.)
222 (For `xbm' and `xface'. This specifies a mask to be used with the
223 bitmap. The format is a list of width, height, and bits, like for
227 (For `xbm' and `xface'. This specifies a file containing the mask
228 data. If neither a mask file nor inline mask data is given for an
229 XBM image, and the XBM image comes from a file, XEmacs will look
230 for a mask file with the same name as the image file but with
231 `Mask' or `msk' appended. For example, if you specify the XBM file
232 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
233 associated mask file `left_ptrmsk' will automatically be picked
238 (For `xbm' and `xface'. These keywords specify a hotspot if the
239 image is instantiated as a `pointer'. Note that if the XBM image
240 file specifies a hotspot, it will automatically be picked up if no
241 explicit hotspot is given.)
244 (Only for `xpm'. This specifies an alist that maps strings that
245 specify symbolic color names to the actual color to be used for
246 that symbolic color (in the form of a string or a color-specifier
247 object). If this is not specified, the contents of
248 `xpm-color-symbols' are used to generate the alist.)
250 If instead of a vector, the instantiator is a string, it will be
251 converted into a vector by looking it up according to the specs in the
252 `console-type-image-conversion-list' for the console type of the domain
253 (usually a window; sometimes a frame or device) over which the image is
256 If the instantiator specifies data from a file, the data will be
257 read in at the time that the instantiator is added to the image
258 specifier (which may be well before the image is actually displayed),
259 and the instantiator will be converted into one of the inline-data
260 forms, with the filename retained using a `:file' keyword. This
261 implies that the file must exist when the instantiator is added to the
262 image, but does not need to exist at any other time (e.g. it may safely
263 be a temporary file).
265 - Function: valid-image-instantiator-format-p FORMAT
266 This function returns non-`nil' if FORMAT is a valid image
267 instantiator format. Note that the return value for many formats
268 listed above depends on whether XEmacs was compiled with support
271 - Function: image-instantiator-format-list
272 This function return a list of valid image-instantiator formats.
274 - Variable: xpm-color-symbols
275 This variable holds definitions of logical color-names used when
276 reading XPM files. Elements of this list should be of the form
277 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
278 string, which is the name of the color to define; the
279 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
280 string to be passed to `make-color-instance' (*note Colors::.). If
281 a loaded XPM file references a symbolic color called COLOR-NAME,
282 it will display as the computed color instead.
284 The default value of this variable defines the logical color names
285 `"foreground"' and `"background"' to be the colors of the
288 - Variable: x-bitmap-file-path
289 A list of the directories in which X bitmap files may be found.
290 If nil, this is initialized from the `"*bitmapFilePath"' resource.
291 This is used by the `make-image-instance' function (however, note
292 that if the environment variable `XBMLANGPATH' is set, it is
296 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
298 Image Instantiator Conversion
299 -----------------------------
301 - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST
302 This function sets the image-conversion-list for consoles of the
303 given CONSOLE-TYPE. The image-conversion-list specifies how image
304 instantiators that are strings should be interpreted. Each
305 element of the list should be a list of two elements (a regular
306 expression string and a vector) or a list of three elements (the
307 preceding two plus an integer index into the vector). The string
308 is converted to the vector associated with the first matching
309 regular expression. If a vector index is specified, the string
310 itself is substituted into that position in the vector.
312 Note: The conversion above is applied when the image instantiator
313 is added to an image specifier, not when the specifier is actually
314 instantiated. Therefore, changing the image-conversion-list only
315 affects newly-added instantiators. Existing instantiators in
316 glyphs and image specifiers will not be affected.
318 - Function: console-type-image-conversion-list CONSOLE-TYPE
319 This function returns the image-conversion-list for consoles of
320 the given CONSOLE-TYPE.
323 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
328 Image-instance objects encapsulate the way a particular image
329 (pixmap, etc.) is displayed on a particular device.
331 In most circumstances, you do not need to directly create image
332 instances; use a glyph instead. However, it may occasionally be useful
333 to explicitly create image instances, if you want more control over the
334 instantiation process.
336 - Function: image-instance-p OBJECT
337 This function returns non-`nil' if OBJECT is an image instance.
341 * Image Instance Types:: Each image instances has a particular type.
342 * Image Instance Functions:: Functions for working with image instances.
345 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
350 Image instances come in a number of different types. The type of an
351 image instance specifies the nature of the image: Whether it is a text
352 string, a mono pixmap, a color pixmap, etc.
354 The valid image instance types are
357 Nothing is displayed.
360 Displayed as text. The foreground and background colors and the
361 font of the text are specified independent of the pixmap.
362 Typically these attributes will come from the face of the
363 surrounding text, unless a face is specified for the glyph in
364 which the image appears.
367 Displayed as a mono pixmap (a pixmap with only two colors where the
368 foreground and background can be specified independent of the
369 pixmap; typically the pixmap assumes the foreground and background
370 colors of the text around it, unless a face is specified for the
371 glyph in which the image appears).
374 Displayed as a color pixmap.
377 Used as the mouse pointer for a window.
380 A child window that is treated as an image. This allows (e.g.)
381 another program to be responsible for drawing into the window.
382 Not currently implemented.
384 - Function: valid-image-instance-type-p TYPE
385 This function returns non-`nil' if TYPE is a valid image instance
388 - Function: image-instance-type-list
389 This function returns a list of the valid image instance types.
391 - Function: image-instance-type IMAGE-INSTANCE
392 This function returns the type of the given image instance. The
393 return value will be one of `nothing', `text', `mono-pixmap',
394 `color-pixmap', `pointer', or `subwindow'.
396 - Function: text-image-instance-p OBJECT
397 This function returns non-`nil' if OBJECT is an image instance of
400 - Function: mono-pixmap-image-instance-p OBJECT
401 This function returns non-`nil' if OBJECT is an image instance of
404 - Function: color-pixmap-image-instance-p OBJECT
405 This function returns non-`nil' if OBJECT is an image instance of
408 - Function: pointer-image-instance-p OBJECT
409 This function returns non-`nil' if OBJECT is an image instance of
412 - Function: subwindow-image-instance-p OBJECT
413 This function returns non-`nil' if OBJECT is an image instance of
416 - Function: nothing-image-instance-p OBJECT
417 This function returns non-`nil' if OBJECT is an image instance of
421 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
423 Image Instance Functions
424 ........................
426 - Function: make-image-instance DATA &optional DEVICE DEST-TYPES
428 This function creates a new image-instance object.
430 DATA is an image instantiator, which describes the image (*note
431 Image Specifiers::.).
433 DEST-TYPES should be a list of allowed image instance types that
434 can be generated. The DEST-TYPES list is unordered. If multiple
435 destination types are possible for a given instantiator, the "most
436 natural" type for the instantiator's format is chosen. (For XBM,
437 the most natural types are `mono-pixmap', followed by
438 `color-pixmap', followed by `pointer'. For the other normal image
439 formats, the most natural types are `color-pixmap', followed by
440 `mono-pixmap', followed by `pointer'. For the string and
441 formatted-string formats, the most natural types are `text',
442 followed by `mono-pixmap' (not currently implemented), followed by
443 `color-pixmap' (not currently implemented). The other formats can
444 only be instantiated as one type. (If you want to control more
445 specifically the order of the types into which an image is
446 instantiated, just call `make-image-instance' repeatedly until it
447 succeeds, passing less and less preferred destination types each
450 If DEST-TYPES is omitted, all possible types are allowed.
452 NO-ERROR controls what happens when the image cannot be generated.
453 If NIL, an error message is generated. If T, no messages are
454 generated and this function returns NIL. If anything else, a
455 warning message is generated and this function returns NIL.
457 - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND
459 This function makes the image instance be displayed in the given
460 colors. Image instances come in two varieties: bitmaps, which are
461 1 bit deep which are rendered in the prevailing foreground and
462 background colors; and pixmaps, which are of arbitrary depth
463 (including 1) and which have the colors explicitly specified.
464 This function converts a bitmap to a pixmap. If the image
465 instance was a pixmap already, nothing is done (and `nil' is
466 returned). Otherwise `t' is returned.
468 - Function: image-instance-name IMAGE-INSTANCE
469 This function returns the name of the given image instance.
471 - Function: image-instance-string IMAGE-INSTANCE
472 This function returns the string of the given image instance.
473 This will only be non-`nil' for text image instances.
475 - Function: image-instance-file-name IMAGE-INSTANCE
476 This function returns the file name from which IMAGE-INSTANCE was
479 - Function: image-instance-mask-file-name IMAGE-INSTANCE
480 This function returns the file name from which IMAGE-INSTANCE's
481 mask was read, if known.
483 - Function: image-instance-depth IMAGE-INSTANCE
484 This function returns the depth of the image instance. This is 0
485 for a mono pixmap, or a positive integer for a color pixmap.
487 - Function: image-instance-height IMAGE-INSTANCE
488 This function returns the height of the image instance, in pixels.
490 - Function: image-instance-width IMAGE-INSTANCE
491 This function returns the width of the image instance, in pixels.
493 - Function: image-instance-hotspot-x IMAGE-INSTANCE
494 This function returns the X coordinate of the image instance's
495 hotspot, if known. This is a point relative to the origin of the
496 pixmap. When an image is used as a mouse pointer, the hotspot is
497 the point on the image that sits over the location that the
498 pointer points to. This is, for example, the tip of the arrow or
499 the center of the crosshairs.
501 This will always be `nil' for a non-pointer image instance.
503 - Function: image-instance-hotspot-y IMAGE-INSTANCE
504 This function returns the Y coordinate of the image instance's
507 - Function: image-instance-foreground IMAGE-INSTANCE
508 This function returns the foreground color of IMAGE-INSTANCE, if
509 applicable. This will be a color instance or `nil'. (It will only
510 be non-`nil' for colorized mono pixmaps and for pointers.)
512 - Function: image-instance-background IMAGE-INSTANCE
513 This function returns the background color of IMAGE-INSTANCE, if
514 applicable. This will be a color instance or `nil'. (It will only
515 be non-`nil' for colorized mono pixmaps and for pointers.)
518 File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
523 Each glyph has a particular type, which controls how the glyph's
524 image is generated. Each glyph type has a corresponding list of
525 allowable image instance types that can be generated. When you call
526 `glyph-image-instance' to retrieve the image instance of a glyph,
527 XEmacs does the equivalent of calling `make-image-instance' and passing
528 in DEST-TYPES the list of allowable image instance types for the
531 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
532 extent, in the modeline, and in the toolbar. Their image can be
533 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
536 * `pointer' glyphs can be used to specify the mouse pointer. Their
537 image can be instantiated as `pointer'.
539 * `icon' glyphs can be used to specify the icon used when a frame is
540 iconified. Their image can be instantiated as `mono-pixmap' and
543 - Function: glyph-type GLYPH
544 This function returns the type of the given glyph. The return
545 value will be a symbol, one of `buffer', `pointer', or `icon'.
547 - Function: valid-glyph-type-p GLYPH-TYPE
548 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
550 - Function: glyph-type-list
551 This function returns a list of valid glyph types.
553 - Function: buffer-glyph-p OBJECT
554 This function returns non-`nil' if OBJECT is a glyph of type
557 - Function: icon-glyph-p OBJECT
558 This function returns non-`nil' if OBJECT is a glyph of type
561 - Function: pointer-glyph-p OBJECT
562 This function returns non-`nil' if OBJECT is a glyph of type
566 File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
571 The shape of the mouse pointer when over a particular section of a
572 frame is controlled using various glyph variables. Since the image of
573 a glyph is a specifier, it can be controlled on a per-buffer,
574 per-frame, per-window, or per-device basis.
576 You should use `set-glyph-image' to set the following variables,
579 - Glyph: text-pointer-glyph
580 This variable specifies the shape of the mouse pointer when over
583 - Glyph: nontext-pointer-glyph
584 This variable specifies the shape of the mouse pointer when over a
585 buffer, but not over text. If unspecified in a particular domain,
586 `text-pointer-glyph' is used.
588 - Glyph: modeline-pointer-glyph
589 This variable specifies the shape of the mouse pointer when over
590 the modeline. If unspecified in a particular domain,
591 `nontext-pointer-glyph' is used.
593 - Glyph: selection-pointer-glyph
594 This variable specifies the shape of the mouse pointer when over a
595 selectable text region. If unspecified in a particular domain,
596 `text-pointer-glyph' is used.
598 - Glyph: gc-pointer-glyph
599 This variable specifies the shape of the mouse pointer when a
600 garbage collection is in progress. If the selected window is on a
601 window system and this glyph specifies a value (i.e. a pointer
602 image instance) in the domain of the selected window, the pointer
603 will be changed as specified during garbage collection.
604 Otherwise, a message will be printed in the echo area, as
605 controlled by `gc-message'.
607 - Glyph: busy-pointer-glyph
608 This variable specifies the shape of the mouse pointer when XEmacs
609 is busy. If unspecified in a particular domain, the pointer is
610 not changed when XEmacs is busy.
612 - Glyph: menubar-pointer-glyph
613 This variable specifies the shape of the mouse pointer when over
614 the menubar. If unspecified in a particular domain, the
615 window-system-provided default pointer is used.
617 - Glyph: scrollbar-pointer-glyph
618 This variable specifies the shape of the mouse pointer when over a
619 scrollbar. If unspecified in a particular domain, the
620 window-system-provided default pointer is used.
622 - Glyph: toolbar-pointer-glyph
623 This variable specifies the shape of the mouse pointer when over a
624 toolbar. If unspecified in a particular domain,
625 `nontext-pointer-glyph' is used.
627 Internally, these variables are implemented in
628 `default-mouse-motion-handler', and thus only take effect when the
629 mouse moves. That function calls `set-frame-pointer', which sets the
630 current mouse pointer for a frame.
632 - Function: set-frame-pointer FRAME IMAGE-INSTANCE
633 This function sets the mouse pointer of FRAME to the given pointer
634 image instance. You should not call this function directly. (If
635 you do, the pointer will change again the next time the mouse
639 File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
644 - Glyph: truncation-glyph
645 This variable specifies what is displayed at the end of truncated
648 - Glyph: continuation-glyph
649 This variable specifies what is displayed at the end of wrapped
652 - Glyph: octal-escape-glyph
653 This variable specifies what to prefix character codes displayed
656 - Glyph: hscroll-glyph
657 This variable specifies what to display at the beginning of
658 horizontally scrolled lines.
660 - Glyph: invisible-text-glyph
661 This variable specifies what to use to indicate the presence of
662 invisible text. This is the glyph that is displayed when an
663 ellipsis is called for, according to `selective-display-ellipses'
664 or `buffer-invisibility-spec'). Normally this is three dots
667 - Glyph: control-arrow-glyph
668 This variable specifies what to use as an arrow for control
672 File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
677 Subwindows are not currently implemented.
679 - Function: subwindowp OBJECT
680 This function returns non-`nil' if OBJECT is a subwindow.
683 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
688 An "annotation" is a pixmap or string that is not part of a buffer's
689 text but is displayed next to a particular location in a buffer.
690 Annotations can be displayed intermixed with text, in any whitespace at
691 the beginning or end of a line, or in a special area at the left or
692 right side of the frame called a "margin", whose size is controllable.
693 Annotations are implemented using extents (*note Extents::.); but you
694 can work with annotations without knowing how extents work.
698 * Annotation Basics:: Introduction to annotations.
699 * Annotation Primitives:: Creating and deleting annotations.
700 * Annotation Properties:: Retrieving and changing the characteristics
702 * Margin Primitives:: Controlling the size of the margins.
703 * Locating Annotations:: Looking for annotations in a buffer.
704 * Annotation Hooks:: Hooks called at certain times during an
705 annotation's lifetime.
708 File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
713 Marginal annotations are notes associated with a particular location
714 in a buffer. They may be displayed in a margin created on the
715 left-hand or right-hand side of the frame, in any whitespace at the
716 beginning or end of a line, or inside of the text itself. Every
717 annotation may have an associated action to be performed when the
718 annotation is selected. The term "annotation" is used to refer to an
719 individual note. The term "margin" is generically used to refer to the
720 whitespace before the first character on a line or after the last
723 Each annotation has the following characteristics:
725 This is a glyph object and is used as the displayed representation
729 If given, this glyph is used as the displayed representation of
730 the annotation when the mouse is pressed down over the annotation.
733 The face with which to display the glyph.
736 Which side of the text (left or right) the annotation is displayed
740 If non-`nil', this field must contain a function capable of being
741 the first argument to `funcall'. This function is normally
742 evaluated with a single argument, the value of the DATA field,
743 each time the annotation is selected. However, if the WITH-EVENT
744 parameter to `make-annotation' is non-`nil', the function is
745 called with two arguments. The first argument is the same as
746 before, and the second argument is the event (a button-up event,
747 usually) that activated the annotation.
750 Not used internally. This field can contain any E-Lisp object.
751 It is passed as the first argument to ACTION described above.
754 A menu displayed when the right mouse button is pressed over the
757 The margin is divided into "outside" and "inside". The outside
758 margin is space on the left or right side of the frame which normal text
759 cannot be displayed in. The inside margin is that space between the
760 leftmost or rightmost point at which text can be displayed and where the
761 first or last character actually is.
763 There are four different "layout types" which affect the exact
764 location an annotation appears.
767 The annotation is placed in the outside margin area. as close as
768 possible to the edge of the frame. If the outside margin is not
769 wide enough for an annotation to fit, it is not displayed.
772 The annotation is placed in the inside margin area, as close as
773 possible to the edge of the frame. If the inside margin is not
774 wide enough for the annotation to fit, it will be displayed using
775 any available outside margin space if and only if the specifier
776 `use-left-overflow' or `use-right-overflow' (depending on which
777 side the annotation appears in) is non-`nil'.
780 The annotation is placed in the inside margin area, as close as
781 possible to the first or last non-whitespace character on a line.
782 If the inside margin is not wide enough for the annotation to fit,
783 it will be displayed if and only if the specifier
784 `use-left-overflow' or `use-right-overflow' (depending on which
785 side the annotation appears in) is non-`nil'.
788 The annotation is placed at the position it is inserted. It will
789 create enough space for itself inside of the text area. It does
790 not take up a place in the logical buffer, only in the display of
793 The current layout policy is that all `whitespace' annotations are
794 displayed first. Next, all `inside-margin' annotations are displayed
795 using any remaining space. Finally as many `outside-margin'
796 annotations are displayed as possible. The `text' annotations will
797 always display as they create their own space to display in.
800 File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
802 Annotation Primitives
803 =====================
805 - Function: make-annotation GLYPH &optional POSITION LAYOUT BUFFER
806 WITH-EVENT D-GLYPH RIGHTP
807 This function creates a marginal annotation at position POS in
808 BUFFER. The annotation is displayed using GLYPH, which should be
809 a glyph object or a string, and is positioned using layout policy
810 LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
811 `whitespace' is used. If BUFFER is `nil', the current buffer is
814 If WITH-EVENT is non-`nil', then when an annotation is activated,
815 the triggering event is passed as the second arg to the annotation
816 function. If D-GLYPH is non-`nil' then it is used as the glyph
817 that will be displayed when button1 is down. If RIGHTP is
818 non-`nil' then the glyph will be displayed on the right side of
819 the buffer instead of the left.
821 The newly created annotation is returned.
823 - Function: delete-annotation ANNOTATION
824 This function removes ANNOTATION from its buffer. This does not
825 modify the buffer text.
827 - Function: annotationp ANNOTATION
828 This function returns `t' if ANNOTATION is an annotation, `nil'
832 File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
834 Annotation Properties
835 =====================
837 - Function: annotation-glyph ANNOTATION
838 This function returns the glyph object used to display ANNOTATION.
840 - Function: set-annotation-glyph ANNOTATION GLYPH &optional LAYOUT SIDE
841 This function sets the glyph of ANNOTATION to GLYPH, which should
842 be a glyph object. If LAYOUT is non-`nil', set the layout policy
843 of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
844 side of the buffer at which the annotation is displayed to the
845 given side. The new value of `annotation-glyph' is returned.
847 - Function: annotation-down-glyph ANNOTATION
848 This function returns the glyph used to display ANNOTATION when
849 the left mouse button is depressed on the annotation.
851 - Function: set-annotation-down-glyph ANNOTATION GLYPH
852 This function returns the glyph used to display ANNOTATION when
853 the left mouse button is depressed on the annotation to GLYPH,
854 which should be a glyph object.
856 - Function: annotation-face ANNOTATION
857 This function returns the face associated with ANNOTATION.
859 - Function: set-annotation-face ANNOTATION FACE
860 This function sets the face associated with ANNOTATION to FACE.
862 - Function: annotation-layout ANNOTATION
863 This function returns the layout policy of ANNOTATION.
865 - Function: set-annotation-layout ANNOTATION LAYOUT
866 This function sets the layout policy of ANNOTATION to LAYOUT.
868 - Function: annotation-side ANNOTATION
869 This function returns the side of the buffer that ANNOTATION is
870 displayed on. Return value is a symbol, either `left' or `right'.
872 - Function: annotation-data ANNOTATION
873 This function returns the data associated with ANNOTATION.
875 - Function: set-annotation-data ANNOTATION DATA
876 This function sets the data field of ANNOTATION to DATA. DATA is
879 - Function: annotation-action ANNOTATION
880 This function returns the action associated with ANNOTATION.
882 - Function: set-annotation-action ANNOTATION ACTION
883 This function sets the action field of ANNOTATION to ACTION.
886 - Function: annotation-menu ANNOTATION
887 This function returns the menu associated with ANNOTATION.
889 - Function: set-annotation-menu ANNOTATION MENU
890 This function sets the menu associated with ANNOTATION to MENU.
891 This menu will be displayed when the right mouse button is pressed
894 - Function: annotation-visible ANNOTATION
895 This function returns `t' if there is enough available space to
896 display ANNOTATION, `nil' otherwise.
898 - Function: annotation-width ANNOTATION
899 This function returns the width of ANNOTATION in pixels.
901 - Function: hide-annotation ANNOTATION
902 This function removes ANNOTATION's glyph, making it invisible.
904 - Function: reveal-annotation ANNOTATION
905 This function restores ANNOTATION's glyph, making it visible.
908 File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
913 - Function: annotations-in-region START END BUFFER
914 This function returns a list of all annotations in BUFFER which
915 are between START and END inclusively.
917 - Function: annotations-at &optional POSITION BUFFER
918 This function returns a list of all annotations at POSITION in
919 BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
920 the current buffer is used.
922 - Function: annotation-list &optional BUFFER
923 This function returns a list of all annotations in BUFFER. If
924 BUFFER is `nil', the current buffer is used.
926 - Function: all-annotations
927 This function returns a list of all annotations in all buffers in
931 File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
936 The margin widths are controllable on a buffer-local, window-local,
937 frame-local, device-local, or device-type-local basis through the use
938 of specifiers. *Note Specifiers::.
940 - Specifier: left-margin-width
941 This is a specifier variable controlling the width of the left
942 outside margin, in characters. Use `set-specifier' to change its
945 - Specifier: right-margin-width
946 This is a specifier variable controlling the width of the right
947 outside margin, in characters. Use `set-specifier' to change its
950 - Specifier: use-left-overflow
951 If non-`nil', use the left outside margin as extra whitespace when
952 displaying `whitespace' and `inside-margin' annotations. Defaults
953 to `nil'. This is a specifier variable; use `set-specifier' to
956 - Specifier: use-right-overflow
957 If non-`nil', use the right outside margin as extra whitespace when
958 displaying `whitespace' and `inside-margin' annotations. Defaults
959 to `nil'. This is a specifier variable; use `set-specifier' to
962 - Function: window-left-margin-pixel-width &optional WINDOW
963 This function returns the width in pixels of the left outside
964 margin of WINDOW. If WINDOW is `nil', the selected window is
967 - Function: window-right-margin-pixel-width &optional WINDOW
968 This function returns the width in pixels of the right outside
969 margin of WINDOW. If WINDOW is `nil', the selected window is
972 The margin colors are controlled by the faces `left-margin' and
973 `right-margin'. These can be set using the X resources
974 `Emacs.left-margin.background' and `Emacs.left-margin.foreground';
975 likewise for the right margin.
978 File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
983 The following three hooks are provided for use with the marginal
986 `before-delete-annotation-hook'
987 This hook is called immediately before an annotation is destroyed.
988 It is passed a single argument, the annotation being destroyed.
990 `after-delete-annotation-hook'
991 This normal hook is called immediately after an annotation is
994 `make-annotation-hook'
995 This hook is called immediately after an annotation is created.
996 It is passed a single argument, the newly created annotation.
999 File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
1004 This chapter describes a number of other features related to the
1005 display that XEmacs presents to the user.
1009 * Refresh Screen:: Clearing the screen and redrawing everything on it.
1010 * Truncation:: Folding or wrapping long text lines.
1011 * The Echo Area:: Where messages are displayed.
1012 * Warnings:: Display of Warnings.
1013 * Invisible Text:: Hiding part of the buffer text.
1014 * Selective Display:: Hiding part of the buffer text (the old way).
1015 * Overlay Arrow:: Display of an arrow to indicate position.
1016 * Temporary Displays:: Displays that go away automatically.
1017 * Blinking:: How XEmacs shows the matching open parenthesis.
1018 * Usual Display:: The usual conventions for displaying nonprinting chars.
1019 * Display Tables:: How to specify other conventions.
1020 * Beeping:: Audible signal to the user.
1023 File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
1025 Refreshing the Screen
1026 =====================
1028 The function `redraw-frame' redisplays the entire contents of a
1029 given frame. *Note Frames::.
1031 - Function: redraw-frame FRAME
1032 This function clears and redisplays frame FRAME.
1034 Even more powerful is `redraw-display':
1036 - Command: redraw-display &optional DEVICE
1037 This function redraws all frames on DEVICE marked as having their
1038 image garbled. DEVICE defaults to the selected device. If DEVICE
1039 is `t', all devices will have their frames checked.
1041 Processing user input takes absolute priority over redisplay. If you
1042 call these functions when input is available, they do nothing
1043 immediately, but a full redisplay does happen eventually--after all the
1044 input has been processed.
1046 Normally, suspending and resuming XEmacs also refreshes the screen.
1047 Some terminal emulators record separate contents for display-oriented
1048 programs such as XEmacs and for ordinary sequential display. If you are
1049 using such a terminal, you might want to inhibit the redisplay on
1050 resumption. *Note Suspending XEmacs::.
1052 - Variable: no-redraw-on-reenter
1053 This variable controls whether XEmacs redraws the entire screen
1054 after it has been suspended and resumed. Non-`nil' means yes,
1057 The above functions do not actually cause the display to be updated;
1058 rather, they clear out the internal display records that XEmacs
1059 maintains, so that the next time the display is updated it will be
1060 redrawn from scratch. Normally this occurs the next time that
1061 `next-event' or `sit-for' is called; however, a display update will not
1062 occur if there is input pending. *Note Command Loop::.
1064 - Function: force-cursor-redisplay
1065 This function causes an immediate update of the cursor on the
1066 selected frame. (This function does not exist in FSF Emacs.)
1069 File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
1074 When a line of text extends beyond the right edge of a window, the
1075 line can either be truncated or continued on the next line. When a line
1076 is truncated, this is normally shown with a `\' in the rightmost column
1077 of the window on X displays, and with a `$' on TTY devices. When a
1078 line is continued or "wrapped" onto the next line, this is shown with a
1079 curved arrow in the rightmost column of the window (or with a `\' on
1080 TTY devices). The additional screen lines used to display a long text
1081 line are called "continuation" lines.
1083 Normally, whenever line truncation is in effect for a particular
1084 window, a horizontal scrollbar is displayed in that window if the
1085 device supports scrollbars. *Note Scrollbars::.
1087 Note that continuation is different from filling; continuation
1088 happens on the screen only, not in the buffer contents, and it breaks a
1089 line precisely at the right margin, not at a word boundary. *Note
1092 - User Option: truncate-lines
1093 This buffer-local variable controls how XEmacs displays lines that
1094 extend beyond the right edge of the window. If it is non-`nil',
1095 then XEmacs does not display continuation lines; rather each line
1096 of text occupies exactly one screen line, and a backslash appears
1097 at the edge of any line that extends to or beyond the edge of the
1098 window. The default is `nil'.
1100 If the variable `truncate-partial-width-windows' is non-`nil',
1101 then truncation is always used for side-by-side windows (within one
1102 frame) regardless of the value of `truncate-lines'.
1104 - User Option: default-truncate-lines
1105 This variable is the default value for `truncate-lines', for
1106 buffers that do not have local values for it.
1108 - User Option: truncate-partial-width-windows
1109 This variable controls display of lines that extend beyond the
1110 right edge of the window, in side-by-side windows (*note Splitting
1111 Windows::.). If it is non-`nil', these lines are truncated;
1112 otherwise, `truncate-lines' says what to do with them.
1114 The backslash and curved arrow used to indicate truncated or
1115 continued lines are only defaults, and can be changed. These images
1116 are actually glyphs (*note Glyphs::.). XEmacs provides a great deal of
1117 flexibility in how glyphs can be controlled. (This differs from FSF
1118 Emacs, which uses display tables to control these images.)
1120 For details, *Note Redisplay Glyphs::.
projects / chise / xemacs-chise.git.1 / blob