X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a3dcc84e76ab44bf0855a1392a7e0b9bde45e1c3..93137f94d8ae3632af0be31fd95b665ceb5a1245:/doc/lispref/display.texi diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 2032ecdc5b..d5870fd3ab 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ @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 @@ -193,10 +193,12 @@ a window, that forces truncation. @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 @@ -206,9 +208,11 @@ over the @code{wrap-prefix} variable. @xref{Special Properties}. @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 @@ -3363,54 +3367,48 @@ fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. @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 @@ -3424,6 +3422,16 @@ vertical-bar horizontal-bar 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 @@ -4126,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}). * 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 @@ -4143,12 +4152,10 @@ names for these dynamic libraries (though it is not possible to add 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}, @@ -4463,33 +4470,13 @@ specifies the actual color to use for displaying that name. @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 @@ -4498,10 +4485,10 @@ every 0.1 seconds. @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 @@ -4540,30 +4527,51 @@ specifying the bounding box of the PostScript image, analogous to the 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: @@ -4578,10 +4586,11 @@ aspect ratio may not be preserved. 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 @@ -4849,6 +4858,39 @@ cache, it can always be displayed, even if the value of @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