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