@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 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.
-
-@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
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
@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.
+or symbol. It returns @code{nil} otherwise.
@end defun
Each face name is meaningful for all frames, and by default it has the
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},
@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
When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority. @xref{Overlays}.
+@defvar face-remapping-alist
+ This variable is used for buffer-local or global changes in the
+appearance of a face, for instance making the @code{default} face a
+variable-pitch face in a particular buffer.
+
+ Its value should be 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 global definition. @var{remapping...} may be any face
+specification suitable for a @code{face} text property, usually a face
+name, but also perhaps a property list of face attribute/value pairs.
+@xref{Special Properties}.
+
+ To affect display only in a single buffer,
+@code{face-remapping-alist} should be made buffer-local.
+
+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.
+
+@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
+
+ 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
+(set (make-local-variable 'face-remapping-alist)
+ '((default variable-pitch :height 2.0)))
+@end example
+
+@end defvar
+
+@noindent
+The following functions implement a somewhat 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.
+
+These functions use entries in @code{face-remapping-alist} which have
+the general form:
+
+@example
+ (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
+@end example
+
+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.
+
+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.
+
+@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.
+
+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.
+
+
+@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.
+
+It returns a ``cookie'' which can be used to later delete the remapping with
+@code{face-remap-remove-relative}.
+
+@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
+
+@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 Font Selection
@subsection Font Selection
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
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{from} and @var{to} are character codepoints. In that case, use
@var{fontname} for all characters in the range @var{from} and @var{to}
(inclusive).
* 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
@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
displayed, Emacs will load the image again.
@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
Emacs is displaying using MS-DOS.
@item w32
Emacs is displaying using Windows.
-@item mac
-Emacs is displaying using a Macintosh.
@item nil
Emacs is using a character-based terminal.
@end table