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