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: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
58 You can examine and modify the properties of an existing face with
59 the following functions.
61 The following symbols have predefined meanings:
64 The foreground color of the face.
67 The background color of the face.
70 The font used to display text covered by this face.
73 The display table of the face.
76 The pixmap displayed in the background of the face. Only used by
80 Underline all text covered by this face.
83 Highlight all text covered by this face. Only used by faces on TTY
87 Dim all text covered by this face. Only used by faces on TTY
91 Blink all text covered by this face. Only used by faces on TTY
95 Reverse the foreground and background colors. Only used by faces
99 Description of what the face's normal use is. NOTE: This is not a
100 specifier, unlike all the other built-in properties, and cannot
101 contain locale-specific values.
103 - Function: set-face-property face property value &optional locale tag
105 This function changes a property of a FACE.
107 For built-in properties, the actual value of the property is a
108 specifier and you cannot change this; but you can change the
109 specifications within the specifier, and that is what this
110 function will do. For user-defined properties, you can use this
111 function to either change the actual value of the property or, if
112 this value is a specifier, change the specifications within it.
114 If PROPERTY is a built-in property, the specifications to be added
115 to this property can be supplied in many different ways:
117 If VALUE is a simple instantiator (e.g. a string naming a
118 font or color) or a list of instantiators, then the
119 instantiator(s) will be added as a specification of the
120 property for the given LOCALE (which defaults to `global' if
123 If VALUE is a list of specifications (each of which is a cons
124 of a locale and a list of instantiators), then LOCALE must be
125 `nil' (it does not make sense to explicitly specify a locale
126 in this case), and specifications will be added as given.
128 If VALUE is a specifier (as would be returned by
129 `face-property' if no LOCALE argument is given), then some or
130 all of the specifications in the specifier will be added to
131 the property. In this case, the function is really
132 equivalent to `copy-specifier' and LOCALE has the same
133 semantics (if it is a particular locale, the specification
134 for the locale will be copied; if a locale type,
135 specifications for all locales of that type will be copied;
136 if `nil' or `all', then all specifications will be copied).
138 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
139 `append', `remove-tag-set-prepend', `remove-tag-set-append',
140 `remove-locale', `remove-locale-type', or `remove-all'. See
141 `copy-specifier' and `add-spec-to-specifier' for a description of
142 what each of these means. Most of the time, you do not need to
143 worry about this argument; the default behavior usually is fine.
145 In general, it is OK to pass an instance object (e.g. as returned
146 by `face-property-instance') as an instantiator in place of an
147 actual instantiator. In such a case, the instantiator used to
148 create that instance object will be used (for example, if you set
149 a font-instance object as the value of the `font' property, then
150 the font name used to create that object will be used instead).
151 If some cases, however, doing this conversion does not make sense,
152 and this will be noted in the documentation for particular types
155 If PROPERTY is not a built-in property, then this function will
156 simply set its value if LOCALE is `nil'. However, if LOCALE is
157 given, then this function will attempt to add VALUE as the
158 instantiator for the given LOCALE, using `add-spec-to-specifier'.
159 If the value of the property is not a specifier, it will
160 automatically be converted into a `generic' specifier.
162 - Function: remove-face-property face property &optional local tag-set
164 This function removes a property of a FACE.
166 For built-in properties, this is analogous to `remove-specifier'.
167 For more information, *Note Other Specification Functions::.
169 When PROPERTY is not a built-in property, this function will just
170 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
171 is other than that, this function will attempt to remove VALUE as
172 the instantiator for the given LOCALE with `remove-specifier'. If
173 the value of the property is not a specifier, it will be converted
174 into a `generic' specifier automatically.
176 - Function: face-property face property &optional locale
177 This function returns FACE's value of the given PROPERTY.
179 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
180 returned. For built-in properties, this will be a specifier
181 object of a type appropriate to the property (e.g. a font or color
182 specifier). For other properties, this could be anything.
184 If LOCALE is supplied, then instead of returning the actual value,
185 the specification(s) for the given locale or locale type will be
186 returned. This will only work if the actual value of PROPERTY is
187 a specifier (this will always be the case for built-in properties,
188 but not or not may apply to user-defined properties). If the
189 actual value of PROPERTY is not a specifier, this value will
190 simply be returned regardless of LOCALE.
192 The return value will be a list of instantiators (e.g. strings
193 specifying a font or color name), or a list of specifications,
194 each of which is a cons of a locale and a list of instantiators.
195 Specifically, if LOCALE is a particular locale (a buffer, window,
196 frame, device, or `global'), a list of instantiators for that
197 locale will be returned. Otherwise, if LOCALE is a locale type
198 (one of the symbols `buffer', `window', `frame', or `device'), the
199 specifications for all locales of that type will be returned.
200 Finally, if LOCALE is `all', the specifications for all locales of
201 all types will be returned.
203 The specifications in a specifier determine what the value of
204 PROPERTY will be in a particular "domain" or set of circumstances,
205 which is typically a particular Emacs window along with the buffer
206 it contains and the frame and device it lies within. The value is
207 derived from the instantiator associated with the most specific
208 locale (in the order buffer, window, frame, device, and `global')
209 that matches the domain in question. In other words, given a
210 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
211 will first be searched for a specification whose locale is the
212 buffer contained within that window; then for a specification
213 whose locale is the window itself; then for a specification whose
214 locale is the frame that the window is contained within; etc. The
215 first instantiator that is valid for the domain (usually this
216 means that the instantiator is recognized by the device [i.e. the
217 X server or TTY device] that the domain is on). The function
218 `face-property-instance' actually does all this, and is used to
219 determine how to display the face.
221 - Function: face-property-instance face property &optional domain
223 This function returns the instance of FACE's PROPERTY in the
226 Under most circumstances, DOMAIN will be a particular window, and
227 the returned instance describes how the specified property
228 actually is displayed for that window and the particular buffer in
229 it. Note that this may not be the same as how the property
230 appears when the buffer is displayed in a different window or
231 frame, or how the property appears in the same window if you
232 switch to another buffer in that window; and in those cases, the
233 returned instance would be different.
235 The returned instance will typically be a color-instance,
236 font-instance, or pixmap-instance object, and you can query it
237 using the appropriate object-specific functions. For example, you
238 could use `color-instance-rgb-components' to find out the RGB
239 (red, green, and blue) components of how the `background' property
240 of the `highlight' face is displayed in a particular window. The
241 results might be different from the results you would get for
242 another window (perhaps the user specified a different color for
243 the frame that window is on; or perhaps the same color was
244 specified but the window is on a different X server, and that X
245 server has different RGB values for the color from this one).
247 DOMAIN defaults to the selected window if omitted.
249 DOMAIN can be a frame or device, instead of a window. The value
250 returned for a such a domain is used in special circumstances when
251 a more specific domain does not apply; for example, a frame value
252 might be used for coloring a toolbar, which is conceptually
253 attached to a frame rather than a particular window. The value is
254 also useful in determining what the value would be for a
255 particular window within the frame or device, if it is not
256 overridden by a more specific specification.
258 If PROPERTY does not name a built-in property, its value will
259 simply be returned unless it is a specifier object, in which case
260 it will be instanced using `specifier-instance'.
262 Optional arguments DEFAULT and NO-FALLBACK are the same as in
263 `specifier-instance'. *Note Specifiers::.
266 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
268 Face Convenience Functions
269 --------------------------
271 - Function: set-face-foreground face color &optional locale tag
273 - Function: set-face-background face color &optional locale tag
275 These functions set the foreground (respectively, background)
276 color of face FACE to COLOR. The argument COLOR should be a
277 string (the name of a color) or a color object as returned by
278 `make-color' (*note Colors::).
280 - Function: set-face-background-pixmap face pixmap &optional locale
282 This function sets the background pixmap of face FACE to PIXMAP.
283 The argument PIXMAP should be a string (the name of a bitmap or
284 pixmap file; the directories listed in the variable
285 `x-bitmap-file-path' will be searched) or a glyph object as
286 returned by `make-glyph' (*note Glyphs::). The argument may also
287 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
288 are the size in pixels, and DATA is a string, containing the raw
291 - Function: set-face-font face font &optional locale tag how-to-add
292 This function sets the font of face FACE. The argument FONT
293 should be a string or a font object as returned by `make-font'
296 - Function: set-face-underline-p face underline-p &optional locale tag
298 This function sets the underline property of face FACE.
300 - Function: face-foreground face &optional locale
301 - Function: face-background face &optional locale
302 These functions return the foreground (respectively, background)
303 color specifier of face FACE. *Note Colors::.
305 - Function: face-background-pixmap face &optional locale
306 This function return the background-pixmap glyph object of face
309 - Function: face-font face &optional locale
310 This function returns the font specifier of face FACE. (Note:
311 This is not the same as the function `face-font' in FSF Emacs.)
314 - Function: face-font-name face &optional domain
315 This function returns the name of the font of face FACE, or `nil'
316 if it is unspecified. This is basically equivalent to `(font-name
317 (face-font FACE) DOMAIN)' except that it does not cause an error
318 if FACE's font is `nil'. (This function is named `face-font' in
321 - Function: face-underline-p face &optional locale
322 This function returns the underline property of face FACE.
324 - Function: face-foreground-instance face &optional domain
325 - Function: face-background-instance face &optional domain
326 These functions return the foreground (respectively, background)
327 color specifier of face FACE. *Note Colors::.
329 - Function: face-background-pixmap-instance face &optional domain
330 This function return the background-pixmap glyph object of face
333 - Function: face-font-instance face &optional domain
334 This function returns the font specifier of face FACE. *Note
338 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
340 Other Face Display Functions
341 ----------------------------
343 - Function: invert-face face &optional locale
344 Swap the foreground and background colors of face FACE. If the
345 face doesn't specify both foreground and background, then its
346 foreground and background are set to the default background and
349 - Function: face-equal face1 face2 &optional domain
350 This returns `t' if the faces FACE1 and FACE2 will display in the
351 same way. DOMAIN is as in `face-property-instance'.
353 - Function: face-differs-from-default-p face &optional domain
354 This returns `t' if the face FACE displays differently from the
355 default face. DOMAIN is as in `face-property-instance'.
358 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
363 This section describes how to work with font specifier and font
364 instance objects, which encapsulate fonts in the window system.
368 * Font Specifiers:: Specifying how a font will appear.
369 * Font Instances:: What a font specifier gets instanced as.
370 * Font Instance Names:: The name of a font instance.
371 * Font Instance Size:: The size of a font instance.
372 * Font Instance Characteristics:: Display characteristics of font instances.
373 * Font Convenience Functions:: Convenience functions that automatically
374 instance and retrieve the properties
378 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
383 - Function: font-specifier-p object
384 This predicate returns `t' if OBJECT is a font specifier, and
388 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
393 - Function: font-instance-p object
394 This predicate returns `t' if OBJECT is a font instance, and `nil'
397 - Function: make-font-instance name &optional device noerror
398 This function creates a new font-instance object of the specified
399 name. DEVICE specifies the device this object applies to and
400 defaults to the selected device. An error is signalled if the
401 font is unknown or cannot be allocated; however, if NOERROR is
402 non-`nil', `nil' is simply returned in this case.
404 The returned object is a normal, first-class lisp object. The way
405 you "deallocate" the font is the way you deallocate any other lisp
406 object: you drop all pointers to it and allow it to be garbage
407 collected. When these objects are GCed, the underlying X data is
411 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
416 - Function: list-fonts pattern &optional device
417 This function returns a list of font names matching the given
418 pattern. DEVICE specifies which device to search for names, and
419 defaults to the currently selected device.
421 - Function: font-instance-name font-instance
422 This function returns the name used to allocate FONT-INSTANCE.
424 - Function: font-instance-truename font-instance
425 This function returns the canonical name of the given font
426 instance. Font names are patterns which may match any number of
427 fonts, of which the first found is used. This returns an
428 unambiguous name for that font (but not necessarily its only
432 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
437 - Function: x-font-size font
438 This function returns the nominal size of the given font. This is
439 done by parsing its name, so it's likely to lose. X fonts can be
440 specified (by the user) in either pixels or 10ths of points, and
441 this returns the first one it finds, so you have to decide which
442 units the returned value is measured in yourself ...
444 - Function: x-find-larger-font font &optional device
445 This function loads a new, slightly larger version of the given
446 font (or font name). Returns the font if it succeeds, `nil'
447 otherwise. If scalable fonts are available, this returns a font
448 which is 1 point larger. Otherwise, it returns the next larger
449 version of this font that is defined.
451 - Function: x-find-smaller-font font &optional device
452 This function loads a new, slightly smaller version of the given
453 font (or font name). Returns the font if it succeeds, `nil'
454 otherwise. If scalable fonts are available, this returns a font
455 which is 1 point smaller. Otherwise, it returns the next smaller
456 version of this font that is defined.
459 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
461 Font Instance Characteristics
462 -----------------------------
464 - Function: font-instance-properties font
465 This function returns the properties (an alist or `nil') of
468 - Function: x-make-font-bold font &optional device
469 Given an X font specification, this attempts to make a "bold" font.
470 If it fails, it returns `nil'.
472 - Function: x-make-font-unbold font &optional device
473 Given an X font specification, this attempts to make a non-bold
474 font. If it fails, it returns `nil'.
476 - Function: x-make-font-italic font &optional device
477 Given an X font specification, this attempts to make an "italic"
478 font. If it fails, it returns `nil'.
480 - Function: x-make-font-unitalic font &optional device
481 Given an X font specification, this attempts to make a non-italic
482 font. If it fails, it returns `nil'.
484 - Function: x-make-font-bold-italic font &optional device
485 Given an X font specification, this attempts to make a
486 "bold-italic" font. If it fails, it returns `nil'.
489 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
491 Font Convenience Functions
492 --------------------------
494 - Function: font-name font &optional domain
495 This function returns the name of the FONT in the specified
496 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
497 is normally a window and defaults to the selected window if
498 omitted. This is equivalent to using `specifier-instance' and
499 applying `font-instance-name' to the result.
501 - Function: font-truename font &optional domain
502 This function returns the truename of the FONT in the specified
503 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
504 is normally a window and defaults to the selected window if
505 omitted. This is equivalent to using `specifier-instance' and
506 applying `font-instance-truename' to the result.
508 - Function: font-properties font &optional domain
509 This function returns the properties of the FONT in the specified
510 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
511 is normally a window and defaults to the selected window if
512 omitted. This is equivalent to using `specifier-instance' and
513 applying `font-instance-properties' to the result.
516 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
523 * Color Specifiers:: Specifying how a color will appear.
524 * Color Instances:: What a color specifier gets instanced as.
525 * Color Instance Properties:: Properties of color instances.
526 * Color Convenience Functions:: Convenience functions that automatically
527 instance and retrieve the properties
528 of a color specifier.
531 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
536 - Function: color-specifier-p object
537 This function returns non-`nil' if OBJECT is a color specifier.
540 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
545 A "color-instance object" is an object describing the way a color
546 specifier is instanced in a particular domain. Functions such as
547 `face-background-instance' return a color-instance object. For example,
549 (face-background-instance 'default (next-window))
550 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
552 The color-instance object returned describes the way the background
553 color of the `default' face is displayed in the next window after the
556 - Function: color-instance-p object
557 This function returns non-`nil' if OBJECT is a color-instance.
560 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
562 Color Instance Properties
563 -------------------------
565 - Function: color-instance-name color-instance
566 This function returns the name used to allocate COLOR-INSTANCE.
568 - Function: color-instance-rgb-components color-instance
569 This function returns a three element list containing the red,
570 green, and blue color components of COLOR-INSTANCE.
572 (color-instance-rgb-components
573 (face-background-instance 'default (next-window)))
574 => (65535 58596 46517)
577 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
579 Color Convenience Functions
580 ---------------------------
582 - Function: color-name color &optional domain
583 This function returns the name of the COLOR in the specified
584 DOMAIN, if any. COLOR should be a color specifier object and
585 DOMAIN is normally a window and defaults to the selected window if
586 omitted. This is equivalent to using `specifier-instance' and
587 applying `color-instance-name' to the result.
589 - Function: color-rgb-components color &optional domain
590 This function returns the RGB components of the COLOR in the
591 specified DOMAIN, if any. COLOR should be a color specifier
592 object and DOMAIN is normally a window and defaults to the
593 selected window if omitted. This is equivalent to using
594 `specifier-instance' and applying `color-instance-rgb-components'
597 (color-rgb-components (face-background 'default (next-window)))
598 => (65535 58596 46517)
601 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
606 A "glyph" is an object that is used for pixmaps and images of all
607 sorts, as well as for things that "act" like pixmaps, such as
608 non-textual strings ("annotations") displayed in a buffer or in the
609 margins. It is used in begin-glyphs and end-glyphs attached to extents,
610 marginal and textual annotations, overlay arrows (`overlay-arrow-*'
611 variables), toolbar buttons, mouse pointers, frame icons, truncation and
612 continuation markers, and the like. (Basically, any place there is an
613 image or something that acts like an image, there will be a glyph object
616 The actual image that is displayed (as opposed to its position or
617 clipping) is defined by an "image specifier" object contained within
618 the glyph. The separation between an image specifier object and a
619 glyph object is made because the glyph includes other properties than
620 just the actual image: e.g. the face it is displayed in (for text
621 images), the alignment of the image (when it is in a buffer), etc.
623 - Function: glyphp object
624 This function returns `t' if OBJECT is a glyph.
628 * Glyph Functions:: Functions for working with glyphs.
629 * Images:: Graphical images displayed in a frame.
630 * Glyph Types:: Each glyph has a particular type.
631 * Mouse Pointer:: Controlling the mouse pointer.
632 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
633 * Subwindows:: Inserting an externally-controlled subwindow
637 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
644 * Creating Glyphs:: Creating new glyphs.
645 * Glyph Properties:: Accessing and modifying a glyph's properties.
646 * Glyph Convenience Functions::
647 Convenience functions for accessing particular
648 properties of a glyph.
649 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
652 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
657 - Function: make-glyph &optional spec-list type
658 This function creates a new glyph object of type TYPE.
660 SPEC-LIST is used to initialize the glyph's image. It is
661 typically an image instantiator (a string or a vector; *Note Image
662 Specifiers::), but can also be a list of such instantiators (each
663 one in turn is tried until an image is successfully produced), a
664 cons of a locale (frame, buffer, etc.) and an instantiator, a list
665 of such conses, or any other form accepted by
666 `canonicalize-spec-list'. *Note Specifiers::, for more
667 information about specifiers.
669 TYPE specifies the type of the glyph, which specifies in which
670 contexts the glyph can be used, and controls the allowable image
671 types into which the glyph's image can be instantiated. TYPE
672 should be one of `buffer' (used for glyphs in an extent, the
673 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
674 for the mouse-pointer), or `icon' (used for a frame's icon), and
675 defaults to `buffer'. *Note Glyph Types::.
677 - Function: make-glyph-internal &optional type
678 This function creates a new, uninitialized glyph of type TYPE.
680 - Function: make-pointer-glyph &optional spec-list
681 This function is equivalent to calling `make-glyph' with a TYPE of
684 - Function: make-icon-glyph &optional spec-list
685 This function is equivalent to calling `make-glyph' with a TYPE of
689 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
694 Each glyph has a list of properties, which control all of the
695 aspects of the glyph's appearance. The following symbols have
699 The image used to display the glyph.
702 Percent above baseline that glyph is to be displayed. Only for
703 glyphs displayed inside of a buffer.
706 Whether the glyph contributes to the height of the line it's on.
707 Only for glyphs displayed inside of a buffer.
710 Face of this glyph (_not_ a specifier).
712 - Function: set-glyph-property glyph property value &optional locale
714 This function changes a property of a GLYPH.
716 For built-in properties, the actual value of the property is a
717 specifier and you cannot change this; but you can change the
718 specifications within the specifier, and that is what this
719 function will do. For user-defined properties, you can use this
720 function to either change the actual value of the property or, if
721 this value is a specifier, change the specifications within it.
723 If PROPERTY is a built-in property, the specifications to be added
724 to this property can be supplied in many different ways:
726 * If VALUE is a simple instantiator (e.g. a string naming a
727 pixmap filename) or a list of instantiators, then the
728 instantiator(s) will be added as a specification of the
729 property for the given LOCALE (which defaults to `global' if
732 * If VALUE is a list of specifications (each of which is a cons
733 of a locale and a list of instantiators), then LOCALE must be
734 `nil' (it does not make sense to explicitly specify a locale
735 in this case), and specifications will be added as given.
737 * If VALUE is a specifier (as would be returned by
738 `glyph-property' if no LOCALE argument is given), then some
739 or all of the specifications in the specifier will be added
740 to the property. In this case, the function is really
741 equivalent to `copy-specifier' and LOCALE has the same
742 semantics (if it is a particular locale, the specification
743 for the locale will be copied; if a locale type,
744 specifications for all locales of that type will be copied;
745 if `nil' or `all', then all specifications will be copied).
747 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
748 `append', `remove-tag-set-prepend', `remove-tag-set-append',
749 `remove-locale', `remove-locale-type', or `remove-all'. See
750 `copy-specifier' and `add-spec-to-specifier' for a description of
751 what each of these means. Most of the time, you do not need to
752 worry about this argument; the default behavior usually is fine.
754 In general, it is OK to pass an instance object (e.g. as returned
755 by `glyph-property-instance') as an instantiator in place of an
756 actual instantiator. In such a case, the instantiator used to
757 create that instance object will be used (for example, if you set
758 a font-instance object as the value of the `font' property, then
759 the font name used to create that object will be used instead).
760 If some cases, however, doing this conversion does not make sense,
761 and this will be noted in the documentation for particular types
764 If PROPERTY is not a built-in property, then this function will
765 simply set its value if LOCALE is `nil'. However, if LOCALE is
766 given, then this function will attempt to add VALUE as the
767 instantiator for the given LOCALE, using `add-spec-to-specifier'.
768 If the value of the property is not a specifier, it will
769 automatically be converted into a `generic' specifier.
771 - Function: glyph-property glyph property &optional locale
772 This function returns GLYPH's value of the given PROPERTY.
774 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
775 be returned. For built-in properties, this will be a specifier
776 object of a type appropriate to the property (e.g. a font or color
777 specifier). For other properties, this could be anything.
779 If LOCALE is supplied, then instead of returning the actual value,
780 the specification(s) for the given locale or locale type will be
781 returned. This will only work if the actual value of PROPERTY is
782 a specifier (this will always be the case for built-in properties,
783 but may or may not apply to user-defined properties). If the
784 actual value of PROPERTY is not a specifier, this value will
785 simply be returned regardless of LOCALE.
787 The return value will be a list of instantiators (e.g. vectors
788 specifying pixmap data), or a list of specifications, each of
789 which is a cons of a locale and a list of instantiators.
790 Specifically, if LOCALE is a particular locale (a buffer, window,
791 frame, device, or `global'), a list of instantiators for that
792 locale will be returned. Otherwise, if LOCALE is a locale type
793 (one of the symbols `buffer', `window', `frame', or `device'), the
794 specifications for all locales of that type will be returned.
795 Finally, if LOCALE is `all', the specifications for all locales of
796 all types will be returned.
798 The specifications in a specifier determine what the value of
799 PROPERTY will be in a particular "domain" or set of circumstances,
800 which is typically a particular Emacs window along with the buffer
801 it contains and the frame and device it lies within. The value is
802 derived from the instantiator associated with the most specific
803 locale (in the order buffer, window, frame, device, and `global')
804 that matches the domain in question. In other words, given a
805 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
806 will first be searched for a specification whose locale is the
807 buffer contained within that window; then for a specification
808 whose locale is the window itself; then for a specification whose
809 locale is the frame that the window is contained within; etc. The
810 first instantiator that is valid for the domain (usually this
811 means that the instantiator is recognized by the device [i.e. the
812 X server or TTY device] that the domain is on). The function
813 `glyph-property-instance' actually does all this, and is used to
814 determine how to display the glyph.
816 - Function: glyph-property-instance glyph property &optional domain
818 This function returns the instance of GLYPH's PROPERTY in the
821 Under most circumstances, DOMAIN will be a particular window, and
822 the returned instance describes how the specified property
823 actually is displayed for that window and the particular buffer in
824 it. Note that this may not be the same as how the property
825 appears when the buffer is displayed in a different window or
826 frame, or how the property appears in the same window if you
827 switch to another buffer in that window; and in those cases, the
828 returned instance would be different.
830 The returned instance is an image-instance object, and you can
831 query it using the appropriate image instance functions. For
832 example, you could use `image-instance-depth' to find out the
833 depth (number of color planes) of a pixmap displayed in a
834 particular window. The results might be different from the
835 results you would get for another window (perhaps the user
836 specified a different image for the frame that window is on; or
837 perhaps the same image was specified but the window is on a
838 different X server, and that X server has different color
839 capabilities from this one).
841 DOMAIN defaults to the selected window if omitted.
843 DOMAIN can be a frame or device, instead of a window. The value
844 returned for such a domain is used in special circumstances when a
845 more specific domain does not apply; for example, a frame value
846 might be used for coloring a toolbar, which is conceptually
847 attached to a frame rather than a particular window. The value is
848 also useful in determining what the value would be for a
849 particular window within the frame or device, if it is not
850 overridden by a more specific specification.
852 If PROPERTY does not name a built-in property, its value will
853 simply be returned unless it is a specifier object, in which case
854 it will be instanced using `specifier-instance'.
856 Optional arguments DEFAULT and NO-FALLBACK are the same as in
857 `specifier-instance'. *Note Specifiers::.
859 - Function: remove-glyph-property glyph property &optional locale
861 This function removes a property from a glyph. For built-in
862 properties, this is analogous to `remove-specifier'. *Note
863 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
864 TAG-SET, and EXACT-P arguments.
867 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
869 Glyph Convenience Functions
870 ---------------------------
872 The following functions are provided for working with specific
873 properties of a glyph. Note that these are exactly like calling the
874 general functions described above and passing in the appropriate value
877 Remember that if you want to determine the "value" of a specific
878 glyph property, you probably want to use the `*-instance' functions.
879 For example, to determine whether a glyph contributes to its line
880 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
881 latter will return a boolean specifier or a list of specifications, and
882 you probably aren't concerned with these.)
884 - Function: glyph-image glyph &optional locale
885 This function is equivalent to calling `glyph-property' with a
886 property of `image'. The return value will be an image specifier
887 if LOCALE is `nil' or omitted; otherwise, it will be a
888 specification or list of specifications.
890 - Function: set-glyph-image glyph spec &optional locale tag-set
892 This function is equivalent to calling `set-glyph-property' with a
895 - Function: glyph-image-instance glyph &optional domain default
897 This function returns the instance of GLYPH's image in the given
898 DOMAIN, and is equivalent to calling `glyph-property-instance'
899 with a property of `image'. The return value will be an image
902 Normally DOMAIN will be a window or `nil' (meaning the selected
903 window), and an instance object describing how the image appears
904 in that particular window and buffer will be returned.
906 - Function: glyph-contrib-p glyph &optional locale
907 This function is equivalent to calling `glyph-property' with a
908 property of `contrib-p'. The return value will be a boolean
909 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
910 specification or list of specifications.
912 - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
914 This function is equivalent to calling `set-glyph-property' with a
915 property of `contrib-p'.
917 - Function: glyph-contrib-p-instance glyph &optional domain default
919 This function returns whether the glyph contributes to its line
920 height in the given DOMAIN, and is equivalent to calling
921 `glyph-property-instance' with a property of `contrib-p'. The
922 return value will be either `nil' or `t'. (Normally DOMAIN will be
923 a window or `nil', meaning the selected window.)
925 - Function: glyph-baseline glyph &optional locale
926 This function is equivalent to calling `glyph-property' with a
927 property of `baseline'. The return value will be a specifier if
928 LOCALE is `nil' or omitted; otherwise, it will be a specification
929 or list of specifications.
931 - Function: set-glyph-baseline glyph spec &optional locale tag-set
933 This function is equivalent to calling `set-glyph-property' with a
934 property of `baseline'.
936 - Function: glyph-baseline-instance glyph &optional domain default
938 This function returns the instance of GLYPH's baseline value in
939 the given DOMAIN, and is equivalent to calling
940 `glyph-property-instance' with a property of `baseline'. The
941 return value will be an integer or `nil'.
943 Normally DOMAIN will be a window or `nil' (meaning the selected
944 window), and an instance object describing the baseline value
945 appears in that particular window and buffer will be returned.
947 - Function: glyph-face glyph
948 This function returns the face of GLYPH. (Remember, this is not a
949 specifier, but a simple property.)
951 - Function: set-glyph-face glyph face
952 This function changes the face of GLYPH to FACE.
955 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
960 - Function: glyph-width glyph &optional window
961 This function returns the width of GLYPH on WINDOW. This may not
962 be exact as it does not take into account all of the context that
965 - Function: glyph-ascent glyph &optional window
966 This function returns the ascent value of GLYPH on WINDOW. This
967 may not be exact as it does not take into account all of the
968 context that redisplay will.
970 - Function: glyph-descent glyph &optional window
971 This function returns the descent value of GLYPH on WINDOW. This
972 may not be exact as it does not take into account all of the
973 context that redisplay will.
975 - Function: glyph-height glyph &optional window
976 This function returns the height of GLYPH on WINDOW. (This is
977 equivalent to the sum of the ascent and descent values.) This may
978 not be exact as it does not take into account all of the context
982 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
989 * Image Specifiers:: Specifying how an image will appear.
990 * Image Instantiator Conversion::
991 Conversion is applied to image instantiators
992 at the time they are added to an
993 image specifier or at the time they
994 are passed to `make-image-instance'.
995 * Image Instances:: What an image specifier gets instanced as.