49.1.3 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 GUI devices, currently X11, and GTK.

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-set 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: remove-face-property face property &optional locale tag-set exact-p

This function removes a property of a face.

For built-in properties, this is analogous to remove-specifier. For more information, See Other Specification Functions.

When property is not a built-in property, this function will just remove its value if locale is nil or all. However, if locale is other than that, this function will attempt to remove value as the instantiator for the given locale with remove-specifier. If the value of the property is not a specifier, it will be converted into a generic specifier automatically.

Function: face-property face property &optional locale tag-set exact-p

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. See Specifiers.