| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| 49.1 Faces | Controlling the way text looks. | |
| 49.2 Fonts | Controlling the typeface of text. | |
| 49.3 Colors | Controlling the color of text and pixmaps. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 48. Specifiers, for more information on specifiers. See section 19.4 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 47. Extents). The
faces named left-margin and right-margin are used for the
left and right margin areas, respectively (see section 51. Annotations). The
face named zmacs-region is used for the highlighted region
between point and mark.
| 49.1.1 Merging Faces for Display | How XEmacs decides which face to use for a character. | |
| 49.1.2 Basic Functions for Working with Faces | How to define and examine faces. | |
| 49.1.3 Face Properties | How to access and modify a face's properties. | |
| 49.1.4 Face Convenience Functions | Convenience functions for accessing particular properties of a face. | |
| 49.1.5 Other Face Display Functions | Other functions pertaining to how a a face appears. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are all the ways to specify which face to use for display of text:
default applies to the text area, while the faces
left-margin and right-margin apply to the left and right
margin areas.
face property; if so,
it's displayed with that face. (Text properties are actually implemented
in terms of extents.) See section 43.18 Text Properties.
face property, which applies
to all the text covered by the extent; in addition, if the
highlight property is set, the highlight property applies
when the mouse moves over the extent or if the extent is explicitly
highlighted. See section 47. Extents.
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 47. 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] | [ ? ] |
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.
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).
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.
t if object is a face, else nil.
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 48. 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] | [ ? ] |
You can examine and modify the properties of an existing face with the following functions.
The following symbols have predefined meanings:
foreground
background
font
display-table
background-pixmap
underline
highlight
dim
blinking
reverse
doc-string
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:
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.
For built-in properties, this is analogous to remove-specifier.
For more information, See section 48.13 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.
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.
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 48. Specifiers.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
make-color (see section 49.3 Colors).
x-bitmap-file-path will be searched) or a glyph object as
returned by make-glyph (see section 50. 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 50.3.1 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?)
set-face-background-pixmap which provides filename completion.
make-font
(see section 49.2 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.
face-font in FSF Emacs.)
See section 49.2 Fonts.
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.)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
t if the faces face1 and face2 will
display in the same way. domain is as in
face-property-instance.
t if the face face displays differently from
the default face. domain is as in face-property-instance.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes how to work with font specifier and font instance objects, which encapsulate fonts in the window system.
| 49.2.1 Font Specifiers | Specifying how a font will appear. | |
| 49.2.2 Font Instances | What a font specifier gets instanced as. | |
| 49.2.3 Font Instance Names | The name of a font instance. | |
| 49.2.4 Font Instance Size | The size of a font instance. | |
| 49.2.5 Font Instance Characteristics | Display characteristics of font instances. | |
| 49.2.6 Font Convenience Functions | Convenience functions that automatically instance and retrieve the properties of a font specifier. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
t if object is a font specifier, and
nil otherwise.
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 48. Specifiers, for more information
about specifiers.
Valid instantiators for font specifiers are:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
t if object is a font instance, and
nil otherwise.
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] | [ ? ] |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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] | [ ? ] |
nil) of
font-instance.
nil.
nil.
nil.
nil.
nil.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
specifier-instance and
applying font-instance-name to the result.
specifier-instance and
applying font-instance-truename to the result.
specifier-instance and
applying font-instance-properties to the result.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| 49.3.1 Color Specifiers | Specifying how a color will appear. | |
| 49.3.2 Color Instances | What a color specifier gets instanced as. | |
| 49.3.3 Color Instance Properties | Properties of color instances. | |
| 49.3.4 Color Convenience Functions | Convenience functions that automatically instance and retrieve the properties of a color specifier. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
nil if object is a color specifier.
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 48. Specifiers, for a detailed
description of how specifiers work.
Valid instantiators for color specifiers are:
foreground or background (if omitted, defaults to the same
property that this color specifier is used for; if this specifier is not
part of a face, the instantiator would not be valid).
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 48. Specifiers, for a detailed
description of how specifiers work.
Valid instantiators for face-boolean specifiers are
nil, means to invert the
sense of the inherited property.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
nil if object is a color-instance.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
(color-instance-rgb-components
(face-background-instance 'default (next-window)))
=> (65535 58596 46517)
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
specifier-instance and applying color-instance-name to the
result.
specifier-instance and applying
color-instance-rgb-components to the result.
(color-rgb-components (face-background 'default (next-window)))
=> (65535 58596 46517)
|
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |