2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995 Ben Wing.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/faces.info
8 @node Faces and Window-System Objects, Glyphs, Specifiers, top
9 @chapter Faces and Window-System Objects
11 @cindex window-system objects
14 * Faces:: Controlling the way text looks.
15 * Fonts:: Controlling the typeface of text.
16 * Colors:: Controlling the colour of text and pixmaps.
23 A @dfn{face} is a named collection of graphical properties: font,
24 foreground color, background color, background pixmap, optional
25 underlining, and (on TTY devices) whether the text is to be highlighted,
26 dimmed, blinking, or displayed in reverse video. Faces control the
27 display of text on the screen. Every face has a name, which is a symbol
28 such as @code{default} or @code{modeline}.
30 Each built-in property of a face is controlled using a specifier,
31 which allows it to have separate values in particular buffers, frames,
32 windows, and devices and to further vary according to device type
33 (X or TTY) and device class (color, mono, or grayscale).
34 @xref{Specifiers}, for more information.
36 The face named @code{default} is used for ordinary text. The face named
37 @code{modeline} is used for displaying the modeline. The face named
38 @code{highlight} is used for highlighted extents (@pxref{Extents}). The
39 faces named @code{left-margin} and @code{right-margin} are used for the
40 left and right margin areas, respectively (@pxref{Annotations}). The
41 face named @code{zmacs-region} is used for the highlighted region
42 between point and mark.
46 * Merging Faces:: How SXEmacs decides which face to use
48 * Basic Face Functions:: How to define and examine faces.
49 * Face Properties:: How to access and modify a face's properties.
50 * Face Convenience Functions:: Convenience functions for accessing
51 particular properties of a face.
52 * Other Face Display Functions:: Other functions pertaining to how a
58 @subsection Merging Faces for Display
60 Here are all the ways to specify which face to use for display of text:
64 With defaults. Each frame has a @dfn{default face}, which is used for
65 all text that doesn't somehow specify another face. The face named
66 @code{default} applies to the text area, while the faces
67 @code{left-margin} and @code{right-margin} apply to the left and right
71 With text properties. A character may have a @code{face} property; if so,
72 it's displayed with that face. (Text properties are actually implemented
73 in terms of extents.) @xref{Text Properties}.
76 With extents. An extent may have a @code{face} property, which applies
77 to all the text covered by the extent; in addition, if the
78 @code{highlight} property is set, the @code{highlight} property applies
79 when the mouse moves over the extent or if the extent is explicitly
80 highlighted. @xref{Extents}.
83 With annotations. Annotations that are inserted into a buffer can specify
84 their own face. (Annotations are actually implemented in terms of extents.)
88 If these various sources together specify more than one face for a
89 particular character, SXEmacs merges the properties of the various faces
90 specified. Extents, text properties, and annotations all use the same
91 underlying representation (as extents). When multiple extents cover one
92 character, an extent with higher priority overrides those with lower
93 priority. @xref{Extents}. If no extent covers a particular character,
94 the @code{default} face is used.
96 @cindex background pixmap
97 If a background pixmap is specified, it determines what will be
98 displayed in the background of text characters. If the background
99 pixmap is actually a pixmap, with its colors specified, those colors are
100 used; if it is a bitmap, the face's foreground and background colors are
104 @node Basic Face Functions
105 @subsection Basic Functions for Working with Faces
107 The properties a face can specify include the font, the foreground
108 color, the background color, the background pixmap, the underlining,
109 the display table, and (for TTY devices) whether the text is to be
110 highlighted, dimmed, blinking, or displayed in reverse video.
111 The face can also leave these unspecified, causing them to assume the
112 value of the corresponding property of the @code{default} face.
114 Here are the basic primitives for working with faces.
116 @defun make-face name &optional doc-string temporary
117 This function defines and returns a new face named @var{name}, initially
118 with all properties unspecified. It does nothing if there is already a
119 face named @var{name}. Optional argument @var{doc-string} specifies
120 an explanatory string used for descriptive purposes. If optional
121 argument @var{temporary} is non-@code{nil}, the face will automatically
122 disappear when there are no more references to it anywhere in text or
123 Lisp code (otherwise, the face will continue to exist indefinitely
124 even if it is not used).
127 @defun face-list &optional temporary
128 This function returns a list of the names of all defined faces. If
129 @var{temporary} is @code{nil}, only the permanent faces are included.
130 If it is @code{t}, only the temporary faces are included. If it is any
131 other non-@code{nil} value both permanent and temporary are included.
135 This function returns @code{t} if @var{object} is a face, else @code{nil}.
138 @defun copy-face old-face new-name &optional locale tag-set exact-p how-to-add
139 This function defines a new face named @var{new-name} which is a copy of
140 the existing face named @var{old-face}. If there is already a face
141 named @var{new-name}, then it alters the face to have the same
142 properties as @var{old-face}.
144 @var{locale}, @var{tag-set}, @var{exact-p} and @var{how-to-add} let you
145 copy just parts of the old face rather than the whole face, and are as
146 in @code{copy-specifier} (@pxref{Specifiers}).
150 @node Face Properties
151 @subsection Face Properties
153 You can examine and modify the properties of an existing face with the
156 The following symbols have predefined meanings:
160 The foreground color of the face.
163 The background color of the face.
166 The font used to display text covered by this face.
169 The display table of the face.
171 @item background-pixmap
172 The pixmap displayed in the background of the face. Only used by faces
173 on GUI devices, currently X11, and GTK.
176 Underline all text covered by this face.
179 Highlight all text covered by this face. Only used by faces on TTY
183 Dim all text covered by this face. Only used by faces on TTY devices.
186 Blink all text covered by this face. Only used by faces on TTY devices.
189 Reverse the foreground and background colors. Only used by faces on TTY
193 Description of what the face's normal use is. NOTE: This is not a
194 specifier, unlike all the other built-in properties, and cannot contain
195 locale-specific values.
198 @defun set-face-property face property value &optional locale tag-set how-to-add
199 This function changes a property of a @var{face}.
201 For built-in properties, the actual value of the property is a specifier
202 and you cannot change this; but you can change the specifications within
203 the specifier, and that is what this function will do. For user-defined
204 properties, you can use this function to either change the actual value
205 of the property or, if this value is a specifier, change the
206 specifications within it.
208 If @var{property} is a built-in property, the specifications to be added
209 to this property can be supplied in many different ways:
212 If @var{value} is a simple instantiator (e.g. a string naming a font or
213 color) or a list of instantiators, then the instantiator(s) will be
214 added as a specification of the property for the given @var{locale}
215 (which defaults to @code{global} if omitted).
217 If @var{value} is a list of specifications (each of which is a cons of a
218 locale and a list of instantiators), then @var{locale} must be
219 @code{nil} (it does not make sense to explicitly specify a locale in
220 this case), and specifications will be added as given.
222 If @var{value} is a specifier (as would be returned by
223 @code{face-property} if no @var{locale} argument is given), then some or
224 all of the specifications in the specifier will be added to the
225 property. In this case, the function is really equivalent to
226 @code{copy-specifier} and @var{locale} has the same semantics (if it is
227 a particular locale, the specification for the locale will be copied; if
228 a locale type, specifications for all locales of that type will be
229 copied; if @code{nil} or @code{all}, then all specifications will be
233 @var{how-to-add} should be either @code{nil} or one of the symbols
234 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
235 @code{remove-tag-set-append}, @code{remove-locale},
236 @code{remove-locale-type}, or @code{remove-all}. See
237 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
238 of what each of these means. Most of the time, you do not need to worry
239 about this argument; the default behavior usually is fine.
241 In general, it is OK to pass an instance object (e.g. as returned by
242 @code{face-property-instance}) as an instantiator in place of an actual
243 instantiator. In such a case, the instantiator used to create that
244 instance object will be used (for example, if you set a font-instance
245 object as the value of the @code{font} property, then the font name used
246 to create that object will be used instead). If some cases, however,
247 doing this conversion does not make sense, and this will be noted in the
248 documentation for particular types of instance objects.
250 If @var{property} is not a built-in property, then this function will
251 simply set its value if @var{locale} is @code{nil}. However, if
252 @var{locale} is given, then this function will attempt to add
253 @var{value} as the instantiator for the given @var{locale}, using
254 @code{add-spec-to-specifier}. If the value of the property is not a
255 specifier, it will automatically be converted into a @code{generic}
259 @defun remove-face-property face property &optional locale tag-set exact-p
260 This function removes a property of a @var{face}.
262 For built-in properties, this is analogous to @code{remove-specifier}.
263 For more information, @xref{Other Specification Functions}.
265 When @var{property} is not a built-in property, this function will just
266 remove its value if @var{locale} is @code{nil} or @code{all}. However,
267 if @var{locale} is other than that, this function will attempt to remove
268 @var{value} as the instantiator for the given @var{locale} with
269 @code{remove-specifier}. If the value of the property is not a
270 specifier, it will be converted into a @code{generic} specifier
274 @defun face-property face property &optional locale tag-set exact-p
275 This function returns @var{face}'s value of the given @var{property}.
277 If @var{locale} is omitted, the @var{face}'s actual value for
278 @var{property} will be returned. For built-in properties, this will be
279 a specifier object of a type appropriate to the property (e.g. a font or
280 color specifier). For other properties, this could be anything.
282 If @var{locale} is supplied, then instead of returning the actual value,
283 the specification(s) for the given locale or locale type will be
284 returned. This will only work if the actual value of @var{property} is
285 a specifier (this will always be the case for built-in properties, but
286 not or not may apply to user-defined properties). If the actual value
287 of @var{property} is not a specifier, this value will simply be returned
288 regardless of @var{locale}.
290 The return value will be a list of instantiators (e.g. strings
291 specifying a font or color name), or a list of specifications, each of
292 which is a cons of a locale and a list of instantiators. Specifically,
293 if @var{locale} is a particular locale (a buffer, window, frame, device,
294 or @code{global}), a list of instantiators for that locale will be
295 returned. Otherwise, if @var{locale} is a locale type (one of the
296 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
297 the specifications for all locales of that type will be returned.
298 Finally, if @var{locale} is @code{all}, the specifications for all
299 locales of all types will be returned.
301 The specifications in a specifier determine what the value of
302 @var{property} will be in a particular @dfn{domain} or set of
303 circumstances, which is typically a particular Emacs window along with
304 the buffer it contains and the frame and device it lies within. The
305 value is derived from the instantiator associated with the most specific
306 locale (in the order buffer, window, frame, device, and @code{global})
307 that matches the domain in question. In other words, given a domain
308 (i.e. an Emacs window, usually), the specifier for @var{property} will
309 first be searched for a specification whose locale is the buffer
310 contained within that window; then for a specification whose locale is
311 the window itself; then for a specification whose locale is the frame
312 that the window is contained within; etc. The first instantiator that
313 is valid for the domain (usually this means that the instantiator is
314 recognized by the device [i.e. the X server or TTY device] that the
315 domain is on). The function @code{face-property-instance} actually does
316 all this, and is used to determine how to display the face.
319 @defun face-property-instance face property &optional domain default no-fallback
320 This function returns the instance of @var{face}'s @var{property} in the
321 specified @var{domain}.
323 Under most circumstances, @var{domain} will be a particular window, and
324 the returned instance describes how the specified property actually is
325 displayed for that window and the particular buffer in it. Note that
326 this may not be the same as how the property appears when the buffer is
327 displayed in a different window or frame, or how the property appears in
328 the same window if you switch to another buffer in that window; and in
329 those cases, the returned instance would be different.
331 The returned instance will typically be a color-instance, font-instance,
332 or pixmap-instance object, and you can query it using the appropriate
333 object-specific functions. For example, you could use
334 @code{color-instance-rgb-components} to find out the RGB (red, green,
335 and blue) components of how the @code{background} property of the
336 @code{highlight} face is displayed in a particular window. The results
337 might be different from the results you would get for another window
338 (perhaps the user specified a different color for the frame that window
339 is on; or perhaps the same color was specified but the window is on a
340 different X server, and that X server has different RGB values for the
341 color from this one).
343 @var{domain} defaults to the selected window if omitted.
345 @var{domain} can be a frame or device, instead of a window. The value
346 returned for a such a domain is used in special circumstances when a
347 more specific domain does not apply; for example, a frame value might be
348 used for coloring a toolbar, which is conceptually attached to a frame
349 rather than a particular window. The value is also useful in
350 determining what the value would be for a particular window within the
351 frame or device, if it is not overridden by a more specific
354 If @var{property} does not name a built-in property, its value will
355 simply be returned unless it is a specifier object, in which case it
356 will be instanced using @code{specifier-instance}.
358 Optional arguments @var{default} and @var{no-fallback} are the same as
359 in @code{specifier-instance}. @xref{Specifiers}.
363 @node Face Convenience Functions
364 @subsection Face Convenience Functions
366 @deffn Command set-face-foreground face color &optional locale tag-set how-to-add
367 @deffnx Command set-face-background face color &optional locale tag-set how-to-add
368 These functions set the foreground (respectively, background) color of
369 face @var{face} to @var{color}. The argument @var{color} should be a
370 string (the name of a color) or a color object as returned by
371 @code{make-color} (@pxref{Colors}).
374 @deffn Command set-face-background-pixmap face pixmap &optional locale tag-set how-to-add
375 This function sets the background pixmap of face @var{face} to
376 @var{pixmap}. The argument @var{pixmap} should be a string (the name of
377 a bitmap or pixmap file; the directories listed in the variable
378 @code{x-bitmap-file-path} will be searched) or a glyph object as
379 returned by @code{make-glyph} (@pxref{Glyphs}). The argument may also
380 be a list of the form @code{(@var{width} @var{height} @var{data})} where
381 @var{width} and @var{height} are the size in pixels, and @var{data} is a
382 string, containing the raw bits of the bitmap.
384 Similarly to how the glyph's image specifier works @xref{Creating
385 Glyphs}, you don't create your own image specifier, but rather add
386 specifications to the existing one. Note that the image instance that is
387 generated in order to actually display the background pixmap is of type
388 @code{mono-pixmap}, meaning that it's a two-color image and the
389 foreground and background of the image get filled in with the
390 corresponding colors from the face. (#### Is this still true?)
393 @deffn Command set-face-font face font &optional locale tag-set how-to-add
394 This function sets the font of face @var{face}. The argument @var{font}
395 should be a string or a font object as returned by @code{make-font}
399 @deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
400 This function sets the underline property of face @var{face}.
403 @defun face-foreground face &optional locale tag-set exact-p
404 @defunx face-background face &optional locale tag-set exact-p
405 These functions return the foreground (respectively, background) color
406 specifier of face @var{face}.
410 @defun face-background-pixmap face &optional locale tag-set exact-p
411 This function returns the background-pixmap image specifier of face
415 @defun face-font face &optional locale tag-set exact-p
416 This function returns the font specifier of face @var{face}.
418 Note: This is not the same as the function @code{face-font} in FSF Emacs.
423 @defun face-font-name face &optional domain
424 This function returns the name of the font of face @var{face}, or
425 @code{nil} if it is unspecified. This is basically equivalent to
426 @code{(font-name (face-font @var{face}) @var{domain})} except that
427 it does not cause an error if @var{face}'s font is @code{nil}.
429 Note: This function is named @code{face-font} in FSF Emacs.
432 @defun face-underline-p face &optional locale
433 This function returns the underline property of face @var{face}.
436 @defun face-foreground-instance face &optional domain
437 @defunx face-background-instance face &optional domain
438 These functions return the foreground (respectively, background) color
439 specifier of face @var{face}.
443 @defun face-background-pixmap-instance face &optional domain
444 This function return the background-pixmap glyph object of face
448 @defun face-font-instance face &optional domain
449 This function returns the font specifier of face @var{face}.
454 @node Other Face Display Functions
455 @subsection Other Face Display Functions
457 @deffn Command invert-face face &optional locale
458 Swap the foreground and background colors of face @var{face}. If the
459 face doesn't specify both foreground and background, then its foreground
460 and background are set to the default background and foreground.
463 @defun face-equal face1 face2 &optional domain
464 This returns @code{t} if the faces @var{face1} and @var{face2} will
465 display in the same way. @var{domain} is as in
466 @code{face-property-instance}.
469 @defun face-differs-from-default-p face &optional domain
470 This returns @code{t} if the face @var{face} displays differently from
471 the default face. @var{domain} is as in @code{face-property-instance}.
479 This section describes how to work with font specifier and
480 font instance objects, which encapsulate fonts in the window system.
483 * Font Specifiers:: Specifying how a font will appear.
484 * Font Instances:: What a font specifier gets instanced as.
485 * Font Instance Names:: The name of a font instance.
486 * Font Instance Size:: The size of a font instance.
487 * Font Instance Characteristics:: Display characteristics of font instances.
488 * Font Convenience Functions:: Convenience functions that automatically
489 instance and retrieve the properties
494 @node Font Specifiers
495 @subsection Font Specifiers
497 @defun font-specifier-p object
498 This predicate returns @code{t} if @var{object} is a font specifier, and
499 @code{nil} otherwise.
502 @defun make-font-specifier spec-list
504 Return a new @code{font} specifier object with the given specification
505 list. @var{spec-list} can be a list of specifications (each of which is
506 a cons of a locale and a list of instantiators), a single instantiator,
507 or a list of instantiators. @xref{Specifiers}, for more information
510 Valid instantiators for font specifiers are:
515 A string naming a font (e.g. under X this might be
516 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point
517 upright medium-weight Courier font).
519 A font instance (use that instance directly if the device matches,
520 or use the string that generated it).
522 A vector of no elements (only on TTY's; this means to set no font
523 at all, thus using the "natural" font of the terminal's text).
525 A vector of one element (a face to inherit from).
531 @subsection Font Instances
533 @defun font-instance-p object
534 This predicate returns @code{t} if @var{object} is a font instance, and
535 @code{nil} otherwise.
538 @defun make-font-instance name &optional device noerror
539 This function creates a new font-instance object of the specified name.
540 @var{device} specifies the device this object applies to and defaults to
541 the selected device. An error is signalled if the font is unknown or
542 cannot be allocated; however, if @var{noerror} is non-@code{nil},
543 @code{nil} is simply returned in this case.
545 The returned object is a normal, first-class lisp object. The way you
546 ``deallocate'' the font is the way you deallocate any other lisp object:
547 you drop all pointers to it and allow it to be garbage collected. When
548 these objects are GCed, the underlying X data is deallocated as well.
552 @node Font Instance Names
553 @subsection Font Instance Names
554 @cindex font instance name
555 @cindex available fonts
556 @cindex fonts available
558 @defun list-fonts pattern &optional device
559 This function returns a list of font names matching the given pattern.
560 @var{device} specifies which device to search for names, and defaults to
561 the currently selected device.
564 @defun font-instance-name font-instance
565 This function returns the name used to allocate @var{font-instance}.
568 @defun font-instance-truename font-instance
569 This function returns the canonical name of the given font instance.
570 Font names are patterns which may match any number of fonts, of which
571 the first found is used. This returns an unambiguous name for that font
572 (but not necessarily its only unambiguous name).
576 @node Font Instance Size
577 @subsection Font Instance Size
578 @cindex font instance size
580 @defun x-font-size font
581 This function returns the nominal size of the given font. This is done
582 by parsing its name, so it's likely to lose. X fonts can be specified
583 (by the user) in either pixels or 10ths of points, and this returns the
584 first one it finds, so you have to decide which units the returned value
585 is measured in yourself ...
588 @defun x-find-larger-font font &optional device
589 This function loads a new, slightly larger version of the given font (or
590 font name). Returns the font if it succeeds, @code{nil} otherwise. If
591 scalable fonts are available, this returns a font which is 1 point
592 larger. Otherwise, it returns the next larger version of this font that
596 @defun x-find-smaller-font font &optional device
597 This function loads a new, slightly smaller version of the given font
598 (or font name). Returns the font if it succeeds, @code{nil} otherwise.
599 If scalable fonts are available, this returns a font which is 1 point
600 smaller. Otherwise, it returns the next smaller version of this font
605 @node Font Instance Characteristics
606 @subsection Font Instance Characteristics
607 @cindex font instance characteristics
608 @cindex characteristics of font instances
614 @defun font-instance-properties font-instance
615 This function returns the properties (an alist or @code{nil}) of
619 @defun x-make-font-bold font &optional device
620 Given an X font specification, this attempts to make a ``bold'' font.
621 If it fails, it returns @code{nil}.
624 @defun x-make-font-unbold font &optional device
625 Given an X font specification, this attempts to make a non-bold font.
626 If it fails, it returns @code{nil}.
629 @defun x-make-font-italic font &optional device
630 Given an X font specification, this attempts to make an ``italic'' font.
631 If it fails, it returns @code{nil}.
634 @defun x-make-font-unitalic font &optional device
635 Given an X font specification, this attempts to make a non-italic font.
636 If it fails, it returns @code{nil}.
639 @defun x-make-font-bold-italic font &optional device
640 Given an X font specification, this attempts to make a ``bold-italic''
641 font. If it fails, it returns @code{nil}.
645 @node Font Convenience Functions
646 @subsection Font Convenience Functions
648 @defun font-name font &optional domain
649 This function returns the name of the @var{font} in the specified
650 @var{domain}, if any. @var{font} should be a font specifier object and
651 @var{domain} is normally a window and defaults to the selected window if
652 omitted. This is equivalent to using @code{specifier-instance} and
653 applying @code{font-instance-name} to the result.
656 @defun font-truename font &optional domain
657 This function returns the truename of the @var{font} in the specified
658 @var{domain}, if any. @var{font} should be a font specifier object and
659 @var{domain} is normally a window and defaults to the selected window if
660 omitted. This is equivalent to using @code{specifier-instance} and
661 applying @code{font-instance-truename} to the result.
664 @defun font-properties font &optional domain
665 This function returns the properties of the @var{font} in the specified
666 @var{domain}, if any. @var{font} should be a font specifier object and
667 @var{domain} is normally a window and defaults to the selected window if
668 omitted. This is equivalent to using @code{specifier-instance} and
669 applying @code{font-instance-properties} to the result.
678 * Color Specifiers:: Specifying how a color will appear.
679 * Color Instances:: What a color specifier gets instanced as.
680 * Color Instance Properties:: Properties of color instances.
681 * Color Convenience Functions:: Convenience functions that automatically
682 instance and retrieve the properties
683 of a color specifier.
687 @node Color Specifiers
688 @subsection Color Specifiers
690 @defun color-specifier-p object
691 This function returns non-@code{nil} if @var{object} is a color specifier.
694 @defun make-color-specifier spec-list
696 Return a new @code{color} specifier object with the given specification
697 list. @var{spec-list} can be a list of specifications (each of which is
698 a cons of a locale and a list of instantiators), a single instantiator,
699 or a list of instantiators. @xref{Specifiers}, for a detailed
700 description of how specifiers work.
702 Valid instantiators for color specifiers are:
706 A string naming a color (e.g. under X this might be "lightseagreen2" or
710 A color instance (use that instance directly if the device matches,
711 or use the string that generated it).
714 A vector of no elements (only on TTY's; this means to set no color at
715 all, thus using the "natural" color of the terminal's text).
718 A vector of one or two elements: a face to inherit from, and optionally
719 a symbol naming which property of that face to inherit, either
720 @code{foreground} or @code{background} (if omitted, defaults to the same
721 property that this color specifier is used for; if this specifier is not
722 part of a face, the instantiator would not be valid).
726 @defun make-face-boolean-specifier spec-list
728 Return a new @code{face-boolean} specifier object with the given spec
729 list. @var{spec-list} can be a list of specifications (each of which is
730 a cons of a locale and a list of instantiators), a single instantiator,
731 or a list of instantiators. @xref{Specifiers}, for a detailed
732 description of how specifiers work.
734 Valid instantiators for face-boolean specifiers are
740 A vector of two or three elements: a face to inherit from, optionally a
741 symbol naming the property of that face to inherit from (if omitted,
742 defaults to the same property that this face-boolean specifier is used
743 for; if this specifier is not part of a face, the instantiator would not
744 be valid), and optionally a value which, if non-@code{nil}, means to invert the
745 sense of the inherited property.
751 @node Color Instances
752 @subsection Color Instances
753 @cindex color instances
755 A @dfn{color-instance object} is an object describing the way a color
756 specifier is instanced in a particular domain. Functions such as
757 @code{face-background-instance} return a color-instance object. For
761 (face-background-instance 'default (next-window))
762 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
765 The color-instance object returned describes the way the background
766 color of the @code{default} face is displayed in the next window after
769 @defun color-instance-p object
770 This function returns non-@code{nil} if @var{object} is a color-instance.
774 @node Color Instance Properties
775 @subsection Color Instance Properties
777 @defun color-instance-name color-instance
778 This function returns the name used to allocate @var{color-instance}.
781 @defun color-instance-rgb-components color-instance
782 This function returns a three element list containing the red, green,
783 and blue color components of @var{color-instance}.
786 (color-instance-rgb-components
787 (face-background-instance 'default (next-window)))
788 @result{} (65535 58596 46517)
792 @node Color Convenience Functions
793 @subsection Color Convenience Functions
795 @defun color-name color &optional domain
796 This function returns the name of the @var{color} in the specified
797 @var{domain}, if any. @var{color} should be a color specifier object
798 and @var{domain} is normally a window and defaults to the selected
799 window if omitted. This is equivalent to using
800 @code{specifier-instance} and applying @code{color-instance-name} to the
804 @defun color-rgb-components color &optional domain
805 This function returns the @sc{rgb} components of the @var{color} in the
806 specified @var{domain}, if any. @var{color} should be a color specifier
807 object and @var{domain} is normally a window and defaults to the
808 selected window if omitted. This is equivalent to using
809 @code{specifier-instance} and applying
810 @code{color-instance-rgb-components} to the result.
813 (color-rgb-components (face-background 'default (next-window)))
814 @result{} (65535 58596 46517)