@item face
@kindex face @r{(overlay property)}
-This property controls the way text is displayed---for example, which
-font and which colors. @xref{Faces}, for more information.
-
-In the simplest case, the value is a face name. It can also be a list;
-then each element can be any of these possibilities:
+This property controls the appearance of the text (@pxref{Faces}).
+The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
-A property list of face attributes. This has the form (@var{keyword}
-@var{value} @dots{}), where each @var{keyword} is a face attribute
-name and @var{value} is a meaningful value for that attribute. With
-this feature, you do not need to create a face each time you want to
-specify a particular attribute for certain text. @xref{Face
-Attributes}.
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
@item
-A cons cell, of the form @code{(foreground-color . @var{color-name})}
-or @code{(background-color . @var{color-name})}. These elements
-specify just the foreground color or just the background color.
+A list of faces. Each list element should be either a face name or an
+anonymous face. This specifies a face which is an aggregate of the
+attributes of each of the listed faces. Faces occurring earlier in
+the list have higher priority.
-@code{(foreground-color . @var{color-name})} has the same effect as
-@code{(:foreground @var{color-name})}; likewise for the background.
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}. This
+form is supported for backward compatibility only, and should be
+avoided.
@end itemize
@item mouse-face
an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
it immediately.
-@item local-map
-@cindex keymap of character (and overlays)
-@kindex local-map @r{(overlay property)}
-If this property is non-@code{nil}, it specifies a keymap for a portion
-of the text. The property's value replaces the buffer's local map, when
-the character after point is within the overlay. @xref{Active Keymaps}.
-
@item keymap
+@cindex keymap of character (and overlays)
@kindex keymap @r{(overlay property)}
-The @code{keymap} property is similar to @code{local-map} but overrides the
-buffer's local map (and the map specified by the @code{local-map}
-property) rather than replacing it.
+If this property is non-@code{nil}, it specifies a keymap for a portion of the
+text. This keymap is used when the character after point is within the
+overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}.
+
+@item local-map
+@kindex local-map @r{(overlay property)}
+The @code{local-map} property is similar to @code{keymap} but replaces the
+buffer's local map rather than augmenting existing keymaps. This also means it
+has lower precedence than minor mode keymaps.
@end table
-The @code{local-map} and @code{keymap} properties do not affect a
+The @code{keymap} and @code{local-map} properties do not affect a
string displayed by the @code{before-string}, @code{after-string}, or
@code{display} properties. This is only relevant for mouse clicks and
other mouse events that fall on the string, since point is never on
the string. To bind special mouse events for the string, assign it a
-@code{local-map} or @code{keymap} text property. @xref{Special
+@code{keymap} or @code{local-map} text property. @xref{Special
Properties}.
@node Finding Overlays
@section Faces
@cindex faces
- A @dfn{face} is a collection of graphical @dfn{attributes} for
-displaying text: font, foreground color, background color, optional
-underlining, etc. Faces control how Emacs displays text in buffers,
-as well as other parts of the frame such as the mode line.
+ A @dfn{face} is a collection of graphical attributes for displaying
+text: font, foreground color, background color, optional underlining,
+etc. Faces control how Emacs displays text in buffers, as well as
+other parts of the frame such as the mode line.
@cindex anonymous face
One way to represent a face is as a property list of attributes,
-like @code{(:foreground "red" :weight bold)}. For example, you can
-assign such an @dfn{anonymous face} as the value of the @code{face}
-text property; this causes Emacs to display the underlying text with
-the specified attributes. @xref{Special Properties}.
+like @code{(:foreground "red" :weight bold)}. Such a list is called
+an @dfn{anonymous face}. For example, you can assign an anonymous
+face as the value of the @code{face} text property, and Emacs will
+display the underlying text with the specified attributes.
+@xref{Special Properties}.
@cindex face name
More commonly, a face is referred to via a @dfn{face name}: a Lisp
-symbol which is associated with a set of face attributes. Named faces
-are defined using the @code{defface} macro (@pxref{Defining Faces}).
-Emacs defines several standard named faces; @xref{Standard Faces,,,
-emacs, The GNU Emacs Manual}.
-
- Many parts of Emacs require named faces, and do not accept anonymous
-faces. These include the functions documented in @ref{Attribute
-Functions}, and the variable @code{font-lock-keywords}
+symbol associated with a set of face attributes@footnote{For backward
+compatibility, you can also use a string to specify a face name; that
+is equivalent to a Lisp symbol with the same name.}. Named faces are
+defined using the @code{defface} macro (@pxref{Defining Faces}).
+Emacs comes with several standard named faces (@pxref{Basic Faces}).
+
+ Many parts of Emacs required named faces, and do not accept
+anonymous faces. These include the functions documented in
+@ref{Attribute Functions}, and the variable @code{font-lock-keywords}
(@pxref{Search-based Fontification}). Unless otherwise stated, we
will use the term @dfn{face} to refer only to named faces.
- For backward compatibility, you can also use a string to specify a
-face name; that is equivalent to a Lisp symbol with the same name.
-
@defun facep object
This function returns a non-@code{nil} value if @var{object} is a
named face: a Lisp symbol or string which serves as a face name.
Otherwise, it returns @code{nil}.
@end defun
- By default, each face name corresponds to the same set of attributes
-in all frames. But you can also assign a face name a special set of
-attributes in one frame (@pxref{Attribute Functions}).
-
@menu
* Face Attributes:: What is in a face?
* Defining Faces:: How to define a face.
@item :font
The font used to display the face. Its value should be a font object.
-@xref{Font Selection}, for information about font objects.
+@xref{Low-Level Font}, for information about font objects, font specs,
+and font entities.
When specifying this attribute using @code{set-face-attribute}
(@pxref{Attribute Functions}), you may also supply a font spec, a font
@node Defining Faces
@subsection Defining Faces
+@cindex face spec
The usual way to define a face is through the @code{defface} macro.
-This macro defines a face name, and associates that name with a set of
-face attributes. It also sets up the face so that the user can
-customize it via the Customize interface (@pxref{Customization}).
+This macro associates a face name (a symbol) with a default @dfn{face
+spec}. A face spec is a construct which specifies what attributes a
+face should have on any given terminal; for example, a face spec might
+specify one foreground color on high-color terminals, and a different
+foreground color on low-color terminals.
+
+ People are sometimes tempted to create a variable whose value is a
+face name. In the vast majority of cases, this is not necessary; the
+usual procedure is to define a face with @code{defface}, and then use
+its name directly.
@defmac defface face spec doc [keyword value]@dots{}
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}. You should not quote the symbol
-@var{face}, and it should not end in @samp{-face} (that would be
-redundant). The argument @var{doc} is a documentation string for the
-face. The additional @var{keyword} arguments have the same meanings
-as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
-
-When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations that were read from the
-init file (@pxref{Init File}) to override that specification.
-
-When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
-Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
-overrides any customizations of the face. This way, the face reflects
-exactly what the @code{defface} says.
-
-@cindex face specification
-The @var{spec} argument is a @dfn{face specification}, which states
-how the face should appear on different kinds of terminals. It should
-be an alist whose elements each have the form
+This macro declares @var{face} as a named face whose default face spec
+is given by @var{spec}. You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant). The
+argument @var{doc} is a documentation string for the face. The
+additional @var{keyword} arguments have the same meanings as in
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+
+If @var{face} already has a default face spec, this macro does
+nothing.
+
+The default face spec determines @var{face}'s appearance when no
+customizations are in effect (@pxref{Customization}). If @var{face}
+has already been customized (via Custom themes or via customizations
+read from the init file), its appearance is determined by the custom
+face spec(s), which override the default face spec @var{spec}.
+However, if the customizations are subsequently removed, the
+appearance of @var{face} will again be determined by its default face
+spec.
+
+As an exception, if you evaluate a @code{defface} form with
+@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature
+of @code{eval-defun} overrides any custom face specs on the face,
+causing the face to reflect exactly what the @code{defface} says.
+
+The @var{spec} argument is a @dfn{face spec}, which states how the
+face should appear on different kinds of terminals. It should be an
+alist whose elements each have the form
@example
(@var{display} . @var{plist})
@end table
@end defmac
- Here's how the standard face @code{highlight} is defined:
+ For example, here's the definition of the standard face
+@code{highlight}:
@example
(defface highlight
:group 'basic-faces)
@end example
- Internally, Emacs stores the face's default specification in its
+ Internally, Emacs stores each face's default spec in its
@code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
-The @code{saved-face} property stores the face specification saved by
-the user, using the customization buffer; the @code{customized-face}
-property stores the face specification customized for the current
-session, but not saved; and the @code{theme-face} property stores an
-alist associating the active customization settings and Custom themes
-with their specifications for that face. The face's documentation
-string is stored in the @code{face-documentation} property. But
-normally you should not try to set any of these properties directly.
-@xref{Applying Customizations}, for the @code{custom-set-faces}
-function, which is used to apply customized face settings.
-
- People are sometimes tempted to create variables whose values
-specify a face to use. In the vast majority of cases, this is not
-necessary; it is preferable to simply use faces directly.
+The @code{saved-face} property stores any face spec saved by the user
+using the customization buffer; the @code{customized-face} property
+stores the face spec customized for the current session, but not
+saved; and the @code{theme-face} property stores an alist associating
+the active customization settings and Custom themes with the face
+specs for that face. The face's documentation string is stored in the
+@code{face-documentation} property.
+
+ Normally, a face is declared just once, using @code{defface}, and
+any further changes to its appearance are applied using the Customize
+framework (e.g., via the Customize user interface or via the
+@code{custom-set-faces} function; @pxref{Applying Customizations}), or
+by face remapping (@pxref{Face Remapping}). In the rare event that
+you need to change a face spec directly from Lisp, you can use the
+@code{face-spec-set} function.
+
+@defun face-spec-set face spec &optional spec-type
+This function applies @var{spec} as a face spec for @code{face}.
+@var{spec} should be a face spec, as described in the above
+documentation for @code{defface}.
+
+@cindex override spec @r{(for a face)}
+The argument @var{spec-type} determines which spec to set. If it is
+@code{nil} or @code{face-override-spec}, this function sets the
+@dfn{override spec}, which overrides over all other face specs on
+@var{face}. If it is @code{face-defface-spec}, this function sets the
+default face spec (the same one set by @code{defface}). If it is
+@code{reset}, this function clears out all customization specs and
+override specs from @var{face} (in this case, the value of @var{spec}
+is ignored). Any other value of @var{spec-type} is reserved for
+internal use.
+@end defun
@node Attribute Functions
@subsection Face Attribute Functions
- This section describes the functions for accessing and modifying the
-attributes of an existing named face.
-
-@defun set-face-attribute face frame &rest arguments
-This function sets one or more attributes of @var{face} for
-@var{frame}. The attributes you specify this way override whatever
-the @code{defface} says.
-
-The extra arguments @var{arguments} specify the attributes to set, and
-the values for them. They should consist of alternating attribute
-names (such as @code{:family} or @code{:underline}) and values. Thus,
-
-@example
-(set-face-attribute 'foo nil
- :width 'extended
- :weight 'bold)
-@end example
-
-@noindent
-sets the attribute @code{:width} to @code{extended} and the attribute
-@code{:weight} to @code{bold}.
-
-If @var{frame} is @code{t}, this function sets the default attributes
-for new frames. Default attribute values specified this way override
-the @code{defface} for newly created frames.
-
-If @var{frame} is @code{nil}, this function sets the attributes for
-all existing frames, and the default for new frames.
-@end defun
+ This section describes functions for directly accessing and
+modifying the attributes of a named face.
@defun face-attribute face attribute &optional frame inherit
-This returns the value of the @var{attribute} attribute of @var{face}
-on @var{frame}. If @var{frame} is @code{nil}, that means the selected
-frame (@pxref{Input Focus}).
+This function returns the value of the @var{attribute} attribute for
+@var{face} on @var{frame}.
-If @var{frame} is @code{t}, this returns whatever new-frames default
-value you previously specified with @code{set-face-attribute} for the
-@var{attribute} attribute of @var{face}. If you have not specified
-one, it returns @code{nil}.
+If @var{frame} is @code{nil}, that means the selected frame
+(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
+returns the value of the specified attribute for newly-created frames
+(this is normally @code{unspecified}, unless you have specified some
+value using @code{set-face-attribute}; see below).
If @var{inherit} is @code{nil}, only attributes directly defined by
@var{face} are considered, so the return value may be
@var{attribute}, returns it merged with the underlying value
@var{value2}; otherwise, if @var{value1} is an absolute value for the
face attribute @var{attribute}, returns @var{value1} unchanged.
+@end defun
+
+ Normally, Emacs uses the face specs of each face to automatically
+calculate its attributes on each frame (@pxref{Defining Faces}). The
+function @code{set-face-attribute} can override this calculation by
+directly assigning attributes to a face, either on a specific frame or
+for all frames. This function is mostly intended for internal usage.
+
+@defun set-face-attribute face frame &rest arguments
+This function sets one or more attributes of @var{face} for
+@var{frame}. The attributes specifies in this way override the face
+spec(s) belonging to @var{face}.
+
+The extra arguments @var{arguments} specify the attributes to set, and
+the values for them. They should consist of alternating attribute
+names (such as @code{:family} or @code{:underline}) and values. Thus,
+
+@example
+(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
+@end example
+
+@noindent
+sets the attribute @code{:weight} to @code{bold} and the attribute
+@code{:slant} to @code{italic}.
+
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for newly created frames. If @var{frame} is @code{nil}, this function
+sets the attributes for all existing frames, as well as for newly
+created frames.
@end defun
The following commands and functions mostly provide compatibility
This swaps the foreground and background colors of face @var{face}.
@end deffn
- The following functions examine the attributes of a face. If you
-don't specify @var{frame}, they refer to the selected frame; @code{t}
-refers to the default data for new frames. They return the symbol
-@code{unspecified} if the face doesn't define any value for that
-attribute. If @var{inherit} is @code{nil}, only an attribute directly
-defined by the face is returned. If @var{inherit} is non-@code{nil},
-any faces specified by its @code{:inherit} attribute are considered as
-well, and if @var{inherit} is a face or a list of faces, then they are
-also considered, until a specified attribute is found. To ensure that
-the return value is always specified, use a value of @code{default} for
+ The following functions examine the attributes of a face. They
+mostly provide compatibility with old versions of Emacs. If you don't
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames. They return @code{unspecified} if
+the face doesn't define any value for that attribute. If
+@var{inherit} is @code{nil}, only an attribute directly defined by the
+face is returned. If @var{inherit} is non-@code{nil}, any faces
+specified by its @code{:inherit} attribute are considered as well, and
+if @var{inherit} is a face or a list of faces, then they are also
+considered, until a specified attribute is found. To ensure that the
+return value is always specified, use a value of @code{default} for
@var{inherit}.
@defun face-font face &optional frame
any text having the face @var{face} with @var{remapping}, rather than
the ordinary definition of @var{face}.
-@var{remapping} may be any face specification suitable for a
-@code{face} text property: either a face (i.e., a face name or a
-property list of attribute/value pairs), or a list of faces. For
-details, see the description of the @code{face} text property in
-@ref{Special Properties}. @var{remapping} serves as the complete
-specification for the remapped face---it replaces the normal
-definition of @var{face}, instead of modifying it.
+@var{remapping} may be any face spec suitable for a @code{face} text
+property: either a face (i.e., a face name or a property list of
+attribute/value pairs), or a list of faces. For details, see the
+description of the @code{face} text property in @ref{Special
+Properties}. @var{remapping} serves as the complete specification for
+the remapped face---it replaces the normal definition of @var{face},
+instead of modifying it.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
-This functions adds the face specifications in @var{specs} as relative
+This functions adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
properties are intermediate between a font object and a font spec:
like a font object, and unlike a font spec, it refers to a single,
specific font. Unlike a font object, creating a font entity does not
-load the contents of that font into computer memory.
+load the contents of that font into computer memory. Emacs may open
+multiple font objects of different sizes from a single font entity
+referring to a scalable font.
@defun find-font font-spec &optional frame
This function returns a font entity that best matches the font spec
HCoop / bpt / emacs.git / blobdiff