[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49. Faces and Window-System Objects


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.1 Faces

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. These properties are computed when the face is instantiated, allowing them to vary according to properties of the display device, such as type (X or TTY), visual class (color, mono, or grayscale), and number of colors displayable on the device. See section Specifiers, for more information on specifiers. See section Face Definitions, for defining faces whose properties vary according to their runtime environments.

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 (see section Extents). The faces named left-margin and right-margin are used for the left and right margin areas, respectively (see section Annotations). The face named zmacs-region is used for the highlighted region between point and mark.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.1.1 Merging Faces for Display

Here are all the ways to specify which face to use for display of text:

If these various sources together specify more than one face for a particular character, XEmacs merges the properties of the various faces specified. Extents, text properties, and annotations all use the same underlying representation (as extents). When multiple extents cover one character, an extent with higher priority overrides those with lower priority. See section Extents. If no extent covers a particular character, the default face is used.

If a background pixmap is specified, it determines what will be displayed in the background of text characters. If the background pixmap is actually a pixmap, with its colors specified, those colors are used; if it is a bitmap, the face’s foreground and background colors are used to color it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.1.2 Basic Functions for Working with Faces

The properties a face can specify include the font, the foreground color, the background color, the background pixmap, the underlining, the display table, and (for TTY devices) whether the text is to be highlighted, dimmed, blinking, or displayed in reverse video. The face can also leave these unspecified, causing them to assume the value of the corresponding property of the default face.

Here are the basic primitives for working with faces.

Function: make-face name &optional doc-string temporary

This function defines and returns a new face named name, initially with all properties unspecified. It does nothing if there is already a face named name. Optional argument doc-string specifies an explanatory string used for descriptive purposes. If optional argument temporary is non-nil, the face will automatically disappear when there are no more references to it anywhere in text or Lisp code (otherwise, the face will continue to exist indefinitely even if it is not used).

Function: face-list &optional temporary

This function returns a list of the names of all defined faces. If temporary is nil, only the permanent faces are included. If it is t, only the temporary faces are included. If it is any other non-nil value both permanent and temporary are included.

Function: facep object

This function returns t if object is a face, else nil.

Function: copy-face old-face new-name &optional locale tag-set exact-p how-to-add

This function defines a new face named new-name which is a copy of the existing face named old-face. If there is already a face named new-name, then it alters the face to have the same properties as old-face.

locale, tag-set, exact-p and how-to-add let you copy just parts of the old face rather than the whole face, and are as in copy-specifier (see section Specifiers).

Finally, you have the possibility to give faces different names by means of aliases. One typical use of this feature is to change the name of a face while preserving backward compatibility. If a symbol has the face-alias property set to another symbol, then this other symbol will be used as the real face name instead. Recursive aliases (aliases of aliases) are allowed, but the depth of indirection is limited to 32 to prevent alias loops.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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, GTK, and Microsoft Windows.

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:

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 section Other Functions for Working with Specifications in a Specifier.

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


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.1.4 Face Convenience Functions

Command: set-face-foreground face color &optional locale tag-set how-to-add
Command: set-face-background face color &optional locale tag-set 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 (see section Colors).

Command: set-face-background-pixmap face pixmap &optional locale tag-set 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 (see section 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.

Similarly to how the glyph’s image specifier works See section Creating Glyphs, you don’t create your own image specifier, but rather add specifications to the existing one. Note that the image instance that is generated in order to actually display the background pixmap is of type mono-pixmap, meaning that it’s a two-color image and the foreground and background of the image get filled in with the corresponding colors from the face. (#### Is this still true?)

Command: set-face-background-pixmap-file face file

This function sets the background pixmap of face face to the image contained in file. This is just a simplified version of set-face-background-pixmap which provides filename completion.

Command: set-face-font face font &optional locale tag-set 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 (see section Fonts).

If you want to set a face’s font for a given Mule character set, you need to include some tags in tag-set that match that character set. See the documentation of define-specifier-tag and its charset-predicate argument.

Command: set-face-underline-p face underline-p &optional locale tag-set how-to-add

This function sets the underline property of face face.

Function: face-foreground face &optional locale tag-set exact-p
Function: face-background face &optional locale tag-set exact-p

These functions return the foreground (respectively, background) color specifier of face face. See section Colors.

Function: face-background-pixmap face &optional locale tag-set exact-p

This function returns the background-pixmap image specifier of face face.

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

This function returns the font specifier of face face. (Note: This is not the same as the function face-font in FSF Emacs.)

See section 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. See section 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 charset

This function returns the font specifier of face face in domain domain (defaulting to the selected device) with Mule charset charset (defaulting to ASCII). See section Fonts.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.1.5 Other Face Display Functions

Command: 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.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2 Fonts

This section describes how to work with font specifier and font instance objects, which encapsulate fonts in the window system.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.1 Font Specifiers

Function: font-specifier-p object

This predicate returns t if object is a font specifier, and nil otherwise.

Function: make-font-specifier spec-list

Return a new font 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. See section Specifiers, for more information about specifiers.

Valid instantiators for font specifiers are:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.2 Font Instances

Function: font-instance-p object

This predicate returns t if object is a font instance, and nil otherwise.

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.

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.3 Font Instance Names

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.

Function: font-instance-name font-instance

This function returns the name used to allocate font-instance.

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).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.4 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.5 Font Instance Characteristics

Function: font-instance-properties font-instance

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.2.6 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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.3 Colors


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.3.1 Color Specifiers

Function: color-specifier-p object

This function returns non-nil if object is a color specifier.

Function: make-color-specifier spec-list

Return a new color 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. See section Specifiers, for a detailed description of how specifiers work.

Valid instantiators for color specifiers are:

Function: make-face-boolean-specifier spec-list

Return a new face-boolean 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. See section Specifiers, for a detailed description of how specifiers work.

Valid instantiators for face-boolean specifiers are


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.3.2 Color Instances

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,

 
(face-background-instance 'default (next-window))
    ⇒ #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>

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: color-instance-p object

This function returns non-nil if object is a color-instance.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

49.3.3 Color Instance Properties

Function: color-instance-name color-instance

This function returns the name used to allocate color-instance.

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.

 
(color-instance-rgb-components
  (face-background-instance 'default (next-window)))
    ⇒ (65535 58596 46517)


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.