Mercurial > hg > xemacs-beta

comparison lisp/faces.el @ 3027:7efd3a9bbcfb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[xemacs-hg @ 2005-10-25 11:28:23 by ben] support :inherit in cus-face and face cus-face.el, faces.el: Provide a basic implementation of the `inherit' property for faces and the :inherit property in custom. Use the new `specifier-instantiator' function. Update the documentation for various places in faces.el. 'foo -> `foo'.
author ben
date Tue, 25 Oct 2005 11:28:24 +0000
parents 2f2d12f4f93a
children ad2f4ae9895b
comparison
equal deleted inserted replaced
3026:beef0f850624 3027:7efd3a9bbcfb
1 ;;; faces.el --- Lisp interface to the C "face" structure 1 ;;; faces.el --- Lisp interface to the C "face" structure
2 2
3 ;; Copyright (C) 1992-4, 1997 Free Software Foundation, Inc. 3 ;; Copyright (C) 1992-4, 1997 Free Software Foundation, Inc.
4 ;; Copyright (C) 1995 Board of Trustees, University of Illinois 4 ;; Copyright (C) 1995 Board of Trustees, University of Illinois
5 ;; Copyright (C) 1995, 1996, 2002 Ben Wing 5 ;; Copyright (C) 1995, 1996, 2002, 2005 Ben Wing
6 6
7 ;; Author: Ben Wing <ben@xemacs.org> 7 ;; Author: Ben Wing <ben@xemacs.org>
8 ;; Keywords: faces, internal, dumped 8 ;; Keywords: faces, internal, dumped
9 9
10 ;; This file is part of XEmacs. 10 ;; This file is part of XEmacs.
94 "A list of the built-in face properties that are specifiers.") 94 "A list of the built-in face properties that are specifiers.")
95 95
96 (defun face-property (face property &optional locale tag-set exact-p) 96 (defun face-property (face property &optional locale tag-set exact-p)
97 "Return FACE's value of the given PROPERTY. 97 "Return FACE's value of the given PROPERTY.
98 98
99 NOTE: If you are looking for the \"value\" of a built-in face property
100 (`foreground', `background', `font', `background-pixmap', etc.), you
101 are probably better off calling `face-property-instance'. The return
102 value of `face-property' for built-in properties describes the original
103 specification used to determine the face property, which may be nil,
104 a list of instantiators, or something else that is unexpected. For
105 example, if you ask for a face property in a particular buffer (by
106 specifying a buffer for LOCALE), you will get a non-nil return value
107 only if a buffer-local specification for that particular buffer had
108 previously been given.
109
110 For a full list of built-in property names and their semantics, see
111 `set-face-property'.
112
99 If LOCALE is omitted, the FACE's actual value for PROPERTY will be 113 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
100 returned. For built-in properties, this will be a specifier object 114 returned. In this case, this function appears to behave rather
101 of a type appropriate to the property (e.g. a font or color 115 differently depending on whether PROPERTY is a built-in face property of
102 specifier). For other properties, this could be anything. 116 a user-defined face property. This is because the most basic value of a
103 117 user-defined property is simply whatever was set using
104 If LOCALE is supplied, then instead of returning the actual value, 118 `set-face-property', but for a built-in property it's always a specifier,
105 the specification(s) for the given locale or locale type will 119 which is an abstract object encapsulating all the specifications for that
106 be returned. This will only work if the actual value of 120 particular property.
107 PROPERTY is a specifier (this will always be the case for built-in 121
108 properties, but not or not may apply to user-defined properties). 122 LOCALE, if supplied, will generally be a buffer, frame or
109 If the actual value of PROPERTY is not a specifier, this value 123 `global' (for the global value), but there are other possibilities -- see
110 will simply be returned regardless of LOCALE. 124 the following paragraph. This mostly applies to built-in properties. In
125 this case, the return value will not be a specifier object but the
126 specification(s) for the given locale or locale type will be returned
127 (equivalent to calling `specifier-specs' on the specifier).
128 (Technically, the same thing happens if the basic value of a user-
129 defined property is a specifier, although this usage is rare.)
111 130
112 The return value will be a list of instantiators (e.g. strings 131 The return value will be a list of instantiators (e.g. strings
113 specifying a font or color name), or a list of specifications, each 132 specifying a font or color name), or a list of specifications, each
114 of which is a cons of a locale and a list of instantiators. 133 of which is a cons of a locale and a list of instantiators.
115 Specifically, if LOCALE is a particular locale (a buffer, window, 134 Specifically, if LOCALE is a particular locale (a buffer, window,
116 frame, device, or 'global), a list of instantiators for that locale 135 frame, device, or `global'), a list of instantiators for that locale
117 will be returned. Otherwise, if LOCALE is a locale type (one of 136 will be returned. Otherwise, if LOCALE is a locale type (one of
118 the symbols 'buffer, 'window, 'frame, or 'device), the specifications 137 the symbols `buffer', `window', `frame', or `device'), the specifications
119 for all locales of that type will be returned. Finally, if LOCALE is 138 for all locales of that type will be returned. Finally, if LOCALE is
120 'all, the specifications for all locales of all types will be returned. 139 `all', the specifications for all locales of all types will be returned.
121 140
122 The specifications in a specifier determine what the value of 141 The specifications in a specifier determine what the value of
123 PROPERTY will be in a particular \"domain\" or set of circumstances, 142 PROPERTY will be in a particular \"domain\" or set of circumstances,
124 which is typically a particular Emacs window along with the buffer 143 which is typically a particular Emacs window -- which in turn defines
125 it contains and the frame and device it lies within. The value is 144 a buffer (the buffer in the window), a frame (the frame that the window
145 is in), and a device (the device that the frame is in). The value is
126 derived from the instantiator associated with the most specific 146 derived from the instantiator associated with the most specific
127 locale (in the order buffer, window, frame, device, and 'global) 147 locale (in the order buffer, window, frame, device, and `global')
128 that matches the domain in question. In other words, given a domain 148 that matches the domain in question. In other words, given a domain
129 (i.e. an Emacs window, usually), the specifier for PROPERTY will 149 (i.e. an Emacs window, usually), the specifier for PROPERTY will
130 first be searched for a specification whose locale is the buffer 150 first be searched for a specification whose locale is the buffer
131 contained within that window; then for a specification whose locale 151 contained within that window; then for a specification whose locale
132 is the window itself; then for a specification whose locale is the 152 is the window itself; then for a specification whose locale is the
133 frame that the window is contained within; etc. The first 153 frame that the window is contained within; etc. The first
134 instantiator that is valid for the domain (usually this means that 154 instantiator that is valid for the domain (usually this means that
135 the instantiator is recognized by the device [i.e. MS Windows, the X 155 the instantiator is recognized by the device [i.e. MS Windows, the X
136 server or TTY device] that the domain is on. The function 156 server or TTY device]) will be \"instantiated\", which generates
137 `face-property-instance' actually does all this, and is used to 157 a Lisp object encapsulating the original instantiator and the underlying
138 determine how to display the face. 158 window-system object describing the property. The function
139 159 `face-property-instance' actually does all this."
140 See `set-face-property' for the built-in property-names."
141 160
142 (setq face (get-face face)) 161 (setq face (get-face face))
143 (let ((value (get face property))) 162 (let ((value (get face property)))
144 (if (and locale 163 (if (and locale
145 (or (memq property built-in-face-specifiers) 164 (or (memq property built-in-face-specifiers)
152 (setq face (get-face face)) 171 (setq face (get-face face))
153 (let ((specifier (get face property))) 172 (let ((specifier (get face property)))
154 ;; if a user-property does not have a specifier but a 173 ;; if a user-property does not have a specifier but a
155 ;; locale was specified, put a specifier there. 174 ;; locale was specified, put a specifier there.
156 ;; If there was already a value there, convert it to a 175 ;; If there was already a value there, convert it to a
157 ;; specifier with the value as its 'global instantiator. 176 ;; specifier with the value as its `global' instantiator.
158 (unless (specifierp specifier) 177 (unless (specifierp specifier)
159 (let ((new-specifier (make-specifier 'generic))) 178 (let ((new-specifier (make-specifier 'generic)))
160 (if (or (not (null specifier)) 179 (if (or (not (null specifier))
161 ;; make sure the nil returned from `get' wasn't 180 ;; make sure the nil returned from `get' wasn't
162 ;; actually the value of the property 181 ;; actually the value of the property
177 frame, or how the property appears in the same window if you 196 frame, or how the property appears in the same window if you
178 switch to another buffer in that window; and in those cases, 197 switch to another buffer in that window; and in those cases,
179 the returned instance would be different. 198 the returned instance would be different.
180 199
181 The returned instance will typically be a color-instance, 200 The returned instance will typically be a color-instance,
182 font-instance, or pixmap-instance object, and you can query 201 font-instance, or image-instance object, and you can query
183 it using the appropriate object-specific functions. For example, 202 it using the appropriate object-specific functions. For example,
184 you could use `color-instance-rgb-components' to find out the 203 you could use `color-instance-rgb-components' to find out the
185 RGB (red, green, and blue) components of how the 'background 204 RGB (red, green, and blue) components of how the `background'
186 property of the 'highlight face is displayed in a particular 205 property of the `highlight' face is displayed in a particular
187 window. The results might be different from the results 206 window. The results might be different from the results
188 you would get for another window (perhaps the user 207 you would get for another window (perhaps the user
189 specified a different color for the frame that window is on; 208 specified a different color for the frame that window is on;
190 or perhaps the same color was specified but the window is 209 or perhaps the same color was specified but the window is
191 on a different X server, and that X server has different RGB 210 on a different X server, and that X server has different RGB
263 this property can be supplied in many different ways: 282 this property can be supplied in many different ways:
264 283
265 -- If VALUE is a simple instantiator (e.g. a string naming a font or 284 -- If VALUE is a simple instantiator (e.g. a string naming a font or
266 color) or a list of instantiators, then the instantiator(s) will 285 color) or a list of instantiators, then the instantiator(s) will
267 be added as a specification of the property for the given LOCALE 286 be added as a specification of the property for the given LOCALE
268 (which defaults to 'global if omitted). 287 (which defaults to `global' if omitted).
269 -- If VALUE is a list of specifications (each of which is a cons of 288 -- If VALUE is a list of specifications (each of which is a cons of
270 a locale and a list of instantiators), then LOCALE must be nil 289 a locale and a list of instantiators), then LOCALE must be nil
271 (it does not make sense to explicitly specify a locale in this 290 (it does not make sense to explicitly specify a locale in this
272 case), and specifications will be added as given. 291 case), and specifications will be added as given.
273 -- If VALUE is a specifier (as would be returned by `face-property' 292 -- If VALUE is a specifier (as would be returned by `face-property'
275 specifications in the specifier will be added to the property. 294 specifications in the specifier will be added to the property.
276 In this case, the function is really equivalent to 295 In this case, the function is really equivalent to
277 `copy-specifier' and LOCALE has the same semantics (if it is 296 `copy-specifier' and LOCALE has the same semantics (if it is
278 a particular locale, the specification for the locale will be 297 a particular locale, the specification for the locale will be
279 copied; if a locale type, specifications for all locales of 298 copied; if a locale type, specifications for all locales of
280 that type will be copied; if nil or 'all, then all 299 that type will be copied; if nil or `all', then all
281 specifications will be copied). 300 specifications will be copied).
282 301
283 HOW-TO-ADD should be either nil or one of the symbols 'prepend, 302 HOW-TO-ADD should be either nil or one of the symbols `prepend',
284 'append, 'remove-tag-set-prepend, 'remove-tag-set-append, 'remove-locale, 303 `append', `remove-tag-set-prepend', `remove-tag-set-append', `remove-locale',
285 'remove-locale-type, or 'remove-all. See `copy-specifier' and 304 `remove-locale-type', or `remove-all'. See `copy-specifier' and
286 `add-spec-to-specifier' for a description of what each of 305 `add-spec-to-specifier' for a description of what each of
287 these means. Most of the time, you do not need to worry about 306 these means. Most of the time, you do not need to worry about
288 this argument; the default behavior usually is fine. 307 this argument; the default behavior usually is fine.
289 308
290 In general, it is OK to pass an instance object (e.g. as returned 309 In general, it is OK to pass an instance object (e.g. as returned
291 by `face-property-instance') as an instantiator in place of 310 by `face-property-instance') as an instantiator in place of
292 an actual instantiator. In such a case, the instantiator used 311 an actual instantiator. In such a case, the instantiator used
293 to create that instance object will be used (for example, if 312 to create that instance object will be used (for example, if
294 you set a font-instance object as the value of the 'font 313 you set a font-instance object as the value of the `font'
295 property, then the font name used to create that object will 314 property, then the font name used to create that object will
296 be used instead). If some cases, however, doing this 315 be used instead). If some cases, however, doing this
297 conversion does not make sense, and this will be noted in 316 conversion does not make sense, and this will be noted in
298 the documentation for particular types of instance objects. 317 the documentation for particular types of instance objects.
299 318
300 If PROPERTY is not a built-in property, then this function will 319 If PROPERTY is not a built-in property, then this function will
301 simply set its value if LOCALE is nil. However, if LOCALE is 320 simply set its value if LOCALE is nil. However, if LOCALE is
302 given, then this function will attempt to add VALUE as the 321 given, then this function will attempt to add VALUE as the
303 instantiator for the given LOCALE, using `add-spec-to-specifier'. 322 instantiator for the given LOCALE, using `add-spec-to-specifier'.
304 If the value of the property is not a specifier, it will 323 If the value of the property is not a specifier, it will
305 automatically be converted into a 'generic specifier. 324 automatically be converted into a `generic' specifier.
306 325
307 326
308 The following symbols have predefined meanings: 327 The following symbols have predefined meanings:
309 328
310 foreground The foreground color of the face. 329 foreground The foreground color of the face.
341 For valid instantiators, see `make-face-boolean-specifier'. 360 For valid instantiators, see `make-face-boolean-specifier'.
342 361
343 reverse Reverse the foreground and background colors. 362 reverse Reverse the foreground and background colors.
344 Only used by faces on TTY devices. 363 Only used by faces on TTY devices.
345 For valid instantiators, see `make-face-boolean-specifier'. 364 For valid instantiators, see `make-face-boolean-specifier'.
365
366 inherit Face name or face object from which to inherit attributes,
367 or a list of such elements. Attributes from inherited
368 faces are merged into the face like an underlying face
369 would be, with higher priority than underlying faces.
346 370
347 doc-string Description of what the face's normal use is. 371 doc-string Description of what the face's normal use is.
348 NOTE: This is not a specifier, unlike all 372 NOTE: This is not a specifier, unlike all
349 the other built-in properties, and cannot 373 the other built-in properties, and cannot
350 contain locale-specific values." 374 contain locale-specific values."
375 (remove-specifier (face-property face property) locale tag-set 399 (remove-specifier (face-property face property) locale tag-set
376 exact-p)))) 400 exact-p))))
377 401
378 (defun reset-face (face &optional locale tag-set exact-p) 402 (defun reset-face (face &optional locale tag-set exact-p)
379 "Clear all existing built-in specifications from FACE. 403 "Clear all existing built-in specifications from FACE.
380 This makes FACE inherit all its display properties from 'default. 404 This makes FACE inherit all its display properties from `default'.
381 WARNING: Be absolutely sure you want to do this!!! It is a dangerous 405 WARNING: Be absolutely sure you want to do this!!! It is a dangerous
382 operation and is not undoable. 406 operation and is not undoable.
383 407
384 The arguments LOCALE, TAG-SET and EXACT-P are the same as for 408 The arguments LOCALE, TAG-SET and EXACT-P are the same as for
385 `remove-specifier'." 409 `remove-specifier'."
393 This makes all properties of FACE inherit from PARENT." 417 This makes all properties of FACE inherit from PARENT."
394 (setq parent (get-face parent)) 418 (setq parent (get-face parent))
395 (mapcar (lambda (x) 419 (mapcar (lambda (x)
396 (set-face-property face x (vector parent) locale tag-set 420 (set-face-property face x (vector parent) locale tag-set
397 how-to-add)) 421 how-to-add))
398 (delq 'display-table 422 (set-difference built-in-face-specifiers
399 (delq 'background-pixmap 423 '(display-table background-pixmap inherit)))
400 (copy-sequence built-in-face-specifiers))))
401 (set-face-background-pixmap face (vector 'inherit ':face parent) 424 (set-face-background-pixmap face (vector 'inherit ':face parent)
402 locale tag-set how-to-add) 425 locale tag-set how-to-add)
403 nil) 426 nil)
404 427
405 (defun face-doc-string (face) 428 (defun face-doc-string (face)
411 (interactive (face-interactive "doc-string")) 434 (interactive (face-interactive "doc-string"))
412 (set-face-property face 'doc-string doc-string)) 435 (set-face-property face 'doc-string doc-string))
413 436
414 (defun face-font-name (face &optional domain charset) 437 (defun face-font-name (face &optional domain charset)
415 "Return the font name of FACE in DOMAIN, or nil if it is unspecified. 438 "Return the font name of FACE in DOMAIN, or nil if it is unspecified.
416 DOMAIN is as in `face-font-instance'." 439 DOMAIN is as in `face-font-instance'.
440
441 Font names are strings, as described in `make-font-specifier'."
417 (let ((f (face-font-instance face domain charset))) 442 (let ((f (face-font-instance face domain charset)))
418 (and f (font-instance-name f)))) 443 (and f (font-instance-name f))))
419 444
420 (defun face-font (face &optional locale tag-set exact-p) 445 (defun face-font (face &optional locale tag-set exact-p)
421 "Return the font of FACE in LOCALE, or nil if it is unspecified. 446 "Return the font spec of FACE in LOCALE, or nil if it is unspecified.
447
448 NOTE: This returns a locale-specific specification, not any sort of value
449 corresponding to the actual font being used. If you want to know the
450 actual font used in a particular domain, use `face-font-instance', or
451 `face-font-name' for its name (i.e. the instantiator used to create it).
422 452
423 FACE may be either a face object or a symbol representing a face. 453 FACE may be either a face object or a symbol representing a face.
424 454
425 LOCALE may be a locale (the instantiators for that particular locale 455 LOCALE may be a locale (the instantiators for that particular locale
426 will be returned), a locale type (the specifications for all locales 456 will be returned), a locale type (the specifications for all locales
427 of that type will be returned), 'all (all specifications will be 457 of that type will be returned), `all' (all specifications will be
428 returned), or nil (the actual specifier object will be returned). 458 returned), or nil (the actual specifier object will be returned).
429 459
430 See `face-property' for more information." 460 See `face-property' for more information."
431 (face-property face 'font locale tag-set exact-p)) 461 (face-property face 'font locale tag-set exact-p))
432 462
433 (defun face-font-instance (face &optional domain charset) 463 (defun face-font-instance (face &optional domain charset)
434 "Return the instance of FACE's font in DOMAIN. 464 "Return the instance of FACE's font in DOMAIN.
465
466 Return value will be a font instance object; query its properties using
467 `font-instance-name', `font-instance-height', `font-instance-width', etc.
435 468
436 FACE may be either a face object or a symbol representing a face. 469 FACE may be either a face object or a symbol representing a face.
437 470
438 Normally DOMAIN will be a window or nil (meaning the selected window), 471 Normally DOMAIN will be a window or nil (meaning the selected window),
439 and an instance object describing how the font appears in that 472 and an instance object describing how the font appears in that
452 FONT should be an instantiator (see `make-font-specifier'), a list of 485 FONT should be an instantiator (see `make-font-specifier'), a list of
453 instantiators, an alist of specifications (each mapping a 486 instantiators, an alist of specifications (each mapping a
454 locale to an instantiator list), or a font specifier object. 487 locale to an instantiator list), or a font specifier object.
455 488
456 If FONT is an alist, LOCALE must be omitted. If FONT is a 489 If FONT is an alist, LOCALE must be omitted. If FONT is a
457 specifier object, LOCALE can be a locale, a locale type, 'all, 490 specifier object, LOCALE can be a locale, a locale type, `all',
458 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE 491 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
459 specifies the locale under which the specified instantiator(s) 492 specifies the locale under which the specified instantiator(s)
460 will be added, and defaults to 'global. 493 will be added, and defaults to `global'.
461 494
462 See `set-face-property' for more information." 495 See `set-face-property' for more information."
463 (interactive (face-interactive "font")) 496 (interactive (face-interactive "font"))
464 (set-face-property face 'font font locale tag-set how-to-add)) 497 (set-face-property face 'font font locale tag-set how-to-add))
465 498
466 (defun face-foreground (face &optional locale tag-set exact-p) 499 (defun face-foreground (face &optional locale tag-set exact-p)
467 "Return the foreground of FACE in LOCALE, or nil if it is unspecified. 500 "Return the foreground spec of FACE in LOCALE, or nil if it is unspecified.
501
502 NOTE: This returns a locale-specific specification, not any sort of value
503 corresponding to the actual foreground being used. If you want to know the
504 actual foreground color used in a particular domain, use
505 `face-foreground-instance', or `face-foreground-name' for its name
506 \(i.e. the instantiator used to create it).
468 507
469 FACE may be either a face object or a symbol representing a face. 508 FACE may be either a face object or a symbol representing a face.
470 509
471 LOCALE may be a locale (the instantiators for that particular locale 510 LOCALE may be a locale (the instantiators for that particular locale
472 will be returned), a locale type (the specifications for all locales 511 will be returned), a locale type (the specifications for all locales
473 of that type will be returned), 'all (all specifications will be 512 of that type will be returned), `all' (all specifications will be
474 returned), or nil (the actual specifier object will be returned). 513 returned), or nil (the actual specifier object will be returned).
475 514
476 See `face-property' for more information." 515 See `face-property' for more information."
477 (face-property face 'foreground locale tag-set exact-p)) 516 (face-property face 'foreground locale tag-set exact-p))
478 517
479 (defun face-foreground-instance (face &optional domain default no-fallback) 518 (defun face-foreground-instance (face &optional domain default no-fallback)
480 "Return the instance of FACE's foreground in DOMAIN. 519 "Return the instance of FACE's foreground in DOMAIN.
520
521 Return value will be a color instance object; query its properties using
522 `color-instance-name' or `color-instance-rgb-properties'.
481 523
482 FACE may be either a face object or a symbol representing a face. 524 FACE may be either a face object or a symbol representing a face.
483 525
484 Normally DOMAIN will be a window or nil (meaning the selected window), 526 Normally DOMAIN will be a window or nil (meaning the selected window),
485 and an instance object describing how the foreground appears in that 527 and an instance object describing how the foreground appears in that
509 COLOR should be an instantiator (see `make-color-specifier'), a list of 551 COLOR should be an instantiator (see `make-color-specifier'), a list of
510 instantiators, an alist of specifications (each mapping a locale to 552 instantiators, an alist of specifications (each mapping a locale to
511 an instantiator list), or a color specifier object. 553 an instantiator list), or a color specifier object.
512 554
513 If COLOR is an alist, LOCALE must be omitted. If COLOR is a 555 If COLOR is an alist, LOCALE must be omitted. If COLOR is a
514 specifier object, LOCALE can be a locale, a locale type, 'all, 556 specifier object, LOCALE can be a locale, a locale type, `all',
515 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE 557 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
516 specifies the locale under which the specified instantiator(s) 558 specifies the locale under which the specified instantiator(s)
517 will be added, and defaults to 'global. 559 will be added, and defaults to `global'.
518 560
519 See `set-face-property' for more information." 561 See `set-face-property' for more information."
520 (interactive (face-interactive "foreground")) 562 (interactive (face-interactive "foreground"))
521 (set-face-property face 'foreground color locale tag-set how-to-add)) 563 (set-face-property face 'foreground color locale tag-set how-to-add))
522 564
523 (defun face-background (face &optional locale tag-set exact-p) 565 (defun face-background (face &optional locale tag-set exact-p)
524 "Return the background color of FACE in LOCALE, or nil if it is unspecified. 566 "Return the background color of FACE in LOCALE, or nil if it is unspecified.
525 567
568 NOTE: This returns a locale-specific specification, not any sort of value
569 corresponding to the actual background being used. If you want to know the
570 actual background color used in a particular domain, use
571 `face-background-instance', or `face-background-name' for its name
572 \(i.e. the instantiator used to create it).
573
526 FACE may be either a face object or a symbol representing a face. 574 FACE may be either a face object or a symbol representing a face.
527 575
528 LOCALE may be a locale (the instantiators for that particular locale 576 LOCALE may be a locale (the instantiators for that particular locale
529 will be returned), a locale type (the specifications for all locales 577 will be returned), a locale type (the specifications for all locales
530 of that type will be returned), 'all (all specifications will be 578 of that type will be returned), `all' (all specifications will be
531 returned), or nil (the actual specifier object will be returned). 579 returned), or nil (the actual specifier object will be returned).
532 580
533 See `face-property' for more information." 581 See `face-property' for more information."
534 (face-property face 'background locale tag-set exact-p)) 582 (face-property face 'background locale tag-set exact-p))
535 583
536 (defun face-background-instance (face &optional domain default no-fallback) 584 (defun face-background-instance (face &optional domain default no-fallback)
537 "Return the instance of FACE's background in DOMAIN. 585 "Return the instance of FACE's background in DOMAIN.
586
587 Return value will be a color instance object; query its properties using
588 `color-instance-name' or `color-instance-rgb-properties'.
538 589
539 FACE may be either a face object or a symbol representing a face. 590 FACE may be either a face object or a symbol representing a face.
540 591
541 Normally DOMAIN will be a window or nil (meaning the selected window), 592 Normally DOMAIN will be a window or nil (meaning the selected window),
542 and an instance object describing how the background appears in that 593 and an instance object describing how the background appears in that
566 COLOR should be an instantiator (see `make-color-specifier'), a list of 617 COLOR should be an instantiator (see `make-color-specifier'), a list of
567 instantiators, an alist of specifications (each mapping a locale to 618 instantiators, an alist of specifications (each mapping a locale to
568 an instantiator list), or a color specifier object. 619 an instantiator list), or a color specifier object.
569 620
570 If COLOR is an alist, LOCALE must be omitted. If COLOR is a 621 If COLOR is an alist, LOCALE must be omitted. If COLOR is a
571 specifier object, LOCALE can be a locale, a locale type, 'all, 622 specifier object, LOCALE can be a locale, a locale type, `all',
572 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE 623 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
573 specifies the locale under which the specified instantiator(s) 624 specifies the locale under which the specified instantiator(s)
574 will be added, and defaults to 'global. 625 will be added, and defaults to `global'.
575 626
576 See `set-face-property' for more information." 627 See `set-face-property' for more information."
577 (interactive (face-interactive "background")) 628 (interactive (face-interactive "background"))
578 (set-face-property face 'background color locale tag-set how-to-add)) 629 (set-face-property face 'background color locale tag-set how-to-add))
579 630
580 (defun face-background-pixmap (face &optional locale tag-set exact-p) 631 (defun face-background-pixmap (face &optional locale tag-set exact-p)
581 "Return the background pixmap of FACE in LOCALE, or nil if it is unspecified. 632 "Return the background pixmap spec of FACE in LOCALE, or nil if unspecified.
582 This property is only used on window system devices. 633 This property is only used on window system devices.
634
635 NOTE: This returns a locale-specific specification, not any sort of value
636 corresponding to the actual background pixmap being used. If you want to
637 know the actual background pixmap used in a particular domain, use
638 `face-background-pixmap-instance'.
583 639
584 FACE may be either a face object or a symbol representing a face. 640 FACE may be either a face object or a symbol representing a face.
585 641
586 LOCALE may be a locale (the instantiators for that particular locale 642 LOCALE may be a locale (the instantiators for that particular locale
587 will be returned), a locale type (the specifications for all locales 643 will be returned), a locale type (the specifications for all locales
588 of that type will be returned), 'all (all specifications will be 644 of that type will be returned), `all' (all specifications will be
589 returned), or nil (the actual specifier object will be returned). 645 returned), or nil (the actual specifier object will be returned).
590 646
591 See `face-property' for more information." 647 See `face-property' for more information."
592 (face-property face 'background-pixmap locale tag-set exact-p)) 648 (face-property face 'background-pixmap locale tag-set exact-p))
593 649
594 (defun face-background-pixmap-instance (face &optional domain default 650 (defun face-background-pixmap-instance (face &optional domain default
595 no-fallback) 651 no-fallback)
596 "Return the instance of FACE's background pixmap in DOMAIN. 652 "Return the instance of FACE's background pixmap in DOMAIN.
653
654 Return value will be an image instance object; query its properties using
655 `image-instance-instantiator' (the original instantiator used to create
656 the image, which may be a complex beast -- see `make-image-specifier'),
657 `image-instance-file-name' (the file, if any, from which the image was
658 created), `image-instance-height', etc.
597 659
598 FACE may be either a face object or a symbol representing a face. 660 FACE may be either a face object or a symbol representing a face.
599 661
600 Normally DOMAIN will be a window or nil (meaning the selected window), 662 Normally DOMAIN will be a window or nil (meaning the selected window),
601 and an instance object describing how the background appears in that 663 and an instance object describing how the background appears in that
614 PIXMAP should be an instantiator (see `make-image-specifier'), a list 676 PIXMAP should be an instantiator (see `make-image-specifier'), a list
615 of instantiators, an alist of specifications (each mapping a locale 677 of instantiators, an alist of specifications (each mapping a locale
616 to an instantiator list), or an image specifier object. 678 to an instantiator list), or an image specifier object.
617 679
618 If PIXMAP is an alist, LOCALE must be omitted. If PIXMAP is a 680 If PIXMAP is an alist, LOCALE must be omitted. If PIXMAP is a
619 specifier object, LOCALE can be a locale, a locale type, 'all, 681 specifier object, LOCALE can be a locale, a locale type, `all',
620 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE 682 or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
621 specifies the locale under which the specified instantiator(s) 683 specifies the locale under which the specified instantiator(s)
622 will be added, and defaults to 'global. 684 will be added, and defaults to `global'.
623 685
624 See `set-face-property' for more information." 686 See `set-face-property' for more information."
625 (interactive (face-interactive "background-pixmap")) 687 (interactive (face-interactive "background-pixmap"))
626 (set-face-property face 'background-pixmap pixmap locale tag-set how-to-add)) 688 (set-face-property face 'background-pixmap pixmap locale tag-set how-to-add))
627 689
645 'background-pixmap-file-history))) 707 'background-pixmap-file-history)))
646 (list face (if (equal file "") nil file)))) 708 (list face (if (equal file "") nil file))))
647 (set-face-property face 'background-pixmap file)) 709 (set-face-property face 'background-pixmap file))
648 710
649 (defun face-display-table (face &optional locale tag-set exact-p) 711 (defun face-display-table (face &optional locale tag-set exact-p)
650 "Return the display table of FACE in LOCALE. 712 "Return the display table spec of FACE in LOCALE, or nil if unspecified..
651 713
652 A vector (as returned by `make-display-table') will be returned. 714 NOTE: This returns a locale-specific specification, not any sort of value
715 corresponding to the actual display table being used. If you want to
716 know the actual display table used in a particular domain, use
717 `face-display-table-instance'.
718
719 FACE may be either a face object or a symbol representing a face.
653 720
654 LOCALE may be a locale (the instantiators for that particular locale 721 LOCALE may be a locale (the instantiators for that particular locale
655 will be returned), a locale type (the specifications for all locales 722 will be returned), a locale type (the specifications for all locales
656 of that type will be returned), 'all (all specifications will be 723 of that type will be returned), `all' (all specifications will be
657 returned), or nil (the actual specifier object will be returned). 724 returned), or nil (the actual specifier object will be returned).
658 725
659 See `face-property' for more information." 726 See `face-property' for more information."
660 (face-property face 'display-table locale tag-set exact-p)) 727 (face-property face 'display-table locale tag-set exact-p))
661 728
662 (defun face-display-table-instance (face &optional domain default no-fallback) 729 (defun face-display-table-instance (face &optional domain default no-fallback)
663 "Return the instance of FACE's display table in DOMAIN. 730 "Return the instance of FACE's display table in DOMAIN.
664 A vector (as returned by `make-display-table') will be returned. 731
665 732 Return value will be a vector, char table or range table; see
666 See `face-property-instance' for the semantics of the DOMAIN argument." 733 `current-display-table'.
734
735 FACE may be either a face object or a symbol representing a face.
736
737 Normally DOMAIN will be a window or nil (meaning the selected window),
738 and the actual display table used in that particular window and buffer
739 will be returned.
740
741 See `face-property-instance' for more information."
667 (face-property-instance face 'display-table domain default no-fallback)) 742 (face-property-instance face 'display-table domain default no-fallback))
668 743
669 (defun set-face-display-table (face display-table &optional locale tag-set 744 (defun set-face-display-table (face display-table &optional locale tag-set
670 how-to-add) 745 how-to-add)
671 "Change the display table of FACE to DISPLAY-TABLE in LOCALE. 746 "Change the display table of FACE to DISPLAY-TABLE in LOCALE.
785 (if (null domain) (setq domain (selected-window))) 860 (if (null domain) (setq domain (selected-window)))
786 (if (not (valid-specifier-domain-p domain)) 861 (if (not (valid-specifier-domain-p domain))
787 (error "Invalid specifier domain")) 862 (error "Invalid specifier domain"))
788 (let ((device (dfw-device domain)) 863 (let ((device (dfw-device domain))
789 (common-props '(foreground background font display-table underline 864 (common-props '(foreground background font display-table underline
790 dim)) 865 dim inherit))
791 (win-props '(background-pixmap strikethru)) 866 (win-props '(background-pixmap strikethru))
792 (tty-props '(highlight blinking reverse))) 867 (tty-props '(highlight blinking reverse)))
793 868
794 ;; First check the properties which are used in common between the 869 ;; First check the properties which are used in common between the
795 ;; x and tty devices. Then, check those properties specific to 870 ;; x and tty devices. Then, check those properties specific to
1629 (let ((init-face-from-resources nil)) 1704 (let ((init-face-from-resources nil))
1630 (make-face name doc-string temporary))) 1705 (make-face name doc-string temporary)))
1631 1706
1632 (defun init-face-from-resources (face &optional locale) 1707 (defun init-face-from-resources (face &optional locale)
1633 "Initialize FACE from the resource database. 1708 "Initialize FACE from the resource database.
1634 If LOCALE is specified, it should be a frame, device, or 'global, and 1709 If LOCALE is specified, it should be a frame, device, or `global', and
1635 the face will be resourced over that locale. Otherwise, the face will 1710 the face will be resourced over that locale. Otherwise, the face will
1636 be resourced over all possible locales (i.e. all frames, all devices, 1711 be resourced over all possible locales (i.e. all frames, all devices,
1637 and 'global)." 1712 and `global')."
1638 (cond ((null init-face-from-resources) 1713 (cond ((null init-face-from-resources)
1639 ;; Do nothing. 1714 ;; Do nothing.
1640 ) 1715 )
1641 ((not locale) 1716 ((not locale)
1642 ;; Global, set for all frames. 1717 ;; Global, set for all frames.