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