@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
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
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
+
@node Font Selection
@subsection Font Selection
insert images into text, and also control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
-specifications. Display specifications generally apply in parallel to
-the text they cover.
+specifications. Display specifications in the same @code{display}
+property value generally apply in parallel to the text they cover.
+
+ If several sources (overlays and/or a text property) specify values
+for the @code{display} property, only one of the values takes effect,
+following the rules of @code{get-char-property}. @xref{Examining
+Properties}.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
+
+@menu
+* Replacing Specs:: Display specs that replace the text.
+* Specified Space:: Displaying one space with a specified width.
+* Pixel Specification:: Specifying space width or height in pixels.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+@end menu
+
+@node Replacing Specs
+@subsection Display Specs That Replace The Text
Some kinds of @code{display} specifications specify something to
-display instead of the text that has the property. If a list of
-display specifications includes more than one of this kind, the first
-is effective and the rest are ignored. You cannot interactively move
-point into the middle of the text that is thus replaced.
-
- For these specifications, ``the text that has the property'' means
-all the consecutive characters that have the same Lisp object as their
-@code{display} property; these characters are replaced as a single
-unit. By contrast, characters that have similar but distinct Lisp
-objects as their @code{display} properties are handled separately.
-Here's a function that illustrates this point:
+display instead of the text that has the property. These are called
+@dfn{replacing} display specifications. Emacs does not allow the user
+to interactively move point into the middle of buffer text that is
+replaced in this way.
+
+ If a list of display specifications includes more than one replacing
+display specification, the first overrides the rest. Replacing
+display specifications make most other display specifications
+irrelevant, since those don't apply to the replacement.
+
+ For replacing display specifications, ``the text that has the
+property'' means all the consecutive characters that have the same
+Lisp object as their @code{display} property; these characters are
+replaced as a single unit. By contrast, characters that have similar
+but distinct Lisp objects as their @code{display} properties are
+handled separately. Here's a function that illustrates this point:
@smallexample
(defun foo ()
whether they got this property from a single call to
@code{put-text-property} or from two different calls.
- The rest of this section describes several kinds of
-display specifications and what they mean.
-
-@menu
-* Specified Space:: Displaying one space with a specified width.
-* Pixel Specification:: Specifying space width or height in pixels.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
- up or down on the page; adjusting the width
- of spaces within text.
-* Display Margins:: Displaying text or images to the side of the main text.
-@end menu
-
@node Specified Space
@subsection Specified Spaces
@cindex spaces, specified height or width
@cindex display margins
@cindex margins, display
- A buffer can have blank areas called @dfn{display margins} on the left
-and on the right. Ordinary text never appears in these areas, but you
-can put things into the display margins using the @code{display}
-property.
-
- To put text in the left or right display margin of the window, use a
-display specification of the form @code{(margin right-margin)} or
-@code{(margin left-margin)} on it. To put an image in a display margin,
-use that display specification along with the display specification for
-the image. Unfortunately, there is currently no way to make
-text or images in the margin mouse-sensitive.
-
- If you put such a display specification directly on text in the
-buffer, the specified margin display appears @emph{instead of} that
-buffer text itself. To put something in the margin @emph{in
-association with} certain buffer text without preventing or altering
-the display of that text, put a @code{before-string} property on the
-text and put the display specification on the contents of the
-before-string.
+ A buffer can have blank areas called @dfn{display margins} on the
+left and on the right. Ordinary text never appears in these areas,
+but you can put things into the display margins using the
+@code{display} property. There is currently no way to make text or
+images in the margin mouse-sensitive.
+
+ The way to display something in the margins is to specify it in a
+margin display specification in the @code{display} property of some
+text. This is a replacing display specification, meaning that the
+text you put it on does not get displayed; the margin display appears,
+but that text does not.
+
+ A margin display specification looks like @code{((margin
+right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+Here, @var{spec} is another display specification that says what to
+display in the margin. Typically it is a string of text to display,
+or an image descriptor.
+
+ To display something in the margin @emph{in association with}
+certain buffer text, without altering or preventing the display of
+that text, put a @code{before-string} property on the text and put the
+margin display specification on the contents of the before-string.
Before the display margins can display anything, you must give
them a nonzero width. The usual way to do that is to set these
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
HCoop / bpt / emacs.git / blobdiff