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: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
58 A "color-instance object" is an object describing the way a color
59 specifier is instanced in a particular domain. Functions such as
60 `face-background-instance' return a color-instance object. For example,
62 (face-background-instance 'default (next-window))
63 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
65 The color-instance object returned describes the way the background
66 color of the `default' face is displayed in the next window after the
69 - Function: color-instance-p object
70 This function returns non-`nil' if OBJECT is a color-instance.
73 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
75 Color Instance Properties
76 -------------------------
78 - Function: color-instance-name color-instance
79 This function returns the name used to allocate COLOR-INSTANCE.
81 - Function: color-instance-rgb-components color-instance
82 This function returns a three element list containing the red,
83 green, and blue color components of COLOR-INSTANCE.
85 (color-instance-rgb-components
86 (face-background-instance 'default (next-window)))
87 => (65535 58596 46517)
90 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
92 Color Convenience Functions
93 ---------------------------
95 - Function: color-name color &optional domain
96 This function returns the name of the COLOR in the specified
97 DOMAIN, if any. COLOR should be a color specifier object and
98 DOMAIN is normally a window and defaults to the selected window if
99 omitted. This is equivalent to using `specifier-instance' and
100 applying `color-instance-name' to the result.
102 - Function: color-rgb-components color &optional domain
103 This function returns the RGB components of the COLOR in the
104 specified DOMAIN, if any. COLOR should be a color specifier
105 object and DOMAIN is normally a window and defaults to the
106 selected window if omitted. This is equivalent to using
107 `specifier-instance' and applying `color-instance-rgb-components'
110 (color-rgb-components (face-background 'default (next-window)))
111 => (65535 58596 46517)
114 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
119 A "glyph" is an object that is used for pixmaps and images of all
120 sorts, as well as for things that "act" like pixmaps, such as
121 non-textual strings ("annotations") displayed in a buffer or in the
122 margins. It is used in begin-glyphs and end-glyphs attached to extents,
123 marginal and textual annotations, overlay arrows (`overlay-arrow-*'
124 variables), toolbar buttons, mouse pointers, frame icons, truncation and
125 continuation markers, and the like. (Basically, any place there is an
126 image or something that acts like an image, there will be a glyph object
129 The actual image that is displayed (as opposed to its position or
130 clipping) is defined by an "image specifier" object contained within
131 the glyph. The separation between an image specifier object and a
132 glyph object is made because the glyph includes other properties than
133 just the actual image: e.g. the face it is displayed in (for text
134 images), the alignment of the image (when it is in a buffer), etc.
136 - Function: glyphp object
137 This function returns `t' if OBJECT is a glyph.
141 * Glyph Functions:: Functions for working with glyphs.
142 * Images:: Graphical images displayed in a frame.
143 * Glyph Types:: Each glyph has a particular type.
144 * Mouse Pointer:: Controlling the mouse pointer.
145 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
146 * Subwindows:: Inserting an externally-controlled subwindow
150 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
157 * Creating Glyphs:: Creating new glyphs.
158 * Glyph Properties:: Accessing and modifying a glyph's properties.
159 * Glyph Convenience Functions::
160 Convenience functions for accessing particular
161 properties of a glyph.
162 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
165 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
170 - Function: make-glyph &optional spec-list type
171 This function creates a new glyph object of type TYPE.
173 SPEC-LIST is used to initialize the glyph's image. It is
174 typically an image instantiator (a string or a vector; *Note Image
175 Specifiers::), but can also be a list of such instantiators (each
176 one in turn is tried until an image is successfully produced), a
177 cons of a locale (frame, buffer, etc.) and an instantiator, a list
178 of such conses, or any other form accepted by
179 `canonicalize-spec-list'. *Note Specifiers::, for more
180 information about specifiers.
182 TYPE specifies the type of the glyph, which specifies in which
183 contexts the glyph can be used, and controls the allowable image
184 types into which the glyph's image can be instantiated. TYPE
185 should be one of `buffer' (used for glyphs in an extent, the
186 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
187 for the mouse-pointer), or `icon' (used for a frame's icon), and
188 defaults to `buffer'. *Note Glyph Types::.
190 - Function: make-glyph-internal &optional type
191 This function creates a new, uninitialized glyph of type TYPE.
193 - Function: make-pointer-glyph &optional spec-list
194 This function is equivalent to calling `make-glyph' with a TYPE of
197 - Function: make-icon-glyph &optional spec-list
198 This function is equivalent to calling `make-glyph' with a TYPE of
202 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
207 Each glyph has a list of properties, which control all of the
208 aspects of the glyph's appearance. The following symbols have
212 The image used to display the glyph.
215 Percent above baseline that glyph is to be displayed. Only for
216 glyphs displayed inside of a buffer.
219 Whether the glyph contributes to the height of the line it's on.
220 Only for glyphs displayed inside of a buffer.
223 Face of this glyph (_not_ a specifier).
225 - Function: set-glyph-property glyph property value &optional locale
227 This function changes a property of a GLYPH.
229 For built-in properties, the actual value of the property is a
230 specifier and you cannot change this; but you can change the
231 specifications within the specifier, and that is what this
232 function will do. For user-defined properties, you can use this
233 function to either change the actual value of the property or, if
234 this value is a specifier, change the specifications within it.
236 If PROPERTY is a built-in property, the specifications to be added
237 to this property can be supplied in many different ways:
239 * If VALUE is a simple instantiator (e.g. a string naming a
240 pixmap filename) or a list of instantiators, then the
241 instantiator(s) will be added as a specification of the
242 property for the given LOCALE (which defaults to `global' if
245 * If VALUE is a list of specifications (each of which is a cons
246 of a locale and a list of instantiators), then LOCALE must be
247 `nil' (it does not make sense to explicitly specify a locale
248 in this case), and specifications will be added as given.
250 * If VALUE is a specifier (as would be returned by
251 `glyph-property' if no LOCALE argument is given), then some
252 or all of the specifications in the specifier will be added
253 to the property. In this case, the function is really
254 equivalent to `copy-specifier' and LOCALE has the same
255 semantics (if it is a particular locale, the specification
256 for the locale will be copied; if a locale type,
257 specifications for all locales of that type will be copied;
258 if `nil' or `all', then all specifications will be copied).
260 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
261 `append', `remove-tag-set-prepend', `remove-tag-set-append',
262 `remove-locale', `remove-locale-type', or `remove-all'. See
263 `copy-specifier' and `add-spec-to-specifier' for a description of
264 what each of these means. Most of the time, you do not need to
265 worry about this argument; the default behavior usually is fine.
267 In general, it is OK to pass an instance object (e.g. as returned
268 by `glyph-property-instance') as an instantiator in place of an
269 actual instantiator. In such a case, the instantiator used to
270 create that instance object will be used (for example, if you set
271 a font-instance object as the value of the `font' property, then
272 the font name used to create that object will be used instead).
273 If some cases, however, doing this conversion does not make sense,
274 and this will be noted in the documentation for particular types
277 If PROPERTY is not a built-in property, then this function will
278 simply set its value if LOCALE is `nil'. However, if LOCALE is
279 given, then this function will attempt to add VALUE as the
280 instantiator for the given LOCALE, using `add-spec-to-specifier'.
281 If the value of the property is not a specifier, it will
282 automatically be converted into a `generic' specifier.
284 - Function: glyph-property glyph property &optional locale
285 This function returns GLYPH's value of the given PROPERTY.
287 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
288 be returned. For built-in properties, this will be a specifier
289 object of a type appropriate to the property (e.g. a font or color
290 specifier). For other properties, this could be anything.
292 If LOCALE is supplied, then instead of returning the actual value,
293 the specification(s) for the given locale or locale type will be
294 returned. This will only work if the actual value of PROPERTY is
295 a specifier (this will always be the case for built-in properties,
296 but may or may not apply to user-defined properties). If the
297 actual value of PROPERTY is not a specifier, this value will
298 simply be returned regardless of LOCALE.
300 The return value will be a list of instantiators (e.g. vectors
301 specifying pixmap data), or a list of specifications, each of
302 which is a cons of a locale and a list of instantiators.
303 Specifically, if LOCALE is a particular locale (a buffer, window,
304 frame, device, or `global'), a list of instantiators for that
305 locale will be returned. Otherwise, if LOCALE is a locale type
306 (one of the symbols `buffer', `window', `frame', or `device'), the
307 specifications for all locales of that type will be returned.
308 Finally, if LOCALE is `all', the specifications for all locales of
309 all types will be returned.
311 The specifications in a specifier determine what the value of
312 PROPERTY will be in a particular "domain" or set of circumstances,
313 which is typically a particular Emacs window along with the buffer
314 it contains and the frame and device it lies within. The value is
315 derived from the instantiator associated with the most specific
316 locale (in the order buffer, window, frame, device, and `global')
317 that matches the domain in question. In other words, given a
318 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
319 will first be searched for a specification whose locale is the
320 buffer contained within that window; then for a specification
321 whose locale is the window itself; then for a specification whose
322 locale is the frame that the window is contained within; etc. The
323 first instantiator that is valid for the domain (usually this
324 means that the instantiator is recognized by the device [i.e. the
325 X server or TTY device] that the domain is on). The function
326 `glyph-property-instance' actually does all this, and is used to
327 determine how to display the glyph.
329 - Function: glyph-property-instance glyph property &optional domain
331 This function returns the instance of GLYPH's PROPERTY in the
334 Under most circumstances, DOMAIN will be a particular window, and
335 the returned instance describes how the specified property
336 actually is displayed for that window and the particular buffer in
337 it. Note that this may not be the same as how the property
338 appears when the buffer is displayed in a different window or
339 frame, or how the property appears in the same window if you
340 switch to another buffer in that window; and in those cases, the
341 returned instance would be different.
343 The returned instance is an image-instance object, and you can
344 query it using the appropriate image instance functions. For
345 example, you could use `image-instance-depth' to find out the
346 depth (number of color planes) of a pixmap displayed in a
347 particular window. The results might be different from the
348 results you would get for another window (perhaps the user
349 specified a different image for the frame that window is on; or
350 perhaps the same image was specified but the window is on a
351 different X server, and that X server has different color
352 capabilities from this one).
354 DOMAIN defaults to the selected window if omitted.
356 DOMAIN can be a frame or device, instead of a window. The value
357 returned for such a domain is used in special circumstances when a
358 more specific domain does not apply; for example, a frame value
359 might be used for coloring a toolbar, which is conceptually
360 attached to a frame rather than a particular window. The value is
361 also useful in determining what the value would be for a
362 particular window within the frame or device, if it is not
363 overridden by a more specific specification.
365 If PROPERTY does not name a built-in property, its value will
366 simply be returned unless it is a specifier object, in which case
367 it will be instanced using `specifier-instance'.
369 Optional arguments DEFAULT and NO-FALLBACK are the same as in
370 `specifier-instance'. *Note Specifiers::.
372 - Function: remove-glyph-property glyph property &optional locale
374 This function removes a property from a glyph. For built-in
375 properties, this is analogous to `remove-specifier'. *Note
376 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
377 TAG-SET, and EXACT-P arguments.
380 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
382 Glyph Convenience Functions
383 ---------------------------
385 The following functions are provided for working with specific
386 properties of a glyph. Note that these are exactly like calling the
387 general functions described above and passing in the appropriate value
390 Remember that if you want to determine the "value" of a specific
391 glyph property, you probably want to use the `*-instance' functions.
392 For example, to determine whether a glyph contributes to its line
393 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
394 latter will return a boolean specifier or a list of specifications, and
395 you probably aren't concerned with these.)
397 - Function: glyph-image glyph &optional locale
398 This function is equivalent to calling `glyph-property' with a
399 property of `image'. The return value will be an image specifier
400 if LOCALE is `nil' or omitted; otherwise, it will be a
401 specification or list of specifications.
403 - Function: set-glyph-image glyph spec &optional locale tag-set
405 This function is equivalent to calling `set-glyph-property' with a
408 - Function: glyph-image-instance glyph &optional domain default
410 This function returns the instance of GLYPH's image in the given
411 DOMAIN, and is equivalent to calling `glyph-property-instance'
412 with a property of `image'. The return value will be an image
415 Normally DOMAIN will be a window or `nil' (meaning the selected
416 window), and an instance object describing how the image appears
417 in that particular window and buffer will be returned.
419 - Function: glyph-contrib-p glyph &optional locale
420 This function is equivalent to calling `glyph-property' with a
421 property of `contrib-p'. The return value will be a boolean
422 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
423 specification or list of specifications.
425 - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
427 This function is equivalent to calling `set-glyph-property' with a
428 property of `contrib-p'.
430 - Function: glyph-contrib-p-instance glyph &optional domain default
432 This function returns whether the glyph contributes to its line
433 height in the given DOMAIN, and is equivalent to calling
434 `glyph-property-instance' with a property of `contrib-p'. The
435 return value will be either `nil' or `t'. (Normally DOMAIN will be
436 a window or `nil', meaning the selected window.)
438 - Function: glyph-baseline glyph &optional locale
439 This function is equivalent to calling `glyph-property' with a
440 property of `baseline'. The return value will be a specifier if
441 LOCALE is `nil' or omitted; otherwise, it will be a specification
442 or list of specifications.
444 - Function: set-glyph-baseline glyph spec &optional locale tag-set
446 This function is equivalent to calling `set-glyph-property' with a
447 property of `baseline'.
449 - Function: glyph-baseline-instance glyph &optional domain default
451 This function returns the instance of GLYPH's baseline value in
452 the given DOMAIN, and is equivalent to calling
453 `glyph-property-instance' with a property of `baseline'. The
454 return value will be an integer or `nil'.
456 Normally DOMAIN will be a window or `nil' (meaning the selected
457 window), and an instance object describing the baseline value
458 appears in that particular window and buffer will be returned.
460 - Function: glyph-face glyph
461 This function returns the face of GLYPH. (Remember, this is not a
462 specifier, but a simple property.)
464 - Function: set-glyph-face glyph face
465 This function changes the face of GLYPH to FACE.
468 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
473 - Function: glyph-width glyph &optional window
474 This function returns the width of GLYPH on WINDOW. This may not
475 be exact as it does not take into account all of the context that
478 - Function: glyph-ascent glyph &optional window
479 This function returns the ascent value of GLYPH on WINDOW. This
480 may not be exact as it does not take into account all of the
481 context that redisplay will.
483 - Function: glyph-descent glyph &optional window
484 This function returns the descent value of GLYPH on WINDOW. This
485 may not be exact as it does not take into account all of the
486 context that redisplay will.
488 - Function: glyph-height glyph &optional window
489 This function returns the height of GLYPH on WINDOW. (This is
490 equivalent to the sum of the ascent and descent values.) This may
491 not be exact as it does not take into account all of the context
495 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
502 * Image Specifiers:: Specifying how an image will appear.
503 * Image Instantiator Conversion::
504 Conversion is applied to image instantiators
505 at the time they are added to an
506 image specifier or at the time they
507 are passed to `make-image-instance'.
508 * Image Instances:: What an image specifier gets instanced as.
511 File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
516 An image specifier is used to describe the actual image of a glyph.
517 It works like other specifiers (*note Specifiers::), in that it contains
518 a number of specifications describing how the image should appear in a
519 variety of circumstances. These specifications are called "image
520 instantiators". When XEmacs wants to display the image, it instantiates
521 the image into an "image instance". Image instances are their own
522 primitive object type (similar to font instances and color instances),
523 describing how the image appears in a particular domain. (On the other
524 hand, image instantiators, which are just descriptions of how the image
525 should appear, are represented using strings or vectors.)
527 - Function: image-specifier-p object
528 This function returns non-`nil' if OBJECT is an image specifier.
529 Usually, an image specifier results from calling `glyph-image' on
532 - Function: make-image-specifier spec-list
533 This function creates a new image specifier object and initializes
534 it according to SPEC-LIST. It is unlikely that you will ever want
535 to do this, but this function is provided for completeness and for
536 experimentation purposes. *Note Specifiers::.
538 Image instantiators come in many formats: `xbm', `xpm', `gif',
539 `jpeg', etc. This describes the format of the data describing the
540 image. The resulting image instances also come in many
541 types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
542 refers to the behavior of the image and the sorts of places it can
543 appear. (For example, a color-pixmap image has fixed colors specified
544 for it, while a mono-pixmap image comes in two unspecified shades
545 "foreground" and "background" that are determined from the face of the
546 glyph or surrounding text; a text image appears as a string of text and
547 has an unspecified foreground, background, and font; a pointer image
548 behaves like a mono-pixmap image but can only be used as a mouse
549 pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
550 is important to keep the distinction between image instantiator format
551 and image instance type in mind. Typically, a given image instantiator
552 format can result in many different image instance types (for example,
553 `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
554 whereas `cursor-font' can be instanced only as `pointer'), and a
555 particular image instance type can be generated by many different image
556 instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
557 `gif', `jpeg', etc.).
559 *Note Image Instances::, for a more detailed discussion of image
562 An image instantiator should be a string or a vector of the form
564 `[FORMAT :KEYWORD VALUE ...]'
566 i.e. a format symbol followed by zero or more alternating
567 keyword-value pairs. The "format" field should be a symbol, one of
570 Don't display anything; no keywords are valid for this. Can only
571 be instanced as `nothing'.
574 Display this image as a text string. Can only be instanced as
575 `text', although support for instancing as `mono-pixmap' should be
579 Display this image as a text string with replaceable fields,
580 similar to a modeline format string; not currently implemented.
583 An X bitmap; only if X support was compiled into this XEmacs. Can
584 be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
587 An XPM pixmap; only if XPM support was compiled into this XEmacs.
588 Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
589 XPM is an add-on library for X that was designed to rectify the
590 shortcomings of the XBM format. Most implementations of X include
591 the XPM library as a standard part. If your vendor does not, it
592 is highly recommended that you download it and install it. You
593 can get it from the standard XEmacs FTP site, among other places.
596 An X-Face bitmap, used to encode people's faces in e-mail messages;
597 only if X-Face support was compiled into this XEmacs. Can be
598 instanced as `mono-pixmap', `color-pixmap', or `pointer'.
601 A GIF87 or GIF89 image; only if GIF support was compiled into this
602 XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
603 includes GIF decoding functions as a standard part of it, so if
604 you have X support, you will normally have GIF support, unless you
605 explicitly disable it at configure time.
608 A JPEG-format image; only if JPEG support was compiled into this
609 XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
610 libraries present on your system when XEmacs is built, XEmacs will
611 automatically detect this and use them, unless you explicitly
612 disable it at configure time.
615 A PNG/GIF24 image; only if PNG support was compiled into this
616 XEmacs. Can be instanced as `color-pixmap'.
619 A TIFF-format image; only if TIFF support was compiled into this
623 One of the standard cursor-font names, such as `watch' or
624 `right_ptr' under X. Under X, this is, more specifically, any of
625 the standard cursor names from appendix B of the Xlib manual [also
626 known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
627 other window systems, the valid names will be specific to the type
628 of window system. Can only be instanced as `pointer'.
631 A glyph from a font; i.e. the name of a font, and glyph index into
632 it of the form `FONT fontname index [[mask-font] mask-index]'.
633 Only if X support was compiled into this XEmacs. Currently can
634 only be instanced as `pointer', although this should probably be
638 An embedded X window; not currently implemented.
641 XEmacs tries to guess what format the data is in. If X support
642 exists, the data string will be checked to see if it names a
643 filename. If so, and this filename contains XBM or XPM data, the
644 appropriate sort of pixmap or pointer will be created. [This
645 includes picking up any specified hotspot or associated mask
646 file.] Otherwise, if `pointer' is one of the allowable
647 image-instance types and the string names a valid cursor-font
648 name, the image will be created as a pointer. Otherwise, the
649 image will be displayed as text. If no X support exists, the
650 image will always be displayed as text.
652 The valid keywords are:
655 Inline data. For most formats above, this should be a string. For
656 XBM images, this should be a list of three elements: width,
657 height, and a string of bit data. This keyword is not valid for
658 instantiator format `nothing'.
661 Data is contained in a file. The value is the name of this file.
662 If both `:data' and `:file' are specified, the image is created
663 from what is specified in `:data' and the string in `:file'
664 becomes the value of the `image-instance-file-name' function when
665 applied to the resulting image-instance. This keyword is not
666 valid for instantiator formats `nothing', `string',
667 `formatted-string', `cursor-font', `font', and `autodetect'.
671 For `xbm', `xface', `cursor-font', and `font'. These keywords
672 allow you to explicitly specify foreground and background colors.
673 The argument should be anything acceptable to
674 `make-color-instance'. This will cause what would be a
675 `mono-pixmap' to instead be colorized as a two-color color-pixmap,
676 and specifies the foreground and/or background colors for a pointer
677 instead of black and white.
680 For `xbm' and `xface'. This specifies a mask to be used with the
681 bitmap. The format is a list of width, height, and bits, like for
685 For `xbm' and `xface'. This specifies a file containing the mask
686 data. If neither a mask file nor inline mask data is given for an
687 XBM image, and the XBM image comes from a file, XEmacs will look
688 for a mask file with the same name as the image file but with
689 `Mask' or `msk' appended. For example, if you specify the XBM file
690 `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
691 associated mask file `left_ptrmsk' will automatically be picked up.
695 For `xbm' and `xface'. These keywords specify a hotspot if the
696 image is instantiated as a `pointer'. Note that if the XBM image
697 file specifies a hotspot, it will automatically be picked up if no
698 explicit hotspot is given.
701 Only for `xpm'. This specifies an alist that maps strings that
702 specify symbolic color names to the actual color to be used for
703 that symbolic color (in the form of a string or a color-specifier
704 object). If this is not specified, the contents of
705 `xpm-color-symbols' are used to generate the alist.
707 If instead of a vector, the instantiator is a string, it will be
708 converted into a vector by looking it up according to the specs in the
709 `console-type-image-conversion-list' for the console type of the domain
710 (usually a window; sometimes a frame or device) over which the image is
713 If the instantiator specifies data from a file, the data will be
714 read in at the time that the instantiator is added to the image
715 specifier (which may be well before the image is actually displayed),
716 and the instantiator will be converted into one of the inline-data
717 forms, with the filename retained using a `:file' keyword. This
718 implies that the file must exist when the instantiator is added to the
719 image, but does not need to exist at any other time (e.g. it may safely
720 be a temporary file).
722 - Function: valid-image-instantiator-format-p format
723 This function returns non-`nil' if FORMAT is a valid image
724 instantiator format. Note that the return value for many formats
725 listed above depends on whether XEmacs was compiled with support
728 - Function: image-instantiator-format-list
729 This function return a list of valid image-instantiator formats.
731 - Variable: xpm-color-symbols
732 This variable holds definitions of logical color-names used when
733 reading XPM files. Elements of this list should be of the form
734 `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
735 string, which is the name of the color to define; the
736 FORM-TO-EVALUATE should evaluate to a color specifier object, or a
737 string to be passed to `make-color-instance' (*note Colors::). If
738 a loaded XPM file references a symbolic color called COLOR-NAME,
739 it will display as the computed color instead.
741 The default value of this variable defines the logical color names
742 `"foreground"' and `"background"' to be the colors of the
745 - Variable: x-bitmap-file-path
746 A list of the directories in which X bitmap files may be found.
747 If nil, this is initialized from the `"*bitmapFilePath"' resource.
748 This is used by the `make-image-instance' function (however, note
749 that if the environment variable `XBMLANGPATH' is set, it is
753 File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
755 Image Instantiator Conversion
756 -----------------------------
758 - Function: set-console-type-image-conversion-list console-type list
759 This function sets the image-conversion-list for consoles of the
760 given CONSOLE-TYPE. The image-conversion-list specifies how image
761 instantiators that are strings should be interpreted. Each
762 element of the list should be a list of two elements (a regular
763 expression string and a vector) or a list of three elements (the
764 preceding two plus an integer index into the vector). The string
765 is converted to the vector associated with the first matching
766 regular expression. If a vector index is specified, the string
767 itself is substituted into that position in the vector.
769 Note: The conversion above is applied when the image instantiator
770 is added to an image specifier, not when the specifier is actually
771 instantiated. Therefore, changing the image-conversion-list only
772 affects newly-added instantiators. Existing instantiators in
773 glyphs and image specifiers will not be affected.
775 - Function: console-type-image-conversion-list console-type
776 This function returns the image-conversion-list for consoles of
777 the given CONSOLE-TYPE.
780 File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
785 Image-instance objects encapsulate the way a particular image
786 (pixmap, etc.) is displayed on a particular device.
788 In most circumstances, you do not need to directly create image
789 instances; use a glyph instead. However, it may occasionally be useful
790 to explicitly create image instances, if you want more control over the
791 instantiation process.
793 - Function: image-instance-p object
794 This function returns non-`nil' if OBJECT is an image instance.
798 * Image Instance Types:: Each image instances has a particular type.
799 * Image Instance Functions:: Functions for working with image instances.
802 File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
807 Image instances come in a number of different types. The type of an
808 image instance specifies the nature of the image: Whether it is a text
809 string, a mono pixmap, a color pixmap, etc.
811 The valid image instance types are
814 Nothing is displayed.
817 Displayed as text. The foreground and background colors and the
818 font of the text are specified independent of the pixmap.
819 Typically these attributes will come from the face of the
820 surrounding text, unless a face is specified for the glyph in
821 which the image appears.
824 Displayed as a mono pixmap (a pixmap with only two colors where the
825 foreground and background can be specified independent of the
826 pixmap; typically the pixmap assumes the foreground and background
827 colors of the text around it, unless a face is specified for the
828 glyph in which the image appears).
831 Displayed as a color pixmap.
834 Used as the mouse pointer for a window.
837 A child window that is treated as an image. This allows (e.g.)
838 another program to be responsible for drawing into the window.
839 Not currently implemented.
841 - Function: valid-image-instance-type-p type
842 This function returns non-`nil' if TYPE is a valid image instance
845 - Function: image-instance-type-list
846 This function returns a list of the valid image instance types.
848 - Function: image-instance-type image-instance
849 This function returns the type of the given image instance. The
850 return value will be one of `nothing', `text', `mono-pixmap',
851 `color-pixmap', `pointer', or `subwindow'.
853 - Function: text-image-instance-p object
854 This function returns non-`nil' if OBJECT is an image instance of
857 - Function: mono-pixmap-image-instance-p object
858 This function returns non-`nil' if OBJECT is an image instance of
861 - Function: color-pixmap-image-instance-p object
862 This function returns non-`nil' if OBJECT is an image instance of
865 - Function: pointer-image-instance-p object
866 This function returns non-`nil' if OBJECT is an image instance of
869 - Function: subwindow-image-instance-p object
870 This function returns non-`nil' if OBJECT is an image instance of
873 - Function: nothing-image-instance-p object
874 This function returns non-`nil' if OBJECT is an image instance of
878 File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
880 Image Instance Functions
881 ........................
883 - Function: make-image-instance data &optional device dest-types
885 This function creates a new image-instance object.
887 DATA is an image instantiator, which describes the image (*note
890 DEST-TYPES should be a list of allowed image instance types that
891 can be generated. The DEST-TYPES list is unordered. If multiple
892 destination types are possible for a given instantiator, the "most
893 natural" type for the instantiator's format is chosen. (For XBM,
894 the most natural types are `mono-pixmap', followed by
895 `color-pixmap', followed by `pointer'. For the other normal image
896 formats, the most natural types are `color-pixmap', followed by
897 `mono-pixmap', followed by `pointer'. For the string and
898 formatted-string formats, the most natural types are `text',
899 followed by `mono-pixmap' (not currently implemented), followed by
900 `color-pixmap' (not currently implemented). The other formats can
901 only be instantiated as one type. (If you want to control more
902 specifically the order of the types into which an image is
903 instantiated, just call `make-image-instance' repeatedly until it
904 succeeds, passing less and less preferred destination types each
907 If DEST-TYPES is omitted, all possible types are allowed.
909 NO-ERROR controls what happens when the image cannot be generated.
910 If NIL, an error message is generated. If T, no messages are
911 generated and this function returns NIL. If anything else, a
912 warning message is generated and this function returns NIL.
914 - Function: colorize-image-instance image-instance foreground
916 This function makes the image instance be displayed in the given
917 colors. Image instances come in two varieties: bitmaps, which are
918 1 bit deep which are rendered in the prevailing foreground and
919 background colors; and pixmaps, which are of arbitrary depth
920 (including 1) and which have the colors explicitly specified.
921 This function converts a bitmap to a pixmap. If the image
922 instance was a pixmap already, nothing is done (and `nil' is
923 returned). Otherwise `t' is returned.
925 - Function: image-instance-name image-instance
926 This function returns the name of the given image instance.
928 - Function: image-instance-string image-instance
929 This function returns the string of the given image instance.
930 This will only be non-`nil' for text image instances.
932 - Function: image-instance-file-name image-instance
933 This function returns the file name from which IMAGE-INSTANCE was
936 - Function: image-instance-mask-file-name image-instance
937 This function returns the file name from which IMAGE-INSTANCE's
938 mask was read, if known.
940 - Function: image-instance-depth image-instance
941 This function returns the depth of the image instance. This is 0
942 for a mono pixmap, or a positive integer for a color pixmap.
944 - Function: image-instance-height image-instance
945 This function returns the height of the image instance, in pixels.
947 - Function: image-instance-width image-instance
948 This function returns the width of the image instance, in pixels.
950 - Function: image-instance-hotspot-x image-instance
951 This function returns the X coordinate of the image instance's
952 hotspot, if known. This is a point relative to the origin of the
953 pixmap. When an image is used as a mouse pointer, the hotspot is
954 the point on the image that sits over the location that the
955 pointer points to. This is, for example, the tip of the arrow or
956 the center of the crosshairs.
958 This will always be `nil' for a non-pointer image instance.
960 - Function: image-instance-hotspot-y image-instance
961 This function returns the Y coordinate of the image instance's
964 - Function: image-instance-foreground image-instance
965 This function returns the foreground color of IMAGE-INSTANCE, if
966 applicable. This will be a color instance or `nil'. (It will only
967 be non-`nil' for colorized mono pixmaps and for pointers.)
969 - Function: image-instance-background image-instance
970 This function returns the background color of IMAGE-INSTANCE, if
971 applicable. This will be a color instance or `nil'. (It will only
972 be non-`nil' for colorized mono pixmaps and for pointers.)
975 File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
980 Each glyph has a particular type, which controls how the glyph's
981 image is generated. Each glyph type has a corresponding list of
982 allowable image instance types that can be generated. When you call
983 `glyph-image-instance' to retrieve the image instance of a glyph,
984 XEmacs does the equivalent of calling `make-image-instance' and passing
985 in DEST-TYPES the list of allowable image instance types for the
988 * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
989 extent, in the modeline, and in the toolbar. Their image can be
990 instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
993 * `pointer' glyphs can be used to specify the mouse pointer. Their
994 image can be instantiated as `pointer'.
996 * `icon' glyphs can be used to specify the icon used when a frame is
997 iconified. Their image can be instantiated as `mono-pixmap' and
1000 - Function: glyph-type glyph
1001 This function returns the type of the given glyph. The return
1002 value will be a symbol, one of `buffer', `pointer', or `icon'.
1004 - Function: valid-glyph-type-p glyph-type
1005 Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
1007 - Function: glyph-type-list
1008 This function returns a list of valid glyph types.
1010 - Function: buffer-glyph-p object
1011 This function returns non-`nil' if OBJECT is a glyph of type
1014 - Function: icon-glyph-p object
1015 This function returns non-`nil' if OBJECT is a glyph of type
1018 - Function: pointer-glyph-p object
1019 This function returns non-`nil' if OBJECT is a glyph of type
1023 File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
1028 The shape of the mouse pointer when over a particular section of a
1029 frame is controlled using various glyph variables. Since the image of
1030 a glyph is a specifier, it can be controlled on a per-buffer,
1031 per-frame, per-window, or per-device basis.
1033 You should use `set-glyph-image' to set the following variables,
1036 - Glyph: text-pointer-glyph
1037 This variable specifies the shape of the mouse pointer when over
1040 - Glyph: nontext-pointer-glyph
1041 This variable specifies the shape of the mouse pointer when over a
1042 buffer, but not over text. If unspecified in a particular domain,
1043 `text-pointer-glyph' is used.
1045 - Glyph: modeline-pointer-glyph
1046 This variable specifies the shape of the mouse pointer when over
1047 the modeline. If unspecified in a particular domain,
1048 `nontext-pointer-glyph' is used.
1050 - Glyph: selection-pointer-glyph
1051 This variable specifies the shape of the mouse pointer when over a
1052 selectable text region. If unspecified in a particular domain,
1053 `text-pointer-glyph' is used.
1055 - Glyph: gc-pointer-glyph
1056 This variable specifies the shape of the mouse pointer when a
1057 garbage collection is in progress. If the selected window is on a
1058 window system and this glyph specifies a value (i.e. a pointer
1059 image instance) in the domain of the selected window, the pointer
1060 will be changed as specified during garbage collection.
1061 Otherwise, a message will be printed in the echo area, as
1062 controlled by `gc-message'.
1064 - Glyph: busy-pointer-glyph
1065 This variable specifies the shape of the mouse pointer when XEmacs
1066 is busy. If unspecified in a particular domain, the pointer is
1067 not changed when XEmacs is busy.
1069 - Glyph: menubar-pointer-glyph
1070 This variable specifies the shape of the mouse pointer when over
1071 the menubar. If unspecified in a particular domain, the
1072 window-system-provided default pointer is used.
1074 - Glyph: scrollbar-pointer-glyph
1075 This variable specifies the shape of the mouse pointer when over a
1076 scrollbar. If unspecified in a particular domain, the
1077 window-system-provided default pointer is used.
1079 - Glyph: toolbar-pointer-glyph
1080 This variable specifies the shape of the mouse pointer when over a
1081 toolbar. If unspecified in a particular domain,
1082 `nontext-pointer-glyph' is used.
1084 Internally, these variables are implemented in
1085 `default-mouse-motion-handler', and thus only take effect when the
1086 mouse moves. That function calls `set-frame-pointer', which sets the
1087 current mouse pointer for a frame.
1089 - Function: set-frame-pointer frame image-instance
1090 This function sets the mouse pointer of FRAME to the given pointer
1091 image instance. You should not call this function directly. (If
1092 you do, the pointer will change again the next time the mouse
1096 File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
1101 - Glyph: truncation-glyph
1102 This variable specifies what is displayed at the end of truncated
1105 - Glyph: continuation-glyph
1106 This variable specifies what is displayed at the end of wrapped
1109 - Glyph: octal-escape-glyph
1110 This variable specifies what to prefix character codes displayed
1113 - Glyph: hscroll-glyph
1114 This variable specifies what to display at the beginning of
1115 horizontally scrolled lines.
1117 - Glyph: invisible-text-glyph
1118 This variable specifies what to use to indicate the presence of
1119 invisible text. This is the glyph that is displayed when an
1120 ellipsis is called for, according to `selective-display-ellipses'
1121 or `buffer-invisibility-spec'). Normally this is three dots
1124 - Glyph: control-arrow-glyph
1125 This variable specifies what to use as an arrow for control
1129 File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
1134 Subwindows are not currently implemented.
1136 - Function: subwindowp object
1137 This function returns non-`nil' if OBJECT is a subwindow.
1140 File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
1145 An "annotation" is a pixmap or string that is not part of a buffer's
1146 text but is displayed next to a particular location in a buffer.
1147 Annotations can be displayed intermixed with text, in any whitespace at
1148 the beginning or end of a line, or in a special area at the left or
1149 right side of the frame called a "margin", whose size is controllable.
1150 Annotations are implemented using extents (*note Extents::); but you
1151 can work with annotations without knowing how extents work.
1155 * Annotation Basics:: Introduction to annotations.
1156 * Annotation Primitives:: Creating and deleting annotations.
1157 * Annotation Properties:: Retrieving and changing the characteristics
1159 * Margin Primitives:: Controlling the size of the margins.
1160 * Locating Annotations:: Looking for annotations in a buffer.
1161 * Annotation Hooks:: Hooks called at certain times during an
1162 annotation's lifetime.