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 of 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 `generic-specifier-p', `integer-specifier-p',
362 `natnum-specifier-p', `boolean-specifier-p', `color-specifier-p',
363 `font-specifier-p', `image-specifier-p',
364 `face-boolean-specifier-p', and `toolbar-specifier-p'.
366 - Function: make-specifier-and-init type spec-list &optional
368 This function creates and initialize a new specifier.
370 This is a front-end onto `make-specifier' that allows you to create
371 a specifier and add specs to it at the same time. TYPE specifies
372 the specifier type. SPEC-LIST supplies the specification(s) to be
373 added to the specifier. Normally, almost any reasonable
374 abbreviation of the full spec-list form is accepted, and is
375 converted to the full form; however, if optional argument
376 DONT-CANONICALIZE is non-`nil', this conversion is not performed,
377 and the SPEC-LIST must already be in full form. See
378 `canonicalize-spec-list'.
381 File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
383 Functions for Checking the Validity of Specifier Components
384 ===========================================================
386 - Function: valid-specifier-domain-p domain
387 This function returns non-`nil' if DOMAIN is a valid specifier
388 domain. A domain is used to instance a specifier (i.e. determine
389 the specifier's value in that domain). Valid domains are a
390 window, frame, or device. (`nil' is not valid.)
392 - Function: valid-specifier-locale-p locale
393 This function returns non-`nil' if LOCALE is a valid specifier
394 locale. Valid locales are a device, a frame, a window, a buffer,
395 and `global'. (`nil' is not valid.)
397 - Function: valid-specifier-locale-type-p locale-type
398 Given a specifier LOCALE-TYPE, this function returns non-nil if it
399 is valid. Valid locale types are the symbols `global', `device',
400 `frame', `window', and `buffer'. (Note, however, that in functions
401 that accept either a locale or a locale type, `global' is
402 considered an individual locale.)
404 - Function: valid-specifier-type-p specifier-type
405 Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
406 valid. Valid types are `generic', `integer', `boolean', `color',
407 `font', `image', `face-boolean', and `toolbar'.
409 - Function: valid-specifier-tag-p tag
410 This function returns non-`nil' if TAG is a valid specifier tag.
412 - Function: valid-instantiator-p instantiator specifier-type
413 This function returns non-`nil' if INSTANTIATOR is valid for
416 - Function: valid-inst-list-p inst-list type
417 This function returns non-`nil' if INST-LIST is valid for
420 - Function: valid-spec-list-p spec-list type
421 This function returns non-`nil' if SPEC-LIST is valid for
424 - Function: check-valid-instantiator instantiator specifier-type
425 This function signals an error if INSTANTIATOR is invalid for
428 - Function: check-valid-inst-list inst-list type
429 This function signals an error if INST-LIST is invalid for
432 - Function: check-valid-spec-list spec-list type
433 This function signals an error if SPEC-LIST is invalid for
437 File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
439 Other Functions for Working with Specifications in a Specifier
440 ==============================================================
442 - Function: copy-specifier specifier &optional dest locale tag-set
444 This function copies SPECIFIER to DEST, or creates a new one if
447 If DEST is `nil' or omitted, a new specifier will be created and
448 the specifications copied into it. Otherwise, the specifications
449 will be copied into the existing specifier in DEST.
451 If LOCALE is `nil' or the symbol `all', all specifications will be
452 copied. If LOCALE is a particular locale, the specification for
453 that particular locale will be copied. If LOCALE is a locale
454 type, the specifications for all locales of that type will be
455 copied. LOCALE can also be a list of locales, locale types,
456 and/or `all'; this is equivalent to calling `copy-specifier' for
457 each of the elements of the list. See `specifier-spec-list' for
458 more information about LOCALE.
460 Only instantiators where TAG-SET (a list of zero or more tags) is
461 a subset of (or possibly equal to) the instantiator's tag set are
462 copied. (The default value of `nil' is a subset of all tag sets,
463 so in this case no instantiators will be screened out.) If EXACT-P
464 is non-`nil', however, TAG-SET must be equal to an instantiator's
465 tag set for the instantiator to be copied.
467 Optional argument HOW-TO-ADD specifies what to do with existing
468 specifications in DEST. If nil, then whichever locales or locale
469 types are copied will first be completely erased in DEST.
470 Otherwise, it is the same as in `add-spec-to-specifier'.
472 - Function: remove-specifier specifier &optional locale tag-set exact-p
473 This function removes specification(s) for SPECIFIER.
475 If LOCALE is a particular locale (a buffer, window, frame, device,
476 or the symbol `global'), the specification for that locale will be
479 If instead, LOCALE is a locale type (i.e. a symbol `buffer',
480 `window', `frame', or `device'), the specifications for all
481 locales of that type will be removed.
483 If LOCALE is `nil' or the symbol `all', all specifications will be
486 LOCALE can also be a list of locales, locale types, and/or `all';
487 this is equivalent to calling `remove-specifier' for each of the
488 elements in the list.
490 Only instantiators where TAG-SET (a list of zero or more tags) is
491 a subset of (or possibly equal to) the instantiator's tag set are
492 removed. (The default value of `nil' is a subset of all tag sets,
493 so in this case no instantiators will be screened out.) If EXACT-P
494 is non-`nil', however, TAG-SET must be equal to an instantiator's
495 tag set for the instantiator to be removed.
497 - Function: map-specifier specifier func &optional locale maparg
498 This function applies FUNC to the specification(s) for LOCALE in
501 If LOCALE is a locale, FUNC will be called for that locale. If
502 LOCALE is a locale type, FUNC will be mapped over all locales of
503 that type. If LOCALE is `nil' or the symbol `all', FUNC will be
504 mapped over all locales in SPECIFIER.
506 FUNC is called with four arguments: the SPECIFIER, the locale
507 being mapped over, the inst-list for that locale, and the optional
508 MAPARG. If any invocation of FUNC returns non-`nil', the mapping
509 will stop and the returned value becomes the value returned from
510 `map-specifier'. Otherwise, `map-specifier' returns `nil'.
512 - Function: specifier-locale-type-from-locale locale
513 Given a specifier LOCALE, this function returns its type.
516 File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
518 Faces and Window-System Objects
519 *******************************
523 * Faces:: Controlling the way text looks.
524 * Fonts:: Controlling the typeface of text.
525 * Colors:: Controlling the color of text and pixmaps.
528 File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
533 A "face" is a named collection of graphical properties: font,
534 foreground color, background color, background pixmap, optional
535 underlining, and (on TTY devices) whether the text is to be highlighted,
536 dimmed, blinking, or displayed in reverse video. Faces control the
537 display of text on the screen. Every face has a name, which is a symbol
538 such as `default' or `modeline'.
540 Each built-in property of a face is controlled using a specifier,
541 which allows it to have separate values in particular buffers, frames,
542 windows, and devices and to further vary according to device type (X or
543 TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
544 for more information.
546 The face named `default' is used for ordinary text. The face named
547 `modeline' is used for displaying the modeline. The face named
548 `highlight' is used for highlighted extents (*note Extents::). The
549 faces named `left-margin' and `right-margin' are used for the left and
550 right margin areas, respectively (*note Annotations::). The face named
551 `zmacs-region' is used for the highlighted region between point and
556 * Merging Faces:: How XEmacs decides which face to use
558 * Basic Face Functions:: How to define and examine faces.
559 * Face Properties:: How to access and modify a face's properties.
560 * Face Convenience Functions:: Convenience functions for accessing
561 particular properties of a face.
562 * Other Face Display Functions:: Other functions pertaining to how a
566 File: lispref.info, Node: Merging Faces, Next: Basic Face Functions, Up: Faces
568 Merging Faces for Display
569 -------------------------
571 Here are all the ways to specify which face to use for display of
574 * With defaults. Each frame has a "default face", which is used for
575 all text that doesn't somehow specify another face. The face named
576 `default' applies to the text area, while the faces `left-margin'
577 and `right-margin' apply to the left and right margin areas.
579 * With text properties. A character may have a `face' property; if
580 so, it's displayed with that face. (Text properties are actually
581 implemented in terms of extents.) *Note Text Properties::.
583 * With extents. An extent may have a `face' property, which applies
584 to all the text covered by the extent; in addition, if the
585 `highlight' property is set, the `highlight' property applies when
586 the mouse moves over the extent or if the extent is explicitly
587 highlighted. *Note Extents::.
589 * With annotations. Annotations that are inserted into a buffer can
590 specify their own face. (Annotations are actually implemented in
591 terms of extents.) *Note Annotations::.
593 If these various sources together specify more than one face for a
594 particular character, XEmacs merges the properties of the various faces
595 specified. Extents, text properties, and annotations all use the same
596 underlying representation (as extents). When multiple extents cover one
597 character, an extent with higher priority overrides those with lower
598 priority. *Note Extents::. If no extent covers a particular character,
599 the `default' face is used.
601 If a background pixmap is specified, it determines what will be
602 displayed in the background of text characters. If the background
603 pixmap is actually a pixmap, with its colors specified, those colors are
604 used; if it is a bitmap, the face's foreground and background colors are
608 File: lispref.info, Node: Basic Face Functions, Next: Face Properties, Prev: Merging Faces, Up: Faces
610 Basic Functions for Working with Faces
611 --------------------------------------
613 The properties a face can specify include the font, the foreground
614 color, the background color, the background pixmap, the underlining,
615 the display table, and (for TTY devices) whether the text is to be
616 highlighted, dimmed, blinking, or displayed in reverse video. The face
617 can also leave these unspecified, causing them to assume the value of
618 the corresponding property of the `default' face.
620 Here are the basic primitives for working with faces.
622 - Function: make-face name &optional doc-string temporary
623 This function defines and returns a new face named NAME, initially
624 with all properties unspecified. It does nothing if there is
625 already a face named NAME. Optional argument DOC-STRING specifies
626 an explanatory string used for descriptive purposes. If optional
627 argument TEMPORARY is non-`nil', the face will automatically
628 disappear when there are no more references to it anywhere in text
629 or Lisp code (otherwise, the face will continue to exist
630 indefinitely even if it is not used).
632 - Function: face-list &optional temporary
633 This function returns a list of the names of all defined faces. If
634 TEMPORARY is `nil', only the permanent faces are included. If it
635 is `t', only the temporary faces are included. If it is any other
636 non-`nil' value both permanent and temporary are included.
638 - Function: facep object
639 This function returns whether the given object is a face.
641 - Function: copy-face old-face new-name &optional locale how-to-add
642 This function defines a new face named NEW-NAME which is a copy of
643 the existing face named OLD-FACE. If there is already a face
644 named NEW-NAME, then it alters the face to have the same
645 properties as OLD-FACE. LOCALE and HOW-TO-ADD let you copy just
646 parts of the old face rather than the whole face, and are as in
647 `copy-specifier' (*note Specifiers::).
650 File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
655 You can examine and modify the properties of an existing face with
656 the following functions.
658 The following symbols have predefined meanings:
661 The foreground color of the face.
664 The background color of the face.
667 The font used to display text covered by this face.
670 The display table of the face.
673 The pixmap displayed in the background of the face. Only used by
677 Underline all text covered by this face.
680 Highlight all text covered by this face. Only used by faces on TTY
684 Dim all text covered by this face. Only used by faces on TTY
688 Blink all text covered by this face. Only used by faces on TTY
692 Reverse the foreground and background colors. Only used by faces
696 Description of what the face's normal use is. NOTE: This is not a
697 specifier, unlike all the other built-in properties, and cannot
698 contain locale-specific values.
700 - Function: set-face-property face property value &optional locale tag
702 This function changes a property of a FACE.
704 For built-in properties, the actual value of the property is a
705 specifier and you cannot change this; but you can change the
706 specifications within the specifier, and that is what this
707 function will do. For user-defined properties, you can use this
708 function to either change the actual value of the property or, if
709 this value is a specifier, change the specifications within it.
711 If PROPERTY is a built-in property, the specifications to be added
712 to this property can be supplied in many different ways:
714 If VALUE is a simple instantiator (e.g. a string naming a
715 font or color) or a list of instantiators, then the
716 instantiator(s) will be added as a specification of the
717 property for the given LOCALE (which defaults to `global' if
720 If VALUE is a list of specifications (each of which is a cons
721 of a locale and a list of instantiators), then LOCALE must be
722 `nil' (it does not make sense to explicitly specify a locale
723 in this case), and specifications will be added as given.
725 If VALUE is a specifier (as would be returned by
726 `face-property' if no LOCALE argument is given), then some or
727 all of the specifications in the specifier will be added to
728 the property. In this case, the function is really
729 equivalent to `copy-specifier' and LOCALE has the same
730 semantics (if it is a particular locale, the specification
731 for the locale will be copied; if a locale type,
732 specifications for all locales of that type will be copied;
733 if `nil' or `all', then all specifications will be copied).
735 HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
736 `append', `remove-tag-set-prepend', `remove-tag-set-append',
737 `remove-locale', `remove-locale-type', or `remove-all'. See
738 `copy-specifier' and `add-spec-to-specifier' for a description of
739 what each of these means. Most of the time, you do not need to
740 worry about this argument; the default behavior usually is fine.
742 In general, it is OK to pass an instance object (e.g. as returned
743 by `face-property-instance') as an instantiator in place of an
744 actual instantiator. In such a case, the instantiator used to
745 create that instance object will be used (for example, if you set
746 a font-instance object as the value of the `font' property, then
747 the font name used to create that object will be used instead).
748 If some cases, however, doing this conversion does not make sense,
749 and this will be noted in the documentation for particular types
752 If PROPERTY is not a built-in property, then this function will
753 simply set its value if LOCALE is `nil'. However, if LOCALE is
754 given, then this function will attempt to add VALUE as the
755 instantiator for the given LOCALE, using `add-spec-to-specifier'.
756 If the value of the property is not a specifier, it will
757 automatically be converted into a `generic' specifier.
759 - Function: remove-face-property face property &optional local tag-set
761 This function removes a property of a FACE.
763 For built-in properties, this is analogous to `remove-specifier'.
764 For more information, *Note Other Specification Functions::.
766 When PROPERTY is not a built-in property, this function will just
767 remove its value if LOCALE is `nil' or `all'. However, if LOCALE
768 is other than that, this function will attempt to remove VALUE as
769 the instantiator for the given LOCALE with `remove-specifier'. If
770 the value of the property is not a specifier, it will be converted
771 into a `generic' specifier automatically.
773 - Function: face-property face property &optional locale
774 This function returns FACE's value of the given PROPERTY.
776 If LOCALE is omitted, the FACE's actual value for PROPERTY will be
777 returned. For built-in properties, this will be a specifier
778 object of a type appropriate to the property (e.g. a font or color
779 specifier). For other properties, this could be anything.
781 If LOCALE is supplied, then instead of returning the actual value,
782 the specification(s) for the given locale or locale type will be
783 returned. This will only work if the actual value of PROPERTY is
784 a specifier (this will always be the case for built-in properties,
785 but not or not may apply to user-defined properties). If the
786 actual value of PROPERTY is not a specifier, this value will
787 simply be returned regardless of LOCALE.
789 The return value will be a list of instantiators (e.g. strings
790 specifying a font or color name), or a list of specifications,
791 each of which is a cons of a locale and a list of instantiators.
792 Specifically, if LOCALE is a particular locale (a buffer, window,
793 frame, device, or `global'), a list of instantiators for that
794 locale will be returned. Otherwise, if LOCALE is a locale type
795 (one of the symbols `buffer', `window', `frame', or `device'), the
796 specifications for all locales of that type will be returned.
797 Finally, if LOCALE is `all', the specifications for all locales of
798 all types will be returned.
800 The specifications in a specifier determine what the value of
801 PROPERTY will be in a particular "domain" or set of circumstances,
802 which is typically a particular Emacs window along with the buffer
803 it contains and the frame and device it lies within. The value is
804 derived from the instantiator associated with the most specific
805 locale (in the order buffer, window, frame, device, and `global')
806 that matches the domain in question. In other words, given a
807 domain (i.e. an Emacs window, usually), the specifier for PROPERTY
808 will first be searched for a specification whose locale is the
809 buffer contained within that window; then for a specification
810 whose locale is the window itself; then for a specification whose
811 locale is the frame that the window is contained within; etc. The
812 first instantiator that is valid for the domain (usually this
813 means that the instantiator is recognized by the device [i.e. the
814 X server or TTY device] that the domain is on). The function
815 `face-property-instance' actually does all this, and is used to
816 determine how to display the face.
818 - Function: face-property-instance face property &optional domain
820 This function returns the instance of FACE's PROPERTY in the
823 Under most circumstances, DOMAIN will be a particular window, and
824 the returned instance describes how the specified property
825 actually is displayed for that window and the particular buffer in
826 it. Note that this may not be the same as how the property
827 appears when the buffer is displayed in a different window or
828 frame, or how the property appears in the same window if you
829 switch to another buffer in that window; and in those cases, the
830 returned instance would be different.
832 The returned instance will typically be a color-instance,
833 font-instance, or pixmap-instance object, and you can query it
834 using the appropriate object-specific functions. For example, you
835 could use `color-instance-rgb-components' to find out the RGB
836 (red, green, and blue) components of how the `background' property
837 of the `highlight' face is displayed in a particular window. The
838 results might be different from the results you would get for
839 another window (perhaps the user specified a different color for
840 the frame that window is on; or perhaps the same color was
841 specified but the window is on a different X server, and that X
842 server has different RGB values for the color from this one).
844 DOMAIN defaults to the selected window if omitted.
846 DOMAIN can be a frame or device, instead of a window. The value
847 returned for a such a domain is used in special circumstances when
848 a more specific domain does not apply; for example, a frame value
849 might be used for coloring a toolbar, which is conceptually
850 attached to a frame rather than a particular window. The value is
851 also useful in determining what the value would be for a
852 particular window within the frame or device, if it is not
853 overridden by a more specific specification.
855 If PROPERTY does not name a built-in property, its value will
856 simply be returned unless it is a specifier object, in which case
857 it will be instanced using `specifier-instance'.
859 Optional arguments DEFAULT and NO-FALLBACK are the same as in
860 `specifier-instance'. *Note Specifiers::.
863 File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
865 Face Convenience Functions
866 --------------------------
868 - Function: set-face-foreground face color &optional locale tag
870 - Function: set-face-background face color &optional locale tag
872 These functions set the foreground (respectively, background)
873 color of face FACE to COLOR. The argument COLOR should be a
874 string (the name of a color) or a color object as returned by
875 `make-color' (*note Colors::).
877 - Function: set-face-background-pixmap face pixmap &optional locale
879 This function sets the background pixmap of face FACE to PIXMAP.
880 The argument PIXMAP should be a string (the name of a bitmap or
881 pixmap file; the directories listed in the variable
882 `x-bitmap-file-path' will be searched) or a glyph object as
883 returned by `make-glyph' (*note Glyphs::). The argument may also
884 be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
885 are the size in pixels, and DATA is a string, containing the raw
888 - Function: set-face-font face font &optional locale tag how-to-add
889 This function sets the font of face FACE. The argument FONT
890 should be a string or a font object as returned by `make-font'
893 - Function: set-face-underline-p face underline-p &optional locale tag
895 This function sets the underline property of face FACE.
897 - Function: face-foreground face &optional locale
898 - Function: face-background face &optional locale
899 These functions return the foreground (respectively, background)
900 color specifier of face FACE. *Note Colors::.
902 - Function: face-background-pixmap face &optional locale
903 This function return the background-pixmap glyph object of face
906 - Function: face-font face &optional locale
907 This function returns the font specifier of face FACE. (Note:
908 This is not the same as the function `face-font' in FSF Emacs.)
911 - Function: face-font-name face &optional domain
912 This function returns the name of the font of face FACE, or `nil'
913 if it is unspecified. This is basically equivalent to `(font-name
914 (face-font FACE) DOMAIN)' except that it does not cause an error
915 if FACE's font is `nil'. (This function is named `face-font' in
918 - Function: face-underline-p face &optional locale
919 This function returns the underline property of face FACE.
921 - Function: face-foreground-instance face &optional domain
922 - Function: face-background-instance face &optional domain
923 These functions return the foreground (respectively, background)
924 color specifier of face FACE. *Note Colors::.
926 - Function: face-background-pixmap-instance face &optional domain
927 This function return the background-pixmap glyph object of face
930 - Function: face-font-instance face &optional domain
931 This function returns the font specifier of face FACE. *Note
935 File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
937 Other Face Display Functions
938 ----------------------------
940 - Function: invert-face face &optional locale
941 Swap the foreground and background colors of face FACE. If the
942 face doesn't specify both foreground and background, then its
943 foreground and background are set to the default background and
946 - Function: face-equal face1 face2 &optional domain
947 This returns `t' if the faces FACE1 and FACE2 will display in the
948 same way. DOMAIN is as in `face-property-instance'.
950 - Function: face-differs-from-default-p face &optional domain
951 This returns `t' if the face FACE displays differently from the
952 default face. DOMAIN is as in `face-property-instance'.
955 File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
960 This section describes how to work with font specifier and font
961 instance objects, which encapsulate fonts in the window system.
965 * Font Specifiers:: Specifying how a font will appear.
966 * Font Instances:: What a font specifier gets instanced as.
967 * Font Instance Names:: The name of a font instance.
968 * Font Instance Size:: The size of a font instance.
969 * Font Instance Characteristics:: Display characteristics of font instances.
970 * Font Convenience Functions:: Convenience functions that automatically
971 instance and retrieve the properties
975 File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
980 - Function: font-specifier-p object
981 This predicate returns `t' if OBJECT is a font specifier, and
985 File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
990 - Function: font-instance-p object
991 This predicate returns `t' if OBJECT is a font instance, and `nil'
994 - Function: make-font-instance name &optional device noerror
995 This function creates a new font-instance object of the specified
996 name. DEVICE specifies the device this object applies to and
997 defaults to the selected device. An error is signalled if the
998 font is unknown or cannot be allocated; however, if NOERROR is
999 non-`nil', `nil' is simply returned in this case.
1001 The returned object is a normal, first-class lisp object. The way
1002 you "deallocate" the font is the way you deallocate any other lisp
1003 object: you drop all pointers to it and allow it to be garbage
1004 collected. When these objects are GCed, the underlying X data is
1005 deallocated as well.
1008 File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
1013 - Function: list-fonts pattern &optional device
1014 This function returns a list of font names matching the given
1015 pattern. DEVICE specifies which device to search for names, and
1016 defaults to the currently selected device.
1018 - Function: font-instance-name font-instance
1019 This function returns the name used to allocate FONT-INSTANCE.
1021 - Function: font-instance-truename font-instance
1022 This function returns the canonical name of the given font
1023 instance. Font names are patterns which may match any number of
1024 fonts, of which the first found is used. This returns an
1025 unambiguous name for that font (but not necessarily its only
1029 File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
1034 - Function: x-font-size font
1035 This function returns the nominal size of the given font. This is
1036 done by parsing its name, so it's likely to lose. X fonts can be
1037 specified (by the user) in either pixels or 10ths of points, and
1038 this returns the first one it finds, so you have to decide which
1039 units the returned value is measured in yourself ...
1041 - Function: x-find-larger-font font &optional device
1042 This function loads a new, slightly larger version of the given
1043 font (or font name). Returns the font if it succeeds, `nil'
1044 otherwise. If scalable fonts are available, this returns a font
1045 which is 1 point larger. Otherwise, it returns the next larger
1046 version of this font that is defined.
1048 - Function: x-find-smaller-font font &optional device
1049 This function loads a new, slightly smaller version of the given
1050 font (or font name). Returns the font if it succeeds, `nil'
1051 otherwise. If scalable fonts are available, this returns a font
1052 which is 1 point smaller. Otherwise, it returns the next smaller
1053 version of this font that is defined.
1056 File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
1058 Font Instance Characteristics
1059 -----------------------------
1061 - Function: font-instance-properties font
1062 This function returns the properties (an alist or `nil') of
1065 - Function: x-make-font-bold font &optional device
1066 Given an X font specification, this attempts to make a "bold" font.
1067 If it fails, it returns `nil'.
1069 - Function: x-make-font-unbold font &optional device
1070 Given an X font specification, this attempts to make a non-bold
1071 font. If it fails, it returns `nil'.
1073 - Function: x-make-font-italic font &optional device
1074 Given an X font specification, this attempts to make an "italic"
1075 font. If it fails, it returns `nil'.
1077 - Function: x-make-font-unitalic font &optional device
1078 Given an X font specification, this attempts to make a non-italic
1079 font. If it fails, it returns `nil'.
1081 - Function: x-make-font-bold-italic font &optional device
1082 Given an X font specification, this attempts to make a
1083 "bold-italic" font. If it fails, it returns `nil'.
1086 File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
1088 Font Convenience Functions
1089 --------------------------
1091 - Function: font-name font &optional domain
1092 This function returns the name of the FONT in the specified
1093 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
1094 is normally a window and defaults to the selected window if
1095 omitted. This is equivalent to using `specifier-instance' and
1096 applying `font-instance-name' to the result.
1098 - Function: font-truename font &optional domain
1099 This function returns the truename of the FONT in the specified
1100 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
1101 is normally a window and defaults to the selected window if
1102 omitted. This is equivalent to using `specifier-instance' and
1103 applying `font-instance-truename' to the result.
1105 - Function: font-properties font &optional domain
1106 This function returns the properties of the FONT in the specified
1107 DOMAIN, if any. FONT should be a font specifier object and DOMAIN
1108 is normally a window and defaults to the selected window if
1109 omitted. This is equivalent to using `specifier-instance' and
1110 applying `font-instance-properties' to the result.
1113 File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
1120 * Color Specifiers:: Specifying how a color will appear.
1121 * Color Instances:: What a color specifier gets instanced as.
1122 * Color Instance Properties:: Properties of color instances.
1123 * Color Convenience Functions:: Convenience functions that automatically
1124 instance and retrieve the properties
1125 of a color specifier.
1128 File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
1133 - Function: color-specifier-p object
1134 This function returns non-`nil' if OBJECT is a color specifier.
projects / chise / xemacs-chise.git / blob