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