1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
55 Retrieving the Specifications from a Specifier
56 ==============================================
58 - Function: specifier-spec-list specifier &optional locale tag-set
60 This function returns the spec-list of specifications for
63 If LOCALE is a particular locale (a window, buffer, frame, device,
64 or the symbol `global'), a spec-list consisting of the
65 specification for that locale will be returned.
67 If LOCALE is a locale type (i.e. a symbol `window', `buffer',
68 `frame', or `device'), a spec-list of the specifications for all
69 locales of that type will be returned.
71 If LOCALE is `nil' or the symbol `all', a spec-list of all
72 specifications in SPECIFIER will be returned.
74 LOCALE can also be a list of locales, locale types, and/or `all';
75 the result is as if `specifier-spec-list' were called on each
76 element of the list and the results concatenated together.
78 Only instantiators where TAG-SET (a list of zero or more tags) is
79 a subset of (or possibly equal to) the instantiator's tag set are
80 returned. (The default value of` nil' is a subset of all tag sets,
81 so in this case no instantiators will be screened out.) If EXACT-P
82 is non-`nil', however, TAG-SET must be equal to an instantiator's
83 tag set for the instantiator to be returned.
85 - Function: specifier-specs specifier &optional locale tag-set exact-p
86 This function returns the specification(s) for SPECIFIER in LOCALE.
88 If LOCALE is a single locale or is a list of one element
89 containing a single locale, then a "short form" of the
90 instantiators for that locale will be returned. Otherwise, this
91 function is identical to `specifier-spec-list'.
93 The "short form" is designed for readability and not for ease of
94 use in Lisp programs, and is as follows:
96 1. If there is only one instantiator, then an inst-pair (i.e.
97 cons of tag and instantiator) will be returned; otherwise a
98 list of inst-pairs will be returned.
100 2. For each inst-pair returned, if the instantiator's tag is
101 `any', the tag will be removed and the instantiator itself
102 will be returned instead of the inst-pair.
104 3. If there is only one instantiator, its value is `nil', and
105 its tag is `any', a one-element list containing `nil' will be
106 returned rather than just `nil', to distinguish this case
107 from there being no instantiators at all.
110 - Function: specifier-fallback specifier
111 This function returns the fallback value for SPECIFIER. Fallback
112 values are provided by the C code for certain built-in specifiers
113 to make sure that instancing won't fail even if all specs are
114 removed from the specifier, or to implement simple inheritance
115 behavior (e.g. this method is used to ensure that faces other than
116 `default' inherit their attributes from `default'). By design,
117 you cannot change the fallback value, and specifiers created with
118 `make-specifier' will never have a fallback (although a similar,
119 Lisp-accessible capability may be provided in the future to allow
122 The fallback value will be an inst-list that is instanced like any
123 other inst-list, a specifier of the same type as SPECIFIER
124 (results in inheritance), or `nil' for no fallback.
126 When you instance a specifier, you can explicitly request that the
127 fallback not be consulted. (The C code does this, for example, when
128 merging faces.) See `specifier-instance'.
131 File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
133 Working With Specifier Tags
134 ===========================
136 A specifier tag set is an entity that is attached to an instantiator
137 and can be used to restrict the scope of that instantiator to a
138 particular device class or device type and/or to mark instantiators
139 added by a particular package so that they can be later removed.
141 A specifier tag set consists of a list of zero or more specifier
142 tags, each of which is a symbol that is recognized by XEmacs as a tag.
143 (The valid device types and device classes are always tags, as are any
144 tags defined by `define-specifier-tag'.) It is called a "tag set" (as
145 opposed to a list) because the order of the tags or the number of times
146 a particular tag occurs does not matter.
148 Each tag has a predicate associated with it, which specifies whether
149 that tag applies to a particular device. The tags which are device
150 types and classes match devices of that type or class. User-defined
151 tags can have any predicate, or none (meaning that all devices match).
152 When attempting to instance a specifier, a particular instantiator is
153 only considered if the device of the domain being instanced over matches
154 all tags in the tag set attached to that instantiator.
156 Most of the time, a tag set is not specified, and the instantiator
157 gets a null tag set, which matches all devices.
159 - Function: valid-specifier-tag-p tag
160 This function returns non-`nil' if TAG is a valid specifier tag.
162 - Function: valid-specifier-tag-set-p tag-set
163 This function returns non-`nil' if TAG-SET is a valid specifier
166 - Function: canonicalize-tag-set tag-set
167 This function canonicalizes the given tag set. Two canonicalized
168 tag sets can be compared with `equal' to see if they represent the
169 same tag set. (Specifically, canonicalizing involves sorting by
170 symbol name and removing duplicates.)
172 - Function: device-matches-specifier-tag-set-p device tag-set
173 This function returns non-`nil' if DEVICE matches specifier tag
174 set TAG-SET. This means that DEVICE matches each tag in the tag
177 - Function: define-specifier-tag tag &optional predicate
178 This function defines a new specifier tag. If PREDICATE is
179 specified, it should be a function of one argument (a device) that
180 specifies whether the tag matches that particular device. If
181 PREDICATE is omitted, the tag matches all devices.
183 You can redefine an existing user-defined specifier tag. However,
184 you cannot redefine the built-in specifier tags (the device types
185 and classes) or the symbols `nil', `t', `all', or `global'.
187 - Function: device-matching-specifier-tag-list &optional device
188 This function returns a list of all specifier tags matching
189 DEVICE. DEVICE defaults to the selected device if omitted.
191 - Function: specifier-tag-list
192 This function returns a list of all currently-defined specifier
193 tags. This includes the built-in ones (the device types and
196 - Function: specifier-tag-predicate tag
197 This function returns the predicate for the given specifier tag.
200 File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
202 Functions for Instancing a Specifier
203 ====================================
205 - Function: specifier-instance specifier &optional domain default
207 This function instantiates SPECIFIER (return its value) in DOMAIN.
208 If no instance can be generated for this domain, return DEFAULT.
210 DOMAIN should be a window, frame, or device. Other values that
211 are legal as a locale (e.g. a buffer) are not valid as a domain
212 because they do not provide enough information to identify a
213 particular device (see `valid-specifier-domain-p'). DOMAIN
214 defaults to the selected window if omitted.
216 "Instantiating" a specifier in a particular domain means
217 determining the specifier's "value" in that domain. This is
218 accomplished by searching through the specifications in the
219 specifier that correspond to all locales that can be derived from
220 the given domain, from specific to general. In most cases, the
221 domain is an Emacs window. In that case specifications are
222 searched for as follows:
224 1. A specification whose locale is the window itself;
226 2. A specification whose locale is the window's buffer;
228 3. A specification whose locale is the window's frame;
230 4. A specification whose locale is the window's frame's device;
232 5. A specification whose locale is the symbol `global'.
234 If all of those fail, then the C-code-provided fallback value for
235 this specifier is consulted (see `specifier-fallback'). If it is
236 an inst-list, then this function attempts to instantiate that list
237 just as when a specification is located in the first five steps
238 above. If the fallback is a specifier, `specifier-instance' is
239 called recursively on this specifier and the return value used.
240 Note, however, that if the optional argument NO-FALLBACK is
241 non-`nil', the fallback value will not be consulted.
243 Note that there may be more than one specification matching a
244 particular locale; all such specifications are considered before
245 looking for any specifications for more general locales. Any
246 particular specification that is found may be rejected because it
247 is tagged to a particular device class (e.g. `color') or device
248 type (e.g. `x') or both and the device for the given domain does
249 not match this, or because the specification is not valid for the
250 device of the given domain (e.g. the font or color name does not
251 exist for this particular X server).
253 The returned value is dependent on the type of specifier. For
254 example, for a font specifier (as returned by the `face-font'
255 function), the returned value will be a font-instance object. For
256 images, the returned value will be a string, pixmap, or subwindow.
258 - Function: specifier-instance-from-inst-list specifier domain
259 inst-list &optional default
260 This function attempts to convert a particular inst-list into an
261 instance. This attempts to instantiate INST-LIST in the given
262 DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
263 If the instantiation fails, DEFAULT is returned. In most
264 circumstances, you should not use this function; use
265 `specifier-instance' instead.
268 File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
270 Example of Specifier Usage
271 ==========================
273 Now let us present an example to clarify the theoretical discussions
274 we have been through. In this example, we will use the general
275 specifier functions for clarity. Keep in mind that many types of
276 specifiers, and some other types of objects that are associated with
277 specifiers (e.g. faces), provide convenience functions making it easier
278 to work with objects of that type.
280 Let us consider the background color of the default face. A
281 specifier is used to specify how that color will appear in different
282 domains. First, let's retrieve the specifier:
284 (setq sp (face-property 'default 'background))
285 => #<color-specifier 0x3da>
288 => ((#<buffer "device.c"> (nil . "forest green"))
289 (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
290 (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
292 (#<x-frame "VM" 0x4ac> (nil . "magenta"))
293 (global ((tty) . "cyan") (nil . "white"))
296 Then, say we want to determine what the background color of the
297 default face is for the window currently displaying the buffer
300 (get-buffer-window "*scratch*")
301 => #<window on "*scratch*" 0x4ad>
302 (window-frame (get-buffer-window "*scratch*"))
303 => #<x-frame "emacs" 0x4ac>
304 (specifier-instance sp (get-buffer-window "*scratch*"))
305 => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
307 Note that we passed a window to `specifier-instance', not a buffer.
308 We cannot pass a buffer because a buffer by itself does not provide
309 enough information. The buffer might not be displayed anywhere at all,
310 or could be displayed in many different frames on different devices.
312 The result is arrived at like this:
314 1. First, we look for a specification matching the buffer displayed
315 in the window, i.e. `*scratch*'. There are none, so we proceed.
317 2. Then, we look for a specification matching the window itself.
318 Again, there are none.
320 3. Then, we look for a specification matching the window's frame. The
321 specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
322 found. We call the instantiation method for colors, passing it the
323 locale we were searching over (i.e. the window, in this case) and
324 the instantiator (`"puke orange"'). However, the particular device
325 which this window is on (let's say it's an X connection) doesn't
326 recognize the color `"puke orange"', so the specification is
329 4. So we continue looking for a specification matching the window's
330 frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
331 we call the instantiation method for colors. This time, the X
332 server our window is on recognizes the color `moccasin', and so the
333 instantiation method succeeds and returns a color instance.
336 File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
338 Creating New Specifier Objects
339 ==============================
341 - Function: make-specifier type
342 This function creates a new specifier.
344 A specifier is an object that can be used to keep track of a
345 property whose value can be per-buffer, per-window, per-frame, or
346 per-device, and can further be restricted to a particular
347 device-type or device-class. Specifiers are used, for example,
348 for the various built-in properties of a face; this allows a face
349 to have different values in different frames, buffers, etc. For
350 more information, see `specifier-instance', `specifier-specs', and
351 `add-spec-to-specifier'; or, for a detailed description of
352 specifiers, including how they are instantiated over a particular
353 domain (i.e. how their value in that domain is determined), see
354 the chapter on specifiers in the XEmacs Lisp Reference Manual.
356 TYPE specifies the particular type of specifier, and should be one
357 of the symbols `generic', `integer', `natnum', `boolean', `color',
358 `font', `image', `face-boolean', or `toolbar'.
360 For more information on particular types of specifiers, see the
361 functions `make-generic-specifier', `make-integer-specifier',
362 `make-natnum-specifier', `make-boolean-specifier',
363 `make-color-specifier', `make-font-specifier',
364 `make-image-specifier', `make-face-boolean-specifier', and
365 `make-toolbar-specifier'.
367 - Function: make-specifier-and-init type spec-list &optional
369 This function creates and initialize a new specifier.
371 This is a front-end onto `make-specifier' that allows you to create
372 a specifier and add specs to it at the same time. TYPE specifies
373 the specifier type. SPEC-LIST supplies the specification(s) to be
374 added to the specifier. Normally, almost any reasonable
375 abbreviation of the full spec-list form is accepted, and is
376 converted to the full form; however, if optional argument
377 DONT-CANONICALIZE is non-`nil', this conversion is not performed,
378 and the SPEC-LIST must already be in full form. See
379 `canonicalize-spec-list'.
381 - Function: make-integer-specifier spec-list
382 Return a new `integer' specifier object with the given
383 specification list. SPEC-LIST can be a list of specifications
384 (each of which is a cons of a locale and a list of instantiators),
385 a single instantiator, or a list of instantiators.
387 Valid instantiators for integer specifiers are integers.
389 - Function: make-boolean-specifier spec-list
390 Return a new `boolean' specifier object with the given
391 specification list. SPEC-LIST can be a list of specifications
392 (each of which is a cons of a locale and a list of instantiators),
393 a single instantiator, or a list of instantiators.
395 Valid instantiators for boolean specifiers are `t' and `nil'.
397 - Function: make-natnum-specifier spec-list
398 Return a new `natnum' specifier object with the given specification
399 list. SPEC-LIST can be a list of specifications (each of which is
400 a cons of a locale and a list of instantiators), a single
401 instantiator, or a list of instantiators.
403 Valid instantiators for natnum specifiers are non-negative
406 - Function: make-generic-specifier spec-list
407 Return a new `generic' specifier object with the given
408 specification list. SPEC-LIST can be a list of specifications
409 (each of which is a cons of a locale and a list of instantiators),
410 a single instantiator, or a list of instantiators.
412 Valid instantiators for generic specifiers are all Lisp values.
413 They are returned back unchanged when a specifier is instantiated.
415 - Function: make-display-table-specifier spec-list
416 Return a new `display-table' specifier object with the given spec
417 list. SPEC-LIST can be a list of specifications (each of which is
418 a cons of a locale and a list of instantiators), a single
419 instantiator, or a list of instantiators.
421 Valid instantiators for display-table specifiers are described in
422 detail in the doc string for `current-display-table' (*note Active
426 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
428 Functions for Checking the Validity of Specifier Components
429 ===========================================================
431 - Function: valid-specifier-domain-p domain
432 This function returns non-`nil' if DOMAIN is a valid specifier
433 domain. A domain is used to instance a specifier (i.e. determine
434 the specifier's value in that domain). Valid domains are a
435 window, frame, or device. (`nil' is not valid.)
437 - Function: valid-specifier-locale-p locale
438 This function returns non-`nil' if LOCALE is a valid specifier
439 locale. Valid locales are a device, a frame, a window, a buffer,
440 and `global'. (`nil' is not valid.)
442 - Function: valid-specifier-locale-type-p locale-type
443 Given a specifier LOCALE-TYPE, this function returns non-nil if it
444 is valid. Valid locale types are the symbols `global', `device',
445 `frame', `window', and `buffer'. (Note, however, that in functions
446 that accept either a locale or a locale type, `global' is
447 considered an individual locale.)
449 - Function: valid-specifier-type-p specifier-type
450 Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
451 valid. Valid types are `generic', `integer', `boolean', `color',
452 `font', `image', `face-boolean', and `toolbar'.
454 - Function: valid-specifier-tag-p tag
455 This function returns non-`nil' if TAG is a valid specifier tag.
457 - Function: valid-instantiator-p instantiator specifier-type
458 This function returns non-`nil' if INSTANTIATOR is valid for
461 - Function: valid-inst-list-p inst-list type
462 This function returns non-`nil' if INST-LIST is valid for
465 - Function: valid-spec-list-p spec-list type
466 This function returns non-`nil' if SPEC-LIST is valid for
469 - Function: check-valid-instantiator instantiator specifier-type
470 This function signals an error if INSTANTIATOR is invalid for
473 - Function: check-valid-inst-list inst-list type
474 This function signals an error if INST-LIST is invalid for
477 - Function: check-valid-spec-list spec-list type
478 This function signals an error if SPEC-LIST is invalid for
482 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
484 Other Functions for Working with Specifications in a Specifier
485 ==============================================================
487 - Function: copy-specifier specifier &optional dest locale tag-set
489 This function copies SPECIFIER to DEST, or creates a new one if
492 If DEST is `nil' or omitted, a new specifier will be created and
493 the specifications copied into it. Otherwise, the specifications
494 will be copied into the existing specifier in DEST.
496 If LOCALE is `nil' or the symbol `all', all specifications will be
497 copied. If LOCALE is a particular locale, the specification for
498 that particular locale will be copied. If LOCALE is a locale
499 type, the specifications for all locales of that type will be
500 copied. LOCALE can also be a list of locales, locale types,
501 and/or `all'; this is equivalent to calling `copy-specifier' for
502 each of the elements of the list. See `specifier-spec-list' for
503 more information about LOCALE.
505 Only instantiators where TAG-SET (a list of zero or more tags) is
506 a subset of (or possibly equal to) the instantiator's tag set are
507 copied. (The default value of `nil' is a subset of all tag sets,
508 so in this case no instantiators will be screened out.) If EXACT-P
509 is non-`nil', however, TAG-SET must be equal to an instantiator's
510 tag set for the instantiator to be copied.
512 Optional argument HOW-TO-ADD specifies what to do with existing
513 specifications in DEST. If nil, then whichever locales or locale
514 types are copied will first be completely erased in DEST.
515 Otherwise, it is the same as in `add-spec-to-specifier'.
517 - Function: remove-specifier specifier &optional locale tag-set exact-p
518 This function removes specification(s) for SPECIFIER.
520 If LOCALE is a particular locale (a buffer, window, frame, device,
521 or the symbol `global'), the specification for that locale will be
524 If instead, LOCALE is a locale type (i.e. a symbol `buffer',
525 `window', `frame', or `device'), the specifications for all
526 locales of that type will be removed.
528 If LOCALE is `nil' or the symbol `all', all specifications will be
531 LOCALE can also be a list of locales, locale types, and/or `all';
532 this is equivalent to calling `remove-specifier' for each of the
533 elements in the list.
535 Only instantiators where TAG-SET (a list of zero or more tags) is
536 a subset of (or possibly equal to) the instantiator's tag set are
537 removed. (The default value of `nil' is a subset of all tag sets,
538 so in this case no instantiators will be screened out.) If EXACT-P
539 is non-`nil', however, TAG-SET must be equal to an instantiator's
540 tag set for the instantiator to be removed.
542 - Function: map-specifier specifier func &optional locale maparg
543 This function applies FUNC to the specification(s) for LOCALE in
546 If LOCALE is a locale, FUNC will be called for that locale. If
547 LOCALE is a locale type, FUNC will be mapped over all locales of
548 that type. If LOCALE is `nil' or the symbol `all', FUNC will be
549 mapped over all locales in SPECIFIER.
551 FUNC is called with four arguments: the SPECIFIER, the locale
552 being mapped over, the inst-list for that locale, and the optional
553 MAPARG. If any invocation of FUNC returns non-`nil', the mapping
554 will stop and the returned value becomes the value returned from
555 `map-specifier'. Otherwise, `map-specifier' returns `nil'.
557 - Function: specifier-locale-type-from-locale locale
558 Given a specifier LOCALE, this function returns its type.
561 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
563 Faces and Window-System Objects
564 *******************************
568 * Faces:: Controlling the way text looks.
569 * Fonts:: Controlling the typeface of text.
570 * Colors:: Controlling the color of text and pixmaps.
573 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
578 A "face" is a named collection of graphical properties: font,
579 foreground color, background color, background pixmap, optional
580 underlining, and (on TTY devices) whether the text is to be highlighted,
581 dimmed, blinking, or displayed in reverse video. Faces control the
582 display of text on the screen. Every face has a name, which is a symbol
583 such as `default' or `modeline'.
585 Each built-in property of a face is controlled using a specifier,
586 which allows it to have separate values in particular buffers, frames,
587 windows, and devices and to further vary according to device type (X or
588 TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
589 for more information.
591 The face named `default' is used for ordinary text. The face named
592 `modeline' is used for displaying the modeline. The face named
593 `highlight' is used for highlighted extents (*note Extents::). The
594 faces named `left-margin' and `right-margin' are used for the left and
595 right margin areas, respectively (*note Annotations::). The face named
596 `zmacs-region' is used for the highlighted region between point and
601 * Merging Faces:: How XEmacs decides which face to use
603 * Basic Face Functions:: How to define and examine faces.
604 * Face Properties:: How to access and modify a face's properties.
605 * Face Convenience Functions:: Convenience functions for accessing
606 particular properties of a face.
607 * Other Face Display Functions:: Other functions pertaining to how a
611 File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
613 Merging Faces for Display
614 -------------------------
616 Here are all the ways to specify which face to use for display of
619 * With defaults. Each frame has a "default face", which is used for
620 all text that doesn't somehow specify another face. The face named
621 `default' applies to the text area, while the faces `left-margin'
622 and `right-margin' apply to the left and right margin areas.
624 * With text properties. A character may have a `face' property; if
625 so, it's displayed with that face. (Text properties are actually
626 implemented in terms of extents.) *Note Text Properties::.
628 * With extents. An extent may have a `face' property, which applies
629 to all the text covered by the extent; in addition, if the
630 `highlight' property is set, the `highlight' property applies when
631 the mouse moves over the extent or if the extent is explicitly
632 highlighted. *Note Extents::.
634 * With annotations. Annotations that are inserted into a buffer can
635 specify their own face. (Annotations are actually implemented in
636 terms of extents.) *Note Annotations::.
638 If these various sources together specify more than one face for a
639 particular character, XEmacs merges the properties of the various faces
640 specified. Extents, text properties, and annotations all use the same
641 underlying representation (as extents). When multiple extents cover one
642 character, an extent with higher priority overrides those with lower
643 priority. *Note Extents::. If no extent covers a particular character,
644 the `default' face is used.
646 If a background pixmap is specified, it determines what will be
647 displayed in the background of text characters. If the background
648 pixmap is actually a pixmap, with its colors specified, those colors are
649 used; if it is a bitmap, the face's foreground and background colors are
653 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
655 Basic Functions for Working with Faces
656 --------------------------------------
658 The properties a face can specify include the font, the foreground
659 color, the background color, the background pixmap, the underlining,
660 the display table, and (for TTY devices) whether the text is to be
661 highlighted, dimmed, blinking, or displayed in reverse video. The face
662 can also leave these unspecified, causing them to assume the value of
663 the corresponding property of the `default' face.
665 Here are the basic primitives for working with faces.
667 - Function: make-face name &optional doc-string temporary
668 This function defines and returns a new face named NAME, initially
669 with all properties unspecified. It does nothing if there is
670 already a face named NAME. Optional argument DOC-STRING specifies
671 an explanatory string used for descriptive purposes. If optional
672 argument TEMPORARY is non-`nil', the face will automatically
673 disappear when there are no more references to it anywhere in text
674 or Lisp code (otherwise, the face will continue to exist
675 indefinitely even if it is not used).
677 - Function: face-list &optional temporary
678 This function returns a list of the names of all defined faces. If
679 TEMPORARY is `nil', only the permanent faces are included. If it
680 is `t', only the temporary faces are included. If it is any other
681 non-`nil' value both permanent and temporary are included.
683 - Function: facep object
684 This function returns whether the given object is a face.
686 - Function: copy-face old-face new-name &optional locale how-to-add
687 This function defines a new face named NEW-NAME which is a copy of
688 the existing face named OLD-FACE. If there is already a face
689 named NEW-NAME, then it alters the face to have the same
690 properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
691 parts of the old face rather than the whole face, and are as in
692 `copy-specifier' (*note Specifiers::).
695 File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
700 You can examine and modify the properties of an existing face with
701 the following functions.
703 The following symbols have predefined meanings:
706 The foreground color of the face.
709 The background color of the face.
712 The font used to display text covered by this face.
715 The display table of the face.
718 The pixmap displayed in the background of the face. Only used by
722 Underline all text covered by this face.
725 Highlight all text covered by this face. Only used by faces on TTY
729 Dim all text covered by this face. Only used by faces on TTY
733 Blink all text covered by this face. Only used by faces on TTY
737 Reverse the foreground and background colors. Only used by faces
741 Description of what the face's normal use is. NOTE: This is not a
742 specifier, unlike all the other built-in properties, and cannot
743 contain locale-specific values.
745 - Function: set-face-property face property value &optional locale tag
747 This function changes a property of a FACE.
749 For built-in properties, the actual value of the property is a
750 specifier and you cannot change this; but you can change the
751 specifications within the specifier, and that is what this
752 function will do. For user-defined properties, you can use this
753 function to either change the actual value of the property or, if
754 this value is a specifier, change the specifications within it.
756 If PROPERTY is a built-in property, the specifications to be added
757 to this property can be supplied in many different ways:
759 If VALUE is a simple instantiator (e.g. a string naming a
760 font or color) or a list of instantiators, then the
761 instantiator(s) will be added as a specification of the
762 property for the given LOCALE (which defaults to `global' if
765 If VALUE is a list of specifications (each of which is a cons
766 of a locale and a list of instantiators), then LOCALE must be
767 `nil' (it does not make sense to explicitly specify a locale
768 in this case), and specifications will be added as given.
770 If VALUE is a specifier (as would be returned by
771 `face-property' if no LOCALE argument is given), then some or
772 all of the specifications in the specifier will be added to
773 the property. In this case, the function is really
774 equivalent to `copy-specifier' and LOCALE has the same
775 semantics (if it is a particular locale, the specification
776 for the locale will be copied; if a locale type,
777 specifications for all locales of that type will be copied;
778 if `nil' or `all', then all specifications will be copied).
780 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
781 `append', `remove-tag-set-prepend', `remove-tag-set-append',
782 `remove-locale', `remove-locale-type', or `remove-all'. See
783 `copy-specifier' and `add-spec-to-specifier' for a description of
784 what each of these means. Most of the time, you do not need to
785 worry about this argument; the default behavior usually is fine.
787 In general, it is OK to pass an instance object (e.g. as returned
788 by `face-property-instance') as an instantiator in place of an
789 actual instantiator. In such a case, the instantiator used to
790 create that instance object will be used (for example, if you set
791 a font-instance object as the value of the `font' property, then
792 the font name used to create that object will be used instead).
793 If some cases, however, doing this conversion does not make sense,
794 and this will be noted in the documentation for particular types
797 If PROPERTY is not a built-in property, then this function will
798 simply set its value if LOCALE is `nil'. However, if LOCALE is
799 given, then this function will attempt to add VALUE as the
800 instantiator for the given LOCALE, using `add-spec-to-specifier'.
801 If the value of the property is not a specifier, it will
802 automatically be converted into a `generic' specifier.
804 - Function: remove-face-property face property &optional local tag-set
806 This function removes a property of a FACE.
808 For built-in properties, this is analogous to `remove-specifier'.
809 For more information, *Note Other Specification Functions::.
811 When PROPERTY is not a built-in property, this function will just
812 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
813 is other than that, this function will attempt to remove VALUE as
814 the instantiator for the given LOCALE with `remove-specifier'. If
815 the value of the property is not a specifier, it will be converted
816 into a `generic' specifier automatically.
818 - Function: face-property face property &optional locale
819 This function returns FACE's value of the given PROPERTY.
821 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
822 returned. For built-in properties, this will be a specifier
823 object of a type appropriate to the property (e.g. a font or color
824 specifier). For other properties, this could be anything.
826 If LOCALE is supplied, then instead of returning the actual value,
827 the specification(s) for the given locale or locale type will be
828 returned. This will only work if the actual value of PROPERTY is
829 a specifier (this will always be the case for built-in properties,
830 but not or not may apply to user-defined properties). If the
831 actual value of PROPERTY is not a specifier, this value will
832 simply be returned regardless of LOCALE.
834 The return value will be a list of instantiators (e.g. strings
835 specifying a font or color name), or a list of specifications,
836 each of which is a cons of a locale and a list of instantiators.
837 Specifically, if LOCALE is a particular locale (a buffer, window,
838 frame, device, or `global'), a list of instantiators for that
839 locale will be returned. Otherwise, if LOCALE is a locale type
840 (one of the symbols `buffer', `window', `frame', or `device'), the
841 specifications for all locales of that type will be returned.
842 Finally, if LOCALE is `all', the specifications for all locales of
843 all types will be returned.
845 The specifications in a specifier determine what the value of
846 PROPERTY will be in a particular "domain" or set of circumstances,
847 which is typically a particular Emacs window along with the buffer
848 it contains and the frame and device it lies within. The value is
849 derived from the instantiator associated with the most specific
850 locale (in the order buffer, window, frame, device, and `global')
851 that matches the domain in question. In other words, given a
852 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
853 will first be searched for a specification whose locale is the
854 buffer contained within that window; then for a specification
855 whose locale is the window itself; then for a specification whose
856 locale is the frame that the window is contained within; etc. The
857 first instantiator that is valid for the domain (usually this
858 means that the instantiator is recognized by the device [i.e. the
859 X server or TTY device] that the domain is on). The function
860 `face-property-instance' actually does all this, and is used to
861 determine how to display the face.
863 - Function: face-property-instance face property &optional domain
865 This function returns the instance of FACE's PROPERTY in the
868 Under most circumstances, DOMAIN will be a particular window, and
869 the returned instance describes how the specified property
870 actually is displayed for that window and the particular buffer in
871 it. Note that this may not be the same as how the property
872 appears when the buffer is displayed in a different window or
873 frame, or how the property appears in the same window if you
874 switch to another buffer in that window; and in those cases, the
875 returned instance would be different.
877 The returned instance will typically be a color-instance,
878 font-instance, or pixmap-instance object, and you can query it
879 using the appropriate object-specific functions. For example, you
880 could use `color-instance-rgb-components' to find out the RGB
881 (red, green, and blue) components of how the `background' property
882 of the `highlight' face is displayed in a particular window. The
883 results might be different from the results you would get for
884 another window (perhaps the user specified a different color for
885 the frame that window is on; or perhaps the same color was
886 specified but the window is on a different X server, and that X
887 server has different RGB values for the color from this one).
889 DOMAIN defaults to the selected window if omitted.
891 DOMAIN can be a frame or device, instead of a window. The value
892 returned for a such a domain is used in special circumstances when
893 a more specific domain does not apply; for example, a frame value
894 might be used for coloring a toolbar, which is conceptually
895 attached to a frame rather than a particular window. The value is
896 also useful in determining what the value would be for a
897 particular window within the frame or device, if it is not
898 overridden by a more specific specification.
900 If PROPERTY does not name a built-in property, its value will
901 simply be returned unless it is a specifier object, in which case
902 it will be instanced using `specifier-instance'.
904 Optional arguments DEFAULT and NO-FALLBACK are the same as in
905 `specifier-instance'. *Note Specifiers::.
908 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
910 Face Convenience Functions
911 --------------------------
913 - Function: set-face-foreground face color &optional locale tag
915 - Function: set-face-background face color &optional locale tag
917 These functions set the foreground (respectively, background)
918 color of face FACE to COLOR. The argument COLOR should be a
919 string (the name of a color) or a color object as returned by
920 `make-color' (*note Colors::).
922 - Function: set-face-background-pixmap face pixmap &optional locale
924 This function sets the background pixmap of face FACE to PIXMAP.
925 The argument PIXMAP should be a string (the name of a bitmap or
926 pixmap file; the directories listed in the variable
927 `x-bitmap-file-path' will be searched) or a glyph object as
928 returned by `make-glyph' (*note Glyphs::). The argument may also
929 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
930 are the size in pixels, and DATA is a string, containing the raw
933 - Function: set-face-font face font &optional locale tag how-to-add
934 This function sets the font of face FACE. The argument FONT
935 should be a string or a font object as returned by `make-font'
938 - Function: set-face-underline-p face underline-p &optional locale tag
940 This function sets the underline property of face FACE.
942 - Function: face-foreground face &optional locale
943 - Function: face-background face &optional locale
944 These functions return the foreground (respectively, background)
945 color specifier of face FACE. *Note Colors::.
947 - Function: face-background-pixmap face &optional locale
948 This function return the background-pixmap glyph object of face
951 - Function: face-font face &optional locale
952 This function returns the font specifier of face FACE. (Note:
953 This is not the same as the function `face-font' in FSF Emacs.)
956 - Function: face-font-name face &optional domain
957 This function returns the name of the font of face FACE, or `nil'
958 if it is unspecified. This is basically equivalent to `(font-name
959 (face-font FACE) DOMAIN)' except that it does not cause an error
960 if FACE's font is `nil'. (This function is named `face-font' in
963 - Function: face-underline-p face &optional locale
964 This function returns the underline property of face FACE.
966 - Function: face-foreground-instance face &optional domain
967 - Function: face-background-instance face &optional domain
968 These functions return the foreground (respectively, background)
969 color specifier of face FACE. *Note Colors::.
971 - Function: face-background-pixmap-instance face &optional domain
972 This function return the background-pixmap glyph object of face
975 - Function: face-font-instance face &optional domain
976 This function returns the font specifier of face FACE. *Note
980 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
982 Other Face Display Functions
983 ----------------------------
985 - Function: invert-face face &optional locale
986 Swap the foreground and background colors of face FACE. If the
987 face doesn't specify both foreground and background, then its
988 foreground and background are set to the default background and
991 - Function: face-equal face1 face2 &optional domain
992 This returns `t' if the faces FACE1 and FACE2 will display in the
993 same way. DOMAIN is as in `face-property-instance'.
995 - Function: face-differs-from-default-p face &optional domain
996 This returns `t' if the face FACE displays differently from the
997 default face. DOMAIN is as in `face-property-instance'.
1000 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
1005 This section describes how to work with font specifier and font
1006 instance objects, which encapsulate fonts in the window system.
1010 * Font Specifiers:: Specifying how a font will appear.
1011 * Font Instances:: What a font specifier gets instanced as.
1012 * Font Instance Names:: The name of a font instance.
1013 * Font Instance Size:: The size of a font instance.
1014 * Font Instance Characteristics:: Display characteristics of font instances.
1015 * Font Convenience Functions:: Convenience functions that automatically
1016 instance and retrieve the properties
1017 of a font specifier.
1020 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
1025 - Function: font-specifier-p object
1026 This predicate returns `t' if OBJECT is a font specifier, and
1029 - Function: make-font-specifier spec-list
1030 Return a new `font' specifier object with the given specification
1031 list. SPEC-LIST can be a list of specifications (each of which is
1032 a cons of a locale and a list of instantiators), a single
1033 instantiator, or a list of instantiators. *Note Specifiers::, for
1034 more information about specifiers.
1036 Valid instantiators for font specifiers are:
1038 * A string naming a font (e.g. under X this might be
1039 "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
1040 14-point upright medium-weight Courier font).
1042 * A font instance (use that instance directly if the device
1043 matches, or use the string that generated it).
1045 * A vector of no elements (only on TTY's; this means to set no
1046 font at all, thus using the "natural" font of the terminal's
1049 * A vector of one element (a face to inherit from).
1052 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
1057 - Function: font-instance-p object
1058 This predicate returns `t' if OBJECT is a font instance, and `nil'
1061 - Function: make-font-instance name &optional device noerror
1062 This function creates a new font-instance object of the specified
1063 name. DEVICE specifies the device this object applies to and
1064 defaults to the selected device. An error is signalled if the
1065 font is unknown or cannot be allocated; however, if NOERROR is
1066 non-`nil', `nil' is simply returned in this case.
1068 The returned object is a normal, first-class lisp object. The way
1069 you "deallocate" the font is the way you deallocate any other lisp
1070 object: you drop all pointers to it and allow it to be garbage
1071 collected. When these objects are GCed, the underlying X data is
1072 deallocated as well.
1075 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
1080 - Function: list-fonts pattern &optional device
1081 This function returns a list of font names matching the given
1082 pattern. DEVICE specifies which device to search for names, and
1083 defaults to the currently selected device.
1085 - Function: font-instance-name font-instance
1086 This function returns the name used to allocate FONT-INSTANCE.
1088 - Function: font-instance-truename font-instance
1089 This function returns the canonical name of the given font
1090 instance. Font names are patterns which may match any number of
1091 fonts, of which the first found is used. This returns an
1092 unambiguous name for that font (but not necessarily its only
1096 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
1101 - Function: x-font-size font
1102 This function returns the nominal size of the given font. This is
1103 done by parsing its name, so it's likely to lose. X fonts can be
1104 specified (by the user) in either pixels or 10ths of points, and
1105 this returns the first one it finds, so you have to decide which
1106 units the returned value is measured in yourself ...
1108 - Function: x-find-larger-font font &optional device
1109 This function loads a new, slightly larger version of the given
1110 font (or font name). Returns the font if it succeeds, `nil'
1111 otherwise. If scalable fonts are available, this returns a font
1112 which is 1 point larger. Otherwise, it returns the next larger
1113 version of this font that is defined.
1115 - Function: x-find-smaller-font font &optional device
1116 This function loads a new, slightly smaller version of the given
1117 font (or font name). Returns the font if it succeeds, `nil'
1118 otherwise. If scalable fonts are available, this returns a font
1119 which is 1 point smaller. Otherwise, it returns the next smaller
1120 version of this font that is defined.
projects / chise / xemacs-chise.git / blob