update.
[chise/xemacs-chise.git] / man / lispref / faces.texi
1 @c -*-texinfo-*-
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
8 @cindex faces
9 @cindex window-system objects
10
11 @menu
12 * Faces::               Controlling the way text looks.
13 * Fonts::               Controlling the typeface of text.
14 * Colors::              Controlling the color of text and pixmaps.
15 @end menu
16
17 @node Faces
18 @section Faces
19
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}.
26
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.
32
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.
40
41
42 @menu
43 * Merging Faces::               How XEmacs decides which face to use
44                                   for a character.
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
50                                   a face appears.
51 @end menu
52
53 @node Merging Faces
54 @subsection Merging Faces for Display
55
56   Here are all the ways to specify which face to use for display of text:
57
58 @itemize @bullet
59 @item
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
64 margin areas.
65
66 @item
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}.
70
71 @item
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}.
77
78 @item
79 With annotations.  Annotations that are inserted into a buffer can specify
80 their own face. (Annotations are actually implemented in terms of extents.)
81 @xref{Annotations}.
82 @end itemize
83
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.
91
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
97 used to color it.
98
99 @node Basic Face Functions
100 @subsection Basic Functions for Working with Faces
101
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.
108
109   Here are the basic primitives for working with faces.
110
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).
120 @end defun
121
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.
127 @end defun
128
129 @defun facep object
130 This function returns @code{t} if @var{object} is a face, else @code{nil}.
131 @end defun
132
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}.
138
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}).
142 @end defun
143
144 @node Face Properties
145 @subsection Face Properties
146
147   You can examine and modify the properties of an existing face with the
148 following functions.
149
150 The following symbols have predefined meanings:
151
152 @table @code
153 @item foreground
154 The foreground color of the face.
155
156 @item background
157 The background color of the face.
158
159 @item font
160 The font used to display text covered by this face.
161
162 @item display-table
163 The display table of the face.
164
165 @item background-pixmap
166 The pixmap displayed in the background of the face.  Only used by faces
167 on X devices.
168
169 @item underline
170 Underline all text covered by this face.
171
172 @item highlight
173 Highlight all text covered by this face.  Only used by faces on TTY
174 devices.
175
176 @item dim
177 Dim all text covered by this face.  Only used by faces on TTY devices.
178
179 @item blinking
180 Blink all text covered by this face.  Only used by faces on TTY devices.
181
182 @item reverse
183 Reverse the foreground and background colors.  Only used by faces on TTY
184 devices.
185
186 @item doc-string
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.
190 @end table
191
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}.
194
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.
201
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:
204
205 @itemize @bullet
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).
210
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.
215
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
224 copied).
225 @end itemize
226
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.
234
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.
243
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}
250 specifier.
251 @end defun
252
253 @defun remove-face-property face property &optional locale tag-set exact-p
254 This function removes a property of a @var{face}.
255
256 For built-in properties, this is analogous to @code{remove-specifier}.
257 For more information, @xref{Other Specification Functions}.
258
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
265 automatically.
266 @end defun
267
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}.
270
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.
275
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}.
283
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.
294
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.
311 @end defun
312
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}.
316
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.
324
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).
336
337 @var{domain} defaults to the selected window if omitted.
338
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
346 specification.
347
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}.
351
352 Optional arguments @var{default} and @var{no-fallback} are the same as
353 in @code{specifier-instance}.  @xref{Specifiers}.
354 @end defun
355
356 @node Face Convenience Functions
357 @subsection Face Convenience Functions
358
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}).
365 @end deffn
366
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.
376 @end deffn
377
378 @deffn Command set-face-font face font &optional locale tag-set how-to-add
379 This function sets the font of face @var{face}.  The argument @var{font}
380 should be a string or a font object as returned by @code{make-font}
381 (@pxref{Fonts}).
382 @end deffn
383
384 @deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
385 This function sets the underline property of face @var{face}.
386 @end deffn
387
388 @defun face-foreground face &optional locale tag-set exact-p
389 @defunx face-background face &optional locale tag-set exact-p
390 These functions return the foreground (respectively, background) color
391 specifier of face @var{face}.
392 @xref{Colors}.
393 @end defun
394
395 @defun face-background-pixmap face &optional locale tag-set exact-p
396 This function return the background-pixmap glyph object of face
397 @var{face}.
398 @end defun
399
400 @defun face-font face &optional locale tag-set exact-p
401 This function returns the font specifier of face @var{face}.  (Note:
402 This is not the same as the function @code{face-font} in FSF Emacs.)
403
404 @xref{Fonts}.
405 @end defun
406
407 @defun face-font-name face &optional domain
408 This function returns the name of the font of face @var{face}, or
409 @code{nil} if it is unspecified.  This is basically equivalent to
410 @code{(font-name (face-font @var{face}) @var{domain})} except that
411 it does not cause an error if @var{face}'s font is @code{nil}. (This
412 function is named @code{face-font} in FSF Emacs.)
413 @end defun
414
415 @defun face-underline-p face &optional locale
416 This function returns the underline property of face @var{face}.
417 @end defun
418
419 @defun face-foreground-instance face &optional domain
420 @defunx face-background-instance face &optional domain
421 These functions return the foreground (respectively, background) color
422 specifier of face @var{face}.
423 @xref{Colors}.
424 @end defun
425
426 @defun face-background-pixmap-instance face &optional domain
427 This function return the background-pixmap glyph object of face
428 @var{face}.
429 @end defun
430
431 @defun face-font-instance face &optional domain
432 This function returns the font specifier of face @var{face}.
433 @xref{Fonts}.
434 @end defun
435
436 @node Other Face Display Functions
437 @subsection Other Face Display Functions
438
439 @deffn Command invert-face face &optional locale
440 Swap the foreground and background colors of face @var{face}.  If the
441 face doesn't specify both foreground and background, then its foreground
442 and background are set to the default background and foreground.
443 @end deffn
444
445 @defun face-equal face1 face2 &optional domain
446 This returns @code{t} if the faces @var{face1} and @var{face2} will
447 display in the same way.  @var{domain} is as in
448 @code{face-property-instance}.
449 @end defun
450
451 @defun face-differs-from-default-p face &optional domain
452 This returns @code{t} if the face @var{face} displays differently from
453 the default face.  @var{domain} is as in @code{face-property-instance}.
454 @end defun
455
456 @node Fonts
457 @section Fonts
458 @cindex fonts
459
460   This section describes how to work with font specifier and
461 font instance objects, which encapsulate fonts in the window system.
462
463 @menu
464 * Font Specifiers::             Specifying how a font will appear.
465 * Font Instances::              What a font specifier gets instanced as.
466 * Font Instance Names::         The name of a font instance.
467 * Font Instance Size::          The size of a font instance.
468 * Font Instance Characteristics:: Display characteristics of font instances.
469 * Font Convenience Functions::  Convenience functions that automatically
470                                   instance and retrieve the properties
471                                   of a font specifier.
472 @end menu
473
474 @node Font Specifiers
475 @subsection Font Specifiers
476
477 @defun font-specifier-p object
478 This predicate returns @code{t} if @var{object} is a font specifier, and
479 @code{nil} otherwise.
480 @end defun
481
482 @defun make-font-specifier spec-list
483
484 Return a new @code{font} specifier object with the given specification
485 list.  @var{spec-list} can be a list of specifications (each of which is
486 a cons of a locale and a list of instantiators), a single instantiator,
487 or a list of instantiators.  @xref{Specifiers}, for more information
488 about specifiers.
489
490 Valid instantiators for font specifiers are:
491
492 @itemize @bullet
493
494 @item
495 A string naming a font (e.g. under X this might be
496 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point
497 upright medium-weight Courier font).
498 @item
499 A font instance (use that instance directly if the device matches,
500 or use the string that generated it).
501 @item
502 A vector of no elements (only on TTY's; this means to set no font
503 at all, thus using the "natural" font of the terminal's text).
504 @item
505 A vector of one element (a face to inherit from).
506 @end itemize
507 @end defun
508
509 @node Font Instances
510 @subsection Font Instances
511
512 @defun font-instance-p object
513 This predicate returns @code{t} if @var{object} is a font instance, and
514 @code{nil} otherwise.
515 @end defun
516
517 @defun make-font-instance name &optional device noerror
518 This function creates a new font-instance object of the specified name.
519 @var{device} specifies the device this object applies to and defaults to
520 the selected device.  An error is signalled if the font is unknown or
521 cannot be allocated; however, if @var{noerror} is non-@code{nil},
522 @code{nil} is simply returned in this case.
523
524 The returned object is a normal, first-class lisp object.  The way you
525 ``deallocate'' the font is the way you deallocate any other lisp object:
526 you drop all pointers to it and allow it to be garbage collected.  When
527 these objects are GCed, the underlying X data is deallocated as well.
528 @end defun
529
530 @node Font Instance Names
531 @subsection Font Instance Names
532 @cindex font instance name
533 @cindex available fonts
534 @cindex fonts available
535
536 @defun list-fonts pattern &optional device
537 This function returns a list of font names matching the given pattern.
538 @var{device} specifies which device to search for names, and defaults to
539 the currently selected device.
540 @end defun
541
542 @defun font-instance-name font-instance
543 This function returns the name used to allocate @var{font-instance}.
544 @end defun
545
546 @defun font-instance-truename font-instance
547 This function returns the canonical name of the given font instance.
548 Font names are patterns which may match any number of fonts, of which
549 the first found is used.  This returns an unambiguous name for that font
550 (but not necessarily its only unambiguous name).
551 @end defun
552
553 @node Font Instance Size
554 @subsection Font Instance Size
555 @cindex font instance size
556
557 @defun x-font-size font
558 This function returns the nominal size of the given font.  This is done
559 by parsing its name, so it's likely to lose.  X fonts can be specified
560 (by the user) in either pixels or 10ths of points, and this returns the
561 first one it finds, so you have to decide which units the returned value
562 is measured in yourself ...
563 @end defun
564
565 @defun x-find-larger-font font &optional device
566 This function loads a new, slightly larger version of the given font (or
567 font name).  Returns the font if it succeeds, @code{nil} otherwise.  If
568 scalable fonts are available, this returns a font which is 1 point
569 larger.  Otherwise, it returns the next larger version of this font that
570 is defined.
571 @end defun
572
573 @defun x-find-smaller-font font &optional device
574 This function loads a new, slightly smaller version of the given font
575 (or font name).  Returns the font if it succeeds, @code{nil} otherwise.
576 If scalable fonts are available, this returns a font which is 1 point
577 smaller.  Otherwise, it returns the next smaller version of this font
578 that is defined.
579 @end defun
580
581 @node Font Instance Characteristics
582 @subsection Font Instance Characteristics
583 @cindex font instance characteristics
584 @cindex characteristics of font instances
585 @cindex bold
586 @cindex demibold
587 @cindex italic
588 @cindex oblique
589
590 @defun font-instance-properties font-instance
591 This function returns the properties (an alist or @code{nil}) of
592 @var{font-instance}.
593 @end defun
594
595 @defun x-make-font-bold font &optional device
596 Given an X font specification, this attempts to make a ``bold'' font.
597 If it fails, it returns @code{nil}.
598 @end defun
599
600 @defun x-make-font-unbold font &optional device
601 Given an X font specification, this attempts to make a non-bold font.
602 If it fails, it returns @code{nil}.
603 @end defun
604
605 @defun x-make-font-italic font &optional device
606 Given an X font specification, this attempts to make an ``italic'' font.
607 If it fails, it returns @code{nil}.
608 @end defun
609
610 @defun x-make-font-unitalic font &optional device
611 Given an X font specification, this attempts to make a non-italic font.
612 If it fails, it returns @code{nil}.
613 @end defun
614
615 @defun x-make-font-bold-italic font &optional device
616 Given an X font specification, this attempts to make a ``bold-italic''
617 font.  If it fails, it returns @code{nil}.
618 @end defun
619
620 @node Font Convenience Functions
621 @subsection Font Convenience Functions
622
623 @defun font-name font &optional domain
624 This function returns the name of the @var{font} in the specified
625 @var{domain}, if any.  @var{font} should be a font specifier object and
626 @var{domain} is normally a window and defaults to the selected window if
627 omitted.  This is equivalent to using @code{specifier-instance} and
628 applying @code{font-instance-name} to the result.
629 @end defun
630
631 @defun font-truename font &optional domain
632 This function returns the truename 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-truename} to the result.
637 @end defun
638
639 @defun font-properties font &optional domain
640 This function returns the properties 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-properties} to the result.
645 @end defun
646
647 @node Colors
648 @section Colors
649 @cindex colors
650
651 @menu
652 * Color Specifiers::            Specifying how a color will appear.
653 * Color Instances::             What a color specifier gets instanced as.
654 * Color Instance Properties::   Properties of color instances.
655 * Color Convenience Functions:: Convenience functions that automatically
656                                   instance and retrieve the properties
657                                   of a color specifier.
658 @end menu
659
660 @node Color Specifiers
661 @subsection Color Specifiers
662
663 @defun color-specifier-p object
664 This function returns non-@code{nil} if @var{object} is a color specifier.
665 @end defun
666
667 @defun make-color-specifier spec-list
668
669 Return a new @code{color} specifier object with the given specification
670 list.  @var{spec-list} can be a list of specifications (each of which is
671 a cons of a locale and a list of instantiators), a single instantiator,
672 or a list of instantiators.  @xref{Specifiers}, for a detailed
673 description of how specifiers work.
674
675 Valid instantiators for color specifiers are:
676
677 @itemize @bullet
678 @item
679 A string naming a color (e.g. under X this might be "lightseagreen2" or
680 "#F534B2").
681
682 @item
683 A color instance (use that instance directly if the device matches,
684 or use the string that generated it).
685
686 @item
687 A vector of no elements (only on TTY's; this means to set no color at
688 all, thus using the "natural" color of the terminal's text).
689
690 @item
691 A vector of one or two elements: a face to inherit from, and optionally
692 a symbol naming which property of that face to inherit, either
693 @code{foreground} or @code{background} (if omitted, defaults to the same
694 property that this color specifier is used for; if this specifier is not
695 part of a face, the instantiator would not be valid).
696 @end itemize
697 @end defun
698
699 @defun make-face-boolean-specifier spec-list
700
701 Return a new @code{face-boolean} specifier object with the given spec
702 list.  @var{spec-list} can be a list of specifications (each of which is
703 a cons of a locale and a list of instantiators), a single instantiator,
704 or a list of instantiators.  @xref{Specifiers}, for a detailed
705 description of how specifiers work.
706
707 Valid instantiators for face-boolean specifiers are
708
709 @itemize @bullet
710 @item
711 t or nil.
712 @item
713 A vector of two or three elements: a face to inherit from, optionally a
714 symbol naming the property of that face to inherit from (if omitted,
715 defaults to the same property that this face-boolean specifier is used
716 for; if this specifier is not part of a face, the instantiator would not
717 be valid), and optionally a value which, if non-@code{nil}, means to invert the
718 sense of the inherited property.
719 @end itemize
720
721 @end defun
722
723
724 @node Color Instances
725 @subsection Color Instances
726 @cindex color instances
727
728 A @dfn{color-instance object} is an object describing the way a color
729 specifier is instanced in a particular domain.  Functions such as
730 @code{face-background-instance} return a color-instance object.  For
731 example,
732
733 @example
734 (face-background-instance 'default (next-window))
735     @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
736 @end example
737
738 The color-instance object returned describes the way the background
739 color of the @code{default} face is displayed in the next window after
740 the selected one.
741
742 @defun color-instance-p object
743 This function returns non-@code{nil} if @var{object} is a color-instance.
744 @end defun
745
746 @node Color Instance Properties
747 @subsection Color Instance Properties
748
749 @defun color-instance-name color-instance
750 This function returns the name used to allocate @var{color-instance}.
751 @end defun
752
753 @defun color-instance-rgb-components color-instance
754 This function returns a three element list containing the red, green,
755 and blue color components of @var{color-instance}.
756
757 @example
758 (color-instance-rgb-components
759   (face-background-instance 'default (next-window)))
760     @result{} (65535 58596 46517)
761 @end example
762 @end defun
763
764 @node Color Convenience Functions
765 @subsection Color Convenience Functions
766
767 @defun color-name color &optional domain
768 This function returns the name of the @var{color} in the specified
769 @var{domain}, if any.  @var{color} should be a color specifier object
770 and @var{domain} is normally a window and defaults to the selected
771 window if omitted.  This is equivalent to using
772 @code{specifier-instance} and applying @code{color-instance-name} to the
773 result.
774 @end defun
775
776 @defun color-rgb-components color &optional domain
777 This function returns the @sc{rgb} components of the @var{color} in the
778 specified @var{domain}, if any.  @var{color} should be a color specifier
779 object and @var{domain} is normally a window and defaults to the
780 selected window if omitted.  This is equivalent to using
781 @code{specifier-instance} and applying
782 @code{color-instance-rgb-components} to the result.
783
784 @example
785 (color-rgb-components (face-background 'default (next-window)))
786     @result{} (65535 58596 46517)
787 @end example
788 @end defun