@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2013 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Display
@chapter Emacs Display
* Selective Display:: Hiding part of the buffer text (the old way).
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
-* Width:: How wide a character or string is on the screen.
+* Size of Displayed Text:: How large displayed text is.
* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
* Scroll Bars:: Controlling vertical scroll bars.
+* Window Dividers:: Separating windows visually.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
This variable has no effect when @code{redisplay-dont-pause} is
non-@code{nil} (the default).
+@end defvar
+
+@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
over the @code{line-prefix} variable. @xref{Special Properties}.
@end defvar
- If your buffer contains @emph{very} long lines, and you use
-continuation to display them, computing the continuation lines can
-make redisplay slow. The column computation and indentation functions
-also become slow. Then you might find it advisable to set
-@code{cache-long-scans} to @code{t}.
+@ignore
+ If your buffer contains only very short lines, you might find it
+advisable to set @code{cache-long-scans} to @code{nil}.
@defvar cache-long-scans
-If this variable is non-@code{nil}, various indentation and motion
-functions, and Emacs redisplay, cache the results of scanning the
-buffer, and consult the cache to avoid rescanning regions of the buffer
-unless they are modified.
+If this variable is non-@code{nil} (the default), various indentation
+and motion functions, and Emacs redisplay, cache the results of
+scanning the buffer, and consult the cache to avoid rescanning regions
+of the buffer unless they are modified.
-Turning on the cache slows down processing of short lines somewhat.
+Turning off the cache speeds up processing of short lines somewhat.
This variable is automatically buffer-local in every buffer.
@end defvar
+@end ignore
@node The Echo Area
@section The Echo Area
The first two arguments have the same meaning as for
@code{progress-reporter-update}. Optional @var{new-message} allows
-you to change the message of the @var{reporter}. Since this functions
+you to change the message of the @var{reporter}. Since this function
always updates the echo area, such a change will be immediately
presented to the user.
@end defun
Almost all the messages displayed in the echo area are also recorded
in the @file{*Messages*} buffer so that the user can refer back to
them. This includes all the messages that are output with
-@code{message}.
+@code{message}. By default, this buffer is read-only and uses the major
+mode @code{messages-buffer-mode}. Nothing prevents the user from
+killing the @file{*Messages*} buffer, but the next display of a message
+recreates it. Any Lisp code that needs to access the
+@file{*Messages*} buffer directly and wants to ensure that it exists
+should use the function @code{messages-buffer}.
+
+@defun messages-buffer
+This function returns the @file{*Messages*} buffer. If it does not
+exist, it creates it, and switches it to @code{messages-buffer-mode}.
+@end defun
@defopt message-log-max
This variable specifies how many lines to keep in the @file{*Messages*}
@defopt echo-keystrokes
This variable determines how much time should elapse before command
-characters echo. Its value must be an integer or floating point number,
-which specifies the
+characters echo. Its value must be a number, and specifies the
number of seconds to wait before echoing. If the user types a prefix
key (such as @kbd{C-x}) and then delays this many seconds before
continuing, the prefix key is echoed in the echo area. (Once echoing
@code{condition-case}, the user won't see the error message; it could
show the message to the user by reporting it as a warning.)
-@c FIXME: Why use ‘(bytecomp)’ instead of ‘'bytecomp’ or simply
-@c ‘bytecomp’ here? The parens are part of ‘warning-type-format’ but
+@c FIXME: Why use "(bytecomp)" instead of "'bytecomp" or simply
+@c "bytecomp" here? The parens are part of warning-type-format but
@c not part of the warning type. --xfq
@cindex warning type
Each warning has a @dfn{warning type} to classify it. The type is a
@vindex line-move-ignore-invisible
Ordinarily, functions that operate on text or move point do not care
-whether the text is invisible. The user-level line motion commands
-ignore invisible newlines if @code{line-move-ignore-invisible} is
-non-@code{nil} (the default), but only because they are explicitly
-programmed to do so.
-
- However, if a command ends with point inside or at the boundary of
+whether the text is invisible, they process invisible characters and
+visible characters alike. The user-level line motion commands,
+such as @code{next-line}, @code{previous-line}, ignore invisible
+newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the
+default), i.e., behave like these invisible newlines didn't exist in
+the buffer, but only because they are explicitly programmed to do so.
+
+ If a command ends with point inside or at the boundary of
invisible text, the main editing loop relocates point to one of the
two ends of the invisible text. Emacs chooses the direction of
relocation so that it is the same as the overall movement direction of
to the first visible character that follows the invisible text and then forward
one more character.
+ These @dfn{adjustments} of point that ended up in the middle of
+invisible text can be disabled by setting @code{disable-point-adjustment}
+to a non-@code{nil} value. @xref{Adjusting Point}.
+
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
this, the overlay should have a non-@code{nil}
hiding certain lines on the screen.
@cindex explicit selective display
- The first variant, explicit selective display, is designed for use
-in a Lisp program: it controls which lines are hidden by altering the
-text. This kind of hiding in some ways resembles the effect of the
-@code{invisible} property (@pxref{Invisible Text}), but the two
-features are different and do not work the same way.
+ The first variant, explicit selective display, was designed for use in a Lisp
+program: it controls which lines are hidden by altering the text. This kind of
+hiding is now obsolete; instead you can get the same effect with the
+@code{invisible} property (@pxref{Invisible Text}).
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
buffer and then present it to the user for perusal rather than for
editing. Many help commands use this feature.
-@defmac with-output-to-temp-buffer buffer-name forms@dots{}
-This function executes @var{forms} while arranging to insert any output
-they print into the buffer named @var{buffer-name}, which is first
-created if necessary, and put into Help mode. Finally, the buffer is
-displayed in some window, but not selected. (See the similar
-form @code{with-temp-buffer-window} below.)
-
-If the @var{forms} do not change the major mode in the output buffer,
-so that it is still Help mode at the end of their execution, then
-@code{with-output-to-temp-buffer} makes this buffer read-only at the
-end, and also scans it for function and variable names to make them
-into clickable cross-references. @xref{Docstring hyperlinks, , Tips
-for Documentation Strings}, in particular the item on hyperlinks in
+@defmac with-output-to-temp-buffer buffer-name body@dots{}
+This function executes the forms in @var{body} while arranging to insert
+any output they print into the buffer named @var{buffer-name}, which is
+first created if necessary, and put into Help mode. (See the similar
+form @code{with-temp-buffer-window} below.) Finally, the buffer is
+displayed in some window, but that window is not selected.
+
+If the forms in @var{body} do not change the major mode in the output
+buffer, so that it is still Help mode at the end of their execution,
+then @code{with-output-to-temp-buffer} makes this buffer read-only at
+the end, and also scans it for function and variable names to make them
+into clickable cross-references. @xref{Docstring hyperlinks, , Tips for
+Documentation Strings}, in particular the item on hyperlinks in
documentation strings, for more details.
-The string @var{buffer-name} specifies the temporary buffer, which
-need not already exist. The argument must be a string, not a buffer.
-The buffer is erased initially (with no questions asked), and it is
-marked as unmodified after @code{with-output-to-temp-buffer} exits.
+The string @var{buffer-name} specifies the temporary buffer, which need
+not already exist. The argument must be a string, not a buffer. The
+buffer is erased initially (with no questions asked), and it is marked
+as unmodified after @code{with-output-to-temp-buffer} exits.
@code{with-output-to-temp-buffer} binds @code{standard-output} to the
-temporary buffer, then it evaluates the forms in @var{forms}. Output
-using the Lisp output functions within @var{forms} goes by default to
+temporary buffer, then it evaluates the forms in @var{body}. Output
+using the Lisp output functions within @var{body} goes by default to
that buffer (but screen display and messages in the echo area, although
they are ``output'' in the general sense of the word, are not affected).
@xref{Output Functions}.
Several hooks are available for customizing the behavior
of this construct; they are listed below.
-The value of the last form in @var{forms} is returned.
+The value of the last form in @var{body} is returned.
@example
@group
is current, and the window it was displayed in is selected.
@end defvar
-@defmac with-temp-buffer-window buffer-or-name action quit-function forms@dots{}
-This macro is similar to @code{with-output-to-temp-buffer}.
-Like that construct, it executes @var{forms} while arranging to insert
-any output they print into the buffer named @var{buffer-or-name}.
-Finally, the buffer is displayed in some window, but not selected.
-Unlike @code{with-output-to-temp-buffer}, this does not switch to Help
-mode.
-
-The argument @var{buffer-or-name} specifies the temporary buffer.
-It can be either a buffer, which must already exist, or a string,
-in which case a buffer of that name is created if necessary.
-The buffer is marked as unmodified and read-only when
-@code{with-temp-buffer-window} exits.
+@defmac with-temp-buffer-window buffer-or-name action quit-function body@dots{}
+This macro is similar to @code{with-output-to-temp-buffer}. Like that
+construct, it executes @var{body} while arranging to insert any output
+it prints into the buffer named @var{buffer-or-name} and displays that
+buffer in some window. Unlike @code{with-output-to-temp-buffer},
+however, it does not automatically switch that buffer to Help mode.
+
+Like @code{with-output-to-temp-buffer} it neither makes the buffer
+specified by @var{buffer-or-name} current when executing @var{body}.
+@findex with-current-buffer-window
+The otherwise identical macro @code{with-current-buffer-window} can be
+used to execute @var{body} with that buffer current.
+
+The argument @var{buffer-or-name} specifies the temporary buffer. It
+can be either a buffer, which must already exist, or a string, in which
+case a buffer of that name is created, if necessary. The buffer is
+marked as unmodified and read-only when @code{with-temp-buffer-window}
+exits.
This macro does not call @code{temp-buffer-show-function}. Rather, it
passes the @var{action} argument to @code{display-buffer} in order to
display the buffer.
-The value of the last form in @var{forms} is returned, unless the
-argument @var{quit-function} is specified. In that case,
-it is called with two arguments: the window showing the buffer
-and the result of @var{forms}. The final return value is then
-whatever @var{quit-function} returns.
+The value of the last form in @var{body} is returned, unless the
+argument @var{quit-function} is specified. In that case, it is called
+with two arguments: the window showing the buffer and the result of
+@var{body}. The final return value is then whatever
+@var{quit-function} returns.
@vindex temp-buffer-window-setup-hook
@vindex temp-buffer-window-show-hook
Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each
-overlay. You should not make assumptions about which overlay will
-prevail when there is a conflict and they have the same priority.
+overlay. In case two overlays have the same priority value, and one
+is nested in the other, then the inner one will have priority over the
+outer one. If neither is nested in the other then you should not make
+assumptions about which overlay will prevail.
These functions read and set the properties of an overlay:
@table @code
@item priority
@kindex priority @r{(overlay property)}
-This property's value (which should be a non-negative integer number)
-determines the priority of the overlay. No priority, or @code{nil},
-means zero.
+This property's value determines the priority of the overlay.
+If you want to specify a priority value, use either @code{nil}
+(or zero), or a positive integer. Any other value has undefined behavior.
The priority matters when two or more overlays cover the same
character and both specify the same property; the one whose
override the face attributes of the lower priority @code{face}
property.
-Currently, all overlays take priority over text properties. Please
-avoid using negative priority values, as we have not yet decided just
-what they should mean.
+Currently, all overlays take priority over text properties.
+
+Note that Emacs sometimes uses non-numeric priority values for some of
+its internal overlays, so do not try to do arithmetic on the
+priority of an overlay (unless it is one that you created). If you
+need to put overlays in priority order, use the @var{sorted} argument
+of @code{overlays-at}. @xref{Finding Overlays}.
@item window
@kindex window @r{(overlay property)}
@node Finding Overlays
@subsection Searching for Overlays
-@defun overlays-at pos
-This function returns a list of all the overlays that cover the
-character at position @var{pos} in the current buffer. The list is in
-no particular order. An overlay contains position @var{pos} if it
-begins at or before @var{pos}, and ends after @var{pos}.
+@defun overlays-at pos &optional sorted
+This function returns a list of all the overlays that cover the character at
+position @var{pos} in the current buffer. If @var{sorted} is non-@code{nil},
+the list is in decreasing order of priority, otherwise it is in no particular
+order. An overlay contains position @var{pos} if it begins at or before
+@var{pos}, and ends after @var{pos}.
To illustrate usage, here is a Lisp function that returns a list of the
overlays that specify property @var{prop} for the character at point:
(point)))
@end smallexample
-@node Width
-@section Width
+@node Size of Displayed Text
+@section Size of Displayed Text
Since not all characters have the same width, these functions let you
check the width of a character. @xref{Primitive Indent}, and
@end example
@end defun
+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.
+
+@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
+pixels. @var{window} must be a live window and defaults to the selected
+one. The return value is a cons of the maximum pixel-width of any text
+line and the maximum pixel-height of all text lines.
+
+The optional argument @var{from}, if non-@code{nil}, specifies the first
+text position to consider and defaults to the minimum accessible
+position of the buffer. If @var{from} is @code{t}, it uses the minimum
+accessible position that is not a newline character. The optional
+argument @var{to}, if non-@code{nil}, specifies the last text position
+to consider and defaults to the maximum accessible position of the
+buffer. If @var{to} is @code{t}, it uses the maximum accessible
+position that is not a newline character.
+
+The optional argument @var{x-limit}, if non-@code{nil}, specifies the
+maximum pixel-width that can be returned. @var{x-limit} @code{nil} or
+omitted, means to use the pixel-width of @var{window}'s body
+(@pxref{Window Sizes}); this is useful when the caller does not intend
+to change the width of @var{window}. Otherwise, the caller should
+specify here the maximum width @var{window}'s body may assume. Text
+whose x-coordinate is beyond @var{x-limit} is ignored. Since
+calculating the width of long lines can take some time, it's always a
+good idea to make this argument as small as needed; in particular, if
+the buffer might contain long lines that will be truncated anyway.
+
+The optional argument @var{y-limit}, if non-@code{nil}, specifies the
+maximum pixel-height that can be returned. Text lines whose
+y-coordinate is beyond @var{y-limit} are ignored. Since calculating the
+pixel-height of a large buffer can take some time, it makes sense to
+specify this argument; in particular, if the caller does not know the
+size of the buffer.
+
+The optional argument @var{mode-and-header-line} @code{nil} or omitted
+means to not include the height of the mode- or header-line of
+@var{window} in the return value. If it is either the symbol
+@code{mode-line} or @code{header-line}, include only the height of that
+line, if present, in the return value. If it is @code{t}, include the
+height of both, if present, in the return value.
+@end defun
+
+
@node Line Height
@section Line Height
@cindex line height
lines in a frame, using the @code{line-spacing} frame parameter
(@pxref{Layout Parameters}). However, if the default value of
@code{line-spacing} is non-@code{nil}, it overrides the
-frame's @code{line-spacing} parameter. An integer value specifies the
-number of pixels put below lines. A floating point number specifies
+frame's @code{line-spacing} parameter. An integer specifies the
+number of pixels put below lines. A floating-point number specifies
the spacing relative to the frame's default line height.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
-buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines. A floating point number
+buffer-local @code{line-spacing} variable. An integer specifies
+the number of pixels put below lines. A floating-point number
specifies the spacing relative to the default frame line height. This
overrides line spacings specified for the frame.
The height of the font. In the simplest case, this is an integer in
units of 1/10 point.
-The value can also be a floating point number or a function, which
+The value can also be floating point or a function, which
specifies the height relative to an @dfn{underlying face}
-(@pxref{Displaying Faces}). If the value is a floating point number,
-that specifies the amount by which to scale the height of the
-underlying face. If the value is a function, that function is called
+(@pxref{Displaying Faces}). A floating-point value
+specifies the amount by which to scale the height of the
+underlying face. A function value is called
with one argument, the height of the underlying face, and returns the
height of the new face. If the function is passed an integer
argument, it must return an integer.
black-and-white displays, certain shades of gray are implemented by
stipple patterns.
+@item :distant-foreground
+Alternative foreground color, a string. This is like @code{:foreground}
+but the color is only used as a foreground when the background color is
+near to the foreground that would have been used. This is useful for
+example when marking text (i.e. the region face). If the text has a foreground
+that is visible with the region face, that foreground is used.
+If the foreground is near the region face background,
+@code{:distant-foreground} is used instead so the text is readable.
+
@item :background
Background color, a string. The value can be a system-defined color
name, or a hexadecimal color specification. @xref{Color Names}.
the values of the @code{:family}, @code{:foundry}, @code{:width},
@code{:height}, @code{:weight}, and @code{:slant} attributes.
+@cindex inheritance, for faces
@item :inherit
The name of a face from which to inherit attributes, or a list of face
names. Attributes from inherited faces are merged into the face like
@var{spec} should be a face spec, as described in the above
documentation for @code{defface}.
+This function also defines @var{face} as a valid face name if it is
+not already one, and (re)calculates its attributes on existing frames.
+
@cindex override spec @r{(for a face)}
The argument @var{spec-type} determines which spec to set. If it is
@code{nil} or @code{face-override-spec}, this function sets the
@dfn{override spec}, which overrides over all other face specs on
-@var{face}. If it is @code{face-defface-spec}, this function sets the
-default face spec (the same one set by @code{defface}). If it is
-@code{reset}, this function clears out all customization specs and
-override specs from @var{face} (in this case, the value of @var{spec}
-is ignored). Any other value of @var{spec-type} is reserved for
-internal use.
+@var{face}. If it is @code{customized-face} or @code{saved-face},
+this function sets the customized spec or the saved custom spec. If
+it is @code{face-defface-spec}, this function sets the default face
+spec (the same one set by @code{defface}). If it is @code{reset},
+this function clears out all customization specs and override specs
+from @var{face} (in this case, the value of @var{spec} is ignored).
+Any other value of @var{spec-type} is reserved for internal use.
@end defun
@node Attribute Functions
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
-This functions adds the face spec in @var{specs} as relative
+This function adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
expression in the list. For example,
@example
-(setq scalable-fonts-allowed '("muleindian-2$"))
+(setq scalable-fonts-allowed '("iso10646-1$"))
@end example
@noindent
-allows the use of scalable fonts with registry @code{muleindian-2}.
+allows the use of scalable fonts with registry @code{iso10646-1}.
@end defopt
@defvar face-font-rescale-alist
@item :size
The font size---either a non-negative integer that specifies the pixel
-size, or a floating point number that specifies the point size.
+size, or a floating-point number that specifies the point size.
@item :adstyle
Additional typographic style information for the font, such as
@xref{Fringe Bitmaps}.
@end ifnottex
-@c FIXME: I can't find the ‘fringes-indicator-alist’ variable. Maybe
-@c it should be ‘fringe-indicator-alist’ or ‘fringe-cursor-alist’? --xfq
+@c FIXME: I can't find the fringes-indicator-alist variable. Maybe
+@c it should be fringe-indicator-alist or fringe-cursor-alist? --xfq
When @code{fringe-cursor-alist} has a buffer-local value, and there is
no bitmap defined for a cursor type, the corresponding value from the
default value of @code{fringes-indicator-alist} is used.
@var{horizontal-type} is not actually meaningful.
@end defun
+@defun window-scroll-bar-width &optional window
+This function returns the width of @var{window}'s vertical scrollbar,
+in pixels. @var{window} must be a live window. If @var{window} is
+@code{nil} or omitted, it will be the selected window.
+@end defun
+
If you don't specify these values for a window with
@code{set-window-scroll-bars}, the buffer-local variables
@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
to use the value specified by the frame.
@end defvar
+@node Window Dividers
+@section Window Dividers
+@cindex window dividers
+@cindex right dividers
+@cindex bottom dividers
+
+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
+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,
+which means that its width contributes to the total width of that
+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 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
+appearance of dividers:
+
+@table @code
+@item window-divider
+When a divider is less than three pixels wide, it is drawn solidly with
+the foreground of this face. For larger dividers this face is used for
+the inner part only, excluding the first and last pixel.
+
+@item window-divider-first-pixel
+This is the face used for drawing the first pixel of a divider that is
+at least three pixels wide. To obtain a solid appearance, set this to
+the same value used for the @code{window-divider} face.
+
+@item window-divider-last-pixel
+This is the face used for drawing the last pixel of a divider that is at
+least three pixels wide. To obtain a solid appearance, set this to the
+same value used for the @code{window-divider} face.
+@end table
+
+You can get the sizes of the dividers of a specific window with the
+following two functions.
+
+@defun window-right-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s right divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is always zero for a rightmost window.
+@end defun
+
+@defun window-bottom-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s bottom divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is zero for the minibuffer window or a bottommost
+window on a minibuffer-less frame.
+@end defun
+
+
@node Display Property
@section The @code{display} Property
@cindex display specification
@table @code
@item :width @var{width}
-If @var{width} is an integer or floating point number, it specifies
+If @var{width} is a number, it specifies
that the space width should be @var{width} times the normal character
width. @var{width} can also be a @dfn{pixel width} specification
(@pxref{Pixel Specification}).
@table @code
@item :height @var{height}
Specifies the height of the space.
-If @var{height} is an integer or floating point number, it specifies
+If @var{height} is a number, it specifies
that the space height should be @var{height} times the normal character
height. The @var{height} may also be a @dfn{pixel height} specification
(@pxref{Pixel Specification}).
(a partial area) of the image to display. The elements @var{y} and
@var{x} specify the top left corner of the slice, within the image;
@var{width} and @var{height} specify the width and height of the
-slice. Integer values are numbers of pixels. A floating point number
+slice. Integers are numbers of pixels. A floating-point number
in the range 0.0--1.0 stands for that fraction of the width or height
of the entire image.
@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
defined by the set of available fonts---specifically, those that match
what was otherwise specified for this text, in all attributes except
``disabled'' button.
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
+@cindex edge detection, images
Specifies a general edge-detection algorithm. @var{matrix} must be
either a nine-element list or a nine-element vector of numbers. A pixel
at position @math{x/y} in the transformed image is computed from
image. @xref{Pointer Shape}, for available pointer shapes.
@item :map @var{map}
+@cindex image maps
This associates an image map of @dfn{hot spots} with this image.
An image map is an alist where each element has the format
ImageMagick entirely.
@end defopt
+@defvar image-format-suffixes
+This variable is an alist mapping image types to file name extensions.
+Emacs uses this in conjunction with the @code{:format} image property
+(see below) to give a hint to the ImageMagick library as to the type
+of an image. Each element has the form @code{(@var{type}
+@var{extension})}, where @var{type} is a symbol specifying an image
+content-type, and @var{extension} is a string that specifies the
+associated file name extension.
+@end defvar
+
Images loaded with ImageMagick support the following additional
image descriptor properties:
supports transparency. If the value is @code{nil}, it defaults to the
frame's background color.
-@item :width, :height
+@item :width @var{width}, :height @var{height}
The @code{:width} and @code{:height} keywords are used for scaling the
image. If only one of them is specified, the other one will be
calculated so as to preserve the aspect ratio. If both are specified,
aspect ratio may not be preserved.
-@item :max-width, :max-height
+@item :max-width @var{max-width}, :max-height @var{max-height}
The @code{:max-width} and @code{:max-height} keywords are used for
scaling if the size of the image of the image exceeds these values.
If @code{:width} is set it will have precedence over @code{max-width},
wish. @code{:max-width} and @code{:max-height} will always preserve
the aspect ratio.
-@item :format
-ImageMagick tries to auto-detect the image type, but it isn't always
-able to. By using @code{:format-type}, we can give ImageMagick a hint
-to try to help it. It's used in conjunction with the
-@code{image-format-suffixes} variable, which provides a mapping from
-content types to file name suffixes. This is then given to
-ImageMagick as a file name hint.
+@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
+when the image does not have an associated file name, to provide a
+hint to ImageMagick to help it detect the image type.
-@item :rotation
+@item :rotation @var{angle}
Specifies a rotation angle in degrees.
-@item :index
+@item :index @var{frame}
@c Doesn't work: http://debbugs.gnu.org/7978
@xref{Multi-Frame Images}.
@end table
The remaining arguments, @var{props}, specify additional image
properties---for example,
+@c ':heuristic-mask' is not documented?
@example
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width}
@var{height})} which specifies the @var{x} and @var{y} positions and
@var{width} and @var{height} of the image area to insert. Integer
-values are in units of pixels. A floating point number in the range
+values are in units of pixels. A floating-point number in the range
0.0--1.0 stands for that fraction of the width or height of the entire
image.
@end defun
@defun image-size spec &optional pixels frame
+@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
larger than this limit.
If the value is an integer, it directly specifies the maximum
-image height and width, measured in pixels. If it is a floating
-point number, it specifies the maximum image height and width
+image height and width, measured in pixels. If it is floating
+point, it specifies the maximum image height and width
as a ratio to the frame height and width. If the value is
non-numeric, there is no explicit limit on the size of images.
from accidentally being loaded into Emacs. It only takes effect the
first time an image is loaded. Once an image is placed in the image
cache, it can always be displayed, even if the value of
-@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@code{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
@node Multi-Frame Images
@subsection Multi-Frame Images
+@cindex multi-frame images
@cindex animation
@cindex image animation
forever; if a number animation stops after that many seconds.
@end defun
+@vindex image-minimum-frame-delay
+@vindex image-default-frame-delay
@noindent Animation operates by means of a timer. Note that Emacs imposes a
minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds.
If the image itself does not specify a delay, Emacs uses
@code{button-buffer-map} as a parent keymap for its keymap.
If the button has a non-@code{nil} @code{follow-link} property, and
-@var{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}.
@defun next-button pos &optional count-current
@defunx previous-button pos &optional count-current
-Return the next button after (for @code{next-button} or before (for
+Return the next button after (for @code{next-button}) or before (for
@code{previous-button}) position @var{pos} in the current buffer. If
@var{count-current} is non-@code{nil}, count any button at @var{pos}
in the search, instead of starting at the next button.
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.
+``model/view/controller'' design paradigm. Ewoc means ``Emacs's
+Widget for Object Collections''.
An @dfn{ewoc} is a structure that organizes information required to
construct buffer text that represents certain Lisp data. The buffer
The header and footer strings.
@item
+@cindex node, ewoc
+@c or "@cindex node, abstract display"?
A doubly-linked chain of @dfn{nodes}, each of which contains:
@itemize
representation to another, and so forth. @xref{Abstract Display
Functions}.
+@cindex encapsulation, ewoc
+@c or "@cindex encapsulation, abstract display"?
A node @dfn{encapsulates} a data element much the way a variable
holds a value. Normally, encapsulation occurs as a part of adding a
node to the ewoc. You can retrieve the data element value and place a
@end defopt
@defopt blink-matching-delay
-This variable specifies the number of seconds for the cursor to remain
-at the matching parenthesis. A fraction of a second often gives
-good results, but the default is 1, which works on all systems.
+This variable specifies the number of seconds to keep indicating the
+matching parenthesis. A fraction of a second often gives good
+results, but the default is 1, which works on all systems.
@end defopt
@deffn Command blink-matching-open
This function is the default value of @code{blink-paren-function}. It
-assumes that point follows a character with close parenthesis syntax and
-moves the cursor momentarily to the matching opening character. If that
-character is not already on the screen, it displays the character's
-context in the echo area. To avoid long delays, this function does not
-search farther than @code{blink-matching-paren-distance} characters.
+assumes that point follows a character with close parenthesis syntax
+and applies the appropriate effect momentarily to the matching opening
+character. If that character is not already on the screen, it
+displays the character's context in the echo area. To avoid long
+delays, this function does not search farther than
+@code{blink-matching-paren-distance} characters.
Here is an example of calling this function explicitly.
@smallexample
@group
(defun interactive-blink-matching-open ()
- "Indicate momentarily the start of sexp before point."
+ "Indicate momentarily the start of parenthesized sexp before point."
(interactive)
@end group
@group
@subsection Glyphs
@cindex glyph
+@cindex glyph code
A @dfn{glyph} is a graphical symbol which occupies a single
character position on the screen. Each glyph is represented in Lisp
as a @dfn{glyph code}, which specifies a character and optionally a
@code{display-graphic-p} or any of the other @code{display-*-p}
predicates described in @ref{Display Feature Testing}.
-@defvar window-setup-hook
-This variable is a normal hook which Emacs runs after handling the
-initialization files. Emacs runs this hook after it has completed
-loading your init file, the default initialization file (if
-any), and the terminal-specific Lisp code, and running the hook
-@code{term-setup-hook}.
-
-This hook is used for internal purposes: setting up communication with
-the window system, and creating the initial window. Users should not
-interfere with it.
-@end defvar
-
@node Bidirectional Display
@section Bidirectional Display
@cindex bidirectional display
@cindex reading order
@cindex visual order
@cindex unicode bidirectional algorithm
+@cindex UBA
@cindex bidirectional reordering
+@cindex reordering, of bidirectional text
Text is stored in Emacs buffers and strings in @dfn{logical} (or
@dfn{reading}) order, i.e., the order in which a human would read
each character. In right-to-left and bidirectional text, the order in
HCoop / bpt / emacs.git / blobdiff