* 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.
+* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
-* Faces:: A face defines a graphics style for text characters:
+* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
+* Fringe Bitmaps:: Customizing fringe bitmaps.
* 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.
* Blinking:: How Emacs shows the matching open parenthesis.
-* Inverse Video:: Specifying how the screen looks.
-* Usual Display:: The usual conventions for displaying nonprinting chars.
-* Display Tables:: How to specify other conventions.
+* Inverse Video:: Specifying how the screen looks.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
@end menu
This function clears and redisplays all visible frames.
@end deffn
+ This function forces certain windows to be redisplayed
+but does not clear them.
+
+@defun force-window-update object
+This function forces redisplay of some or all windows. 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}, 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
@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.
symbols. If it matches the first few elements in a warning type, then
that warning is not logged.
@end defopt
+
@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
@end example
@vindex line-move-ignore-invisible
- Ordinarily, commands that operate on text or move point do not care
+ Ordinarily, functions that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
explicitly ignore invisible newlines if
@code{line-move-ignore-invisible} is non-@code{nil}, but only because
they are explicitly programmed to do so.
+ However, if a command ends with point inside or immediately after
+invisible text, the main editing loop moves point further forward or
+further backward (in the same direction that the command already moved
+it) until that condition is no longer true. Thus, if the command
+moved point back into an invisible range, Emacs moves point back to
+the beginning of that range, following the previous visible character.
+If the command moved point forward into an invisible range, Emacs
+moves point forward past the first visible character that follows the
+invisible text.
+
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
this, the overlay should have a non-@code{nil}
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.
+* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
* Managing Overlays:: Creating and moving overlays.
* Finding Overlays:: Searching for overlays.
@defun overlay-put overlay prop value
This function sets the value of property @var{prop} recorded in
@var{overlay} to @var{value}. It returns @var{value}.
+@end defun
+
+@defun overlay-properties overlay
+This returns a copy of the property list of @var{overlay}.
@end defun
See also the function @code{get-char-property} which checks both
@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)
This section describes the functions to create, delete and move
overlays, and to examine their contents.
+@defun overlayp object
+This function returns @code{t} if @var{object} is an overlay.
+@end defun
+
@defun make-overlay start end &optional buffer front-advance rear-advance
This function creates and returns an overlay that belongs to
@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
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
* Standard Faces:: The faces Emacs normally comes with.
* 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.
+* Attribute Functions:: Functions to examine and set face attributes.
+* Merging 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.
+* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
* Font Lookup:: Looking up the names of available fonts
and information about them.
@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)
@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
@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}.
-If window is @code{nil}, that stands for the selected 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
fringe, and likewise @var{right} for the right fringe. A value of
should appear outside of the display margins.
@end defun
-@defun window-fringes window
+@defun window-fringes &optional window
This function returns information about the fringes of a window
-@var{window}. The value has the form @code{(@var{left-width}
+@var{window}. If @var{window} is omitted or @code{nil}, the selected
+window is used. The value has the form @code{(@var{left-width}
@var{right-width} @var{frames-outside-margins})}.
@end defun
+@defvar overflow-newline-into-fringe
+This variable, if non-@code{nil}, specifies that lines which are
+exactly as wide as the window (not counting the final newline
+character) shall not be broken into two lines on the display (with
+just the newline on the second line). Instead, the newline now
+overflows into the right fringe, and the cursor will be displayed in
+the fringe when positioned on that newline.
+@end defvar
+
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling is indicated in the fringes.
+
+ The buffer boundaries, i.e. first and last line in the buffer, can be
+marked with angle bitmaps in the left or right fringe. This can be
+combined with up and down arrow bitmaps shown at the top and bottom of
+the left or right fringe if the window can be scrolled in either
+direction.
+
+ If the value is @code{left} or @code{right}, both angle and arrow
+bitmaps are displayed in the left or right fringe, respectively.
+Any other non-@code{nil} value causes the bitmap on the top line to be
+displayed in the left fringe, and the bitmap on the bottom line in the
+right fringe.
+
+ If value is a cons @code{(angles . arrows)}, the car specifies the
+position of the angle bitmaps, and the cdr specifies the position of
+the arrow bitmaps. For example, @code{(t . right)} places the top
+angle bitmap in left fringe, the bottom angle bitmap in right fringe,
+and both arrow bitmaps in right fringe. To show just the angle
+bitmaps in the left fringe, but no arrow bitmaps, use @code{(left . nil)}.
+@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 Fringe Bitmaps
+@section Fringe Bitmaps
+@cindex Fringe Bitmaps
+
+ The @dfn{fringe bitmaps} are tiny icons Emacs displays in the fringe
+on a window system 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. Emacs can handle a maximum of 255 different fringe
+bitmaps.
+
+A fringe bitmap is identified by an opaque integer, but Lisp code
+should use the following names defined by @code{(require 'fringe)}:
+
+Truncation and continuation line bitmaps:
+@code{left-truncation-fringe-bitmap},
+@code{right-truncation-fringe-bitmap},
+@code{continued-line-fringe-bitmap},
+@code{continuation-line-fringe-bitmap}.
+
+Buffer indication bitmaps:
+@code{up-arrow-fringe-bitmap},
+@code{down-arrow-fringe-bitmap},
+@code{top-left-angle-fringe-bitmap},
+@code{top-right-angle-fringe-bitmap},
+@code{bottom-left-angle-fringe-bitmap},
+@code{bottom-right-angle-fringe-bitmap},
+@code{left-bracket-fringe-bitmap},
+@code{right-bracket-fringe-bitmap}.
+
+Empty line indication bitmap:
+@code{empty-line-fringe-bitmap}.
+
+Overlay arrow bitmap:
+@code{overlay-arrow-fringe-bitmap}.
+
+Bitmaps for displaying the cursor in right fringe:
+@code{filled-box-cursor-fringe-bitmap},
+@code{hollow-box-cursor-fringe-bitmap},
+@code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},
+@code{hbar-cursor-fringe-bitmap}.
+
+Fringe bitmap opaque value indicating that no fringe bitmap is present:
+@code{no-fringe-bitmap}.
+
+Fringe bitmap opaque value indicating a reference to an undefined bitmap:
+@code{undef-fringe-bitmap}.
+
+ To display an specific fringe bitmap on a line in an Emacs window,
+use it as a @code{left-fringe} or @code{right-fringe} specifier in the
+@code{display} property of some text that is displayed on that line
+(@pxref{Display Property}).
+
+@defun define-fringe-bitmap bits &optional height width align bitmap
+Define a new fringe bitmap, or change an existing bitmap.
+
+The argument @code{bits} is either a string or a vector of integers,
+where each element (typically) corresponds to one row of the bitmap,
+and each bit of an integer corresponds to one pixel of the bitmap.
+
+The optional argument @code{height} specifies the height of the bitmap.
+If @code{height} is @code{nil}, the length of @code{bits} is used.
+
+The optional argument @code{width} specifies the width of the bitmap;
+it must be an integer between 1 and 16, or @code{nil} which defaults
+to a width of 8 pixels.
+
+The optional argument @code{align} may be one of @code{top},
+@code{center}, or @code{bottom}, indicating the positioning of the
+bitmap relative to the rows where it is used; the default is to center
+the bitmap.
+
+The @code{align} argument may also be a list @code{(ALIGN PERIODIC)}
+where @code{ALIGN} is intepreted as described above, and if
+@code{PERIODIC} is non-@code{nil} it specifies that the @code{bits} should
+be repeated until a bitmap of the specified @code{height} is created.
+
+The optional argument @code{bitmap} specifies the opaque integer that
+identifies an existing bitmap to redefine.
+
+The return value is a new opaque integer identifying the new bitmap number,
+or @code{nil} of there are no more free bitmap slots.
+@end defun
+
+@defun destroy-fringe-bitmap bitmap
+Destroy the fringe bitmap identified by the opaque integer
+@code{bitmap}. If @code{bitmap} identifies a standard fringe bitmap,
+the original built-in bitmap is restored.
+@end defun
+
+@defun set-fringe-bitmap-face bitmap &optional face
+Set face for a specific fringe bitmap @code{bitmap} to the face
+specified by the argument @code{face}.
+If @code{face} is @code{nil}, reset face to default @code{fringe} face.
+
+Normally, the specified face should be a face derived from the
+@code{fringe} face, only specifying the foreground color as the
+desired color of the fringe bitmap.
+@end defun
+
@node Scroll Bars
@section Scroll Bars
@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}, this applies to the selected window.)
+Set width and type of scroll bars of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
@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
@defun window-scroll-bars &optional window
Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, it defaults to the currently
-selected window. The value is a list of the form @code{(@var{width}
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
@var{cols} @var{vertical-type} @var{horizontal-type})}. The value
@var{width} is the value that was specified for the width (which may
be @code{nil}); @var{cols} is the number of columns that the scroll
window take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
+@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.
+
+The available pointer shapes are: @code{text} (or @code{nil}),
+@code{arrow}, @code{hand}, @code{vdrag}, @code{hdrag},
+@code{modeline}, and @code{hourglass}.
+
+The mouse pointer shape over text or images can be changed via the
+@code{pointer} text property, and for image with the @code{:pointer}
+and @code{:map} image properties.
+
+@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
they mean.
@menu
-* Specified Space:: Displaying one space with a specified width.
-* Other Display Specs:: Displaying an image; magnifying text; moving it
+* 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.
-* Conditional Display:: Making any of the above features conditional
+* Display Fringe Bitmaps:: Displaying a fringe bitmap in a specific line.
+* Conditional Display:: Making any of the above features conditional
depending on some Lisp expression.
@end menu
@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. The @var{width} may 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 the value @var{hpos} is an integer or a floating point number, it
+is measured in units of the normal character width. The @var{hpos}
+may also be a @dfn{pixel width} specification (@pxref{Pixel Specification}).
@end table
+ The @code{:height} and @code{:align-to} properties are also supported
+on non-window systems.
+
You should use one and only one of the above properties. You can
also specify the height of the space, with other 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.
+@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 (trivial) expression
+which is evaluated during redisplay. The result of the evaluation is
+used as an absolute number of pixels.
+
+ The following expressions are supported:
+
+@example
+@group
+ EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM
+ NUM ::= INTEGER | FLOAT | SYMBOL
+ UNIT ::= in | mm | cm | width | height
+ ELEM ::= left-fringe | right-fringe | left-margin | right-margin
+ | scroll-bar | text
+ POS ::= left | center | right
+ FORM ::= (NUM . EXPR) | (OP EXPR ...)
+ OP ::= + | -
+@end group
+@end example
+
+ The form @var{NUM} specifies a fractional width or height of the
+default frame font size. The form @code{(@var{NUM})} specifies an
+absolute number of pixels. If a symbol @var{SYMBOL} is specified, its
+buffer-local variable binding is used.
+
+ The @code{in}, @code{mm}, and @code{cm} units specifies the number
+of pixels per inch, milli-meter, and centi-meter, resp. The
+@code{width} and @code{height} units correspond to the width and
+height of the current face font. An image specification @var{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.
+
+ One 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 occurences 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.
+
+ The value of the form @code{(@var{NUM} . @var{EXPR})} is the value of
+@var{NUM} multiplied by the value of the expression @var{EXPR}. For
+example, @samp{(2 . in)} specifies a width of 2 inches, while
+@samp{(0.5 . 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
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 property is used with an @code{image} property to specify a
+@dfn{slice} (a partial area) of the image to display. The top left
+corner of the slice is specified by @var{y} and @var{x} and the width
+and height of the slice is specified by @var{width} and @var{height}.
+Integer values are taken as pixel values. A floating point number in
+the range 0.0 - 1.0 is relative to the width or height of the whole
+image.
+
@item ((margin nil) @var{string})
@itemx @var{string}
A display specification of this form means to display @var{string}
If @var{window} is @code{nil}, the selected window is used.
@end defun
+@node Display Fringe Bitmaps
+@subsection Displaying Bitmaps in the Fringes
+@cindex display fringes
+@cindex margins, fringes
+
+ You can display a bitmap in the left or right fringes for a given
+line in a window using the @code{display} property.
+
+ To put text in the left or right fringe of the window, use a
+display specification of the form @code{(left-fringe @var{bitmap} [@var{face}])}
+or @code{(right-fringe @var{bitmap} [@var{face}])} on one of the
+characters on the corresponding text line.
+
+ The @var{bitmap} is an opaque integer identifying the bitmap, and the
+optional @var{face} is the name of the face whose foreground and
+background color is to be used for displaying the bitmap.
+
+@defun fringe-bitmaps-at-pos &optional pos window
+This function returns the fringe bitmaps of the display row containing
+position @var{pos} in window @var{window}. The return value is a cons
+@code{(@var{left} . @var{right})} where @var{left} and @var{right}
+are the fringe bitmap numbers for the bitmaps in the left and right
+fringe, resp.
+
+ Returns @code{nil} if @var{pos} is not visible in window
+@var{window}. If @var{window} is @code{nil}, use the selected window.
+If @var{pos} is @code{nil}, use value of point in that window.
+@end defun
+
@node Conditional Display
@subsection Conditional Display Specifications
@cindex conditional display specifications
@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 posible 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 Shapes}, 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 Shapes}, 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, e.g. @samp{[area4 mouse-1]} if the hot-spot's @var{id} is
+@samp{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.
@item :index @var{index}
You can use @code{:index} to specify one image from a GIF file that
contains more than one image. This property specifies use of image
-number @var{index} from the file. An error is signaled if the GIF file
-doesn't contain an image with index @var{index}.
+number @var{index} from the file. If the GIF file doesn't contain an
+image with index @var{index}, the image displays as a hollow box.
@end table
@ignore
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 taken as pixel values. A floating point number in the
+range 0.0 - 1.0 is relative to the width or height of the 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 the image is automatically split 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
are cleared.
@end defun
+@node Buttons
+@section Buttons
+@cindex buttons
+@cindex buttons in buffers
+@cindex clickable buttons in buffers
+
+ The @emph{button} package defines functions for inserting and
+manipulating clickable (with the mouse, or via keyboard commands)
+buttons in Emacs buffers, such as might be used for help hyper-links,
+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
+are called its button properties. @xref{Button Properties}.
+
+One of the these properties (@code{action}) is a function, which will
+be called when the user invokes it using the keyboard or the mouse.
+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
+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
+programmers---for users, the result is about the same). The extra
+speed and space savings are useful mainly if you need to create many
+buttons in a buffer (for instance an @code{*Apropos*} buffer uses
+buttons to make entries clickable, and may contain many thousands of
+entries).
+
+@menu
+* Button Properties:: Button properties with special meanings.
+* Button Types:: Defining common properties for classes of buttons.
+* 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::
+@end menu
+
+@node Button Properties
+@subsection Button Properties
+@cindex button properties
+
+ Buttons have an associated list of properties defining their
+appearance and behavior, and other arbitrary properties may be used
+for application specific purposes.
+
+Some properties that have special meaning to the button package
+include:
+
+@table @code
+
+@item action
+@kindex action @r{(button property)}
+The function to call when the user invokes the button, which is passed
+the single argument @var{button}. By default this is @code{ignore},
+which does nothing.
+
+@item mouse-action
+@kindex mouse-action @r{(button property)}
+This is similar to @code{action}, and when present, will be used
+instead of @code{action} for button invocations resulting from
+mouse-clicks (instead of the user hitting @key{RET}). If not
+present, mouse-clicks use @code{action} instead.
+
+@item face
+@kindex face @r{(button property)}
+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.
+
+@item keymap
+@kindex keymap @r{(button property)}
+The button's keymap, defining bindings active within the button
+region. By default this is the usual button region keymap, stored
+in the variable @code{button-map}, which defines @key{RET} and
+@key{mouse-2} to invoke the button.
+
+@item type
+@kindex type @r{(button property)}
+The button-type of the button. When creating a button, this is
+usually specified using the @code{:type} keyword argument.
+@xref{Button Types}.
+
+@item help-echo
+@kindex help-index @r{(button property)}
+A string displayed by the Emacs tool-tip help system; by default,
+@code{"mouse-2, RET: Push this button"}.
+
+@item button
+@kindex button @r{(button property)}
+All buttons have a non-@code{nil} @code{button} property, which may be useful
+in finding regions of text that comprise buttons (which is what the
+standard button functions do).
+@end table
+
+There are other properties defined for the regions of text in a
+button, but these are not generally interesting for typical uses.
+
+@node Button Types
+@subsection Button Types
+@cindex button types
+
+ Every button has a button @emph{type}, which defines default values
+for the button's properties. Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
+
+@defun define-button-type name &rest properties
+@tindex define-button-type
+Define a `button type' called @var{name}. 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
+the @code{:type} keyword argument).
+
+In addition, the keyword argument @code{:supertype} may be used to
+specify a button-type from which @var{name} inherits its default
+property values. Note that this inheritance happens only when
+@var{name} is defined; subsequent changes to a supertype are not
+reflected in its subtypes.
+@end defun
+
+Using @code{define-button-type} to define default properties for
+buttons is not necessary---buttons without any specified type use the
+built-in button-type @code{button}---but it is is encouraged, since
+doing so usually makes the resulting code clearer and more efficient.
+
+@node Making Buttons
+@subsection Making Buttons
+@cindex making buttons
+
+ 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
+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.
+
+For convenience, there are two sorts of button-creation functions,
+those that add button properties to an existing region of a buffer,
+called @code{make-...button}, and those also insert the button text,
+called @code{insert-...button}.
+
+The button-creation functions all take the @code{&rest} argument
+@var{properties}, which should be a sequence of @var{property value}
+pairs, specifying properties to add to the button; see @ref{Button
+Properties}. In addition, the keyword argument @code{:type} may be
+used to specify a button-type from which to inherit other properties;
+see @ref{Button Types}. Any properties not explicitly specified
+during creation will be inherited from the button's type (if the type
+defines such a property).
+
+The following functions add a button using an overlay
+(@pxref{Overlays}) to hold the button properties:
+
+@defun make-button beg end &rest properties
+@tindex make-button
+Make a button from @var{beg} to @var{end} in the current buffer.
+@end defun
+
+@defun insert-button label &rest properties
+@tindex insert-button
+Insert a button with the label @var{label}.
+@end defun
+
+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,
+so this may be preferable when creating large numbers of buttons):
+
+@defun make-text-button beg end &rest properties
+@tindex make-text-button
+Make a button from @var{beg} to @var{end} in the current buffer, using
+text-properties.
+@end defun
+
+@defun insert-text-button label &rest properties
+@tindex insert-text-button
+Insert a button with the label @var{label}, using text-properties.
+@end defun
+
+Buttons using text-properties retain no markers into the buffer are
+retained, which is important for speed in cases where there are
+extremely large numbers of buttons.
+
+@node Manipulating Buttons
+@subsection Manipulating Buttons
+@cindex manipulating buttons
+
+These are functions for getting and setting properties of buttons.
+Often these are used by a button's invocation function to determine
+what to do.
+
+Where a @var{button} parameter is specified, it means an object
+referring to a specific button, either an overlay (for overlay
+buttons), or a buffer-position or marker (for text property buttons).
+Such an object is passed as the first argument to a button's
+invocation function when it is invoked.
+
+@defun button-start button
+@tindex button-start
+Return the position at which @var{button} starts.
+@end defun
+
+@defun button-end button
+@tindex button-end
+Return the position at which @var{button} ends.
+@end defun
+
+@defun button-get button prop
+@tindex button-get
+Get the property of button @var{button} named @var{prop}.
+@end defun
+
+@defun button-put button prop val
+@tindex button-put
+Set @var{button}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-activate button &optional use-mouse-action
+@tindex button-activate
+Call @var{button}'s @code{action} property (i.e., invoke it). If
+@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@end defun
+
+@defun button-label button
+@tindex button-label
+Return @var{button}'s text label.
+@end defun
+
+@defun button-type button
+@tindex button-type
+Return @var{button}'s button-type.
+@end defun
+
+@defun button-has-type-p button type
+@tindex button-has-type-p
+Return @code{t} if @var{button} has button-type @var{type}, or one of
+@var{type}'s subtypes.
+@end defun
+
+@defun button-at pos
+@tindex button-at
+Return the button at position @var{pos} in the current buffer, or @code{nil}.
+@end defun
+
+@node Button Buffer Commands
+@subsection Button Buffer Commands
+@cindex button buffer commands
+
+These are commands and functions for locating and operating on
+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}
+and to @key{mouse-2} using a region-specific keymap. Commands
+that are useful outside the buttons itself, such as
+@code{forward-button} and @code{backward-button} are additionally
+available in the keymap stored in @code{button-buffer-map}; a mode
+which uses buttons may want to use @code{button-buffer-map} as a
+parent keymap for its keymap.
+
+@deffn Command push-button &optional pos use-mouse-action
+@tindex push-button
+Perform the action specified by a button at location @var{pos}.
+@var{pos} may be either a buffer position or a mouse-event. If
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used. If there's no button at @var{pos}, do
+nothing and return @code{nil}, otherwise return @code{t}.
+@end deffn
+
+@deffn Command forward-button n &optional wrap display-message
+@tindex forward-button
+Move to the @var{n}th next button, or @var{n}th previous button if
+@var{n} is negative. If @var{n} is zero, move to the start of any
+button at point. If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end. If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
+@end deffn
+
+@deffn Command backward-button n &optional wrap display-message
+@tindex backward-button
+Move to the @var{n}th previous button, or @var{n}th next button if
+@var{n} is negative. If @var{n} is zero, move to the start of any
+button at point. If @var{wrap} is non-@code{nil}, moving past either
+end of the buffer continues from the other end. If
+@var{display-message} is non-@code{nil}, the button's help-echo string
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
+@end deffn
+
+@defun next-button pos &optional count-current
+@tindex next-button
+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
+@tindex previous-button
+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.
+@end defun
+
+@node Manipulating Button Types
+@subsection Manipulating Button Types
+@cindex manipulating button types
+
+@defun button-type-put type prop val
+@tindex button-type-put
+Set the button-type @var{type}'s @var{prop} property to @var{val}.
+@end defun
+
+@defun button-type-get type prop
+@tindex button-type-get
+Get the property of button-type @var{type} named @var{prop}.
+@end defun
+
+@defun button-type-subtype-p type supertype
+@tindex button-type-subtype-p
+Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
+@end defun
+
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@menu
-* Display Table Format:: What a display table consists of.
-* Active Display Table:: How Emacs selects a display table to use.
-* Glyphs:: How to define a glyph, and what glyphs mean.
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How Emacs selects a display table to use.
+* Glyphs:: How to define a glyph, and what glyphs mean.
@end menu
@node Display Table Format