1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Merging Faces, Next: Basic Face Functions, Up: Faces
55 Merging Faces for Display
56 -------------------------
58 Here are all the ways to specify which face to use for display of
61 * With defaults. Each frame has a "default face", which is used for
62 all text that doesn't somehow specify another face. The face named
63 `default' applies to the text area, while the faces `left-margin'
64 and `right-margin' apply to the left and right margin areas.
66 * With text properties. A character may have a `face' property; if
67 so, it's displayed with that face. (Text properties are actually
68 implemented in terms of extents.) *Note Text Properties::.
70 * With extents. An extent may have a `face' property, which applies
71 to all the text covered by the extent; in addition, if the
72 `highlight' property is set, the `highlight' property applies when
73 the mouse moves over the extent or if the extent is explicitly
74 highlighted. *Note Extents::.
76 * With annotations. Annotations that are inserted into a buffer can
77 specify their own face. (Annotations are actually implemented in
78 terms of extents.) *Note Annotations::.
80 If these various sources together specify more than one face for a
81 particular character, XEmacs merges the properties of the various faces
82 specified. Extents, text properties, and annotations all use the same
83 underlying representation (as extents). When multiple extents cover one
84 character, an extent with higher priority overrides those with lower
85 priority. *Note Extents::. If no extent covers a particular character,
86 the `default' face is used.
88 If a background pixmap is specified, it determines what will be
89 displayed in the background of text characters. If the background
90 pixmap is actually a pixmap, with its colors specified, those colors are
91 used; if it is a bitmap, the face's foreground and background colors are
95 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
97 Basic Functions for Working with Faces
98 --------------------------------------
100 The properties a face can specify include the font, the foreground
101 color, the background color, the background pixmap, the underlining,
102 the display table, and (for TTY devices) whether the text is to be
103 highlighted, dimmed, blinking, or displayed in reverse video. The face
104 can also leave these unspecified, causing them to assume the value of
105 the corresponding property of the `default' face.
107 Here are the basic primitives for working with faces.
109 - Function: make-face name &optional doc-string temporary
110 This function defines and returns a new face named NAME, initially
111 with all properties unspecified. It does nothing if there is
112 already a face named NAME. Optional argument DOC-STRING specifies
113 an explanatory string used for descriptive purposes. If optional
114 argument TEMPORARY is non-`nil', the face will automatically
115 disappear when there are no more references to it anywhere in text
116 or Lisp code (otherwise, the face will continue to exist
117 indefinitely even if it is not used).
119 - Function: face-list &optional temporary
120 This function returns a list of the names of all defined faces. If
121 TEMPORARY is `nil', only the permanent faces are included. If it
122 is `t', only the temporary faces are included. If it is any other
123 non-`nil' value both permanent and temporary are included.
125 - Function: facep object
126 This function returns `t' if OBJECT is a face, else `nil'.
128 - Function: copy-face old-face new-name &optional locale tag-set
130 This function defines a new face named NEW-NAME which is a copy of
131 the existing face named OLD-FACE. If there is already a face
132 named NEW-NAME, then it alters the face to have the same
133 properties as OLD-FACE.
135 LOCALE, TAG-SET, EXACT-P and HOW-TO-ADD let you copy just parts of
136 the old face rather than the whole face, and are as in
137 `copy-specifier' (*note Specifiers::).
140 File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
145 You can examine and modify the properties of an existing face with
146 the following functions.
148 The following symbols have predefined meanings:
151 The foreground color of the face.
154 The background color of the face.
157 The font used to display text covered by this face.
160 The display table of the face.
163 The pixmap displayed in the background of the face. Only used by
167 Underline all text covered by this face.
170 Highlight all text covered by this face. Only used by faces on TTY
174 Dim all text covered by this face. Only used by faces on TTY
178 Blink all text covered by this face. Only used by faces on TTY
182 Reverse the foreground and background colors. Only used by faces
186 Description of what the face's normal use is. NOTE: This is not a
187 specifier, unlike all the other built-in properties, and cannot
188 contain locale-specific values.
190 - Function: set-face-property face property value &optional locale
192 This function changes a property of a FACE.
194 For built-in properties, the actual value of the property is a
195 specifier and you cannot change this; but you can change the
196 specifications within the specifier, and that is what this
197 function will do. For user-defined properties, you can use this
198 function to either change the actual value of the property or, if
199 this value is a specifier, change the specifications within it.
201 If PROPERTY is a built-in property, the specifications to be added
202 to this property can be supplied in many different ways:
204 If VALUE is a simple instantiator (e.g. a string naming a
205 font or color) or a list of instantiators, then the
206 instantiator(s) will be added as a specification of the
207 property for the given LOCALE (which defaults to `global' if
210 If VALUE is a list of specifications (each of which is a cons
211 of a locale and a list of instantiators), then LOCALE must be
212 `nil' (it does not make sense to explicitly specify a locale
213 in this case), and specifications will be added as given.
215 If VALUE is a specifier (as would be returned by
216 `face-property' if no LOCALE argument is given), then some or
217 all of the specifications in the specifier will be added to
218 the property. In this case, the function is really
219 equivalent to `copy-specifier' and LOCALE has the same
220 semantics (if it is a particular locale, the specification
221 for the locale will be copied; if a locale type,
222 specifications for all locales of that type will be copied;
223 if `nil' or `all', then all specifications will be copied).
225 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
226 `append', `remove-tag-set-prepend', `remove-tag-set-append',
227 `remove-locale', `remove-locale-type', or `remove-all'. See
228 `copy-specifier' and `add-spec-to-specifier' for a description of
229 what each of these means. Most of the time, you do not need to
230 worry about this argument; the default behavior usually is fine.
232 In general, it is OK to pass an instance object (e.g. as returned
233 by `face-property-instance') as an instantiator in place of an
234 actual instantiator. In such a case, the instantiator used to
235 create that instance object will be used (for example, if you set
236 a font-instance object as the value of the `font' property, then
237 the font name used to create that object will be used instead).
238 If some cases, however, doing this conversion does not make sense,
239 and this will be noted in the documentation for particular types
242 If PROPERTY is not a built-in property, then this function will
243 simply set its value if LOCALE is `nil'. However, if LOCALE is
244 given, then this function will attempt to add VALUE as the
245 instantiator for the given LOCALE, using `add-spec-to-specifier'.
246 If the value of the property is not a specifier, it will
247 automatically be converted into a `generic' specifier.
249 - Function: remove-face-property face property &optional locale
251 This function removes a property of a FACE.
253 For built-in properties, this is analogous to `remove-specifier'.
254 For more information, *Note Other Specification Functions::.
256 When PROPERTY is not a built-in property, this function will just
257 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
258 is other than that, this function will attempt to remove VALUE as
259 the instantiator for the given LOCALE with `remove-specifier'. If
260 the value of the property is not a specifier, it will be converted
261 into a `generic' specifier automatically.
263 - Function: face-property face property &optional locale tag-set
265 This function returns FACE's value of the given PROPERTY.
267 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
268 returned. For built-in properties, this will be a specifier
269 object of a type appropriate to the property (e.g. a font or color
270 specifier). For other properties, this could be anything.
272 If LOCALE is supplied, then instead of returning the actual value,
273 the specification(s) for the given locale or locale type will be
274 returned. This will only work if the actual value of PROPERTY is
275 a specifier (this will always be the case for built-in properties,
276 but not or not may apply to user-defined properties). If the
277 actual value of PROPERTY is not a specifier, this value will
278 simply be returned regardless of LOCALE.
280 The return value will be a list of instantiators (e.g. strings
281 specifying a font or color name), or a list of specifications,
282 each of which is a cons of a locale and a list of instantiators.
283 Specifically, if LOCALE is a particular locale (a buffer, window,
284 frame, device, or `global'), a list of instantiators for that
285 locale will be returned. Otherwise, if LOCALE is a locale type
286 (one of the symbols `buffer', `window', `frame', or `device'), the
287 specifications for all locales of that type will be returned.
288 Finally, if LOCALE is `all', the specifications for all locales of
289 all types will be returned.
291 The specifications in a specifier determine what the value of
292 PROPERTY will be in a particular "domain" or set of circumstances,
293 which is typically a particular Emacs window along with the buffer
294 it contains and the frame and device it lies within. The value is
295 derived from the instantiator associated with the most specific
296 locale (in the order buffer, window, frame, device, and `global')
297 that matches the domain in question. In other words, given a
298 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
299 will first be searched for a specification whose locale is the
300 buffer contained within that window; then for a specification
301 whose locale is the window itself; then for a specification whose
302 locale is the frame that the window is contained within; etc. The
303 first instantiator that is valid for the domain (usually this
304 means that the instantiator is recognized by the device [i.e. the
305 X server or TTY device] that the domain is on). The function
306 `face-property-instance' actually does all this, and is used to
307 determine how to display the face.
309 - Function: face-property-instance face property &optional domain
311 This function returns the instance of FACE's PROPERTY in the
314 Under most circumstances, DOMAIN will be a particular window, and
315 the returned instance describes how the specified property
316 actually is displayed for that window and the particular buffer in
317 it. Note that this may not be the same as how the property
318 appears when the buffer is displayed in a different window or
319 frame, or how the property appears in the same window if you
320 switch to another buffer in that window; and in those cases, the
321 returned instance would be different.
323 The returned instance will typically be a color-instance,
324 font-instance, or pixmap-instance object, and you can query it
325 using the appropriate object-specific functions. For example, you
326 could use `color-instance-rgb-components' to find out the RGB
327 (red, green, and blue) components of how the `background' property
328 of the `highlight' face is displayed in a particular window. The
329 results might be different from the results you would get for
330 another window (perhaps the user specified a different color for
331 the frame that window is on; or perhaps the same color was
332 specified but the window is on a different X server, and that X
333 server has different RGB values for the color from this one).
335 DOMAIN defaults to the selected window if omitted.
337 DOMAIN can be a frame or device, instead of a window. The value
338 returned for a such a domain is used in special circumstances when
339 a more specific domain does not apply; for example, a frame value
340 might be used for coloring a toolbar, which is conceptually
341 attached to a frame rather than a particular window. The value is
342 also useful in determining what the value would be for a
343 particular window within the frame or device, if it is not
344 overridden by a more specific specification.
346 If PROPERTY does not name a built-in property, its value will
347 simply be returned unless it is a specifier object, in which case
348 it will be instanced using `specifier-instance'.
350 Optional arguments DEFAULT and NO-FALLBACK are the same as in
351 `specifier-instance'. *Note Specifiers::.
354 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
356 Face Convenience Functions
357 --------------------------
359 - Command: set-face-foreground face color &optional locale tag-set
361 - Command: set-face-background face color &optional locale tag-set
363 These functions set the foreground (respectively, background)
364 color of face FACE to COLOR. The argument COLOR should be a
365 string (the name of a color) or a color object as returned by
366 `make-color' (*note Colors::).
368 - Command: set-face-background-pixmap face pixmap &optional locale
370 This function sets the background pixmap of face FACE to PIXMAP.
371 The argument PIXMAP should be a string (the name of a bitmap or
372 pixmap file; the directories listed in the variable
373 `x-bitmap-file-path' will be searched) or a glyph object as
374 returned by `make-glyph' (*note Glyphs::). The argument may also
375 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
376 are the size in pixels, and DATA is a string, containing the raw
379 - Command: set-face-font face font &optional locale tag-set how-to-add
380 This function sets the font of face FACE. The argument FONT
381 should be a string or a font object as returned by `make-font'
384 - Command: set-face-underline-p face underline-p &optional locale
386 This function sets the underline property of face FACE.
388 - Function: face-foreground face &optional locale tag-set exact-p
389 - Function: face-background face &optional locale tag-set exact-p
390 These functions return the foreground (respectively, background)
391 color specifier of face FACE. *Note Colors::.
393 - Function: face-background-pixmap face &optional locale tag-set
395 This function return the background-pixmap glyph object of face
398 - Function: face-font face &optional locale tag-set exact-p
399 This function returns the font specifier of face FACE. (Note:
400 This is not the same as the function `face-font' in FSF Emacs.)
404 - Function: face-font-name face &optional domain
405 This function returns the name of the font of face FACE, or `nil'
406 if it is unspecified. This is basically equivalent to `(font-name
407 (face-font FACE) DOMAIN)' except that it does not cause an error
408 if FACE's font is `nil'. (This function is named `face-font' in
411 - Function: face-underline-p face &optional locale
412 This function returns the underline property of face FACE.
414 - Function: face-foreground-instance face &optional domain
415 - Function: face-background-instance face &optional domain
416 These functions return the foreground (respectively, background)
417 color specifier of face FACE. *Note Colors::.
419 - Function: face-background-pixmap-instance face &optional domain
420 This function return the background-pixmap glyph object of face
423 - Function: face-font-instance face &optional domain
424 This function returns the font specifier of face FACE. *Note
428 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
430 Other Face Display Functions
431 ----------------------------
433 - Command: invert-face face &optional locale
434 Swap the foreground and background colors of face FACE. If the
435 face doesn't specify both foreground and background, then its
436 foreground and background are set to the default background and
439 - Function: face-equal face1 face2 &optional domain
440 This returns `t' if the faces FACE1 and FACE2 will display in the
441 same way. DOMAIN is as in `face-property-instance'.
443 - Function: face-differs-from-default-p face &optional domain
444 This returns `t' if the face FACE displays differently from the
445 default face. DOMAIN is as in `face-property-instance'.
448 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
453 This section describes how to work with font specifier and font
454 instance objects, which encapsulate fonts in the window system.
458 * Font Specifiers:: Specifying how a font will appear.
459 * Font Instances:: What a font specifier gets instanced as.
460 * Font Instance Names:: The name of a font instance.
461 * Font Instance Size:: The size of a font instance.
462 * Font Instance Characteristics:: Display characteristics of font instances.
463 * Font Convenience Functions:: Convenience functions that automatically
464 instance and retrieve the properties
468 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
473 - Function: font-specifier-p object
474 This predicate returns `t' if OBJECT is a font specifier, and
477 - Function: make-font-specifier spec-list
478 Return a new `font' specifier object with the given specification
479 list. SPEC-LIST can be a list of specifications (each of which is
480 a cons of a locale and a list of instantiators), a single
481 instantiator, or a list of instantiators. *Note Specifiers::, for
482 more information about specifiers.
484 Valid instantiators for font specifiers are:
486 * A string naming a font (e.g. under X this might be
487 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
488 14-point upright medium-weight Courier font).
490 * A font instance (use that instance directly if the device
491 matches, or use the string that generated it).
493 * A vector of no elements (only on TTY's; this means to set no
494 font at all, thus using the "natural" font of the terminal's
497 * A vector of one element (a face to inherit from).
500 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
505 - Function: font-instance-p object
506 This predicate returns `t' if OBJECT is a font instance, and `nil'
509 - Function: make-font-instance name &optional device noerror
510 This function creates a new font-instance object of the specified
511 name. DEVICE specifies the device this object applies to and
512 defaults to the selected device. An error is signalled if the
513 font is unknown or cannot be allocated; however, if NOERROR is
514 non-`nil', `nil' is simply returned in this case.
516 The returned object is a normal, first-class lisp object. The way
517 you "deallocate" the font is the way you deallocate any other lisp
518 object: you drop all pointers to it and allow it to be garbage
519 collected. When these objects are GCed, the underlying X data is
523 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
528 - Function: list-fonts pattern &optional device
529 This function returns a list of font names matching the given
530 pattern. DEVICE specifies which device to search for names, and
531 defaults to the currently selected device.
533 - Function: font-instance-name font-instance
534 This function returns the name used to allocate FONT-INSTANCE.
536 - Function: font-instance-truename font-instance
537 This function returns the canonical name of the given font
538 instance. Font names are patterns which may match any number of
539 fonts, of which the first found is used. This returns an
540 unambiguous name for that font (but not necessarily its only
544 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
549 - Function: x-font-size font
550 This function returns the nominal size of the given font. This is
551 done by parsing its name, so it's likely to lose. X fonts can be
552 specified (by the user) in either pixels or 10ths of points, and
553 this returns the first one it finds, so you have to decide which
554 units the returned value is measured in yourself ...
556 - Function: x-find-larger-font font &optional device
557 This function loads a new, slightly larger version of the given
558 font (or font name). Returns the font if it succeeds, `nil'
559 otherwise. If scalable fonts are available, this returns a font
560 which is 1 point larger. Otherwise, it returns the next larger
561 version of this font that is defined.
563 - Function: x-find-smaller-font font &optional device
564 This function loads a new, slightly smaller version of the given
565 font (or font name). Returns the font if it succeeds, `nil'
566 otherwise. If scalable fonts are available, this returns a font
567 which is 1 point smaller. Otherwise, it returns the next smaller
568 version of this font that is defined.
571 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
573 Font Instance Characteristics
574 -----------------------------
576 - Function: font-instance-properties font-instance
577 This function returns the properties (an alist or `nil') of
580 - Function: x-make-font-bold font &optional device
581 Given an X font specification, this attempts to make a "bold" font.
582 If it fails, it returns `nil'.
584 - Function: x-make-font-unbold font &optional device
585 Given an X font specification, this attempts to make a non-bold
586 font. If it fails, it returns `nil'.
588 - Function: x-make-font-italic font &optional device
589 Given an X font specification, this attempts to make an "italic"
590 font. If it fails, it returns `nil'.
592 - Function: x-make-font-unitalic font &optional device
593 Given an X font specification, this attempts to make a non-italic
594 font. If it fails, it returns `nil'.
596 - Function: x-make-font-bold-italic font &optional device
597 Given an X font specification, this attempts to make a
598 "bold-italic" font. If it fails, it returns `nil'.
601 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
603 Font Convenience Functions
604 --------------------------
606 - Function: font-name font &optional domain
607 This function returns the name of the FONT in the specified
608 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
609 is normally a window and defaults to the selected window if
610 omitted. This is equivalent to using `specifier-instance' and
611 applying `font-instance-name' to the result.
613 - Function: font-truename font &optional domain
614 This function returns the truename of the FONT in the specified
615 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
616 is normally a window and defaults to the selected window if
617 omitted. This is equivalent to using `specifier-instance' and
618 applying `font-instance-truename' to the result.
620 - Function: font-properties font &optional domain
621 This function returns the properties of the FONT in the specified
622 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
623 is normally a window and defaults to the selected window if
624 omitted. This is equivalent to using `specifier-instance' and
625 applying `font-instance-properties' to the result.
628 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
635 * Color Specifiers:: Specifying how a color will appear.
636 * Color Instances:: What a color specifier gets instanced as.
637 * Color Instance Properties:: Properties of color instances.
638 * Color Convenience Functions:: Convenience functions that automatically
639 instance and retrieve the properties
640 of a color specifier.
643 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
648 - Function: color-specifier-p object
649 This function returns non-`nil' if OBJECT is a color specifier.
651 - Function: make-color-specifier spec-list
652 Return a new `color' specifier object with the given specification
653 list. SPEC-LIST can be a list of specifications (each of which is
654 a cons of a locale and a list of instantiators), a single
655 instantiator, or a list of instantiators. *Note Specifiers::, for
656 a detailed description of how specifiers work.
658 Valid instantiators for color specifiers are:
660 * A string naming a color (e.g. under X this might be
661 "lightseagreen2" or "#F534B2").
663 * A color instance (use that instance directly if the device
664 matches, or use the string that generated it).
666 * A vector of no elements (only on TTY's; this means to set no
667 color at all, thus using the "natural" color of the
670 * A vector of one or two elements: a face to inherit from, and
671 optionally a symbol naming which property of that face to
672 inherit, either `foreground' or `background' (if omitted,
673 defaults to the same property that this color specifier is
674 used for; if this specifier is not part of a face, the
675 instantiator would not be valid).
677 - Function: make-face-boolean-specifier spec-list
678 Return a new `face-boolean' specifier object with the given spec
679 list. SPEC-LIST can be a list of specifications (each of which is
680 a cons of a locale and a list of instantiators), a single
681 instantiator, or a list of instantiators. *Note Specifiers::, for
682 a detailed description of how specifiers work.
684 Valid instantiators for face-boolean specifiers are
688 * A vector of two or three elements: a face to inherit from,
689 optionally a symbol naming the property of that face to
690 inherit from (if omitted, defaults to the same property that
691 this face-boolean specifier is used for; if this specifier is
692 not part of a face, the instantiator would not be valid), and
693 optionally a value which, if non-`nil', means to invert the
694 sense of the inherited property.
698 File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
703 A "color-instance object" is an object describing the way a color
704 specifier is instanced in a particular domain. Functions such as
705 `face-background-instance' return a color-instance object. For example,
707 (face-background-instance 'default (next-window))
708 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
710 The color-instance object returned describes the way the background
711 color of the `default' face is displayed in the next window after the
714 - Function: color-instance-p object
715 This function returns non-`nil' if OBJECT is a color-instance.
718 File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
720 Color Instance Properties
721 -------------------------
723 - Function: color-instance-name color-instance
724 This function returns the name used to allocate COLOR-INSTANCE.
726 - Function: color-instance-rgb-components color-instance
727 This function returns a three element list containing the red,
728 green, and blue color components of COLOR-INSTANCE.
730 (color-instance-rgb-components
731 (face-background-instance 'default (next-window)))
732 => (65535 58596 46517)
735 File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
737 Color Convenience Functions
738 ---------------------------
740 - Function: color-name color &optional domain
741 This function returns the name of the COLOR in the specified
742 DOMAIN, if any. COLOR should be a color specifier object and
743 DOMAIN is normally a window and defaults to the selected window if
744 omitted. This is equivalent to using `specifier-instance' and
745 applying `color-instance-name' to the result.
747 - Function: color-rgb-components color &optional domain
748 This function returns the RGB components of the COLOR in the
749 specified DOMAIN, if any. COLOR should be a color specifier
750 object and DOMAIN is normally a window and defaults to the
751 selected window if omitted. This is equivalent to using
752 `specifier-instance' and applying `color-instance-rgb-components'
755 (color-rgb-components (face-background 'default (next-window)))
756 => (65535 58596 46517)
759 File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
764 A "glyph" is an object that is used for pixmaps, widgets and images
765 of all sorts, as well as for things that "act" like pixmaps, such as
766 non-textual strings ("annotations") displayed in a buffer or in the
767 margins. It is used in begin-glyphs and end-glyphs attached to
768 extents, marginal and textual annotations, overlay arrows
769 (`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
770 icons, truncation and continuation markers, and the like. (Basically,
771 any place there is an image or something that acts like an image, there
772 will be a glyph object representing it.)
774 The actual image that is displayed (as opposed to its position or
775 clipping) is defined by an "image specifier" object contained within
776 the glyph. The separation between an image specifier object and a
777 glyph object is made because the glyph includes other properties than
778 just the actual image: e.g. the face it is displayed in (for text
779 images), the alignment of the image (when it is in a buffer), etc.
781 - Function: glyphp object
782 This function returns `t' if OBJECT is a glyph.
786 * Glyph Functions:: Functions for working with glyphs.
787 * Images:: Graphical images displayed in a frame.
788 * Glyph Types:: Each glyph has a particular type.
789 * Mouse Pointer:: Controlling the mouse pointer.
790 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
791 * Subwindows:: Inserting an externally-controlled subwindow
795 File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
802 * Creating Glyphs:: Creating new glyphs.
803 * Glyph Properties:: Accessing and modifying a glyph's properties.
804 * Glyph Convenience Functions::
805 Convenience functions for accessing particular
806 properties of a glyph.
807 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
810 File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
815 - Function: make-glyph &optional spec-list type
816 This function creates a new glyph object of type TYPE.
818 SPEC-LIST is used to initialize the glyph's image. It is
819 typically an image instantiator (a string or a vector; *Note Image
820 Specifiers::), but can also be a list of such instantiators (each
821 one in turn is tried until an image is successfully produced), a
822 cons of a locale (frame, buffer, etc.) and an instantiator, a list
823 of such conses, or any other form accepted by
824 `canonicalize-spec-list'. *Note Specifiers::, for more
825 information about specifiers.
827 TYPE specifies the type of the glyph, which specifies in which
828 contexts the glyph can be used, and controls the allowable image
829 types into which the glyph's image can be instantiated. TYPE
830 should be one of `buffer' (used for glyphs in an extent, the
831 modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
832 for the mouse-pointer), or `icon' (used for a frame's icon), and
833 defaults to `buffer'. *Note Glyph Types::.
835 A glyph in XEmacs does *NOT* refer to a single unit of textual
836 display (the XEmacs term for this is "rune"), but rather is an
837 object encapsulating a graphical element, such as an image or
838 widget (an element such as a button or text field; "widget" is the
839 term for this under X Windows, and it's called a "control" under
840 MS Windows). This graphical element could appear in a buffer, a
841 margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
844 Creating a glyph using `make-glyph' does not specify _where_ the
845 glyph will be used, but it does specify _what_ the glyph will look
846 like. In particular, SPEC-LIST is used to specify this, and it's
847 used to initialize the glyph's `image' property, which is an image
848 specifier. (Note that "image" as used in the context of a glyph's
849 `image' property or in the terms "image specifier", "image
850 instantiator", or "image instance" does not refer to what people
851 normally think of as an image (which in XEmacs is called a
852 "pixmap"), but to any graphical element--a pixmap, a widget, or
853 even a block of text, when used in the places that call for a
854 glyph.) The format of the SPEC-LIST is typically an image
855 instantiator (a string or a vector; *Note Image Specifiers::), but
856 can also be a list of such instantiators (each one in turn is
857 tried until an image is successfully produced), a cons of a locale
858 (frame, buffer, etc.) and an instantiator, a list of such conses,
859 or any other form accepted by `canonicalize-spec-list'. *Note
860 Specifiers::, for more information about specifiers.
862 If you're not familiar with specifiers, you should be in order to
863 understand how glyphs work. The clearest introduction to
864 specifiers is in the Lispref manual, available under Info. (Choose
865 Help->Info->Info Contents on the menubar or type C-h i.) You can
866 also see `make-specifier' for a capsule summary. What's important
867 to keep in mind is that a specifier lets you set a different value
868 for any particular buffer, window, frame, device, or console.
869 This allows for a great deal of flexibility; in particular, only
870 one global glyph needs to exist for a particular purpose (e.g. the
871 icon used to represent an iconified frame, the mouse pointer used
872 over particular areas of a frame, etc.), and in these cases you do
873 not create your own glyph, but rather modify the existing one.
875 As well as using SPEC-LIST to initialize the glyph, you can set
876 specifications using `set-glyph-image'. Note that, due to a
877 possibly questionable historical design decision, a glyph itself
878 is not actually a specifier, but rather is an object containing an
879 image specifier (as well as other, seldom-used properties).
880 Therefore, you cannot set or access specifications for the glyph's
881 image by directly using `set-specifier', `specifier-instance' or
882 the like on the glyph; instead use them on `(glyph-image GLYPH)'
883 or use the convenience functions `set-glyph-image',
884 `glyph-image-instance', and `glyph-image'.
886 Once you have created a glyph, you specify where it will be used as
889 * To insert a glyph into a buffer, create an extent in the
890 buffer and then use `set-extent-begin-glyph' or
891 `set-extent-end-glyph' to set a glyph to be displayed at the
892 corresponding edge of the extent. (It is common to create
893 zero-width extents for this purpose.)
895 * To insert a glyph into the left or right margin of a buffer,
896 first make sure the margin is visible by setting a value for
897 the specifiers `left-margin-width' or `right-margin-width'.
898 (Not strictly necessary when using margin glyphs with layout
899 policy `whitespace'.) Then follow the same procedure above
900 for inserting a glyph in a buffer, and then set a non-default
901 layout policy for the glyph using
902 `set-extent-begin-glyph-layout' or
903 `set-extent-end-glyph-layout'. Alternatively, use the
904 high-level annotations API (see `make-annotation'). (In point
905 of fact, you can also use the annotations API for glyphs in a
906 buffer, by setting a layout policy of `text'.)
908 * To insert a glyph into the modeline, just put the glyph
909 directly as one of the modeline elements. (Unfortunately you
910 can't currently put a begin glyph or end glyph on one of the
911 modeline extents--they're ignored.)
913 * To insert a glyph into a toolbar, specify it as part of a
914 toolbar instantiator (typically set on the specifier
915 `default-toolbar'). See `default-toolbar' for more
916 information. (Note that it is standard practice to use a
917 symbol in place of the glyph list in the toolbar
918 instantiator; the symbol is evalled to get the glyph list.
919 This facilitates both creating the toolbar instantiator and
920 modifying individual glyphs in a toolbar later on. For
921 example, you can change the way that the Mail toolbar button
922 looks by modifying the value of the variable
923 `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
924 calling `(set-specifier-dirty-flag default-toolbar)'. (####
925 Unfortunately this doesn't quite work the way it should; the
926 change will appear in new frames, but not existing ones.
928 * To insert a glyph into a gutter, create or modify a gutter
929 instantiator (typically set on the specifier
930 `default-gutter'). Gutter instantiators consist of strings
931 or lists of strings, so to insert a glyph, create an extent
932 over the string, and use `set-extent-begin-glyph' or
933 `set-extent-end-glyph' to set a glyph to be displayed at the
934 corresponding edge of the extent, just like for glyphs in a
937 * To use a glyph as the icon for a frame, you do not actually
938 create a new glyph; rather, you change the specifications for
939 the existing glyph `frame-icon-glyph'. (Remember that,
940 because of the specifier nature of glyphs, you can set
941 different values for any particular buffer or frame.)
943 * To use a glyph as the mouse pointer, in general you do not
944 create a new glyph, but rather you change the specifications
945 of various existing glyphs, such as `text-pointer-glyph' for
946 the pointer used over text, `modeline-pointer-glyph' for the
947 pointer used over the modeline, etc. Do an apropos over
948 `*-pointer-glyph' to find all of them. (Note also that you
949 can temporarily set the mouse pointer to some specific shape
950 by using `set-frame-pointer', which takes an image instance,
951 as obtained from calling `glyph-image-instance' on a glyph of
952 type `pointer' - either one of the above-mentioned variables
953 or one you created yourself. (See below for what it means to
954 create a glyph of type `pointer'.) This pointer will last
955 only until the next mouse motion event is processed or
956 certain other things happen, such as creating or deleting a
957 window. (In fact, the above-mentioned pointer glyph variables
958 are implemented as part of the default handler for mouse
959 motion events. If you want to customize this behavior, take a
960 look at `mode-motion-hook', or `mouse-motion-handler' if you
961 really want to get low-level.)
963 * To use a glyph to control the shape of miscellaneous
964 redisplay effects such as the truncation and continuation
965 markers, set the appropriate existing glyph variables, as for
966 icons and pointers above. See `continuation-glyph',
967 `control-arrow-glyph', `hscroll-glyph',
968 `invisible-text-glyph', `octal-escape-glyph', and
969 `truncation-glyph'. See also `overlay-arrow-string', an odd
970 redisplay leftover which can be set to a glyph you created,
971 and will cause the glyph to be displayed on top of the text
972 position specified in the marker stored in
973 `overlay-arrow-position'.
975 * To use a glyph in a display table (i.e. to control the
976 appearance of any individual character), create the
977 appropriate character glyphs and then set a specification for
978 the specifier `current-display-table', which controls the
979 appearance of characters. You can also set an overriding
980 display table for use with text displayed in a particular
981 face; see `set-face-display-table' and `make-display-table'.
982 #### Note: Display tables do not currently support general
983 Mule characters. They will be overhauled at some point to
984 support this and to provide other features required under
987 * To use a glyph as the background pixmap of a face: Note that
988 the background pixmap of a face is actually an image
989 specifier - probably the only place in XEmacs where an image
990 specifier occurs outside of a glyph. Similarly to how the
991 glyph's image specifier works, you don't create your own
992 image specifier, but rather add specifications to the
993 existing one (using `set-face-background-pixmap'). Note that
994 the image instance that is generated in order to actually
995 display the background pixmap is of type `mono-pixmap',
996 meaning that it's a two-color image and the foreground and
997 background of the image get filled in with the corresponding
998 colors from the face.
1000 It is extremely rare that you will ever have to specify a value for
1001 TYPE, which should be one of `buffer' (used for glyphs in an
1002 extent, the modeline, the toolbar, or elsewhere in a buffer),
1003 `pointer' (used for the mouse-pointer), or `icon' (used for a
1004 frame's icon), and defaults to `buffer'. The only cases where it
1005 needs to be specified is when creating icon or pointer glyphs, and
1006 in both cases the necessary glyphs have already been created at
1007 startup and are accessed through the appropriate variables, e.g.
1008 `text-pointer-glyph' (or in general, `*-pointer-glyph') and
1009 `frame-icon-glyph'. *Note Glyph Types::.
1011 - Function: make-glyph-internal &optional type
1012 This function creates a new, uninitialized glyph of type TYPE.
1014 - Function: make-pointer-glyph &optional spec-list
1015 Return a new `pointer-glyph' object with the specification list
1016 SPEC-LIST. This function is equivalent to calling `make-glyph'
1017 with a TYPE of `pointer'.
1019 It is extremely unlikely that you will ever need to create a
1020 pointer glyph. Instead, you probably want to be calling
1021 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
1023 - Function: make-icon-glyph &optional spec-list
1024 Return a new `pointer-glyph' object with the specification list
1025 SPEC-LIST. This function is equivalent to calling `make-glyph'
1026 with a TYPE of `icon'.
1028 It is extremely unlikely that you will ever need to create a
1029 pointer glyph. Instead, you probably want to be calling
1030 `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.