annotate man/lispref/faces.texi @ 4407:4ee73bbe4f8e

Always use boyer_moore in ASCII or Latin-1 buffers with ASCII search strings. 2007-12-26 Aidan Kehoe <kehoea@parhasard.net> * casetab.c: Extend and correct some case table documentation. * search.c (search_buffer): Correct a bug where only the first entry for a character in the case equivalence table was examined in determining if the Boyer-Moore search algorithm is appropriate. If there are case mappings outside of the charset and row of the characters specified in the search string, those case mappings can be safely ignored (and Boyer-Moore search can be used) if we know from the buffer statistics that the corresponding characters cannot occur. * search.c (boyer_moore): Assert that we haven't been passed a string with varying characters sets or rows within character sets. That's what simple_search is for. In the very rare event that a character in the search string has a canonical case mapping that is not in the same character set and row, don't try to search for the canonical character, search for some other character that is in the the desired character set and row. Assert that the case table isn't corrupt. Do not search for any character case mappings that cannot possibly occur in the buffer, given the buffer metadata about its contents.
author Aidan Kehoe <kehoea@parhasard.net>
date Wed, 26 Dec 2007 17:30:16 +0100
parents f200f93c0b69
children b6e59ea11533
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
1 @c -*-texinfo-*-
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
2 @c This is part of the XEmacs Lisp Reference Manual.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
3 @c Copyright (C) 1995 Ben Wing.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
4 @c See the file lispref.texi for copying conditions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
5 @setfilename ../../info/faces.info
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
6 @node Faces and Window-System Objects, Glyphs, Specifiers, top
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
7 @chapter Faces and Window-System Objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
8 @cindex faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
9 @cindex window-system objects
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
10
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
11 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
12 * Faces:: Controlling the way text looks.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
13 * Fonts:: Controlling the typeface of text.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
14 * Colors:: Controlling the color of text and pixmaps.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
15 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
16
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
17 @node Faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
18 @section Faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
19
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
20 A @dfn{face} is a named collection of graphical properties: font,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
21 foreground color, background color, background pixmap, optional
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
22 underlining, and (on TTY devices) whether the text is to be highlighted,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
23 dimmed, blinking, or displayed in reverse video. Faces control the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
24 display of text on the screen. Every face has a name, which is a symbol
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
25 such as @code{default} or @code{modeline}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
26
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
27 Each built-in property of a face is controlled using a specifier,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
28 which allows it to have separate values in particular buffers, frames,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
29 windows, and devices and to further vary according to device type
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
30 (X or TTY) and device class (color, mono, or grayscale).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
31 @xref{Specifiers}, for more information.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
32
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
33 The face named @code{default} is used for ordinary text. The face named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
34 @code{modeline} is used for displaying the modeline. The face named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
35 @code{highlight} is used for highlighted extents (@pxref{Extents}). The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
36 faces named @code{left-margin} and @code{right-margin} are used for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
37 left and right margin areas, respectively (@pxref{Annotations}). The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
38 face named @code{zmacs-region} is used for the highlighted region
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
39 between point and mark.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
40
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
41
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
42 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
43 * Merging Faces:: How XEmacs decides which face to use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
44 for a character.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
45 * Basic Face Functions:: How to define and examine faces.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
46 * Face Properties:: How to access and modify a face's properties.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
47 * Face Convenience Functions:: Convenience functions for accessing
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
48 particular properties of a face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
49 * Other Face Display Functions:: Other functions pertaining to how a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
50 a face appears.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
51 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
52
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
53 @node Merging Faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
54 @subsection Merging Faces for Display
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
55
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
56 Here are all the ways to specify which face to use for display of text:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
57
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
58 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
59 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
60 With defaults. Each frame has a @dfn{default face}, which is used for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
61 all text that doesn't somehow specify another face. The face named
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
62 @code{default} applies to the text area, while the faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
63 @code{left-margin} and @code{right-margin} apply to the left and right
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
64 margin areas.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
65
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
66 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
67 With text properties. A character may have a @code{face} property; if so,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
68 it's displayed with that face. (Text properties are actually implemented
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
69 in terms of extents.) @xref{Text Properties}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
70
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
71 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
72 With extents. An extent may have a @code{face} property, which applies
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
73 to all the text covered by the extent; in addition, if the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
74 @code{highlight} property is set, the @code{highlight} property applies
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
75 when the mouse moves over the extent or if the extent is explicitly
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
76 highlighted. @xref{Extents}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
77
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
78 @item
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
79 With annotations. Annotations that are inserted into a buffer can specify
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
80 their own face. (Annotations are actually implemented in terms of extents.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
81 @xref{Annotations}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
82 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
83
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
84 If these various sources together specify more than one face for a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
85 particular character, XEmacs merges the properties of the various faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
86 specified. Extents, text properties, and annotations all use the same
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
87 underlying representation (as extents). When multiple extents cover one
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
88 character, an extent with higher priority overrides those with lower
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
89 priority. @xref{Extents}. If no extent covers a particular character,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
90 the @code{default} face is used.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
91
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
92 @cindex background pixmap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
93 If a background pixmap is specified, it determines what will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
94 displayed in the background of text characters. If the background
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
95 pixmap is actually a pixmap, with its colors specified, those colors are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
96 used; if it is a bitmap, the face's foreground and background colors are
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
97 used to color it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
98
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
99 @node Basic Face Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
100 @subsection Basic Functions for Working with Faces
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
101
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
102 The properties a face can specify include the font, the foreground
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
103 color, the background color, the background pixmap, the underlining,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
104 the display table, and (for TTY devices) whether the text is to be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
105 highlighted, dimmed, blinking, or displayed in reverse video.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
106 The face can also leave these unspecified, causing them to assume the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
107 value of the corresponding property of the @code{default} face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
108
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
109 Here are the basic primitives for working with faces.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
110
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
111 @defun make-face name &optional doc-string temporary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
112 This function defines and returns a new face named @var{name}, initially
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
113 with all properties unspecified. It does nothing if there is already a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
114 face named @var{name}. Optional argument @var{doc-string} specifies
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
115 an explanatory string used for descriptive purposes. If optional
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
116 argument @var{temporary} is non-@code{nil}, the face will automatically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
117 disappear when there are no more references to it anywhere in text or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
118 Lisp code (otherwise, the face will continue to exist indefinitely
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
119 even if it is not used).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
120 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
121
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
122 @defun face-list &optional temporary
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
123 This function returns a list of the names of all defined faces. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
124 @var{temporary} is @code{nil}, only the permanent faces are included.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
125 If it is @code{t}, only the temporary faces are included. If it is any
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
126 other non-@code{nil} value both permanent and temporary are included.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
127 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
128
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
129 @defun facep object
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
130 This function returns @code{t} if @var{object} is a face, else @code{nil}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
131 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
132
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
133 @defun copy-face old-face new-name &optional locale tag-set exact-p how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
134 This function defines a new face named @var{new-name} which is a copy of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
135 the existing face named @var{old-face}. If there is already a face
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
136 named @var{new-name}, then it alters the face to have the same
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
137 properties as @var{old-face}.
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
138
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
139 @var{locale}, @var{tag-set}, @var{exact-p} and @var{how-to-add} let you
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
140 copy just parts of the old face rather than the whole face, and are as
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
141 in @code{copy-specifier} (@pxref{Specifiers}).
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
142 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
143
2865
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
144
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
145 Finally, you have the possibility to give faces different names by
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
146 means of aliases. One typical use of this feature is to change the name
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
147 of a face while preserving backward compatibility. If a symbol has the
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
148 @code{face-alias} property set to another symbol, then this other symbol
2867
abbd4c295aa2 [xemacs-hg @ 2005-07-20 07:36:33 by didierv]
didierv
parents: 2865
diff changeset
149 will be used as the real face name instead. Recursive aliases (aliases
abbd4c295aa2 [xemacs-hg @ 2005-07-20 07:36:33 by didierv]
didierv
parents: 2865
diff changeset
150 of aliases) are allowed, but the depth of indirection is limited to 32
abbd4c295aa2 [xemacs-hg @ 2005-07-20 07:36:33 by didierv]
didierv
parents: 2865
diff changeset
151 to prevent alias loops.
2865
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
152
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
153
8baa2f03d853 [xemacs-hg @ 2005-07-19 09:45:00 by didierv]
didierv
parents: 2127
diff changeset
154
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
155 @node Face Properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
156 @subsection Face Properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
157
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
158 You can examine and modify the properties of an existing face with the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
159 following functions.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
160
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
161 The following symbols have predefined meanings:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
162
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
163 @table @code
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
164 @item foreground
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
165 The foreground color of the face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
166
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
167 @item background
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
168 The background color of the face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
169
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
170 @item font
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
171 The font used to display text covered by this face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
172
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
173 @item display-table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
174 The display table of the face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
175
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
176 @item background-pixmap
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
177 The pixmap displayed in the background of the face. Only used by faces
2127
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
178 on GUI devices, currently X11, GTK, and Microsoft Windows.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
179
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
180 @item underline
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
181 Underline all text covered by this face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
182
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
183 @item highlight
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
184 Highlight all text covered by this face. Only used by faces on TTY
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
185 devices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
186
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
187 @item dim
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
188 Dim all text covered by this face. Only used by faces on TTY devices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
189
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
190 @item blinking
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
191 Blink all text covered by this face. Only used by faces on TTY devices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
192
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
193 @item reverse
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
194 Reverse the foreground and background colors. Only used by faces on TTY
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
195 devices.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
196
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
197 @item doc-string
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
198 Description of what the face's normal use is. NOTE: This is not a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
199 specifier, unlike all the other built-in properties, and cannot contain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
200 locale-specific values.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
201 @end table
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
202
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
203 @defun set-face-property face property value &optional locale tag-set how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
204 This function changes a property of a @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
205
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
206 For built-in properties, the actual value of the property is a specifier
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
207 and you cannot change this; but you can change the specifications within
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
208 the specifier, and that is what this function will do. For user-defined
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
209 properties, you can use this function to either change the actual value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
210 of the property or, if this value is a specifier, change the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
211 specifications within it.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
212
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
213 If @var{property} is a built-in property, the specifications to be added
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
214 to this property can be supplied in many different ways:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
215
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
216 @itemize @bullet
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
217 If @var{value} is a simple instantiator (e.g. a string naming a font or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
218 color) or a list of instantiators, then the instantiator(s) will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
219 added as a specification of the property for the given @var{locale}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
220 (which defaults to @code{global} if omitted).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
221
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
222 If @var{value} is a list of specifications (each of which is a cons of a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
223 locale and a list of instantiators), then @var{locale} must be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
224 @code{nil} (it does not make sense to explicitly specify a locale in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
225 this case), and specifications will be added as given.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
226
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
227 If @var{value} is a specifier (as would be returned by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
228 @code{face-property} if no @var{locale} argument is given), then some or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
229 all of the specifications in the specifier will be added to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
230 property. In this case, the function is really equivalent to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
231 @code{copy-specifier} and @var{locale} has the same semantics (if it is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
232 a particular locale, the specification for the locale will be copied; if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
233 a locale type, specifications for all locales of that type will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
234 copied; if @code{nil} or @code{all}, then all specifications will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
235 copied).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
236 @end itemize
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
237
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
238 @var{how-to-add} should be either @code{nil} or one of the symbols
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
239 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
240 @code{remove-tag-set-append}, @code{remove-locale},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
241 @code{remove-locale-type}, or @code{remove-all}. See
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
242 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
243 of what each of these means. Most of the time, you do not need to worry
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
244 about this argument; the default behavior usually is fine.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
245
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
246 In general, it is OK to pass an instance object (e.g. as returned by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
247 @code{face-property-instance}) as an instantiator in place of an actual
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
248 instantiator. In such a case, the instantiator used to create that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
249 instance object will be used (for example, if you set a font-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
250 object as the value of the @code{font} property, then the font name used
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
251 to create that object will be used instead). If some cases, however,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
252 doing this conversion does not make sense, and this will be noted in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
253 documentation for particular types of instance objects.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
254
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
255 If @var{property} is not a built-in property, then this function will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
256 simply set its value if @var{locale} is @code{nil}. However, if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
257 @var{locale} is given, then this function will attempt to add
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
258 @var{value} as the instantiator for the given @var{locale}, using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
259 @code{add-spec-to-specifier}. If the value of the property is not a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
260 specifier, it will automatically be converted into a @code{generic}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
261 specifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
262 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
263
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
264 @defun remove-face-property face property &optional locale tag-set exact-p
440
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
265 This function removes a property of a @var{face}.
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
266
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
267 For built-in properties, this is analogous to @code{remove-specifier}.
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
268 For more information, @xref{Other Specification Functions}.
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
269
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
270 When @var{property} is not a built-in property, this function will just
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
271 remove its value if @var{locale} is @code{nil} or @code{all}. However,
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
272 if @var{locale} is other than that, this function will attempt to remove
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
273 @var{value} as the instantiator for the given @var{locale} with
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
274 @code{remove-specifier}. If the value of the property is not a
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
275 specifier, it will be converted into a @code{generic} specifier
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
276 automatically.
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
277 @end defun
8de8e3f6228a Import from CVS: tag r21-2-28
cvs
parents: 428
diff changeset
278
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
279 @defun face-property face property &optional locale tag-set exact-p
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
280 This function returns @var{face}'s value of the given @var{property}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
281
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
282 If @var{locale} is omitted, the @var{face}'s actual value for
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
283 @var{property} will be returned. For built-in properties, this will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
284 a specifier object of a type appropriate to the property (e.g. a font or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
285 color specifier). For other properties, this could be anything.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
286
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
287 If @var{locale} is supplied, then instead of returning the actual value,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
288 the specification(s) for the given locale or locale type will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
289 returned. This will only work if the actual value of @var{property} is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
290 a specifier (this will always be the case for built-in properties, but
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
291 not or not may apply to user-defined properties). If the actual value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
292 of @var{property} is not a specifier, this value will simply be returned
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
293 regardless of @var{locale}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
294
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
295 The return value will be a list of instantiators (e.g. strings
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
296 specifying a font or color name), or a list of specifications, each of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
297 which is a cons of a locale and a list of instantiators. Specifically,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
298 if @var{locale} is a particular locale (a buffer, window, frame, device,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
299 or @code{global}), a list of instantiators for that locale will be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
300 returned. Otherwise, if @var{locale} is a locale type (one of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
301 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
302 the specifications for all locales of that type will be returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
303 Finally, if @var{locale} is @code{all}, the specifications for all
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
304 locales of all types will be returned.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
305
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
306 The specifications in a specifier determine what the value of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
307 @var{property} will be in a particular @dfn{domain} or set of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
308 circumstances, which is typically a particular Emacs window along with
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
309 the buffer it contains and the frame and device it lies within. The
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
310 value is derived from the instantiator associated with the most specific
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
311 locale (in the order buffer, window, frame, device, and @code{global})
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
312 that matches the domain in question. In other words, given a domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
313 (i.e. an Emacs window, usually), the specifier for @var{property} will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
314 first be searched for a specification whose locale is the buffer
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
315 contained within that window; then for a specification whose locale is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
316 the window itself; then for a specification whose locale is the frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
317 that the window is contained within; etc. The first instantiator that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
318 is valid for the domain (usually this means that the instantiator is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
319 recognized by the device [i.e. the X server or TTY device] that the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
320 domain is on). The function @code{face-property-instance} actually does
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
321 all this, and is used to determine how to display the face.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
322 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
323
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
324 @defun face-property-instance face property &optional domain default no-fallback
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
325 This function returns the instance of @var{face}'s @var{property} in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
326 specified @var{domain}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
327
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
328 Under most circumstances, @var{domain} will be a particular window, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
329 the returned instance describes how the specified property actually is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
330 displayed for that window and the particular buffer in it. Note that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
331 this may not be the same as how the property appears when the buffer is
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
332 displayed in a different window or frame, or how the property appears in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
333 the same window if you switch to another buffer in that window; and in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
334 those cases, the returned instance would be different.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
335
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
336 The returned instance will typically be a color-instance, font-instance,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
337 or pixmap-instance object, and you can query it using the appropriate
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
338 object-specific functions. For example, you could use
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
339 @code{color-instance-rgb-components} to find out the RGB (red, green,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
340 and blue) components of how the @code{background} property of the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
341 @code{highlight} face is displayed in a particular window. The results
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
342 might be different from the results you would get for another window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
343 (perhaps the user specified a different color for the frame that window
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
344 is on; or perhaps the same color was specified but the window is on a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
345 different X server, and that X server has different RGB values for the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
346 color from this one).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
347
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
348 @var{domain} defaults to the selected window if omitted.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
349
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
350 @var{domain} can be a frame or device, instead of a window. The value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
351 returned for a such a domain is used in special circumstances when a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
352 more specific domain does not apply; for example, a frame value might be
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
353 used for coloring a toolbar, which is conceptually attached to a frame
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
354 rather than a particular window. The value is also useful in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
355 determining what the value would be for a particular window within the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
356 frame or device, if it is not overridden by a more specific
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
357 specification.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
358
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
359 If @var{property} does not name a built-in property, its value will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
360 simply be returned unless it is a specifier object, in which case it
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
361 will be instanced using @code{specifier-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
362
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
363 Optional arguments @var{default} and @var{no-fallback} are the same as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
364 in @code{specifier-instance}. @xref{Specifiers}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
365 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
366
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
367 @node Face Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
368 @subsection Face Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
369
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
370 @deffn Command set-face-foreground face color &optional locale tag-set how-to-add
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
371 @deffnx Command set-face-background face color &optional locale tag-set how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
372 These functions set the foreground (respectively, background) color of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
373 face @var{face} to @var{color}. The argument @var{color} should be a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
374 string (the name of a color) or a color object as returned by
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
375 @code{make-color} (@pxref{Colors}).
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
376 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
377
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
378 @deffn Command set-face-background-pixmap face pixmap &optional locale tag-set how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
379 This function sets the background pixmap of face @var{face} to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
380 @var{pixmap}. The argument @var{pixmap} should be a string (the name of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
381 a bitmap or pixmap file; the directories listed in the variable
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
382 @code{x-bitmap-file-path} will be searched) or a glyph object as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
383 returned by @code{make-glyph} (@pxref{Glyphs}). The argument may also
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
384 be a list of the form @code{(@var{width} @var{height} @var{data})} where
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
385 @var{width} and @var{height} are the size in pixels, and @var{data} is a
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
386 string, containing the raw bits of the bitmap.
2127
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
387
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
388 Similarly to how the glyph's image specifier works @xref{Creating
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
389 Glyphs}, you don't create your own image specifier, but rather add
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
390 specifications to the existing one. Note that the image instance that is
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
391 generated in order to actually display the background pixmap is of type
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
392 @code{mono-pixmap}, meaning that it's a two-color image and the
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
393 foreground and background of the image get filled in with the
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
394 corresponding colors from the face. (#### Is this still true?)
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
395 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
396
1137
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
397 @deffn Command set-face-background-pixmap-file face file
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
398 This function sets the background pixmap of face @var{face} to the image
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
399 contained in @var{file}. This is just a simplified version of
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
400 @code{set-face-background-pixmap} which provides filename completion.
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
401 @end deffn
c6facab13185 [xemacs-hg @ 2002-12-03 10:35:06 by didierv]
didierv
parents: 444
diff changeset
402
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
403 @deffn Command set-face-font face font &optional locale tag-set how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
404 This function sets the font of face @var{face}. The argument @var{font}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
405 should be a string or a font object as returned by @code{make-font}
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
406 (@pxref{Fonts}).
3674
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
407
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
408 If you want to set a face's font for a given Mule character set, you
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
409 need to include some tags in @var{tag-set} that match that character
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
410 set. See the documentation of @code{define-specifier-tag} and its
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
411 @code{charset-predicate} argument.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
412 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
413
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
414 @deffn Command set-face-underline-p face underline-p &optional locale tag-set how-to-add
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
415 This function sets the underline property of face @var{face}.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
416 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
417
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
418 @defun face-foreground face &optional locale tag-set exact-p
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
419 @defunx face-background face &optional locale tag-set exact-p
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
420 These functions return the foreground (respectively, background) color
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
421 specifier of face @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
422 @xref{Colors}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
423 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
424
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
425 @defun face-background-pixmap face &optional locale tag-set exact-p
2127
4657b5a54253 [xemacs-hg @ 2004-06-14 10:24:44 by stephent]
stephent
parents: 1137
diff changeset
426 This function returns the background-pixmap image specifier of face
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
427 @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
428 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
429
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
430 @defun face-font face &optional locale tag-set exact-p
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
431 This function returns the font specifier of face @var{face}. (Note:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
432 This is not the same as the function @code{face-font} in FSF Emacs.)
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
433
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
434 @xref{Fonts}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
435 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
436
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
437 @defun face-font-name face &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
438 This function returns the name of the font of face @var{face}, or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
439 @code{nil} if it is unspecified. This is basically equivalent to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
440 @code{(font-name (face-font @var{face}) @var{domain})} except that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
441 it does not cause an error if @var{face}'s font is @code{nil}. (This
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
442 function is named @code{face-font} in FSF Emacs.)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
443 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
444
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
445 @defun face-underline-p face &optional locale
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
446 This function returns the underline property of face @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
447 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
448
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
449 @defun face-foreground-instance face &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
450 @defunx face-background-instance face &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
451 These functions return the foreground (respectively, background) color
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
452 specifier of face @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
453 @xref{Colors}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
454 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
455
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
456 @defun face-background-pixmap-instance face &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
457 This function return the background-pixmap glyph object of face
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
458 @var{face}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
459 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
460
3674
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
461 @defun face-font-instance face &optional domain charset
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
462 This function returns the font specifier of face @var{face} in domain
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
463 @var{domain} (defaulting to the selected device) with Mule charset
f200f93c0b69 [xemacs-hg @ 2006-11-11 16:05:31 by aidan]
aidan
parents: 2867
diff changeset
464 @var{charset} (defaulting to ASCII).
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
465 @xref{Fonts}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
466 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
467
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
468 @node Other Face Display Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
469 @subsection Other Face Display Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
470
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
471 @deffn Command invert-face face &optional locale
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
472 Swap the foreground and background colors of face @var{face}. If the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
473 face doesn't specify both foreground and background, then its foreground
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
474 and background are set to the default background and foreground.
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
475 @end deffn
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
476
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
477 @defun face-equal face1 face2 &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
478 This returns @code{t} if the faces @var{face1} and @var{face2} will
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
479 display in the same way. @var{domain} is as in
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
480 @code{face-property-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
481 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
482
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
483 @defun face-differs-from-default-p face &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
484 This returns @code{t} if the face @var{face} displays differently from
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
485 the default face. @var{domain} is as in @code{face-property-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
486 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
487
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
488 @node Fonts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
489 @section Fonts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
490 @cindex fonts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
491
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
492 This section describes how to work with font specifier and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
493 font instance objects, which encapsulate fonts in the window system.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
494
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
495 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
496 * Font Specifiers:: Specifying how a font will appear.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
497 * Font Instances:: What a font specifier gets instanced as.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
498 * Font Instance Names:: The name of a font instance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
499 * Font Instance Size:: The size of a font instance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
500 * Font Instance Characteristics:: Display characteristics of font instances.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
501 * Font Convenience Functions:: Convenience functions that automatically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
502 instance and retrieve the properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
503 of a font specifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
504 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
505
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
506 @node Font Specifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
507 @subsection Font Specifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
508
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
509 @defun font-specifier-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
510 This predicate returns @code{t} if @var{object} is a font specifier, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
511 @code{nil} otherwise.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
512 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
513
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
514 @defun make-font-specifier spec-list
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
515
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
516 Return a new @code{font} specifier object with the given specification
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
517 list. @var{spec-list} can be a list of specifications (each of which is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
518 a cons of a locale and a list of instantiators), a single instantiator,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
519 or a list of instantiators. @xref{Specifiers}, for more information
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
520 about specifiers.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
521
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
522 Valid instantiators for font specifiers are:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
523
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
524 @itemize @bullet
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
525
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
526 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
527 A string naming a font (e.g. under X this might be
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
528 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a 14-point
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
529 upright medium-weight Courier font).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
530 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
531 A font instance (use that instance directly if the device matches,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
532 or use the string that generated it).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
533 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
534 A vector of no elements (only on TTY's; this means to set no font
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
535 at all, thus using the "natural" font of the terminal's text).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
536 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
537 A vector of one element (a face to inherit from).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
538 @end itemize
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
539 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
540
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
541 @node Font Instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
542 @subsection Font Instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
543
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
544 @defun font-instance-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
545 This predicate returns @code{t} if @var{object} is a font instance, and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
546 @code{nil} otherwise.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
547 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
548
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
549 @defun make-font-instance name &optional device noerror
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
550 This function creates a new font-instance object of the specified name.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
551 @var{device} specifies the device this object applies to and defaults to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
552 the selected device. An error is signalled if the font is unknown or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
553 cannot be allocated; however, if @var{noerror} is non-@code{nil},
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
554 @code{nil} is simply returned in this case.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
555
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
556 The returned object is a normal, first-class lisp object. The way you
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
557 ``deallocate'' the font is the way you deallocate any other lisp object:
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
558 you drop all pointers to it and allow it to be garbage collected. When
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
559 these objects are GCed, the underlying X data is deallocated as well.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
560 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
561
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
562 @node Font Instance Names
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
563 @subsection Font Instance Names
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
564 @cindex font instance name
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
565 @cindex available fonts
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
566 @cindex fonts available
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
567
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
568 @defun list-fonts pattern &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
569 This function returns a list of font names matching the given pattern.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
570 @var{device} specifies which device to search for names, and defaults to
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
571 the currently selected device.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
572 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
573
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
574 @defun font-instance-name font-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
575 This function returns the name used to allocate @var{font-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
576 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
577
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
578 @defun font-instance-truename font-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
579 This function returns the canonical name of the given font instance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
580 Font names are patterns which may match any number of fonts, of which
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
581 the first found is used. This returns an unambiguous name for that font
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
582 (but not necessarily its only unambiguous name).
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
583 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
584
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
585 @node Font Instance Size
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
586 @subsection Font Instance Size
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
587 @cindex font instance size
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
588
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
589 @defun x-font-size font
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
590 This function returns the nominal size of the given font. This is done
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
591 by parsing its name, so it's likely to lose. X fonts can be specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
592 (by the user) in either pixels or 10ths of points, and this returns the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
593 first one it finds, so you have to decide which units the returned value
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
594 is measured in yourself ...
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
595 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
596
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
597 @defun x-find-larger-font font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
598 This function loads a new, slightly larger version of the given font (or
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
599 font name). Returns the font if it succeeds, @code{nil} otherwise. If
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
600 scalable fonts are available, this returns a font which is 1 point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
601 larger. Otherwise, it returns the next larger version of this font that
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
602 is defined.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
603 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
604
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
605 @defun x-find-smaller-font font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
606 This function loads a new, slightly smaller version of the given font
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
607 (or font name). Returns the font if it succeeds, @code{nil} otherwise.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
608 If scalable fonts are available, this returns a font which is 1 point
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
609 smaller. Otherwise, it returns the next smaller version of this font
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
610 that is defined.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
611 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
612
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
613 @node Font Instance Characteristics
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
614 @subsection Font Instance Characteristics
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
615 @cindex font instance characteristics
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
616 @cindex characteristics of font instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
617 @cindex bold
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
618 @cindex demibold
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
619 @cindex italic
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
620 @cindex oblique
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
621
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
622 @defun font-instance-properties font-instance
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
623 This function returns the properties (an alist or @code{nil}) of
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
624 @var{font-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
625 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
626
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
627 @defun x-make-font-bold font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
628 Given an X font specification, this attempts to make a ``bold'' font.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
629 If it fails, it returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
630 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
631
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
632 @defun x-make-font-unbold font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
633 Given an X font specification, this attempts to make a non-bold font.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
634 If it fails, it returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
635 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
636
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
637 @defun x-make-font-italic font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
638 Given an X font specification, this attempts to make an ``italic'' font.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
639 If it fails, it returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
640 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
641
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
642 @defun x-make-font-unitalic font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
643 Given an X font specification, this attempts to make a non-italic font.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
644 If it fails, it returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
645 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
646
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
647 @defun x-make-font-bold-italic font &optional device
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
648 Given an X font specification, this attempts to make a ``bold-italic''
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
649 font. If it fails, it returns @code{nil}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
650 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
651
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
652 @node Font Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
653 @subsection Font Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
654
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
655 @defun font-name font &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
656 This function returns the name of the @var{font} in the specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
657 @var{domain}, if any. @var{font} should be a font specifier object and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
658 @var{domain} is normally a window and defaults to the selected window if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
659 omitted. This is equivalent to using @code{specifier-instance} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
660 applying @code{font-instance-name} to the result.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
661 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
662
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
663 @defun font-truename font &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
664 This function returns the truename of the @var{font} in the specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
665 @var{domain}, if any. @var{font} should be a font specifier object and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
666 @var{domain} is normally a window and defaults to the selected window if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
667 omitted. This is equivalent to using @code{specifier-instance} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
668 applying @code{font-instance-truename} to the result.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
669 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
670
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
671 @defun font-properties font &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
672 This function returns the properties of the @var{font} in the specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
673 @var{domain}, if any. @var{font} should be a font specifier object and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
674 @var{domain} is normally a window and defaults to the selected window if
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
675 omitted. This is equivalent to using @code{specifier-instance} and
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
676 applying @code{font-instance-properties} to the result.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
677 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
678
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
679 @node Colors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
680 @section Colors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
681 @cindex colors
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
682
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
683 @menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
684 * Color Specifiers:: Specifying how a color will appear.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
685 * Color Instances:: What a color specifier gets instanced as.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
686 * Color Instance Properties:: Properties of color instances.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
687 * Color Convenience Functions:: Convenience functions that automatically
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
688 instance and retrieve the properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
689 of a color specifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
690 @end menu
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
691
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
692 @node Color Specifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
693 @subsection Color Specifiers
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
694
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
695 @defun color-specifier-p object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
696 This function returns non-@code{nil} if @var{object} is a color specifier.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
697 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
698
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
699 @defun make-color-specifier spec-list
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
700
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
701 Return a new @code{color} specifier object with the given specification
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
702 list. @var{spec-list} can be a list of specifications (each of which is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
703 a cons of a locale and a list of instantiators), a single instantiator,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
704 or a list of instantiators. @xref{Specifiers}, for a detailed
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
705 description of how specifiers work.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
706
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
707 Valid instantiators for color specifiers are:
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
708
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
709 @itemize @bullet
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
710 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
711 A string naming a color (e.g. under X this might be "lightseagreen2" or
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
712 "#F534B2").
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
713
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
714 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
715 A color instance (use that instance directly if the device matches,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
716 or use the string that generated it).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
717
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
718 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
719 A vector of no elements (only on TTY's; this means to set no color at
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
720 all, thus using the "natural" color of the terminal's text).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
721
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
722 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
723 A vector of one or two elements: a face to inherit from, and optionally
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
724 a symbol naming which property of that face to inherit, either
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
725 @code{foreground} or @code{background} (if omitted, defaults to the same
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
726 property that this color specifier is used for; if this specifier is not
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
727 part of a face, the instantiator would not be valid).
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
728 @end itemize
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
729 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
730
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
731 @defun make-face-boolean-specifier spec-list
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
732
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
733 Return a new @code{face-boolean} specifier object with the given spec
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
734 list. @var{spec-list} can be a list of specifications (each of which is
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
735 a cons of a locale and a list of instantiators), a single instantiator,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
736 or a list of instantiators. @xref{Specifiers}, for a detailed
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
737 description of how specifiers work.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
738
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
739 Valid instantiators for face-boolean specifiers are
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
740
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
741 @itemize @bullet
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
742 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
743 t or nil.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
744 @item
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
745 A vector of two or three elements: a face to inherit from, optionally a
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
746 symbol naming the property of that face to inherit from (if omitted,
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
747 defaults to the same property that this face-boolean specifier is used
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
748 for; if this specifier is not part of a face, the instantiator would not
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
749 be valid), and optionally a value which, if non-@code{nil}, means to invert the
442
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
750 sense of the inherited property.
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
751 @end itemize
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
752
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
753 @end defun
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
754
abe6d1db359e Import from CVS: tag r21-2-36
cvs
parents: 440
diff changeset
755
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
756 @node Color Instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
757 @subsection Color Instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
758 @cindex color instances
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
759
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
760 A @dfn{color-instance object} is an object describing the way a color
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
761 specifier is instanced in a particular domain. Functions such as
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
762 @code{face-background-instance} return a color-instance object. For
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
763 example,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
764
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
765 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
766 (face-background-instance 'default (next-window))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
767 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
768 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
769
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
770 The color-instance object returned describes the way the background
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
771 color of the @code{default} face is displayed in the next window after
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
772 the selected one.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
773
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
774 @defun color-instance-p object
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
775 This function returns non-@code{nil} if @var{object} is a color-instance.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
776 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
777
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
778 @node Color Instance Properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
779 @subsection Color Instance Properties
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
780
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
781 @defun color-instance-name color-instance
444
576fb035e263 Import from CVS: tag r21-2-37
cvs
parents: 442
diff changeset
782 This function returns the name used to allocate @var{color-instance}.
428
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
783 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
784
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
785 @defun color-instance-rgb-components color-instance
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
786 This function returns a three element list containing the red, green,
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
787 and blue color components of @var{color-instance}.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
788
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
789 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
790 (color-instance-rgb-components
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
791 (face-background-instance 'default (next-window)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
792 @result{} (65535 58596 46517)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
793 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
794 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
795
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
796 @node Color Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
797 @subsection Color Convenience Functions
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
798
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
799 @defun color-name color &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
800 This function returns the name of the @var{color} in the specified
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
801 @var{domain}, if any. @var{color} should be a color specifier object
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
802 and @var{domain} is normally a window and defaults to the selected
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
803 window if omitted. This is equivalent to using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
804 @code{specifier-instance} and applying @code{color-instance-name} to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
805 result.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
806 @end defun
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
807
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
808 @defun color-rgb-components color &optional domain
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
809 This function returns the @sc{rgb} components of the @var{color} in the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
810 specified @var{domain}, if any. @var{color} should be a color specifier
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
811 object and @var{domain} is normally a window and defaults to the
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
812 selected window if omitted. This is equivalent to using
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
813 @code{specifier-instance} and applying
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
814 @code{color-instance-rgb-components} to the result.
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
815
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
816 @example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
817 (color-rgb-components (face-background 'default (next-window)))
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
818 @result{} (65535 58596 46517)
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
819 @end example
3ecd8885ac67 Import from CVS: tag r21-2-22
cvs
parents:
diff changeset
820 @end defun