-@c -*-texinfo-*-
+@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
@cindex @samp{\} in display
When a line of text extends beyond the right edge of a window, Emacs
-can @dfn{continue} the line (make it ``wrap'' to the next screen
+can @dfn{continue} the line (make it wrap to the next screen
line), or @dfn{truncate} the line (limit it to one screen line). The
additional screen lines used to display a long text line are called
@dfn{continuation} lines. Continuation is not the same as filling;
indicate truncated and continued lines (@pxref{Fringes}). On a text
terminal, a @samp{$} in the rightmost column of the window indicates
truncation; a @samp{\} on the rightmost column indicates a line that
-``wraps''. (The display table can specify alternate characters to use
+wraps. (The display table can specify alternate characters to use
for this; @pxref{Display Tables}).
@defopt truncate-lines
@defun message format-string &rest arguments
This function displays a message in the echo area.
@var{format-string} is a format string, and @var{arguments} are the
-objects for its format specifications, like in the @code{format}
+objects for its format specifications, like in the @code{format-message}
function (@pxref{Formatting Strings}). The resulting formatted string
is displayed in the echo area; if it contains @code{face} text
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.
+
In batch mode, the message is printed to the standard error stream,
followed by a newline.
+When @code{inhibit-message} is non-@code{nil}, no message will be displayed
+in the echo area, it will only be logged to @samp{*Messages*}.
+
If @var{format-string} is @code{nil} or the empty string,
@code{message} clears the echo area; if the echo area has been
expanded automatically, this brings it back to its normal size. If
@example
@group
-(message "Minibuffer depth is %d."
- (minibuffer-depth))
- @print{} Minibuffer depth is 0.
-@result{} "Minibuffer depth is 0."
+(message "Reverting `%s'..." (buffer-name))
+ @print{} Reverting ‘subr.el’...
+@result{} "Reverting ‘subr.el’..."
@end group
@group
---------- Echo Area ----------
-Minibuffer depth is 0.
+Reverting ‘subr.el’...
---------- Echo Area ----------
@end group
@end example
To automatically display a message in the echo area or in a pop-buffer,
depending on its size, use @code{display-message-or-buffer} (see below).
+
+@strong{Warning:} If you want to use your own string as a message
+verbatim, don't just write @code{(message @var{string})}. If
+@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
+reformatted, with undesirable results. Instead, use @code{(message
+"%s" @var{string})}.
@end defun
+@defvar inhibit-message
+When this variable is non-@code{nil}, @code{message} and related functions
+will not use the Echo Area to display messages.
+@end defvar
+
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
@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
When this progress reporter is subsequently used, it will display
@var{message} in the echo area, followed by progress percentage.
@var{message} is treated as a simple string. If you need it to depend
-on a filename, for instance, use @code{format} before calling this
+on a filename, for instance, use @code{format-message} before calling this
function.
The arguments @var{min-value} and @var{max-value} should be numbers
standing for the starting and final states of the operation. For
-instance, an operation that ``scans'' a buffer should set these to the
+instance, an operation that scans a buffer should set these to the
results of @code{point-min} and @code{point-max} correspondingly.
@var{max-value} should be greater than @var{min-value}.
@defun progress-reporter-done reporter
This function should be called when the operation is finished. It
-prints the message of @var{reporter} followed by word ``done'' in the
+prints the message of @var{reporter} followed by word @samp{done} in the
echo area.
You should always call this function and not hope for
-@code{progress-reporter-update} to print ``100%''. Firstly, it may
+@code{progress-reporter-update} to print @samp{100%}. Firstly, it may
never print it, there are many good reasons for this not to happen.
-Secondly, ``done'' is more explicit.
+Secondly, @samp{done} is more explicit.
@end defun
@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.
- A ``question followed by an answer'' means two messages like the
+ A question followed by an answer has two messages like the
ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
and the second is @samp{@var{question}...@var{answer}}. The first
message conveys no additional information beyond what's in the second,
so logging the second message discards the first from the log.
- A ``series of progress messages'' means successive messages like
+ A series of progress messages has successive messages like
those produced by @code{make-progress-reporter}. They have the form
@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
time, while @var{how-far} varies. Logging each message in the series
@end defun
@defun lwarn type level message &rest args
-This function reports a warning using the value of @code{(format
+This function reports a warning using the value of @code{(format-message
@var{message} @var{args}...)} as the message in the @file{*Warnings*}
buffer. In other respects it is equivalent to @code{display-warning}.
@end defun
@defun warn message &rest args
-This function reports a warning using the value of @code{(format
+This function reports a warning using the value of @code{(format-message
@var{message} @var{args}...)} as the message, @code{(emacs)} as the
type, and @code{:warning} as the severity level. It exists for
compatibility only; we recommend not using it, because you should
these affect the display of the text within the overlay.
@cindex scalability of overlays
+@cindex overlays, scalability
The visual effect of an overlay is the same as of the corresponding
text property (@pxref{Text Properties}). However, due to a different
implementation, overlays generally don't scale well (many operations
markers. If @var{buffer} is omitted, the overlay is created in the
current buffer.
+@cindex empty overlay
+@cindex overlay, empty
+An overlay whose @var{start} and @var{end} specify the same buffer
+position is known as @dfn{empty}. A non-empty overlay can become
+empty if the text between its @var{start} and @var{end} is deleted.
+When that happens, the overlay is by default not deleted, but you can
+cause it to be deleted by giving it the @samp{evaporate} property
+(@pxref{Overlay Properties, evaporate property}).
+
The arguments @var{front-advance} and @var{rear-advance} specify the
marker insertion type for the start of the overlay and for the end of
the overlay, respectively. @xref{Marker Insertion Types}. If they
This is the only valid way to change the endpoints of an overlay. Do
not try modifying the markers in the overlay by hand, as that fails to
update other vital data structures and can cause some overlays to be
-``lost''.
+lost.
@end defun
@defun remove-overlays &optional start end name value
@end example
Emacs stores the overlays of each buffer in two lists, divided
-around an arbitrary ``center position''. One list extends backwards
+around an arbitrary center position. One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position. The center position can be anywhere
in the buffer.
@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
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it becomes empty (i.e., if its length becomes zero). If you give
-an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
-it immediately.
+an empty overlay (@pxref{Managing Overlays, empty overlay}) a
+non-@code{nil} @code{evaporate} property, that deletes it immediately.
+Note that, unless an overlay has this property, it will not be deleted
+when the text between its starting and ending positions is deleted
+from the buffer.
@item keymap
@cindex keymap of character (and overlays)
@defun overlays-in beg end
This function returns a list of the overlays that overlap the region
-@var{beg} through @var{end}. ``Overlap'' means that at least one
-character is contained within the overlay and also contained within the
-specified region; however, empty overlays are included in the result if
-they are located at @var{beg}, strictly between @var{beg} and @var{end},
-or at @var{end} when @var{end} denotes the position at the end of the
-buffer.
+@var{beg} through @var{end}. An overlay overlaps with a region if it
+contains one or more characters in the region; empty overlays
+(@pxref{Managing Overlays, empty overlay}) overlap if they are at
+@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end}
+when @var{end} denotes the position at the end of the buffer.
@end defun
@defun next-overlay-change pos
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)
The following function returns the size in pixels of text as if it were
displayed in a given window. This function is used by
-@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
-@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
-exactly as large as the text it contains.
+@code{fit-window-to-buffer} and @code{fit-frame-to-buffer}
+(@pxref{Resizing Windows}) to make a window exactly as large as the text
+it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
This function returns the size of the text of @var{window}'s buffer in
contents of the line, plus optional additional vertical line spacing
above or below the display line.
- The height of the line contents is the maximum height of any
-character or image on that display line, including the final newline
-if there is one. (A display line that is continued doesn't include a
-final newline.) That is the default line height, if you do nothing to
-specify a greater height. (In the most common case, this equals the
-height of the default frame font.)
+ The height of the line contents is the maximum height of any character
+or image on that display line, including the final newline if there is
+one. (A display line that is continued doesn't include a final
+newline.) That is the default line height, if you do nothing to specify
+a greater height. (In the most common case, this equals the height of
+the corresponding frame's default font, see @ref{Frame Font}.)
There are several ways to explicitly specify a larger line height,
either by specifying an absolute height for the display line, or by
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
@item
If the text lies within an overlay with a non-@code{nil} @code{face}
property, Emacs applies the face(s) specified by that property. If
-the overlay has a @code{mouse-face} property and the mouse is ``near
-enough'' to the overlay, Emacs applies the face or face attributes
+the overlay has a @code{mouse-face} property and the mouse is near
+enough to the overlay, Emacs applies the face or face attributes
specified by the @code{mouse-face} property instead. @xref{Overlay
Properties}.
functions instead of setting @code{face-remapping-alist} directly, to
avoid trampling on remappings applied elsewhere. These functions are
intended for buffer-local remappings, so they all make
-@code{face-remapping-alist} buffer-local as a side-effect. They manage
+@code{face-remapping-alist} buffer-local as a side-effect. They manage
@code{face-remapping-alist} entries of the form
@example
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
-The return value is a Lisp object that serves as a ``cookie''; you can
+The return value is a Lisp object that serves as a cookie; you can
pass this object as an argument to @code{face-remap-remove-relative}
if you need to remove the remapping later.
@example
-;; Remap the `escape-glyph' face into a combination
-;; of the `highlight' and `italic' faces:
+;; Remap the 'escape-glyph' face into a combination
+;; of the 'highlight' and 'italic' faces:
(face-remap-add-relative 'escape-glyph 'highlight 'italic)
-;; Increase the size of the `default' face by 50%:
+;; Increase the size of the 'default' face by 50%:
(face-remap-add-relative 'default :height 1.5)
@end example
@end defun
often a good idea to use certain existing faces or inherit from them,
rather than defining entirely new faces. This way, if other users
have customized the basic faces to give Emacs a certain look, your
-program will ``fit in'' without additional customization.
+program will fit in without additional customization.
Some of the basic faces defined in Emacs are listed below. In
addition to these, you might want to make use of the Font Lock faces
unspecified (and so given by @code{default}).
@item shadow
-For ``dimmed out'' text. For example, it is used for the ignored
+For dimmed-out text. For example, it is used for the ignored
part of a filename in the minibuffer (@pxref{Minibuffer File,,
Minibuffers for File Names, emacs, The GNU Emacs Manual}).
@item link
@itemx link-visited
For clickable text buttons that send the user to a different
-buffer or ``location''.
+buffer or location.
@item highlight
For stretches of text that should temporarily stand out. For example,
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
character codes. An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can. Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
-when you specify the ``font'' for a frame or a face. Here is
+when you specify the font for a frame or a face. Here is
information about defining a fontset under Lisp program control.
@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
@defun set-fontset-font name character font-spec &optional frame add
This function modifies the existing fontset @var{name} to use the font
-matching with @var{font-spec} for the character @var{character}.
+matching with @var{font-spec} for the specified @var{character}.
If @var{name} is @code{nil}, this function modifies the fontset of the
selected frame or that of @var{frame} if @var{frame} is not
If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
-@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
-@var{from} and @var{to} are character codepoints. In that case, use
-@var{font-spec} for all characters in the range @var{from} and @var{to}
-(inclusive).
+In addition to specifying a single codepoint, @var{character} may be a
+cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are
+character codepoints. In that case, use @var{font-spec} for all the
+characters in the range @var{from} and @var{to} (inclusive).
@var{character} may be a charset. In that case, use
@var{font-spec} for all character in the charsets.
@var{character} may be a script name. In that case, use
@var{font-spec} for all character in the charsets.
+@var{font-spec} may be a font-spec object created by the function
+@code{font-spec} (@pxref{Low-Level Font}).
+
@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
@var{font-spec} may be a font name string.
+@var{font-spec} may be @code{nil}, which explicitly specifies that
+there's no font for the specified @var{character}. This is useful,
+for example, to avoid expensive system-wide search for fonts for
+characters that have no glyphs, like those from the Unicode Private
+Use Area (PUA).
+
The optional argument @var{add}, if non-@code{nil}, specifies how to
add @var{font-spec} to the font specifications previously set. If it
is @code{prepend}, @var{font-spec} is prepended. If it is
@item :script
The script that the font must support (a symbol).
+@item :lang
+The language that the font should support. The value should be a
+symbol whose name is a two-letter ISO-639 language name. On X, the
+value is matched against the ``Additional Style'' field of the XLFD
+name of a font, if it is non-empty. On MS-Windows, fonts matching the
+spec are required to support codepages needed for the language.
+Currently, only a small set of CJK languages is supported with this
+property: @samp{ja}, @samp{ko}, and @samp{zh}.
+
@item :otf
@cindex OpenType font
The font must be an OpenType font that supports these OpenType
maximum length of the returned list. The optional argument
@var{prefer}, if non-@code{nil}, should be another font spec, which is
used to control the order of the returned list; the returned font
-entities are sorted in order of decreasing ``closeness'' to that font
+entities are sorted in order of decreasing closeness to that font
spec.
@end defun
If you call @code{set-face-attribute} and pass a font spec, font
entity, or font name string as the value of the @code{:font}
-attribute, Emacs opens the best ``matching'' font that is available
+attribute, Emacs opens the best matching font that is available
for display. It then stores the corresponding font object as the
actual value of the @code{:font} attribute for that face.
@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
@cindex right dividers
@cindex bottom dividers
-Window dividers are bars drawn between a frame's windows. A ``right''
+Window dividers are bars drawn between a frame's windows. A right
divider is drawn between a window and any adjacent windows on the right.
Its width (thickness) is specified by the frame parameter
-@code{right-divider-width}. A ``bottom'' divider is drawn between a
+@code{right-divider-width}. A bottom divider is drawn between a
window and adjacent windows on the bottom or the echo area. Its width
is specified by the frame parameter @code{bottom-divider-width}. In
either case, specifying a width of zero means to not draw such dividers.
@xref{Layout Parameters}.
- Technically, a right divider ``belongs'' to the window on its left,
+ Technically, a right divider belongs to the window on its left,
which means that its width contributes to the total width of that
-window. A bottom divider ``belongs'' to the window above it, which
+window. A bottom divider belongs to the window above it, which
means that its width contributes to the total height of that window.
@xref{Window Sizes}. When a window has both, a right and a bottom
-divider, the bottom divider ``prevails''. This means that a bottom
+divider, the bottom divider prevails. This means that a bottom
divider is drawn over the full total width of its window while the right
divider ends above the bottom divider.
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
display specifications make most other display specifications
irrelevant, since those don't apply to the replacement.
- For replacing display specifications, ``the text that has the
-property'' means all the consecutive characters that have the same
+ For replacing display specifications, @dfn{the text that has the
+property} means all the consecutive characters that have the same
Lisp object as their @code{display} property; these characters are
replaced as a single unit. If two characters have different Lisp
objects as their @code{display} properties (i.e., objects which are
@item :relative-width @var{factor}
Specifies that the width of the stretch should be computed from the
first character in the group of consecutive characters that have the
-same @code{display} property. The space width is the width of that
-character, multiplied by @var{factor}.
+same @code{display} property. The space width is the pixel width of
+that character, multiplied by @var{factor}. (On text-mode terminals,
+the ``pixel width'' of a character is usually 1, but it could be more
+for TABs and double-width CJK characters.)
@item :align-to @var{hpos}
Specifies that the space should be wide enough to reach @var{hpos}.
@table @asis
@item @code{(+ @var{n})}
@c FIXME: Add an index for "step"? --xfq
-This means to use a font that is @var{n} steps larger. A ``step'' is
+This means to use a font that is @var{n} steps larger. A @dfn{step} is
defined by the set of available fonts---specifically, those that match
what was otherwise specified for this text, in all attributes except
height. Each size for which a suitable font is available counts as
faces used for the text.
@end table
-@c We put all the `@code{(when ...)}' on one line to encourage
+@c We put all the '@code{(when ...)}' on one line to encourage
@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
@c was at eol; the info file ended up w/ two spaces rendered after it.
You can make any display specification conditional. To do that,
* 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.
Specifies the Laplace edge detection algorithm, which blurs out small
differences in color while highlighting larger differences. People
sometimes consider this useful for displaying the image for a
-``disabled'' button.
+disabled button.
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
@cindex edge detection, images
@end ifnottex
@item disabled
-Specifies transforming the image so that it looks ``disabled''.
+Specifies transforming the image so that it looks disabled.
@end table
@item :mask @var{mask}
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{insert-image}, but splits the image into @var{rows}x@var{cols}
equally sized slices.
-If an image is inserted ``sliced'', Emacs displays each slice as a
-separate image, and allow more intuitive scrolling up/down, instead of
+Emacs displays each slice as a
+separate image, and allows more intuitive scrolling up/down, instead of
jumping up/down the entire image when paging through a buffer that
displays (large) images.
@end defun
@cindex size of image
This function returns the size of an image as a pair
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
-specification. @var{pixels} non-@code{nil} means return sizes
-measured in pixels, otherwise return sizes measured in canonical
-character units (fractions of the width/height of the frame's default
-font). @var{frame} is the frame on which the image will be displayed.
-@var{frame} null or omitted means use the selected frame (@pxref{Input
-Focus}).
+specification. @var{pixels} non-@code{nil} means return sizes measured
+in pixels, otherwise return sizes measured in the default character size
+of @var{frame} (@pxref{Frame Font}). @var{frame} is the frame on which
+the image will be displayed. @var{frame} null or omitted means use the
+selected frame (@pxref{Input Focus}).
@end defun
@defvar max-image-size
@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
multiple frames for GIF, TIFF, and certain ImageMagick formats such as
DJVM@.
-The frames can be used either to represent multiple ``pages'' (this is
+The frames can be used either to represent multiple pages (this is
usually the case with multi-frame TIFF files, for example), or to
create animation (usually the case with multi-frame GIF files).
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
specific tasks.
@defun define-button-type name &rest properties
-Define a `button type' called @var{name} (a symbol).
+Define a button type called @var{name} (a symbol).
The remaining arguments
form a sequence of @var{property value} pairs, specifying default
property values for buttons with this type (a button's type may be set
These are commands and functions for locating and operating on
buttons in an Emacs buffer.
-@code{push-button} is the command that a user uses to actually `push'
+@code{push-button} is the command that a user uses to actually push
a button, and is bound by default in the button itself to @key{RET}
and to @key{mouse-2} using a local keymap in the button's overlay or
text properties. Commands that are useful outside the buttons itself,
The Ewoc package constructs buffer text that represents a structure
of Lisp objects, and updates the text to follow changes in that
structure. This is like the ``view'' component in the
-``model/view/controller'' design paradigm. Ewoc means ``Emacs's
+``model--view--controller'' design paradigm. Ewoc means ``Emacs's
Widget for Object Collections''.
An @dfn{ewoc} is a structure that organizes information required to
@noindent
You can also use, as the data element value, a Lisp object (list or
-vector) that is a container for the ``real'' value, or an index into
+vector) that is a container for the real value, or an index into
some other structure. The example (@pxref{Abstract Display Example})
uses the latter approach.
the footer and every node's textual description. If @var{nosep}
is non-@code{nil}, no newline is inserted. This may be useful for
displaying an entire ewoc on a single line, for example, or for
-making nodes ``invisible'' by arranging for @var{pretty-printer}
+making nodes invisible by arranging for @var{pretty-printer}
to do nothing for those nodes.
An ewoc maintains its text in the buffer that is current when
@subsection Abstract Display Example
Here is a simple example using functions of the ewoc package to
-implement a ``color components display'', an area in a buffer that
+implement a @dfn{color components} display, an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.
@end example
@cindex controller part, model/view/controller
- This example can be extended to be a ``color selection widget'' (in
-other words, the controller part of the ``model/view/controller''
+ This example can be extended to be a color selection widget (in
+other words, the ``controller'' part of the ``model--view--controller''
design paradigm) by defining commands to modify @code{colorcomp-data}
-and to ``finish'' the selection process, and a keymap to tie it all
+and to finish the selection process, and a keymap to tie it all
together conveniently.
@smallexample
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
-``line''.
+line.
- The display table also has six ``extra slots'' which serve special
+ The display table also has six @dfn{extra slots} which serve special
purposes. Here is a table of their meanings; @code{nil} in any slot
means to use the default for that slot, as stated below.
@defvar standard-display-table
The value of this variable is the standard display table, which is
used when Emacs is displaying a buffer in a window with neither a
-window display table nor a buffer display table defined. Its default
-is @code{nil}.
+window display table nor a buffer display table defined, or when Emacs
+is outputting text to the standard output or error streams. Although its
+default is typically @code{nil}, in an interactive session if the
+terminal cannot display curved quotes, its default maps curved quotes
+to ASCII approximations. @xref{Keys in Documentation}.
@end defvar
The @file{disp-table} library defines several functions for changing
hexadecimal notation.
@item an @acronym{ASCII} string
-Display a box containing that string.
+Display a box containing that string. The string should contain at
+most 6 @acronym{ASCII} characters.
@item a cons cell @code{(@var{graphical} . @var{text})}
Display with @var{graphical} on graphical displays, and with
@noindent
The @code{thin-space}, @code{empty-box}, @code{hex-code}, and
@acronym{ASCII} string display methods are drawn with the
-@code{glyphless-char} face.
+@code{glyphless-char} face. On text terminals, a box is emulated by
+square brackets, @samp{[]}.
The char-table has one extra slot, which determines how to display any
character that cannot be displayed with any available font, or cannot
@samp{\230}).
@item format-control
-Characters of Unicode General Category `Cf', such as @samp{U+200E}
+Characters of Unicode General Category [Cf], such as @samp{U+200E}
(Left-to-Right Mark), but excluding characters that have graphic
images, such as @samp{U+00AD} (Soft Hyphen).
by the terminal's coding system.
@end table
-@c FIXME: this can also be `acronym', but that's not currently
+@c FIXME: this can also be 'acronym', but that's not currently
@c completely implemented; it applies only to the format-control
-@c group, and only works if the acronym is in `char-acronym-table'.
+@c group, and only works if the acronym is in 'char-acronym-table'.
The @var{method} symbol should be one of @code{zero-width},
@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
the same meanings as in @code{glyphless-char-display}, above.
capability (@samp{vb}).
@end defopt
-@defvar 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
+@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
which is described in Annex #9 of the Unicode standard
(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full
Bidirectionality'' class implementation of the @acronym{UBA},
-consistent with the requirements of the Unicode Standard v7.0.
+consistent with the requirements of the Unicode Standard v8.0.
@defvar bidi-display-reordering
If the value of this buffer-local variable is non-@code{nil} (the
when two strings with bidirectional content are juxtaposed in a
buffer, or otherwise programmatically concatenated into a string of
text. A typical problematic case is when a buffer consists of
-sequences of text ``fields'' separated by whitespace or punctuation
+sequences of text fields separated by whitespace or punctuation
characters, like Buffer Menu mode or Rmail Summary Mode. Because the
punctuation characters used as separators have @dfn{weak
directionality}, they take on the directionality of surrounding text.