1 This is ../info/lispref.info, produced by makeinfo version 4.0 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: 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 contains
60 a number of specifications describing how the image should appear in a
61 variety of circumstances. These specifications are called "image
62 instantiators". When XEmacs wants to display the image, it instantiates
63 the image into an "image instance". Image instances are their own
64 primitive object type (similar to font instances and color instances),
65 describing how the image appears in a particular domain. (On the other
66 hand, image instantiators, which are just descriptions of how the image
67 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. *Note Specifiers::.
78 Note that, in practice, you rarely, if ever, need to actually
79 create an image specifier! (This function exists mainly for
80 completeness.) Pretty much the only use for image specifiers is to
81 control how glyphs are displayed, and the image specifier
82 associated with a glyph (the `image' property of a glyph) is
83 created automatically when a glyph is created and need not (and
84 cannot, for that matter) ever be changed (*note Glyphs::). In
85 fact, the design decision to create a separate image specifier
86 type, rather than make glyphs themselves be specifiers, is
87 debatable--the other properties of glyphs are rarely used and could
88 conceivably have been incorporated into the glyph's instantiator.
89 The rarely used glyph types (buffer, pointer, icon) could also
90 have been incorporated into the instantiator.
92 Image instantiators come in many formats: `xbm', `xpm', `gif',
93 `jpeg', etc. This describes the format of the data describing the
94 image. The resulting image instances also come in many
95 types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
96 refers to the behavior of the image and the sorts of places it can
97 appear. (For example, a color-pixmap image has fixed colors specified
98 for it, while a mono-pixmap image comes in two unspecified shades
99 "foreground" and "background" that are determined from the face of the
100 glyph or surrounding text; a text image appears as a string of text and
101 has an unspecified foreground, background, and font; a pointer image
102 behaves like a mono-pixmap image but can only be used as a mouse
103 pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
104 is important to keep the distinction between image instantiator format
105 and image instance type in mind. Typically, a given image instantiator
106 format can result in many different image instance types (for example,
107 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
108 whereas `cursor-font' can be instanced only as `pointer'), and a
109 particular image instance type can be generated by many different image
110 instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
111 `gif', `jpeg', etc.).
113 *Note Image Instances::, for a more detailed discussion of image
116 An image instantiator should be a string or a vector of the form
118 `[FORMAT :KEYWORD VALUE ...]'
120 i.e. a format symbol followed by zero or more alternating
121 keyword-value pairs. The "format" field should be a symbol, one of
124 Don't display anything; no keywords are valid for this. Can only
125 be instanced as `nothing'.
128 Display this image as a text string. Can only be instanced as
129 `text', although support for instancing as `mono-pixmap' should be
133 Display this image as a text string with replaceable fields,
134 similar to a modeline format string; not currently implemented.
137 An X bitmap; only if X support was compiled into this XEmacs. Can
138 be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
141 An XPM pixmap; only if XPM support was compiled into this XEmacs.
142 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
143 XPM is an add-on library for X that was designed to rectify the
144 shortcomings of the XBM format. Most implementations of X include
145 the XPM library as a standard part. If your vendor does not, it
146 is highly recommended that you download it and install it. You
147 can get it from the standard XEmacs FTP site, among other places.
150 An X-Face bitmap, used to encode people's faces in e-mail messages;
151 only if X-Face support was compiled into this XEmacs. Can be
152 instanced as `mono-pixmap', `color-pixmap', or `pointer'.
155 A GIF87 or GIF89 image; only if GIF support was compiled into this
156 XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
157 includes GIF decoding functions as a standard part of it, so if
158 you have X support, you will normally have GIF support, unless you
159 explicitly disable it at configure time.
162 A JPEG-format image; only if JPEG support was compiled into this
163 XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
164 libraries present on your system when XEmacs is built, XEmacs will
165 automatically detect this and use them, unless you explicitly
166 disable it at configure time.
169 A PNG/GIF24 image; only if PNG support was compiled into this
170 XEmacs. Can be instanced as `color-pixmap'.
173 A TIFF-format image; only if TIFF support was compiled into this
177 One of the standard cursor-font names, such as `watch' or
178 `right_ptr' under X. Under X, this is, more specifically, any of
179 the standard cursor names from appendix B of the Xlib manual [also
180 known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
181 other window systems, the valid names will be specific to the type
182 of window system. Can only be instanced as `pointer'.
185 A glyph from a font; i.e. the name of a font, and glyph index into
186 it of the form `FONT fontname index [[mask-font] mask-index]'.
187 Only if X support was compiled into this XEmacs. Currently can
188 only be instanced as `pointer', although this should probably be
192 An MS Windows pointer resource. Specifies a resource to retrieve
193 directly from the system (an OEM resource) or from a file,
194 particularly an executable file. If the resource is to be
195 retrieved from a file, use :file and optionally :resource-id.
196 Otherwise use :resource-id. Always specify :resource-type to
197 specify the type (cursor, bitmap or icon) of the resource.
198 Possible values for :resource-id are listed below. Can be
199 instanced as `pointer' or `color-pixmap'.
202 An embedded windowing system window. Can only be instanced as
206 A button widget; either a push button, radio button or toggle
207 button. Can only be instanced as `widget'.
210 A drop list of selectable items in a widget, for editing text.
211 Can only be instanced as `widget'.
214 A text editing widget. Can only be instanced as `widget'.
217 A static, text-only, widget; for displaying text. Can only be
218 instanced as `widget'.
221 A widget for controlling the positioning of children underneath it.
222 Through the use of nested layouts, a widget hierarchy can be
223 created which can have the appearance of any standard dialog box
224 or similar arrangement; all of this is counted as one "glyph" and
225 could appear in many of the places that expect a single glyph.
226 Can only be instanced as `widget'.
229 The native version of a layout widget. Can only be instanced as
233 A sliding widget, for showing progress. Can only be instanced as
237 A tab widget; a series of user selectable tabs. Can only be
238 instanced as `widget'.
241 A folding widget. Can only be instanced as `widget'.
244 A scrollbar widget. Can only be instanced as `widget'.
247 XEmacs tries to guess what format the data is in. If X support
248 exists, the data string will be checked to see if it names a
249 filename. If so, and this filename contains XBM or XPM data, the
250 appropriate sort of pixmap or pointer will be created. [This
251 includes picking up any specified hotspot or associated mask
252 file.] Otherwise, if `pointer' is one of the allowable
253 image-instance types and the string names a valid cursor-font
254 name, the image will be created as a pointer. Otherwise, the
255 image will be displayed as text. If no X support exists, the
256 image will always be displayed as text.
259 Inherit from the background-pixmap property of a face. Can only be
260 instanced as `mono-pixmap'.
262 The valid keywords are:
265 Inline data. For most formats above, this should be a string. For
266 XBM images, this should be a list of three elements: width,
267 height, and a string of bit data. This keyword is not valid for
268 instantiator format `nothing'.
271 Data is contained in a file. The value is the name of this file.
272 If both `:data' and `:file' are specified, the image is created
273 from what is specified in `:data' and the string in `:file'
274 becomes the value of the `image-instance-file-name' function when
275 applied to the resulting image-instance. This keyword is not
276 valid for instantiator formats `nothing', `string',
277 `formatted-string', `cursor-font', `font', and `autodetect'.
281 For `xbm', `xface', `cursor-font', and `font'. These keywords
282 allow you to explicitly specify foreground and background colors.
283 The argument should be anything acceptable to
284 `make-color-instance'. This will cause what would be a
285 `mono-pixmap' to instead be colorized as a two-color color-pixmap,
286 and specifies the foreground and/or background colors for a pointer
287 instead of black and white.
290 For `xbm' and `xface'. This specifies a mask to be used with the
291 bitmap. The format is a list of width, height, and bits, like for
295 For `xbm' and `xface'. This specifies a file containing the mask
296 data. If neither a mask file nor inline mask data is given for an
297 XBM image, and the XBM image comes from a file, XEmacs will look
298 for a mask file with the same name as the image file but with
299 `Mask' or `msk' appended. For example, if you specify the XBM file
300 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
301 associated mask file `left_ptrmsk' will automatically be picked up.
305 For `xbm' and `xface'. These keywords specify a hotspot if the
306 image is instantiated as a `pointer'. Note that if the XBM image
307 file specifies a hotspot, it will automatically be picked up if no
308 explicit hotspot is given.
311 Only for `xpm'. This specifies an alist that maps strings that
312 specify symbolic color names to the actual color to be used for
313 that symbolic color (in the form of a string or a color-specifier
314 object). If this is not specified, the contents of
315 `xpm-color-symbols' are used to generate the alist.
318 Only for `mswindows-resource'. This must be either an integer
319 (which directly specifies a resource number) or a string. Valid
324 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
325 "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
326 "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
327 "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
328 "check", "checkboxes", and "btncorners".
332 "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
333 "sizewe", "sizens", "sizeall", and "no".
337 "sample", "hand", "ques", "bang", "note", and "winlogo".
340 Only for `mswindows-resource'. This must be a symbol, either
341 `cursor', `icon', or `bitmap', specifying the type of resource to
345 Only for `inherit'. This specifies the face to inherit from. For
346 widgets this also specifies the face to use for display. It
347 defaults to gui-element-face.
349 Keywords accepted as menu item specs are also accepted by widgets.
350 These are `:selected', `:active', `:suffix', `:keys', `:style',
351 `:filter', `:config', `:included', `:key-sequence', `:accelerator',
352 `:label' and `:callback'.
354 If instead of a vector, the instantiator is a string, it will be
355 converted into a vector by looking it up according to the specs in the
356 `console-type-image-conversion-list' for the console type of the domain
357 (usually a window; sometimes a frame or device) over which the image is
360 If the instantiator specifies data from a file, the data will be
361 read in at the time that the instantiator is added to the image
362 specifier (which may be well before the image is actually displayed),
363 and the instantiator will be converted into one of the inline-data
364 forms, with the filename retained using a `:file' keyword. This
365 implies that the file must exist when the instantiator is added to the
366 image, but does not need to exist at any other time (e.g. it may safely
367 be a temporary file).
369 - Function: valid-image-instantiator-format-p format
370 This function returns non-`nil' if FORMAT is a valid image
371 instantiator format. Note that the return value for many formats
372 listed above depends on whether XEmacs was compiled with support
375 - Function: image-instantiator-format-list
376 This function return a list of valid image-instantiator formats.
378 - Variable: xpm-color-symbols
379 This variable holds definitions of logical color-names used when
380 reading XPM files. Elements of this list should be of the form
381 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
382 string, which is the name of the color to define; the
383 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
384 string to be passed to `make-color-instance' (*note Colors::). If
385 a loaded XPM file references a symbolic color called COLOR-NAME,
386 it will display as the computed color instead.
388 The default value of this variable defines the logical color names
389 `"foreground"' and `"background"' to be the colors of the
392 - Variable: x-bitmap-file-path
393 A list of the directories in which X bitmap files may be found.
394 If nil, this is initialized from the `"*bitmapFilePath"' resource.
395 This is used by the `make-image-instance' function (however, note
396 that if the environment variable `XBMLANGPATH' is set, it is
400 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
402 Image Instantiator Conversion
403 -----------------------------
405 - Function: set-console-type-image-conversion-list console-type list
406 This function sets the image-conversion-list for consoles of the
407 given CONSOLE-TYPE. The image-conversion-list specifies how image
408 instantiators that are strings should be interpreted. Each
409 element of the list should be a list of two elements (a regular
410 expression string and a vector) or a list of three elements (the
411 preceding two plus an integer index into the vector). The string
412 is converted to the vector associated with the first matching
413 regular expression. If a vector index is specified, the string
414 itself is substituted into that position in the vector.
416 Note: The conversion above is applied when the image instantiator
417 is added to an image specifier, not when the specifier is actually
418 instantiated. Therefore, changing the image-conversion-list only
419 affects newly-added instantiators. Existing instantiators in
420 glyphs and image specifiers will not be affected.
422 - Function: console-type-image-conversion-list console-type
423 This function returns the image-conversion-list for consoles of
424 the given CONSOLE-TYPE.
427 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
432 Image-instance objects encapsulate the way a particular image
433 (pixmap, etc.) is displayed on a particular device.
435 In most circumstances, you do not need to directly create image
436 instances; use a glyph instead. However, it may occasionally be useful
437 to explicitly create image instances, if you want more control over the
438 instantiation process.
440 - Function: image-instance-p object
441 This function returns non-`nil' if OBJECT is an image instance.
445 * Image Instance Types:: Each image instances has a particular type.
446 * Image Instance Functions:: Functions for working with image instances.
449 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
454 Image instances come in a number of different types. The type of an
455 image instance specifies the nature of the image: Whether it is a text
456 string, a mono pixmap, a color pixmap, etc.
458 The valid image instance types are
461 Nothing is displayed.
464 Displayed as text. The foreground and background colors and the
465 font of the text are specified independent of the pixmap.
466 Typically these attributes will come from the face of the
467 surrounding text, unless a face is specified for the glyph in
468 which the image appears.
471 Displayed as a mono pixmap (a pixmap with only two colors where the
472 foreground and background can be specified independent of the
473 pixmap; typically the pixmap assumes the foreground and background
474 colors of the text around it, unless a face is specified for the
475 glyph in which the image appears).
478 Displayed as a color pixmap.
481 Used as the mouse pointer for a window.
484 A child window that is treated as an image. This allows (e.g.)
485 another program to be responsible for drawing into the window.
486 Not currently implemented.
488 - Function: valid-image-instance-type-p type
489 This function returns non-`nil' if TYPE is a valid image instance
492 - Function: image-instance-type-list
493 This function returns a list of the valid image instance types.
495 - Function: image-instance-type image-instance
496 This function returns the type of the given image instance. The
497 return value will be one of `nothing', `text', `mono-pixmap',
498 `color-pixmap', `pointer', or `subwindow'.
500 - Function: text-image-instance-p object
501 This function returns non-`nil' if OBJECT is an image instance of
504 - Function: mono-pixmap-image-instance-p object
505 This function returns non-`nil' if OBJECT is an image instance of
508 - Function: color-pixmap-image-instance-p object
509 This function returns non-`nil' if OBJECT is an image instance of
512 - Function: pointer-image-instance-p object
513 This function returns non-`nil' if OBJECT is an image instance of
516 - Function: subwindow-image-instance-p object
517 This function returns non-`nil' if OBJECT is an image instance of
520 - Function: nothing-image-instance-p object
521 This function returns non-`nil' if OBJECT is an image instance of
524 - Function: widget-image-instance-p object
525 Return t if OBJECT is an image instance of type `widget'.
528 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
530 Image Instance Functions
531 ........................
533 - Function: make-image-instance data &optional domain dest-types
535 This function creates a new image-instance object.
537 DATA is an image instantiator, which describes the image (*note
540 DEST-TYPES should be a list of allowed image instance types that
541 can be generated. The DEST-TYPES list is unordered. If multiple
542 destination types are possible for a given instantiator, the "most
543 natural" type for the instantiator's format is chosen. (For XBM,
544 the most natural types are `mono-pixmap', followed by
545 `color-pixmap', followed by `pointer'. For the other normal image
546 formats, the most natural types are `color-pixmap', followed by
547 `mono-pixmap', followed by `pointer'. For the string and
548 formatted-string formats, the most natural types are `text',
549 followed by `mono-pixmap' (not currently implemented), followed by
550 `color-pixmap' (not currently implemented). For MS Windows
551 resources, the most natural type for pointer resources is
552 `pointer', and for the others it's `color-pixmap'. The other
553 formats can only be instantiated as one type. (If you want to
554 control more specifically the order of the types into which an
555 image is instantiated, just call `make-image-instance' repeatedly
556 until it succeeds, passing less and less preferred destination
559 If DEST-TYPES is omitted, all possible types are allowed.
561 DOMAIN specifies the domain to which the image instance will be
562 attached. This domain is termed the "governing domain". The type
563 of the governing domain depends on the image instantiator format.
564 (Although, more correctly, it should probably depend on the image
565 instance type.) For example, pixmap image instances are specific
566 to a device, but widget image instances are specific to a
567 particular XEmacs window because in order to display such a widget
568 when two windows onto the same buffer want to display the widget,
569 two separate underlying widgets must be created. (That's because a
570 widget is actually a child window-system window, and all
571 window-system windows have a unique existence on the screen.) This
572 means that the governing domain for a pixmap image instance will
573 be some device (most likely, the only existing device), whereas
574 the governing domain for a widget image instance will be some
577 If you specify an overly general DOMAIN (e.g. a frame when a
578 window was wanted), an error is signaled. If you specify an overly
579 specific DOMAIN (e.g. a window when a device was wanted), the
580 corresponding general domain is fetched and used instead. For
581 `make-image-instance', it makes no difference whether you specify
582 an overly specific domain or the properly general domain derived
583 from it. However, it does matter when creating an image instance
584 by instantiating a specifier or glyph (e.g. with
585 `glyph-image-instance'), because the more specific domain causes
586 spec lookup to start there and proceed to more general domains. (It
587 would also matter when creating an image instance with an
588 instantiator format of `inherit', but we currently disallow this.
589 #### We should fix this.) n If omitted, DOMAIN defaults to the
592 NO-ERROR controls what happens when the image cannot be generated.
593 If NIL, an error message is generated. If T, no messages are
594 generated and this function returns NIL. If anything else, a
595 warning message is generated and this function returns NIL.
597 - Function: colorize-image-instance image-instance foreground
599 This function makes the image instance be displayed in the given
600 colors. Image instances come in two varieties: bitmaps, which are
601 1 bit deep which are rendered in the prevailing foreground and
602 background colors; and pixmaps, which are of arbitrary depth
603 (including 1) and which have the colors explicitly specified.
604 This function converts a bitmap to a pixmap. If the image
605 instance was a pixmap already, nothing is done (and `nil' is
606 returned). Otherwise `t' is returned.
608 - Function: image-instance-name image-instance
609 This function returns the name of the given image instance.
611 - Function: image-instance-domain image-instance
612 Return the governing domain of the given IMAGE-INSTANCE. The
613 governing domain of an image instance is the domain that the image
614 instance is specific to. It is _NOT_ necessarily the domain that
615 was given to the call to `specifier-instance' that resulted in the
616 creation of this image instance. See `make-image-instance' for
617 more information on governing domains.
619 - Function: image-instance-string image-instance
620 This function returns the string of the given image instance.
621 This will only be non-`nil' for text image instances.
623 - Function: image-instance-file-name image-instance
624 This function returns the file name from which IMAGE-INSTANCE was
627 - Function: image-instance-mask-file-name image-instance
628 This function returns the file name from which IMAGE-INSTANCE's
629 mask was read, if known.
631 - Function: image-instance-depth image-instance
632 This function returns the depth of the image instance. This is 0
633 for a mono pixmap, or a positive integer for a color pixmap.
635 - Function: image-instance-height image-instance
636 This function returns the height of the image instance, in pixels.
638 - Function: image-instance-width image-instance
639 This function returns the width of the image instance, in pixels.
641 - Function: image-instance-hotspot-x image-instance
642 This function returns the X coordinate of the image instance's
643 hotspot, if known. This is a point relative to the origin of the
644 pixmap. When an image is used as a mouse pointer, the hotspot is
645 the point on the image that sits over the location that the
646 pointer points to. This is, for example, the tip of the arrow or
647 the center of the crosshairs.
649 This will always be `nil' for a non-pointer image instance.
651 - Function: image-instance-hotspot-y image-instance
652 This function returns the Y coordinate of the image instance's
655 - Function: image-instance-foreground image-instance
656 This function returns the foreground color of IMAGE-INSTANCE, if
657 applicable. This will be a color instance or `nil'. (It will only
658 be non-`nil' for colorized mono pixmaps and for pointers.)
660 - Function: image-instance-background image-instance
661 This function returns the background color of IMAGE-INSTANCE, if
662 applicable. This will be a color instance or `nil'. (It will only
663 be non-`nil' for colorized mono pixmaps and for pointers.)
666 File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
671 Each glyph has a particular type, which controls how the glyph's
672 image is generated. Each glyph type has a corresponding list of
673 allowable image instance types that can be generated. When you call
674 `glyph-image-instance' to retrieve the image instance of a glyph,
675 XEmacs does the equivalent of calling `make-image-instance' and passing
676 in DEST-TYPES the list of allowable image instance types for the
679 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
680 extent, in the modeline, and in the toolbar. Their image can be
681 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
684 * `pointer' glyphs can be used to specify the mouse pointer. Their
685 image can be instantiated as `pointer'.
687 * `icon' glyphs can be used to specify the icon used when a frame is
688 iconified. Their image can be instantiated as `mono-pixmap' and
691 - Function: glyph-type glyph
692 This function returns the type of the given glyph. The return
693 value will be a symbol, one of `buffer', `pointer', or `icon'.
695 - Function: valid-glyph-type-p glyph-type
696 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
698 - Function: glyph-type-list
699 This function returns a list of valid glyph types.
701 - Function: buffer-glyph-p object
702 This function returns non-`nil' if OBJECT is a glyph of type
705 - Function: icon-glyph-p object
706 This function returns non-`nil' if OBJECT is a glyph of type
709 - Function: pointer-glyph-p object
710 This function returns non-`nil' if OBJECT is a glyph of type
714 File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
719 The shape of the mouse pointer when over a particular section of a
720 frame is controlled using various glyph variables. Since the image of
721 a glyph is a specifier, it can be controlled on a per-buffer,
722 per-frame, per-window, or per-device basis.
724 You should use `set-glyph-image' to set the following variables,
727 - Glyph: text-pointer-glyph
728 This variable specifies the shape of the mouse pointer when over
731 - Glyph: nontext-pointer-glyph
732 This variable specifies the shape of the mouse pointer when over a
733 buffer, but not over text. If unspecified in a particular domain,
734 `text-pointer-glyph' is used.
736 - Glyph: modeline-pointer-glyph
737 This variable specifies the shape of the mouse pointer when over
738 the modeline. If unspecified in a particular domain,
739 `nontext-pointer-glyph' is used.
741 - Glyph: selection-pointer-glyph
742 This variable specifies the shape of the mouse pointer when over a
743 selectable text region. If unspecified in a particular domain,
744 `text-pointer-glyph' is used.
746 - Glyph: gc-pointer-glyph
747 This variable specifies the shape of the mouse pointer when a
748 garbage collection is in progress. If the selected window is on a
749 window system and this glyph specifies a value (i.e. a pointer
750 image instance) in the domain of the selected window, the pointer
751 will be changed as specified during garbage collection.
752 Otherwise, a message will be printed in the echo area, as
753 controlled by `gc-message'.
755 - Glyph: busy-pointer-glyph
756 This variable specifies the shape of the mouse pointer when XEmacs
757 is busy. If unspecified in a particular domain, the pointer is
758 not changed when XEmacs is busy.
760 - Glyph: menubar-pointer-glyph
761 This variable specifies the shape of the mouse pointer when over
762 the menubar. If unspecified in a particular domain, the
763 window-system-provided default pointer is used.
765 - Glyph: scrollbar-pointer-glyph
766 This variable specifies the shape of the mouse pointer when over a
767 scrollbar. If unspecified in a particular domain, the
768 window-system-provided default pointer is used.
770 - Glyph: toolbar-pointer-glyph
771 This variable specifies the shape of the mouse pointer when over a
772 toolbar. If unspecified in a particular domain,
773 `nontext-pointer-glyph' is used.
775 Internally, these variables are implemented in
776 `default-mouse-motion-handler', and thus only take effect when the
777 mouse moves. That function calls `set-frame-pointer', which sets the
778 current mouse pointer for a frame.
780 - Function: set-frame-pointer frame image-instance
781 This function sets the mouse pointer of FRAME to the given pointer
782 image instance. You should not call this function directly. (If
783 you do, the pointer will change again the next time the mouse
787 File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
792 - Glyph: truncation-glyph
793 This variable specifies what is displayed at the end of truncated
796 - Glyph: continuation-glyph
797 This variable specifies what is displayed at the end of wrapped
800 - Glyph: octal-escape-glyph
801 This variable specifies what to prefix character codes displayed
804 - Glyph: hscroll-glyph
805 This variable specifies what to display at the beginning of
806 horizontally scrolled lines.
808 - Glyph: invisible-text-glyph
809 This variable specifies what to use to indicate the presence of
810 invisible text. This is the glyph that is displayed when an
811 ellipsis is called for, according to `selective-display-ellipses'
812 or `buffer-invisibility-spec'). Normally this is three dots
815 - Glyph: control-arrow-glyph
816 This variable specifies what to use as an arrow for control
820 File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
825 Subwindows are not currently implemented.
827 - Function: subwindowp object
828 This function returns non-`nil' if OBJECT is a subwindow.
831 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
836 An "annotation" is a pixmap or string that is not part of a buffer's
837 text but is displayed next to a particular location in a buffer.
838 Annotations can be displayed intermixed with text, in any whitespace at
839 the beginning or end of a line, or in a special area at the left or
840 right side of the frame called a "margin", whose size is controllable.
841 Annotations are implemented using extents (*note Extents::); but you
842 can work with annotations without knowing how extents work.
846 * Annotation Basics:: Introduction to annotations.
847 * Annotation Primitives:: Creating and deleting annotations.
848 * Annotation Properties:: Retrieving and changing the characteristics
850 * Margin Primitives:: Controlling the size of the margins.
851 * Locating Annotations:: Looking for annotations in a buffer.
852 * Annotation Hooks:: Hooks called at certain times during an
853 annotation's lifetime.
856 File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
861 Marginal annotations are notes associated with a particular location
862 in a buffer. They may be displayed in a margin created on the
863 left-hand or right-hand side of the frame, in any whitespace at the
864 beginning or end of a line, or inside of the text itself. Every
865 annotation may have an associated action to be performed when the
866 annotation is selected. The term "annotation" is used to refer to an
867 individual note. The term "margin" is generically used to refer to the
868 whitespace before the first character on a line or after the last
871 Each annotation has the following characteristics:
873 This is a glyph object and is used as the displayed representation
877 If given, this glyph is used as the displayed representation of
878 the annotation when the mouse is pressed down over the annotation.
881 The face with which to display the glyph.
884 Which side of the text (left or right) the annotation is displayed
888 If non-`nil', this field must contain a function capable of being
889 the first argument to `funcall'. This function is normally
890 evaluated with a single argument, the value of the DATA field,
891 each time the annotation is selected. However, if the WITH-EVENT
892 parameter to `make-annotation' is non-`nil', the function is
893 called with two arguments. The first argument is the same as
894 before, and the second argument is the event (a button-up event,
895 usually) that activated the annotation.
898 Not used internally. This field can contain any E-Lisp object.
899 It is passed as the first argument to ACTION described above.
902 A menu displayed when the right mouse button is pressed over the
905 The margin is divided into "outside" and "inside". The outside
906 margin is space on the left or right side of the frame which normal text
907 cannot be displayed in. The inside margin is that space between the
908 leftmost or rightmost point at which text can be displayed and where the
909 first or last character actually is.
911 There are four different "layout types" which affect the exact
912 location an annotation appears.
915 The annotation is placed in the outside margin area. as close as
916 possible to the edge of the frame. If the outside margin is not
917 wide enough for an annotation to fit, it is not displayed.
920 The annotation is placed in the inside margin area, as close as
921 possible to the edge of the frame. If the inside margin is not
922 wide enough for the annotation to fit, it will be displayed using
923 any available outside margin space if and only if the specifier
924 `use-left-overflow' or `use-right-overflow' (depending on which
925 side the annotation appears in) is non-`nil'.
928 The annotation is placed in the inside margin area, as close as
929 possible to the first or last non-whitespace character on a line.
930 If the inside margin is not wide enough for the annotation to fit,
931 it will be displayed if and only if the specifier
932 `use-left-overflow' or `use-right-overflow' (depending on which
933 side the annotation appears in) is non-`nil'.
936 The annotation is placed at the position it is inserted. It will
937 create enough space for itself inside of the text area. It does
938 not take up a place in the logical buffer, only in the display of
941 The current layout policy is that all `whitespace' annotations are
942 displayed first. Next, all `inside-margin' annotations are displayed
943 using any remaining space. Finally as many `outside-margin'
944 annotations are displayed as possible. The `text' annotations will
945 always display as they create their own space to display in.
948 File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
950 Annotation Primitives
951 =====================
953 - Function: make-annotation glyph &optional position layout buffer
954 with-event d-glyph rightp
955 This function creates a marginal annotation at position POS in
956 BUFFER. The annotation is displayed using GLYPH, which should be
957 a glyph object or a string, and is positioned using layout policy
958 LAYOUT. If POS is `nil', point is used. If LAYOUT is `nil',
959 `whitespace' is used. If BUFFER is `nil', the current buffer is
962 If WITH-EVENT is non-`nil', then when an annotation is activated,
963 the triggering event is passed as the second arg to the annotation
964 function. If D-GLYPH is non-`nil' then it is used as the glyph
965 that will be displayed when button1 is down. If RIGHTP is
966 non-`nil' then the glyph will be displayed on the right side of
967 the buffer instead of the left.
969 The newly created annotation is returned.
971 - Function: delete-annotation annotation
972 This function removes ANNOTATION from its buffer. This does not
973 modify the buffer text.
975 - Function: annotationp annotation
976 This function returns `t' if ANNOTATION is an annotation, `nil'
980 File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
982 Annotation Properties
983 =====================
985 - Function: annotation-glyph annotation
986 This function returns the glyph object used to display ANNOTATION.
988 - Function: set-annotation-glyph annotation glyph &optional layout side
989 This function sets the glyph of ANNOTATION to GLYPH, which should
990 be a glyph object. If LAYOUT is non-`nil', set the layout policy
991 of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
992 side of the buffer at which the annotation is displayed to the
993 given side. The new value of `annotation-glyph' is returned.
995 - Function: annotation-down-glyph annotation
996 This function returns the glyph used to display ANNOTATION when
997 the left mouse button is depressed on the annotation.
999 - Function: set-annotation-down-glyph annotation glyph
1000 This function returns the glyph used to display ANNOTATION when
1001 the left mouse button is depressed on the annotation to GLYPH,
1002 which should be a glyph object.
1004 - Function: annotation-face annotation
1005 This function returns the face associated with ANNOTATION.
1007 - Function: set-annotation-face annotation face
1008 This function sets the face associated with ANNOTATION to FACE.
1010 - Function: annotation-layout annotation
1011 This function returns the layout policy of ANNOTATION.
1013 - Function: set-annotation-layout annotation layout
1014 This function sets the layout policy of ANNOTATION to LAYOUT.
1016 - Function: annotation-side annotation
1017 This function returns the side of the buffer that ANNOTATION is
1018 displayed on. Return value is a symbol, either `left' or `right'.
1020 - Function: annotation-data annotation
1021 This function returns the data associated with ANNOTATION.
1023 - Function: set-annotation-data annotation data
1024 This function sets the data field of ANNOTATION to DATA. DATA is
1027 - Function: annotation-action annotation
1028 This function returns the action associated with ANNOTATION.
1030 - Function: set-annotation-action annotation action
1031 This function sets the action field of ANNOTATION to ACTION.
1032 ACTION is returned..
1034 - Function: annotation-menu annotation
1035 This function returns the menu associated with ANNOTATION.
1037 - Function: set-annotation-menu annotation menu
1038 This function sets the menu associated with ANNOTATION to MENU.
1039 This menu will be displayed when the right mouse button is pressed
1040 over the annotation.
1042 - Function: annotation-visible annotation
1043 This function returns `t' if there is enough available space to
1044 display ANNOTATION, `nil' otherwise.
1046 - Function: annotation-width annotation
1047 This function returns the width of ANNOTATION in pixels.
1049 - Function: hide-annotation annotation
1050 This function removes ANNOTATION's glyph, making it invisible.
1052 - Function: reveal-annotation annotation
1053 This function restores ANNOTATION's glyph, making it visible.
1056 File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
1058 Locating Annotations
1059 ====================
1061 - Function: annotations-in-region start end buffer
1062 This function returns a list of all annotations in BUFFER which
1063 are between START and END inclusively.
1065 - Function: annotations-at &optional position buffer
1066 This function returns a list of all annotations at POSITION in
1067 BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
1068 the current buffer is used.
1070 - Function: annotation-list &optional buffer
1071 This function returns a list of all annotations in BUFFER. If
1072 BUFFER is `nil', the current buffer is used.
1074 - Function: all-annotations
1075 This function returns a list of all annotations in all buffers in
1079 File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
1084 The margin widths are controllable on a buffer-local, window-local,
1085 frame-local, device-local, or device-type-local basis through the use
1086 of specifiers. *Note Specifiers::.
1088 - Specifier: left-margin-width
1089 This is a specifier variable controlling the width of the left
1090 outside margin, in characters. Use `set-specifier' to change its
1093 - Specifier: right-margin-width
1094 This is a specifier variable controlling the width of the right
1095 outside margin, in characters. Use `set-specifier' to change its
1098 - Specifier: use-left-overflow
1099 If non-`nil', use the left outside margin as extra whitespace when
1100 displaying `whitespace' and `inside-margin' annotations. Defaults
1101 to `nil'. This is a specifier variable; use `set-specifier' to
1104 - Specifier: use-right-overflow
1105 If non-`nil', use the right outside margin as extra whitespace when
1106 displaying `whitespace' and `inside-margin' annotations. Defaults
1107 to `nil'. This is a specifier variable; use `set-specifier' to
1110 - Function: window-left-margin-pixel-width &optional window
1111 This function returns the width in pixels of the left outside
1112 margin of WINDOW. If WINDOW is `nil', the selected window is
1115 - Function: window-right-margin-pixel-width &optional window
1116 This function returns the width in pixels of the right outside
1117 margin of WINDOW. If WINDOW is `nil', the selected window is
1120 The margin colors are controlled by the faces `left-margin' and
1121 `right-margin'. These can be set using the X resources
1122 `Emacs.left-margin.background' and `Emacs.left-margin.foreground';
1123 likewise for the right margin.
1126 File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
1131 The following three hooks are provided for use with the marginal
1134 `before-delete-annotation-hook'
1135 This hook is called immediately before an annotation is destroyed.
1136 It is passed a single argument, the annotation being destroyed.
1138 `after-delete-annotation-hook'
1139 This normal hook is called immediately after an annotation is
1142 `make-annotation-hook'
1143 This hook is called immediately after an annotation is created.
1144 It is passed a single argument, the newly created annotation.
1147 File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
1152 This chapter describes a number of other features related to the
1153 display that XEmacs presents to the user.
1157 * Refresh Screen:: Clearing the screen and redrawing everything on it.
1158 * Truncation:: Folding or wrapping long text lines.
1159 * The Echo Area:: Where messages are displayed.
1160 * Warnings:: Display of Warnings.
1161 * Invisible Text:: Hiding part of the buffer text.
1162 * Selective Display:: Hiding part of the buffer text (the old way).
1163 * Overlay Arrow:: Display of an arrow to indicate position.
1164 * Temporary Displays:: Displays that go away automatically.
1165 * Blinking:: How XEmacs shows the matching open parenthesis.
1166 * Usual Display:: The usual conventions for displaying nonprinting chars.
1167 * Display Tables:: How to specify other conventions.
1168 * Beeping:: Audible signal to the user.
1171 File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
1173 Refreshing the Screen
1174 =====================
1176 The function `redraw-frame' redisplays the entire contents of a
1177 given frame. *Note Frames::.
1179 - Function: redraw-frame frame
1180 This function clears and redisplays frame FRAME.
1182 Even more powerful is `redraw-display':
1184 - Command: redraw-display &optional device
1185 This function redraws all frames on DEVICE marked as having their
1186 image garbled. DEVICE defaults to the selected device. If DEVICE
1187 is `t', all devices will have their frames checked.
1189 Processing user input takes absolute priority over redisplay. If you
1190 call these functions when input is available, they do nothing
1191 immediately, but a full redisplay does happen eventually--after all the
1192 input has been processed.
1194 Normally, suspending and resuming XEmacs also refreshes the screen.
1195 Some terminal emulators record separate contents for display-oriented
1196 programs such as XEmacs and for ordinary sequential display. If you are
1197 using such a terminal, you might want to inhibit the redisplay on
1198 resumption. *Note Suspending XEmacs::.
1200 - Variable: no-redraw-on-reenter
1201 This variable controls whether XEmacs redraws the entire screen
1202 after it has been suspended and resumed. Non-`nil' means yes,
1205 The above functions do not actually cause the display to be updated;
1206 rather, they clear out the internal display records that XEmacs
1207 maintains, so that the next time the display is updated it will be
1208 redrawn from scratch. Normally this occurs the next time that
1209 `next-event' or `sit-for' is called; however, a display update will not
1210 occur if there is input pending. *Note Command Loop::.
1212 - Function: force-cursor-redisplay
1213 This function causes an immediate update of the cursor on the
1214 selected frame. (This function does not exist in FSF Emacs.)
projects / chise / xemacs-chise.git- / blob