@c -*- mode: texinfo; coding: utf-8 -*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2016 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
+* Xwidgets:: Displaying native widgets in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted.
-@defun redraw-frame frame
-This function clears and redisplays frame @var{frame}.
+@defun redraw-frame &optional frame
+This function clears and redisplays frame @var{frame}. If @var{frame}
+is omitted or nil, it redraws the selected frame.
@end defun
Even more powerful is @code{redraw-display}:
newly arriving input.
@end defun
-@defvar pre-redisplay-function
-A function run just before redisplay. It is called with one argument,
-the set of windows to redisplay.
-@end defvar
-
Although @code{redisplay} tries immediately to redisplay, it does
not change how Emacs decides which parts of its frame(s) to redisplay.
By contrast, the following function adds certain windows to the
it waits for input, or when the function @code{redisplay} is called.
@end defun
+@defvar pre-redisplay-function
+A function run just before redisplay. It is called with one argument,
+the set of windows to be redisplayed. The set can be @code{nil},
+meaning only the selected window, or @code{t}, meaning all the
+windows.
+@end defvar
+
+@defvar pre-redisplay-functions
+This hook is run just before redisplay. It is called once in each
+window that is about to be redisplayed, with @code{current-buffer} set
+to the buffer displayed in that window.
+@end defvar
+
@node Truncation
@section Truncation
@cindex line wrapping
@code{message}.
@end defun
-@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+@defun display-message-or-buffer message &optional buffer-name action frame
This function displays the message @var{message}, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
where @var{message} is a string and displayed in the echo area, it is
not specified whether the contents are inserted into the buffer anyway.
-The optional arguments @var{not-this-window} and @var{frame} are as for
+The optional arguments @var{action} and @var{frame} are as for
@code{display-buffer}, and only used if a buffer is displayed.
@end defun
@item intangible
@kindex intangible @r{(overlay property)}
The @code{intangible} property on an overlay works just like the
-@code{intangible} text property. @xref{Special Properties}, for details.
+@code{intangible} text property. It is obsolete. @xref{Special
+Properties}, for details.
@item isearch-open-invisible
This property tells incremental search how to make an invisible overlay
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
+@vindex truncate-string-ellipsis
If @var{ellipsis} is non-@code{nil}, it should be a string which will
replace the end of @var{string} (including any padding) if it extends
beyond @var{width}, unless the display width of @var{string} is equal
to or less than the display width of @var{ellipsis}. If
@var{ellipsis} is non-@code{nil} and not a string, it stands for
-@code{"..."}.
+the value of the variable @code{truncate-string-ellipsis}.
@example
(truncate-string-to-width "\tab\t" 12 4)
return value is always specified, use a value of @code{default} for
@var{inherit}.
-@defun face-font face &optional frame
+@defun face-font face &optional frame character
This function returns the name of the font of face @var{face}.
+
+If the optional argument @var{frame} is specified, it returns the name
+of the font of @var{face} for that frame. If @var{frame} is omitted or
+@code{nil}, the selected frame is used. And, in this case, if the
+optional third argument @var{character} is supplied, it returns the font
+name used for @var{character}.
@end defun
@defun face-foreground face &optional frame inherit
highlighting (@pxref{Special Properties}).
@item match
-For text matching a search command.
+@itemx isearch
+@itemx lazy-highlight
+For text matching (respectively) permanent search matches, interactive
+search matches, and lazy highlighting other matches than the current
+interactive one.
@item error
@itemx warning
@end table
@end defun
+@cindex font information for layout
+The following four functions return size information about fonts used
+by various faces, allowing various layout considerations in Lisp
+programs. These functions take face remapping into consideration,
+returning information about the remapped face, if the face in question
+was remapped. @xref{Face Remapping}.
+
+@defun default-font-width
+This function returns the average width in pixels of the font used by
+the current buffer's default face.
+@end defun
+
+@defun default-font-height
+This function returns the height in pixels of the font used by the
+current buffer's default face.
+@end defun
+
+@defun window-font-width &optional window face
+This function returns the average width in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
+@defun window-font-height &optional window face
+This function returns the height in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
Dividers can be dragged with the mouse and are therefore useful for
adjusting the sizes of adjacent windows with the mouse. They also serve
to visually set apart adjacent windows when no scroll bars or mode lines
-are present. The following three faces allow to customize the
+are present. The following three faces allow the customization of the
appearance of dividers:
@table @code
* 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.
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
@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 you build Emacs 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
@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}.
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}.
The image is looked for in @code{image-load-path}.
@end defun
-@defvar image-load-path
+@defopt image-load-path
This variable's value is a list of locations in which to search for
image files. If an element is a string or a variable symbol whose
value is a string, the string is taken to be the name of a directory
@example
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
@end example
-@end defvar
+@end defopt
@defun image-load-path-for-library library image &optional path no-error
This function returns a suitable search path for images used by the
@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
@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
debugging.
@end defvar
+@node Xwidgets
+@section Embedded Native Widgets
+@cindex xwidget
+@cindex embedded widgets
+@cindex webkit browser widget
+
+ Emacs is able to display native widgets, such as GTK WebKit widgets,
+in Emacs buffers when it was built with the necessary support
+libraries and is running on a graphical terminal. To test whether
+Emacs supports display of embedded widgets, check that the
+@code{xwidget-internal} feature is available (@pxref{Named Features}).
+
+ To display an embedded widget in a buffer, you must first create an
+xwidget object, and then use that object as the display specifier
+in a @code{display} text or overlay property (@pxref{Display
+Property}).
+
+@defun make-xwidget beg end type title width height arguments &optional buffer
+This creates an xwidget object between @var{beg} and @var{end}, buffer
+positions in @var{buffer}, and returns the new object. If
+@var{buffer} is omitted or @code{nil}, it defaults to the current
+buffer. If @var{buffer} names a buffer that doesn't exist, it will be
+created. The @var{type} identifies the type of the xwidget component,
+it can be one of the following:
+
+@table @code
+@item webkit-osr
+The WebKit OSR (@dfn{on-stack replacement}) component.
+@end table
+
+The @var{width} and @var{height} arguments specify the widget size in
+pixels, and @var{title}, a string, specifies its title.
+@end defun
+
+@defun xwidgetp object
+This function returns @code{t} if @var{object} is an xwidget,
+@code{nil} otherwise.
+@end defun
+
+@defun xwidget-plist xwidget
+This function returns the property list of @var{xwidget}.
+@end defun
+
+@defun set-xwidget-plist xwidget plist
+This function replaces the property list of @var{xwidget} with a new
+property list given by @var{plist}.
+@end defun
+
+@defun xwidget-buffer xwidget
+This function returns the buffer of @var{xwidget}.
+@end defun
+
+@defun get-buffer-xwidgets buffer
+This function returns a list of xwidget objects associated with the
+@var{buffer}, which can be specified as a buffer object or a name of
+an existing buffer, a string. The value is @code{nil} if @var{buffer}
+contains no xwidgets.
+@end defun
+
+@defun xwidget-webkit-goto-uri xwidget uri
+This function browses the specified @var{uri} in the given
+@var{xwidget}. The @var{uri} is a string that specifies the name of a
+file or a URL. @c FIXME: What else can a URI specify in this context?
+@end defun
+
+@defun xwidget-webkit-execute-script xwidget script
+This function causes the browser widget specified by @var{xwidget} to
+execute the specified JavaScript @code{script}.
+@end defun
+
+@defun xwidget-webkit-execute-script-rv xwidget script &optional default
+This function executes the specified @var{script} like
+@code{xwidget-webkit-execute-script} does, but it also returns the
+script's return value as a string. If @var{script} doesn't return a
+value, this function returns @var{default}, or @code{nil} if
+@var{default} was omitted.
+@end defun
+
+@defun xwidget-webkit-get-title xwidget
+This function returns the title of @var{xwidget} as a string.
+@end defun
+
+@defun xwidget-resize xwidget width height
+This function resizes the specified @var{xwidget} to the size
+@var{width}x@var{height} pixels.
+@end defun
+
+@defun xwidget-size-request xwidget
+This function returns the desired size of @var{xwidget} as a list of
+the form @code{(@var{width} @var{height})}. The dimensions are in
+pixels.
+@end defun
+
+@defun xwidget-info xwidget
+This function returns the attributes of @var{xwidget} as a vector of
+the form @code{[@var{type} @var{title} @var{width} @var{height}]}.
+The attributes are usually determined by @code{make-xwidget} when the
+xwidget is created.
+@end defun
+
+@defun set-xwidget-query-on-exit-flag xwidget flag
+This function allows you to arrange that Emacs will ask the user for
+confirmation before exiting or before killing a buffer that has
+@var{xwidget} associated with it. If @var{flag} is non-@code{nil},
+Emacs will query the user, otherwise it will not.
+@end defun
+
+@defun xwidget-query-on-exit-flag xwidget
+This function returns the current setting of @var{xwidget}s
+query-on-exit flag, either @code{t} or @code{nil}.
+@end defun
+
@node Buttons
@section Buttons
@cindex buttons in buffers
capability (@samp{vb}).
@end defopt
-@defvar ring-bell-function
+@defopt ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ring the
bell. Its value should be a function of no arguments. If this is
non-@code{nil}, it takes precedence over the @code{visible-bell}
variable.
-@end defvar
+@end defopt
@node Window Systems
@section Window Systems