@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
+@cindex line truncation
@cindex continuation lines
@cindex @samp{$} in display
@cindex @samp{\} in display
@node Displaying Messages
@subsection Displaying Messages in the Echo Area
+@cindex display message in echo area
This section describes the functions for explicitly producing echo
area messages. Many other Emacs features display messages there, too.
is @var{atom} or if it is a list with @var{atom} as a member.
@item (@var{atom} . t)
-A character is invisible if its @code{invisible} property value
-is @var{atom} or if it is a list with @var{atom} as a member.
-Moreover, if this character is at the end of a line and is followed
-by a visible newline, it displays an ellipsis.
+A character is invisible if its @code{invisible} property value is
+@var{atom} or if it is a list with @var{atom} as a member. Moreover,
+a sequence of such characters displays as an ellipsis.
@end table
@end table
@end defvar
@node Selective Display
@section Selective Display
-@cindex selective display
+@c @cindex selective display Duplicates selective-display
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
Attributes}.
@item
-A cons cell of the form @code{(foreground-color . @var{color-name})} or
+A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
@code{inhibit-modification-hooks} to @code{t} around doing so, to
avoid confusing the internal mechanism that calls these hooks.
+Text properties also support the @code{modification-hooks} property,
+but the details are somewhat different (@pxref{Special Properties}).
+
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called before and
@code{(point-min)}.
@end defun
- Here's a function which uses @code{next-overlay-change} to search
-for the next character which gets a given property @code{prop} from
-either its overlays or its text properties (@pxref{Property Search}):
+ As an example, here's a simplified (and inefficient) version of the
+primitive function @code{next-single-char-property-change}
+(@pxref{Property Search}). It searches forward from position
+@var{pos} for the next position where the value of a given property
+@code{prop}, as obtained from either overlays or text properties,
+changes.
@smallexample
-(defun find-overlay-prop (prop)
+(defun next-single-char-property-change (position prop)
(save-excursion
- (while (and (not (eobp))
- (not (get-char-property (point) prop)))
- (goto-char (min (next-overlay-change (point))
- (next-single-property-change (point) prop))))
+ (goto-char position)
+ (let ((propval (get-char-property (point) prop)))
+ (while (and (not (eobp))
+ (eq (get-char-property (point) prop) propval))
+ (goto-char (min (next-overlay-change (point))
+ (next-single-property-change (point) prop)))))
(point)))
@end smallexample
- Now you can search for a @code{happy} property like this:
-
-@smallexample
-(find-overlay-prop 'happy)
-@end smallexample
-
@node Width
@section Width
@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
@var{spec}, then uses any customizations that were read from the
init file (@pxref{Init File}) to override that specification.
+When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
+Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
+overrides any customizations of the face. This way, the face reflects
+exactly what the @code{defface} says.
+
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements
have the form @code{(@var{display} @var{atts})}. Each element's
@example
@group
+(defface region
'((((class color) (min-colors 88) (background dark))
:background "blue3")
@end group
For example:
@example
-(read-face-name "Describe face" "= `default' face" t)
+(face-attribute-relative-p :height 2.0)
+ @result{} t
@end example
-
-prompts with @samp{Describe face (default = `default' face): }.
@end defun
@defun merge-face-attribute attribute value1 value2
@cindex automatic face assignment
@cindex faces, automatic choice
-@cindex Font-Lock mode
This hook is used for automatically assigning faces to text in the
-buffer. It is part of the implementation of Font-Lock mode.
+buffer. It is part of the implementation of Jit-Lock mode, used by
+Font-Lock.
@defvar fontification-functions
This variable holds a list of functions that are called by Emacs
@node Fringes
@section Fringes
-@cindex Fringes
+@cindex fringes
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
@node Overlay Arrow
@subsection The Overlay Arrow
-@cindex overlay arrow
+@c @cindex overlay arrow Duplicates variable names
The @dfn{overlay arrow} is useful for directing the user's attention
to a particular line in a buffer. For example, in the modes used for
@node Scroll Bars
@section Scroll Bars
+@cindex scroll bars
Normally the frame parameter @code{vertical-scroll-bars} controls
whether the windows in the frame have vertical scroll bars, and
insert images into text, and also control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
-specifications.
+specifications. Display specifications in the same @code{display}
+property value generally apply in parallel to the text they cover.
+
+ If several sources (overlays and/or a text property) specify values
+for the @code{display} property, only one of the values takes effect,
+following the rules of @code{get-char-property}. @xref{Examining
+Properties}.
+
+ The rest of this section describes several kinds of
+display specifications and what they mean.
+
+@menu
+* Replacing Specs:: Display specs that replace the text.
+* Specified Space:: Displaying one space with a specified width.
+* Pixel Specification:: Specifying space width or height in pixels.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+@end menu
+
+@node Replacing Specs
+@subsection Display Specs That Replace The Text
+
+ Some kinds of @code{display} specifications specify something to
+display instead of the text that has the property. These are called
+@dfn{replacing} display specifications. Emacs does not allow the user
+to interactively move point into the middle of buffer text that is
+replaced in this way.
- Some kinds of @code{display} properties specify something to display
-instead of the text that has the property. In this case, ``the text''
-means all the consecutive characters that have the same Lisp object as
-their @code{display} property; these characters are replaced as a
-single unit. By contrast, characters that have similar but distinct
-Lisp objects as their @code{display} properties are handled
-separately. Here's a function that illustrates this point:
+ If a list of display specifications includes more than one replacing
+display specification, the first overrides the rest. Replacing
+display specifications make most other display specifications
+irrelevant, since those don't apply to the replacement.
+
+ For replacing display specifications, ``the text that has the
+property'' means all the consecutive characters that have the same
+Lisp object as their @code{display} property; these characters are
+replaced as a single unit. By contrast, characters that have similar
+but distinct Lisp objects as their @code{display} properties are
+handled separately. Here's a function that illustrates this point:
@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(let ((string (concat "A")))
- (put-text-property (point) (2+ (point)) 'display string)
+ (put-text-property (point) (+ 2 (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
@end smallexample
whether they got this property from a single call to
@code{put-text-property} or from two different calls.
- The rest of this section describes several kinds of
-display specifications and what they mean.
-
-@menu
-* Specified Space:: Displaying one space with a specified width.
-* Pixel Specification:: Specifying space width or height in pixels.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
- up or down on the page; adjusting the width
- of spaces within text.
-* Display Margins:: Displaying text or images to the side of the main text.
-@end menu
-
@node Specified Space
@subsection Specified Spaces
@cindex spaces, specified height or width
-@cindex specified spaces
@cindex variable-width spaces
To display a space of specified width and/or height, use a display
@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
The supported image formats include XBM, XPM (this requires the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
-@code{libungif} 4.1.0), Postscript, PBM, JPEG (requiring the
+@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
v3.4), and PNG (requiring @code{libpng} 1.0.2).
into Emacs.
@end defvar
-@defun image-type-available-p type
-@findex image-type-available-p
-
+@defun image-type-available-p type
This function returns non-@code{nil} if image type @var{type} is
available, i.e., if images of this type can be loaded and displayed in
Emacs. @var{type} should be one of the types contained in
* XBM Images:: Special features for XBM format.
* XPM Images:: Special features for XPM format.
* GIF Images:: Special features for GIF format.
-* Postscript Images:: Special features for Postscript 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.
* Showing Images:: Convenient ways to display an image once it is defined.
(run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
@end ignore
-@node Postscript Images
-@subsection Postscript Images
-@cindex Postscript images
+@node PostScript Images
+@subsection PostScript Images
+@cindex postscript images
- To use Postscript for an image, specify image type @code{postscript}.
+ To use PostScript for an image, specify image type @code{postscript}.
This works only if you have Ghostscript installed. You must always use
these three properties:
@item :bounding-box @var{box}
The value, @var{box}, must be a list or vector of four integers, which
-specifying the bounding box of the Postscript image, analogous to the
-@samp{BoundingBox} comment found in Postscript files.
+specifying the bounding box of the PostScript image, analogous to the
+@samp{BoundingBox} comment found in PostScript files.
@example
%%BoundingBox: 22 171 567 738
@end example
@end table
- Displaying Postscript images from Lisp data is not currently
+ 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.
This function returns a suitable search path for images used by the
Lisp package @var{library}.
-The function searches for @var{image} first in @code{image-load-path}
-(excluding @file{@code{data-directory}/images}) and then in
+The function searches for @var{image} first using @code{image-load-path},
+excluding @file{@code{data-directory}/images}, and then in
@code{load-path}, followed by a path suitable for @var{library}, which
includes @file{../../etc/images} and @file{../etc/images} relative to
the library file itself, and finally in
@node Image Cache
@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.
+
+ 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}.
+
+@defun image-refresh spec &optional frame
+This function refreshes any images having 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.
+@end defun
- Emacs stores images in an image cache when it displays them, so it can
-display them again more efficiently. It removes an image from the cache
-when it hasn't been displayed for a specified period of time.
+@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.
+@end defun
-When an image is looked up in the cache, its specification is compared
-with cached image specifications using @code{equal}. This means that
-all images with equal specifications share the same image in the cache.
+If an image in the image cache has not been displayed for a specified
+period of time, Emacs removes it from the cache and frees the
+associated memory.
@defvar image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the
debugging.
@end defvar
-@defun clear-image-cache &optional frame
-This function clears the image cache. If @var{frame} is non-@code{nil},
-only the cache for that frame is cleared. Otherwise all frames' caches
-are cleared.
-@end defun
-
@node Buttons
@section Buttons
-@cindex buttons
@cindex buttons in buffers
@cindex clickable buttons in buffers
@end deffn
@defun next-button pos &optional count-current
-Return the next button after position @var{pos} in the current buffer.
-If @var{count-current} is non-@code{nil}, count any button at
-@var{pos} in the search, instead of starting at the next button.
-@end defun
-
-@defun previous-button pos &optional count-current
-Return the @var{n}th button before position @var{pos} in the current
-buffer. If @var{count-current} is non-@code{nil}, count any button at
-@var{pos} in the search, instead of starting at the next button.
+@defunx previous-button pos &optional count-current
+Return the next button after (for @code{next-button} or before (for
+@code{previous-button}) position @var{pos} in the current buffer. If
+@var{count-current} is non-@code{nil}, count any button at @var{pos}
+in the search, instead of starting at the next button.
@end defun
@node Abstract Display
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
-@cindex blinking
+@cindex blinking parentheses
@cindex balancing parentheses
-@cindex close parenthesis
This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.
@cindex glyph
A @dfn{glyph} is a generalization of a character; it stands for an
-image that takes up a single character position on the screen. Glyphs
-are represented in Lisp as integers, just as characters are. Normally
+image that takes up a single character position on the screen. Normally
glyphs come from vectors in the display table (@pxref{Display Tables}).
- A glyph code can be @dfn{simple} or it can be defined by the
-@dfn{glyph table}. A simple glyph code is just a way of specifying a
-character and a face to output it in. When a glyph code is simple,
-the code, mod 524288, is the character to output, and the code divided
-by 524288 specifies the face number (@pxref{Face Functions}) to use
-while outputting it. (524288 is
-@ifnottex
-2**19.)
-@end ifnottex
-@tex
-$2^{19}$.)
-@end tex
-@xref{Faces}.
+ A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
+can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
+simple glyph code is just a way of specifying a character and a face
+to output it in. @xref{Faces}.
+
+ The following functions are used to manipulate simple glyph codes:
+
+@defun make-glyph-code char &optional face
+This function returns a simple glyph code representing char @var{char}
+with face @var{face}.
+@end defun
+
+@defun glyph-char glyph
+This function returns the character of simple glyph code @var{glyph}.
+@end defun
+
+@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).
+@end defun
On character terminals, you can set up a @dfn{glyph table} to define
-the meaning of glyph codes.
+the meaning of glyph codes (represented as small integers).
@defvar glyph-table
The value of this variable is the current glyph table. It should be
Send the characters in @var{string} to the terminal to output
this glyph code.
-@item @var{integer}
-Define this glyph code as an alias for glyph code @var{integer}. You
-can use such an alias to define a small-numbered glyph code which
-specifies a face.
+@item @var{code}
+Define this glyph code as an alias for glyph code @var{code} created
+by @code{make-glyph-code}. You can use such an alias to define a
+small-numbered glyph code which specifies a character with a face.
@item @code{nil}
This glyph code is simple.
@node Beeping
@section Beeping
-@cindex beeping
+@c @cindex beeping "beep" is adjacent
@cindex bell
This section describes how to make Emacs ring the bell (or blink the