diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 156 |
1 files changed, 102 insertions, 54 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 4a647ef15a..199a20cc2c 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,8 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/display @node Display, System Interface, Processes, Top @@ -3214,7 +3212,9 @@ width from the window's frame. 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 once again in the -same window, to make the changes take effect. +same window, to make the changes take effect. A buffer that does not +specify values for these variables will use the default values +specified for the frame; see @ref{Layout Parameters}. @defun set-window-fringes window left &optional right outside-margins This function sets the fringe widths of window @var{window}. @@ -4046,6 +4046,7 @@ displayed (@pxref{Display Feature Testing}). * GIF Images:: Special features for GIF format. * TIFF Images:: Special features for TIFF format. * PostScript Images:: Special features for PostScript format. +* ImageMagick Images:: Special features available through ImageMagick. * 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. @@ -4059,10 +4060,12 @@ displayed (@pxref{Display Feature Testing}). Emacs can display a number of different image formats; some of them are supported only if particular support libraries are installed on -your machine. In some environments, Emacs can load image -libraries on demand; if so, the variable @code{image-library-alist} -can be used to modify the set of known names for these dynamic -libraries (though it is not possible to add new image formats). +your machine. In some environments, Emacs can load support libraries +on demand; if so, the variable @code{dynamic-library-alist} +(@pxref{Dynamic Libraries}) can be used to modify the set of known +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 @@ -4086,24 +4089,6 @@ 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 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 @@ -4229,14 +4214,14 @@ Laplace edge-detection currently uses a matrix of @tex $$\pmatrix{1 & 0 & 0 \cr 0& 0 & 0 \cr - 9 & 9 & -1 \cr}$$ + 0 & 0 & -1 \cr}$$ @end tex @end iftex @ifnottex @display (1 0 0 0 0 0 - 9 9 -1) + 0 0 -1) @end display @end ifnottex @@ -4470,6 +4455,60 @@ specifying the bounding box of the PostScript image, analogous to the @end example @end table +@node ImageMagick Images +@subsection ImageMagick Images +@cindex ImageMagick images +@cindex images, support for more formats + + If you build Emacs with ImageMagick (@url{http://www.imagemagick.org}) +support, you can use the ImageMagick library to load many image formats. + +@findex imagemagick-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}. + +@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 +JPEG files, add @code{JPG} to this list. + +@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. + +Images loaded with ImageMagick support a few new display specifications: + +@table @code +@item :width, :height +The @code{:width} and @code{:height} keywords are used for scaling the +image. If only one of them is specified, the other one will be +calculated so as to preserve the aspect ratio. If both are specified, +aspect ratio may not be preserved. + +@item :rotation +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). +@end table + + @node Other Image Types @subsection Other Image Types @cindex PBM @@ -4735,29 +4774,35 @@ cache, it can always be displayed, even if the value of efficiently. When Emacs displays an image, it searches the image cache for an existing image specification @code{equal} to the desired specification. If a match is found, the image is displayed from the -cache; otherwise, Emacs loads the image normally. - - Occasionally, you may need to tell Emacs to refresh the images -associated with a given image specification. For example, suppose you -display an image using a specification that contains a @code{:file} -property. The image is automatically cached, and subsequent displays -of that image, with the same image specification, will use the image -cache. If the image file changes in the meantime, Emacs would be -displaying the old version of the image. In such a situation, you can -``refresh'' the image by calling @code{image-refresh}. - - In Emacs' current implementation, each graphical terminal possesses -an image cache, which is shared by all the frames on that terminal +cache. Otherwise, Emacs loads the image normally. + +@defun image-flush spec &optional frame +This function removes the image with specification @var{spec} from the +image cache of frame @var{frame}. Image specifications are compared +using @code{equal}. If @var{frame} is @code{nil}, it defaults to the +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 +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. - -@defun image-refresh spec &optional frame -This function refreshes any images with image specifications -@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is -@code{nil}, it defaults to the selected frame. If @var{frame} is -@code{t}, the refresh is applied to all existing frames. @end defun + One use for @code{image-flush} is to tell Emacs about a change in an +image file. If an image specification contains a @code{:file} +property, the image is cached based on the file's contents when the +image is first displayed. Even if the file subsequently changes, +Emacs continues displaying the old version of the image. Calling +@code{image-flush} flushes the image from the cache, forcing Emacs to +re-read the file the next time it needs to display that image. + + Another use for @code{image-flush} is for memory conservation. If +your Lisp program creates a large number of temporary images over a +period much shorter than @code{image-cache-eviction-delay} (see +below), you can opt to flush unused images yourself, instead of +waiting for Emacs to do it automatically. + @defun clear-image-cache &optional filter This function clears an image cache, removing all the images stored in it. If @var{filter} is omitted or @code{nil}, it clears the cache for @@ -4773,9 +4818,12 @@ period of time, Emacs removes it from the cache and frees the associated memory. @defvar image-cache-eviction-delay -This variable specifies the number of seconds an image can remain in the -cache without being displayed. When an image is not displayed for this -length of time, Emacs removes it from the image cache. +This variable specifies the number of seconds an image can remain in +the cache without being displayed. When an image is not displayed for +this length of time, Emacs removes it from the image cache. + +Under some circumstances, if the number of images in the cache grows +too large, the actual eviction delay may be shorter than this. If the value is @code{nil}, Emacs does not remove images from the cache except when you explicitly clear it. This mode can be useful for @@ -5152,7 +5200,7 @@ element value into the current buffer. Typically, you define an ewoc with @code{ewoc-create}, and then pass the resulting ewoc structure to other functions in the Ewoc package to build nodes within it, and display it in the buffer. Once it is -displayed in the buffer, other functions determine the correspondance +displayed in the buffer, other functions determine the correspondence between buffer positions and nodes, move point from one node's textual representation to another, and so forth. @xref{Abstract Display Functions}. @@ -5537,9 +5585,9 @@ digit characters representing the character code in octal. (A display table can specify a glyph to use instead of @samp{\}.) @item -Multibyte character codes above 256 are displayed as themselves, or as a -question mark or empty box if the terminal cannot display that -character. +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. @end itemize The usual display conventions apply even when there is a display |