@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, 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, Processes, Top
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Warnings:: Displaying warning messages for the user.
+* Progress:: Informing user about progress of a long operation.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
+* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
+* Fringe Bitmaps:: Displaying bitmaps in the window fringes.
+* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
* Scroll Bars:: Controlling vertical scroll bars.
+* Pointer Shape:: Controlling the mouse pointer shape.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
@end defvar
@defvar warning-prefix-function
-If non-@code{nil}, te value is a function to generate prefix text for
+If non-@code{nil}, the value is a function to generate prefix text for
warnings. Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
current, and the function can insert text in it. That text becomes
The function is called with two arguments, the severity level and its
entry in @code{warning-levels}. It should return a list to use as the
entry (this value need not be an actual member of
-@code{warning-levels}). By constructing this value, the function to
+@code{warning-levels}). By constructing this value, the function can
change the severity of the warning, or specify different handling for
a given severity level.
Programs can bind this variable to @code{t} to say that the next
warning should begin a series. When several warnings form a series,
that means to leave point on the first warning of the series, rather
-than keep move it for each warning so that it appears on the last one.
+than keep moving it for each warning so that it appears on the last one.
The series ends when the local binding is unbound and
@code{warning-series} becomes @code{nil} again.
that warning is not logged.
@end defopt
+@node Progress
+@section Reporting Operation Progress
+@cindex progress reporting
+
+When an operation can take a while to finish, you should inform the
+user about the progress it makes. This way the user can estimate
+remaining time and clearly see that Emacs is busy working, not hung.
+
+Functions listed in this section provide simple and efficient way of
+reporting operation progress. Here is a working example that does
+nothing useful:
+
+@example
+(let ((progress-reporter
+ (make-progress-reporter "Collecting some mana for Emacs..."
+ 0 500)))
+ (dotimes (k 500)
+ (sit-for 0.01)
+ (progress-reporter-update progress-reporter k))
+ (progress-reporter-done progress-reporter))
+@end example
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates a progress reporter---the object you will use as
+an argument for all other functions listed here. The idea is to
+precompute as much data as possible to make progress reporting very
+fast.
+
+The @var{message} will be displayed in the echo area, followed by
+progress percentage. @var{message} is treated as a simple string. If
+you need it to depend on a filename, for instance, use @code{format}
+before calling this function.
+
+@var{min-value} and @var{max-value} arguments stand for starting and
+final states of your operation. For instance, if you scan a buffer,
+they should be the results of @code{point-min} and @code{point-max}
+correspondingly. It is required that @var{max-value} is greater than
+@var{min-value}. If you create progress reporter when some part of
+the operation has already been completed, then specify
+@var{current-value} argument. But normally you should omit it or set
+it to @code{nil}---it will default to @var{min-value} then.
+
+Remaining arguments control the rate of echo area updates. Progress
+reporter will wait for at least @var{min-change} more percents of the
+operation to be completed before printing next message.
+@var{min-time} specifies the minimum time in seconds to pass between
+successive prints. It can be fractional. Depending on Emacs and
+system capabilities, progress reporter may or may not respect this
+last argument or do it with varying precision. Default value for
+@var{min-change} is 1 (one percent), for @var{min-time}---0.2
+(seconds.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation. It print the message of @var{reporter} followed by
+progress percentage determined by @var{value}. If percentage is zero,
+then it is not printed at all.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}. @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}. For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation. It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}. Optional @var{new-message} allows
+you to change the message of the @var{reporter}. Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished. It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
+@defmac dotimes-with-progress-reporter (var count [result]) message body...
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above. It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+ (k 500)
+ "Collecting some mana for Emacs..."
+ (sit-for 0.01))
+@end example
+@end defmac
+
@node Invisible Text
@section Invisible Text
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
-actually make a character invisible.
+actually make a character invisible. Setting this variable makes it
+buffer-local.
@table @asis
@item @code{t}
@end defun
@defun remove-from-invisibility-spec element
-This removeds the element @var{element} from
+This removes the element @var{element} from
@code{buffer-invisibility-spec}. This does nothing if @var{element}
is not in the list.
@end defun
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
+An overlays 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,
+you can specify whether text inserted at the beginning should be
+inside the overlay or outside, and likewise for the end of the overlay.
+
@menu
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
@xref{Display Property}.
@item help-echo
-@kindex help-echo @r{(text property)}
+@kindex help-echo @r{(overlay property)}
If an overlay has a @code{help-echo} property, then when you move the
mouse onto the text in the overlay, Emacs displays a help string in the
echo area, or in the tooltip window. For details see @ref{Text
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
-if it becomes empty (i.e., if its length becomes zero). However,
-if the overlay is @emph{already} empty, @code{evaporate} does not
-delete it.
+if it becomes empty (i.e., if its length becomes zero). If you give
+an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
+it immediately.
@item local-map
@cindex keymap of character (and overlays)
The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}.
+overlay, respectively. @xref{Marker Insertion Types}. If
+@var{front-advance} is non-@code{nil}, text inserted at the beginning
+of the overlay is excluded from the overlay. If @var{read-advance} is
+non-@code{nil}, text inserted at the beginning of the overlay is
+included in the overlay.
@end defun
@defun overlay-start overlay
@end example
@end defun
+@node Line Height
+@section Line Height
+@cindex line height
+
+ The total height of each display line consists of the height of the
+contents of the line, and additional vertical line spacing below the
+display row.
+
+ The height of the line contents is normally determined from the
+maximum height of any character or image on that display line,
+including the final newline if there is one. (A line that is
+continued doesn't include a final newline.) In the most common case,
+the line height equals the height of the default frame font.
+
+ There are several ways to explicitly control or change the line
+height, either by specifying an absolute height for the display line,
+or by adding additional vertical space below one or all lines.
+
+@kindex line-height @r{(text property)}
+ A newline can have a @code{line-height} text or overlay property
+that controls the total height of the display line ending in that
+newline.
+
+ If the property value is a list @code{(@var{height} @var{total})},
+then @var{height} is used as the actual property value for the
+@code{line-height}, and @var{total} specifies the total displayed
+height of the line, so the line spacing added below the line equals
+the @var{total} height minus the actual line height. In this case,
+the other ways to specify the line spacing are ignored.
+
+ If the property value is @code{t}, the displayed height of the
+line is exactly what its contents demand; no line-spacing is added.
+This case is useful for tiling small images or image slices without
+adding blank areas between the images.
+
+ If the property value is not @code{t}, it is a height spec. A height
+spec stands for a numeric height value; this heigh spec specifies the
+actual line height, @var{line-height}. There are several ways to
+write a height spec; here's how each of them translates into a numeric
+height:
+
+@table @code
+@item @var{integer}
+If the height spec is a positive integer, the height value is that integer.
+@item @var{float}
+If the height spec is a float, @var{float}, the numeric height value
+is @var{float} times the frame's default line height.
+@item (@var{face} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of face @var{face}. @var{ratio} can
+be any type of number, or @code{nil} which means a ratio of 1.
+If @var{face} is @code{t}, it refers to the current face.
+@item (@code{nil} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of the contents of the line.
+@end table
+
+ Thus, any valid non-@code{t} property value specifies a height in pixels,
+@var{line-height}, one way or another. If the line contents' height
+is less than @var{line-height}, Emacs adds extra vertical space above
+the line to achieve the total height @var{line-height}. Otherwise,
+@var{line-height} has no effect.
+
+ If you don't specify the @code{line-height} propery, the line's
+height consists of the contents' height plus the line spacing.
+There are several ways to specify the line spacing for different
+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, @xref{Window Frame 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 window systems. 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 window systems. 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
+property that controls the height of the display line ending with that
+newline. The property value overrides the default frame line spacing
+and the buffer local @code{line-spacing} variable.
+
+ One way or another, these mechanisms specify a Lisp value for the
+spacing of each line. The value is a height spec, and it translates
+into a Lisp value as described above. However, in this case the
+numeric height value specifies the line spacing, rather than the line
+height.
+
@node Faces
@section Faces
@cindex faces
* 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.
-* Merging Faces:: How Emacs combines the faces specified for a character.
+* Displaying Faces:: How Emacs combines the faces specified for a character.
* Font Selection:: Finding the best available font for a face.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
@item fringe
@kindex fringe @r{(face name)}
-This face controls the colors of window fringes, the thin areas on
+This face controls the default colors of window fringes, the thin areas on
either side that are used to display continuation and truncation glyphs.
@item minibuffer-prompt
@item background
The kind of background---either @code{light} or @code{dark}.
+@item min-colors
+An integer that represents the minimum number of colors the frame should
+support, it is compared with the result of @code{display-color-cells}.
+
@item supports
Whether or not the frame can display the face attributes given in
@var{value}@dots{} (@pxref{Face Attributes}). See the documentation
@example
@group
-(defface region
- `((((type tty) (class color))
- (:background "blue" :foreground "white"))
+ '((((class color) (min-colors 88) (background dark))
+ :background "blue3")
@end group
+ (((class color) (min-colors 88) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 16) (background dark))
+ :background "blue3")
+ (((class color) (min-colors 16) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 8))
+ :background "blue" :foreground "white")
(((type tty) (class mono))
- (:inverse-video t))
- (((class color) (background dark))
- (:background "blue"))
- (((class color) (background light))
- (:background "lightblue"))
- (t (:background "gray")))
+ :inverse-video t)
+ (t :background "gray"))
@group
"Basic face for highlighting the region."
:group 'basic-faces)
attributes}. This table lists all the face attributes, and what they
mean. Note that in general, more than one face can be specified for a
given piece of text; when that happens, the attributes of all the faces
-are merged to specify how to display the text. @xref{Merging Faces}.
+are merged to specify how to display the text. @xref{Displaying Faces}.
In Emacs 21, any attribute in a face can have the value
@code{unspecified}. This means the face doesn't specify that attribute.
the terminal supports the feature.
@item :foreground
-Foreground color, a string.
+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.)
@item :background
-Background color, a string.
+Background color, a string, like the foreground color.
@item :inverse-video
Whether or not characters should be displayed in inverse video. The
@tindex face-attribute-relative-p
@defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as a
+This function returns non-@code{nil} if @var{value}, when used as
the value of the face attribute @var{attribute}, is relative (that is,
if it modifies an underlying or inherited value of @var{attribute}).
@end defun
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
-If @var{inherit} is nil, only a color directly defined by the face is
-returned. If @var{inherit} is non-nil, any faces specified by its
+If @var{inherit} is @code{nil}, only a color directly defined by the face is
+returned. If @var{inherit} is non-@code{nil}, any faces specified by its
@code{:inherit} attribute are considered as well, and if @var{inherit}
is a face or a list of faces, then they are also considered, until a
specified color is found. To ensure that the return value is always
This function returns the @code{:inverse-video} attribute of face @var{face}.
@end defun
-@node Merging Faces
-@subsection Merging Faces for Display
+@node Displaying Faces
+@subsection Displaying Faces
Here are the ways to specify which faces to use for display of text:
@end defun
@defun face-differs-from-default-p face &optional frame
-This returns @code{t} if the face @var{face} displays differently from
-the default face. A face is considered to be ``the same'' as the
-default face if each attribute is either the same as that of the default
-face, or unspecified (meaning to inherit from the default).
+This returns non-@code{nil} if the face @var{face} displays
+differently from the default face.
@end defun
@node Auto Faces
use the font name @var{fontname} for the character @var{character}.
If @var{name} is @code{nil}, this function modifies the default
-fontset of which short name is @samp{fontset-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
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
-continuation, and horizontal scrolling, the overlay arrow. The
+continuation, horizontal scrolling, and the overlay arrow. The
fringes normally appear between the display margins and the window
text, but you can put them outside the display margins for a specific
buffer by setting @code{fringes-outside-margins} buffer-locally to a
@defvar fringes-outside-margins
If the value is non-@code{nil}, the frames appear outside
-the display margins.
+the display margins.
@end defvar
@defvar left-fringe-width
The values of these variables take effect when you display the
buffer in a window. If you change them while the buffer is visible,
-you can call @code{set-window-buffer} to display it in a window again.
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
@defun set-window-fringes window left &optional right outside-margins
-This function sets the fringe widthes of window @var{window}.
+This function sets the fringe widths of window @var{window}.
If @var{window} is @code{nil}, the selected window is used.
The argument @var{left} specifies the width in pixels of the left
@var{right-width} @var{frames-outside-margins})}.
@end defun
+@defvar 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
+
+@node Fringe Bitmaps
+@section Fringe Bitmaps
+@cindex fringe bitmaps
+@cindex bitmaps, fringe
+
+ The @dfn{fringe bitmaps} are tiny icons Emacs displays in the window
+fringe (on a graphic display) to indicate truncated or continued
+lines, buffer boundaries, overlay arrow, etc. The fringe bitmaps are
+shared by all frames and windows. You can redefine the built-in
+fringe bitmaps, and you can define new fringe bitmaps.
+
+ The way to display a bitmap in the left or right fringes for a given
+line in a window is by specifying the @code{display} property for one
+of the characters that appears in it. Use a display specification of
+the form @code{(left-fringe @var{bitmap} [@var{face}])} or
+@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
+Property}). Here, @var{bitmap} is a symbol identifying the bitmap
+you want, and @var{face} (which is optional) is the name of the face
+whose colors should be used for displaying the bitmap.
+
+ These are the symbols identify the standard fringe bitmaps.
+Evaluate @code{(require 'fringe)} to define them. Fringe bitmap
+symbols have their own name space.
+
+@table @asis
+@item Truncation and continuation line bitmaps:
+@code{left-truncation}, @code{right-truncation},
+@code{continued-line}, @code{continuation-line}.
+
+@item Buffer indication bitmaps:
+@code{up-arrow}, @code{down-arrow},
+@code{top-left-angle}, @code{top-right-angle},
+@code{bottom-left-angle}, @code{bottom-right-angle},
+@code{left-bracket}, @code{right-bracket}.
+
+@item Empty line indication bitmap:
+@code{empty-line}.
+
+@item Overlay arrow bitmap:
+@code{overlay-arrow}.
+
+@item Bitmaps for displaying the cursor in right fringe:
+@code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
+@code{bar-cursor}, @code{hbar-cursor}.
+@end table
+
+@defun fringe-bitmaps-at-pos &optional pos window
+This function returns the fringe bitmaps of the display line
+containing position @var{pos} in window @var{window}. The return
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
+is the symbol for the fringe bitmap in the left fringe (or @code{nil}
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
+
+The value is @code{nil} if @var{pos} is not visible in @var{window}.
+If @var{window} is @code{nil}, that stands for the selected window.
+If @var{pos} is @code{nil}, that stands for the value of point in
+@var{window}.
+@end defun
+
+@node Customizing Bitmaps
+@section Customizing Fringe Bitmaps
+
+@defun define-fringe-bitmap bitmap bits &optional height width align
+This function defines the symbol @var{bitmap} as a new fringe bitmap,
+or replaces an existing bitmap with that name.
+
+The argument @var{bits} specifies the image to use. It should be
+either a string or a vector of integers, where each element (an
+integer) corresponds to one row of the bitmap. Each bit of an integer
+corresponds to one pixel of the bitmap, where the low bit corresponds
+to the rightmost pixel of the bitmap.
+
+The height is normally the length of @var{bits}. However, you
+can specify a different height with non-@code{nil} @var{height}. The width
+is normally 8, but you can specify a different width with non-@code{nil}
+@var{width}. The width must be an integer between 1 and 16.
+
+The argument @var{align} specifies the positioning of the bitmap
+relative to the range of rows where it is used; the default is to
+center the bitmap. The allowed values are @code{top}, @code{center},
+or @code{bottom}.
+
+The @var{align} argument may also be a list @code{(@var{align}
+@var{periodic})} where @var{align} is interpreted as described above.
+If @var{periodic} is non-@code{nil}, it specifies that the rows in
+@code{bits} should be repeated enough times to reach the specified
+height.
+
+The return value on success is an integer identifying the new bitmap.
+You should save that integer in a variable so it can be used to select
+this bitmap.
+
+This function signals an error if there are no more free bitmap slots.
+@end defun
+
+@defun destroy-fringe-bitmap bitmap
+This function destroy the fringe bitmap identified by @var{bitmap}.
+If @var{bitmap} identifies a standard fringe bitmap, it actually
+restores the standard definition of that bitmap, instead of
+eliminating it entirely.
+@end defun
+
+@defun set-fringe-bitmap-face bitmap &optional face
+This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
+If @var{face} is @code{nil}, it selects the @code{fringe} face. The
+bitmap's face controls the color to draw it in.
+
+The face you use here should be derived from @code{fringe}, and should
+specify only the foreground color.
+@end defun
+
@node Scroll Bars
@section Scroll Bars
@code{scroll-bar-width} specifies how wide they are (@code{nil}
meaning the default). @xref{Window Frame Parameters}.
-You can also control this for individual windows. Call the function
+@vindex vertical-scroll-bar
+ You can enable or disable scroll bars for a particular buffer,
+by setting the variable @code{vertical-scroll-bar}. This variable
+automatically becomes buffer-local when set. The possible values are
+@code{left}, @code{right}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+
+ You can also control this for individual windows. Call the function
@code{set-window-scroll-bars} to specify what to do for a specific window:
@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-Set width and type of scroll bars of window @var{window}.
-If @var{window} is @code{nil}, the selected window is used.
+This function sets the width and type of scroll bars for window
+@var{window}.
+
@var{width} specifies the scroll bar width in pixels (@code{nil} means
-use whatever is specified for width for the frame).
-@var{vertical-type} specifies whether to have a vertical scroll bar
-and, if so, where. The possible values are @code{left}, @code{right}
-and @code{nil}, just like the values of the
-@code{vertical-scroll-bars} frame parameter.
+use the width specified for the frame). @var{vertical-type} specifies
+whether to have a vertical scroll bar and, if so, where. The possible
+values are @code{left}, @code{right} and @code{nil}, just like the
+values of the @code{vertical-scroll-bars} frame parameter.
The argument @var{horizontal-type} is meant to specify whether and
where to have horizontal scroll bars, but since they are not
-implemented, it has no effect.
+implemented, it has no effect. If @var{window} is @code{nil}, the
+selected window is used.
@end defun
@defun window-scroll-bars &optional window
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
+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
+
+@defvar scroll-bar-width
+This variable, always local in all buffers, specifies the width of the
+buffer's scroll bars, measured in pixels. A value of @code{nil} means
+to use the value specified by the frame.
+@end defvar
+
+@node Pointer Shape
+@section Pointer Shape
+
+ Normally, the mouse pointer has the @code{text} shape over text and
+the @code{arrow} shape over window areas which do not correspond to
+any buffer text. You can specify the mouse pointer shape over text or
+images via the @code{pointer} text property, and for images with the
+@code{:pointer} and @code{:map} image properties.
+
+ The available pointer shapes are: @code{text} (or @code{nil}),
+@code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
+@code{modeline}, and @code{hourglass}.
+
+@defvar void-text-area-pointer
+@tindex void-text-area-pointer
+This variable specifies the mouse pointer shape in void text areas,
+i.e. the areas after the end of a line or below the last line in the
+buffer. The default is to use the @code{arrow} (non-text) pointer.
+@end defvar
+
@node Display Property
@section The @code{display} Property
@cindex display specification
@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.
@table @code
@item :width @var{width}
-Specifies that the space width should be @var{width} times the normal
-character width. @var{width} can be an integer or floating point
-number.
+If @var{width} is an integer or floating point number, it specifies
+that the space width should be @var{width} times the normal character
+width. @var{width} can also be a @dfn{pixel width} specification
+(@pxref{Pixel Specification}).
@item :relative-width @var{factor}
Specifies that the width of the stretch should be computed from the
character, multiplied by @var{factor}.
@item :align-to @var{hpos}
-Specifies that the space should be wide enough to reach @var{hpos}. The
-value @var{hpos} is measured in units of the normal character width. It
-may be an integer or a floating point number.
+Specifies that the space should be wide enough to reach @var{hpos}.
+If @var{hpos} is a number, it is measured in units of the normal
+character width. @var{hpos} can also be a @dfn{pixel width}
+specification (@pxref{Pixel Specification}).
@end table
You should use one and only one of the above properties. You can
-also specify the height of the space, with other properties:
+also specify the height of the space, with these properties:
@table @code
@item :height @var{height}
-Specifies the height of the space, as @var{height},
-measured in terms of the normal line height.
+Specifies the height of the space.
+If @var{height} is an integer or floating point number, it specifies
+that the space height should be @var{height} times the normal character
+height. The @var{height} may also be a @dfn{pixel height} specification
+(@pxref{Pixel Specification}).
@item :relative-height @var{factor}
Specifies the height of the space, multiplying the ordinary height
of the text having this display specification by @var{factor}.
@item :ascent @var{ascent}
-Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space---that is, the part above the
-baseline. The value of @var{ascent} must be a non-negative number no
-greater than 100.
+If the value of @var{ascent} is a non-negative number no greater than
+100, it specifies that @var{ascent} percent of the height of the space
+should be considered as the ascent of the space---that is, the part
+above the baseline. The ascent may also be specified in pixel units
+with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
+
@end table
Don't use both @code{:height} and @code{:relative-height} together.
+ The @code{:height} and @code{:align-to} properties are supported on
+non-graphic terminals, but the other space properties in this section
+are not.
+
+@node Pixel Specification
+@subsection Pixel Specification for Spaces
+@cindex spaces, pixel specification
+
+ The value of the @code{:width}, @code{:align-to}, @code{:height},
+and @code{:ascent} properties can be a special kind of expression that
+is evaluated during redisplay. The result of the evaluation is used
+as an absolute number of pixels.
+
+ The following expressions are supported:
+
+@example
+@group
+ @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
+ @var{num} ::= @var{integer} | @var{float} | @var{symbol}
+ @var{unit} ::= in | mm | cm | width | height
+ @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
+ | scroll-bar | text
+ @var{pos} ::= left | center | right
+ @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
+ @var{op} ::= + | -
+@end group
+@end example
+
+ The form @var{num} specifies a fraction of the default frame font
+height or width. The form @code{(@var{num})} specifies an absolute
+number of pixels. If @var{num} is a symbol, @var{symbol}, its
+buffer-local variable binding is used.
+
+ The @code{in}, @code{mm}, and @code{cm} units specify the number of
+pixels per inch, millimeter, and centimeter, respectively. The
+@code{width} and @code{height} units correspond to the default width
+and height of the current face. An image specification @code{image}
+corresponds to the width or height of the image.
+
+ The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
+@code{right-margin}, @code{scroll-bar}, and @code{text} elements
+specify to the width of the corresponding area of the window.
+
+ The @code{left}, @code{center}, and @code{right} positions can be
+used with @code{:align-to} to specify a position relative to the left
+edge, center, or right edge of the text area.
+
+ Any of the above window elements (except @code{text}) can also be
+used with @code{:align-to} to specify that the position is relative to
+the left edge of the given area. Once the base offset for a relative
+position has been set (by the first occurrence of one of these
+symbols), further occurrences of these symbols are interpreted as the
+width of the specified area. For example, to align to the center of
+the left-margin, use
+
+@example
+:align-to (+ left-margin (0.5 . left-margin))
+@end example
+
+ If no specific base offset is set for alignment, it is always relative
+to the left edge of the text area. For example, @samp{:align-to 0} in a
+header-line aligns with the first text column in the text area.
+
+ A value of the form @code{(@var{num} . @var{expr})} stands
+multiplying the values of @var{num} and @var{expr}. For example,
+@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
+@var{image})} specifies half the width (or height) of the specified image.
+
+ The form @code{(+ @var{expr} ...)} adds up the value of the
+expressions. The form @code{(- @var{expr} ...)} negates or subtracts
+the value of the expressions.
+
@node Other Display Specs
@subsection Other Display Specifications
+ Here are the other sorts of display specifications that you can use
+in the @code{display} text property.
+
@table @code
@item (image . @var{image-props})
This is in fact an image descriptor (@pxref{Images}). When used as a
display specification, it means to display the image instead of the text
that has the display specification.
+@item (slice @var{x} @var{y} @var{width} @var{height})
+This specification together with @code{image} specifies a @dfn{slice}
+(a partial area) of the image to display. The elements @var{y} and
+@var{x} specify the top left corner of the slice, within the image;
+@var{width} and @var{height} specify the width and height of the
+slice. Integer values are numbers of pixels. A floating point number
+in the range 0.0--1.0 stands for that fraction of the width or height
+of the entire image.
+
@item ((margin nil) @var{string})
@itemx @var{string}
A display specification of this form means to display @var{string}
@code{display} property, this feature is available starting in Emacs 21.
Emacs can display a number of different image formats; some of them
-are supported only if particular support libraries are installed on your
-machine. The supported image formats include XBM, XPM (needing the
+are supported only if particular support libraries are installed on
+your machine. In some environments, Emacs allows loading image
+libraries on demand; if so, the variable @code{image-library-alist}
+can be used to modify the set of known names for these dynamic
+libraries (though it is not possible to add new image formats).
+
+ The supported image formats include XBM, XPM (needing the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
@defvar image-types
This variable contains a list of those image type symbols that are
-supported in the current configuration.
+potentially supported in the current configuration.
+@emph{Potentially} here means that Emacs knows about the image types,
+not necessarily that they can be loaded (they could depend on
+unavailable dynamic libraries, for example).
+
+To know which image types are really available, use
+@code{image-type-available-p}.
@end defvar
+@defvar image-library-alist
+This in an alist of image types vs external libraries needed to
+display them.
+
+Each element is a list @code{(@var{image-type} @var{library}...)},
+where the car is a supported image format from @code{image-types}, and
+the rest are strings giving alternate filenames for the corresponding
+external libraries to load.
+
+Emacs tries to load the libraries in the order they appear on the
+list; if none is loaded, the running session of Emacs won't support
+the image type. @code{pbm} and @code{xbm} don't need to be listed;
+they're always supported.
+
+This variable is ignored if the image libraries are statically linked
+into Emacs.
+@end defvar
+
+@defun image-type-available-p type
+@findex image-type-available-p
+
+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
+@code{image-types}.
+
+For image types whose support libraries are statically linked, this
+function always returns @code{t}; for other image types, it returns
+@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
+@end defun
+
@menu
* Image Descriptors:: How to specify an image for use in @code{:display}.
* XBM Images:: Special features for XBM format.
If @var{mask} is @code{nil}, remove a mask from the image, if it has
one. Images in some formats include a mask which can be removed by
specifying @code{:mask nil}.
+
+@item :pointer @var{shape}
+This specifies the pointer shape when the mouse pointer is over this
+image. @xref{Pointer Shape}, for available pointer shapes.
+
+@item :map @var{map}
+This associates an image map of @dfn{hot spots} with this image.
+
+An image map is an alist where each element has the format
+@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
+as either a rectangle, a circle, or a polygon.
+
+A rectangle is a cons
+@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
+which specifies the pixel coordinates of the upper left and bottom right
+corners of the rectangle area.
+
+A circle is a cons
+@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
+which specifies the center and the radius of the circle; @var{r} may
+be a float or integer.
+
+A polygon is a cons
+@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
+where each pair in the vector describes one corner in the polygon.
+
+When the mouse pointer is above a hot-spot area of an image, the
+@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
+property it defines a tool-tip for the hot-spot, and if it contains
+a @code{pointer} property, it defines the shape of the mouse cursor when
+it is over the hot-spot.
+@xref{Pointer Shape}, for available pointer shapes.
+
+When you click the mouse when the mouse pointer is over a hot-spot, an
+event is composed by combining the @var{id} of the hot-spot with the
+mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
+@var{id} is @code{area4}.
@end table
@defun image-mask-p spec &optional frame
For GIF images, specify image type @code{gif}. Because of the patents
in the US covering the LZW algorithm, the continued use of GIF format is
a problem for the whole Internet; to end this problem, it is a good idea
-for everyone, even outside the US, to stop using GIFS right away
+for everyone, even outside the US, to stop using GIFs right away
(@uref{http://www.burnallgifs.org/}). But if you still want to use
them, Emacs can display them.
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
-@defun create-image file &optional type &rest props
+@defun create-image file-or-data &optional type data-p &rest props
@tindex create-image
This function creates and returns an image descriptor which uses the
-data in @var{file}.
+data in @var{file-or-data}. @var{file-or-data} can be a file name or
+a string containing the image data; @var{data-p} should be @code{nil}
+for the former case, non-@code{nil} for the latter case.
The optional argument @var{type} is a symbol specifying the image type.
If @var{type} is omitted or @code{nil}, @code{create-image} tries to
properties---for example,
@example
-(create-image "foo.xpm" 'xpm :heuristic-mask t)
+(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
The function returns @code{nil} if images of this type are not
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image &optional string area
+@defun insert-image image &optional string area slice
This function inserts @var{image} in the current buffer at point. The
value @var{image} should be an image descriptor; it could be a value
returned by @code{create-image}, or the value of a symbol defined with
@code{nil} or omitted, the image is displayed at point within the
buffer's text.
+The argument @var{slice} specifies a slice of the image to insert. If
+@var{slice} is @code{nil} or omitted the whole image is inserted.
+Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
+@var{height})} which specifies the @var{x} and @var{y} positions and
+@var{width} and @var{height} of the image area to insert. Integer
+values are in units of pixels. A floating point number in the range
+0.0--1.0 stands for that fraction of the width or height of the entire
+image.
+
Internally, this function inserts @var{string} in the buffer, and gives
it a @code{display} property which specifies @var{image}. @xref{Display
Property}.
@end defun
+@defun insert-sliced-image image &optional string area rows cols
+This function inserts @var{image} in the current buffer at point, like
+@code{insert-image}, but splits the image into @var{rows}x@var{cols}
+equally sized slices.
+@end defun
+
@defun put-image image pos &optional string area
This function puts image @var{image} in front of @var{pos} in the
current buffer. The argument @var{pos} should be an integer or a
etc. Emacs uses buttons for the hyper-links in help text and the like.
A button is essentially a set of properties attached (via text
-properties or overlays) to a region of text in an emacs buffer, which
+properties or overlays) to a region of text in an Emacs buffer, which
are called its button properties. @xref{Button Properties}.
One of the these properties (@code{action}) is a function, which will
The invoked function may then examine the button and use its other
properties as desired.
-In some ways the emacs button package duplicates functionality offered
+In some ways the Emacs button package duplicates functionality offered
by the widget package (@pxref{Top, , Introduction, widget, The Emacs
Widget Library}), but the button package has the advantage that it is
much faster, much smaller, and much simpler to use (for elisp
@menu
* Button Properties:: Button properties with special meanings.
* Button Types:: Defining common properties for classes of buttons.
-* Making Buttons:: Adding buttons to emacs buffers.
+* Making Buttons:: Adding buttons to Emacs buffers.
* Manipulating Buttons:: Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
-* Manipulating Button Types::
+* Manipulating Button Types::
@end menu
@node Button Properties
@item face
@kindex face @r{(button property)}
-This is an emacs face controlling how buttons of this type are
+This is an Emacs face controlling how buttons of this type are
displayed; by default this is the @code{button} face.
@item mouse-face
@kindex mouse-face @r{(button property)}
This is an additional face which controls appearance during
mouse-overs (merged with the usual button face); by default this is
-the usual emacs @code{highlight} face.
+the usual Emacs @code{highlight} face.
@item keymap
@kindex keymap @r{(button property)}
@item help-echo
@kindex help-index @r{(button property)}
-A string displayed by the emacs tool-tip help system; by default,
+A string displayed by the Emacs tool-tip help system; by default,
@code{"mouse-2, RET: Push this button"}.
+@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}.
+
@item button
@kindex button @r{(button property)}
All buttons have a non-@code{nil} @code{button} property, which may be useful
Buttons are associated with a region of text, using an overlay or
text-properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
-button type @code{button}). Like all emacs text, the appearance of
+button type @code{button}). Like all Emacs text, the appearance of
the button is governed by the @code{face} property; by default (via
the @code{face} property inherited from the @code{button} button-type)
this is a simple underline, like a typical web-page link.
Insert a button with the label @var{label}.
@end defun
-The following functions are similar, but use emacs text-properties
+The following functions are similar, but use Emacs text-properties
(@pxref{Text Properties}) to hold the button properties, making the
button actually part of the text instead of being a property of the
buffer (using text-properties is usually faster than using overlays,
@cindex button buffer commands
These are commands and functions for locating and operating on
-buttons in an emacs buffer.
+buttons in an Emacs buffer.
@code{push-button} is the command that a user uses to actually `push'
a button, and is bound by default in the button itself to @key{RET}
which uses buttons may want to use @code{button-buffer-map} as a
parent keymap for its keymap.
+If the button has a non-@code{nil} @code{follow-link} property, and
+@var{mouse-1-click-follows-link} is set, a @key{Mouse-1} click will
+also activate the @code{push-button} command.
+
@deffn Command push-button &optional pos use-mouse-action
@tindex push-button
Perform the action specified by a button at location @var{pos}.
buffers that do not override it. @xref{Default Value}.
@end defvar
+@defopt tab-width
+The value of this variable is the spacing between tab stops used for
+displaying tab characters in Emacs buffers. The value is in units of
+columns, and the default is 8. Note that this feature is completely
+independent of the user-settable tab stops used by the command
+@code{tab-to-tab-stop}. @xref{Indent Tabs}.
+@end defopt
+
@defopt indicate-empty-lines
@tindex indicate-empty-lines
@cindex fringes, and empty line indication
support it (window systems). @xref{Fringes}.
@end defopt
-@defopt tab-width
-The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers. The value is in units of
-columns, and the default is 8. Note that this feature is completely
-independent of the user-settable tab stops used by the command
-@code{tab-to-tab-stop}. @xref{Indent Tabs}.
-@end defopt
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling are indicated in the window fringes.
+
+Emacs can indicate the buffer boundaries---that is, the first and last
+line in the buffer---with angle icons when they appear on the screen.
+In addition, Emacs can display an up-arrow in the fringe to show
+that there is text above the screen, and a down-arrow to show
+there is text below the screen.
+
+There are four kinds of basic values:
+
+@table @asis
+@item @code{nil}
+Don't display the icons.
+@item @code{left}
+Display them in the left fringe.
+@item @code{right}
+Display them in the right fringe.
+@item @var{anything-else}
+Display the icon at the top of the window top in the left fringe, and other
+in the right fringe.
+@end table
+
+If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
+controls the angle icons, and @var{arrows} controls the arrows. Both
+@var{angles} and @var{arrows} work according to the table above.
+Thus, @code{(t . right)} places the top angle icon in the left
+fringe, the bottom angle icon in the right fringe, and both arrows in
+the right fringe.
+@end defvar
+
+@defvar default-indicate-buffer-boundaries
+The value of this variable is the default value for
+@code{indicate-buffer-boundaries} in buffers that do not override it.
+@end defvar
@node Display Tables
@section Display Tables
@item 1
The glyph for the end of a continued line (the default is @samp{\}).
Newer Emacs versions, on some platforms, display curved arrows to
-indicate truncation---the display table has no effect in these
+indicate continuation---the display table has no effect in these
situations.
@item 2
The glyph for indicating a character displayed as an octal character