1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: 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: face-property FACE PROPERTY &optional LOCALE
163 This function returns FACE's value of the given PROPERTY.
165 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
166 returned. For built-in properties, this will be a specifier
167 object of a type appropriate to the property (e.g. a font or color
168 specifier). For other properties, this could be anything.
170 If LOCALE is supplied, then instead of returning the actual value,
171 the specification(s) for the given locale or locale type will be
172 returned. This will only work if the actual value of PROPERTY is
173 a specifier (this will always be the case for built-in properties,
174 but not or not may apply to user-defined properties). If the
175 actual value of PROPERTY is not a specifier, this value will
176 simply be returned regardless of LOCALE.
178 The return value will be a list of instantiators (e.g. strings
179 specifying a font or color name), or a list of specifications,
180 each of which is a cons of a locale and a list of instantiators.
181 Specifically, if LOCALE is a particular locale (a buffer, window,
182 frame, device, or `global'), a list of instantiators for that
183 locale will be returned. Otherwise, if LOCALE is a locale type
184 (one of the symbols `buffer', `window', `frame', or `device'), the
185 specifications for all locales of that type will be returned.
186 Finally, if LOCALE is `all', the specifications for all locales of
187 all types will be returned.
189 The specifications in a specifier determine what the value of
190 PROPERTY will be in a particular "domain" or set of circumstances,
191 which is typically a particular Emacs window along with the buffer
192 it contains and the frame and device it lies within. The value is
193 derived from the instantiator associated with the most specific
194 locale (in the order buffer, window, frame, device, and `global')
195 that matches the domain in question. In other words, given a
196 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
197 will first be searched for a specification whose locale is the
198 buffer contained within that window; then for a specification
199 whose locale is the window itself; then for a specification whose
200 locale is the frame that the window is contained within; etc. The
201 first instantiator that is valid for the domain (usually this
202 means that the instantiator is recognized by the device [i.e. the
203 X server or TTY device] that the domain is on). The function
204 `face-property-instance' actually does all this, and is used to
205 determine how to display the face.
207 - Function: face-property-instance FACE PROPERTY &optional DOMAIN
209 This function returns the instance of FACE's PROPERTY in the
212 Under most circumstances, DOMAIN will be a particular window, and
213 the returned instance describes how the specified property
214 actually is displayed for that window and the particular buffer in
215 it. Note that this may not be the same as how the property
216 appears when the buffer is displayed in a different window or
217 frame, or how the property appears in the same window if you
218 switch to another buffer in that window; and in those cases, the
219 returned instance would be different.
221 The returned instance will typically be a color-instance,
222 font-instance, or pixmap-instance object, and you can query it
223 using the appropriate object-specific functions. For example, you
224 could use `color-instance-rgb-components' to find out the RGB
225 (red, green, and blue) components of how the `background' property
226 of the `highlight' face is displayed in a particular window. The
227 results might be different from the results you would get for
228 another window (perhaps the user specified a different color for
229 the frame that window is on; or perhaps the same color was
230 specified but the window is on a different X server, and that X
231 server has different RGB values for the color from this one).
233 DOMAIN defaults to the selected window if omitted.
235 DOMAIN can be a frame or device, instead of a window. The value
236 returned for a such a domain is used in special circumstances when
237 a more specific domain does not apply; for example, a frame value
238 might be used for coloring a toolbar, which is conceptually
239 attached to a frame rather than a particular window. The value is
240 also useful in determining what the value would be for a
241 particular window within the frame or device, if it is not
242 overridden by a more specific specification.
244 If PROPERTY does not name a built-in property, its value will
245 simply be returned unless it is a specifier object, in which case
246 it will be instanced using `specifier-instance'.
248 Optional arguments DEFAULT and NO-FALLBACK are the same as in
249 `specifier-instance'. *Note Specifiers::.
252 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
254 Face Convenience Functions
255 --------------------------
257 - Function: set-face-foreground FACE COLOR &optional LOCALE TAG
259 - Function: set-face-background FACE COLOR &optional LOCALE TAG
261 These functions set the foreground (respectively, background)
262 color of face FACE to COLOR. The argument COLOR should be a
263 string (the name of a color) or a color object as returned by
264 `make-color' (*note Colors::.).
266 - Function: set-face-background-pixmap FACE PIXMAP &optional LOCALE
268 This function sets the background pixmap of face FACE to PIXMAP.
269 The argument PIXMAP should be a string (the name of a bitmap or
270 pixmap file; the directories listed in the variable
271 `x-bitmap-file-path' will be searched) or a glyph object as
272 returned by `make-glyph' (*note Glyphs::.). The argument may also
273 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
274 are the size in pixels, and DATA is a string, containing the raw
277 - Function: set-face-font FACE FONT &optional LOCALE TAG HOW-TO-ADD
278 This function sets the font of face FACE. The argument FONT
279 should be a string or a font object as returned by `make-font'
282 - Function: set-face-underline-p FACE UNDERLINE-P &optional LOCALE TAG
284 This function sets the underline property of face FACE.
286 - Function: face-foreground FACE &optional LOCALE
287 - Function: face-background FACE &optional LOCALE
288 These functions return the foreground (respectively, background)
289 color specifier of face FACE. *Note Colors::.
291 - Function: face-background-pixmap FACE &optional LOCALE
292 This function return the background-pixmap glyph object of face
295 - Function: face-font FACE &optional LOCALE
296 This function returns the font specifier of face FACE. (Note:
297 This is not the same as the function `face-font' in FSF Emacs.)
300 - Function: face-font-name FACE &optional DOMAIN
301 This function returns the name of the font of face FACE, or `nil'
302 if it is unspecified. This is basically equivalent to `(font-name
303 (face-font FACE) DOMAIN)' except that it does not cause an error
304 if FACE's font is `nil'. (This function is named `face-font' in
307 - Function: face-underline-p FACE &optional LOCALE
308 This function returns the underline property of face FACE.
310 - Function: face-foreground-instance FACE &optional DOMAIN
311 - Function: face-background-instance FACE &optional DOMAIN
312 These functions return the foreground (respectively, background)
313 color specifier of face FACE. *Note Colors::.
315 - Function: face-background-pixmap-instance FACE &optional DOMAIN
316 This function return the background-pixmap glyph object of face
319 - Function: face-font-instance FACE &optional DOMAIN
320 This function returns the font specifier of face FACE. *Note
324 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
326 Other Face Display Functions
327 ----------------------------
329 - Function: invert-face FACE &optional LOCALE
330 Swap the foreground and background colors of face FACE. If the
331 face doesn't specify both foreground and background, then its
332 foreground and background are set to the default background and
335 - Function: face-equal FACE1 FACE2 &optional DOMAIN
336 This returns `t' if the faces FACE1 and FACE2 will display in the
337 same way. DOMAIN is as in `face-property-instance'.
339 - Function: face-differs-from-default-p FACE &optional DOMAIN
340 This returns `t' if the face FACE displays differently from the
341 default face. DOMAIN is as in `face-property-instance'.
344 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
349 This section describes how to work with font specifier and font
350 instance objects, which encapsulate fonts in the window system.
354 * Font Specifiers:: Specifying how a font will appear.
355 * Font Instances:: What a font specifier gets instanced as.
356 * Font Instance Names:: The name of a font instance.
357 * Font Instance Size:: The size of a font instance.
358 * Font Instance Characteristics:: Display characteristics of font instances.
359 * Font Convenience Functions:: Convenience functions that automatically
360 instance and retrieve the properties
364 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
369 - Function: font-specifier-p OBJECT
370 This predicate returns `t' if OBJECT is a font specifier, and
374 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
379 - Function: font-instance-p OBJECT
380 This predicate returns `t' if OBJECT is a font instance, and `nil'
383 - Function: make-font-instance NAME &optional DEVICE NOERROR
384 This function creates a new font-instance object of the specified
385 name. DEVICE specifies the device this object applies to and
386 defaults to the selected device. An error is signalled if the
387 font is unknown or cannot be allocated; however, if NOERROR is
388 non-`nil', `nil' is simply returned in this case.
390 The returned object is a normal, first-class lisp object. The way
391 you "deallocate" the font is the way you deallocate any other lisp
392 object: you drop all pointers to it and allow it to be garbage
393 collected. When these objects are GCed, the underlying X data is
397 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
402 - Function: list-fonts PATTERN &optional DEVICE
403 This function returns a list of font names matching the given
404 pattern. DEVICE specifies which device to search for names, and
405 defaults to the currently selected device.
407 - Function: font-instance-name FONT-INSTANCE
408 This function returns the name used to allocate FONT-INSTANCE.
410 - Function: font-instance-truename FONT-INSTANCE
411 This function returns the canonical name of the given font
412 instance. Font names are patterns which may match any number of
413 fonts, of which the first found is used. This returns an
414 unambiguous name for that font (but not necessarily its only
418 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
423 - Function: x-font-size FONT
424 This function returns the nominal size of the given font. This is
425 done by parsing its name, so it's likely to lose. X fonts can be
426 specified (by the user) in either pixels or 10ths of points, and
427 this returns the first one it finds, so you have to decide which
428 units the returned value is measured in yourself ...
430 - Function: x-find-larger-font FONT &optional DEVICE
431 This function loads a new, slightly larger version of the given
432 font (or font name). Returns the font if it succeeds, `nil'
433 otherwise. If scalable fonts are available, this returns a font
434 which is 1 point larger. Otherwise, it returns the next larger
435 version of this font that is defined.
437 - Function: x-find-smaller-font FONT &optional DEVICE
438 This function loads a new, slightly smaller version of the given
439 font (or font name). Returns the font if it succeeds, `nil'
440 otherwise. If scalable fonts are available, this returns a font
441 which is 1 point smaller. Otherwise, it returns the next smaller
442 version of this font that is defined.
445 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
447 Font Instance Characteristics
448 -----------------------------
450 - Function: font-instance-properties FONT
451 This function returns the properties (an alist or `nil') of
454 - Function: x-make-font-bold FONT &optional DEVICE
455 Given an X font specification, this attempts to make a "bold" font.
456 If it fails, it returns `nil'.
458 - Function: x-make-font-unbold FONT &optional DEVICE
459 Given an X font specification, this attempts to make a non-bold
460 font. If it fails, it returns `nil'.
462 - Function: x-make-font-italic FONT &optional DEVICE
463 Given an X font specification, this attempts to make an "italic"
464 font. If it fails, it returns `nil'.
466 - Function: x-make-font-unitalic FONT &optional DEVICE
467 Given an X font specification, this attempts to make a non-italic
468 font. If it fails, it returns `nil'.
470 - Function: x-make-font-bold-italic FONT &optional DEVICE
471 Given an X font specification, this attempts to make a
472 "bold-italic" font. If it fails, it returns `nil'.
475 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
477 Font Convenience Functions
478 --------------------------
480 - Function: font-name FONT &optional DOMAIN
481 This function returns the name of the FONT in the specified
482 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
483 is normally a window and defaults to the selected window if
484 omitted. This is equivalent to using `specifier-instance' and
485 applying `font-instance-name' to the result.
487 - Function: font-truename FONT &optional DOMAIN
488 This function returns the truename of the FONT in the specified
489 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
490 is normally a window and defaults to the selected window if
491 omitted. This is equivalent to using `specifier-instance' and
492 applying `font-instance-truename' to the result.
494 - Function: font-properties FONT &optional DOMAIN
495 This function returns the properties 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-properties' to the result.
502 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
509 * Color Specifiers:: Specifying how a color will appear.
510 * Color Instances:: What a color specifier gets instanced as.
511 * Color Instance Properties:: Properties of color instances.
512 * Color Convenience Functions:: Convenience functions that automatically
513 instance and retrieve the properties
514 of a color specifier.
517 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
522 - Function: color-specifier-p OBJECT
523 This function returns non-`nil' if OBJECT is a color specifier.
526 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
531 A "color-instance object" is an object describing the way a color
532 specifier is instanced in a particular domain. Functions such as
533 `face-background-instance' return a color-instance object. For example,
535 (face-background-instance 'default (next-window))
536 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
538 The color-instance object returned describes the way the background
539 color of the `default' face is displayed in the next window after the
542 - Function: color-instance-p OBJECT
543 This function returns non-`nil' if OBJECT is a color-instance.
546 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
548 Color Instance Properties
549 -------------------------
551 - Function: color-instance-name COLOR-INSTANCE
552 This function returns the name used to allocate COLOR-INSTANCE.
554 - Function: color-instance-rgb-components COLOR-INSTANCE
555 This function returns a three element list containing the red,
556 green, and blue color components of COLOR-INSTANCE.
558 (color-instance-rgb-components
559 (face-background-instance 'default (next-window)))
560 => (65535 58596 46517)
563 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
565 Color Convenience Functions
566 ---------------------------
568 - Function: color-name COLOR &optional DOMAIN
569 This function returns the name of the COLOR in the specified
570 DOMAIN, if any. COLOR should be a color specifier object and
571 DOMAIN is normally a window and defaults to the selected window if
572 omitted. This is equivalent to using `specifier-instance' and
573 applying `color-instance-name' to the result.
575 - Function: color-rgb-components COLOR &optional DOMAIN
576 This function returns the RGB components of the COLOR in the
577 specified DOMAIN, if any. COLOR should be a color specifier
578 object and DOMAIN is normally a window and defaults to the
579 selected window if omitted. This is equivalent to using
580 `specifier-instance' and applying `color-instance-rgb-components'
583 (color-rgb-components (face-background 'default (next-window)))
584 => (65535 58596 46517)
587 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
592 A "glyph" is an object that is used for pixmaps and images of all
593 sorts, as well as for things that "act" like pixmaps, such as
594 non-textual strings ("annotations") displayed in a buffer or in the
595 margins. It is used in begin-glyphs and end-glyphs attached to extents,
596 marginal and textual annotations, overlay arrows (`overlay-arrow-*'
597 variables), toolbar buttons, mouse pointers, frame icons, truncation and
598 continuation markers, and the like. (Basically, any place there is an
599 image or something that acts like an image, there will be a glyph object
602 The actual image that is displayed (as opposed to its position or
603 clipping) is defined by an "image specifier" object contained within
604 the glyph. The separation between an image specifier object and a
605 glyph object is made because the glyph includes other properties than
606 just the actual image: e.g. the face it is displayed in (for text
607 images), the alignment of the image (when it is in a buffer), etc.
609 - Function: glyphp OBJECT
610 This function returns `t' if OBJECT is a glyph.
614 * Glyph Functions:: Functions for working with glyphs.
615 * Images:: Graphical images displayed in a frame.
616 * Glyph Types:: Each glyph has a particular type.
617 * Mouse Pointer:: Controlling the mouse pointer.
618 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
619 * Subwindows:: Inserting an externally-controlled subwindow
623 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
630 * Creating Glyphs:: Creating new glyphs.
631 * Glyph Properties:: Accessing and modifying a glyph's properties.
632 * Glyph Convenience Functions::
633 Convenience functions for accessing particular
634 properties of a glyph.
635 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
638 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
643 - Function: make-glyph &optional SPEC-LIST TYPE
644 This function creates a new glyph object of type TYPE.
646 SPEC-LIST is used to initialize the glyph's image. It is
647 typically an image instantiator (a string or a vector; *Note Image
648 Specifiers::), but can also be a list of such instantiators (each
649 one in turn is tried until an image is successfully produced), a
650 cons of a locale (frame, buffer, etc.) and an instantiator, a list
651 of such conses, or any other form accepted by
652 `canonicalize-spec-list'. *Note Specifiers::, for more
653 information about specifiers.
655 TYPE specifies the type of the glyph, which specifies in which
656 contexts the glyph can be used, and controls the allowable image
657 types into which the glyph's image can be instantiated. TYPE
658 should be one of `buffer' (used for glyphs in an extent, the
659 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
660 for the mouse-pointer), or `icon' (used for a frame's icon), and
661 defaults to `buffer'. *Note Glyph Types::.
663 - Function: make-glyph-internal &optional TYPE
664 This function creates a new, uninitialized glyph of type TYPE.
666 - Function: make-pointer-glyph &optional SPEC-LIST
667 This function is equivalent to calling `make-glyph' with a TYPE of
670 - Function: make-icon-glyph &optional SPEC-LIST
671 This function is equivalent to calling `make-glyph' with a TYPE of
675 File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
680 Each glyph has a list of properties, which control all of the
681 aspects of the glyph's appearance. The following symbols have
685 The image used to display the glyph.
688 Percent above baseline that glyph is to be displayed. Only for
689 glyphs displayed inside of a buffer.
692 Whether the glyph contributes to the height of the line it's on.
693 Only for glyphs displayed inside of a buffer.
696 Face of this glyph (*not* a specifier).
698 - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
700 This function changes a property of a GLYPH.
702 For built-in properties, the actual value of the property is a
703 specifier and you cannot change this; but you can change the
704 specifications within the specifier, and that is what this
705 function will do. For user-defined properties, you can use this
706 function to either change the actual value of the property or, if
707 this value is a specifier, change the specifications within it.
709 If PROPERTY is a built-in property, the specifications to be added
710 to this property can be supplied in many different ways:
712 * If VALUE is a simple instantiator (e.g. a string naming a
713 pixmap filename) or a list of instantiators, then the
714 instantiator(s) will be added as a specification of the
715 property for the given LOCALE (which defaults to `global' if
718 * If VALUE is a list of specifications (each of which is a cons
719 of a locale and a list of instantiators), then LOCALE must be
720 `nil' (it does not make sense to explicitly specify a locale
721 in this case), and specifications will be added as given.
723 * If VALUE is a specifier (as would be returned by
724 `glyph-property' if no LOCALE argument is given), then some
725 or all of the specifications in the specifier will be added
726 to the property. In this case, the function is really
727 equivalent to `copy-specifier' and LOCALE has the same
728 semantics (if it is a particular locale, the specification
729 for the locale will be copied; if a locale type,
730 specifications for all locales of that type will be copied;
731 if `nil' or `all', then all specifications will be copied).
733 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
734 `append', `remove-tag-set-prepend', `remove-tag-set-append',
735 `remove-locale', `remove-locale-type', or `remove-all'. See
736 `copy-specifier' and `add-spec-to-specifier' for a description of
737 what each of these means. Most of the time, you do not need to
738 worry about this argument; the default behavior usually is fine.
740 In general, it is OK to pass an instance object (e.g. as returned
741 by `glyph-property-instance') as an instantiator in place of an
742 actual instantiator. In such a case, the instantiator used to
743 create that instance object will be used (for example, if you set
744 a font-instance object as the value of the `font' property, then
745 the font name used to create that object will be used instead).
746 If some cases, however, doing this conversion does not make sense,
747 and this will be noted in the documentation for particular types
750 If PROPERTY is not a built-in property, then this function will
751 simply set its value if LOCALE is `nil'. However, if LOCALE is
752 given, then this function will attempt to add VALUE as the
753 instantiator for the given LOCALE, using `add-spec-to-specifier'.
754 If the value of the property is not a specifier, it will
755 automatically be converted into a `generic' specifier.
757 - Function: glyph-property GLYPH PROPERTY &optional LOCALE
758 This function returns GLYPH's value of the given PROPERTY.
760 If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
761 be returned. For built-in properties, this will be a specifier
762 object of a type appropriate to the property (e.g. a font or color
763 specifier). For other properties, this could be anything.
765 If LOCALE is supplied, then instead of returning the actual value,
766 the specification(s) for the given locale or locale type will be
767 returned. This will only work if the actual value of PROPERTY is
768 a specifier (this will always be the case for built-in properties,
769 but may or may not apply to user-defined properties). If the
770 actual value of PROPERTY is not a specifier, this value will
771 simply be returned regardless of LOCALE.
773 The return value will be a list of instantiators (e.g. vectors
774 specifying pixmap data), or a list of specifications, each of
775 which is a cons of a locale and a list of instantiators.
776 Specifically, if LOCALE is a particular locale (a buffer, window,
777 frame, device, or `global'), a list of instantiators for that
778 locale will be returned. Otherwise, if LOCALE is a locale type
779 (one of the symbols `buffer', `window', `frame', or `device'), the
780 specifications for all locales of that type will be returned.
781 Finally, if LOCALE is `all', the specifications for all locales of
782 all types will be returned.
784 The specifications in a specifier determine what the value of
785 PROPERTY will be in a particular "domain" or set of circumstances,
786 which is typically a particular Emacs window along with the buffer
787 it contains and the frame and device it lies within. The value is
788 derived from the instantiator associated with the most specific
789 locale (in the order buffer, window, frame, device, and `global')
790 that matches the domain in question. In other words, given a
791 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
792 will first be searched for a specification whose locale is the
793 buffer contained within that window; then for a specification
794 whose locale is the window itself; then for a specification whose
795 locale is the frame that the window is contained within; etc. The
796 first instantiator that is valid for the domain (usually this
797 means that the instantiator is recognized by the device [i.e. the
798 X server or TTY device] that the domain is on). The function
799 `glyph-property-instance' actually does all this, and is used to
800 determine how to display the glyph.
802 - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
804 This function returns the instance of GLYPH's PROPERTY in the
807 Under most circumstances, DOMAIN will be a particular window, and
808 the returned instance describes how the specified property
809 actually is displayed for that window and the particular buffer in
810 it. Note that this may not be the same as how the property
811 appears when the buffer is displayed in a different window or
812 frame, or how the property appears in the same window if you
813 switch to another buffer in that window; and in those cases, the
814 returned instance would be different.
816 The returned instance is an image-instance object, and you can
817 query it using the appropriate image instance functions. For
818 example, you could use `image-instance-depth' to find out the
819 depth (number of color planes) of a pixmap displayed in a
820 particular window. The results might be different from the
821 results you would get for another window (perhaps the user
822 specified a different image for the frame that window is on; or
823 perhaps the same image was specified but the window is on a
824 different X server, and that X server has different color
825 capabilities from this one).
827 DOMAIN defaults to the selected window if omitted.
829 DOMAIN can be a frame or device, instead of a window. The value
830 returned for such a domain is used in special circumstances when a
831 more specific domain does not apply; for example, a frame value
832 might be used for coloring a toolbar, which is conceptually
833 attached to a frame rather than a particular window. The value is
834 also useful in determining what the value would be for a
835 particular window within the frame or device, if it is not
836 overridden by a more specific specification.
838 If PROPERTY does not name a built-in property, its value will
839 simply be returned unless it is a specifier object, in which case
840 it will be instanced using `specifier-instance'.
842 Optional arguments DEFAULT and NO-FALLBACK are the same as in
843 `specifier-instance'. *Note Specifiers::.
845 - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
847 This function removes a property from a glyph. For built-in
848 properties, this is analogous to `remove-specifier'. *Note
849 remove-specifier-p: Specifiers, for the meaning of the LOCALE,
850 TAG-SET, and EXACT-P arguments.
853 File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
855 Glyph Convenience Functions
856 ---------------------------
858 The following functions are provided for working with specific
859 properties of a glyph. Note that these are exactly like calling the
860 general functions described above and passing in the appropriate value
863 Remember that if you want to determine the "value" of a specific
864 glyph property, you probably want to use the `*-instance' functions.
865 For example, to determine whether a glyph contributes to its line
866 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
867 latter will return a boolean specifier or a list of specifications, and
868 you probably aren't concerned with these.)
870 - Function: glyph-image GLYPH &optional LOCALE
871 This function is equivalent to calling `glyph-property' with a
872 property of `image'. The return value will be an image specifier
873 if LOCALE is `nil' or omitted; otherwise, it will be a
874 specification or list of specifications.
876 - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
878 This function is equivalent to calling `set-glyph-property' with a
881 - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
883 This function returns the instance of GLYPH's image in the given
884 DOMAIN, and is equivalent to calling `glyph-property-instance'
885 with a property of `image'. The return value will be an image
888 Normally DOMAIN will be a window or `nil' (meaning the selected
889 window), and an instance object describing how the image appears
890 in that particular window and buffer will be returned.
892 - Function: glyph-contrib-p GLYPH &optional LOCALE
893 This function is equivalent to calling `glyph-property' with a
894 property of `contrib-p'. The return value will be a boolean
895 specifier if LOCALE is `nil' or omitted; otherwise, it will be a
896 specification or list of specifications.
898 - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
900 This function is equivalent to calling `set-glyph-property' with a
901 property of `contrib-p'.
903 - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
905 This function returns whether the glyph contributes to its line
906 height in the given DOMAIN, and is equivalent to calling
907 `glyph-property-instance' with a property of `contrib-p'. The
908 return value will be either `nil' or `t'. (Normally DOMAIN will be
909 a window or `nil', meaning the selected window.)
911 - Function: glyph-baseline GLYPH &optional LOCALE
912 This function is equivalent to calling `glyph-property' with a
913 property of `baseline'. The return value will be a specifier if
914 LOCALE is `nil' or omitted; otherwise, it will be a specification
915 or list of specifications.
917 - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
919 This function is equivalent to calling `set-glyph-property' with a
920 property of `baseline'.
922 - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
924 This function returns the instance of GLYPH's baseline value in
925 the given DOMAIN, and is equivalent to calling
926 `glyph-property-instance' with a property of `baseline'. The
927 return value will be an integer or `nil'.
929 Normally DOMAIN will be a window or `nil' (meaning the selected
930 window), and an instance object describing the baseline value
931 appears in that particular window and buffer will be returned.
933 - Function: glyph-face GLYPH
934 This function returns the face of GLYPH. (Remember, this is not a
935 specifier, but a simple property.)
937 - Function: set-glyph-face GLYPH FACE
938 This function changes the face of GLYPH to FACE.
941 File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
946 - Function: glyph-width GLYPH &optional WINDOW
947 This function returns the width of GLYPH on WINDOW. This may not
948 be exact as it does not take into account all of the context that
951 - Function: glyph-ascent GLYPH &optional WINDOW
952 This function returns the ascent value of GLYPH on WINDOW. This
953 may not be exact as it does not take into account all of the
954 context that redisplay will.
956 - Function: glyph-descent GLYPH &optional WINDOW
957 This function returns the descent value of GLYPH on WINDOW. This
958 may not be exact as it does not take into account all of the
959 context that redisplay will.
961 - Function: glyph-height GLYPH &optional WINDOW
962 This function returns the height of GLYPH on WINDOW. (This is
963 equivalent to the sum of the ascent and descent values.) This may
964 not be exact as it does not take into account all of the context
968 File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
975 * Image Specifiers:: Specifying how an image will appear.
976 * Image Instantiator Conversion::
977 Conversion is applied to image instantiators
978 at the time they are added to an
979 image specifier or at the time they
980 are passed to `make-image-instance'.
981 * Image Instances:: What an image specifier gets instanced as.
projects / chise / xemacs-chise.git.1 / blob