48.9 Functions for Instancing a Specifier

Function: specifier-instance specifier &optional domain default no-fallback

This function instantiates specifier (returns 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 SXEmacs 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-matching-instance specifier matchspec &optional domain default no-fallback

This function returns an instance for specifier in domain that matches matchspec. If no instance can be generated for domain, return default.

This function is identical to specifier-instance except that a specification will only be considered if it matches matchspec. The definition of “match,” and allowed values for matchspec, are dependent on the particular type of specifier. Here are some examples:

• For chartable (e.g. display table) specifiers, matchspec should be a character, and the specification (a chartable) must give a value for that character in order to be considered. This allows you to specify, e.g., a buffer-local display table that only gives values for particular characters. All other characters are handled as if the buffer-local display table is not there. (Chartable specifiers are not yet implemented.)
• For font specifiers, matchspec should be a charset, and the specification (a font string) must have a registry that matches the charset’s registry. (This only makes sense with Mule support.) This makes it easy to choose a font that can display a particular character. (This is what redisplay does, in fact.)

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.