@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
@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
@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 to indicate buffer boundaries 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.
+ 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.
-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.
+ The standard symbols for fringe bitmaps are:
-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
empty-line question-mark
@end example
+@noindent
+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.
+@end defvar
+
@node Fringe Cursors
@subsection Fringe Cursors
@cindex fringe cursors
* 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 possible 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