@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
@node Display, System Interface, Processes, Top
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.
+ 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.
-@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.
+ On text-only terminals, suspending and resuming Emacs normally also
+refreshes the screen. Some terminal emulators record separate
+contents for display-oriented programs such as Emacs and for ordinary
+sequential display. If you are using such a terminal, you might want
+to inhibit the redisplay on resumption.
- Normally, suspending and resuming Emacs also refreshes the screen.
-Some terminal emulators record separate contents for display-oriented
-programs such as Emacs and for ordinary sequential display. If you are
-using such a terminal, you might want to inhibit the redisplay on
-resumption.
-
-@defvar no-redraw-on-reenter
+@defopt no-redraw-on-reenter
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
-@end defvar
+@end defopt
@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay
+ Emacs normally tries to redisplay the screen whenever it waits for
+input. With the following 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.
+
+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
for this; @pxref{Display Tables}).
@defopt truncate-lines
-This buffer-local variable controls how Emacs displays lines that extend
-beyond the right edge of the window. The default is @code{nil}, which
-specifies continuation. If the value is non-@code{nil}, then these
-lines are truncated.
-
-If the variable @code{truncate-partial-width-windows} is non-@code{nil},
-then truncation is always used for side-by-side windows (within one
-frame) regardless of the value of @code{truncate-lines}.
+If this buffer-local variable is non-@code{nil}, lines that extend
+beyond the right edge of the window are truncated; otherwise, they are
+continued. As a special exception, the variable
+@code{truncate-partial-width-windows} takes precedence in
+@dfn{partial-width} windows (i.e., windows that do not occupy the
+entire frame width).
@end defopt
@defopt default-truncate-lines
@end defopt
@defopt truncate-partial-width-windows
-This variable controls display of lines that extend beyond the right
-edge of the window, in side-by-side windows (@pxref{Splitting Windows}).
-If it is non-@code{nil}, these lines are truncated; otherwise,
-@code{truncate-lines} says what to do with them.
+This variable controls line truncation in @dfn{partial-width} windows.
+A partial-width window is one that does not occupy the entire frame
+width (@pxref{Splitting Windows}). If the value is @code{nil}, line
+truncation is determined by the variable @code{truncate-lines} (see
+above). If the value is an integer @var{n}, lines are truncated if
+the partial-width window has fewer than @var{n} columns, regardless of
+the value of @code{truncate-lines}; if the partial-width window has
+@var{n} or more columns, line truncation is determined by
+@code{truncate-lines}. For any other non-@code{nil} value, lines are
+truncated in every partial-width window, regardless of the value of
+@code{truncate-lines}.
@end defopt
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}, it defines a
+``prefix'' that is prepended to every continuation line at
+display-time. (If lines are truncated, the wrap-prefix is never
+used.) It may be a string, an image, or a stretch-glyph; the value is
+interpreted in the same way as a @code{display} text property.
+@xref{Display Property}.
+
+A wrap-prefix may also be specified for regions of text, using the
+@code{wrap-prefix} text or overlay property. This takes precedence
+over the @code{wrap-prefix} variable. @xref{Special Properties}.
+@end defvar
+
+@defvar line-prefix
+If this buffer-local variable is non-@code{nil}, it defines a
+``prefix'' that is prepended to every non-continuation line at
+display-time. It may be a string, an image, or a stretch-glyph; the
+value is interpreted in the same way as a @code{display} text
+property. @xref{Display Property}.
+
+A line-prefix may also be specified for regions of text using the
+@code{line-prefix} text or overlay property. This takes precedence
+over 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
-become slow. Then you might find it advisable to set
+continuation to display them, computing the continuation lines can
+make Emacs redisplay slow. The column computation and indentation
+functions also become slow. Then you might find it advisable to set
@code{cache-long-line-scans} to @code{t}.
@defvar cache-long-line-scans
@code{(message nil)} or for any other reason.
@end defvar
-@defvar echo-keystrokes
+@defopt echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
which specifies the
sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
-@end defvar
+@end defopt
@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
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
(remove-from-invisibility-spec 'my-symbol)
@end example
+ You can check for invisibility using the following function:
+
+@defun invisible-p pos-or-prop
+If @var{pos-or-prop} is a marker or number, this function returns a
+non-@code{nil} value if the text at that position is invisible.
+
+If @var{pos-or-prop} is any other kind of Lisp object, that is taken
+to mean a possible value of the @code{invisible} text or overlay
+property. In that case, this function returns a non-@code{nil} value
+if that value would cause text to become invisible, based on the
+current value of @code{buffer-invisibility-spec}.
+@end defun
+
@vindex line-move-ignore-invisible
Ordinarily, functions that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
-explicitly ignore invisible newlines if
-@code{line-move-ignore-invisible} is non-@code{nil} (the default), but
-only because they are explicitly programmed to do so.
+ignore invisible newlines if @code{line-move-ignore-invisible} is
+non-@code{nil} (the default), but only because they are explicitly
+programmed to do so.
However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
@end example
@end defvar
-@defvar selective-display-ellipses
+@defopt selective-display-ellipses
If this buffer-local variable is non-@code{nil}, then Emacs displays
@samp{@dots{}} at the end of a line that is followed by hidden text.
This example is a continuation of the previous one.
You can use a display table to substitute other text for the ellipsis
(@samp{@dots{}}). @xref{Display Tables}.
-@end defvar
+@end defopt
@node Temporary Displays
@section Temporary Displays
@end example
@end defspec
-@defvar temp-buffer-show-function
+@defopt temp-buffer-show-function
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-selected-window} and with the chosen window and buffer
selected.
-@end defvar
+@end defopt
@defvar temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
@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
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
+@cindex scalability of overlays
+The visual effect of an overlay is the same as of the corresponding
+text property (@pxref{Text Properties}). However, due to a different
+implementation, overlays generally don't scale well (many operations
+take a time that is proportional to the number of overlays in the
+buffer). If you need to affect the visual appearance of many portions
+in the buffer, we recommend using text properties.
+
An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text. When you create the overlay,
the overlay. The string does not appear in the buffer in any
sense---only on the screen.
+@item line-prefix
+This property specifies a display spec to prepend to each
+non-continuation line at display-time. @xref{Truncation}.
+
+@itemx wrap-prefix
+This property specifies a display spec to prepend to each continuation
+line at display-time. @xref{Truncation}.
+
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
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
parts of Emacs text.
@vindex default-line-spacing
- You can specify the line spacing for all lines in a frame with the
-@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
-However, if the variable @code{default-line-spacing} is
-non-@code{nil}, it overrides the frame's @code{line-spacing}
-parameter. An integer value specifies the number of pixels put below
-lines on graphical displays. A floating point number specifies the
-spacing relative to the frame's default line height.
+ On graphical terminals, you can specify the line spacing for all
+lines in a frame, using the @code{line-spacing} frame parameter
+(@pxref{Layout Parameters}). However, if the variable
+@code{default-line-spacing} is non-@code{nil}, it overrides the
+frame's @code{line-spacing} parameter. An integer value specifies the
+number of pixels put below lines. A floating point number specifies
+the spacing relative to the frame's default line height.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines on graphical displays. A floating
-point number specifies the spacing relative to the default frame line
-height. This overrides line spacings specified for the frame.
+the number of pixels put below lines. A floating point number
+specifies the spacing relative to the default frame line height. This
+overrides line spacings specified for the frame.
@kindex line-spacing @r{(text property)}
Finally, a newline can have a @code{line-spacing} text or overlay
numeric height value specifies the line spacing, rather than the line
height.
+ On text-only terminals, the line spacing cannot be altered.
+
@node Faces
@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:
-
-@table @code
-@item :font
-This attribute specifies the font name.
+@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 :bold
-A non-@code{nil} value specifies a bold font.
+@item :stipple
+The background stipple, a bitmap.
-@item :italic
-A non-@code{nil} value specifies an italic font.
-@end table
+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}.
- For compatibility, you can still set these ``attributes,'' even
-though they are not real face attributes. Here is what that does:
+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.
-@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.
+If the value is @code{nil}, that means use no stipple pattern.
-If the value is a pattern with wildcards, the first font that matches
-the pattern is used to set these attributes.
+Normally you do not need to set the stipple attribute, because it is
+used automatically to handle certain shades of gray.
-@item :bold
-A non-@code{nil} makes the face bold; @code{nil} makes it normal.
-This actually works by setting the @code{:weight} attribute.
+@item :font
+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.
-@item :italic
-A non-@code{nil} makes the face italic; @code{nil} makes it normal.
-This actually works by setting the @code{:slant} attribute.
+@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
-@defvar x-bitmap-file-path
+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
+to be displayed; if it is @code{nil}, the selected frame is used.
+@end defun
+
+@defopt underline-minimum-offset
+This variable specifies the minimum distance between the baseline and
+the underline, in pixels, when displaying underlined text.
+@end defopt
+
+@defopt x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
-@end defvar
+@end defopt
@defun bitmap-spec-p object
This returns @code{t} if @var{object} is a valid bitmap specification,
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 the normal definition of @var{face} in the
+selected frame, 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 @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
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.
+
+@defopt 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 defopt
+
+@defopt 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 defopt
+
+@defopt 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 defopt
+
+ Emacs can make use of scalable fonts, but by default it does not use
+them.
+
+@defopt 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 defopt
+
+@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 fontset of the
+selected frame or that of @var{frame} if @var{frame} is not
+@code{nil}.
-If @var{name} is @code{nil}, this function modifies the default
+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{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+@var{character} may be a script anme. In that case, use
+@var{font-spec} for all character in the charsets.
+
+@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.
+
+@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
+
+ 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.
+
+ 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
buffer-local in every buffer.
@end defopt
-@defvar indicate-buffer-boundaries
+@defopt indicate-buffer-boundaries
This buffer-local variable controls how the buffer boundaries and
window scrolling are indicated in the window fringes.
bitmap in left fringe, and the bottom angle bitmap as well as both
arrow bitmaps in right fringe. To show the angle bitmaps in the left
fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
-@end defvar
+@end defopt
@defvar default-indicate-buffer-boundaries
The value of this variable is the default value for
normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
display line.
-@defvar overflow-newline-into-fringe
+@defopt overflow-newline-into-fringe
If this is non-@code{nil}, lines exactly as wide as the window (not
counting the final newline character) are not continued. Instead,
when point is at the end of the line, the cursor appears in the right
fringe.
-@end defvar
+@end defopt
@defvar fringe-cursor-alist
This variable specifies the mapping from logical cursor type to the
window take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
-@defvar scroll-bar-mode
+@defopt scroll-bar-mode
This variable, always local in all buffers, controls whether and where
to put scroll bars in windows displaying the buffer. The possible values
are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
the left, and @code{right} to put a scroll bar on the right.
-@end defvar
+@end defopt
@defun window-current-scroll-bars &optional window
This function reports the scroll bar type for window @var{window}.
but that text does not.
A margin display specification looks like @code{((margin
-right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+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.
* 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
@subsection Image Cache
@cindex image cache
- Emacs stores images in an image cache so that it can display them
-again more efficiently. When Emacs displays an image, it searches the
-image cache for an existing image specification @code{equal} to the
-desired specification. If a match is found, the image is displayed
-from the cache; otherwise, Emacs loads the image normally.
+ Emacs caches images so that it can display them again more
+efficiently. When Emacs displays an image, it searches the image
+cache for an existing image specification @code{equal} to the desired
+specification. If a match is found, the image is displayed from the
+cache; otherwise, Emacs loads the image normally.
Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification. For example, suppose you
display an image using a specification that contains a @code{:file}
-property. The image is loaded from the given file and stored in the
-image cache. If you later display the image again, using the same
-image specification, the image is displayed from the image cache.
-Normally, this is not a problem. However, if the image file has
-changed in the meantime, Emacs would be displaying the old version of
-the image. In such a situation, it is necessary to ``refresh'' the
-image using @code{image-refresh}.
+property. The image is automatically cached, and subsequent displays
+of that image, with the same image specification, will use the image
+cache. If the image file changes in the meantime, Emacs would be
+displaying the old version of the image. In such a situation, you can
+``refresh'' the image by calling @code{image-refresh}.
+
+ In Emacs' current implementation, each graphical terminal possesses
+an image cache, which is shared by all the frames on that terminal
+(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
+also refreshes it in all other frames on the same terminal.
@defun image-refresh spec &optional frame
-This function refreshes any images having image specifications
+This function refreshes any images with image specifications
@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
-@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.
+@code{nil}, it defaults to the selected frame. If @var{frame} is
+@code{t}, the refresh is applied to all existing frames.
@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 an image cache, removing all the images stored in
+it. If @var{filter} is omitted or @code{nil}, it clears the cache for
+the selected frame. If @var{filter} is a frame, it clears the cache
+for that frame. If @var{filter} is @code{t}, all image caches are
+cleared. Otherwise, @var{filter} is taken to be a file name, and all
+images associated with that file name are removed from all image
+caches.
@end defun
If an image in the image cache has not been displayed for a specified
@item follow-link
@kindex follow-link @r{(button property)}
The follow-link property, defining how a @key{Mouse-1} click behaves
-on this button, @xref{Links and Mouse-1}.
+on this button, @xref{Clickable Text}.
@item button
@kindex button @r{(button property)}
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
If the button has a non-@code{nil} @code{follow-link} property, and
@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
will also activate the @code{push-button} command.
-@xref{Links and Mouse-1}.
+@xref{Clickable Text}.
@deffn Command push-button &optional pos use-mouse-action
Perform the action specified by a button at location @var{pos}.
@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
HCoop / bpt / emacs.git / blobdiff