@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Display, System Interface, Processes, Top
+@node Display
@chapter Emacs Display
This chapter describes a number of features related to the display
message is printed immediately.
@end defun
-@defun progress-reporter-update reporter value
+@defun progress-reporter-update reporter &optional value
This function does the main work of reporting progress of your
operation. It displays the message of @var{reporter}, followed by
progress percentage determined by @var{value}. If percentage is zero,
likely negate your effort.
@end defun
-@defun progress-reporter-force-update reporter value &optional new-message
+@defun progress-reporter-force-update reporter &optional value new-message
This function is similar to @code{progress-reporter-update} except
that it prints a message in the echo area unconditionally.
@findex collapse-delayed-warnings
@findex display-delayed-warnings
@noindent
-The function @code{collapse-delayed-warnings} iterates through
-@code{delayed-warnings-list}, removing repeated entries. The function
+The function @code{collapse-delayed-warnings} removes repeated entries
+from @code{delayed-warnings-list}. The function
@code{display-delayed-warnings} calls @code{display-warning} on each
of the entries in @code{delayed-warnings-list}, in turn, and then sets
@code{delayed-warnings-list} to @code{nil}.
This function executes @var{forms} while arranging to insert any output
they print into the buffer named @var{buffer-name}, which is first
created if necessary, and put into Help mode. Finally, the buffer is
-displayed in some window, but not selected.
+displayed in some window, but not selected. (See the similar
+form @code{with-temp-buffer-window} below.)
If the @var{forms} do not change the major mode in the output buffer,
so that it is still Help mode at the end of their execution, then
is current, and the window it was displayed in is selected.
@end defvar
+@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
+This macro is similar to @code{with-output-to-temp-buffer}.
+Like that construct, it executes @var{forms} while arranging to insert
+any output they print into the buffer named @var{buffer-or-name}.
+Finally, the buffer is displayed in some window, but not selected.
+Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
+mode.
+
+The argument @var{buffer-or-name} specifies the temporary buffer.
+It can be either a buffer, which must already exist, or a string,
+in which case a buffer of that name is created if necessary.
+The buffer is marked as unmodified and read-only when
+@code{with-temp-buffer-window} exits.
+
+This macro does not call @code{temp-buffer-show-function}. Rather, it
+passes the @var{action} argument to @code{display-buffer} in order to
+display the buffer.
+
+The value of the last form in @var{forms} is returned, unless the
+argument @var{quit-function} is specified. In that case,
+it is called with two arguments: the window showing the buffer
+and the result of @var{forms}. The final return value is then
+whatever @var{quit-function} returns.
+
+@vindex temp-buffer-window-setup-hook
+@vindex temp-buffer-window-show-hook
+This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
+and @code{temp-buffer-window-show-hook} in place of the analogous hooks
+run by @code{with-output-to-temp-buffer}.
+@end defmac
+
@defun momentary-string-display string position &optional char message
This function momentarily displays @var{string} in the current buffer at
@var{position}. It has no effect on the undo list or on the buffer's
A @dfn{face} is a collection of graphical @dfn{attributes} for
displaying text: font, foreground color, background color, optional
-underlining, and so on. Faces control how Emacs displays text in
-buffers, as well as other parts of the frame such as the mode line.
-@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
-faces Emacs normally comes with.
-
-@cindex face id
- For most purposes, you refer to a face in Lisp programs using its
-@dfn{face name}, which is usually a Lisp symbol. For backward
-compatibility, a face name can also be a string, which is equivalent
-to a Lisp symbol of the same name.
+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}.
+
+@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}
+(@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 Lisp
-symbol or string that names a face. Otherwise, it returns @code{nil}.
+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
attributes in one frame (@pxref{Attribute Functions}).
@menu
-* Defining Faces:: How to define a face.
* Face Attributes:: What is in a face?
+* Defining Faces:: How to define a face.
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a character.
* Face Remapping:: Remapping faces to alternative definitions.
* Low-Level Font:: Lisp representation for character display fonts.
@end menu
-@node Defining Faces
-@subsection Defining Faces
-
- The @code{defface} macro defines a face and specifies its default
-appearance. The user can subsequently customize the face using the
-Customize interface (@pxref{Customization}).
-
-@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 @code{(@var{display}
-@var{atts})}. @var{display} specifies a class of terminals (see
-below), while @var{atts} is a property list of face attributes and
-their values, specifying the appearance of the face on matching
-terminals
-@iftex
-(see the next section for details about face attributes).
-@end iftex
-@ifnottex
-(@pxref{Face Attributes}, for details about face attributes).
-@end ifnottex
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element matches. If more than one element of @var{spec}
-matches a given frame, the first element that matches is the one used
-for that frame. There are three possibilities for @var{display}:
-
-@table @asis
-@item @code{default}
-This element of @var{spec} doesn't match any frames; instead, it
-specifies defaults that apply to all frames. This kind of element, if
-used, must be the first element of @var{spec}. Each of the following
-elements can override any or all of these defaults.
-
-@item @code{t}
-This element of @var{spec} matches all frames. Therefore, any
-subsequent elements of @var{spec} are never used. Normally
-@code{t} is used in the last (or only) element of @var{spec}.
-
-@item a list
-If @var{display} is a list, each element should have the form
-@code{(@var{characteristic} @var{value}@dots{})}. Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to. Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{graphic} (any
-graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console),
-@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty}
-(a non-graphics-capable display).
-@xref{Window Systems, window-system}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background---either @code{light} or @code{dark}.
-
-@item min-colors
-An integer that represents the minimum number of colors the frame
-should support. This matches a frame if its
-@code{display-color-cells} value is at least the specified integer.
-
-@item supports
-Whether or not the frame can display the face attributes given in
-@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
-Attribute Testing}, for more information on exactly how this testing
-is done.
-@end table
-
-If an element of @var{display} specifies more than one @var{value} for a
-given @var{characteristic}, any of those values is acceptable. If
-@var{display} has more than one element, each element should specify a
-different @var{characteristic}; then @emph{each} characteristic of the
-frame must match one of the @var{value}s specified for it in
-@var{display}.
-@end table
-@end defmac
-
- Here's how the standard face @code{highlight} is defined:
-
-@example
-(defface highlight
- '((((class color) (min-colors 88) (background light))
- :background "darkseagreen2")
- (((class color) (min-colors 88) (background dark))
- :background "darkolivegreen")
- (((class color) (min-colors 16) (background light))
- :background "darkseagreen2")
- (((class color) (min-colors 16) (background dark))
- :background "darkolivegreen")
- (((class color) (min-colors 8))
- :background "green" :foreground "black")
- (t :inverse-video t))
- "Basic face for highlighting."
- :group 'basic-faces)
-@end example
-
- Internally, Emacs stores the face's default specification in its
-@code{face-defface-spec} symbol property (@pxref{Property Lists}).
-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.
-
-@defopt frame-background-mode
-This option, if non-@code{nil}, specifies the background type to use for
-interpreting face definitions. If it is @code{dark}, then Emacs treats
-all frames as if they had a dark background, regardless of their actual
-background colors. If it is @code{light}, then Emacs treats all frames
-as if they had a light background.
-@end defopt
-
@node Face Attributes
@subsection Face Attributes
@cindex face attributes
- The effect of using a face is determined by a fixed set of @dfn{face
-attributes}. This table lists all the face attributes, their possible
-values, and their effects. You can specify more than one face for a
-given piece of text; Emacs merges the attributes of all the faces to
-determine how to display the text. @xref{Displaying Faces}.
+ @dfn{Face attributes} determine the visual appearance of a face.
+The following table lists all the face attributes, their possible
+values, and their effects.
- In addition to the values given below, each face attribute can also
-have the value @code{unspecified}. This special value means the face
-doesn't specify that attribute. In face merging, when the first face
-fails to specify a particular attribute, the next face gets a chance.
-However, the @code{default} face must specify all attributes.
+ Apart from the values given below, each face attribute can have the
+value @code{unspecified}. This special value means that the face
+doesn't specify that attribute directly. An @code{unspecified}
+attribute tells Emacs to refer instead to a parent face (see the
+description @code{:inherit} attribute below); or, failing that, to an
+underlying face (@pxref{Displaying Faces}). The @code{default} face
+must specify all attributes.
Some of these attributes are meaningful only on certain kinds of
displays. If your display cannot handle a certain attribute, the
@table @code
@item :family
Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU
-Emacs Manual}. If you specify a font family name, the wild-card
-characters @samp{*} and @samp{?} are allowed. The function
-@code{font-family-list}, described below, returns a list of available
-family names. @xref{Fontsets}, for information about fontsets.
+Emacs Manual}, for more information about font families. The function
+@code{font-family-list} (see below) returns a list of available family
+names. @xref{Fontsets}, for information about fontsets.
@item :foundry
The name of the @dfn{font foundry} for the font family specified by
-the @code{:family} attribute (a string). The wild-card characters
-@samp{*} and @samp{?} are allowed. @xref{Fonts,,, emacs, The GNU
-Emacs Manual}.
+the @code{:family} attribute (a string). @xref{Fonts,,, emacs, The
+GNU Emacs Manual}.
@item :width
-Relative proportionate character width, also known as the character
-set width. This should be one of the symbols @code{ultra-condensed},
-@code{extra-condensed}, @code{condensed}, @code{semi-condensed},
-@code{normal}, @code{semi-expanded}, @code{expanded},
-@code{extra-expanded}, or @code{ultra-expanded}.
+Relative character width. This should be one of the symbols
+@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
+@code{semi-condensed}, @code{normal}, @code{semi-expanded},
+@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
@item :height
The height of the font. In the simplest case, this is an integer in
units of 1/10 point.
The value can also be a floating point number or a function, which
-specifies the height relative to an @dfn{underlying face} (i.e., a
-face that has a lower priority in the list described in
-@ref{Displaying Faces}). If the value is a floating point number,
+specifies the height relative to an @dfn{underlying face}
+(@pxref{Displaying Faces}). If the value is a floating point number,
that specifies the amount by which to scale the height of the
underlying face. If the value is a function, that function is called
with one argument, the height of the underlying face, and returns the
as extra bright, and any weight less than normal is displayed as
half-bright.
+@cindex italic text
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique},
@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On
Background color, a string. The value can be a system-defined color
name, or a hexadecimal color specification. @xref{Color Names}.
+@cindex underlined text
@item :underline
-Whether or not characters should be underlined, and in what color. If
-the value is @code{t}, underlining uses the foreground color of the
-face. If the value is a string, underlining uses that color. The
-value @code{nil} means do not underline.
+Whether or not characters should be underlined, and in what
+way. The possible values of the @code{:underline} attribute are:
+
+@table @asis
+@item @code{nil}
+Don't underline.
+
+@item @code{t}
+Underline with the foreground color of the face.
+@item @var{color}
+Underline in color @var{color}, a string specifying a color.
+
+@item @code{(:color @var{color} :style @var{style})}
+@var{color} is either a string, or the symbol @code{foreground-color},
+meaning the foreground color of the face. Omitting the attribute
+@code{:color} means to use the foreground color of the face.
+@var{style} should be a symbol @code{line} or @code{wave}, meaning to
+use a straight or wavy line. Omitting the attribute @code{:style}
+means to use a straight line.
+@end table
+
+@cindex overlined text
@item :overline
Whether or not characters should be overlined, and in what color.
-The value is used like that of @code{:underline}.
+If the value is @code{t}, overlining uses the foreground color of the
+face. If the value is a string, overlining uses that color. The
+value @code{nil} means do not overline.
+@cindex strike-through text
@item :strike-through
Whether or not characters should be strike-through, and in what
-color. The value is used like that of @code{:underline}.
+color. The value is used like that of @code{:overline}.
@item :box
Whether or not a box should be drawn around characters, its color, the
faces.
@end table
-For compatibility with Emacs 20, you can also specify values for two
-``fake'' face attributes: @code{:bold} and @code{:italic}. Their
-values must be either @code{t} or @code{nil}; a value of
-@code{unspecified} is not allowed. Setting @code{:bold} to @code{t}
-is equivalent to setting the @code{:weight} attribute to @code{bold},
-and setting it to @code{nil} is equivalent to setting @code{:weight}
-to @code{normal}. Setting @code{:italic} to @code{t} is equivalent to
-setting the @code{:slant} attribute to @code{italic}, and setting it
-to @code{nil} is equivalent to setting @code{:slant} to @code{normal}.
-
@defun font-family-list &optional frame
This function returns a list of available font family names. The
optional argument @var{frame} specifies the frame on which the text is
@code{nil} otherwise.
@end defun
+@node Defining Faces
+@subsection Defining Faces
+
+ 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}).
+
+@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
+
+@example
+(@var{display} . @var{plist})
+@end example
+
+@noindent
+@var{display} specifies a class of terminals (see below). @var{plist}
+is a property list of face attributes and their values, specifying how
+the face appears on such terminals. For backward compatibility, you
+can also write an element as @code{(@var{display} @var{plist})}.
+
+The @var{display} part of an element of @var{spec} determines which
+terminals the element matches. If more than one element of @var{spec}
+matches a given terminal, the first element that matches is the one
+used for that terminal. There are three possibilities for
+@var{display}:
+
+@table @asis
+@item @code{default}
+This element of @var{spec} doesn't match any terminal; instead, it
+specifies defaults that apply to all terminals. This element, if
+used, must be the first element of @var{spec}. Each of the following
+elements can override any or all of these defaults.
+
+@item @code{t}
+This element of @var{spec} matches all terminals. Therefore, any
+subsequent elements of @var{spec} are never used. Normally @code{t}
+is used in the last (or only) element of @var{spec}.
+
+@item a list
+If @var{display} is a list, each element should have the form
+@code{(@var{characteristic} @var{value}@dots{})}. Here
+@var{characteristic} specifies a way of classifying terminals, and the
+@var{value}s are possible classifications which @var{display} should
+apply to. Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the terminal uses---either @code{graphic}
+(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
+console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a
+non-graphics-capable display). @xref{Window Systems, window-system}.
+
+@item class
+What kinds of colors the terminal supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background---either @code{light} or @code{dark}.
+
+@item min-colors
+An integer that represents the minimum number of colors the terminal
+should support. This matches a terminal if its
+@code{display-color-cells} value is at least the specified integer.
+
+@item supports
+Whether or not the terminal can display the face attributes given in
+@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
+Attribute Testing}, for more information on exactly how this testing
+is done.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for
+a given @var{characteristic}, any of those values is acceptable. If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+terminal must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+ Here's how the standard face @code{highlight} is defined:
+
+@example
+(defface highlight
+ '((((class color) (min-colors 88) (background light))
+ :background "darkseagreen2")
+ (((class color) (min-colors 88) (background dark))
+ :background "darkolivegreen")
+ (((class color) (min-colors 16) (background light))
+ :background "darkseagreen2")
+ (((class color) (min-colors 16) (background dark))
+ :background "darkolivegreen")
+ (((class color) (min-colors 8))
+ :background "green" :foreground "black")
+ (t :inverse-video t))
+ "Basic face for highlighting."
+ :group 'basic-faces)
+@end example
+
+ Internally, Emacs stores the face's default specification in its
+@code{face-defface-spec} symbol property (@pxref{Property Lists}).
+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.
+
@node Attribute Functions
@subsection Face Attribute Functions
This section describes the functions for accessing and modifying the
-attributes of an existing face.
+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{italic-p} is @code{nil}, and to @var{italic} otherwise.
@end defun
-@defun set-face-underline-p face underline &optional frame
+@defun set-face-underline face underline &optional frame
This sets the @code{:underline} attribute of @var{face} to
@var{underline}.
@end defun
@code{nil} otherwise.
@end defun
+@c Note the weasel words. A face that inherits from an underlined
+@c face but does not specify :underline will return nil.
@defun face-underline-p face &optional frame
-This function returns the @code{:underline} attribute of face @var{face}.
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:underline} attribute.
@end defun
@defun face-inverse-video-p face &optional frame
-This function returns the @code{:inverse-video} attribute of face @var{face}.
+This function returns non-@code{nil} if face @var{face} specifies
+a non-@code{nil} @code{:inverse-video} attribute.
@end defun
@node Displaying Faces
@subsection Displaying Faces
- Here is how Emacs determines the face to use for displaying any
-given piece of text:
+ When Emacs displays a given piece of text, the visual appearance of
+the text may be determined by faces drawn from different sources. If
+these various sources together specify more than one face for a
+particular character, Emacs merges the attributes of the various
+faces. Here is the order in which Emacs merges the faces, from
+highest to lowest priority:
@itemize @bullet
@item
@item
If the text lies within an overlay with a non-@code{nil} @code{face}
-property, Emacs applies the face or face attributes specified by that
-property. If the overlay has a @code{mouse-face} property and the
-mouse is ``near enough'' to the overlay, Emacs applies the face or
-face attributes specified by the @code{mouse-face} property instead.
-@xref{Overlay Properties}.
+property, Emacs applies the face(s) specified by that property. If
+the overlay has a @code{mouse-face} property and the mouse is ``near
+enough'' to the overlay, Emacs applies the face or face attributes
+specified by the @code{mouse-face} property instead. @xref{Overlay
+Properties}.
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
steps, Emacs applies the attribute of the @code{default} face.
@end itemize
- If these various sources together specify more than one face for a
-particular character, Emacs merges the attributes of the various faces
-specified. For each attribute, Emacs tries using the above order
-(i.e.@: first the face of any special glyph; then the face for region
-highlighting, if appropriate; and so on).
+ At each stage, if a face has a valid @code{:inherit} attribute,
+Emacs treats any attribute with an @code{unspecified} value as having
+the corresponding value drawn from the parent face(s). @pxref{Face
+Attributes}. Note that the parent face(s) may also leave the
+attribute unspecified; in that case, the attribute remains unspecified
+at the next level of face merging.
@node Face Remapping
@subsection Face Remapping
The value of this variable is an alist whose elements have the form
@code{(@var{face} . @var{remapping})}. This causes Emacs to display
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 name, or a property list of attribute/value pairs, or a list in
-which each element is either a face name or a property list
-(@pxref{Special Properties}).
+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.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
-Two points bear emphasizing:
-
-@enumerate
-@item
-@var{remapping} serves as the complete specification for the remapped
-face---it replaces the normal definition of @var{face}, instead of
-modifying it.
-
-@item
-If @var{remapping} references the same face name @var{face}, either
-directly or via the @code{:inherit} attribute of some other face in
-@var{remapping}, that reference uses the normal definition of
-@var{face}. In other words, the remapping cannot be recursive.
+Note: face remapping is non-recursive. If @var{remapping} references
+the same face name @var{face}, either directly or via the
+@code{:inherit} attribute of some other face in @var{remapping}, that
+reference uses the normal definition of @var{face}. For instance, if
+the @code{mode-line} face is remapped using this entry in
+@code{face-remapping-alist}:
-For instance, if the @code{mode-line} face is remapped using this
-entry in @code{face-remapping-alist}:
@example
(mode-line italic mode-line)
@end example
+
@noindent
then the new definition of the @code{mode-line} face inherits from the
@code{italic} face, and the @emph{normal} (non-remapped) definition of
@code{mode-line} face.
-@end enumerate
@end defvar
The following functions implement a higher-level interface to
(put 'modeline 'face-alias 'mode-line)
@end example
-@defun define-obsolete-face-alias obsolete-face current-face &optional when
-This function defines a face alias and marks it as obsolete, indicating
-that it may be removed in future. The optional string @var{when}
-indicates when the face was made obsolete (for example, a release number).
-@end defun
+@defmac define-obsolete-face-alias obsolete-face current-face when
+This macro defines @code{obsolete-face} as an alias for
+@var{current-face}, and also marks it as obsolete, indicating that it
+may be removed in future. @var{when} should be a string indicating
+when @code{obsolete-face} was made obsolete (usually a version number
+string).
+@end defmac
@node Auto Faces
@subsection Automatic Face Assignment
encoding of the font.
@end defun
-@defopt font-list-limit
-This variable specifies maximum number of fonts to consider in font
-matching. The function @code{x-family-fonts} will not return more
-than that many fonts, and font selection will consider only that many
-fonts when searching a matching font for face attributes. The default
-is 100.
-@end defopt
-
@node Fontsets
@subsection Fontsets
@itemx @code{vertical-bar}, @code{horizontal-bar}
Used for different types of fringe cursors.
-@item @code{empty-line}, @code{question-mark}
-Unused.
+@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark}
+Not used by core Emacs features.
@end table
@noindent
@cindex images, support for more formats
If you build Emacs with ImageMagick support, you can use the
-ImageMagick library to load many image formats. The image type symbol
+ImageMagick library to load many image formats (@pxref{File
+Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol
for images loaded via ImageMagick is @code{imagemagick}, regardless of
the actual underlying image format.
@defun imagemagick-types
This function returns a list of image file extensions supported by the
-current ImageMagick installation.
-@end defun
-
- By default, Emacs does not use ImageMagick to display images in
-Image mode, e.g.@: when visiting such files with @kbd{C-x C-f}. This
-feature is enabled by calling @code{imagemagick-register-types}.
-
-@defun imagemagick-register-types
-This function enables using Image mode to visit image files supported
-by ImageMagick. @xref{File Conveniences,,, emacs, The GNU Emacs
-Manual}. It also causes @code{create-image} and other helper
-functions to associate such file names with the @code{imagemagick}
-image type (@pxref{Defining Images}).
-
-All image file extensions supported by ImageMagick are registered,
-except those specified in @code{imagemagick-types-inhibit}. If Emacs
-was not compiled with ImageMagick support, this function does nothing.
-@end defun
+current ImageMagick installation. Each list element is a symbol
+representing an internal ImageMagick name for an image type, such as
+@code{BMP} for @file{.bmp} images.
+@end defun
+
+@defopt imagemagick-enabled-types
+The value of this variable is a list of ImageMagick image types which
+Emacs may attempt to render using ImageMagick. Each list element
+should be one of the symbols in the list returned by
+@code{imagemagick-types}, or an equivalent string. Alternatively, a
+value of @code{t} enables ImageMagick for all possible image types.
+Regardless of the value of this variable,
+@code{imagemagick-types-inhibit} (see below) takes precedence.
+@end defopt
@defopt imagemagick-types-inhibit
-This variable specifies a list of image types that should @emph{not}
-be registered by @code{imagemagick-register-types}. Each entry in
-this list should be one of the symbols returned by
-@code{imagemagick-types}. The default value lists several file types
-that are considered ``images'' by ImageMagick, but which should not be
-considered as images by Emacs, including C files and HTML files.
+The value of this variable lists the ImageMagick image types which
+should never be rendered using ImageMagick, regardless of the value of
+@code{imagemagick-enabled-types}. A value of @code{t} disables
+ImageMagick entirely.
@end defopt
-@ignore
-@c I don't know what this means. I suspect it means eg loading jpg
-@c images via libjpeg or ImageMagick. But it doesn't work.
-@c If you don't have libjpeg support compiled in, you cannot
-@c view jpeg images, even if you have imagemagick support:
-@c http://debbugs.gnu.org/9045
-@c And if you have both compiled in, then you always get
-@c the libjpeg version:
-@c http://debbugs.gnu.org/10746
-There may be overlap between image loaders in your Emacs installation,
-and you may prefer to use a different one for a given image type
-(which loader will be used in practice depends on the priority of the
-loaders).
-For example, if you never want to use the ImageMagick loader to view
-JPEG files, add @code{JPG} to this list.
-@end ignore
-
Images loaded with ImageMagick support the following additional
image descriptor properties:
@table @code
+@item :background @var{background}
+@var{background}, if non-@code{nil}, should be a string specifying a
+color, which is used as the image's background color if the image
+supports transparency. If the value is @code{nil}, it defaults to the
+frame's background color.
+
@item :width, :height
The @code{:width} and @code{:height} keywords are used for scaling the
image. If only one of them is specified, the other one will be
The following functions related to animated images are available.
@defun image-animated-p image
-This function returns non-nil if @var{image} can be animated.
+This function returns non-@code{nil} if @var{image} can be animated.
The actual return value is a cons @code{(@var{nimages} . @var{delay})},
where @var{nimages} is the number of frames and @var{delay} is the
delay in seconds between them.
HCoop / bpt / emacs.git / blobdiff