diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 242 |
1 files changed, 206 insertions, 36 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index fbdc574c658..945a701fcb2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2101,7 +2101,7 @@ is equivalent to a Lisp symbol with the same name.}. Named faces are defined using the @code{defface} macro (@pxref{Defining Faces}). Emacs comes with several standard named faces (@pxref{Basic Faces}). - Many parts of Emacs required named faces, and do not accept + Many parts of Emacs require named faces, and do not accept anonymous faces. These include the functions documented in @ref{Attribute Functions}, and the variable @code{font-lock-keywords} (@pxref{Search-based Fontification}). Unless otherwise stated, we @@ -4779,8 +4779,8 @@ displayed (@pxref{Display Feature Testing}). * Image Descriptors:: How to specify an image for use in @code{:display}. * XBM Images:: Special features for XBM format. * XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. * ImageMagick Images:: Special features available through ImageMagick. +* SVG Images:: Creating and manipulating SVG images. * 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. @@ -4803,12 +4803,12 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. Furthermore, if you build Emacs with ImageMagick @@ -5121,39 +5121,12 @@ the name of a color as it appears in the image file, and @var{color} specifies the actual color to use for displaying that name. @end table -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@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 support, you can use the + If your Emacs build has ImageMagick support, you can use the ImageMagick library to load many image formats (@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol for images loaded via ImageMagick is @code{imagemagick}, regardless of @@ -5224,6 +5197,16 @@ and if @code{:height} is set it will have precedence over wish. @code{:max-width} and @code{:max-height} will always preserve the aspect ratio. +@item :scale @var{scale} +This should be a number, where values higher than 1 means to increase +the size, and lower means to decrease the size. For instance, a value +of 0.25 will make the image a quarter size of what it originally was. +If the scaling makes the image larger than specified by +@code{:max-width} or @code{:max-height}, the resulting size will not +exceed those two values. If both @code{:scale} and +@code{:height}/@code{:width} are specified, the height/width will be +adjusted by the specified scaling factor. + @item :format @var{type} The value, @var{type}, should be a symbol specifying the type of the image data, as found in @code{image-format-suffixes}. This is used @@ -5238,6 +5221,163 @@ Specifies a rotation angle in degrees. @xref{Multi-Frame Images}. @end table +@node SVG Images +@subsection SVG Images +@cindex SVG images + +SVG (Scalable Vector Graphics) is an XML format for specifying images. +If your Emacs build has with SVG support, you can create and manipulate +these images with the following commands. + +@defun svg-create width height &rest args +Create a new, empty SVG image with the specified dimensions. +@var{args} is an argument plist with you can specify following: + +@table @code +@item :stroke-width +The default width (in pixels) of any lines created. + +@item :stroke +The default stroke color on any lines created. +@end table + +This function returns an SVG structure, and all the following commands +work on that structure. +@end defun + +@defun svg-gradient svg id type stops +Create a gradient in @var{svg} with identifier @var{id}. @var{type} +specifies the gradient type, and can be either @code{linear} or +@code{radial}. @var{stops} is a list of percentage/color pairs. + +The following will create a linear gradient that goes from red at the +start, to green 25% of the way, to blue at the end: + +@lisp +(svg-gradient svg "gradient1" 'linear + '((0 . "red") (25 . "green") (100 . "blue"))) +@end lisp + +The gradient created (and inserted into the SVG object) can later be +used by all functions that create shapes. +@end defun + +All the following functions take an optional list of keyword +parameters that alter the various attributes from their default +values. Valid attributes include: + +@table @code +@item :stroke-width +The width (in pixels) of lines drawn, and outlines around solid +shapes. + +@item :stroke-color +The color of lines drawn, and outlines around solid shapes. + +@item :fill-color +The color used for solid shapes. + +@item :id +The identified of the shape. + +@item :gradient +If given, this should be the identifier of a previously defined +gradient object. +@end table + +@defun svg-rectangle svg x y width height &rest args +Add a rectangle to @var{svg} where the upper left corner is at +position @var{x}/@var{y} and is of size @var{width}/@var{height}. + +@lisp +(svg-rectangle svg 100 100 500 500 :gradient "gradient1") +@end lisp +@end defun + +@defun svg-circle svg x y radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} +and the radius is @var{radius}. +@end defun + +@defun svg-ellipse svg x y x-radius y-radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} and +the horizontal radius is @var{x-radius} and the vertical radius is +@var{y-radius}. +@end defun + +@defun svg-line svg x1 y1 x2 y2 &rest args +Add a line to @var{svg} that starts at @var{x1}/@var{y1} and extends +to @var{x2}/@var{y2}. +@end defun + +@defun svg-polyline svg points &rest args +Add a multiple segment line to @var{svg} that goes through +@var{points}, which is a list of X/Y position pairs. + +@lisp +(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100)) + :stroke-color "green") +@end lisp +@end defun + +@defun svg-polygon svg points &rest args +Add a polygon to @var{svg} where @var{points} is a list of X/Y pairs +that describe the outer circumference of the polygon. + +@lisp +(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90)) + :stroke-color "blue" :fill-color "red"") +@end lisp +@end defun + +@defun svg-text svg text &rest args +Add a text to @var{svg}. + +@lisp +(svg-text + svg "This is a text" + :font-size "40" + :font-weight "bold" + :stroke "black" + :fill "white" + :font-family "impact" + :letter-spacing "4pt" + :x 300 + :y 400 + :stroke-width 1) +@end lisp +@end defun + +@defun svg-embed svg image image-type datap &rest args +Add an embedded (raster) image to @var{svg}. If @var{datap} is +@code{nil}, @var{IMAGE} should be a file name; if not, it should be a +binary string containing the image data. @var{image-type} should be a +@acronym{MIME} image type, for instance @samp{"image/jpeg"}. + +@lisp +(svg-embed svg "~/rms.jpg" "image/jpeg" nil + :width "100px" :height "100px" + :x "50px" :y "75px") +@end lisp +@end defun + +@defun svg-remove svg id +Remove the element with identifier @code{id} from the @code{svg}. +@end defun + +Finally, the @code{svg-image} takes an SVG object as its parameter and +returns an image object suitable for use in functions like +@code{insert-image}. Here's a complete example that creates and +inserts an image with a circle: + +@lisp +(let ((svg (svg-create 400 400 :stroke-width 10))) + (svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue"))) + (svg-circle svg 200 200 100 :gradient "gradient1" :stroke-color "green") + (insert-image (svg-image svg))) +@end lisp + + @node Other Image Types @subsection Other Image Types @cindex PBM @@ -5274,9 +5414,6 @@ Image type @code{jpeg}. @item PNG Image type @code{png}. -@item SVG -Image type @code{svg}. - @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. @@ -5340,6 +5477,12 @@ If none of the alternatives will work, then @var{symbol} is defined as @code{nil}. @end defmac +@defun image-property image property +Return the value of @var{property} in @var{image}. Properties can be +set by using @code{setf}. Setting a property to @code{nil} will +remove the property from the image. +@end defun + @defun find-image specs This function provides a convenient way to find an image satisfying one of a list of image specifications @var{specs}. @@ -5410,6 +5553,13 @@ Here is an example of using @code{image-load-path-for-library}: @end example @end defun +@vindex image-scaling-factor +Images are automatically scaled when created based on the +@code{image-scaling-factor} variable. The value is either a floating +point number (where numbers higher than 1 means to increase the size +and lower means to shrink the size), or the symbol @code{auto}, which +will compute a scaling factor based on the font pixel size. + @node Showing Images @subsection Showing Images @cindex show image @@ -5519,6 +5669,26 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +Images inserted with the insertion functions above also get a local +keymap installed in the text properties (or overlays) that span the +displayed image. This keymap defines the following commands: + +@table @kbd +@item + +Increase the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to increase the size by 40%. The default is 20%. + +@item - +Decrease the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to decrease the size by 40%. The default is 20%. + +@item r +Rotate the image by 90 degrees (@code{image-rotate}). + +@item o +Save the image to a file (@code{image-save}). +@end table + @node Multi-Frame Images @subsection Multi-Frame Images @cindex multi-frame images @@ -6969,7 +7139,7 @@ Emacs is displaying the frame on a character-based terminal. @defvar initial-window-system This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial +as a daemon, it does not create any initial frames, so @code{initial-window-system} is @code{nil}, except on MS-Windows, where it is still @code{w32}. @xref{Initial Options, daemon,, emacs, The GNU Emacs Manual}.) |