@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/display
@node Display, System Interface, Processes, Top
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
-* Abstract Display:: Emacs' Widget for Object Collections.
+* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying nonprinting chars.
* Display Tables:: How to specify other conventions.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
+* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Refresh Screen
immediately, but the requested redisplay does happen
eventually---after all the input has been processed.
- On text-only terminals, suspending and resuming Emacs normally also
+ On text terminals, suspending and resuming Emacs normally also
refreshes the screen. Some terminal emulators record separate
contents for display-oriented programs such as Emacs and for ordinary
sequential display. If you are using such a terminal, you might want
@defvar wrap-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is prepended to every continuation line at
-display-time. (If lines are truncated, the wrap-prefix is never
-used.) It may be a string, an image, or a stretch-glyph; the value is
-interpreted in the same way as a @code{display} text property.
-@xref{Display Property}.
+display time. (If lines are truncated, the wrap-prefix is never
+used.) It may be a string or an image (@pxref{Other Display Specs}),
+or a stretch of whitespace such as specified by the @code{:width} or
+@code{:align-to} display properties (@pxref{Specified Space}). The
+value is interpreted in the same way as a @code{display} text
+property. @xref{Display Property}.
A wrap-prefix may also be specified for regions of text, using the
@code{wrap-prefix} text or overlay property. This takes precedence
@defvar line-prefix
If this buffer-local variable is non-@code{nil}, it defines a
``prefix'' that is prepended to every non-continuation line at
-display-time. It may be a string, an image, or a stretch-glyph; the
-value is interpreted in the same way as a @code{display} text
-property. @xref{Display Property}.
+display time. It may be a string or an image (@pxref{Other Display
+Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}). The value is interpreted in the same way as a @code{display}
+text property. @xref{Display Property}.
A line-prefix may also be specified for regions of text using the
@code{line-prefix} text or overlay property. This takes precedence
non-@code{nil} (the default), but only because they are explicitly
programmed to do so.
- However, if a command ends with point inside or immediately before
-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, and then back one more character. If the
-command moved point forward into an invisible range, Emacs moves point
-forward up to the first visible character that follows the invisible
-text.
+ However, if a command ends with point inside or at the boundary of invisible
+text, the main editing loop moves point to one of the two ends of the invisible
+text. Which end to move to is chosen based on the following factors: make sure
+that the overall movement of the command is still in the same direction, and
+prefer a position where an inserted char would not inherit the @code{invisible}
+property. Additionally, if the text is not replaced by an ellipsis and the
+command only moved within the invisible text, then point is moved one extra
+character so as to try and reflect the command's movement by a visible movement
+of the cursor.
+
+ Thus, if the command moved point back to an invisible range (with the usual
+stickiness), Emacs moves point back to the beginning of that range. If the
+command moved point forward into an invisible range, Emacs moves point forward
+to the first visible character that follows the invisible text and then forward
+one more character.
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
numeric height value specifies the line spacing, rather than the line
height.
- On text-only terminals, the line spacing cannot be altered.
+ On text terminals, the line spacing cannot be altered.
@node Faces
@section Faces
Font weight---one of the symbols (from densest to faintest)
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or
-@code{ultra-light}. On text-only terminals that support
+@code{ultra-light}. On text terminals which support
variable-brightness text, any weight greater than normal is displayed
as extra bright, and any weight less than normal is displayed as
half-bright.
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique},
@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On
-text-only terminals that support variable-brightness text, slanted
-text is displayed as half-bright.
+text terminals that support variable-brightness text, slanted text is
+displayed as half-bright.
@item :foreground
Foreground color, a string. The value can be a system-defined color
entity, or a string. Emacs converts such values to an appropriate
font object, and stores that font object as the actual attribute
value. If you specify a string, the contents of the string should be
-a font name (@pxref{Font X,, Font Specification Options, emacs, The
-GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
-Emacs chooses the first font matching those wildcards. Specifying
-this attribute also changes the values of the @code{:family},
-@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
-@code{:slant} attributes.
+a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
+font name is an XLFD containing wildcards, Emacs chooses the first
+font matching those wildcards. Specifying this attribute also changes
+the values of the @code{:family}, @code{:foundry}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} attributes.
@item :inherit
The name of a face from which to inherit attributes, or a list of face
@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@var{name}. @var{name} should be a string containing a font name in
-either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
-Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD
-string, wildcard characters may be used: the @samp{*} character
-matches any substring, and the @samp{?} character matches any single
-character. Case is ignored when matching font names.
+either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The
+GNU Emacs Manual}). Within an XLFD string, wildcard characters may be
+used: the @samp{*} character matches any substring, and the @samp{?}
+character matches any single character. Case is ignored when matching
+font names.
If the optional arguments @var{reference-face} and @var{frame} are
specified, the returned list includes only fonts that are the same
@table @code
@item :name
The font name (a string), in either XLFD, Fontconfig, or GTK format.
-@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
-Manual}.
+@xref{Fonts,,, emacs, The GNU Emacs Manual}.
@item :family
@itemx :foundry
@defun font-xlfd-name font &optional fold-wildcards
This function returns the XLFD (X Logical Font Descriptor), a string,
-matching @var{font}. @xref{Font X,, Font Specification Options,
-emacs, The GNU Emacs Manual}, for information about XLFDs. If the
-name is too long for an XLFD (which can contain at most 255
-characters), the function returns @code{nil}.
+matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for
+information about XLFDs. If the name is too long for an XLFD (which
+can contain at most 255 characters), the function returns @code{nil}.
If the optional argument @var{fold-wildcards} is non-@code{nil},
consecutive wildcards in the XLFD are folded into one.
@defvar fringe-indicator-alist
This buffer-local variable specifies the mapping from logical fringe
-indicators to the actual bitmaps displayed in the window fringes.
+indicators to the actual bitmaps displayed in the window fringes. The
+value is an alist of elements @code{(@var{indicator}
+. @var{bitmaps})}, where @var{indicator} specifies a logical indicator
+type and @var{bitmaps} specifies the fringe bitmaps to use for that
+indicator.
-These symbols identify the logical fringe indicators:
+ Each @var{indicator} should be one of the following symbols:
@table @asis
-@item Truncation and continuation line indicators:
-@code{truncation}, @code{continuation}.
-
-@item Buffer position indicators:
-@code{up}, @code{down},
-@code{top}, @code{bottom},
-@code{top-bottom}.
-
-@item Empty line indicator:
-@code{empty-line}.
-
-@item Overlay arrow indicator:
-@code{overlay-arrow}.
-
-@item Unknown bitmap indicator:
-@code{unknown}.
+@item @code{truncation}, @code{continuation}.
+Used for truncation and continuation lines.
+
+@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom}
+Used when @code{indicate-buffer-boundaries} is non-@code{nil}:
+@code{up} and @code{down} indicate a buffer boundary lying above or
+below the window edge; @code{top} and @code{bottom} indicate the
+topmost and bottommost buffer text line; and @code{top-bottom}
+indicates where there is just one line of text in the buffer.
+
+@item @code{empty-line}
+Used to indicate empty lines when @code{indicate-empty-lines} is
+non-@code{nil}.
+
+@item @code{overlay-arrow}
+Used for overlay arrows (@pxref{Overlay Arrow}).
+@c Is this used anywhere?
+@c @item Unknown bitmap indicator:
+@c @code{unknown}.
@end table
- The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
-specifies the fringe bitmaps used to display a specific logical
-fringe indicator.
-
-Here, @var{indicator} specifies the logical indicator type, and
-@var{bitmaps} is list of symbols @code{(@var{left} @var{right}
-[@var{left1} @var{right1}])} which specifies the actual bitmap shown
-in the left or right fringe for the logical indicator.
-
-The @var{left} and @var{right} symbols specify the bitmaps shown in
-the left and/or right fringe for the specific indicator. The
-@var{left1} or @var{right1} bitmaps are used only for the `bottom' and
-`top-bottom indicators when the last (only) line in has no final
-newline. Alternatively, @var{bitmaps} may be a single symbol which is
-used in both left and right fringes.
-
-When @code{fringe-indicator-alist} has a buffer-local value, and there
-is no bitmap defined for a logical indicator, or the bitmap is
+ Each @var{bitmaps} value may be a list of symbols @code{(@var{left}
+@var{right} [@var{left1} @var{right1}])}. The @var{left} and
+@var{right} symbols specify the bitmaps shown in the left and/or right
+fringe, for the specific indicator. @var{left1} and @var{right1} are
+specific to the @code{bottom} and @code{top-bottom} indicators, and
+are used to indicate that the last text line has no final newline.
+Alternatively, @var{bitmaps} may be a single symbol which is used in
+both left and right fringes.
+
+ @xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how
+to define your own. In addition, @code{nil} represents the empty
+bitmap (i.e.@: an indicator that is not shown).
+
+ When @code{fringe-indicator-alist} has a buffer-local value, and
+there is no bitmap defined for a logical indicator, or the bitmap is
@code{t}, the corresponding value from the default value of
@code{fringe-indicator-alist} is used.
-
-To completely hide a specific indicator, set the bitmap to @code{nil}.
@end defvar
-Standard fringe bitmaps for indicators:
-@example
-left-arrow right-arrow up-arrow down-arrow
-left-curly-arrow right-curly-arrow
-left-triangle right-triangle
-top-left-angle top-right-angle
-bottom-left-angle bottom-right-angle
-left-bracket right-bracket
-filled-rectangle hollow-rectangle
-filled-square hollow-square
-vertical-bar horizontal-bar
-empty-line question-mark
-@end example
-
@node Fringe Cursors
@subsection Fringe Cursors
@cindex fringe cursors
bitmaps are used to represent the cursor in the fringe depending on
the current buffer's cursor type.
-@table @asis
-@item Logical cursor types:
-@code{box} , @code{hollow}, @code{bar},
-@code{hbar}, @code{hollow-small}.
-@end table
-
-The @code{hollow-small} type is used instead of @code{hollow} when the
-normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
-display line.
-
@defopt 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,
@defvar fringe-cursor-alist
This variable specifies the mapping from logical cursor type to the
actual fringe bitmaps displayed in the right fringe. The value is an
-alist where each element @code{(@var{cursor} . @var{bitmap})} specifies
-the fringe bitmaps used to display a specific logical cursor type in
-the fringe. Here, @var{cursor} specifies the logical cursor type and
-@var{bitmap} is a symbol specifying the fringe bitmap to be displayed
-for that logical cursor type.
+alist where each element has the form @code{(@var{cursor-type}
+. @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to
+display cursors of type @var{cursor-type}.
+
+Each @var{cursor-type} should be one of @code{box}, @code{hollow},
+@code{bar}, @code{hbar}, or @code{hollow-small}. The first four have
+the same meanings as in the @code{cursor-type} frame parameter
+(@pxref{Cursor Parameters}). The @code{hollow-small} type is used
+instead of @code{hollow} when the normal @code{hollow-rectangle}
+bitmap is too tall to fit on a specific display line.
+
+Each @var{bitmap} should be a symbol specifying the fringe bitmap to
+be displayed for that logical cursor type.
+@iftex
+See the next subsection for details.
+@end iftex
+@ifnottex
+@xref{Fringe Bitmaps}.
+@end ifnottex
When @code{fringe-cursor-alist} has a buffer-local value, and there is
no bitmap defined for a cursor type, the corresponding value from the
default value of @code{fringes-indicator-alist} is used.
@end defvar
-Standard bitmaps for displaying the cursor in right fringe:
-@example
-filled-rectangle hollow-rectangle filled-square hollow-square
-vertical-bar horizontal-bar
-@end example
-
-
@node Fringe Bitmaps
@subsection Fringe Bitmaps
@cindex fringe bitmaps
The @dfn{fringe bitmaps} are the actual bitmaps which represent the
logical fringe indicators for truncated or continued lines, buffer
-boundaries, overlay arrow, etc. Fringe bitmap symbols have their own
-name space. 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, instead of the
-default @code{fringe} face. @var{face} is automatically merged with
-the @code{fringe} face, so normally @var{face} need only specify the
-foreground color for the bitmap.
+boundaries, overlay arrows, etc. Each bitmap is represented by a
+symbol.
+@iftex
+These symbols are referred to by the variables
+@code{fringe-indicator-alist} and @code{fringe-cursor-alist},
+described in the previous subsections.
+@end iftex
+@ifnottex
+These symbols are referred to by the variable
+@code{fringe-indicator-alist}, which maps fringe indicators to bitmaps
+(@pxref{Fringe Indicators}), and the variable
+@code{fringe-cursor-alist}, which maps fringe cursors to bitmaps
+(@pxref{Fringe Cursors}).
+@end ifnottex
+
+ Lisp programs can also directly display a bitmap in the left or
+right fringe, by using a @code{display} property for one of the
+characters appearing in the line (@pxref{Other Display Specs}). Such
+a display specification has the form
+
+@example
+(left-fringe @var{bitmap} [@var{face}])
+@end example
+
+@noindent
+or
+
+@example
+(right-fringe @var{bitmap} [@var{face}])
+@end example
+
+@noindent
+The symbol @var{bitmap} identifies the bitmap to display. The
+optional @var{face} names a face whose foreground color is used to
+display the bitmap; this face is automatically merged with the
+@code{fringe} face.
+
+ Here is a list of the standard fringe bitmaps defined in Emacs, and
+how they are currently used in Emacs (via
+@code{fringe-indicator-alist} and @code{fringe-cursor-alist}):
+
+@table @asis
+@item @code{left-arrow}, @code{right-arrow}
+Used to indicate truncated lines.
+
+@item @code{left-curly-arrow}, @code{right-curly-arrow}
+Used to indicate continued lines.
+
+@item @code{right-triangle}, @code{left-triangle}
+The former is used by overlay arrows. The latter is unused.
+
+@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle}
+@itemx @code{bottom-left-angle}, @code{bottom-right-angle}
+@itemx @code{top-right-angle}, @code{top-left-angle}
+@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle}
+Used to indicate buffer boundaries.
+
+@item @code{filled-rectangle}, @code{hollow-rectangle}
+@itemx @code{filled-square}, @code{hollow-square}
+@itemx @code{vertical-bar}, @code{horizontal-bar}
+Used for different types of fringe cursors.
+
+@item @code{empty-line}, @code{question-mark}
+Unused.
+@end table
+
+@noindent
+The next subsection describes how to define your own fringe bitmaps.
@defun fringe-bitmaps-at-pos &optional pos window
This function returns the fringe bitmaps of the display line
Each variable on this list can have properties
@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
-specify an overlay arrow string (for text-only terminals) or fringe
-bitmap (for graphical terminals) to display at the corresponding
-overlay arrow position. If either property is not set, the default
+specify an overlay arrow string (for text terminals) or fringe bitmap
+(for graphical terminals) to display at the corresponding overlay
+arrow position. If either property is not set, the default
@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
is used.
* Other Image Types:: Various other formats are supported.
* Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once it is defined.
+* Animated Images:: Some image formats can be animated.
* Image Cache:: Internal mechanisms of image display.
@end menu
new image formats). Note that image types @code{pbm} and @code{xbm}
do not depend on external libraries and are always available in Emacs.
- The supported image formats include XBM, XPM (this requires the
-libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
-@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
-@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
-v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
-@code{librsvg} 2.0.0).
+ The supported image formats (and the necessary library files)
+include XBM, XPM (@code{libXpm} and @code{libz}), GIF (@code{libgif}
+or @code{libungif}), PostScript, PBM, JPEG (@code{libjpeg}), TIFF
+(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
You specify one of these formats with an image type symbol. The image
type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
@table @code
@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. If the GIF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+GIF file that contains more than one image. If the GIF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box. GIF files with more than one image can be animated,
+@pxref{Animated Images}.
@end table
-@ignore
-This could be used to implement limited support for animated GIFs.
-For example, the following function displays a multi-image GIF file
-at point-min in the current buffer, switching between sub-images
-every 0.1 seconds.
-
-(defun show-anim (file max)
- "Display multi-image GIF file FILE which contains MAX subimages."
- (display-anim (current-buffer) file 0 max t))
-
-(defun display-anim (buffer file idx max first-time)
- (when (= idx max)
- (setq idx 0))
- (let ((img (create-image file nil :image idx)))
- (with-current-buffer buffer
- (goto-char (point-min))
- (unless first-time (delete-char 1))
- (insert-image img))
- (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
-@end ignore
-
@node TIFF Images
@subsection TIFF Images
@cindex TIFF
@table @code
@item :index @var{index}
-You can use @code{:index} to specify one image from a TIFF file that
-contains more than one image. This property specifies use of image
-number @var{index} from the file. If the TIFF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+TIFF file that contains more than one image. If the TIFF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box.
@end table
@node PostScript Images
support, you can use the ImageMagick library to load many image formats.
@findex imagemagick-types
+@findex imagemagick-register-types
The function @code{imagemagick-types} returns a list of image file
extensions that your installation of ImageMagick supports. To enable
support, you must call the function @code{imagemagick-register-types}.
+This enables Emacs to visit these file types in @code{image-mode}
+(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}).
+If your Emacs was not compiled with ImageMagick support, then
+@code{imagemagick-types} will be undefined and
+@code{imagemagick-register-types} will do nothing.
@vindex imagemagick-types-inhibit
The variable @code{imagemagick-types-inhibit} specifies a list of
-image types that you do @emph{not} want ImageMagick to handle. There
-may be overlap between image loaders in your Emacs installation, and
-you may prefer to use a different one for a given image type (which
-@c FIXME how is this priority determined?
-loader will be used in practice depends on the priority of the loaders).
-@c FIXME why are these uppercase when image-types is lower-case?
-@c FIXME what are the possibe options? Are these actually file extensions?
-For example, if you never want to use the ImageMagick loader to use
+image types that you do @emph{not} want ImageMagick to handle. It is
+a list of symbols, each of which has the same name as one of the
+format tags used internally by ImageMagick (i.e., as
+@code{imagemagick-types} returns). ImageMagick has a very broad
+definition of what an image is, for example it includes such file
+types as C files and HTML files. It is not appropriate to treat these
+as images in Emacs. You can add any other ImageMagick type that you
+wish to this list.
+@ignore
+@c I don't know what this means. I suspect it means eg loading jpg
+@c images via libjpeg or ImageMagick. But it doesn't work.
+@c If you don't have libjpeg support compiled in, you cannot
+@c view jpeg images, even if you have imagemagick support:
+@c http://debbugs.gnu.org/9045
+@c And if you have both compiled in, then you always get
+@c the libjpeg version:
+@c http://debbugs.gnu.org/10746
+There may be overlap between image loaders in your Emacs installation,
+and you may prefer to use a different one for a given image type
+(which loader will be used in practice depends on the priority of the
+loaders).
+For example, if you never want to use the ImageMagick loader to view
JPEG files, add @code{JPG} to this list.
+@end ignore
+Note that ImageMagick often distinguishes between several different
+types of a particular format (e.g., @code{JPG}, @code{JPEG},
+@code{PJPEG}, etc.), and you may need to add all versions to this
+list.
+@c Not sure this should even be in the manual at all.
@vindex imagemagick-render-type
-You can set the variable @code{imagemagick-render-type} to choose
-between screen render methods for the ImageMagick loader. The options
-are: @code{0}, a conservative method which works with older
-@c FIXME details of this "newer method"?
-@c Presumably it is faster but may be less "robust"?
-ImageMagick versions (it is a bit slow, but robust); and @code{1},
-a newer ImageMagick method.
+If you wish to experiment with the performance of the ImageMagick
+loader, see the variable @code{imagemagick-render-type}.
Images loaded with ImageMagick support a few new display specifications:
Specifies a rotation angle in degrees.
@item :index
-Specifies which image to view inside an image bundle file format, such
-as TIFF or DJVM. You can use the @code{image-metadata} function to
-retrieve the total number of images in an image bundle (this is
-similar to how GIF files work).
+@c Doesn't work: http://debbugs.gnu.org/7978
+This has the same meaning as it does for GIF images (@pxref{GIF Images}),
+i.e. it specifies which image to view inside an image bundle file format
+such as DJVM. You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle.
@end table
@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
+@node Animated Images
+@subsection Animated Images
+
+@cindex animation
+@cindex image animation
+Some image files can contain more than one image. This can be used to
+create animation. Currently, Emacs only supports animated GIF files.
+The following functions related to animated images are available.
+
+@defun image-animated-p image
+This function returns non-nil if @var{image} can be animated.
+The actual return value is a cons @code{(@var{nimages} . @var{delay})},
+where @var{nimages} is the number of frames and @var{delay} is the
+delay in seconds between them.
+@end defun
+
+@defun image-animate image &optional index limit
+This function animates @var{image}. The optional integer @var{index}
+specifies the frame from which to start (default 0). The optional
+argument @var{limit} controls the length of the animation. If omitted
+or @code{nil}, the image animates once only; if @code{t} it loops
+forever; if a number animation stops after that many seconds.
+@end defun
+
+@noindent Animation operates by means of a timer. Note that Emacs imposes a
+minimum frame delay of 0.01 seconds.
+
+@defun image-animate-timer image
+This function returns the timer responsible for animating @var{image},
+if there is one.
+@end defun
+
+
@node Image Cache
@subsection Image Cache
@cindex image cache
selected frame. If @var{frame} is @code{t}, the image is flushed on
all existing frames.
-In Emacs' current implementation, each graphical terminal possesses an
+In Emacs's current implementation, each graphical terminal possesses an
image cache, which is shared by all the frames on that terminal
(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
also refreshes it in all other frames on the same terminal.
@itemize @bullet
@item
Character codes 32 through 126 map to glyph codes 32 through 126.
-Normally this means they display as themselves.
+Normally this means they display as themselves, but a display table
+can change that.
@item
Character code 9 is a horizontal tab. It displays as whitespace
up to a position determined by @code{tab-width}.
@item
-Character code 10 is a newline.
+Character code 10 is a newline. It is normally invisible on display,
+and has the effect of ending the preceding line and starting a new
+line.
@item
-All other codes in the range 0 through 31, and code 127, display in one
-of two ways according to the value of @code{ctl-arrow}. If it is
-non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
-specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
-just like the codes in the range 128 to 255.
-
-On MS-DOS terminals, Emacs arranges by default for the character code
-127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon. This glyph is used to display non-@acronym{ASCII} characters
-that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
-emacs, The GNU Emacs Manual}.
-
+All other codes in the range 0 through 31 display in one of two ways
+according to the value of @code{ctl-arrow}. If it is non-@code{nil},
+these codes map to sequences of two glyphs, where the first glyph is
+the @acronym{ASCII} code for @samp{^}. (A display table can specify a
+glyph to use instead of @samp{^}.) Otherwise, these codes map just
+like the raw bytes in the range 128 to 255 (described below).
+
+@cindex octal escapes
@item
-Character codes 128 through 255 map to sequences of four glyphs, where
-the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
-digit characters representing the character code in octal. (A display
-table can specify a glyph to use instead of @samp{\}.)
+Raw bytes (@pxref{Text Representations}) with codes 128 through 255,
+and the @acronym{ASCII} control character with code 127, display as
+sequences of four glyphs, where the first glyph is the @acronym{ASCII}
+code for @samp{\}, and the others are digit characters representing
+the character code in octal. (A display table can specify a glyph to
+use instead of @samp{\}.) This is known as the @dfn{octal escape}
+display.
@item
-Multibyte character codes above 256 are displayed as themselves, or as
-a question mark or a hex code or an empty box if the terminal cannot
-display that character.
+Non-@acronym{ASCII} character codes above 127 are displayed as
+themselves, if the terminal and the available fonts support them.
+Characters that are not supported by the terminal, or (on window
+systems) have no fonts available for them, are displayed as a question
+mark or a hex code or an empty box. @xref{Glyphless Chars}, for how
+to control display of the characters not supported by the terminal or
+fonts. Display tables can change how a character is displayed, even
+if it is supported.
@end itemize
The usual display conventions apply even when there is a display
This buffer-local variable controls how control characters are
displayed. If it is non-@code{nil}, they are displayed as a caret
followed by the character: @samp{^A}. If it is @code{nil}, they are
-displayed as a backslash followed by three octal digits: @samp{\001}.
+displayed as octal escapes: a backslash followed by three octal
+digits, as in @samp{\001}.
@end defopt
@defopt tab-width
@defopt visible-bell
This variable determines whether Emacs should flash the screen to
-represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
-is effective on graphical displays, and on text-only terminals
+represent a bell. Non-@code{nil} means yes, @code{nil} means no.
+This is effective on graphical displays, and on text terminals
provided the terminal's Termcap entry defines the visible bell
capability (@samp{vb}).
@end defopt
appropriate mirrored character in the reordered text. Lisp programs
can affect the mirrored display by changing this property. Again, any
such changes affect all of Emacs display.
+
+@node Glyphless Chars
+@section Glyphless Character Display
+@cindex glyphless characters
+
+ @dfn{Glyphless characters} are not displayed in the usual way when
+they appear in a buffer, but in some special way (e.g. as a box
+containing a hexadecimal code). These include characters that cannot
+be displayed with any available font (on a graphical display), or that
+cannot be encoded by the terminal's coding system (on a text
+terminal). Specific characters can also be defined to be glyphless.
+
+@defvar glyphless-char-display
+The value of this variable is a char-table that defines glyphless
+characters and how they are displayed. If an entry is @code{nil}, the
+corresponding character is displayed in its usual way. Otherwise, an
+entry should be one of the following display methods:
+
+@table @asis
+@item @code{zero-width}
+Don't display the character.
+
+@item @code{thin-space}
+Display a thin space, 1-pixel wide on graphical displays, or
+1-character wide on text terminals.
+
+@item @code{empty-box}
+Display an empty box.
+
+@item @code{hex-code}
+Display a box containing the Unicode codepoint of the character, in
+hexadecimal notation.
+
+@item an @acronym{ASCII} string
+Display a box containing that string.
+@end table
+
+@noindent
+Except for @code{zero-width}, these methods display using the
+@code{glyphless-char} face.
+
+An entry can also be a cons cell @code{(@var{graphical}
+. @var{text})}, where @var{graphical} and @var{text} are the display
+methods on graphical displays and text terminals respectively.
+
+The char-table has one extra slot, which determines how to display any
+character that cannot be displayed with any available font, or cannot
+be encoded by the terminal's coding system. Its value should be one
+of the above display methods, except @code{zero-width} or a cons cell.
+@end defvar
+
+@defopt glyphless-char-display-control
+This user option provides a convenient way to set
+@code{glyphless-char-display} for groups of similar characters. It
+takes effect via a custom @code{:set} function (@pxref{Variable
+Definitions}), which update @code{glyphless-char-display}.
+
+Its value should be an alist of elements @code{(@var{group}
+. @var{method})}, where @var{group} is a symbol specifying a group of
+characters, and @var{method} is a symbol specifying how to display
+them.
+
+@var{group} should be one of the following:
+
+@table @code
+@item c0-control
+@acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
+excluding the newline and tab characters (normally displayed as escape
+sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
+emacs, The GNU Emacs Manual}).
+
+@item c1-control
+Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
+@code{U+009F} (normally displayed as octal escape sequences like
+@samp{\230}).
+
+@item format-control
+Characters of Unicode General Category `Cf', such as @samp{U+200E}
+(Left-to-Right Mark), but excluding characters that have graphic
+images, such as @samp{U+00AD} (Soft Hyphen).
+
+@item no-font
+Characters for there is no suitable font, or which cannot be encoded
+by the terminal's coding system.
+@end table
+
+@c FIXME: this can also be `acronym', but that's not currently
+@c completely implemented; it applies only to the format-control
+@c group, and only works if the acronym is in `char-acronym-table'.
+The @var{method} symbol should be one of @code{zero-width},
+@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
+the same meanings as in @code{glyphless-char-display}, above.
+@end defopt