@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../info/display
+@setfilename ../../info/display
@node Display, System Interface, Processes, Top
@chapter Emacs Display
This function clears and redisplays all visible frames.
@end deffn
- This function calls for redisplay of certain windows, the next time
-redisplay is done, but does not clear them first.
-
-@defun force-window-update &optional object
-This function forces some or all windows to be updated on next redisplay.
-If @var{object} is a window, it forces redisplay of that window. If
-@var{object} is a buffer or buffer name, it forces redisplay of all
-windows displaying that buffer. If @var{object} is @code{nil} (or
-omitted), it forces redisplay of all windows.
-@end defun
-
- Processing user input takes absolute priority over redisplay. If you
-call these functions when input is available, they do nothing
-immediately, but a full redisplay does happen eventually---after all the
-input has been processed.
+ In Emacs, processing user input takes priority over redisplay. If
+you call these functions when input is available, they don't redisplay
+immediately, but the requested redisplay does happen
+eventually---after all the input has been processed.
Normally, suspending and resuming Emacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
@section Forcing Redisplay
@cindex forcing redisplay
+ Emacs normally tries to redisplay the screen whenever it waits for
+input. With this function you can request an immediate attempt to
+redisplay, in the middle of Lisp code, without actually waiting for
+input.
+
+@defun redisplay &optional force
+This function tries immediately to redisplay, provided there are no
+pending input events. It is equivalent to @code{(sit-for 0)}.
+
+If the optional argument @var{force} is non-@code{nil}, it does all
+pending redisplay work even if input is available, with no
+pre-emption.
+
+The function returns @code{t} if it actually tried to redisplay, and
+@code{nil} otherwise. A value of @code{t} does not mean that
+redisplay proceeded to completion; it could have been pre-empted by
+newly arriving terminal input.
+@end defun
+
+ @code{redisplay} with no argument tries immediately to redisplay,
+but has no effect on the usual rules for what parts of the screen to
+redisplay. By contrast, the following function adds certain windows
+to the pending redisplay work (as if their contents had completely
+changed), but doesn't immediately try to do any redisplay work.
+
+@defun force-window-update &optional object
+This function forces some or all windows to be updated on next
+redisplay. If @var{object} is a window, it requires eventual
+redisplay of that window. If @var{object} is a buffer or buffer name,
+it requires eventual redisplay of all windows displaying that buffer.
+If @var{object} is @code{nil} (or omitted), it requires eventual
+redisplay of all windows.
+@end defun
+
+ @code{force-window-update} does not do a redisplay immediately.
+(Emacs will do that when it waits for input.) Rather, its effect is
+to put more work on the queue to be done by redisplay whenever there
+is a chance.
+
Emacs redisplay normally stops if input arrives, and does not happen
at all if input is available before it starts. Most of the time, this
is exactly what you want. However, you can prevent preemption by
binding @code{redisplay-dont-pause} to a non-@code{nil} value.
+@defvar redisplay-dont-pause
+If this variable is non-@code{nil}, pending input does not
+prevent or halt redisplay; redisplay occurs, and finishes,
+regardless of whether input is available.
+@end defvar
+
@defvar redisplay-preemption-period
This variable specifies how many seconds Emacs waits between checks
for new input during redisplay. (The default is 0.1 seconds.) If
text terminals, see @ref{Terminal Output}.
@end defvar
-@defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not
-prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available.
-@end defvar
-
-@defun redisplay &optional force
-This function performs an immediate redisplay provided there are no
-pending input events. This is equivalent to @code{(sit-for 0)}.
-
-If the optional argument @var{force} is non-@code{nil}, it forces an
-immediate and complete redisplay even if input is available.
-
-Returns @code{t} if redisplay was performed, or @code{nil} otherwise.
-@end defun
-
@node Truncation
@section Truncation
@cindex line wrapping
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
+@defvar wrap-prefix
+If this buffer-local variable is non-@code{nil}, the prefix it defines
+will be added at display-time to the beginning of every continuation
+line due to text wrapping (so if lines are truncated, the wrap-prefix
+is never used). It may be a string, an image, or a stretch-glyph such
+as used by the `display' text-property. @xref{Display Property}.
+
+A wrap-prefix may also be specified for regions of text using the
+@code{wrap-prefix} text-property (which takes precedence over the
+value of the @code{wrap-prefix} variable). @xref{Special Properties}.
+@end defvar
+
+@defvar line-prefix
+If this buffer-local variable is non-@code{nil}, the prefix it defines
+will be added at display-time to the beginning of every
+non-continuation line It may be a string, an image, or a stretch-glyph
+such as used by the `display' text-property. @xref{Display Property}.
+
+A line-prefix may also be specified for regions of text using the
+@code{line-prefix} text-property (which takes precedence over the
+value of the @code{line-prefix} variable). @xref{Special Properties}.
+@end defvar
+
If your buffer contains @emph{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
redisplay slow. The column computation and indentation functions also
The variable @code{max-mini-window-height}, which specifies the
maximum height for resizing minibuffer windows, also applies to the
echo area (which is really a special use of the minibuffer window.
-@xref{Minibuffer Misc}.
+@xref{Minibuffer Misc}.).
@node Warnings
@section Reporting Warnings
@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
displaying the temporary buffer. When the hook runs, the temporary buffer
-is current, and the window it was displayed in is selected. This hook
-is normally set up with a function to make the buffer read only, and
-find function names and variable names in it, provided the major mode
-is Help mode.
+is current, and the window it was displayed in is selected.
@end defvar
@defun momentary-string-display string position &optional char message
text property changes, overlay property changes are not recorded in
the buffer's undo list.
+ Since more than one overlay can specify a property value for the
+same character, Emacs lets you specify a priority value of each
+overlay. You should not make assumptions about which overlay will
+prevail when there is a conflict and they have the same priority.
+
These functions read and set the properties of an overlay:
@defun overlay-get overlay prop
@item priority
@kindex priority @r{(overlay property)}
This property's value (which should be a nonnegative integer number)
-determines the priority of the overlay. The priority matters when two
-or more overlays cover the same character and both specify the same
-property; the one whose @code{priority} value is larger takes priority
-over the other. For the @code{face} property, the higher priority
-value does not completely replace the other; instead, its face
-attributes override the face attributes of the lower priority
-@code{face} property.
+determines the priority of the overlay. No priority, or @code{nil},
+means zero.
+
+The priority matters when two or more overlays cover the same
+character and both specify the same property; the one whose
+@code{priority} value is larger overrides the other. For the
+@code{face} property, the higher priority overlay's value does not
+completely override the other value; instead, its face attributes
+override the face attributes of the lower priority @code{face}
+property.
Currently, all overlays take priority over text properties. Please
avoid using negative priority values, as we have not yet decided just
property) rather than replacing it.
@end table
+The @code{local-map} and @code{keymap} 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
+Properties}.
+
@node Finding Overlays
@subsection Searching for Overlays
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
specified region; however, empty overlays are included in the result if
-they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
+they are located at @var{beg}, strictly between @var{beg} and @var{end},
+or at @var{end} when @var{end} denotes the position at the end of the
+buffer.
@end defun
@defun next-overlay-change pos
@section Faces
@cindex faces
- A @dfn{face} is a named collection of graphical attributes: font
-family, foreground color, background color, optional underlining, and
-many others. Faces are used in Emacs to control the style of display of
-particular parts of the text or the frame. @xref{Standard Faces,,,
-emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
-comes with.
+ A @dfn{face} is a collection of graphical attributes for displaying
+text: font family, foreground color, background color, optional
+underlining, and so on. Faces control how buffer text is displayed,
+and how some parts of the frame, such as the mode-line, are displayed.
+@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
+faces Emacs normally comes with.
@cindex face id
-Each face has its own @dfn{face number}, which distinguishes faces at
-low levels within Emacs. However, for most purposes, you refer to
-faces in Lisp programs by the symbols that name them.
+ For most purposes, you refer to a face in Lisp programs using its
+@dfn{face name}. This is either a string or (equivalently) a Lisp
+symbol whose name is equal to that string.
@defun facep object
-This function returns @code{t} if @var{object} is a face name string
-or symbol (or if it is a vector of the kind used internally to record
-face data). It returns @code{nil} otherwise.
+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}.
@end defun
-Each face name is meaningful for all frames, and by default it has the
-same meaning in all frames. But you can arrange to give a particular
-face name a special meaning in one frame if you wish.
+ Each face name is meaningful for all frames, and by default it has
+the same meaning in all frames. But you can arrange to give a
+particular face name a special meaning in one frame if you wish.
@menu
* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a character.
-* Font Selection:: Finding the best available font for a face.
+* Face Remapping:: Remapping faces to alternative definitions.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
+* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
* Fontsets:: A fontset is a collection of fonts
that handle a range of character sets.
+* Low-Level Font:: Lisp representation for character display fonts.
@end menu
@node Defining Faces
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
+ People are sometimes tempted to create variables whose values specify
+which faces to use (for example, Font-Lock does this). In the vast
+majority of cases, this is not necessary, and simply using faces
+directly is preferable.
+
@defmac defface face spec doc [keyword value]@dots{}
-This declares @var{face} as a customizable face that defaults
-according to @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} specifies the face documentation. The keywords you
-can use in @code{defface} are the same as in @code{defgroup} and
-@code{defcustom} (@pxref{Common Keywords}).
+This 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} specifies the face documentation.
+The keywords you can use in @code{defface} are the same 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
@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), @code{mac} (for the Macintosh
-display), or @code{tty} (a non-graphics-capable display).
+@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty}
+(a non-graphics-capable display).
@xref{Window Systems, window-system}.
@item class
@item supports
Whether or not the frame can display the face attributes given in
-@var{value}@dots{} (@pxref{Face Attributes}). See the documentation
-for the function @code{display-supports-face-attributes-p} for more
-information on exactly how this testing is done. @xref{Display Face
-Attribute Testing}.
+@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
@end example
Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, @code{customized-face} for the
-attributes customized by the user for the current session, but not
-saved, and @code{face-documentation} for the documentation string.
+@code{face-defface-spec} to record the specified face attributes. The
+attributes saved by the user with the customization buffer are
+recorded in the symbol property @code{saved-face}; the attributes
+customized by the user for the current session, but not saved, are
+recorded in the symbol property @code{customized-face}. The
+documentation string is recorded in the symbol property
+@code{face-documentation}.
@defopt frame-background-mode
This option, if non-@code{nil}, specifies the background type to use for
@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, and what they
-mean. 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}.
-
- Any attribute in a face can have the value @code{unspecified}. This
-means the face doesn't specify that attribute. In face merging, when
-the first face fails to specify a particular attribute, that means the
-next face gets a chance. However, the @code{default} face must
-specify all attributes.
-
- Some of these font attributes are meaningful only on certain kinds of
-displays---if your display cannot handle a certain attribute, the
-attribute is ignored. (The attributes @code{:family}, @code{:width},
-@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
-an X Logical Font Descriptor.)
+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}.
+
+ 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.
+
+ Some of these font attributes are meaningful only on certain kinds
+of displays. If your display cannot handle a certain attribute, the
+attribute is ignored.
@table @code
@item :family
-Font family name, or fontset name (@pxref{Fontsets}). If you specify a
-font family name, the wild-card characters @samp{*} and @samp{?} are
-allowed.
+Font family name or fontset name (a string). 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.
+
+@item :foundry
+The name of the @dfn{font foundry} in which the font family specified
+by the @code{:family} attribute is located (a string). The wild-card
+characters @samp{*} and @samp{?} are allowed.
@item :width
-Relative proportionate width, also known as the character set width or
+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}.
@item :height
-Either the font height, an integer in units of 1/10 point, a floating
+Font height---either an integer in units of 1/10 point, or a floating
point number specifying the amount by which to scale the height of any
-underlying face, or a function, which is called with the old height
-(from the underlying face), and should return the new height.
+underlying face, or a function that is called with one argument (the
+height of the underlying face) and returns the height of the new face.
+If the function is passed an integer argument, it must return an
+integer.
+
+The height of the default face must be specified using an integer;
+floating point and function values are not allowed.
@item :weight
-Font weight---a symbol from this series (from most dense to most faint):
+Font weight---one of the symbols (from densest to faintest)
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
-@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
-or @code{ultra-light}.
-
-On a text-only terminal, any weight greater than normal is displayed as
-extra bright, and any weight less than normal is displayed as
-half-bright (provided the terminal supports the feature).
+@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or
+@code{ultra-light}. On text-only terminals that support
+variable-brightness text, any weight greater than normal is displayed
+as extra bright, and any weight less than normal is displayed as
+half-bright.
@item :slant
-Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
-@code{reverse-italic}, or @code{reverse-oblique}.
-
-On a text-only terminal, slanted text is displayed as half-bright, if
-the terminal supports the feature.
+Font slant---one of the symbols @code{italic}, @code{oblique},
+@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On
+text-only terminals that support variable-brightness text, slanted
+text is displayed as half-bright.
@item :foreground
Foreground color, a string. The value can be a system-defined color
-name, or a hexadecimal color specification of the form
-@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
-@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
-blue, and @samp{#ffffff} is white.)
+name, or a hexadecimal color specification. @xref{Color Names}. On
+black-and-white displays, certain shades of gray are implemented by
+stipple patterns.
@item :background
-Background color, a string, like the foreground color.
-
-@item :inverse-video
-Whether or not characters should be displayed in inverse video. The
-value should be @code{t} (yes) or @code{nil} (no).
-
-@item :stipple
-The background stipple, a bitmap.
-
-The value can be a string; that should be the name of a file containing
-external-format X bitmap data. The file is found in the directories
-listed in the variable @code{x-bitmap-file-path}.
-
-Alternatively, the value can specify the bitmap directly, with a list
-of the form @code{(@var{width} @var{height} @var{data})}. Here,
-@var{width} and @var{height} specify the size in pixels, and
-@var{data} is a string containing the raw bits of the bitmap, row by
-row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
-in the string (which should be a unibyte string for best results).
-This means that each row always occupies at least one whole byte.
-
-If the value is @code{nil}, that means use no stipple pattern.
-
-Normally you do not need to set the stipple attribute, because it is
-used automatically to handle certain shades of gray.
+Background color, a string. The value can be a system-defined color
+name, or a hexadecimal color specification. @xref{Color Names}.
@item :underline
Whether or not characters should be underlined, and in what color. If
Whether or not characters should be strike-through, and in what
color. The value is used like that of @code{:underline}.
-@item :inherit
-The name of a face from which to inherit attributes, or a list of face
-names. Attributes from inherited faces are merged into the face like an
-underlying face would be, with higher priority than underlying faces.
-If a list of faces is used, attributes from faces earlier in the list
-override those from later faces.
-
@item :box
Whether or not a box should be drawn around characters, its color, the
-width of the box lines, and 3D appearance.
-@end table
-
- Here are the possible values of the @code{:box} attribute, and what
-they mean:
+width of the box lines, and 3D appearance. Here are the possible
+values of the @code{:box} attribute, and what they mean:
@table @asis
@item @code{nil}
is used.
@end table
- In older versions of Emacs, before @code{:family}, @code{:height},
-@code{:width}, @code{:weight}, and @code{:slant} existed, these
-attributes were used to specify the type face. They are now
-semi-obsolete, but they still work:
+@item :inverse-video
+Whether or not characters should be displayed in inverse video. The
+value should be @code{t} (yes) or @code{nil} (no).
-@table @code
-@item :font
-This attribute specifies the font name.
+@item :stipple
+The background stipple, a bitmap.
-@item :bold
-A non-@code{nil} value specifies a bold font.
+The value can be a string; that should be the name of a file containing
+external-format X bitmap data. The file is found in the directories
+listed in the variable @code{x-bitmap-file-path}.
-@item :italic
-A non-@code{nil} value specifies an italic font.
-@end table
+Alternatively, the value can specify the bitmap directly, with a list
+of the form @code{(@var{width} @var{height} @var{data})}. Here,
+@var{width} and @var{height} specify the size in pixels, and
+@var{data} is a string containing the raw bits of the bitmap, row by
+row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
+in the string (which should be a unibyte string for best results).
+This means that each row always occupies at least one whole byte.
- For compatibility, you can still set these ``attributes,'' even
-though they are not real face attributes. Here is what that does:
+If the value is @code{nil}, that means use no stipple pattern.
+
+Normally you do not need to set the stipple attribute, because it is
+used automatically to handle certain shades of gray.
-@table @code
@item :font
-You can specify an X font name as the ``value'' of this ``attribute'';
-that sets the @code{:family}, @code{:width}, @code{:height},
-@code{:weight}, and @code{:slant} attributes according to the font name.
+The font used to display the face. Its value should be a font object.
+@xref{Font Selection}, for information about font objects.
+
+When specifying this attribute using @code{set-face-attribute}
+(@pxref{Attribute Functions}), you may also supply a font spec, a font
+entity, or a string. Emacs converts such values to an appropriate
+font object, and stores that font object as the actual attribute
+value. If you specify a string, the contents of the string should be
+a font name (@pxref{Font X,, Font Specification Options, emacs, The
+GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
+Emacs chooses the first font matching those wildcards. Specifying
+this attribute also changes the values of the @code{:family},
+@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
+@code{:slant} attributes.
-If the value is a pattern with wildcards, the first font that matches
-the pattern is used to set these attributes.
+@item :inherit
+The name of a face from which to inherit attributes, or a list of face
+names. Attributes from inherited faces are merged into the face like
+an underlying face would be, with higher priority than underlying
+faces. If a list of faces is used, attributes from faces earlier in
+the list override those from later faces.
+@end table
-@item :bold
-A non-@code{nil} makes the face bold; @code{nil} makes it normal.
-This actually works by setting the @code{:weight} attribute.
+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}.
-@item :italic
-A non-@code{nil} makes the face italic; @code{nil} makes it normal.
-This actually works by setting the @code{:slant} attribute.
-@end table
+@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
+to be displayed; if it is @code{nil}, the selected frame is used.
+@end defun
@defvar x-bitmap-file-path
This variable specifies a list of directories for searching
attributes of an existing face.
@defun set-face-attribute face frame &rest arguments
-This function sets one or more attributes of face @var{face} for frame
+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.
@end defun
@defun face-attribute face attribute &optional frame inherit
-This returns the value of the @var{attribute} attribute of face
-@var{face} on @var{frame}. If @var{frame} is @code{nil},
-that means the selected frame (@pxref{Input Focus}).
+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}).
If @var{frame} is @code{t}, this returns whatever new-frames default
value you previously specified with @code{set-face-attribute} for the
from a subsequent face in the face list or that is inherited from
another face.
-@code{unspecified} is a relative value for all attributes.
-For @code{:height}, floating point values are also relative.
+@code{unspecified} is a relative value for all attributes. For
+@code{:height}, floating point and function values are also relative.
For example:
@end example
@end defun
+@defun face-all-attributes face &optional frame
+This function returns an alist of attributes of @var{face}. The
+elements of the result are name-value pairs of the form
+@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument
+@var{frame} specifies the frame whose definition of @var{face} to
+return; if omitted or @code{nil}, the returned value describes the
+default attributes of @var{face} for newly created frames.
+@end defun
+
@defun merge-face-attribute attribute value1 value2
If @var{value1} is a relative value for the face attribute
@var{attribute}, returns it merged with the underlying value
face attribute @var{attribute}, returns @var{value1} unchanged.
@end defun
- The functions above did not exist before Emacs 21. For compatibility
-with older Emacs versions, you can use the following functions to set
-and examine the face attributes which existed in those versions.
-They use values of @code{t} and @code{nil} for @var{frame}
+ The following functions provide compatibility with Emacs 20 and
+below. They work by calling @code{set-face-attribute}. Values of
+@code{t} and @code{nil} for their @var{frame} argument are handled
just like @code{set-face-attribute} and @code{face-attribute}.
@defun set-face-foreground face color &optional frame
@defunx set-face-background face color &optional frame
-These functions set the foreground (or background, respectively) color
-of face @var{face} to @var{color}. The argument @var{color} should be a
-string, the name of a color.
-
-Certain shades of gray are implemented by stipple patterns on
-black-and-white screens.
+These functions set the @code{:foreground} attribute (or
+@code{:background} attribute, respectively) of @var{face} to
+@var{color}.
@end defun
@defun set-face-stipple face pattern &optional frame
-This function sets the background stipple pattern of face @var{face}
-to @var{pattern}. The argument @var{pattern} should be the name of a
-stipple pattern defined by the X server, or actual bitmap data
-(@pxref{Face Attributes}), or @code{nil} meaning don't use stipple.
-
-Normally there is no need to pay attention to stipple patterns, because
-they are used automatically to handle certain shades of gray.
+This function sets the @code{:stipple} attribute of @var{face} to
+@var{pattern}.
@end defun
@defun set-face-font face font &optional frame
-This function sets the font of face @var{face}. This actually sets
-the attributes @code{:family}, @code{:width}, @code{:height},
-@code{:weight}, and @code{:slant} according to the font name
+This function sets the @code{:font} attribute of @var{face} to
@var{font}.
@end defun
@defun set-face-bold-p face bold-p &optional frame
-This function specifies whether @var{face} should be bold. If
-@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
-This actually sets the @code{:weight} attribute.
+This function sets the @code{:weight} attribute of @var{face} to
+@var{normal} if @var{bold-p} is @code{nil}, and to @var{bold}
+otherwise.
@end defun
@defun set-face-italic-p face italic-p &optional frame
-This function specifies whether @var{face} should be italic. If
-@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
-This actually sets the @code{:slant} attribute.
+This function sets the @code{:slant} attribute of @var{face} to
+@var{normal} if @var{italic-p} is @code{nil}, and to @var{italic}
+otherwise.
@end defun
@defun set-face-underline-p face underline &optional frame
-This function sets the underline attribute of face @var{face}.
-Non-@code{nil} means do underline; @code{nil} means don't.
-If @var{underline} is a string, underline with that color.
+This function sets the @code{:underline} attribute of @var{face} to
+@var{underline}.
@end defun
@defun set-face-inverse-video-p face inverse-video-p &optional frame
-This function sets the @code{:inverse-video} attribute of face
-@var{face}.
+This function sets the @code{:inverse-video} attribute of @var{face}
+to @var{inverse-video-p}.
@end defun
@defun invert-face face &optional frame
@var{face}.
@end defun
- These 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
+ 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.
@end defun
@defun face-bold-p face &optional frame
-This function returns @code{t} if @var{face} is bold---that is, if it is
-bolder than normal. It returns @code{nil} otherwise.
+This function returns a non-@code{nil} value if the @code{:weight}
+attribute of @var{face} is bolder than normal (i.e., one of
+@code{semi-bold}, @code{bold}, @code{extra-bold}, or
+@code{ultra-bold}). Otherwise, it returns @code{nil}.
@end defun
@defun face-italic-p face &optional frame
-This function returns @code{t} if @var{face} is italic or oblique,
+This function returns a non-@code{nil} value if the @code{:slant}
+attribute of @var{face} is @code{italic} or @code{oblique}, and
@code{nil} otherwise.
@end defun
@node Displaying Faces
@subsection Displaying Faces
- Here are the ways to specify which faces to use for display of text:
+ Here is how Emacs determines the face to use for displaying any
+given piece of text:
@itemize @bullet
@item
-With defaults. The @code{default} face is used as the ultimate
-default for all text. (In Emacs 19 and 20, the @code{default}
-face is used only when no other face is specified.)
+If the text consists of a special glyph, the glyph can specify a
+particular face. @xref{Glyphs}.
@item
-For a mode line or header line, the face @code{mode-line} or
-@code{mode-line-inactive}, or @code{header-line}, is merged in just
-before @code{default}.
+If the text lies within an active region, Emacs highlights it using
+the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs
+Manual}.
@item
-With text properties. A character can have a @code{face} property; if
-so, the faces and face attributes specified there apply. @xref{Special
-Properties}.
+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}.
-If the character has a @code{mouse-face} property, that is used instead
-of the @code{face} property when the mouse is ``near enough'' to the
-character.
+When multiple overlays cover one character, an overlay with higher
+priority overrides those with lower priority. @xref{Overlays}.
@item
-With overlays. An overlay can have @code{face} and @code{mouse-face}
-properties too; they apply to all the text covered by the overlay.
+If the text contains a @code{face} or @code{mouse-face} property,
+Emacs applies the specified faces and face attributes. @xref{Special
+Properties}. (This is how Font Lock mode faces are applied.
+@xref{Font Lock Mode}.)
@item
-With a region that is active. In Transient Mark mode, the region is
-highlighted with the face @code{region} (@pxref{Standard Faces,,,
-emacs, The GNU Emacs Manual}).
+If the text lies within the mode line of the selected window, Emacs
+applies the @code{mode-line} face. For the mode line of a
+non-selected window, Emacs applies the @code{mode-line-inactive} face.
+For a header line, Emacs applies the @code{header-line} face.
@item
-With special glyphs. Each glyph can specify a particular face
-number. @xref{Glyphs}.
+If any given attribute has not been specified during the preceding
+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 first the face of any
-special glyph; then the face for region highlighting, if appropriate;
-then the faces specified by overlays, followed by those specified by
-text properties, then the @code{mode-line} or
-@code{mode-line-inactive} or @code{header-line} face (if in a mode
-line or a header line), and last the @code{default} face.
-
- When multiple overlays cover one character, an overlay with higher
-priority overrides those with lower priority. @xref{Overlays}.
-
-@node Font Selection
-@subsection Font Selection
-
- @dfn{Selecting a font} means mapping the specified face attributes for
-a character to a font that is available on a particular display. The
-face attributes, as determined by face merging, specify most of the
-font choice, but not all. Part of the choice depends on what character
-it is.
-
- If the face specifies a fontset name, that fontset determines a
-pattern for fonts of the given charset. If the face specifies a font
-family, a font pattern is constructed.
-
- Emacs tries to find an available font for the given face attributes
-and character's registry and encoding. If there is a font that matches
-exactly, it is used, of course. The hard case is when no available font
-exactly fits the specification. Then Emacs looks for one that is
-``close''---one attribute at a time. You can specify the order to
-consider the attributes. In the case where a specified font family is
-not available, you can specify a set of mappings for alternatives to
-try.
-
-@defvar face-font-selection-order
-This variable specifies the order of importance of the face attributes
-@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The
-value should be a list containing those four symbols, in order of
-decreasing importance.
-
-Font selection first finds the best available matches for the first
-attribute listed; then, among the fonts which are best in that way, it
-searches for the best matches in the second attribute, and so on.
-
-The attributes @code{:weight} and @code{:width} have symbolic values in
-a range centered around @code{normal}. Matches that are more extreme
-(farther from @code{normal}) are somewhat preferred to matches that are
-less extreme (closer to @code{normal}); this is designed to ensure that
-non-normal faces contrast with normal ones, whenever possible.
-
-The default is @code{(:width :height :weight :slant)}, which means first
-find the fonts closest to the specified @code{:width}, then---among the
-fonts with that width---find a best match for the specified font height,
-and so on.
+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; then faces specified by overlays, then
+faces specified by text properties, then the @code{mode-line} or
+@code{mode-line-inactive} or @code{header-line} face, if appropriate,
+and finally the @code{default} face).
+
+@node Face Remapping
+@subsection Face Remapping
+
+ The variable @code{face-remapping-alist} is used for buffer-local or
+global changes in the appearance of a face. For instance, it can be
+used to make the @code{default} face a variable-pitch face within a
+particular buffer.
+
+@defvar face-remapping-alist
+An alist whose elements have the form @code{(@var{face}
+@var{remapping...})}. This causes Emacs to display text using the
+face @var{face} using @var{remapping...} instead of @var{face}'s
+ordinary definition. @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. @xref{Special Properties}.
+
+If @code{face-remapping-alist} is buffer-local, its local value takes
+effect only within that buffer.
+
+Two points bear emphasizing:
+
+@enumerate
+@item
+The new definition @var{remapping...} is the complete
+specification of how to display @var{face}---it entirely replaces,
+rather than augmenting or modifying, the normal definition of that
+face.
-One example of a case where this variable makes a difference is when the
-default font has no italic equivalent. With the default ordering, the
-@code{italic} face will use a non-italic font that is similar to the
-default one. But if you put @code{:slant} before @code{:height}, the
-@code{italic} face will use an italic font, even if its height is not
-quite right.
+@item
+If @var{remapping...} recursively references the same face name
+@var{face}, either directly remapping entry, or via the
+@code{:inherit} attribute of some other face in
+@var{remapping...}, then that reference uses normal frame-wide
+definition of @var{face} instead of the ``remapped'' definition.
+
+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
-@defvar face-font-family-alternatives
-This variable lets you specify alternative font families to try, if a
-given family is specified and doesn't exist. Each element should have
-this form:
+ A typical use of the @code{face-remapping-alist} is to change a
+buffer's @code{default} face; for example, the following changes a
+buffer's @code{default} face to use the @code{variable-pitch} face,
+with the height doubled:
@example
-(@var{family} @var{alternate-families}@dots{})
+(set (make-local-variable 'face-remapping-alist)
+ '((default variable-pitch :height 2.0)))
@end example
-If @var{family} is specified but not available, Emacs will try the other
-families given in @var{alternate-families}, one by one, until it finds a
-family that does exist.
-@end defvar
-
-@defvar face-font-registry-alternatives
-This variable lets you specify alternative font registries to try, if a
-given registry is specified and doesn't exist. Each element should have
-this form:
+ The following functions implement a higher-level interface to
+@code{face-remapping-alist}, making it easier to use
+``cooperatively''. They are mainly intended for buffer-local use, and
+so all make @code{face-remapping-alist} variable buffer-local as a
+side-effect. They use entries in @code{face-remapping-alist} which
+have the general form:
@example
-(@var{registry} @var{alternate-registries}@dots{})
+ (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
@end example
-If @var{registry} is specified but not available, Emacs will try the
-other registries given in @var{alternate-registries}, one by one,
-until it finds a registry that does exist.
-@end defvar
+Everything except the @var{face} is a ``face spec'', a list of face
+names or face attribute-value pairs. All face specs are merged
+together, with earlier values taking precedence.
- Emacs can make use of scalable fonts, but by default it does not use
-them, since the use of too many or too big scalable fonts can crash
-XFree86 servers.
+The @var{relative_specs_}n values are ``relative specs'', and are
+added by @code{face-remap-add-relative} (and removed by
+@code{face-remap-remove-relative}. These are intended for face
+modifications (such as increasing the size). Typical users of these
+relative specs would be minor modes.
-@defvar scalable-fonts-allowed
-This variable controls which scalable fonts to use. A value of
-@code{nil}, the default, means do not use scalable fonts. @code{t}
-means to use any scalable font that seems appropriate for the text.
+@var{base_specs} is the lowest-priority value, and by default is just the
+face name, which causes the global definition of that face to be used.
-Otherwise, the value must be a list of regular expressions. Then a
-scalable font is enabled for use if its name matches any regular
-expression in the list. For example,
+A non-default value of @var{base_specs} may also be set using
+@code{face-remap-set-base}. Because this @emph{overwrites} the
+default base-spec value (which inherits the global face definition),
+it is up to the caller of @code{face-remap-set-base} to add such
+inheritance if it is desired. A typical use of
+@code{face-remap-set-base} would be a major mode adding a face
+remappings, e.g., of the default face.
-@example
-(setq scalable-fonts-allowed '("muleindian-2$"))
-@end example
-@noindent
-allows the use of scalable fonts with registry @code{muleindian-2}.
-@end defvar
+@defun face-remap-add-relative face &rest specs
+This functions adds a face remapping entry of @var{face} to @var{specs}
+in the current buffer.
-@defvar face-font-rescale-alist
-This variable specifies scaling for certain faces. Its value should
-be a list of elements of the form
+It returns a ``cookie'' which can be used to later delete the remapping with
+@code{face-remap-remove-relative}.
-@example
-(@var{fontname-regexp} . @var{scale-factor})
-@end example
+@var{specs} can be any value suitable for the @code{face} text
+property, including a face name, a list of face names, or a
+face-attribute property list. The attributes given by @var{specs}
+will be merged with any other currently active face remappings of
+@var{face}, and with the global definition of @var{face} (by default;
+this may be changed using @code{face-remap-set-base}), with the most
+recently added relative remapping taking precedence.
+@end defun
-If @var{fontname-regexp} matches the font name that is about to be
-used, this says to choose a larger similar font according to the
-factor @var{scale-factor}. You would use this feature to normalize
-the font size if certain fonts are bigger or smaller than their
-nominal heights and widths would suggest.
-@end defvar
+@defun face-remap-remove-relative cookie
+This function removes a face remapping previously added by
+@code{face-remap-add-relative}. @var{cookie} should be a return value
+from that function.
+@end defun
+
+@defun face-remap-set-base face &rest specs
+This function sets the ``base remapping'' of @var{face} in the current
+buffer to @var{specs}. If @var{specs} is empty, the default base
+remapping is restored, which inherits from the global definition of
+@var{face}; note that this is different from @var{specs} containing a
+single value @code{nil}, which has the opposite result (the global
+definition of @var{face} is ignored).
+@end defun
+
+@defun face-remap-reset-base face
+This function sets the ``base remapping'' of @var{face} to its default
+value, which inherits from @var{face}'s global definition.
+@end defun
@node Face Functions
@subsection Functions for Working with Faces
@end defun
@defun face-id face
-This function returns the face number of face @var{face}.
+This function returns the @dfn{face number} of face @var{face}. This
+is a number that uniquely identifies a face at low levels within
+Emacs. It is seldom necessary to refer to a face by its face number.
@end defun
@defun face-documentation face
(put 'modeline 'face-alias 'mode-line)
@end example
-
@node Auto Faces
@subsection Automatic Face Assignment
@cindex automatic face assignment
@cindex faces, automatic choice
- This hook is used for automatically assigning facesto text in the
+ This hook is used for automatically assigning faces to text in the
buffer. It is part of the implementation of Jit-Lock mode, used by
Font-Lock.
usually assign faces to around 400 to 600 characters at each call.
@end defvar
+@node Font Selection
+@subsection Font Selection
+
+ Before Emacs can draw a character on a particular display, it must
+select a @dfn{font} for that character@footnote{In this context, the
+term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
+Mode}).}. Normally, Emacs automatically chooses a font based on the
+faces assigned to that character---specifically, the face attributes
+@code{:family}, @code{:weight}, @code{:slant}, and @code{:width}
+(@pxref{Face Attributes}). The choice of font also depends on the
+character to be displayed; some fonts can only display a limited set
+of characters. If no available font exactly fits the requirements,
+Emacs looks for the @dfn{closest matching font}. The variables in
+this section control how Emacs makes this selection.
+
+@defvar face-font-family-alternatives
+If a given family is specified but does not exist, this variable
+specifies alternative font families to try. Each element should have
+this form:
+
+@example
+(@var{family} @var{alternate-families}@dots{})
+@end example
+
+If @var{family} is specified but not available, Emacs will try the other
+families given in @var{alternate-families}, one by one, until it finds a
+family that does exist.
+@end defvar
+
+@defvar face-font-selection-order
+If there is no font that exactly matches all desired face attributes
+(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
+this variable specifies the order in which these attributes should be
+considered when selecting the closest matching font. The value should
+be a list containing those four attribute symbols, in order of
+decreasing importance. The default is @code{(:width :height :weight
+:slant)}.
+
+Font selection first finds the best available matches for the first
+attribute in the list; then, among the fonts which are best in that
+way, it searches for the best matches in the second attribute, and so
+on.
+
+The attributes @code{:weight} and @code{:width} have symbolic values in
+a range centered around @code{normal}. Matches that are more extreme
+(farther from @code{normal}) are somewhat preferred to matches that are
+less extreme (closer to @code{normal}); this is designed to ensure that
+non-normal faces contrast with normal ones, whenever possible.
+
+One example of a case where this variable makes a difference is when the
+default font has no italic equivalent. With the default ordering, the
+@code{italic} face will use a non-italic font that is similar to the
+default one. But if you put @code{:slant} before @code{:height}, the
+@code{italic} face will use an italic font, even if its height is not
+quite right.
+@end defvar
+
+@defvar face-font-registry-alternatives
+This variable lets you specify alternative font registries to try, if a
+given registry is specified and doesn't exist. Each element should have
+this form:
+
+@example
+(@var{registry} @var{alternate-registries}@dots{})
+@end example
+
+If @var{registry} is specified but not available, Emacs will try the
+other registries given in @var{alternate-registries}, one by one,
+until it finds a registry that does exist.
+@end defvar
+
+ Emacs can make use of scalable fonts, but by default it does not use
+them.
+
+@defvar scalable-fonts-allowed
+This variable controls which scalable fonts to use. A value of
+@code{nil}, the default, means do not use scalable fonts. @code{t}
+means to use any scalable font that seems appropriate for the text.
+
+Otherwise, the value must be a list of regular expressions. Then a
+scalable font is enabled for use if its name matches any regular
+expression in the list. For example,
+
+@example
+(setq scalable-fonts-allowed '("muleindian-2$"))
+@end example
+
+@noindent
+allows the use of scalable fonts with registry @code{muleindian-2}.
+@end defvar
+
+@defvar face-font-rescale-alist
+This variable specifies scaling for certain faces. Its value should
+be a list of elements of the form
+
+@example
+(@var{fontname-regexp} . @var{scale-factor})
+@end example
+
+If @var{fontname-regexp} matches the font name that is about to be
+used, this says to choose a larger similar font according to the
+factor @var{scale-factor}. You would use this feature to normalize
+the font size if certain fonts are bigger or smaller than their
+nominal heights and widths would suggest.
+@end defvar
+
@node Font Lookup
@subsection Looking Up Fonts
-@defun x-list-fonts pattern &optional face frame maximum
+@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
-@var{pattern}. If the optional arguments @var{face} and @var{frame} are
-specified, then the list is limited to fonts that are the same size as
-@var{face} currently is on @var{frame}.
-
-The argument @var{pattern} should be a string, perhaps with wildcard
-characters: the @samp{*} character matches any substring, and the
-@samp{?} character matches any single character. Pattern matching
-of font names ignores case.
-
-If you specify @var{face} and @var{frame}, @var{face} should be a face name
-(a symbol) and @var{frame} should be a frame.
+@var{name}. @var{name} should be a string containing a font name in
+either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
+Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD
+string, wildcard characters may be used: the @samp{*} character
+matches any substring, and the @samp{?} character matches any single
+character. Case is ignored when matching font names.
+
+If the optional arguments @var{reference-face} and @var{frame} are
+specified, the returned list includes only fonts that are the same
+size as @var{reference-face} (a face name) currently is on the frame
+@var{frame}.
The optional argument @var{maximum} sets a limit on how many fonts to
-return. If this is non-@code{nil}, then the return value is truncated
-after the first @var{maximum} matching fonts. Specifying a small value
-for @var{maximum} can make this function much faster, in cases where
-many fonts match the pattern.
+return. If it is non-@code{nil}, then the return value is truncated
+after the first @var{maximum} matching fonts. Specifying a small
+value for @var{maximum} can make this function much faster, in cases
+where many fonts match the pattern.
+
+The optional argument @var{width} specifies a desired font width. If
+it is non-@code{nil}, the function only returns those fonts whose
+characters are (on average) @var{width} times as wide as
+@var{reference-face}.
@end defun
@defun x-family-fonts &optional family frame
omitted or @code{nil}, it applies to the selected frame's display
(@pxref{Input Focus}).
-The list contains a vector of the following form for each font:
+Each element in the list is a vector of the following form:
@example
[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
@var{full} is the full name of the font, and
@var{registry-and-encoding} is a string giving the registry and
encoding of the font.
-
-The result list is sorted according to the current face font sort order.
-@end defun
-
-@defun x-font-family-list &optional frame
-This function returns a list of the font families available for
-@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it
-describes the selected frame's display (@pxref{Input Focus}).
-
-The value is a list of elements of this form:
-
-@example
-(@var{family} . @var{fixed-p})
-@end example
-
-@noindent
-Here @var{family} is a font family, and @var{fixed-p} is
-non-@code{nil} if fonts of that family are fixed-pitch.
@end defun
@defvar font-list-limit
string @var{fontset-spec}. The string should have this format:
@smallexample
-@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
@end smallexample
@noindent
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
-@defun set-fontset-font name character fontname &optional frame
-This function modifies the existing fontset @var{name} to
-use the font name @var{fontname} for the character @var{character}.
+@defun set-fontset-font name character font-spec &optional frame add
+This function modifies the existing fontset @var{name} to use the font
+matching with @var{font-spec} for the character @var{character}.
-If @var{name} is @code{nil}, this function modifies the default
+If @var{name} is @code{nil}, this function modifies the fontset of the
+selected frame or that of @var{frame} if @var{frame} is not
+@code{nil}.
+
+If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
-@var{from} and @var{to} are non-generic characters. In that case, use
-@var{fontname} for all characters in the range @var{from} and @var{to}
+@var{from} and @var{to} are character codepoints. In that case, use
+@var{font-spec} for all characters in the range @var{from} and @var{to}
(inclusive).
@var{character} may be a charset. In that case, use
-@var{fontname} for all character in the charsets.
+@var{font-spec} for all character in the charsets.
+
+@var{character} may be a script anme. In that case, use
+@var{font-spec} for all character in the charsets.
-@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).
+@var{font-spec} may be a font name string.
+
+The optional argument @var{add}, if non-@code{nil}, specifies how to
+add @var{font-spec} to the font specifications previously set. If it
+is @code{prepend}, @var{font-spec} is prepended. If it is
+@code{append}, @var{font-spec} is appended. By default,
+@var{font-spec} overrides the previous settings.
+
For instance, this changes the default fontset to use a font of which
-registry name is @samp{JISX0208.1983} for all characters belonging to
+family name is @samp{Kochi Gothic} for all characters belonging to
the charset @code{japanese-jisx0208}.
@smallexample
-(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+(set-fontset-font t 'japanese-jisx0208
+ (font-spec :family "Kochi Gothic"))
@end smallexample
@end defun
does that, this function's value may not be accurate.
@end defun
+@node Low-Level Font
+@subsection Low-Level Font Representation
+
+ Normally, it is not necessary to manipulate fonts directly. In case
+you need to do so, this section explains how.
+
+ In Emacs Lisp, fonts are represented using three different Lisp
+object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
+entities}.
+
+@defun fontp object &optional type
+Return @code{t} if @var{object} is a font object, font spec, or font
+entity. Otherwise, return @code{nil}.
+
+The optional argument @var{type}, if non-@code{nil}, determines the
+exact type of Lisp object to check for. In that case, @var{type}
+should be one of @code{font-object}, @code{font-spec}, or
+@code{font-entity}.
+@end defun
+
+ A font object is a Lisp object that represents a font that Emacs has
+@dfn{opened}. Font objects cannot be modified in Lisp, but they can
+be inspected. If you call @code{set-face-attribute} and pass a font
+spec, font entity, or font name string as the value of the
+@code{:font} attribute, Emacs opens the best ``matching'' font that is
+available for display. It then stores the corresponding font object
+as the actual value of the @code{:font} attribute for that face.
+
+@defun font-at position &optional window string
+Return the font object that is being used to display the character at
+position @var{position} in the window @var{window}. If @var{window}
+is @code{nil}, it defaults to the selected window. If @var{string} is
+@code{nil}, @var{position} specifies a position in the current buffer;
+otherwise, @var{string} should be a string, and @var{position}
+specifies a position in that string.
+@end defun
+
+ A font spec is a Lisp object that contains a set of specifications
+that can be used to find a font. More than one font may match the
+specifications in a font spec.
+
+@defun font-spec &rest arguments
+Return a new font spec using the specifications in @var{arguments},
+which should come in @code{property}-@code{value} pairs. The possible
+specifications are as follows:
+
+@table @code
+@item :name
+The font name (a string), in either XLFD, Fontconfig, or GTK format.
+@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
+Manual}.
+
+@item :family
+@itemx :foundry
+@itemx :weight
+@itemx :slant
+@itemx :width
+These have the same meanings as the face attributes of the same name.
+@xref{Face Attributes}.
+
+@item :size
+The font size---either a non-negative integer that specifies the pixel
+size, or a floating point number that specifies the point size.
+
+@item :adstyle
+Additional typographic style information for the font, such as
+@samp{sans}. The value should be a string or a symbol.
+
+@item :registry
+The charset registry and encoding of the font, such as
+@samp{iso8859-1}. The value should be a string or a symbol.
+
+@item :script
+The script that the font must support (a symbol).
+@end table
+@end defun
+
+@defun font-put font-spec property value
+Set the font property @var{property} in the font-spec @var{font-spec}
+to @var{value}.
+@end defun
+
+ A font entity is a reference to a font that need not be open. Its
+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.
+
+@defun find-font font-spec &optional frame
+This function returns a font entity that best matches the font spec
+@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil},
+it defaults to the selected frame.
+@end defun
+
+@defun list-fonts font-spec &optional frame num prefer
+This function returns a list of all font entities that match the font
+spec @var{font-spec}.
+
+The optional argument @var{frame}, if non-@code{nil}, specifies the
+frame on which the fonts are to be displayed. The optional argument
+@var{num}, if non-@code{nil}, should be an integer that specifies the
+maximum length of the returned list. The optional argument
+@var{prefer}, if non-@code{nil}, should be another font spec, which is
+used to control the order of the returned list; the returned font
+entities are sorted in order of decreasing ``closeness'' to that font
+spec.
+@end defun
+
+ The following functions can be used to obtain information about a
+font. For these functions, the @var{font} argument can be a font
+object, a font entity, or a font spec.
+
+@defun font-get font property
+This function returns the value of the font property @var{property}
+for @var{font}.
+
+If @var{font} is a font spec and the font spec does not specify
+@var{property}, the return value is @code{nil}. If @var{font} is a
+font object or font entity, the value for the @var{:script} property
+may be a list of scripts supported by the font.
+@end defun
+
+@defun font-face-attributes font &optional frame
+This function returns a list of face attributes corresponding to
+@var{font}. The optional argument @var{frame} specifies the frame on
+which the font is to be displayed. If it is @code{nil}, the selected
+frame is used. The return value has the form
+
+@smallexample
+(:family @var{family} :height @var{height} :weight @var{weight}
+ :slant @var{slant} :width @var{width})
+@end smallexample
+
+where the values of @var{family}, @var{height}, @var{weight},
+@var{slant}, and @var{width} are face attribute values. Some of these
+key-attribute pairs may be omitted from the list if they are not
+specified by @var{font}.
+@end defun
+
+@defun font-xlfd-name font &optional fold-wildcards
+This function returns the XLFD (X Logical Font Descriptor), a string,
+matching @var{font}. @xref{Font X,, Font Specification Options,
+emacs, The GNU Emacs Manual}, for information about XLFDs. If the
+name is too long for an XLFD (which can contain at most 255
+characters), the function returns @code{nil}.
+
+If the optional argument @var{fold-wildcards} is non-@code{nil},
+consecutive wildcards in the XLFD are folded into one.
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
insert images into text, and also control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
-specifications.
+specifications. Display specifications in the same @code{display}
+property value generally apply in parallel to the text they cover.
- Some kinds of @code{display} properties specify something to display
-instead of the text that has the property. In this case, ``the text''
-means all the consecutive characters that have the same Lisp object as
-their @code{display} property; these characters are replaced as a
-single unit. By contrast, characters that have similar but distinct
-Lisp objects as their @code{display} properties are handled
-separately. Here's a function that illustrates this point:
+ If several sources (overlays and/or a text property) specify values
+for the @code{display} property, only one of the values takes effect,
+following the rules of @code{get-char-property}. @xref{Examining
+Properties}.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
+
+@menu
+* Replacing Specs:: Display specs that replace the text.
+* Specified Space:: Displaying one space with a specified width.
+* Pixel Specification:: Specifying space width or height in pixels.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+@end menu
+
+@node Replacing Specs
+@subsection Display Specs That Replace The Text
+
+ Some kinds of @code{display} specifications specify something to
+display instead of the text that has the property. These are called
+@dfn{replacing} display specifications. Emacs does not allow the user
+to interactively move point into the middle of buffer text that is
+replaced in this way.
+
+ If a list of display specifications includes more than one replacing
+display specification, the first overrides the rest. Replacing
+display specifications make most other display specifications
+irrelevant, since those don't apply to the replacement.
+
+ For replacing display specifications, ``the text that has the
+property'' means all the consecutive characters that have the same
+Lisp object as their @code{display} property; these characters are
+replaced as a single unit. By contrast, characters that have similar
+but distinct Lisp objects as their @code{display} properties are
+handled separately. Here's a function that illustrates this point:
@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(let ((string (concat "A")))
- (put-text-property (point) (2+ (point)) 'display string)
+ (put-text-property (point) (+ 2 (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
@end smallexample
whether they got this property from a single call to
@code{put-text-property} or from two different calls.
- The rest of this section describes several kinds of
-display specifications and what they mean.
-
-@menu
-* Specified Space:: Displaying one space with a specified width.
-* Pixel Specification:: Specifying space width or height in pixels.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
- up or down on the page; adjusting the width
- of spaces within text.
-* Display Margins:: Displaying text or images to the side of the main text.
-@end menu
-
@node Specified Space
@subsection Specified Spaces
@cindex spaces, specified height or width
@cindex display margins
@cindex margins, display
- A buffer can have blank areas called @dfn{display margins} on the left
-and on the right. Ordinary text never appears in these areas, but you
-can put things into the display margins using the @code{display}
-property.
-
- To put text in the left or right display margin of the window, use a
-display specification of the form @code{(margin right-margin)} or
-@code{(margin left-margin)} on it. To put an image in a display margin,
-use that display specification along with the display specification for
-the image. Unfortunately, there is currently no way to make
-text or images in the margin mouse-sensitive.
-
- If you put such a display specification directly on text in the
-buffer, the specified margin display appears @emph{instead of} that
-buffer text itself. To put something in the margin @emph{in
-association with} certain buffer text without preventing or altering
-the display of that text, put a @code{before-string} property on the
-text and put the display specification on the contents of the
-before-string.
+ A buffer can have blank areas called @dfn{display margins} on the
+left and on the right. Ordinary text never appears in these areas,
+but you can put things into the display margins using the
+@code{display} property. There is currently no way to make text or
+images in the margin mouse-sensitive.
+
+ The way to display something in the margins is to specify it in a
+margin display specification in the @code{display} property of some
+text. This is a replacing display specification, meaning that the
+text you put it on does not get displayed; the margin display appears,
+but that text does not.
+
+ A margin display specification looks like @code{((margin
+right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
+Here, @var{spec} is another display specification that says what to
+display in the margin. Typically it is a string of text to display,
+or an image descriptor.
+
+ To display something in the margin @emph{in association with}
+certain buffer text, without altering or preventing the display of
+that text, put a @code{before-string} property on the text and put the
+margin display specification on the contents of the before-string.
Before the display margins can display anything, you must give
them a nonzero width. The usual way to do that is to set these
* XBM Images:: Special features for XBM format.
* XPM Images:: Special features for XPM format.
* GIF Images:: Special features for GIF format.
+* TIFF Images:: Special features for TIFF format.
* PostScript Images:: Special features for PostScript format.
* Other Image Types:: Various other formats are supported.
* Defining Images:: Convenient ways to define an image for later use.
(run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
@end ignore
+@node TIFF Images
+@subsection TIFF Images
+@cindex TIFF
+
+ For TIFF images, specify image type @code{tiff}.
+
+@table @code
+@item :index @var{index}
+You can use @code{:index} to specify one image from a TIFF file that
+contains more than one image. This property specifies use of image
+number @var{index} from the file. If the TIFF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
+@end table
+
@node PostScript Images
@subsection PostScript Images
@cindex postscript images
@end example
@end table
- Displaying PostScript images from Lisp data is not currently
-implemented, but it may be implemented by the time you read this.
-See the @file{etc/NEWS} file to make sure.
-
@node Other Image Types
@subsection Other Image Types
@cindex PBM
@item :foreground @var{foreground}
The value, @var{foreground}, should be a string specifying the image
foreground color, or @code{nil} for the default color. This color is
-used for each pixel in the XBM that is 1. The default is the frame's
+used for each pixel in the PBM that is 1. The default is the frame's
foreground color.
@item :background @var{background}
The value, @var{background}, should be a string specifying the image
background color, or @code{nil} for the default color. This color is
-used for each pixel in the XBM that is 0. The default is the frame's
+used for each pixel in the PBM that is 0. The default is the frame's
background color.
@end table
@code{nil}, the selected frame is used. If @var{frame} is @code{t},
the refresh is applied to all existing frames.
-This works by removing all image with image specifications matching
-@var{spec} from the image cache. Thus, the next time the image is
-displayed, Emacs will load the image again.
+This works by removing from the image cache all the images whose image
+specifications match @var{spec}. The next time Emacs needs to display
+such an image, it will reload the image anew.
@end defun
-@defun clear-image-cache &optional frame
-This function clears the entire image cache. If @var{frame} is
-non-@code{nil}, only the cache for that frame is cleared. Otherwise,
-all frames' caches are cleared.
+@defun clear-image-cache &optional filter
+This function clears the image cache. If @var{filter} is
+a frame, only the cache for that frame is cleared. If omitted or
+@code{nil}, clear the images on the selected frame. If @code{t},
+all frames' caches are cleared. Otherwise, @var{filter} is taken as
+a file name and only images that reference this file will be flushed.
@end defun
If an image in the image cache has not been displayed for a specified
specific tasks.
@defun define-button-type name &rest properties
-Define a `button type' called @var{name}. The remaining arguments
+Define a `button type' called @var{name} (a symbol).
+The remaining arguments
form a sequence of @var{property value} pairs, specifying default
property values for buttons with this type (a button's type may be set
by giving it a @code{type} property when creating the button, using
@defun glyph-face glyph
This function returns face of simple glyph code @var{glyph}, or
@code{nil} if @var{glyph} has the default face (face-id 0).
+@xref{Face Functions}.
@end defun
On character terminals, you can set up a @dfn{glyph table} to define
concerned; the individual Emacs windows are not known to X at all.
@defvar window-system
-This variable tells Lisp programs what window system Emacs is running
-under. The possible values are
+This frame-local variable tells Lisp programs what window system Emacs is using
+for displaying the frame. The possible values are
@table @code
@item x
@cindex X Window System
-Emacs is displaying using X.
-@item pc
-Emacs is displaying using MS-DOS.
+Emacs is displaying the frame using X.
@item w32
-Emacs is displaying using Windows.
-@item mac
-Emacs is displaying using a Macintosh.
+Emacs is displaying the frame using native MS-Windows GUI.
+@item pc
+Emacs is displaying the frame using MS-DOS direct screen writes.
@item nil
-Emacs is using a character-based terminal.
+Emacs is displaying the frame on a character-based terminal.
@end table
@end defvar
+@defvar initial-window-system
+This variable holds the value of @code{window-system} used for the
+first frame created by Emacs during startup. (When Emacs is invoked
+with the @option{--daemon} option, it does not create any initial
+frames, so @code{initial-window-system} is @code{nil}. @xref{Initial
+Options, daemon,, emacs, The GNU Emacs Manual}.)
+@end defvar
+
+@defun window-system &optional frame
+This function returns a symbol whose name tells what window system is
+used for displaying @var{frame} (which defaults to the currently
+selected frame). The list of possible symbols it returns is the same
+one documented for the variable @code{window-system} above.
+@end defun
+
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed