X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/e87fbc07801a4ac291d335f0af957ca32cd26381..36906806ccfc0e53f1d8c365ab0d7151288b7833:/doc/lispref/display.texi diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 010dcb2fd1..1956ee5503 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -265,10 +265,13 @@ properties, it is displayed with the specified faces (@pxref{Faces}). The string is also added to the @file{*Messages*} buffer, but without text properties (@pxref{Logging Messages}). -In a format string containing single quotes, curved quotes @t{‘like -this’} and grave quotes @t{`like this'} work better than straight -quotes @t{'like this'}, as @code{message} typically formats every -straight quote as a curved closing quote. +The @code{text-quoting-style} variable controls what quotes are +generated; @xref{Keys in Documentation}. A call using a format like +@t{"Missing `%s'"} with grave accents and apostrophes typically +generates a message like @t{"Missing ‘foo’"} with matching curved +quotes. In contrast, a call using a format like @t{"Missing '%s'"} +with only apostrophes typically generates a message like @t{"Missing +’foo’"} with only closing curved quotes, an unusual style in English. In batch mode, the message is printed to the standard error stream, followed by a newline. @@ -3014,6 +3017,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 @@ -4766,6 +4770,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. @@ -5138,12 +5143,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 @@ -5203,6 +5214,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 @@ -5217,6 +5238,128 @@ 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 + +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 @@ -5253,9 +5396,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}. @@ -5319,6 +5459,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}. @@ -5389,6 +5535,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 @@ -5498,6 +5651,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 @@ -5820,7 +5993,7 @@ A string displayed by the Emacs tool-tip help system; by default, @item follow-link @kindex follow-link @r{(button property)} -The follow-link property, defining how a @key{Mouse-1} click behaves +The follow-link property, defining how a @key{mouse-1} click behaves on this button, @xref{Clickable Text}. @item button @@ -6007,7 +6180,7 @@ additionally available in the keymap stored in @code{button-buffer-map} as a parent keymap for its keymap. If the button has a non-@code{nil} @code{follow-link} property, and -@code{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click +@code{mouse-1-click-follows-link} is set, a quick @key{mouse-1} click will also activate the @code{push-button} command. @xref{Clickable Text}.