@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.
+* Scroll Bars:: Controlling 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.
@node Refresh Screen
@section Refreshing the Screen
+@cindex refresh the screen
+@cindex screen refresh
The function @code{redraw-frame} clears and redisplays the entire
contents of a given frame (@pxref{Frames}). This is useful if the
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
+@ignore
If your buffer contains only very short lines, you might find it
advisable to set @code{cache-long-scans} to @code{nil}.
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*}
@node Echo Area Customization
@subsection Echo Area Customization
+@cindex echo area customization
These variables control details of how the echo area works.
@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
@node Warning Variables
@subsection Warning Variables
+@cindex warning variables
Programs can customize how their warnings appear by binding
the variables described in this section.
@node Warning Options
@subsection Warning Options
+@cindex warning options
These variables are used by users to control what happens
when a Lisp program reports a warning.
@node Delayed Warnings
@subsection Delayed Warnings
+@cindex delayed warnings
Sometimes, you may wish to avoid showing a warning while a command is
running, and only show it only after the end of the command. You can
@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}
@node Temporary Displays
@section Temporary Displays
+@cindex temporary display
+@cindex temporary buffer display
Temporary displays are used by Lisp programs to put output into 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
@node Managing Overlays
@subsection Managing Overlays
+@cindex managing overlays
+@cindex overlays, managing
This section describes the functions to create, delete and move
overlays, and to examine their contents. Overlay changes are not
@node Overlay Properties
@subsection Overlay Properties
+@cindex overlay properties
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
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
+@cindex searching for overlays
+@cindex overlays, searching for
-@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
+@cindex size of text on display
+@cindex character width on display
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.
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
+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.
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
@node Defining Faces
@subsection Defining Faces
+@cindex defining faces
@cindex face spec
The usual way to define a face is through the @code{defface} macro.
@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
@subsection Face Attribute Functions
+@cindex face attributes, access and modification
This section describes functions for directly accessing and
modifying the attributes of a named face.
@node Displaying Faces
@subsection Displaying Faces
+@cindex displaying faces
+@cindex face merging
When Emacs displays a given piece of text, the visual appearance of
the text may be determined by faces drawn from different sources. If
@node Face Remapping
@subsection Face Remapping
+@cindex face remapping
The variable @code{face-remapping-alist} is used for buffer-local or
global changes in the appearance of a face. For instance, it is used
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.
@node Basic Faces
@subsection Basic Faces
+@cindex basic faces
If your Emacs Lisp program needs to assign some faces to text, it is
often a good idea to use certain existing faces or inherit from them,
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
@node Font Lookup
@subsection Looking Up Fonts
+@cindex font lookup
+@cindex looking up fonts
@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@node Fontsets
@subsection Fontsets
+@cindex fontset
A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes. An individual font cannot display the whole range of
@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
@item :otf
@cindex OpenType font
The font must be an OpenType font that supports these OpenType
-features, provided Emacs is compiled with support for @samp{libotf} (a
-library for performing complex text layout in certain scripts). The
-value must be a list of the form
+features, provided Emacs is compiled with a library, such as
+@samp{libotf} on GNU/Linux, that supports complex text layout for
+scripts which need that. The value must be a list of the form
@smallexample
@code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})}
consecutive wildcards in the XLFD are folded into one.
@end defun
+The following two functions return important information about a font.
+
+@defun font-info name &optional frame
+This function returns information about a font specified by its
+@var{name}, a string, as it is used on @var{frame}. If @var{frame} is
+omitted or @code{nil}, it defaults to the selected frame.
+
+The value returned by the function is a vector of the form
+@code{[@var{opened-name} @var{full-name} @var{size} @var{height}
+@var{baseline-offset} @var{relative-compose} @var{default-ascent}
+@var{max-width} @var{ascent} @var{descent} @var{space-width}
+@var{average-width} @var{filename} @var{capability}]}. Here's the
+description of each components of this vector:
+
+@table @var
+@item opened-name
+The name used to open the font, a string.
+
+@item full-name
+The full name of the font, a string.
+
+@item size
+The pixel size of the font.
+
+@item height
+The height of the font in pixels.
+
+@item baseline-offset
+The offset in pixels from the @acronym{ASCII} baseline, positive
+upward.
+
+@item relative-compose
+@itemx default-ascent
+Numbers controlling how to compose characters.
+
+@item ascent
+@itemx descent
+The ascent and descent of this font. The sum of these two numbers
+should be equal to the value of @var{height} above.
+
+@item space-width
+The width, in pixels, of the font's space character.
+
+@item average-width
+The average width of the font characters. If this is zero, Emacs uses
+the value of @var{space-width} instead, when it calculates text layout
+on display.
+
+@item filename
+The file name of the font as a string. This can be @code{nil} if the
+font back-end does not provide a way to find out the font's file name.
+
+@item capability
+A list whose first element is a symbol representing the font type, one
+of @code{x}, @code{opentype}, @code{truetype}, @code{type1},
+@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2
+additional elements describing the @sc{gsub} and @sc{gpos} features
+supported by the font. Each of these elements is a list of the form
+@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{})
+@dots{})}, where @var{script} is a symbol representing an OpenType
+script tag, @var{langsys} is a symbol representing an OpenType langsys
+tag (or @code{nil}, which stands for the default langsys), and each
+@var{feature} is a symbol representing an OpenType feature tag.
+@end table
+@end defun
+
+@defun query-font font-object
+This function returns information about a @var{font-object}. (This is
+in contrast to @code{font-info}, which takes the font name, a string,
+as its argument.)
+
+The value returned by the function is a vector of the form
+@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width}
+@var{ascent} @var{descent} @var{space-width} @var{average-width}
+@var{capability}]}. Here's the description of each components of this
+vector:
+
+@table @var
+@item name
+The font name, a string.
+
+@item filename
+The file name of the font as a string. This can be @code{nil} if the
+font back-end does not provide a way to find out the font's file name.
+
+@item pixel-size
+The pixel size of the font used to open the font.
+
+@item max-width
+The maximum advance width of the font.
+
+@item ascent
+@itemx descent
+The ascent and descent of this font. The sum of these two numbers
+gives the font height.
+
+@item space-width
+The width, in pixels, of the font's space character.
+
+@item average-width
+The average width of the font characters. If this is zero, Emacs uses
+the value of @var{space-width} instead, when it calculates text layout
+on display.
+
+@item capability
+A list whose first element is a symbol representing the font type, one
+of @code{x}, @code{opentype}, @code{truetype}, @code{type1},
+@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2
+additional elements describing the @sc{gsub} and @sc{gpos} features
+supported by the font. Each of these elements is a list of the form
+@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{})
+@dots{})}, where @var{script} is a symbol representing an OpenType
+script tag, @var{langsys} is a symbol representing an OpenType langsys
+tag (or @code{nil}, which stands for the default langsys), and each
+@var{feature} is a symbol representing an OpenType feature tag.
+@end table
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
@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.
@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
is used.
+
@node Scroll Bars
@section Scroll Bars
@cindex scroll bars
Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars, and
-whether they are on the left or right. The frame parameter
-@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default). @xref{Layout Parameters}.
+whether the windows in the frame have vertical scroll bars, and whether
+they are on the left or right. The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning
+the default).
+
+ The frame parameter @code{horizontal-scroll-bars} controls whether
+the windows in the frame have horizontal scroll bars. The frame
+parameter @code{scroll-bar-height} specifies how high they are
+(@code{nil} meaning the default). @xref{Layout Parameters}.
+
+@vindex horizontal-scroll-bars-available-p
+ Horizontal scroll bars are not available on all platforms. The
+function @code{horizontal-scroll-bars-available-p} which takes no
+argument returns non-@code{nil} if they are available on your system.
+
+ The following three functions take as argument a live frame which
+defaults to the selected one.
@defun frame-current-scroll-bars &optional frame
-This function reports the scroll bar type settings for frame
-@var{frame}. The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
-@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
-(which means no scroll bar.) @var{horizontal-type} is meant to
-specify the horizontal scroll bar type, but since they are not
-implemented, it is always @code{nil}.
-@end defun
-
-@vindex vertical-scroll-bar
- You can enable or disable scroll bars for a particular buffer,
-by setting the variable @code{vertical-scroll-bar}. This variable
-automatically becomes buffer-local when set. The possible values are
-@code{left}, @code{right}, @code{t}, which means to use the
-frame's default, and @code{nil} for no scroll bar.
+This function reports the scroll bar types for frame @var{frame}. The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}, where @var{vertical-type} is either
+@code{left}, @code{right}, or @code{nil} (which means no vertical scroll
+bar.) @var{horizontal-type} is either @code{bottom} or @code{nil}
+(which means no horizontal scroll bar).
+@end defun
- You can also control this for individual windows. Call the function
-@code{set-window-scroll-bars} to specify what to do for a specific window:
+@defun frame-scroll-bar-width &optional Lisp_Object &optional frame
+This function returns the width of vertical scroll bars of @var{frame}
+in pixels.
+@end defun
-@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-This function sets the width and type of scroll bars for window
-@var{window}.
+@defun frame-scroll-bar-height &optional Lisp_Object &optional frame
+This function returns the height of horizontal scroll bars of
+@var{frame} in pixels.
+@end defun
-@var{width} specifies the scroll bar width in pixels (@code{nil} means
-use the width specified for the frame). @var{vertical-type} specifies
-whether to have a vertical scroll bar and, if so, where. The possible
-values are @code{left}, @code{right} and @code{nil}, just like the
-values of the @code{vertical-scroll-bars} frame parameter.
+You can override the frame specific settings for individual windows by
+using the following function:
-The argument @var{horizontal-type} is meant to specify whether and
-where to have horizontal scroll bars, but since they are not
-implemented, it has no effect. If @var{window} is @code{nil}, the
-selected window is used.
+@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type
+This function sets the width and/or height and the types of scroll bars
+for window @var{window}.
+
+@var{width} specifies the width of the vertical scroll bar in pixels
+(@code{nil} means use the width specified for the frame).
+@var{vertical-type} specifies whether to have a vertical scroll bar and,
+if so, where. The possible values are @code{left}, @code{right},
+@code{t}, which means to use the frame's default, and @code{nil} for no
+vertical scroll bar.
+
+@var{height} specifies the height of the horizontal scroll bar in pixels
+(@code{nil} means use the height specified for the frame).
+@var{horizontal-type} specifies whether to have a horizontal scroll bar.
+The possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no horizontal scroll bar.
+
+If @var{window} is @code{nil}, the selected window is used.
@end defun
+The following four functions take as argument a live window which
+defaults to the selected one.
+
@defun window-scroll-bars &optional window
-Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a list of the form @code{(@var{width}
-@var{cols} @var{vertical-type} @var{horizontal-type})}. The value
-@var{width} is the value that was specified for the width (which may
-be @code{nil}); @var{cols} is the number of columns that the scroll
-bar actually occupies.
+This function returns a list of the form @code{(@var{width}
+@var{columns} @var{vertical-type} @var{height} @var{lines}
+@var{horizontal-type})}.
+
+The value @var{width} is the value that was specified for the width of
+the vertical scroll bar (which may be @code{nil}); @var{columns} is the
+(possibly rounded) number of columns that the vertical scroll bar
+actually occupies.
+
+The value @var{height} is the value that was specified for the height of
+the horizontal scroll bar (which may be @code{nil}); @var{lines} is the
+(possibly rounded) number of lines that the horizontally scroll bar
+actually occupies.
+@end defun
-@var{horizontal-type} is not actually meaningful.
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}. The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}. Unlike @code{window-scroll-bars}, this reports
+the scroll bar type actually used, once frame defaults and
+@code{scroll-bar-mode} are taken into account.
+@end defun
+
+@defun window-scroll-bar-width &optional window
+This function returns the width in pixels of @var{window}'s vertical
+scrollbar.
+@end defun
+
+@defun window-scroll-bar-height &optional window
+This function returns the height in pixels of @var{window}'s horizontal
+scrollbar.
@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
-displayed control the window's vertical scroll bars. The function
+@code{vertical-scroll-bar}, @code{horizontal-scroll-bar},
+@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being
+displayed control the window's scroll bars. The function
@code{set-window-buffer} examines these variables. If you change them
-in a buffer that is already visible in a window, you can make the
-window take note of the new values by calling @code{set-window-buffer}
+in a buffer that is already visible in a window, you can make the window
+take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
+You can control the appearance of scroll bars for a particular buffer by
+setting the following variables which automatically become buffer-local
+when set.
+
+@defvar vertical-scroll-bar
+This variable specifies the location of the vertical scroll bar. The
+possible values are @code{left}, @code{right}, @code{t}, which means to
+use the frame's default, and @code{nil} for no scroll bar.
+@end defvar
+
+@defvar horizontal-scroll-bar
+This variable specifies the location of the horizontal scroll bar. The
+possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+@end defvar
+
+@defvar scroll-bar-width
+This variable specifies the width of the buffer's vertical scroll bars,
+measured in pixels. A value of @code{nil} means to use the value
+specified by the frame.
+@end defvar
+
+@defvar scroll-bar-height
+This variable specifies the height of the buffer's horizontal scroll
+bar, measured in pixels. A value of @code{nil} means to use the value
+specified by the frame.
+@end defvar
+
+Finally you can toggle the display of scroll bars on all frames by
+customizing the variables @code{scroll-bar-mode} and
+@code{horizontal-scroll-bar-mode}.
+
@defopt scroll-bar-mode
-This variable, always local in all buffers, controls whether and where
-to put scroll bars in windows displaying the buffer. The possible values
-are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
-the left, and @code{right} to put a scroll bar on the right.
+This variable controls whether and where to put vertical scroll bars in
+all frames. The possible values are @code{nil} for no scroll bars,
+@code{left} to put scroll bars on the left and @code{right} to put
+scroll bars on the right.
@end defopt
-@defun window-current-scroll-bars &optional window
-This function reports the scroll bar type for window @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike
-@code{window-scroll-bars}, this reports the scroll bar type actually
-used, once frame defaults and @code{scroll-bar-mode} are taken into
-account.
+@defopt horizontal-scroll-bar-mode
+This variable controls whether to display horizontal scroll bars on all
+frames.
+@end defopt
+
+
+@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
-@defvar scroll-bar-width
-This variable, always local in all buffers, specifies the width of the
-buffer's scroll bars, measured in pixels. A value of @code{nil} means
-to use the value specified by the frame.
-@end defvar
@node Display Property
@section The @code{display} Property
@node Replacing Specs
@subsection Display Specs That Replace The Text
+@cindex replacing display specs
Some kinds of display specifications specify something to display
instead of the text that has the property. These are called
@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.
Each image descriptor has the form @code{(image . @var{props})},
where @var{props} is a property list of alternating keyword symbols
-and values, including at least the pair @code{:type @var{TYPE}} which
+and values, including at least the pair @code{:type @var{type}} that
specifies the image type.
The following is a list of properties that are meaningful for all
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.
-@c FIXME: ‘:format-type’ or ‘:format’? --xfq
-@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
@node Defining Images
@subsection Defining Images
+@cindex define image
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
The remaining arguments, @var{props}, specify additional image
properties---for example,
-@c ‘:heuristic-mask’ is not documented?
+@c ':heuristic-mask' is not documented?
@example
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
Each specification in @var{specs} is a property list with contents
depending on image type. All specifications must at least contain the
properties @code{:type @var{type}} and either @w{@code{:file @var{file}}}
-or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying
+or @w{@code{:data @var{data}}}, where @var{type} is a symbol specifying
the image type, e.g., @code{xbm}, @var{file} is the file to load the
image from, and @var{data} is a string containing the actual image data.
The first specification in the list whose @var{type} is supported, and
@node Showing Images
@subsection Showing Images
+@cindex show image
You can use an image descriptor by setting up the @code{display}
property yourself, but it is easier to use the functions in this
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.
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.
@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
@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
follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}),
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}.
+Bidirectionality'' class implementation of the @acronym{UBA},
+consistent with the requirements of the Unicode Standard v7.0.
@defvar bidi-display-reordering
If the value of this buffer-local variable is non-@code{nil} (the
appropriate mirrored character in the reordered text. Lisp programs
can affect the mirrored display by changing this property. Again, any
such changes affect all of Emacs display.
+
+@cindex overriding bidirectional properties
+@cindex directional overrides
+@cindex LRO
+@cindex RLO
+ The bidirectional properties of characters can be overridden by
+inserting into the text special directional control characters,
+LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE
+(@acronym{RLO}). Any characters between a @acronym{RLO} and the
+following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF})
+control character, whichever comes first, will be displayed as if they
+were strong right-to-left characters, i.e.@: they will be reversed on
+display. Similarly, any characters between @acronym{LRO} and
+@acronym{PDF} or newline will display as if they were strong
+left-to-right, and will @emph{not} be reversed even if they are strong
+right-to-left characters.
+
+@cindex phishing using directional overrides
+@cindex malicious use of directional overrides
+ These overrides are useful when you want to make some text
+unaffected by the reordering algorithm, and instead directly control
+the display order. But they can also be used for malicious purposes,
+known as @dfn{phishing}. Specifically, a URL on a Web page or a link
+in an email message can be manipulated to make its visual appearance
+unrecognizable, or similar to some popular benign location, while the
+real location, interpreted by a browser in the logical order, is very
+different.
+
+ Emacs provides a primitive that applications can use to detect
+instances of text whose bidirectional properties were overridden so as
+to make a left-to-right character display as if it were a
+right-to-left character, or vise versa.
+
+@defun bidi-find-overridden-directionality from to &optional object
+This function looks at the text of the specified @var{object} between
+positions @var{from} (inclusive) and @var{to} (exclusive), and returns
+the first position where it finds a strong left-to-right character
+whose directional properties were forced to display the character as
+right-to-left, or for a strong right-to-left character that was forced
+to display as left-to-right. If it finds no such characters in the
+specified region of text, it returns @code{nil}.
+
+The optional argument @var{object} specifies which text to search, and
+defaults to the current buffer. If @var{object} is non-@code{nil}, it
+can be some other buffer, or it can be a string or a window. If it is
+a string, the function searches that string. If it is a window, the
+function searches the buffer displayed in that window. If a buffer
+whose text you want to examine is displayed in some window, we
+recommend to specify it by that window, rather than pass the buffer to
+the function. This is because telling the function about the window
+allows it to correctly account for window-specific overlays, which
+might change the result of the function if some text in the buffer is
+covered by overlays.
+@end defun
+
+@cindex copying bidirectional text, preserve visual order
+@cindex visual order, preserve when copying bidirectional text
+ When text that includes mixed right-to-left and left-to-right
+characters and bidirectional controls is copied into a different
+location, it can change its visual appearance, and also can affect the
+visual appearance of the surrounding text at destination. This is
+because reordering of bidirectional text specified by the
+@acronym{UBA} has non-trivial context-dependent effects both on the
+copied text and on the text at copy destination that will surround it.
+
+ Sometimes, a Lisp program may need to preserve the exact visual
+appearance of the copied text at destination, and of the text that
+surrounds the copy. Lisp programs can use the following function to
+achieve that effect.
+
+@defun buffer-substring-with-bidi-context start end &optional no-properties
+This function works similar to @code{buffer-substring} (@pxref{Buffer
+Contents}), but it prepends and appends to the copied text bidi
+directional control characters necessary to preserve the visual
+appearance of the text when it is inserted at another place. Optional
+argument @var{no-properties}, if non-@code{nil}, means remove the text
+properties from the copy of the text.
+@end defun