Mercurial > emacs
comparison doc/lispref/display.texi @ 100978:d14fcdc20167
(Attribute Functions): Note that a function value :height is relative,
and that compatibility functions work by calling set-face-attribute.
(Displaying Faces): Reorder list in order of increasing priority.
(Face Remapping): New node. Content moved here from Displaying Faces.
(Glyphs): Link to Face Functions.
author | Chong Yidong <cyd@stupidchicken.com> |
---|---|
date | Thu, 08 Jan 2009 11:46:04 +0000 |
parents | cb5d2387102c |
children | 80faf5dfb6cd |
comparison
equal
deleted
inserted
replaced
100977:26225b02af03 | 100978:d14fcdc20167 |
---|---|
1784 @menu | 1784 @menu |
1785 * Defining Faces:: How to define a face with @code{defface}. | 1785 * Defining Faces:: How to define a face with @code{defface}. |
1786 * Face Attributes:: What is in a face? | 1786 * Face Attributes:: What is in a face? |
1787 * Attribute Functions:: Functions to examine and set face attributes. | 1787 * Attribute Functions:: Functions to examine and set face attributes. |
1788 * Displaying Faces:: How Emacs combines the faces specified for a character. | 1788 * Displaying Faces:: How Emacs combines the faces specified for a character. |
1789 * Face Remapping:: Remapping faces to alternative definitions. | |
1789 * Font Selection:: Finding the best available font for a face. | 1790 * Font Selection:: Finding the best available font for a face. |
1790 * Face Functions:: How to define and examine faces. | 1791 * Face Functions:: How to define and examine faces. |
1791 * Auto Faces:: Hook for automatic face assignment. | 1792 * Auto Faces:: Hook for automatic face assignment. |
1792 * Font Lookup:: Looking up the names of available fonts | 1793 * Font Lookup:: Looking up the names of available fonts |
1793 and information about them. | 1794 and information about them. |
2197 value of the face attribute @var{attribute}, is relative. This means | 2198 value of the face attribute @var{attribute}, is relative. This means |
2198 it would modify, rather than completely override, any value that comes | 2199 it would modify, rather than completely override, any value that comes |
2199 from a subsequent face in the face list or that is inherited from | 2200 from a subsequent face in the face list or that is inherited from |
2200 another face. | 2201 another face. |
2201 | 2202 |
2202 @code{unspecified} is a relative value for all attributes. | 2203 @code{unspecified} is a relative value for all attributes. For |
2203 For @code{:height}, floating point values are also relative. | 2204 @code{:height}, floating point and function values are also relative. |
2204 | 2205 |
2205 For example: | 2206 For example: |
2206 | 2207 |
2207 @example | 2208 @example |
2208 (face-attribute-relative-p :height 2.0) | 2209 (face-attribute-relative-p :height 2.0) |
2225 @var{value2}; otherwise, if @var{value1} is an absolute value for the | 2226 @var{value2}; otherwise, if @var{value1} is an absolute value for the |
2226 face attribute @var{attribute}, returns @var{value1} unchanged. | 2227 face attribute @var{attribute}, returns @var{value1} unchanged. |
2227 @end defun | 2228 @end defun |
2228 | 2229 |
2229 The following functions provide compatibility with Emacs 20 and | 2230 The following functions provide compatibility with Emacs 20 and |
2230 below. They use values of @code{t} and @code{nil} for @var{frame} | 2231 below. They work by calling @code{set-face-attribute}. Values of |
2232 @code{t} and @code{nil} for their @var{frame} argument are handled | |
2231 just like @code{set-face-attribute} and @code{face-attribute}. | 2233 just like @code{set-face-attribute} and @code{face-attribute}. |
2232 | 2234 |
2233 @defun set-face-foreground face color &optional frame | 2235 @defun set-face-foreground face color &optional frame |
2234 @defunx set-face-background face color &optional frame | 2236 @defunx set-face-background face color &optional frame |
2235 These functions set the foreground (or background, respectively) color | 2237 These functions set the @code{:foreground} attribute (or |
2236 of face @var{face} to @var{color}. The argument @var{color} should be | 2238 @code{:background} attribute, respectively) of @var{face} to |
2237 a string, the name of a color. | 2239 @var{color}. |
2238 @end defun | 2240 @end defun |
2239 | 2241 |
2240 @defun set-face-stipple face pattern &optional frame | 2242 @defun set-face-stipple face pattern &optional frame |
2241 This function sets the background stipple pattern of face @var{face} | 2243 This function sets the @code{:stipple} attribute of @var{face} to |
2242 to @var{pattern}. The argument PATTERN should be the name of a | 2244 @var{pattern}. |
2243 stipple pattern defined by the X server, or actual bitmap data | |
2244 (@pxref{Face Attributes}), or `nil' meaning don't use stipple. | |
2245 @end defun | 2245 @end defun |
2246 | 2246 |
2247 @defun set-face-font face font &optional frame | 2247 @defun set-face-font face font &optional frame |
2248 This function sets the font of face @var{face}. This actually sets | 2248 This function sets the @code{:font} attribute of @var{face} to |
2249 the attributes @code{:family}, @code{:width}, @code{:height}, | |
2250 @code{:weight}, and @code{:slant} according to the font name | |
2251 @var{font}. | 2249 @var{font}. |
2252 @end defun | 2250 @end defun |
2253 | 2251 |
2254 @defun set-face-bold-p face bold-p &optional frame | 2252 @defun set-face-bold-p face bold-p &optional frame |
2255 This function specifies whether @var{face} should be bold. If | 2253 This function sets the @code{:weight} attribute of @var{face} to |
2256 @var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no. | 2254 @var{normal} if @var{bold-p} is @code{nil}, and to @var{bold} |
2257 This actually sets the @code{:weight} attribute. | 2255 otherwise. |
2258 @end defun | 2256 @end defun |
2259 | 2257 |
2260 @defun set-face-italic-p face italic-p &optional frame | 2258 @defun set-face-italic-p face italic-p &optional frame |
2261 This function specifies whether @var{face} should be italic. If | 2259 This function sets the @code{:slant} attribute of @var{face} to |
2262 @var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no. | 2260 @var{normal} if @var{italic-p} is @code{nil}, and to @var{italic} |
2263 This actually sets the @code{:slant} attribute. | 2261 otherwise. |
2264 @end defun | 2262 @end defun |
2265 | 2263 |
2266 @defun set-face-underline-p face underline &optional frame | 2264 @defun set-face-underline-p face underline &optional frame |
2267 This function sets the underline attribute of face @var{face}. | 2265 This function sets the @code{:underline} attribute of @var{face} to |
2268 Non-@code{nil} means do underline; @code{nil} means don't. | 2266 @var{underline}. |
2269 If @var{underline} is a string, underline with that color. | |
2270 @end defun | 2267 @end defun |
2271 | 2268 |
2272 @defun set-face-inverse-video-p face inverse-video-p &optional frame | 2269 @defun set-face-inverse-video-p face inverse-video-p &optional frame |
2273 This function sets the @code{:inverse-video} attribute of face | 2270 This function sets the @code{:inverse-video} attribute of @var{face} |
2274 @var{face}. | 2271 to @var{inverse-video-p}. |
2275 @end defun | 2272 @end defun |
2276 | 2273 |
2277 @defun invert-face face &optional frame | 2274 @defun invert-face face &optional frame |
2278 This function swaps the foreground and background colors of face | 2275 This function swaps the foreground and background colors of face |
2279 @var{face}. | 2276 @var{face}. |
2280 @end defun | 2277 @end defun |
2281 | 2278 |
2282 These functions examine the attributes of a face. If you don't | 2279 The following functions examine the attributes of a face. If you |
2283 specify @var{frame}, they refer to the selected frame; @code{t} refers | 2280 don't specify @var{frame}, they refer to the selected frame; @code{t} |
2284 to the default data for new frames. They return the symbol | 2281 refers to the default data for new frames. They return the symbol |
2285 @code{unspecified} if the face doesn't define any value for that | 2282 @code{unspecified} if the face doesn't define any value for that |
2286 attribute. | 2283 attribute. |
2287 | 2284 |
2288 @defun face-foreground face &optional frame inherit | 2285 @defun face-foreground face &optional frame inherit |
2289 @defunx face-background face &optional frame inherit | 2286 @defunx face-background face &optional frame inherit |
2314 @defun face-font face &optional frame | 2311 @defun face-font face &optional frame |
2315 This function returns the name of the font of face @var{face}. | 2312 This function returns the name of the font of face @var{face}. |
2316 @end defun | 2313 @end defun |
2317 | 2314 |
2318 @defun face-bold-p face &optional frame | 2315 @defun face-bold-p face &optional frame |
2319 This function returns @code{t} if @var{face} is bold---that is, if it is | 2316 This function returns a non-@code{nil} value if the @code{:weight} |
2320 bolder than normal. It returns @code{nil} otherwise. | 2317 attribute of @var{face} is bolder than normal (i.e., one of |
2318 @code{semi-bold}, @code{bold}, @code{extra-bold}, or | |
2319 @code{ultra-bold}). Otherwise, it returns @code{nil}. | |
2321 @end defun | 2320 @end defun |
2322 | 2321 |
2323 @defun face-italic-p face &optional frame | 2322 @defun face-italic-p face &optional frame |
2324 This function returns @code{t} if @var{face} is italic or oblique, | 2323 This function returns a non-@code{nil} value if the @code{:slant} |
2324 attribute of @var{face} is @code{italic} or @code{oblique}, and | |
2325 @code{nil} otherwise. | 2325 @code{nil} otherwise. |
2326 @end defun | 2326 @end defun |
2327 | 2327 |
2328 @defun face-underline-p face &optional frame | 2328 @defun face-underline-p face &optional frame |
2329 This function returns the @code{:underline} attribute of face @var{face}. | 2329 This function returns the @code{:underline} attribute of face @var{face}. |
2334 @end defun | 2334 @end defun |
2335 | 2335 |
2336 @node Displaying Faces | 2336 @node Displaying Faces |
2337 @subsection Displaying Faces | 2337 @subsection Displaying Faces |
2338 | 2338 |
2339 Here are the ways to specify which faces to use for display of text: | 2339 Here is how Emacs determines the face to use for displaying any |
2340 given piece of text: | |
2340 | 2341 |
2341 @itemize @bullet | 2342 @itemize @bullet |
2342 @item | 2343 @item |
2343 With defaults. The @code{default} face is used as the ultimate | 2344 If the text consists of a special glyph, the glyph can specify a |
2344 default for all text. (In Emacs 19 and 20, the @code{default} | 2345 particular face. @xref{Glyphs}. |
2345 face is used only when no other face is specified.) | |
2346 | 2346 |
2347 @item | 2347 @item |
2348 For a mode line or header line, the face @code{mode-line} or | 2348 If the text lies within an active region, Emacs highlights it using |
2349 @code{mode-line-inactive}, or @code{header-line}, is merged in just | 2349 the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs |
2350 before @code{default}. | 2350 Manual}. |
2351 | 2351 |
2352 @item | 2352 @item |
2353 With text properties. A character can have a @code{face} property; if | 2353 If the text lies within an overlay with a non-@code{nil} @code{face} |
2354 so, the faces and face attributes specified there apply. @xref{Special | 2354 property, Emacs applies the face or face attributes specified by that |
2355 Properties}. | 2355 property. If the overlay has a @code{mouse-face} property and the |
2356 | 2356 mouse is ``near enough'' to the overlay, Emacs applies the face or |
2357 If the character has a @code{mouse-face} property, that is used instead | 2357 face attributes specified by the @code{mouse-face} property instead. |
2358 of the @code{face} property when the mouse is ``near enough'' to the | 2358 @xref{Overlay Properties}. |
2359 character. | 2359 |
2360 When multiple overlays cover one character, an overlay with higher | |
2361 priority overrides those with lower priority. @xref{Overlays}. | |
2360 | 2362 |
2361 @item | 2363 @item |
2362 With overlays. An overlay can have @code{face} and @code{mouse-face} | 2364 If the text contains a @code{face} or @code{mouse-face} property, |
2363 properties too; they apply to all the text covered by the overlay. | 2365 Emacs applies the specified faces and face attributes. @xref{Special |
2366 Properties}. (This is how Font Lock mode faces are applied. | |
2367 @xref{Font Lock Mode}.) | |
2364 | 2368 |
2365 @item | 2369 @item |
2366 With a region that is active. In Transient Mark mode, the region is | 2370 If the text lies within the mode line of the selected window, Emacs |
2367 highlighted with the face @code{region} (@pxref{Standard Faces,,, | 2371 applies the @code{mode-line} face. For the mode line of a |
2368 emacs, The GNU Emacs Manual}). | 2372 non-selected window, Emacs applies the @code{mode-line-inactive} face. |
2373 For a header line, Emacs applies the @code{header-line} face. | |
2369 | 2374 |
2370 @item | 2375 @item |
2371 With special glyphs. Each glyph can specify a particular face | 2376 If any given attribute has not been specified during the preceding |
2372 number. @xref{Glyphs}. | 2377 steps, Emacs applies the attribute of the @code{default} face. |
2373 @end itemize | 2378 @end itemize |
2374 | 2379 |
2375 If these various sources together specify more than one face for a | 2380 If these various sources together specify more than one face for a |
2376 particular character, Emacs merges the attributes of the various faces | 2381 particular character, Emacs merges the attributes of the various faces |
2377 specified. For each attribute, Emacs tries first the face of any | 2382 specified. For each attribute, Emacs tries using the above order |
2378 special glyph; then the face for region highlighting, if appropriate; | 2383 (i.e., first the face of any special glyph; then the face for region |
2379 then the faces specified by overlays, followed by those specified by | 2384 highlighting, if appropriate; then faces specified by overlays, then |
2380 text properties, then the @code{mode-line} or | 2385 faces specified by text properties, then the @code{mode-line} or |
2381 @code{mode-line-inactive} or @code{header-line} face (if in a mode | 2386 @code{mode-line-inactive} or @code{header-line} face, if appropriate, |
2382 line or a header line), and last the @code{default} face. | 2387 and finally the @code{default} face). |
2383 | 2388 |
2384 When multiple overlays cover one character, an overlay with higher | 2389 @node Face Remapping |
2385 priority overrides those with lower priority. @xref{Overlays}. | 2390 @subsection Face Remapping |
2391 | |
2392 The variable @code{face-remapping-alist} is used for buffer-local or | |
2393 global changes in the appearance of a face. For instance, it can be | |
2394 used to make the @code{default} face a variable-pitch face within a | |
2395 particular buffer. | |
2386 | 2396 |
2387 @defvar face-remapping-alist | 2397 @defvar face-remapping-alist |
2388 This variable is used for buffer-local or global changes in the | 2398 An alist whose elements have the form @code{(@var{face} |
2389 appearance of a face, for instance making the @code{default} face a | 2399 @var{remapping...})}. This causes Emacs to display text using the |
2390 variable-pitch face in a particular buffer. | 2400 face @var{face} using @var{remapping...} instead of @var{face}'s |
2391 | 2401 ordinary definition. @var{remapping...} may be any face specification |
2392 Its value should be an alist, whose elements have the form | 2402 suitable for a @code{face} text property: either a face name, or a |
2393 @code{(@var{face} @var{remapping...})}. This causes Emacs to display | 2403 property list of attribute/value pairs. @xref{Special Properties}. |
2394 text using the face @var{face} using @var{remapping...} instead of | 2404 |
2395 @var{face}'s global definition. @var{remapping...} may be any face | 2405 If @code{face-remapping-alist} is buffer-local, its local value takes |
2396 specification suitable for a @code{face} text property, usually a face | 2406 effect only within that buffer. |
2397 name, but also perhaps a property list of face attribute/value pairs. | |
2398 @xref{Special Properties}. | |
2399 | |
2400 To affect display only in a single buffer, | |
2401 @code{face-remapping-alist} should be made buffer-local. | |
2402 | 2407 |
2403 Two points bear emphasizing: | 2408 Two points bear emphasizing: |
2404 | 2409 |
2405 @enumerate | 2410 @enumerate |
2406 @item | 2411 @item |
2424 @noindent | 2429 @noindent |
2425 then the new definition of the @code{mode-line} face inherits from the | 2430 then the new definition of the @code{mode-line} face inherits from the |
2426 @code{italic} face, and the @emph{normal} (non-remapped) definition of | 2431 @code{italic} face, and the @emph{normal} (non-remapped) definition of |
2427 @code{mode-line} face. | 2432 @code{mode-line} face. |
2428 @end enumerate | 2433 @end enumerate |
2434 @end defvar | |
2429 | 2435 |
2430 A typical use of the @code{face-remapping-alist} is to change a | 2436 A typical use of the @code{face-remapping-alist} is to change a |
2431 buffer's @code{default} face; for example, the following changes a | 2437 buffer's @code{default} face; for example, the following changes a |
2432 buffer's @code{default} face to use the @code{variable-pitch} face, | 2438 buffer's @code{default} face to use the @code{variable-pitch} face, |
2433 with the height doubled: | 2439 with the height doubled: |
2435 @example | 2441 @example |
2436 (set (make-local-variable 'face-remapping-alist) | 2442 (set (make-local-variable 'face-remapping-alist) |
2437 '((default variable-pitch :height 2.0))) | 2443 '((default variable-pitch :height 2.0))) |
2438 @end example | 2444 @end example |
2439 | 2445 |
2440 @end defvar | 2446 The following functions implement a higher-level interface to |
2441 | |
2442 @noindent | |
2443 The following functions implement a somewhat higher-level interface to | |
2444 @code{face-remapping-alist}, making it easier to use | 2447 @code{face-remapping-alist}, making it easier to use |
2445 ``cooperatively''. They are mainly intended for buffer-local use, and | 2448 ``cooperatively''. They are mainly intended for buffer-local use, and |
2446 so all make @code{face-remapping-alist} variable buffer-local as a | 2449 so all make @code{face-remapping-alist} variable buffer-local as a |
2447 side-effect. | 2450 side-effect. They use entries in @code{face-remapping-alist} which |
2448 | 2451 have the general form: |
2449 These functions use entries in @code{face-remapping-alist} which have | |
2450 the general form: | |
2451 | 2452 |
2452 @example | 2453 @example |
2453 (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) | 2454 (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) |
2454 @end example | 2455 @end example |
2455 | 2456 |
5544 @end defun | 5545 @end defun |
5545 | 5546 |
5546 @defun glyph-face glyph | 5547 @defun glyph-face glyph |
5547 This function returns face of simple glyph code @var{glyph}, or | 5548 This function returns face of simple glyph code @var{glyph}, or |
5548 @code{nil} if @var{glyph} has the default face (face-id 0). | 5549 @code{nil} if @var{glyph} has the default face (face-id 0). |
5550 @xref{Face Functions}. | |
5549 @end defun | 5551 @end defun |
5550 | 5552 |
5551 On character terminals, you can set up a @dfn{glyph table} to define | 5553 On character terminals, you can set up a @dfn{glyph table} to define |
5552 the meaning of glyph codes (represented as small integers). | 5554 the meaning of glyph codes (represented as small integers). |
5553 | 5555 |