-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
-
-Face Properties
----------------
-
- You can examine and modify the properties of an existing face with
-the following functions.
-
- The following symbols have predefined meanings:
-
-`foreground'
- The foreground color of the face.
-
-`background'
- The background color of the face.
-
-`font'
- The font used to display text covered by this face.
-
-`display-table'
- The display table of the face.
-
-`background-pixmap'
- The pixmap displayed in the background of the face. Only used by
- faces on X devices.
-
-`underline'
- Underline all text covered by this face.
-
-`highlight'
- Highlight all text covered by this face. Only used by faces on TTY
- devices.
-
-`dim'
- Dim all text covered by this face. Only used by faces on TTY
- devices.
-
-`blinking'
- Blink all text covered by this face. Only used by faces on TTY
- devices.
-
-`reverse'
- Reverse the foreground and background colors. Only used by faces
- on TTY devices.
-
-`doc-string'
- Description of what the face's normal use is. NOTE: This is not a
- specifier, unlike all the other built-in properties, and cannot
- contain locale-specific values.
-
- - Function: set-face-property FACE PROPERTY VALUE &optional LOCALE TAG
- HOW-TO-ADD
- This function changes a property of a FACE.
-
- For built-in properties, the actual value of the property is a
- specifier and you cannot change this; but you can change the
- specifications within the specifier, and that is what this
- function will do. For user-defined properties, you can use this
- function to either change the actual value of the property or, if
- this value is a specifier, change the specifications within it.
-
- If PROPERTY is a built-in property, the specifications to be added
- to this property can be supplied in many different ways:
-
- If VALUE is a simple instantiator (e.g. a string naming a
- font or color) or a list of instantiators, then the
- instantiator(s) will be added as a specification of the
- property for the given LOCALE (which defaults to `global' if
- omitted).
-
- If VALUE is a list of specifications (each of which is a cons
- of a locale and a list of instantiators), then LOCALE must be
- `nil' (it does not make sense to explicitly specify a locale
- in this case), and specifications will be added as given.
-
- If VALUE is a specifier (as would be returned by
- `face-property' if no LOCALE argument is given), then some or
- all of the specifications in the specifier will be added to
- the property. In this case, the function is really
- equivalent to `copy-specifier' and LOCALE has the same
- semantics (if it is a particular locale, the specification
- for the locale will be copied; if a locale type,
- specifications for all locales of that type will be copied;
- if `nil' or `all', then all specifications will be copied).
-
- HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
- `append', `remove-tag-set-prepend', `remove-tag-set-append',
- `remove-locale', `remove-locale-type', or `remove-all'. See
- `copy-specifier' and `add-spec-to-specifier' for a description of
- what each of these means. Most of the time, you do not need to
- worry about this argument; the default behavior usually is fine.
-
- In general, it is OK to pass an instance object (e.g. as returned
- by `face-property-instance') as an instantiator in place of an
- actual instantiator. In such a case, the instantiator used to
- create that instance object will be used (for example, if you set
- a font-instance object as the value of the `font' property, then
- the font name used to create that object will be used instead).
- If some cases, however, doing this conversion does not make sense,
- and this will be noted in the documentation for particular types
- of instance objects.
-
- If PROPERTY is not a built-in property, then this function will
- simply set its value if LOCALE is `nil'. However, if LOCALE is
- given, then this function will attempt to add VALUE as the
- instantiator for the given LOCALE, using `add-spec-to-specifier'.
- If the value of the property is not a specifier, it will
- automatically be converted into a `generic' specifier.
-
- - Function: face-property FACE PROPERTY &optional LOCALE
- This function returns FACE's value of the given PROPERTY.
-
- If LOCALE is omitted, the FACE's actual value for PROPERTY will be
- returned. For built-in properties, this will be a specifier
- object of a type appropriate to the property (e.g. a font or color
- specifier). For other properties, this could be anything.
-
- If LOCALE is supplied, then instead of returning the actual value,
- the specification(s) for the given locale or locale type will be
- returned. This will only work if the actual value of PROPERTY is
- a specifier (this will always be the case for built-in properties,
- but not or not may apply to user-defined properties). If the
- actual value of PROPERTY is not a specifier, this value will
- simply be returned regardless of LOCALE.
-
- The return value will be a list of instantiators (e.g. strings
- specifying a font or color name), or a list of specifications,
- each of which is a cons of a locale and a list of instantiators.
- Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or `global'), a list of instantiators for that
- locale will be returned. Otherwise, if LOCALE is a locale type
- (one of the symbols `buffer', `window', `frame', or `device'), the
- specifications for all locales of that type will be returned.
- Finally, if LOCALE is `all', the specifications for all locales of
- all types will be returned.
-
- The specifications in a specifier determine what the value of
- PROPERTY will be in a particular "domain" or set of circumstances,
- which is typically a particular Emacs window along with the buffer
- it contains and the frame and device it lies within. The value is
- derived from the instantiator associated with the most specific
- locale (in the order buffer, window, frame, device, and `global')
- that matches the domain in question. In other words, given a
- domain (i.e. an Emacs window, usually), the specifier for PROPERTY
- will first be searched for a specification whose locale is the
- buffer contained within that window; then for a specification
- whose locale is the window itself; then for a specification whose
- locale is the frame that the window is contained within; etc. The
- first instantiator that is valid for the domain (usually this
- means that the instantiator is recognized by the device [i.e. the
- X server or TTY device] that the domain is on). The function
- `face-property-instance' actually does all this, and is used to
- determine how to display the face.
-
- - Function: face-property-instance FACE PROPERTY &optional DOMAIN
- DEFAULT NO-FALLBACK
- This function returns the instance of FACE's PROPERTY in the
- specified DOMAIN.
-
- Under most circumstances, DOMAIN will be a particular window, and
- the returned instance describes how the specified property
- actually is displayed for that window and the particular buffer in
- it. Note that this may not be the same as how the property
- appears when the buffer is displayed in a different window or
- frame, or how the property appears in the same window if you
- switch to another buffer in that window; and in those cases, the
- returned instance would be different.
-
- The returned instance will typically be a color-instance,
- font-instance, or pixmap-instance object, and you can query it
- using the appropriate object-specific functions. For example, you
- could use `color-instance-rgb-components' to find out the RGB
- (red, green, and blue) components of how the `background' property
- of the `highlight' face is displayed in a particular window. The
- results might be different from the results you would get for
- another window (perhaps the user specified a different color for
- the frame that window is on; or perhaps the same color was
- specified but the window is on a different X server, and that X
- server has different RGB values for the color from this one).
-
- DOMAIN defaults to the selected window if omitted.
-
- DOMAIN can be a frame or device, instead of a window. The value
- returned for a such a domain is used in special circumstances when
- a more specific domain does not apply; for example, a frame value
- might be used for coloring a toolbar, which is conceptually
- attached to a frame rather than a particular window. The value is
- also useful in determining what the value would be for a
- particular window within the frame or device, if it is not
- overridden by a more specific specification.
-
- If PROPERTY does not name a built-in property, its value will
- simply be returned unless it is a specifier object, in which case
- it will be instanced using `specifier-instance'.
-
- Optional arguments DEFAULT and NO-FALLBACK are the same as in
- `specifier-instance'. *Note Specifiers::.
+File: lispref.info, Node: Specifiers In-Depth, Next: Specifier Instancing, Prev: Introduction to Specifiers, Up: Specifiers
+
+In-Depth Overview of a Specifier
+================================
+
+ A specifier object encapsulates a set of "specifications", each of
+which says what its value should be if a particular condition applies.
+For example, one specification might be "The value should be
+darkseagreen2 on X devices" another might be "The value should be blue
+in the *Help* buffer". In specifier terminology, these conditions are
+called "locales" and the values are called "instantiators". Given a
+specifier, a logical question is "What is its value in a particular
+situation?" This involves looking through the specifications to see
+which ones apply to this particular situation, and perhaps preferring
+one over another if more than one applies. In specifier terminology, a
+"particular situation" is called a "domain", and determining its value
+in a particular domain is called "instancing". Most of the time, a
+domain is identified by a particular window. For example, if the
+redisplay engine is drawing text in the default face in a particular
+window, it retrieves the specifier for the foreground color of the
+default face and "instances" it in the domain given by that window; in
+other words, it asks the specifier, "What is your value in this
+window?".
+
+ More specifically, a specifier contains a set of "specifications",
+each of which associates a "locale" (a window object, a buffer object,
+a frame object, a device object, or the symbol `global') with an
+"inst-list", which is a list of one or more "inst-pairs". (For each
+possible locale, there can be at most one specification containing that
+locale.) Each inst-pair is a cons of a "tag set" (an unordered list of
+zero or more symbols, or "tags") and an "instantiator" (the allowed
+form of this varies depending on the type of specifier). In a given
+specification, there may be more than one inst-pair with the same tag
+set; this is unlike for locales.
+
+ The tag set is used to restrict the sorts of devices over which the
+instantiator is valid and to uniquely identify instantiators added by a
+particular application, so that different applications can work on the
+same specifier and not interfere with each other. Each tag can have a
+"predicate" associated with it, which is a function of one argument (a
+device) that specifies whether the tag matches that particular device.
+(If a tag does not have a predicate, it matches all devices.) All tags
+in a tag set must match a device for the associated inst-pair to be
+instantiable over that device. (A null tag set is perfectly valid.)
+
+ The valid device types (normally `x', `tty', and `stream') and
+device classes (normally `color', `grayscale', and `mono') can always
+be used as tags, and match devices of the associated type or class
+(*note Consoles and Devices::). User-defined tags may be defined, with
+an optional predicate specified. An application can create its own
+tag, use it to mark all its instantiators, and be fairly confident that
+it will not interfere with other applications that modify the same
+specifier--Functions that add a specification to a specifier usually
+only overwrite existing inst-pairs with the same tag set as was given,
+and a particular tag or tag set can be specified when removing
+instantiators.
+
+ When a specifier is instanced in a domain, both the locale and the
+tag set can be viewed as specifying necessary conditions that must
+apply in that domain for an instantiator to be considered as a possible
+result of the instancing. More specific locales always override more
+general locales (thus, there is no particular ordering of the
+specifications in a specifier); however, the tag sets are simply
+considered in the order that the inst-pairs occur in the
+specification's inst-list.
+
+ Note also that the actual object that results from the instancing
+(called an "instance object") may not be the same as the instantiator
+from which it was derived. For some specifier types (such as integer
+specifiers and boolean specifiers), the instantiator will be returned
+directly as the instance object. For other types, however, this is not
+the case. For example, for font specifiers, the instantiator is a
+font-description string and the instance object is a font-instance
+object, which describes how the font is displayed on a particular
+device. A font-instance object encapsulates such things as the actual
+font name used to display the font on that device (a font-description
+string under X is usually a wildcard specification that may resolve to
+different font names, with possibly different foundries, widths, etc.,
+on different devices), the extra properties of that font on that
+device, etc. Furthermore, this conversion (called "instantiation")
+might fail--a font or color might not exist on a particular device, for
+example.
\1f
-File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
-
-Face Convenience Functions
---------------------------
-
- - Function: set-face-foreground FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
- - Function: set-face-background FACE COLOR &optional LOCALE TAG
- HOW-TO-ADD
- These functions set the foreground (respectively, background)
- color of face FACE to COLOR. The argument COLOR should be a
- string (the name of a color) or a color object as returned by
- `make-color' (*note Colors::.).
-
- - Function: set-face-background-pixmap FACE PIXMAP &optional LOCALE
- TAG HOW-TO-ADD
- This function sets the background pixmap of face FACE to PIXMAP.
- The argument PIXMAP should be a string (the name of a bitmap or
- pixmap file; the directories listed in the variable
- `x-bitmap-file-path' will be searched) or a glyph object as
- returned by `make-glyph' (*note Glyphs::.). The argument may also
- be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
- are the size in pixels, and DATA is a string, containing the raw
- bits of the bitmap.
-
- - Function: set-face-font FACE FONT &optional LOCALE TAG HOW-TO-ADD
- This function sets the font of face FACE. The argument FONT
- should be a string or a font object as returned by `make-font'
- (*note Fonts::.).
-
- - Function: set-face-underline-p FACE UNDERLINE-P &optional LOCALE TAG
- HOW-TO-ADD
- This function sets the underline property of face FACE.
-
- - Function: face-foreground FACE &optional LOCALE
- - Function: face-background FACE &optional LOCALE
- These functions return the foreground (respectively, background)
- color specifier of face FACE. *Note Colors::.
-
- - Function: face-background-pixmap FACE &optional LOCALE
- This function return the background-pixmap glyph object of face
- FACE.
-
- - Function: face-font FACE &optional LOCALE
- This function returns the font specifier of face FACE. (Note:
- This is not the same as the function `face-font' in FSF Emacs.)
- *Note Fonts::.
-
- - Function: face-font-name FACE &optional DOMAIN
- This function returns the name of the font of face FACE, or `nil'
- if it is unspecified. This is basically equivalent to `(font-name
- (face-font FACE) DOMAIN)' except that it does not cause an error
- if FACE's font is `nil'. (This function is named `face-font' in
- FSF Emacs.)
-
- - Function: face-underline-p FACE &optional LOCALE
- This function returns the underline property of face FACE.
-
- - Function: face-foreground-instance FACE &optional DOMAIN
- - Function: face-background-instance FACE &optional DOMAIN
- These functions return the foreground (respectively, background)
- color specifier of face FACE. *Note Colors::.
-
- - Function: face-background-pixmap-instance FACE &optional DOMAIN
- This function return the background-pixmap glyph object of face
- FACE.
-
- - Function: face-font-instance FACE &optional DOMAIN
- This function returns the font specifier of face FACE. *Note
- Fonts::.
+File: lispref.info, Node: Specifier Instancing, Next: Specifier Types, Prev: Specifiers In-Depth, Up: Specifiers
+
+How a Specifier Is Instanced
+============================
+
+ Instancing of a specifier in a particular window domain proceeds as
+follows:
+
+ * First, XEmacs searches for a specification whose locale is the
+ same as the window. If that fails, the search is repeated,
+ looking for a locale that is the same as the window's buffer. If
+ that fails, the search is repeated using the window's frame, then
+ using the device that frame is on. Finally, the specification
+ whose locale is the symbol `global' (if there is such a
+ specification) is considered.
+
+ * The inst-pairs contained in the specification that was found are
+ considered in their order in the inst-list, looking for one whose
+ tag set matches the device that is derived from the window domain.
+ (The tag set is an unordered list of zero or more tag symbols.
+ For all tags that have predicates associated with them, the
+ predicate must match the device.)
+
+ * If a matching tag set is found, the corresponding instantiator is
+ passed to the specifier's instantiation method, which is specific
+ to the type of the specifier. If it succeeds, the resulting
+ instance object is returned as the result of the instancing and
+ the instancing is done. Otherwise, the operation continues,
+ looking for another matching inst-pair in the current
+ specification.
+
+ * When there are no more inst-pairs to be considered in the current
+ specification, the search starts over, looking for another
+ specification as in the first step above.
+
+ * If all specifications are exhausted and no instance object can be
+ derived, the instancing fails. (Actually, this is not completely
+ true. Some specifier objects for built-in properties have a
+ "fallback" value, which is either an inst-list or another
+ specifier object, that is consulted if the instancing is about to
+ fail. If it is an inst-list, the searching proceeds using the
+ inst-pairs in that list. If it is a specifier, the entire
+ instancing starts over using that specifier instead of the given
+ one. Fallback values are set by the C code and cannot be
+ modified, except perhaps indirectly, using any Lisp functions.
+ The purpose of them is to supply some values to make sure that
+ instancing of built-in properties can't fail and to implement some
+ basic specifier inheritance, such as the fact that faces inherit
+ their properties from the `default' face.)
+
+ It is also possible to instance a specifier over a frame domain or
+device domain instead of over a window domain. The C code, for example,
+instances the `top-toolbar-height' variable over a frame domain in
+order to determine the height of a frame's top toolbar. Instancing over
+a frame or device is similar to instancing over a window except that
+specifications for locales that cannot be derived from the domain are
+ignored. Specifically, instancing over a frame looks first for frame
+locales, then device locales, then the `global' locale. Instancing
+over a device domain looks only for device locales and the `global'
+locale.
\1f
-File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
-
-Other Face Display Functions
-----------------------------
+File: lispref.info, Node: Specifier Types, Next: Adding Specifications, Prev: Specifier Instancing, Up: Specifiers
- - Function: invert-face FACE &optional LOCALE
- Swap the foreground and background colors of face FACE. If the
- face doesn't specify both foreground and background, then its
- foreground and background are set to the default background and
- foreground.
-
- - Function: face-equal FACE1 FACE2 &optional DOMAIN
- This returns `t' if the faces FACE1 and FACE2 will display in the
- same way. DOMAIN is as in `face-property-instance'.
+Specifier Types
+===============
- - Function: face-differs-from-default-p FACE &optional DOMAIN
- This returns `t' if the face FACE displays differently from the
- default face. DOMAIN is as in `face-property-instance'.
+ There are various different types of specifiers. The type of a
+specifier controls what sorts of instantiators are valid, how an
+instantiator is instantiated, etc. Here is a list of built-in specifier
+types:
+
+`boolean'
+ The valid instantiators are the symbols `t' and `nil'. Instance
+ objects are the same as instantiators so no special instantiation
+ function is needed.
+
+`integer'
+ The valid instantiators are integers. Instance objects are the
+ same as instantiators so no special instantiation function is
+ needed. `modeline-shadow-thickness' is an example of an integer
+ specifier (negative thicknesses indicate that the shadow is drawn
+ recessed instead of raised).
+
+`natnum'
+ The valid instantiators are natnums (non-negative integers).
+ Instance objects are the same as instantiators so no special
+ instantiation function is needed. Natnum specifiers are used for
+ dimension variables such as `top-toolbar-height'.
+
+`generic'
+ All Lisp objects are valid instantiators. Instance objects are
+ the same as instantiators so no special instantiation function is
+ needed.
-\1f
-File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
+`font'
+ The valid instantiators are strings describing fonts or vectors
+ indicating inheritance from the font of some face. Instance
+ objects are font-instance objects, which are specific to a
+ particular device. The instantiation method for font specifiers
+ can fail, unlike for integer, natnum, boolean, and generic
+ specifiers.
+
+`color'
+ The valid instantiators are strings describing colors or vectors
+ indicating inheritance from the foreground or background of some
+ face. Instance objects are color-instance objects, which are
+ specific to a particular device. The instantiation method for
+ color specifiers can fail, as for font specifiers.
-Fonts
-=====
+`image'
+ Images are perhaps the most complicated type of built-in
+ specifier. The valid instantiators are strings (a filename,
+ inline data for a pixmap, or text to be displayed in a text glyph)
+ or vectors describing inline data of various sorts or indicating
+ inheritance from the background-pixmap property of some face.
+ Instance objects are either strings (for text images),
+ image-instance objects (for pixmap images), or subwindow objects
+ (for subwindow images). The instantiation method for image
+ specifiers can fail, as for font and color specifiers.
+
+`face-boolean'
+ The valid instantiators are the symbols `t' and `nil' and vectors
+ indicating inheritance from a boolean property of some face.
+ Specifiers of this sort are used for all of the built-in boolean
+ properties of faces. Instance objects are either the symbol `t'
+ or the symbol `nil'.
+
+`toolbar'
+ The valid instantiators are toolbar descriptors, which are lists
+ of toolbar-button descriptors (each of which is a vector of two or
+ four elements). *Note Toolbar::, for more information.
+
+ Color and font instance objects can also be used in turn as
+instantiators for a new color or font instance object. Since these
+instance objects are device-specific, the instantiator can be used
+directly as the new instance object, but only if they are of the same
+device. If the devices differ, the base color or font of the
+instantiating object is effectively used instead as the instantiator.
+
+ *Note Faces and Window-System Objects::, for more information on
+fonts, colors, and face-boolean specifiers. *Note Glyphs::, for more
+information about image specifiers. *Note Toolbar::, for more
+information on toolbar specifiers.
+
+ - Function: specifier-type specifier
+ This function returns the type of SPECIFIER. The returned value
+ will be a symbol: one of `integer', `boolean', etc., as listed in
+ the above table.
+
+ Functions are also provided to query whether an object is a
+particular kind of specifier:
+
+ - Function: boolean-specifier-p object
+ This function returns non-`nil' if OBJECT is a boolean specifier.
+
+ - Function: integer-specifier-p object
+ This function returns non-`nil' if OBJECT is an integer specifier.
+
+ - Function: natnum-specifier-p object
+ This function returns non-`nil' if OBJECT is a natnum specifier.
+
+ - Function: generic-specifier-p object
+ This function returns non-`nil' if OBJECT is a generic specifier.
+
+ - Function: face-boolean-specifier-p object
+ This function returns non-`nil' if OBJECT is a face-boolean
+ specifier.
+
+ - Function: toolbar-specifier-p object
+ This function returns non-`nil' if OBJECT is a toolbar specifier.
+
+ - Function: font-specifier-p object
+ This function returns non-`nil' if OBJECT is a font specifier.
+
+ - Function: color-specifier-p object
+ This function returns non-`nil' if OBJECT is a color specifier.
- This section describes how to work with font specifier and font
-instance objects, which encapsulate fonts in the window system.
+ - Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
-* Menu:
+\1f
+File: lispref.info, Node: Adding Specifications, Next: Retrieving Specifications, Prev: Specifier Types, Up: Specifiers
-* Font Specifiers:: Specifying how a font will appear.
-* Font Instances:: What a font specifier gets instanced as.
-* Font Instance Names:: The name of a font instance.
-* Font Instance Size:: The size of a font instance.
-* Font Instance Characteristics:: Display characteristics of font instances.
-* Font Convenience Functions:: Convenience functions that automatically
- instance and retrieve the properties
- of a font specifier.
+Adding specifications to a Specifier
+====================================
-\1f
-File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
+ - Function: add-spec-to-specifier specifier instantiator &optional
+ locale tag-set how-to-add
+ This function adds a specification to SPECIFIER. The
+ specification maps from LOCALE (which should be a window, buffer,
+ frame, device, or the symbol `global', and defaults to `global')
+ to INSTANTIATOR, whose allowed values depend on the type of the
+ specifier. Optional argument TAG-SET limits the instantiator to
+ apply only to the specified tag set, which should be a list of
+ tags all of which must match the device being instantiated over
+ (tags are a device type, a device class, or tags defined with
+ `define-specifier-tag'). Specifying a single symbol for TAG-SET
+ is equivalent to specifying a one-element list containing that
+ symbol. Optional argument HOW-TO-ADD specifies what to do if
+ there are already specifications in the specifier. It should be
+ one of
-Font Specifiers
----------------
+ `prepend'
+ Put at the beginning of the current list of instantiators for
+ LOCALE.
- - Function: font-specifier-p OBJECT
- This predicate returns `t' if OBJECT is a font specifier, and
- `nil' otherwise.
+ `append'
+ Add to the end of the current list of instantiators for
+ LOCALE.
+
+ `remove-tag-set-prepend'
+ This is the default. Remove any existing instantiators whose
+ tag set is the same as TAG-SET; then put the new instantiator
+ at the beginning of the current list.
+
+ `remove-tag-set-append'
+ Remove any existing instantiators whose tag set is the same as
+ TAG-SET; then put the new instantiator at the end of the
+ current list.
+
+ `remove-locale'
+ Remove all previous instantiators for this locale before
+ adding the new spec.
+
+ `remove-locale-type'
+ Remove all specifications for all locales of the same type as
+ LOCALE (this includes LOCALE itself) before adding the new
+ spec.
+
+ `remove-all'
+ Remove all specifications from the specifier before adding
+ the new spec.
+
+ `remove-tag-set-prepend' is the default.
+
+ You can retrieve the specifications for a particular locale or
+ locale type with the function `specifier-spec-list' or
+ `specifier-specs'.
+
+ - Function: add-spec-list-to-specifier specifier spec-list &optional
+ how-to-add
+ This function adds a "spec-list" (a list of specifications) to
+ SPECIFIER. The format of a spec-list is
+
+ `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'
+
+ where
+
+ * LOCALE := a window, a buffer, a frame, a device, or `global'
+
+ * TAG-SET := an unordered list of zero or more TAGS, each of
+ which is a symbol
+
+ * TAG := a device class (*note Consoles and Devices::), a
+ device type, or a tag defined with `define-specifier-tag'
+
+ * INSTANTIATOR := format determined by the type of specifier
+
+ The pair `(TAG-SET . INSTANTIATOR)' is called an "inst-pair". A
+ list of inst-pairs is called an "inst-list". The pair `(LOCALE .
+ INST-LIST)' is called a "specification". A spec-list, then, can
+ be viewed as a list of specifications.
+
+ HOW-TO-ADD specifies how to combine the new specifications with
+ the existing ones, and has the same semantics as for
+ `add-spec-to-specifier'.
+
+ In many circumstances, the higher-level function `set-specifier' is
+ more convenient and should be used instead.
+
+ - Special Form: let-specifier specifier-list &rest body
+ This special form temporarily adds specifications to specifiers,
+ evaluates forms in BODY and restores the specifiers to their
+ previous states. The specifiers and their temporary
+ specifications are listed in SPECIFIER-LIST.
+
+ The format of SPECIFIER-LIST is
+
+ ((SPECIFIER VALUE &optional LOCALE TAG-SET HOW-TO-ADD) ...)
+
+ SPECIFIER is the specifier to be temporarily modified. VALUE is
+ the instantiator to be temporarily added to specifier in LOCALE.
+ LOCALE, TAG-SET and HOW-TO-ADD have the same meaning as in
+ `add-spec-to-specifier'.
+
+ This special form is implemented as a macro; the code resulting
+ from macro expansion will add specifications to specifiers using
+ `add-spec-to-specifier'. After forms in BODY are evaluated, the
+ temporary specifications are removed and old specifier spec-lists
+ are restored.
+
+ LOCALE, TAG-SET and HOW-TO-ADD may be omitted, and default to
+ `nil'. The value of the last form in BODY is returned.
+
+ NOTE: If you want the specifier's instance to change in all
+ circumstances, use `(selected-window)' as the LOCALE. If LOCALE
+ is `nil' or omitted, it defaults to `global'.
+
+ The following example removes the 3D modeline effect in the
+ currently selected window for the duration of a second:
-\1f
-File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
+ (let-specifier ((modeline-shadow-thickness 0 (selected-window)))
+ (sit-for 1))
-Font Instances
---------------
+ - Function: set-specifier specifier value &optional locale tag-set
+ how-to-add
+ This function adds some specifications to SPECIFIER. VALUE can be
+ a single instantiator or tagged instantiator (added as a global
+ specification), a list of tagged and/or untagged instantiators
+ (added as a global specification), a cons of a locale and
+ instantiator or locale and instantiator list, a list of such
+ conses, or nearly any other reasonable form. More specifically,
+ VALUE can be anything accepted by `canonicalize-spec-list'.
- - Function: font-instance-p OBJECT
- This predicate returns `t' if OBJECT is a font instance, and `nil'
- otherwise.
+ LOCALE, TAG-SET, and HOW-TO-ADD are the same as in
+ `add-spec-to-specifier'.
- - Function: make-font-instance NAME &optional DEVICE NOERROR
- This function creates a new font-instance object of the specified
- name. DEVICE specifies the device this object applies to and
- defaults to the selected device. An error is signalled if the
- font is unknown or cannot be allocated; however, if NOERROR is
- non-`nil', `nil' is simply returned in this case.
+ Note that `set-specifier' is exactly complementary to
+ `specifier-specs' except in the case where SPECIFIER has no specs
+ at all in it but `nil' is a valid instantiator (in that case,
+ `specifier-specs' will return `nil' (meaning no specs) and
+ `set-specifier' will interpret the `nil' as meaning "I'm adding a
+ global instantiator and its value is `nil'"), or in strange cases
+ where there is an ambiguity between a spec-list and an inst-list,
+ etc. (The built-in specifier types are designed in such a way as
+ to avoid any such ambiguities.)
- The returned object is a normal, first-class lisp object. The way
- you "deallocate" the font is the way you deallocate any other lisp
- object: you drop all pointers to it and allow it to be garbage
- collected. When these objects are GCed, the underlying X data is
- deallocated as well.
+ If you want to work with spec-lists, you should probably not use
+ these functions, but should use the lower-level functions
+ `specifier-spec-list' and `add-spec-list-to-specifier'. These
+ functions always work with fully-qualified spec-lists; thus, there
+ is no ambiguity.
-\1f
-File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
+ - Function: canonicalize-inst-pair inst-pair specifier-type &optional
+ noerror
+ This function canonicalizes the given INST-PAIR.
-Font Instance Names
--------------------
+ SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+ will be used for.
- - Function: list-fonts PATTERN &optional DEVICE
- This function returns a list of font names matching the given
- pattern. DEVICE specifies which device to search for names, and
- defaults to the currently selected device.
+ Canonicalizing means converting to the full form for an inst-pair,
+ i.e. `(TAG-SET . INSTANTIATOR)'. A single, untagged instantiator
+ is given a tag set of `nil' (the empty set), and a single tag is
+ converted into a tag set consisting only of that tag.
- - Function: font-instance-name FONT-INSTANCE
- This function returns the name used to allocate FONT-INSTANCE.
+ If NOERROR is non-`nil', signal an error if the inst-pair is
+ invalid; otherwise return `t'.
- - Function: font-instance-truename FONT-INSTANCE
- This function returns the canonical name of the given font
- instance. Font names are patterns which may match any number of
- fonts, of which the first found is used. This returns an
- unambiguous name for that font (but not necessarily its only
- unambiguous name).
+ - Function: canonicalize-inst-list inst-list specifier-type &optional
+ noerror
+ This function canonicalizes the given INST-LIST (a list of
+ inst-pairs).
+
+ SPECIFIER-TYPE specifies the type of specifier that this INST-LIST
+ will be used for.
+
+ Canonicalizing means converting to the full form for an inst-list,
+ i.e. `((TAG-SET . INSTANTIATOR) ...)'. This function accepts a
+ single inst-pair or any abbreviation thereof or a list of
+ (possibly abbreviated) inst-pairs. (See `canonicalize-inst-pair'.)
+
+ If NOERROR is non-`nil', signal an error if the inst-list is
+ invalid; otherwise return `t'.
+
+ - Function: canonicalize-spec spec specifier-type &optional noerror
+ This function canonicalizes the given SPEC (a specification).
+
+ SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+ will be used for.
+
+ Canonicalizing means converting to the full form for a spec, i.e.
+ `(LOCALE (TAG-SET . INSTANTIATOR) ...)'. This function accepts a
+ possibly abbreviated inst-list or a cons of a locale and a
+ possibly abbreviated inst-list. (See `canonicalize-inst-list'.)
+
+ If NOERROR is `nil', signal an error if the specification is
+ invalid; otherwise return `t'.
+
+ - Function: canonicalize-spec-list spec-list specifier-type &optional
+ noerror
+ This function canonicalizes the given SPEC-LIST (a list of
+ specifications).
+
+ SPECIFIER-TYPE specifies the type of specifier that this SPEC-LIST
+ will be used for.
+
+ Canonicalizing means converting to the full form for a spec-list,
+ i.e. `((LOCALE (TAG-SET . INSTANTIATOR) ...) ...)'. This
+ function accepts a possibly abbreviated specification or a list of
+ such things. (See `canonicalize-spec'.) This is the function used
+ to convert spec-lists accepted by `set-specifier' and such into a
+ form suitable for `add-spec-list-to-specifier'.
+
+ This function tries extremely hard to resolve any ambiguities, and
+ the built-in specifier types (font, image, toolbar, etc.) are
+ designed so that there won't be any ambiguities.
+
+ If NOERROR is `nil', signal an error if the spec-list is invalid;
+ otherwise return `t'.
\1f
-File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
-
-Font Instance Size
-------------------
-
- - Function: x-font-size FONT
- This function returns the nominal size of the given font. This is
- done by parsing its name, so it's likely to lose. X fonts can be
- specified (by the user) in either pixels or 10ths of points, and
- this returns the first one it finds, so you have to decide which
- units the returned value is measured in yourself ...
-
- - Function: x-find-larger-font FONT &optional DEVICE
- This function loads a new, slightly larger version of the given
- font (or font name). Returns the font if it succeeds, `nil'
- otherwise. If scalable fonts are available, this returns a font
- which is 1 point larger. Otherwise, it returns the next larger
- version of this font that is defined.
-
- - Function: x-find-smaller-font FONT &optional DEVICE
- This function loads a new, slightly smaller version of the given
- font (or font name). Returns the font if it succeeds, `nil'
- otherwise. If scalable fonts are available, this returns a font
- which is 1 point smaller. Otherwise, it returns the next smaller
- version of this font that is defined.
+File: lispref.info, Node: Retrieving Specifications, Next: Specifier Tag Functions, Prev: Adding Specifications, Up: Specifiers
+
+Retrieving the Specifications from a Specifier
+==============================================
+
+ - Function: specifier-spec-list specifier &optional locale tag-set
+ exact-p
+ This function returns the spec-list of specifications for
+ SPECIFIER in LOCALE.
+
+ If LOCALE is a particular locale (a window, buffer, frame, device,
+ or the symbol `global'), a spec-list consisting of the
+ specification for that locale will be returned.
+
+ If LOCALE is a locale type (i.e. one of the symbols `window',
+ `buffer', `frame', or `device'), a spec-list of the specifications
+ for all locales of that type will be returned.
+
+ If LOCALE is `nil' or the symbol `all', a spec-list of all
+ specifications in SPECIFIER will be returned.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ the result is as if `specifier-spec-list' were called on each
+ element of the list and the results concatenated together.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ returned. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be returned.
+
+ - Function: specifier-specs specifier &optional locale tag-set exact-p
+ This function returns the specification(s) for SPECIFIER in LOCALE.
+
+ If LOCALE is a single locale or is a list of one element
+ containing a single locale, then a "short form" of the
+ instantiators for that locale will be returned. Otherwise, this
+ function is identical to `specifier-spec-list'.
+
+ The "short form" is designed for readability and not for ease of
+ use in Lisp programs, and is as follows:
+
+ 1. If there is only one instantiator, then an inst-pair (i.e.
+ cons of tag and instantiator) will be returned; otherwise a
+ list of inst-pairs will be returned.
+
+ 2. For each inst-pair returned, if the instantiator's tag is
+ `any', the tag will be removed and the instantiator itself
+ will be returned instead of the inst-pair.
+
+ 3. If there is only one instantiator, its value is `nil', and
+ its tag is `any', a one-element list containing `nil' will be
+ returned rather than just `nil', to distinguish this case
+ from there being no instantiators at all.
+
+
+ - Function: specifier-fallback specifier
+ This function returns the fallback value for SPECIFIER. Fallback
+ values are provided by the C code for certain built-in specifiers
+ to make sure that instancing won't fail even if all specs are
+ removed from the specifier, or to implement simple inheritance
+ behavior (e.g. this method is used to ensure that faces other than
+ `default' inherit their attributes from `default'). By design,
+ you cannot change the fallback value, and specifiers created with
+ `make-specifier' will never have a fallback (although a similar,
+ Lisp-accessible capability may be provided in the future to allow
+ for inheritance).
+
+ The fallback value will be an inst-list that is instanced like any
+ other inst-list, a specifier of the same type as SPECIFIER
+ (results in inheritance), or `nil' for no fallback.
+
+ When you instance a specifier, you can explicitly request that the
+ fallback not be consulted. (The C code does this, for example, when
+ merging faces.) See `specifier-instance'.
\1f
-File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
-
-Font Instance Characteristics
------------------------------
-
- - Function: font-instance-properties FONT
- This function returns the properties (an alist or `nil') of
- FONT-INSTANCE.
-
- - Function: x-make-font-bold FONT &optional DEVICE
- Given an X font specification, this attempts to make a "bold" font.
- If it fails, it returns `nil'.
-
- - Function: x-make-font-unbold FONT &optional DEVICE
- Given an X font specification, this attempts to make a non-bold
- font. If it fails, it returns `nil'.
-
- - Function: x-make-font-italic FONT &optional DEVICE
- Given an X font specification, this attempts to make an "italic"
- font. If it fails, it returns `nil'.
-
- - Function: x-make-font-unitalic FONT &optional DEVICE
- Given an X font specification, this attempts to make a non-italic
- font. If it fails, it returns `nil'.
-
- - Function: x-make-font-bold-italic FONT &optional DEVICE
- Given an X font specification, this attempts to make a
- "bold-italic" font. If it fails, it returns `nil'.
+File: lispref.info, Node: Specifier Tag Functions, Next: Specifier Instancing Functions, Prev: Retrieving Specifications, Up: Specifiers
+
+Working With Specifier Tags
+===========================
+
+ A specifier tag set is an entity that is attached to an instantiator
+and can be used to restrict the scope of that instantiator to a
+particular device class or device type and/or to mark instantiators
+added by a particular package so that they can be later removed.
+
+ A specifier tag set consists of a list of zero or more specifier
+tags, each of which is a symbol that is recognized by XEmacs as a tag.
+(The valid device types and device classes are always tags, as are any
+tags defined by `define-specifier-tag'.) It is called a "tag set" (as
+opposed to a list) because the order of the tags or the number of times
+a particular tag occurs does not matter.
+
+ Each tag has a predicate associated with it, which specifies whether
+that tag applies to a particular device. The tags which are device
+types and classes match devices of that type or class. User-defined
+tags can have any predicate, or none (meaning that all devices match).
+When attempting to instance a specifier, a particular instantiator is
+only considered if the device of the domain being instanced over matches
+all tags in the tag set attached to that instantiator.
+
+ Most of the time, a tag set is not specified, and the instantiator
+gets a null tag set, which matches all devices.
+
+ - Function: valid-specifier-tag-p tag
+ This function returns non-`nil' if TAG is a valid specifier tag.
+
+ - Function: valid-specifier-tag-set-p tag-set
+ This function returns non-`nil' if TAG-SET is a valid specifier
+ tag set.
+
+ - Function: canonicalize-tag-set tag-set
+ This function canonicalizes the given tag set. Two canonicalized
+ tag sets can be compared with `equal' to see if they represent the
+ same tag set. (Specifically, canonicalizing involves sorting by
+ symbol name and removing duplicates.)
+
+ - Function: device-matches-specifier-tag-set-p device tag-set
+ This function returns non-`nil' if DEVICE matches specifier tag
+ set TAG-SET. This means that DEVICE matches each tag in the tag
+ set.
+
+ - Function: define-specifier-tag tag &optional predicate
+ This function defines a new specifier tag. If PREDICATE is
+ specified, it should be a function of one argument (a device) that
+ specifies whether the tag matches that particular device. If
+ PREDICATE is omitted, the tag matches all devices.
+
+ You can redefine an existing user-defined specifier tag. However,
+ you cannot redefine the built-in specifier tags (the device types
+ and classes) or the symbols `nil', `t', `all', or `global'.
+
+ - Function: device-matching-specifier-tag-list &optional device
+ This function returns a list of all specifier tags matching
+ DEVICE. DEVICE defaults to the selected device if omitted.
+
+ - Function: specifier-tag-list
+ This function returns a list of all currently-defined specifier
+ tags. This includes the built-in ones (the device types and
+ classes).
+
+ - Function: specifier-tag-predicate tag
+ This function returns the predicate for the given specifier tag.
\1f
-File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
-
-Font Convenience Functions
---------------------------
-
- - Function: font-name FONT &optional DOMAIN
- This function returns the name of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-name' to the result.
-
- - Function: font-truename FONT &optional DOMAIN
- This function returns the truename of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-truename' to the result.
-
- - Function: font-properties FONT &optional DOMAIN
- This function returns the properties of the FONT in the specified
- DOMAIN, if any. FONT should be a font specifier object and DOMAIN
- is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `font-instance-properties' to the result.
+File: lispref.info, Node: Specifier Instancing Functions, Next: Specifier Example, Prev: Specifier Tag Functions, Up: Specifiers
+
+Functions for Instancing a Specifier
+====================================
+
+ - Function: specifier-instance specifier &optional domain default
+ no-fallback
+ This function instantiates SPECIFIER (return its value) in DOMAIN.
+ If no instance can be generated for this domain, return DEFAULT.
+
+ DOMAIN should be a window, frame, or device. Other values that
+ are legal as a locale (e.g. a buffer) are not valid as a domain
+ because they do not provide enough information to identify a
+ particular device (see `valid-specifier-domain-p'). DOMAIN
+ defaults to the selected window if omitted.
+
+ "Instantiating" a specifier in a particular domain means
+ determining the specifier's "value" in that domain. This is
+ accomplished by searching through the specifications in the
+ specifier that correspond to all locales that can be derived from
+ the given domain, from specific to general. In most cases, the
+ domain is an Emacs window. In that case specifications are
+ searched for as follows:
+
+ 1. A specification whose locale is the window itself;
+
+ 2. A specification whose locale is the window's buffer;
+
+ 3. A specification whose locale is the window's frame;
+
+ 4. A specification whose locale is the window's frame's device;
+
+ 5. A specification whose locale is the symbol `global'.
+
+ If all of those fail, then the C-code-provided fallback value for
+ this specifier is consulted (see `specifier-fallback'). If it is
+ an inst-list, then this function attempts to instantiate that list
+ just as when a specification is located in the first five steps
+ above. If the fallback is a specifier, `specifier-instance' is
+ called recursively on this specifier and the return value used.
+ Note, however, that if the optional argument NO-FALLBACK is
+ non-`nil', the fallback value will not be consulted.
+
+ Note that there may be more than one specification matching a
+ particular locale; all such specifications are considered before
+ looking for any specifications for more general locales. Any
+ particular specification that is found may be rejected because it
+ is tagged to a particular device class (e.g. `color') or device
+ type (e.g. `x') or both and the device for the given domain does
+ not match this, or because the specification is not valid for the
+ device of the given domain (e.g. the font or color name does not
+ exist for this particular X server).
+
+ The returned value is dependent on the type of specifier. For
+ example, for a font specifier (as returned by the `face-font'
+ function), the returned value will be a font-instance object. For
+ images, the returned value will be a string, pixmap, or subwindow.
+
+ - Function: specifier-instance-from-inst-list specifier domain
+ inst-list &optional default
+ This function attempts to convert a particular inst-list into an
+ instance. This attempts to instantiate INST-LIST in the given
+ DOMAIN, as if INST-LIST existed in a specification in SPECIFIER.
+ If the instantiation fails, DEFAULT is returned. In most
+ circumstances, you should not use this function; use
+ `specifier-instance' instead.
\1f
-File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
-
-Colors
-======
-
-* Menu:
-
-* Color Specifiers:: Specifying how a color will appear.
-* Color Instances:: What a color specifier gets instanced as.
-* Color Instance Properties:: Properties of color instances.
-* Color Convenience Functions:: Convenience functions that automatically
- instance and retrieve the properties
- of a color specifier.
+File: lispref.info, Node: Specifier Example, Next: Creating Specifiers, Prev: Specifier Instancing Functions, Up: Specifiers
+
+Example of Specifier Usage
+==========================
+
+ Now let us present an example to clarify the theoretical discussions
+we have been through. In this example, we will use the general
+specifier functions for clarity. Keep in mind that many types of
+specifiers, and some other types of objects that are associated with
+specifiers (e.g. faces), provide convenience functions making it easier
+to work with objects of that type.
+
+ Let us consider the background color of the default face. A
+specifier is used to specify how that color will appear in different
+domains. First, let's retrieve the specifier:
+
+ (setq sp (face-property 'default 'background))
+ => #<color-specifier 0x3da>
+
+ (specifier-specs sp)
+ => ((#<buffer "device.c"> (nil . "forest green"))
+ (#<window on "Makefile" 0x8a2b> (nil . "hot pink"))
+ (#<x-frame "emacs" 0x4ac> (nil . "puke orange")
+ (nil . "moccasin"))
+ (#<x-frame "VM" 0x4ac> (nil . "magenta"))
+ (global ((tty) . "cyan") (nil . "white"))
+ )
+
+ Then, say we want to determine what the background color of the
+default face is for the window currently displaying the buffer
+`*scratch*'. We call
+
+ (get-buffer-window "*scratch*")
+ => #<window on "*scratch*" 0x4ad>
+ (window-frame (get-buffer-window "*scratch*"))
+ => #<x-frame "emacs" 0x4ac>
+ (specifier-instance sp (get-buffer-window "*scratch*"))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x6309>
+
+ Note that we passed a window to `specifier-instance', not a buffer.
+We cannot pass a buffer because a buffer by itself does not provide
+enough information. The buffer might not be displayed anywhere at all,
+or could be displayed in many different frames on different devices.
+
+ The result is arrived at like this:
+
+ 1. First, we look for a specification matching the buffer displayed
+ in the window, i.e. `*scratch*'. There are none, so we proceed.
+
+ 2. Then, we look for a specification matching the window itself.
+ Again, there are none.
+
+ 3. Then, we look for a specification matching the window's frame. The
+ specification `(#<x-frame "emacs" 0x4ac> . "puke orange")' is
+ found. We call the instantiation method for colors, passing it the
+ locale we were searching over (i.e. the window, in this case) and
+ the instantiator (`"puke orange"'). However, the particular device
+ which this window is on (let's say it's an X connection) doesn't
+ recognize the color `"puke orange"', so the specification is
+ rejected.
+
+ 4. So we continue looking for a specification matching the window's
+ frame. We find `(#<x-frame "emacs" 0x4ac> . "moccasin")'. Again,
+ we call the instantiation method for colors. This time, the X
+ server our window is on recognizes the color `moccasin', and so the
+ instantiation method succeeds and returns a color instance.
\1f
-File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
-
-Color Specifiers
-----------------
-
- - Function: color-specifier-p OBJECT
- This function returns non-`nil' if OBJECT is a color specifier.
+File: lispref.info, Node: Creating Specifiers, Next: Specifier Validation Functions, Prev: Specifier Example, Up: Specifiers
+
+Creating New Specifier Objects
+==============================
+
+ - Function: make-specifier type
+ This function creates a new specifier.
+
+ A specifier is an object that can be used to keep track of a
+ property whose value can be per-buffer, per-window, per-frame, or
+ per-device, and can further be restricted to a particular
+ device-type or device-class. Specifiers are used, for example,
+ for the various built-in properties of a face; this allows a face
+ to have different values in different frames, buffers, etc. For
+ more information, see `specifier-instance', `specifier-specs', and
+ `add-spec-to-specifier'; or, for a detailed description of
+ specifiers, including how they are instantiated over a particular
+ domain (i.e. how their value in that domain is determined), see
+ the chapter on specifiers in the XEmacs Lisp Reference Manual.
+
+ TYPE specifies the particular type of specifier, and should be one
+ of the symbols `generic', `integer', `natnum', `boolean', `color',
+ `font', `image', `face-boolean', or `toolbar'.
+
+ For more information on particular types of specifiers, see the
+ functions `make-generic-specifier', `make-integer-specifier',
+ `make-natnum-specifier', `make-boolean-specifier',
+ `make-color-specifier', `make-font-specifier',
+ `make-image-specifier', `make-face-boolean-specifier', and
+ `make-toolbar-specifier'.
+
+ - Function: make-specifier-and-init type spec-list &optional
+ dont-canonicalize
+ This function creates and initialize a new specifier.
+
+ This is a front-end onto `make-specifier' that allows you to create
+ a specifier and add specs to it at the same time. TYPE specifies
+ the specifier type. SPEC-LIST supplies the specification(s) to be
+ added to the specifier. Normally, almost any reasonable
+ abbreviation of the full spec-list form is accepted, and is
+ converted to the full form; however, if optional argument
+ DONT-CANONICALIZE is non-`nil', this conversion is not performed,
+ and the SPEC-LIST must already be in full form. See
+ `canonicalize-spec-list'.
+
+ - Function: make-integer-specifier spec-list
+ Return a new `integer' specifier object with the given
+ specification list. SPEC-LIST can be a list of specifications
+ (each of which is a cons of a locale and a list of instantiators),
+ a single instantiator, or a list of instantiators.
+
+ Valid instantiators for integer specifiers are integers.
+
+ - Function: make-boolean-specifier spec-list
+ Return a new `boolean' specifier object with the given
+ specification list. SPEC-LIST can be a list of specifications
+ (each of which is a cons of a locale and a list of instantiators),
+ a single instantiator, or a list of instantiators.
+
+ Valid instantiators for boolean specifiers are `t' and `nil'.
+
+ - Function: make-natnum-specifier spec-list
+ Return a new `natnum' specifier object with the given specification
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators.
+
+ Valid instantiators for natnum specifiers are non-negative
+ integers.
+
+ - Function: make-generic-specifier spec-list
+ Return a new `generic' specifier object with the given
+ specification list. SPEC-LIST can be a list of specifications
+ (each of which is a cons of a locale and a list of instantiators),
+ a single instantiator, or a list of instantiators.
+
+ Valid instantiators for generic specifiers are all Lisp values.
+ They are returned back unchanged when a specifier is instantiated.
+
+ - Function: make-display-table-specifier spec-list
+ Return a new `display-table' specifier object with the given spec
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators.
+
+ Valid instantiators for display-table specifiers are described in
+ detail in the doc string for `current-display-table' (*note Active
+ Display Table::).
\1f
-File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+File: lispref.info, Node: Specifier Validation Functions, Next: Other Specification Functions, Prev: Creating Specifiers, Up: Specifiers
-Color Instances
----------------
+Functions for Checking the Validity of Specifier Components
+===========================================================
- A "color-instance object" is an object describing the way a color
-specifier is instanced in a particular domain. Functions such as
-`face-background-instance' return a color-instance object. For example,
+ - Function: valid-specifier-domain-p domain
+ This function returns non-`nil' if DOMAIN is a valid specifier
+ domain. A domain is used to instance a specifier (i.e. determine
+ the specifier's value in that domain). Valid domains are a
+ window, frame, or device. (`nil' is not valid.)
- (face-background-instance 'default (next-window))
- => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+ - Function: valid-specifier-locale-p locale
+ This function returns non-`nil' if LOCALE is a valid specifier
+ locale. Valid locales are a device, a frame, a window, a buffer,
+ and `global'. (`nil' is not valid.)
- The color-instance object returned describes the way the background
-color of the `default' face is displayed in the next window after the
-selected one.
+ - Function: valid-specifier-locale-type-p locale-type
+ Given a specifier LOCALE-TYPE, this function returns non-`nil' if
+ it is valid. Valid locale types are the symbols `global',
+ `device', `frame', `window', and `buffer'. (Note, however, that in
+ functions that accept either a locale or a locale type, `global'
+ is considered an individual locale.)
- - Function: color-instance-p OBJECT
- This function returns non-`nil' if OBJECT is a color-instance.
+ - Function: valid-specifier-type-p specifier-type
+ Given a SPECIFIER-TYPE, this function returns non-`nil' if it is
+ valid. Valid types are `generic', `integer', `boolean', `color',
+ `font', `image', `face-boolean', and `toolbar'.
-\1f
-File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-
-Color Instance Properties
--------------------------
+ - Function: valid-specifier-tag-p tag
+ This function returns non-`nil' if TAG is a valid specifier tag.
- - Function: color-instance-name COLOR-INSTANCE
- This function returns the name used to allocate COLOR-INSTANCE.
+ - Function: valid-instantiator-p instantiator specifier-type
+ This function returns non-`nil' if INSTANTIATOR is valid for
+ SPECIFIER-TYPE.
- - Function: color-instance-rgb-components COLOR-INSTANCE
- This function returns a three element list containing the red,
- green, and blue color components of COLOR-INSTANCE.
+ - Function: valid-inst-list-p inst-list type
+ This function returns non-`nil' if INST-LIST is valid for
+ specifier type TYPE.
- (color-instance-rgb-components
- (face-background-instance 'default (next-window)))
- => (65535 58596 46517)
-
-\1f
-File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+ - Function: valid-spec-list-p spec-list type
+ This function returns non-`nil' if SPEC-LIST is valid for
+ specifier type TYPE.
-Color Convenience Functions
----------------------------
+ - Function: check-valid-instantiator instantiator specifier-type
+ This function signals an error if INSTANTIATOR is invalid for
+ SPECIFIER-TYPE.
- - Function: color-name COLOR &optional DOMAIN
- This function returns the name of the COLOR in the specified
- DOMAIN, if any. COLOR should be a color specifier object and
- DOMAIN is normally a window and defaults to the selected window if
- omitted. This is equivalent to using `specifier-instance' and
- applying `color-instance-name' to the result.
+ - Function: check-valid-inst-list inst-list type
+ This function signals an error if INST-LIST is invalid for
+ specifier type TYPE.
- - Function: color-rgb-components COLOR &optional DOMAIN
- This function returns the RGB components of the COLOR in the
- specified DOMAIN, if any. COLOR should be a color specifier
- object and DOMAIN is normally a window and defaults to the
- selected window if omitted. This is equivalent to using
- `specifier-instance' and applying `color-instance-rgb-components'
- to the result.
-
- (color-rgb-components (face-background 'default (next-window)))
- => (65535 58596 46517)
+ - Function: check-valid-spec-list spec-list type
+ This function signals an error if SPEC-LIST is invalid for
+ specifier type TYPE.
\1f
-File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
-
-Glyphs
-******
-
- A "glyph" is an object that is used for pixmaps and images of all
-sorts, as well as for things that "act" like pixmaps, such as
-non-textual strings ("annotations") displayed in a buffer or in the
-margins. It is used in begin-glyphs and end-glyphs attached to extents,
-marginal and textual annotations, overlay arrows (`overlay-arrow-*'
-variables), toolbar buttons, mouse pointers, frame icons, truncation and
-continuation markers, and the like. (Basically, any place there is an
-image or something that acts like an image, there will be a glyph object
-representing it.)
-
- The actual image that is displayed (as opposed to its position or
-clipping) is defined by an "image specifier" object contained within
-the glyph. The separation between an image specifier object and a
-glyph object is made because the glyph includes other properties than
-just the actual image: e.g. the face it is displayed in (for text
-images), the alignment of the image (when it is in a buffer), etc.
-
- - Function: glyphp OBJECT
- This function returns `t' if OBJECT is a glyph.
-
-* Menu:
-
-* Glyph Functions:: Functions for working with glyphs.
-* Images:: Graphical images displayed in a frame.
-* Glyph Types:: Each glyph has a particular type.
-* Mouse Pointer:: Controlling the mouse pointer.
-* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
-* Subwindows:: Inserting an externally-controlled subwindow
- into a buffer.
+File: lispref.info, Node: Other Specification Functions, Prev: Specifier Validation Functions, Up: Specifiers
+
+Other Functions for Working with Specifications in a Specifier
+==============================================================
+
+ - Function: copy-specifier specifier &optional dest locale tag-set
+ exact-p how-to-add
+ This function copies SPECIFIER to DEST, or creates a new one if
+ DEST is `nil'.
+
+ If DEST is `nil' or omitted, a new specifier will be created and
+ the specifications copied into it. Otherwise, the specifications
+ will be copied into the existing specifier in DEST.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ copied. If LOCALE is a particular locale, the specification for
+ that particular locale will be copied. If LOCALE is a locale
+ type, the specifications for all locales of that type will be
+ copied. LOCALE can also be a list of locales, locale types,
+ and/or `all'; this is equivalent to calling `copy-specifier' for
+ each of the elements of the list. See `specifier-spec-list' for
+ more information about LOCALE.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ copied. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be copied.
+
+ Optional argument HOW-TO-ADD specifies what to do with existing
+ specifications in DEST. If `nil', then whichever locales or locale
+ types are copied will first be completely erased in DEST.
+ Otherwise, it is the same as in `add-spec-to-specifier'.
+
+ - Function: remove-specifier specifier &optional locale tag-set exact-p
+ This function removes specification(s) for SPECIFIER.
+
+ If LOCALE is a particular locale (a buffer, window, frame, device,
+ or the symbol `global'), the specification for that locale will be
+ removed.
+
+ If instead, LOCALE is a locale type (i.e. a symbol `buffer',
+ `window', `frame', or `device'), the specifications for all
+ locales of that type will be removed.
+
+ If LOCALE is `nil' or the symbol `all', all specifications will be
+ removed.
+
+ LOCALE can also be a list of locales, locale types, and/or `all';
+ this is equivalent to calling `remove-specifier' for each of the
+ elements in the list.
+
+ Only instantiators where TAG-SET (a list of zero or more tags) is
+ a subset of (or possibly equal to) the instantiator's tag set are
+ removed. (The default value of `nil' is a subset of all tag sets,
+ so in this case no instantiators will be screened out.) If EXACT-P
+ is non-`nil', however, TAG-SET must be equal to an instantiator's
+ tag set for the instantiator to be removed.
+
+ - Function: map-specifier specifier func &optional locale maparg
+ This function applies FUNC to the specification(s) for LOCALE in
+ SPECIFIER.
+
+ If LOCALE is a locale, FUNC will be called for that locale. If
+ LOCALE is a locale type, FUNC will be mapped over all locales of
+ that type. If LOCALE is `nil' or the symbol `all', FUNC will be
+ mapped over all locales in SPECIFIER.
+
+ FUNC is called with four arguments: the SPECIFIER, the locale
+ being mapped over, the inst-list for that locale, and the optional
+ MAPARG. If any invocation of FUNC returns non-`nil', the mapping
+ will stop and the returned value becomes the value returned from
+ `map-specifier'. Otherwise, `map-specifier' returns `nil'.
+
+ - Function: specifier-locale-type-from-locale locale
+ Given a specifier LOCALE, this function returns its type.
\1f
-File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
+File: lispref.info, Node: Faces and Window-System Objects, Next: Glyphs, Prev: Specifiers, Up: Top
-Glyph Functions
-===============
+Faces and Window-System Objects
+*******************************
* Menu:
-* Creating Glyphs:: Creating new glyphs.
-* Glyph Properties:: Accessing and modifying a glyph's properties.
-* Glyph Convenience Functions::
- Convenience functions for accessing particular
- properties of a glyph.
-* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
-
-\1f
-File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
-
-Creating Glyphs
----------------
-
- - Function: make-glyph &optional SPEC-LIST TYPE
- This function creates a new glyph object of type TYPE.
-
- SPEC-LIST is used to initialize the glyph's image. It is
- typically an image instantiator (a string or a vector; *Note Image
- Specifiers::), but can also be a list of such instantiators (each
- one in turn is tried until an image is successfully produced), a
- cons of a locale (frame, buffer, etc.) and an instantiator, a list
- of such conses, or any other form accepted by
- `canonicalize-spec-list'. *Note Specifiers::, for more
- information about specifiers.
-
- TYPE specifies the type of the glyph, which specifies in which
- contexts the glyph can be used, and controls the allowable image
- types into which the glyph's image can be instantiated. TYPE
- should be one of `buffer' (used for glyphs in an extent, the
- modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
- for the mouse-pointer), or `icon' (used for a frame's icon), and
- defaults to `buffer'. *Note Glyph Types::.
-
- - Function: make-glyph-internal &optional TYPE
- This function creates a new, uninitialized glyph of type TYPE.
-
- - Function: make-pointer-glyph &optional SPEC-LIST
- This function is equivalent to calling `make-glyph' with a TYPE of
- `pointer'.
-
- - Function: make-icon-glyph &optional SPEC-LIST
- This function is equivalent to calling `make-glyph' with a TYPE of
- `icon'.
-
-\1f
-File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
-
-Glyph Properties
-----------------
-
- Each glyph has a list of properties, which control all of the
-aspects of the glyph's appearance. The following symbols have
-predefined meanings:
-
-`image'
- The image used to display the glyph.
-
-`baseline'
- Percent above baseline that glyph is to be displayed. Only for
- glyphs displayed inside of a buffer.
-
-`contrib-p'
- Whether the glyph contributes to the height of the line it's on.
- Only for glyphs displayed inside of a buffer.
-
-`face'
- Face of this glyph (*not* a specifier).
-
- - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
- TAG-SET HOW-TO-ADD
- This function changes a property of a GLYPH.
-
- For built-in properties, the actual value of the property is a
- specifier and you cannot change this; but you can change the
- specifications within the specifier, and that is what this
- function will do. For user-defined properties, you can use this
- function to either change the actual value of the property or, if
- this value is a specifier, change the specifications within it.
-
- If PROPERTY is a built-in property, the specifications to be added
- to this property can be supplied in many different ways:
-
- * If VALUE is a simple instantiator (e.g. a string naming a
- pixmap filename) or a list of instantiators, then the
- instantiator(s) will be added as a specification of the
- property for the given LOCALE (which defaults to `global' if
- omitted).
-
- * If VALUE is a list of specifications (each of which is a cons
- of a locale and a list of instantiators), then LOCALE must be
- `nil' (it does not make sense to explicitly specify a locale
- in this case), and specifications will be added as given.
-
- * If VALUE is a specifier (as would be returned by
- `glyph-property' if no LOCALE argument is given), then some
- or all of the specifications in the specifier will be added
- to the property. In this case, the function is really
- equivalent to `copy-specifier' and LOCALE has the same
- semantics (if it is a particular locale, the specification
- for the locale will be copied; if a locale type,
- specifications for all locales of that type will be copied;
- if `nil' or `all', then all specifications will be copied).
-
- HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
- `append', `remove-tag-set-prepend', `remove-tag-set-append',
- `remove-locale', `remove-locale-type', or `remove-all'. See
- `copy-specifier' and `add-spec-to-specifier' for a description of
- what each of these means. Most of the time, you do not need to
- worry about this argument; the default behavior usually is fine.
-
- In general, it is OK to pass an instance object (e.g. as returned
- by `glyph-property-instance') as an instantiator in place of an
- actual instantiator. In such a case, the instantiator used to
- create that instance object will be used (for example, if you set
- a font-instance object as the value of the `font' property, then
- the font name used to create that object will be used instead).
- If some cases, however, doing this conversion does not make sense,
- and this will be noted in the documentation for particular types
- of instance objects.
-
- If PROPERTY is not a built-in property, then this function will
- simply set its value if LOCALE is `nil'. However, if LOCALE is
- given, then this function will attempt to add VALUE as the
- instantiator for the given LOCALE, using `add-spec-to-specifier'.
- If the value of the property is not a specifier, it will
- automatically be converted into a `generic' specifier.
-
- - Function: glyph-property GLYPH PROPERTY &optional LOCALE
- This function returns GLYPH's value of the given PROPERTY.
-
- If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
- be returned. For built-in properties, this will be a specifier
- object of a type appropriate to the property (e.g. a font or color
- specifier). For other properties, this could be anything.
-
- If LOCALE is supplied, then instead of returning the actual value,
- the specification(s) for the given locale or locale type will be
- returned. This will only work if the actual value of PROPERTY is
- a specifier (this will always be the case for built-in properties,
- but may or may not apply to user-defined properties). If the
- actual value of PROPERTY is not a specifier, this value will
- simply be returned regardless of LOCALE.
-
- The return value will be a list of instantiators (e.g. vectors
- specifying pixmap data), or a list of specifications, each of
- which is a cons of a locale and a list of instantiators.
- Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or `global'), a list of instantiators for that
- locale will be returned. Otherwise, if LOCALE is a locale type
- (one of the symbols `buffer', `window', `frame', or `device'), the
- specifications for all locales of that type will be returned.
- Finally, if LOCALE is `all', the specifications for all locales of
- all types will be returned.
-
- The specifications in a specifier determine what the value of
- PROPERTY will be in a particular "domain" or set of circumstances,
- which is typically a particular Emacs window along with the buffer
- it contains and the frame and device it lies within. The value is
- derived from the instantiator associated with the most specific
- locale (in the order buffer, window, frame, device, and `global')
- that matches the domain in question. In other words, given a
- domain (i.e. an Emacs window, usually), the specifier for PROPERTY
- will first be searched for a specification whose locale is the
- buffer contained within that window; then for a specification
- whose locale is the window itself; then for a specification whose
- locale is the frame that the window is contained within; etc. The
- first instantiator that is valid for the domain (usually this
- means that the instantiator is recognized by the device [i.e. the
- X server or TTY device] that the domain is on). The function
- `glyph-property-instance' actually does all this, and is used to
- determine how to display the glyph.
-
- - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
- DEFAULT NO-FALLBACK
- This function returns the instance of GLYPH's PROPERTY in the
- specified DOMAIN.
-
- Under most circumstances, DOMAIN will be a particular window, and
- the returned instance describes how the specified property
- actually is displayed for that window and the particular buffer in
- it. Note that this may not be the same as how the property
- appears when the buffer is displayed in a different window or
- frame, or how the property appears in the same window if you
- switch to another buffer in that window; and in those cases, the
- returned instance would be different.
-
- The returned instance is an image-instance object, and you can
- query it using the appropriate image instance functions. For
- example, you could use `image-instance-depth' to find out the
- depth (number of color planes) of a pixmap displayed in a
- particular window. The results might be different from the
- results you would get for another window (perhaps the user
- specified a different image for the frame that window is on; or
- perhaps the same image was specified but the window is on a
- different X server, and that X server has different color
- capabilities from this one).
-
- DOMAIN defaults to the selected window if omitted.
-
- DOMAIN can be a frame or device, instead of a window. The value
- returned for such a domain is used in special circumstances when a
- more specific domain does not apply; for example, a frame value
- might be used for coloring a toolbar, which is conceptually
- attached to a frame rather than a particular window. The value is
- also useful in determining what the value would be for a
- particular window within the frame or device, if it is not
- overridden by a more specific specification.
-
- If PROPERTY does not name a built-in property, its value will
- simply be returned unless it is a specifier object, in which case
- it will be instanced using `specifier-instance'.
-
- Optional arguments DEFAULT and NO-FALLBACK are the same as in
- `specifier-instance'. *Note Specifiers::.
-
- - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
- TAG-SET EXACT-P
- This function removes a property from a glyph. For built-in
- properties, this is analogous to `remove-specifier'. *Note
- remove-specifier-p: Specifiers, for the meaning of the LOCALE,
- TAG-SET, and EXACT-P arguments.
-
-\1f
-File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
-
-Glyph Convenience Functions
----------------------------
-
- The following functions are provided for working with specific
-properties of a glyph. Note that these are exactly like calling the
-general functions described above and passing in the appropriate value
-for PROPERTY.
-
- Remember that if you want to determine the "value" of a specific
-glyph property, you probably want to use the `*-instance' functions.
-For example, to determine whether a glyph contributes to its line
-height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
-latter will return a boolean specifier or a list of specifications, and
-you probably aren't concerned with these.)
-
- - Function: glyph-image GLYPH &optional LOCALE
- This function is equivalent to calling `glyph-property' with a
- property of `image'. The return value will be an image specifier
- if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
-
- - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
- This function is equivalent to calling `set-glyph-property' with a
- property of `image'.
-
- - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
- This function returns the instance of GLYPH's image in the given
- DOMAIN, and is equivalent to calling `glyph-property-instance'
- with a property of `image'. The return value will be an image
- instance.
-
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing how the image appears
- in that particular window and buffer will be returned.
-
- - Function: glyph-contrib-p GLYPH &optional LOCALE
- This function is equivalent to calling `glyph-property' with a
- property of `contrib-p'. The return value will be a boolean
- specifier if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
-
- - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
- This function is equivalent to calling `set-glyph-property' with a
- property of `contrib-p'.
-
- - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
- This function returns whether the glyph contributes to its line
- height in the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `contrib-p'. The
- return value will be either `nil' or `t'. (Normally DOMAIN will be
- a window or `nil', meaning the selected window.)
-
- - Function: glyph-baseline GLYPH &optional LOCALE
- This function is equivalent to calling `glyph-property' with a
- property of `baseline'. The return value will be a specifier if
- LOCALE is `nil' or omitted; otherwise, it will be a specification
- or list of specifications.
-
- - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
- HOW-TO-ADD
- This function is equivalent to calling `set-glyph-property' with a
- property of `baseline'.
-
- - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
- NO-FALLBACK
- This function returns the instance of GLYPH's baseline value in
- the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `baseline'. The
- return value will be an integer or `nil'.
-
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing the baseline value
- appears in that particular window and buffer will be returned.
-
- - Function: glyph-face GLYPH
- This function returns the face of GLYPH. (Remember, this is not a
- specifier, but a simple property.)
-
- - Function: set-glyph-face GLYPH FACE
- This function changes the face of GLYPH to FACE.
+* Faces:: Controlling the way text looks.
+* Fonts:: Controlling the typeface of text.
+* Colors:: Controlling the color of text and pixmaps.
\1f
-File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+File: lispref.info, Node: Faces, Next: Fonts, Up: Faces and Window-System Objects
-Glyph Dimensions
-----------------
-
- - Function: glyph-width GLYPH &optional WINDOW
- This function returns the width of GLYPH on WINDOW. This may not
- be exact as it does not take into account all of the context that
- redisplay will.
-
- - Function: glyph-ascent GLYPH &optional WINDOW
- This function returns the ascent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
-
- - Function: glyph-descent GLYPH &optional WINDOW
- This function returns the descent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
-
- - Function: glyph-height GLYPH &optional WINDOW
- This function returns the height of GLYPH on WINDOW. (This is
- equivalent to the sum of the ascent and descent values.) This may
- not be exact as it does not take into account all of the context
- that redisplay will.
-
-\1f
-File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+Faces
+=====
-Images
-======
+ A "face" is a named collection of graphical properties: font,
+foreground color, background color, background pixmap, optional
+underlining, and (on TTY devices) whether the text is to be highlighted,
+dimmed, blinking, or displayed in reverse video. Faces control the
+display of text on the screen. Every face has a name, which is a symbol
+such as `default' or `modeline'.
+
+ Each built-in property of a face is controlled using a specifier,
+which allows it to have separate values in particular buffers, frames,
+windows, and devices and to further vary according to device type (X or
+TTY) and device class (color, mono, or grayscale). *Note Specifiers::,
+for more information.
+
+ The face named `default' is used for ordinary text. The face named
+`modeline' is used for displaying the modeline. The face named
+`highlight' is used for highlighted extents (*note Extents::). The
+faces named `left-margin' and `right-margin' are used for the left and
+right margin areas, respectively (*note Annotations::). The face named
+`zmacs-region' is used for the highlighted region between point and
+mark.
* Menu:
-* Image Specifiers:: Specifying how an image will appear.
-* Image Instantiator Conversion::
- Conversion is applied to image instantiators
- at the time they are added to an
- image specifier or at the time they
- are passed to `make-image-instance'.
-* Image Instances:: What an image specifier gets instanced as.
+* Merging Faces:: How XEmacs decides which face to use
+ for a character.
+* Basic Face Functions:: How to define and examine faces.
+* Face Properties:: How to access and modify a face's properties.
+* Face Convenience Functions:: Convenience functions for accessing
+ particular properties of a face.
+* Other Face Display Functions:: Other functions pertaining to how a
+ a face appears.
projects / chise / xemacs-chise.git- / blobdiff