diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 215 |
1 files changed, 210 insertions, 5 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 0d0ec671f7..93b84a0f20 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2094,7 +2094,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 @@ -3020,6 +3020,7 @@ attribute on this face (@pxref{Face Attributes}). @itemx bold-italic @itemx underline @itemx fixed-pitch +@itemx fixed-pitch-serif @itemx variable-pitch These have the attributes indicated by their names (e.g., @code{bold} has a bold @code{:weight} attribute), with all other attributes @@ -4772,6 +4773,7 @@ displayed (@pxref{Display Feature Testing}). * 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. @@ -5144,12 +5146,18 @@ specifying the bounding box of the PostScript image, analogous to the @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 the actual underlying image format. +To check for ImageMagick support, use the following: + +@lisp +(image-type-available-p 'imagemagick) +@end lisp + @defun imagemagick-types This function returns a list of image file extensions supported by the current ImageMagick installation. Each list element is a symbol @@ -5209,6 +5217,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 @@ -5223,6 +5241,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 @@ -5259,9 +5434,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}. @@ -5325,6 +5497,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}. @@ -5395,6 +5573,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 @@ -5504,6 +5689,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 |