2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995 Ben Wing.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/faces.info
6 @node Faces and Window-System Objects, Glyphs, Specifiers, top
7 @chapter Faces and Window-System Objects
9 @cindex window-system objects
12 * Faces:: Controlling the way text looks.
13 * Fonts:: Controlling the typeface of text.
14 * Colors:: Controlling the color of text and pixmaps.
20 A @dfn{face} is a named collection of graphical properties: font,
21 foreground color, background color, background pixmap, optional
22 underlining, and (on TTY devices) whether the text is to be highlighted,
23 dimmed, blinking, or displayed in reverse video. Faces control the
24 display of text on the screen. Every face has a name, which is a symbol
25 such as @code{default} or @code{modeline}.
27 Each built-in property of a face is controlled using a specifier,
28 which allows it to have separate values in particular buffers, frames,
29 windows, and devices and to further vary according to device type
30 (X or TTY) and device class (color, mono, or grayscale).
31 @xref{Specifiers}, for more information.
33 The face named @code{default} is used for ordinary text. The face named
34 @code{modeline} is used for displaying the modeline. The face named
35 @code{highlight} is used for highlighted extents (@pxref{Extents}). The
36 faces named @code{left-margin} and @code{right-margin} are used for the
37 left and right margin areas, respectively (@pxref{Annotations}). The
38 face named @code{zmacs-region} is used for the highlighted region
39 between point and mark.
43 * Merging Faces:: How XEmacs decides which face to use
45 * Basic Face Functions:: How to define and examine faces.
46 * Face Properties:: How to access and modify a face's properties.
47 * Face Convenience Functions:: Convenience functions for accessing
48 particular properties of a face.
49 * Other Face Display Functions:: Other functions pertaining to how a
54 @subsection Merging Faces for Display
56 Here are all the ways to specify which face to use for display of text:
60 With defaults. Each frame has a @dfn{default face}, which is used for
61 all text that doesn't somehow specify another face. The face named
62 @code{default} applies to the text area, while the faces
63 @code{left-margin} and @code{right-margin} apply to the left and right
67 With text properties. A character may have a @code{face} property; if so,
68 it's displayed with that face. (Text properties are actually implemented
69 in terms of extents.) @xref{Text Properties}.
72 With extents. An extent may have a @code{face} property, which applies
73 to all the text covered by the extent; in addition, if the
74 @code{highlight} property is set, the @code{highlight} property applies
75 when the mouse moves over the extent or if the extent is explicitly
76 highlighted. @xref{Extents}.
79 With annotations. Annotations that are inserted into a buffer can specify
80 their own face. (Annotations are actually implemented in terms of extents.)
84 If these various sources together specify more than one face for a
85 particular character, XEmacs merges the properties of the various faces
86 specified. Extents, text properties, and annotations all use the same
87 underlying representation (as extents). When multiple extents cover one
88 character, an extent with higher priority overrides those with lower
89 priority. @xref{Extents}. If no extent covers a particular character,
90 the @code{default} face is used.
92 @cindex background pixmap
93 If a background pixmap is specified, it determines what will be
94 displayed in the background of text characters. If the background
95 pixmap is actually a pixmap, with its colors specified, those colors are
96 used; if it is a bitmap, the face's foreground and background colors are
99 @node Basic Face Functions
100 @subsection Basic Functions for Working with Faces
102 The properties a face can specify include the font, the foreground
103 color, the background color, the background pixmap, the underlining,
104 the display table, and (for TTY devices) whether the text is to be
105 highlighted, dimmed, blinking, or displayed in reverse video.
106 The face can also leave these unspecified, causing them to assume the
107 value of the corresponding property of the @code{default} face.
109 Here are the basic primitives for working with faces.
111 @defun make-face name &optional doc-string temporary
112 This function defines and returns a new face named @var{name}, initially
113 with all properties unspecified. It does nothing if there is already a
114 face named @var{name}. Optional argument @var{doc-string} specifies
115 an explanatory string used for descriptive purposes. If optional
116 argument @var{temporary} is non-@code{nil}, the face will automatically
117 disappear when there are no more references to it anywhere in text or
118 Lisp code (otherwise, the face will continue to exist indefinitely
119 even if it is not used).
122 @defun face-list &optional temporary
123 This function returns a list of the names of all defined faces. If
124 @var{temporary} is @code{nil}, only the permanent faces are included.
125 If it is @code{t}, only the temporary faces are included. If it is any
126 other non-@code{nil} value both permanent and temporary are included.
130 This function returns @code{t} if @var{object} is a face, else @code{nil}.
133 @defun copy-face old-face new-name &optional locale tag-set exact-p how-to-add
134 This function defines a new face named @var{new-name} which is a copy of
135 the existing face named @var{old-face}. If there is already a face
136 named @var{new-name}, then it alters the face to have the same
137 properties as @var{old-face}.
139 @var{locale}, @var{tag-set}, @var{exact-p} and @var{how-to-add} let you
140 copy just parts of the old face rather than the whole face, and are as
141 in @code{copy-specifier} (@pxref{Specifiers}).
144 @node Face Properties
145 @subsection Face Properties
147 You can examine and modify the properties of an existing face with the
150 The following symbols have predefined meanings:
154 The foreground color of the face.
157 The background color of the face.
160 The font used to display text covered by this face.
163 The display table of the face.
165 @item background-pixmap
166 The pixmap displayed in the background of the face. Only used by faces
167 on GUI devices, currently X11, GTK, and Microsoft Windows.
170 Underline all text covered by this face.
173 Highlight all text covered by this face. Only used by faces on TTY
177 Dim all text covered by this face. Only used by faces on TTY devices.
180 Blink all text covered by this face. Only used by faces on TTY devices.
183 Reverse the foreground and background colors. Only used by faces on TTY
187 Description of what the face's normal use is. NOTE: This is not a
188 specifier, unlike all the other built-in properties, and cannot contain
189 locale-specific values.
192 @defun set-face-property face property value &optional locale tag-set how-to-add
193 This function changes a property of a @var{face}.
195 For built-in properties, the actual value of the property is a specifier
196 and you cannot change this; but you can change the specifications within
197 the specifier, and that is what this function will do. For user-defined
198 properties, you can use this function to either change the actual value
199 of the property or, if this value is a specifier, change the
200 specifications within it.
202 If @var{property} is a built-in property, the specifications to be added
203 to this property can be supplied in many different ways:
206 If @var{value} is a simple instantiator (e.g. a string naming a font or
207 color) or a list of instantiators, then the instantiator(s) will be
208 added as a specification of the property for the given @var{locale}
209 (which defaults to @code{global} if omitted).
211 If @var{value} is a list of specifications (each of which is a cons of a
212 locale and a list of instantiators), then @var{locale} must be
213 @code{nil} (it does not make sense to explicitly specify a locale in
214 this case), and specifications will be added as given.
216 If @var{value} is a specifier (as would be returned by
217 @code{face-property} if no @var{locale} argument is given), then some or
218 all of the specifications in the specifier will be added to the
219 property. In this case, the function is really equivalent to
220 @code{copy-specifier} and @var{locale} has the same semantics (if it is
221 a particular locale, the specification for the locale will be copied; if
222 a locale type, specifications for all locales of that type will be
223 copied; if @code{nil} or @code{all}, then all specifications will be
227 @var{how-to-add} should be either @code{nil} or one of the symbols
228 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
229 @code{remove-tag-set-append}, @code{remove-locale},
230 @code{remove-locale-type}, or @code{remove-all}. See
231 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
232 of what each of these means. Most of the time, you do not need to worry
233 about this argument; the default behavior usually is fine.
235 In general, it is OK to pass an instance object (e.g. as returned by
236 @code{face-property-instance}) as an instantiator in place of an actual
237 instantiator. In such a case, the instantiator used to create that
238 instance object will be used (for example, if you set a font-instance
239 object as the value of the @code{font} property, then the font name used
240 to create that object will be used instead). If some cases, however,
241 doing this conversion does not make sense, and this will be noted in the
242 documentation for particular types of instance objects.
244 If @var{property} is not a built-in property, then this function will
245 simply set its value if @var{locale} is @code{nil}. However, if
246 @var{locale} is given, then this function will attempt to add
247 @var{value} as the instantiator for the given @var{locale}, using
248 @code{add-spec-to-specifier}. If the value of the property is not a
249 specifier, it will automatically be converted into a @code{generic}
253 @defun remove-face-property face property &optional locale tag-set exact-p
254 This function removes a property of a @var{face}.
256 For built-in properties, this is analogous to @code{remove-specifier}.
257 For more information, @xref{Other Specification Functions}.
259 When @var{property} is not a built-in property, this function will just
260 remove its value if @var{locale} is @code{nil} or @code{all}. However,
261 if @var{locale} is other than that, this function will attempt to remove
262 @var{value} as the instantiator for the given @var{locale} with
263 @code{remove-specifier}. If the value of the property is not a
264 specifier, it will be converted into a @code{generic} specifier
268 @defun face-property face property &optional locale tag-set exact-p
269 This function returns @var{face}'s value of the given @var{property}.
271 If @var{locale} is omitted, the @var{face}'s actual value for
272 @var{property} will be returned. For built-in properties, this will be
273 a specifier object of a type appropriate to the property (e.g. a font or
274 color specifier). For other properties, this could be anything.
276 If @var{locale} is supplied, then instead of returning the actual value,
277 the specification(s) for the given locale or locale type will be
278 returned. This will only work if the actual value of @var{property} is
279 a specifier (this will always be the case for built-in properties, but
280 not or not may apply to user-defined properties). If the actual value
281 of @var{property} is not a specifier, this value will simply be returned
282 regardless of @var{locale}.
284 The return value will be a list of instantiators (e.g. strings
285 specifying a font or color name), or a list of specifications, each of
286 which is a cons of a locale and a list of instantiators. Specifically,
287 if @var{locale} is a particular locale (a buffer, window, frame, device,
288 or @code{global}), a list of instantiators for that locale will be
289 returned. Otherwise, if @var{locale} is a locale type (one of the
290 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
291 the specifications for all locales of that type will be returned.
292 Finally, if @var{locale} is @code{all}, the specifications for all
293 locales of all types will be returned.
295 The specifications in a specifier determine what the value of
296 @var{property} will be in a particular @dfn{domain} or set of
297 circumstances, which is typically a particular Emacs window along with
298 the buffer it contains and the frame and device it lies within. The
299 value is derived from the instantiator associated with the most specific
300 locale (in the order buffer, window, frame, device, and @code{global})
301 that matches the domain in question. In other words, given a domain
302 (i.e. an Emacs window, usually), the specifier for @var{property} will
303 first be searched for a specification whose locale is the buffer
304 contained within that window; then for a specification whose locale is
305 the window itself; then for a specification whose locale is the frame
306 that the window is contained within; etc. The first instantiator that
307 is valid for the domain (usually this means that the instantiator is
308 recognized by the device [i.e. the X server or TTY device] that the
309 domain is on). The function @code{face-property-instance} actually does
310 all this, and is used to determine how to display the face.
313 @defun face-property-instance face property &optional domain default no-fallback
314 This function returns the instance of @var{face}'s @var{property} in the
315 specified @var{domain}.
317 Under most circumstances, @var{domain} will be a particular window, and
318 the returned instance describes how the specified property actually is
319 displayed for that window and the particular buffer in it. Note that
320 this may not be the same as how the property appears when the buffer is
321 displayed in a different window or frame, or how the property appears in
322 the same window if you switch to another buffer in that window; and in
323 those cases, the returned instance would be different.
325 The returned instance will typically be a color-instance, font-instance,
326 or pixmap-instance object, and you can query it using the appropriate
327 object-specific functions. For example, you could use
328 @code{color-instance-rgb-components} to find out the RGB (red, green,
329 and blue) components of how the @code{background} property of the
330 @code{highlight} face is displayed in a particular window. The results
331 might be different from the results you would get for another window
332 (perhaps the user specified a different color for the frame that window
333 is on; or perhaps the same color was specified but the window is on a
334 different X server, and that X server has different RGB values for the
335 color from this one).
337 @var{domain} defaults to the selected window if omitted.
339 @var{domain} can be a frame or device, instead of a window. The value
340 returned for a such a domain is used in special circumstances when a
341 more specific domain does not apply; for example, a frame value might be
342 used for coloring a toolbar, which is conceptually attached to a frame
343 rather than a particular window. The value is also useful in
344 determining what the value would be for a particular window within the
345 frame or device, if it is not overridden by a more specific
348 If @var{property} does not name a built-in property, its value will
349 simply be returned unless it is a specifier object, in which case it
350 will be instanced using @code{specifier-instance}.
352 Optional arguments @var{default} and @var{no-fallback} are the same as
353 in @code{specifier-instance}. @xref{Specifiers}.
356 @node Face Convenience Functions
357 @subsection Face Convenience Functions
359 @deffn Command set-face-foreground face color &optional locale tag-set how-to-add
360 @deffnx Command set-face-background face color &optional locale tag-set how-to-add
361 These functions set the foreground (respectively, background) color of
362 face @var{face} to @var{color}. The argument @var{color} should be a
363 string (the name of a color) or a color object as returned by
364 @code{make-color} (@pxref{Colors}).
367 @deffn Command set-face-background-pixmap face pixmap &optional locale tag-set how-to-add
368 This function sets the background pixmap of face @var{face} to
369 @var{pixmap}. The argument @var{pixmap} should be a string (the name of
370 a bitmap or pixmap file; the directories listed in the variable
371 @code{x-bitmap-file-path} will be searched) or a glyph object as
372 returned by @code{make-glyph} (@pxref{Glyphs}). The argument may also
373 be a list of the form @code{(@var{width} @var{height} @var{data})} where
374 @var{width} and @var{height} are the size in pixels, and @var{data} is a
375 string, containing the raw bits of the bitmap.
377 Similarly to how the glyph's image specifier works @xref{Creating
378 Glyphs}, you don't create your own image specifier, but rather add
379 specifications to the existing one. Note that the image instance that is
380 generated in order to actually display the background pixmap is of type
381 @code{mono-pixmap}, meaning that it's a two-color image and the
382 foreground and background of the image get filled in with the
383 corresponding colors from the face. (#### Is this still true?)
386 @deffn Command set-face-font face font &optional locale tag-set how-to-add
387 This function sets the font of face @var{face}. The argument @var{font}
388 should be a string or a font object as returned by @code{make-font}
392 @deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
393 This function sets the underline property of face @var{face}.
396 @defun face-foreground face &optional locale tag-set exact-p
397 @defunx face-background face &optional locale tag-set exact-p
398 These functions return the foreground (respectively, background) color
399 specifier of face @var{face}.
403 @defun face-background-pixmap face &optional locale tag-set exact-p
404 This function returns the background-pixmap image specifier of face
408 @defun face-font face &optional locale tag-set exact-p
409 This function returns the font specifier of face @var{face}. (Note:
410 This is not the same as the function @code{face-font} in FSF Emacs.)
415 @defun face-font-name face &optional domain
416 This function returns the name of the font of face @var{face}, or
417 @code{nil} if it is unspecified. This is basically equivalent to
418 @code{(font-name (face-font @var{face}) @var{domain})} except that
419 it does not cause an error if @var{face}'s font is @code{nil}. (This
420 function is named @code{face-font} in FSF Emacs.)
423 @defun face-underline-p face &optional locale
424 This function returns the underline property of face @var{face}.
427 @defun face-foreground-instance face &optional domain
428 @defunx face-background-instance face &optional domain
429 These functions return the foreground (respectively, background) color
430 specifier of face @var{face}.
434 @defun face-background-pixmap-instance face &optional domain
435 This function return the background-pixmap glyph object of face
439 @defun face-font-instance face &optional domain
440 This function returns the font specifier of face @var{face}.
444 @node Other Face Display Functions
445 @subsection Other Face Display Functions
447 @deffn Command invert-face face &optional locale
448 Swap the foreground and background colors of face @var{face}. If the
449 face doesn't specify both foreground and background, then its foreground
450 and background are set to the default background and foreground.
453 @defun face-equal face1 face2 &optional domain
454 This returns @code{t} if the faces @var{face1} and @var{face2} will
455 display in the same way. @var{domain} is as in
456 @code{face-property-instance}.
459 @defun face-differs-from-default-p face &optional domain
460 This returns @code{t} if the face @var{face} displays differently from
461 the default face. @var{domain} is as in @code{face-property-instance}.
468 This section describes how to work with font specifier and
469 font instance objects, which encapsulate fonts in the window system.
472 * Font Specifiers:: Specifying how a font will appear.
473 * Font Instances:: What a font specifier gets instanced as.
474 * Font Instance Names:: The name of a font instance.
475 * Font Instance Size:: The size of a font instance.
476 * Font Instance Characteristics:: Display characteristics of font instances.
477 * Font Convenience Functions:: Convenience functions that automatically
478 instance and retrieve the properties
482 @node Font Specifiers
483 @subsection Font Specifiers
485 @defun font-specifier-p object
486 This predicate returns @code{t} if @var{object} is a font specifier, and
487 @code{nil} otherwise.
490 @defun make-font-specifier spec-list
492 Return a new @code{font} specifier object with the given specification
493 list. @var{spec-list} can be a list of specifications (each of which is
494 a cons of a locale and a list of instantiators), a single instantiator,
495 or a list of instantiators. @xref{Specifiers}, for more information
498 Valid instantiators for font specifiers are:
503 A string naming a font (e.g. under X this might be
504 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point
505 upright medium-weight Courier font).
507 A font instance (use that instance directly if the device matches,
508 or use the string that generated it).
510 A vector of no elements (only on TTY's; this means to set no font
511 at all, thus using the "natural" font of the terminal's text).
513 A vector of one element (a face to inherit from).
518 @subsection Font Instances
520 @defun font-instance-p object
521 This predicate returns @code{t} if @var{object} is a font instance, and
522 @code{nil} otherwise.
525 @defun make-font-instance name &optional device noerror
526 This function creates a new font-instance object of the specified name.
527 @var{device} specifies the device this object applies to and defaults to
528 the selected device. An error is signalled if the font is unknown or
529 cannot be allocated; however, if @var{noerror} is non-@code{nil},
530 @code{nil} is simply returned in this case.
532 The returned object is a normal, first-class lisp object. The way you
533 ``deallocate'' the font is the way you deallocate any other lisp object:
534 you drop all pointers to it and allow it to be garbage collected. When
535 these objects are GCed, the underlying X data is deallocated as well.
538 @node Font Instance Names
539 @subsection Font Instance Names
540 @cindex font instance name
541 @cindex available fonts
542 @cindex fonts available
544 @defun list-fonts pattern &optional device
545 This function returns a list of font names matching the given pattern.
546 @var{device} specifies which device to search for names, and defaults to
547 the currently selected device.
550 @defun font-instance-name font-instance
551 This function returns the name used to allocate @var{font-instance}.
554 @defun font-instance-truename font-instance
555 This function returns the canonical name of the given font instance.
556 Font names are patterns which may match any number of fonts, of which
557 the first found is used. This returns an unambiguous name for that font
558 (but not necessarily its only unambiguous name).
561 @node Font Instance Size
562 @subsection Font Instance Size
563 @cindex font instance size
565 @defun x-font-size font
566 This function returns the nominal size of the given font. This is done
567 by parsing its name, so it's likely to lose. X fonts can be specified
568 (by the user) in either pixels or 10ths of points, and this returns the
569 first one it finds, so you have to decide which units the returned value
570 is measured in yourself ...
573 @defun x-find-larger-font font &optional device
574 This function loads a new, slightly larger version of the given font (or
575 font name). Returns the font if it succeeds, @code{nil} otherwise. If
576 scalable fonts are available, this returns a font which is 1 point
577 larger. Otherwise, it returns the next larger version of this font that
581 @defun x-find-smaller-font font &optional device
582 This function loads a new, slightly smaller version of the given font
583 (or font name). Returns the font if it succeeds, @code{nil} otherwise.
584 If scalable fonts are available, this returns a font which is 1 point
585 smaller. Otherwise, it returns the next smaller version of this font
589 @node Font Instance Characteristics
590 @subsection Font Instance Characteristics
591 @cindex font instance characteristics
592 @cindex characteristics of font instances
598 @defun font-instance-properties font-instance
599 This function returns the properties (an alist or @code{nil}) of
603 @defun x-make-font-bold font &optional device
604 Given an X font specification, this attempts to make a ``bold'' font.
605 If it fails, it returns @code{nil}.
608 @defun x-make-font-unbold font &optional device
609 Given an X font specification, this attempts to make a non-bold font.
610 If it fails, it returns @code{nil}.
613 @defun x-make-font-italic font &optional device
614 Given an X font specification, this attempts to make an ``italic'' font.
615 If it fails, it returns @code{nil}.
618 @defun x-make-font-unitalic font &optional device
619 Given an X font specification, this attempts to make a non-italic font.
620 If it fails, it returns @code{nil}.
623 @defun x-make-font-bold-italic font &optional device
624 Given an X font specification, this attempts to make a ``bold-italic''
625 font. If it fails, it returns @code{nil}.
628 @node Font Convenience Functions
629 @subsection Font Convenience Functions
631 @defun font-name font &optional domain
632 This function returns the name of the @var{font} in the specified
633 @var{domain}, if any. @var{font} should be a font specifier object and
634 @var{domain} is normally a window and defaults to the selected window if
635 omitted. This is equivalent to using @code{specifier-instance} and
636 applying @code{font-instance-name} to the result.
639 @defun font-truename font &optional domain
640 This function returns the truename of the @var{font} in the specified
641 @var{domain}, if any. @var{font} should be a font specifier object and
642 @var{domain} is normally a window and defaults to the selected window if
643 omitted. This is equivalent to using @code{specifier-instance} and
644 applying @code{font-instance-truename} to the result.
647 @defun font-properties font &optional domain
648 This function returns the properties of the @var{font} in the specified
649 @var{domain}, if any. @var{font} should be a font specifier object and
650 @var{domain} is normally a window and defaults to the selected window if
651 omitted. This is equivalent to using @code{specifier-instance} and
652 applying @code{font-instance-properties} to the result.
660 * Color Specifiers:: Specifying how a color will appear.
661 * Color Instances:: What a color specifier gets instanced as.
662 * Color Instance Properties:: Properties of color instances.
663 * Color Convenience Functions:: Convenience functions that automatically
664 instance and retrieve the properties
665 of a color specifier.
668 @node Color Specifiers
669 @subsection Color Specifiers
671 @defun color-specifier-p object
672 This function returns non-@code{nil} if @var{object} is a color specifier.
675 @defun make-color-specifier spec-list
677 Return a new @code{color} specifier object with the given specification
678 list. @var{spec-list} can be a list of specifications (each of which is
679 a cons of a locale and a list of instantiators), a single instantiator,
680 or a list of instantiators. @xref{Specifiers}, for a detailed
681 description of how specifiers work.
683 Valid instantiators for color specifiers are:
687 A string naming a color (e.g. under X this might be "lightseagreen2" or
691 A color instance (use that instance directly if the device matches,
692 or use the string that generated it).
695 A vector of no elements (only on TTY's; this means to set no color at
696 all, thus using the "natural" color of the terminal's text).
699 A vector of one or two elements: a face to inherit from, and optionally
700 a symbol naming which property of that face to inherit, either
701 @code{foreground} or @code{background} (if omitted, defaults to the same
702 property that this color specifier is used for; if this specifier is not
703 part of a face, the instantiator would not be valid).
707 @defun make-face-boolean-specifier spec-list
709 Return a new @code{face-boolean} specifier object with the given spec
710 list. @var{spec-list} can be a list of specifications (each of which is
711 a cons of a locale and a list of instantiators), a single instantiator,
712 or a list of instantiators. @xref{Specifiers}, for a detailed
713 description of how specifiers work.
715 Valid instantiators for face-boolean specifiers are
721 A vector of two or three elements: a face to inherit from, optionally a
722 symbol naming the property of that face to inherit from (if omitted,
723 defaults to the same property that this face-boolean specifier is used
724 for; if this specifier is not part of a face, the instantiator would not
725 be valid), and optionally a value which, if non-@code{nil}, means to invert the
726 sense of the inherited property.
732 @node Color Instances
733 @subsection Color Instances
734 @cindex color instances
736 A @dfn{color-instance object} is an object describing the way a color
737 specifier is instanced in a particular domain. Functions such as
738 @code{face-background-instance} return a color-instance object. For
742 (face-background-instance 'default (next-window))
743 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
746 The color-instance object returned describes the way the background
747 color of the @code{default} face is displayed in the next window after
750 @defun color-instance-p object
751 This function returns non-@code{nil} if @var{object} is a color-instance.
754 @node Color Instance Properties
755 @subsection Color Instance Properties
757 @defun color-instance-name color-instance
758 This function returns the name used to allocate @var{color-instance}.
761 @defun color-instance-rgb-components color-instance
762 This function returns a three element list containing the red, green,
763 and blue color components of @var{color-instance}.
766 (color-instance-rgb-components
767 (face-background-instance 'default (next-window)))
768 @result{} (65535 58596 46517)
772 @node Color Convenience Functions
773 @subsection Color Convenience Functions
775 @defun color-name color &optional domain
776 This function returns the name of the @var{color} in the specified
777 @var{domain}, if any. @var{color} should be a color specifier object
778 and @var{domain} is normally a window and defaults to the selected
779 window if omitted. This is equivalent to using
780 @code{specifier-instance} and applying @code{color-instance-name} to the
784 @defun color-rgb-components color &optional domain
785 This function returns the @sc{rgb} components of the @var{color} in the
786 specified @var{domain}, if any. @var{color} should be a color specifier
787 object and @var{domain} is normally a window and defaults to the
788 selected window if omitted. This is equivalent to using
789 @code{specifier-instance} and applying
790 @code{color-instance-rgb-components} to the result.
793 (color-rgb-components (face-background 'default (next-window)))
794 @result{} (65535 58596 46517)