|
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
|
|
|
130 This function returns whether the given object is a face.
|
|
|
131 @end defun
|
|
|
132
|
|
|
133 @defun copy-face old-face new-name &optional locale how-to-add
|
|
|
134 This function defines a new face named @var{new-name} which is a copy of
|
|
|
135 the existing face named @var{old-face}. If there is already a face
|
|
|
136 named @var{new-name}, then it alters the face to have the same
|
|
|
137 properties as @var{old-face}. @var{locale} and @var{how-to-add}
|
|
|
138 let you copy just parts of the old face rather than the whole face,
|
|
|
139 and are as in @code{copy-specifier} (@pxref{Specifiers}).
|
|
|
140 @end defun
|
|
|
141
|
|
|
142 @node Face Properties
|
|
|
143 @subsection Face Properties
|
|
|
144
|
|
|
145 You can examine and modify the properties of an existing face with the
|
|
|
146 following functions.
|
|
|
147
|
|
|
148 The following symbols have predefined meanings:
|
|
|
149
|
|
|
150 @table @code
|
|
|
151 @item foreground
|
|
|
152 The foreground color of the face.
|
|
|
153
|
|
|
154 @item background
|
|
|
155 The background color of the face.
|
|
|
156
|
|
|
157 @item font
|
|
|
158 The font used to display text covered by this face.
|
|
|
159
|
|
|
160 @item display-table
|
|
|
161 The display table of the face.
|
|
|
162
|
|
|
163 @item background-pixmap
|
|
|
164 The pixmap displayed in the background of the face. Only used by faces
|
|
|
165 on X devices.
|
|
|
166
|
|
|
167 @item underline
|
|
|
168 Underline all text covered by this face.
|
|
|
169
|
|
|
170 @item highlight
|
|
|
171 Highlight all text covered by this face. Only used by faces on TTY
|
|
|
172 devices.
|
|
|
173
|
|
|
174 @item dim
|
|
|
175 Dim all text covered by this face. Only used by faces on TTY devices.
|
|
|
176
|
|
|
177 @item blinking
|
|
|
178 Blink all text covered by this face. Only used by faces on TTY devices.
|
|
|
179
|
|
|
180 @item reverse
|
|
|
181 Reverse the foreground and background colors. Only used by faces on TTY
|
|
|
182 devices.
|
|
|
183
|
|
|
184 @item doc-string
|
|
|
185 Description of what the face's normal use is. NOTE: This is not a
|
|
|
186 specifier, unlike all the other built-in properties, and cannot contain
|
|
|
187 locale-specific values.
|
|
|
188 @end table
|
|
|
189
|
|
|
190 @defun set-face-property face property value &optional locale tag how-to-add
|
|
|
191 This function changes a property of a @var{face}.
|
|
|
192
|
|
|
193 For built-in properties, the actual value of the property is a specifier
|
|
|
194 and you cannot change this; but you can change the specifications within
|
|
|
195 the specifier, and that is what this function will do. For user-defined
|
|
|
196 properties, you can use this function to either change the actual value
|
|
|
197 of the property or, if this value is a specifier, change the
|
|
|
198 specifications within it.
|
|
|
199
|
|
|
200 If @var{property} is a built-in property, the specifications to be added
|
|
|
201 to this property can be supplied in many different ways:
|
|
|
202
|
|
|
203 @itemize @bullet
|
|
|
204 If @var{value} is a simple instantiator (e.g. a string naming a font or
|
|
|
205 color) or a list of instantiators, then the instantiator(s) will be
|
|
|
206 added as a specification of the property for the given @var{locale}
|
|
|
207 (which defaults to @code{global} if omitted).
|
|
|
208
|
|
|
209 If @var{value} is a list of specifications (each of which is a cons of a
|
|
|
210 locale and a list of instantiators), then @var{locale} must be
|
|
|
211 @code{nil} (it does not make sense to explicitly specify a locale in
|
|
|
212 this case), and specifications will be added as given.
|
|
|
213
|
|
|
214 If @var{value} is a specifier (as would be returned by
|
|
|
215 @code{face-property} if no @var{locale} argument is given), then some or
|
|
|
216 all of the specifications in the specifier will be added to the
|
|
|
217 property. In this case, the function is really equivalent to
|
|
|
218 @code{copy-specifier} and @var{locale} has the same semantics (if it is
|
|
|
219 a particular locale, the specification for the locale will be copied; if
|
|
|
220 a locale type, specifications for all locales of that type will be
|
|
|
221 copied; if @code{nil} or @code{all}, then all specifications will be
|
|
|
222 copied).
|
|
|
223 @end itemize
|
|
|
224
|
|
|
225 @var{how-to-add} should be either @code{nil} or one of the symbols
|
|
|
226 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
|
|
|
227 @code{remove-tag-set-append}, @code{remove-locale},
|
|
|
228 @code{remove-locale-type}, or @code{remove-all}. See
|
|
|
229 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
|
|
|
230 of what each of these means. Most of the time, you do not need to worry
|
|
|
231 about this argument; the default behavior usually is fine.
|
|
|
232
|
|
|
233 In general, it is OK to pass an instance object (e.g. as returned by
|
|
|
234 @code{face-property-instance}) as an instantiator in place of an actual
|
|
|
235 instantiator. In such a case, the instantiator used to create that
|
|
|
236 instance object will be used (for example, if you set a font-instance
|
|
|
237 object as the value of the @code{font} property, then the font name used
|
|
|
238 to create that object will be used instead). If some cases, however,
|
|
|
239 doing this conversion does not make sense, and this will be noted in the
|
|
|
240 documentation for particular types of instance objects.
|
|
|
241
|
|
|
242 If @var{property} is not a built-in property, then this function will
|
|
|
243 simply set its value if @var{locale} is @code{nil}. However, if
|
|
|
244 @var{locale} is given, then this function will attempt to add
|
|
|
245 @var{value} as the instantiator for the given @var{locale}, using
|
|
|
246 @code{add-spec-to-specifier}. If the value of the property is not a
|
|
|
247 specifier, it will automatically be converted into a @code{generic}
|
|
|
248 specifier.
|
|
|
249 @end defun
|
|
|
250
|
|
440
|
251 @defun remove-face-property face property &optional local tag-set exact-p
|
|
|
252 This function removes a property of a @var{face}.
|
|
|
253
|
|
|
254 For built-in properties, this is analogous to @code{remove-specifier}.
|
|
|
255 For more information, @xref{Other Specification Functions}.
|
|
|
256
|
|
|
257 When @var{property} is not a built-in property, this function will just
|
|
|
258 remove its value if @var{locale} is @code{nil} or @code{all}. However,
|
|
|
259 if @var{locale} is other than that, this function will attempt to remove
|
|
|
260 @var{value} as the instantiator for the given @var{locale} with
|
|
|
261 @code{remove-specifier}. If the value of the property is not a
|
|
|
262 specifier, it will be converted into a @code{generic} specifier
|
|
|
263 automatically.
|
|
|
264 @end defun
|
|
|
265
|
|
428
|
266 @defun face-property face property &optional locale
|
|
|
267 This function returns @var{face}'s value of the given @var{property}.
|
|
|
268
|
|
|
269 If @var{locale} is omitted, the @var{face}'s actual value for
|
|
|
270 @var{property} will be returned. For built-in properties, this will be
|
|
|
271 a specifier object of a type appropriate to the property (e.g. a font or
|
|
|
272 color specifier). For other properties, this could be anything.
|
|
|
273
|
|
|
274 If @var{locale} is supplied, then instead of returning the actual value,
|
|
|
275 the specification(s) for the given locale or locale type will be
|
|
|
276 returned. This will only work if the actual value of @var{property} is
|
|
|
277 a specifier (this will always be the case for built-in properties, but
|
|
|
278 not or not may apply to user-defined properties). If the actual value
|
|
|
279 of @var{property} is not a specifier, this value will simply be returned
|
|
|
280 regardless of @var{locale}.
|
|
|
281
|
|
|
282 The return value will be a list of instantiators (e.g. strings
|
|
|
283 specifying a font or color name), or a list of specifications, each of
|
|
|
284 which is a cons of a locale and a list of instantiators. Specifically,
|
|
|
285 if @var{locale} is a particular locale (a buffer, window, frame, device,
|
|
|
286 or @code{global}), a list of instantiators for that locale will be
|
|
|
287 returned. Otherwise, if @var{locale} is a locale type (one of the
|
|
|
288 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
|
|
|
289 the specifications for all locales of that type will be returned.
|
|
|
290 Finally, if @var{locale} is @code{all}, the specifications for all
|
|
|
291 locales of all types will be returned.
|
|
|
292
|
|
|
293 The specifications in a specifier determine what the value of
|
|
|
294 @var{property} will be in a particular @dfn{domain} or set of
|
|
|
295 circumstances, which is typically a particular Emacs window along with
|
|
|
296 the buffer it contains and the frame and device it lies within. The
|
|
|
297 value is derived from the instantiator associated with the most specific
|
|
|
298 locale (in the order buffer, window, frame, device, and @code{global})
|
|
|
299 that matches the domain in question. In other words, given a domain
|
|
|
300 (i.e. an Emacs window, usually), the specifier for @var{property} will
|
|
|
301 first be searched for a specification whose locale is the buffer
|
|
|
302 contained within that window; then for a specification whose locale is
|
|
|
303 the window itself; then for a specification whose locale is the frame
|
|
|
304 that the window is contained within; etc. The first instantiator that
|
|
|
305 is valid for the domain (usually this means that the instantiator is
|
|
|
306 recognized by the device [i.e. the X server or TTY device] that the
|
|
|
307 domain is on). The function @code{face-property-instance} actually does
|
|
|
308 all this, and is used to determine how to display the face.
|
|
|
309 @end defun
|
|
|
310
|
|
|
311 @defun face-property-instance face property &optional domain default no-fallback
|
|
|
312 This function returns the instance of @var{face}'s @var{property} in the
|
|
|
313 specified @var{domain}.
|
|
|
314
|
|
|
315 Under most circumstances, @var{domain} will be a particular window, and
|
|
|
316 the returned instance describes how the specified property actually is
|
|
|
317 displayed for that window and the particular buffer in it. Note that
|
|
|
318 this may not be the same as how the property appears when the buffer is
|
|
|
319 displayed in a different window or frame, or how the property appears in
|
|
|
320 the same window if you switch to another buffer in that window; and in
|
|
|
321 those cases, the returned instance would be different.
|
|
|
322
|
|
|
323 The returned instance will typically be a color-instance, font-instance,
|
|
|
324 or pixmap-instance object, and you can query it using the appropriate
|
|
|
325 object-specific functions. For example, you could use
|
|
|
326 @code{color-instance-rgb-components} to find out the RGB (red, green,
|
|
|
327 and blue) components of how the @code{background} property of the
|
|
|
328 @code{highlight} face is displayed in a particular window. The results
|
|
|
329 might be different from the results you would get for another window
|
|
|
330 (perhaps the user specified a different color for the frame that window
|
|
|
331 is on; or perhaps the same color was specified but the window is on a
|
|
|
332 different X server, and that X server has different RGB values for the
|
|
|
333 color from this one).
|
|
|
334
|
|
|
335 @var{domain} defaults to the selected window if omitted.
|
|
|
336
|
|
|
337 @var{domain} can be a frame or device, instead of a window. The value
|
|
|
338 returned for a such a domain is used in special circumstances when a
|
|
|
339 more specific domain does not apply; for example, a frame value might be
|
|
|
340 used for coloring a toolbar, which is conceptually attached to a frame
|
|
|
341 rather than a particular window. The value is also useful in
|
|
|
342 determining what the value would be for a particular window within the
|
|
|
343 frame or device, if it is not overridden by a more specific
|
|
|
344 specification.
|
|
|
345
|
|
|
346 If @var{property} does not name a built-in property, its value will
|
|
|
347 simply be returned unless it is a specifier object, in which case it
|
|
|
348 will be instanced using @code{specifier-instance}.
|
|
|
349
|
|
|
350 Optional arguments @var{default} and @var{no-fallback} are the same as
|
|
|
351 in @code{specifier-instance}. @xref{Specifiers}.
|
|
|
352 @end defun
|
|
|
353
|
|
|
354 @node Face Convenience Functions
|
|
|
355 @subsection Face Convenience Functions
|
|
|
356
|
|
|
357 @defun set-face-foreground face color &optional locale tag how-to-add
|
|
|
358 @defunx set-face-background face color &optional locale tag how-to-add
|
|
|
359 These functions set the foreground (respectively, background) color of
|
|
|
360 face @var{face} to @var{color}. The argument @var{color} should be a
|
|
|
361 string (the name of a color) or a color object as returned by
|
|
|
362 @code{make-color} (@pxref{Colors}).
|
|
|
363 @end defun
|
|
|
364
|
|
|
365 @defun set-face-background-pixmap face pixmap &optional locale tag how-to-add
|
|
|
366 This function sets the background pixmap of face @var{face} to
|
|
|
367 @var{pixmap}. The argument @var{pixmap} should be a string (the name of
|
|
|
368 a bitmap or pixmap file; the directories listed in the variable
|
|
|
369 @code{x-bitmap-file-path} will be searched) or a glyph object as
|
|
|
370 returned by @code{make-glyph} (@pxref{Glyphs}). The argument may also
|
|
|
371 be a list of the form @code{(@var{width} @var{height} @var{data})} where
|
|
|
372 @var{width} and @var{height} are the size in pixels, and @var{data} is a
|
|
|
373 string, containing the raw bits of the bitmap.
|
|
|
374 @end defun
|
|
|
375
|
|
|
376 @defun set-face-font face font &optional locale tag how-to-add
|
|
|
377 This function sets the font of face @var{face}. The argument @var{font}
|
|
|
378 should be a string or a font object as returned by @code{make-font}
|
|
|
379 (@pxref{Fonts}).
|
|
|
380 @end defun
|
|
|
381
|
|
|
382 @defun set-face-underline-p face underline-p &optional locale tag how-to-add
|
|
|
383 This function sets the underline property of face @var{face}.
|
|
|
384 @end defun
|
|
|
385
|
|
|
386 @defun face-foreground face &optional locale
|
|
|
387 @defunx face-background face &optional locale
|
|
|
388 These functions return the foreground (respectively, background) color
|
|
|
389 specifier of face @var{face}.
|
|
|
390 @xref{Colors}.
|
|
|
391 @end defun
|
|
|
392
|
|
|
393 @defun face-background-pixmap face &optional locale
|
|
|
394 This function return the background-pixmap glyph object of face
|
|
|
395 @var{face}.
|
|
|
396 @end defun
|
|
|
397
|
|
|
398 @defun face-font face &optional locale
|
|
|
399 This function returns the font specifier of face @var{face}. (Note:
|
|
|
400 This is not the same as the function @code{face-font} in FSF Emacs.)
|
|
|
401 @xref{Fonts}.
|
|
|
402 @end defun
|
|
|
403
|
|
|
404 @defun face-font-name face &optional domain
|
|
|
405 This function returns the name of the font of face @var{face}, or
|
|
|
406 @code{nil} if it is unspecified. This is basically equivalent to
|
|
|
407 @code{(font-name (face-font @var{face}) @var{domain})} except that
|
|
|
408 it does not cause an error if @var{face}'s font is @code{nil}. (This
|
|
|
409 function is named @code{face-font} in FSF Emacs.)
|
|
|
410 @end defun
|
|
|
411
|
|
|
412 @defun face-underline-p face &optional locale
|
|
|
413 This function returns the underline property of face @var{face}.
|
|
|
414 @end defun
|
|
|
415
|
|
|
416 @defun face-foreground-instance face &optional domain
|
|
|
417 @defunx face-background-instance face &optional domain
|
|
|
418 These functions return the foreground (respectively, background) color
|
|
|
419 specifier of face @var{face}.
|
|
|
420 @xref{Colors}.
|
|
|
421 @end defun
|
|
|
422
|
|
|
423 @defun face-background-pixmap-instance face &optional domain
|
|
|
424 This function return the background-pixmap glyph object of face
|
|
|
425 @var{face}.
|
|
|
426 @end defun
|
|
|
427
|
|
|
428 @defun face-font-instance face &optional domain
|
|
|
429 This function returns the font specifier of face @var{face}.
|
|
|
430 @xref{Fonts}.
|
|
|
431 @end defun
|
|
|
432
|
|
|
433 @node Other Face Display Functions
|
|
|
434 @subsection Other Face Display Functions
|
|
|
435
|
|
|
436 @defun invert-face face &optional locale
|
|
|
437 Swap the foreground and background colors of face @var{face}. If the
|
|
|
438 face doesn't specify both foreground and background, then its foreground
|
|
|
439 and background are set to the default background and foreground.
|
|
|
440 @end defun
|
|
|
441
|
|
|
442 @defun face-equal face1 face2 &optional domain
|
|
|
443 This returns @code{t} if the faces @var{face1} and @var{face2} will
|
|
|
444 display in the same way. @var{domain} is as in
|
|
|
445 @code{face-property-instance}.
|
|
|
446 @end defun
|
|
|
447
|
|
|
448 @defun face-differs-from-default-p face &optional domain
|
|
|
449 This returns @code{t} if the face @var{face} displays differently from
|
|
|
450 the default face. @var{domain} is as in @code{face-property-instance}.
|
|
|
451 @end defun
|
|
|
452
|
|
|
453 @node Fonts
|
|
|
454 @section Fonts
|
|
|
455 @cindex fonts
|
|
|
456
|
|
|
457 This section describes how to work with font specifier and
|
|
|
458 font instance objects, which encapsulate fonts in the window system.
|
|
|
459
|
|
|
460 @menu
|
|
|
461 * Font Specifiers:: Specifying how a font will appear.
|
|
|
462 * Font Instances:: What a font specifier gets instanced as.
|
|
|
463 * Font Instance Names:: The name of a font instance.
|
|
|
464 * Font Instance Size:: The size of a font instance.
|
|
|
465 * Font Instance Characteristics:: Display characteristics of font instances.
|
|
|
466 * Font Convenience Functions:: Convenience functions that automatically
|
|
|
467 instance and retrieve the properties
|
|
|
468 of a font specifier.
|
|
|
469 @end menu
|
|
|
470
|
|
|
471 @node Font Specifiers
|
|
|
472 @subsection Font Specifiers
|
|
|
473
|
|
|
474 @defun font-specifier-p object
|
|
|
475 This predicate returns @code{t} if @var{object} is a font specifier, and
|
|
|
476 @code{nil} otherwise.
|
|
|
477 @end defun
|
|
|
478
|
|
|
479 @node Font Instances
|
|
|
480 @subsection Font Instances
|
|
|
481
|
|
|
482 @defun font-instance-p object
|
|
|
483 This predicate returns @code{t} if @var{object} is a font instance, and
|
|
|
484 @code{nil} otherwise.
|
|
|
485 @end defun
|
|
|
486
|
|
|
487 @defun make-font-instance name &optional device noerror
|
|
|
488 This function creates a new font-instance object of the specified name.
|
|
|
489 @var{device} specifies the device this object applies to and defaults to
|
|
|
490 the selected device. An error is signalled if the font is unknown or
|
|
|
491 cannot be allocated; however, if @var{noerror} is non-@code{nil},
|
|
|
492 @code{nil} is simply returned in this case.
|
|
|
493
|
|
|
494 The returned object is a normal, first-class lisp object. The way you
|
|
|
495 ``deallocate'' the font is the way you deallocate any other lisp object:
|
|
|
496 you drop all pointers to it and allow it to be garbage collected. When
|
|
|
497 these objects are GCed, the underlying X data is deallocated as well.
|
|
|
498 @end defun
|
|
|
499
|
|
|
500 @node Font Instance Names
|
|
|
501 @subsection Font Instance Names
|
|
|
502 @cindex font instance name
|
|
|
503 @cindex available fonts
|
|
|
504 @cindex fonts available
|
|
|
505
|
|
|
506 @defun list-fonts pattern &optional device
|
|
|
507 This function returns a list of font names matching the given pattern.
|
|
|
508 @var{device} specifies which device to search for names, and defaults to
|
|
|
509 the currently selected device.
|
|
|
510 @end defun
|
|
|
511
|
|
|
512 @defun font-instance-name font-instance
|
|
|
513 This function returns the name used to allocate @var{font-instance}.
|
|
|
514 @end defun
|
|
|
515
|
|
|
516 @defun font-instance-truename font-instance
|
|
|
517 This function returns the canonical name of the given font instance.
|
|
|
518 Font names are patterns which may match any number of fonts, of which
|
|
|
519 the first found is used. This returns an unambiguous name for that font
|
|
|
520 (but not necessarily its only unambiguous name).
|
|
|
521 @end defun
|
|
|
522
|
|
|
523 @node Font Instance Size
|
|
|
524 @subsection Font Instance Size
|
|
|
525 @cindex font instance size
|
|
|
526
|
|
|
527 @defun x-font-size font
|
|
|
528 This function returns the nominal size of the given font. This is done
|
|
|
529 by parsing its name, so it's likely to lose. X fonts can be specified
|
|
|
530 (by the user) in either pixels or 10ths of points, and this returns the
|
|
|
531 first one it finds, so you have to decide which units the returned value
|
|
|
532 is measured in yourself ...
|
|
|
533 @end defun
|
|
|
534
|
|
|
535 @defun x-find-larger-font font &optional device
|
|
|
536 This function loads a new, slightly larger version of the given font (or
|
|
|
537 font name). Returns the font if it succeeds, @code{nil} otherwise. If
|
|
|
538 scalable fonts are available, this returns a font which is 1 point
|
|
|
539 larger. Otherwise, it returns the next larger version of this font that
|
|
|
540 is defined.
|
|
|
541 @end defun
|
|
|
542
|
|
|
543 @defun x-find-smaller-font font &optional device
|
|
|
544 This function loads a new, slightly smaller version of the given font
|
|
|
545 (or font name). Returns the font if it succeeds, @code{nil} otherwise.
|
|
|
546 If scalable fonts are available, this returns a font which is 1 point
|
|
|
547 smaller. Otherwise, it returns the next smaller version of this font
|
|
|
548 that is defined.
|
|
|
549 @end defun
|
|
|
550
|
|
|
551 @node Font Instance Characteristics
|
|
|
552 @subsection Font Instance Characteristics
|
|
|
553 @cindex font instance characteristics
|
|
|
554 @cindex characteristics of font instances
|
|
|
555 @cindex bold
|
|
|
556 @cindex demibold
|
|
|
557 @cindex italic
|
|
|
558 @cindex oblique
|
|
|
559
|
|
|
560 @defun font-instance-properties font
|
|
|
561 This function returns the properties (an alist or @code{nil}) of
|
|
|
562 @var{font-instance}.
|
|
|
563 @end defun
|
|
|
564
|
|
|
565 @defun x-make-font-bold font &optional device
|
|
|
566 Given an X font specification, this attempts to make a ``bold'' font.
|
|
|
567 If it fails, it returns @code{nil}.
|
|
|
568 @end defun
|
|
|
569
|
|
|
570 @defun x-make-font-unbold font &optional device
|
|
|
571 Given an X font specification, this attempts to make a non-bold font.
|
|
|
572 If it fails, it returns @code{nil}.
|
|
|
573 @end defun
|
|
|
574
|
|
|
575 @defun x-make-font-italic font &optional device
|
|
|
576 Given an X font specification, this attempts to make an ``italic'' font.
|
|
|
577 If it fails, it returns @code{nil}.
|
|
|
578 @end defun
|
|
|
579
|
|
|
580 @defun x-make-font-unitalic font &optional device
|
|
|
581 Given an X font specification, this attempts to make a non-italic font.
|
|
|
582 If it fails, it returns @code{nil}.
|
|
|
583 @end defun
|
|
|
584
|
|
|
585 @defun x-make-font-bold-italic font &optional device
|
|
|
586 Given an X font specification, this attempts to make a ``bold-italic''
|
|
|
587 font. If it fails, it returns @code{nil}.
|
|
|
588 @end defun
|
|
|
589
|
|
|
590 @node Font Convenience Functions
|
|
|
591 @subsection Font Convenience Functions
|
|
|
592
|
|
|
593 @defun font-name font &optional domain
|
|
|
594 This function returns the name of the @var{font} in the specified
|
|
|
595 @var{domain}, if any. @var{font} should be a font specifier object and
|
|
|
596 @var{domain} is normally a window and defaults to the selected window if
|
|
|
597 omitted. This is equivalent to using @code{specifier-instance} and
|
|
|
598 applying @code{font-instance-name} to the result.
|
|
|
599 @end defun
|
|
|
600
|
|
|
601 @defun font-truename font &optional domain
|
|
|
602 This function returns the truename of the @var{font} in the specified
|
|
|
603 @var{domain}, if any. @var{font} should be a font specifier object and
|
|
|
604 @var{domain} is normally a window and defaults to the selected window if
|
|
|
605 omitted. This is equivalent to using @code{specifier-instance} and
|
|
|
606 applying @code{font-instance-truename} to the result.
|
|
|
607 @end defun
|
|
|
608
|
|
|
609 @defun font-properties font &optional domain
|
|
|
610 This function returns the properties of the @var{font} in the specified
|
|
|
611 @var{domain}, if any. @var{font} should be a font specifier object and
|
|
|
612 @var{domain} is normally a window and defaults to the selected window if
|
|
|
613 omitted. This is equivalent to using @code{specifier-instance} and
|
|
|
614 applying @code{font-instance-properties} to the result.
|
|
|
615 @end defun
|
|
|
616
|
|
|
617 @node Colors
|
|
|
618 @section Colors
|
|
|
619 @cindex colors
|
|
|
620
|
|
|
621 @menu
|
|
|
622 * Color Specifiers:: Specifying how a color will appear.
|
|
|
623 * Color Instances:: What a color specifier gets instanced as.
|
|
|
624 * Color Instance Properties:: Properties of color instances.
|
|
|
625 * Color Convenience Functions:: Convenience functions that automatically
|
|
|
626 instance and retrieve the properties
|
|
|
627 of a color specifier.
|
|
|
628 @end menu
|
|
|
629
|
|
|
630 @node Color Specifiers
|
|
|
631 @subsection Color Specifiers
|
|
|
632
|
|
|
633 @defun color-specifier-p object
|
|
|
634 This function returns non-@code{nil} if @var{object} is a color specifier.
|
|
|
635 @end defun
|
|
|
636
|
|
|
637 @node Color Instances
|
|
|
638 @subsection Color Instances
|
|
|
639 @cindex color instances
|
|
|
640
|
|
|
641 A @dfn{color-instance object} is an object describing the way a color
|
|
|
642 specifier is instanced in a particular domain. Functions such as
|
|
|
643 @code{face-background-instance} return a color-instance object. For
|
|
|
644 example,
|
|
|
645
|
|
|
646 @example
|
|
|
647 (face-background-instance 'default (next-window))
|
|
|
648 @result{} #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
|
|
|
649 @end example
|
|
|
650
|
|
|
651 The color-instance object returned describes the way the background
|
|
|
652 color of the @code{default} face is displayed in the next window after
|
|
|
653 the selected one.
|
|
|
654
|
|
|
655 @defun color-instance-p object
|
|
|
656 This function returns non-@code{nil} if @var{object} is a color-instance.
|
|
|
657 @end defun
|
|
|
658
|
|
|
659 @node Color Instance Properties
|
|
|
660 @subsection Color Instance Properties
|
|
|
661
|
|
|
662 @defun color-instance-name color-instance
|
|
|
663 This function returns the name used to allocate @var{color-instance}.
|
|
|
664 @end defun
|
|
|
665
|
|
|
666 @defun color-instance-rgb-components color-instance
|
|
|
667 This function returns a three element list containing the red, green,
|
|
|
668 and blue color components of @var{color-instance}.
|
|
|
669
|
|
|
670 @example
|
|
|
671 (color-instance-rgb-components
|
|
|
672 (face-background-instance 'default (next-window)))
|
|
|
673 @result{} (65535 58596 46517)
|
|
|
674 @end example
|
|
|
675 @end defun
|
|
|
676
|
|
|
677 @node Color Convenience Functions
|
|
|
678 @subsection Color Convenience Functions
|
|
|
679
|
|
|
680 @defun color-name color &optional domain
|
|
|
681 This function returns the name of the @var{color} in the specified
|
|
|
682 @var{domain}, if any. @var{color} should be a color specifier object
|
|
|
683 and @var{domain} is normally a window and defaults to the selected
|
|
|
684 window if omitted. This is equivalent to using
|
|
|
685 @code{specifier-instance} and applying @code{color-instance-name} to the
|
|
|
686 result.
|
|
|
687 @end defun
|
|
|
688
|
|
|
689 @defun color-rgb-components color &optional domain
|
|
|
690 This function returns the @sc{rgb} components of the @var{color} in the
|
|
|
691 specified @var{domain}, if any. @var{color} should be a color specifier
|
|
|
692 object and @var{domain} is normally a window and defaults to the
|
|
|
693 selected window if omitted. This is equivalent to using
|
|
|
694 @code{specifier-instance} and applying
|
|
|
695 @code{color-instance-rgb-components} to the result.
|
|
|
696
|
|
|
697 @example
|
|
|
698 (color-rgb-components (face-background 'default (next-window)))
|
|
|
699 @result{} (65535 58596 46517)
|
|
|
700 @end example
|
|
|
701 @end defun
|
