* 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.
@defun redisplay &optional force
This function tries immediately to redisplay. The optional argument
@var{force}, if non-@code{nil}, forces the redisplay to be performed,
-instead of being preempted if input is pending.
+instead of being preempted, even if input is pending and the variable
+@code{redisplay-dont-pause} is @code{nil} (see below). If
+@code{redisplay-dont-pause} is non-@code{nil} (the default), this
+function redisplays in any case, i.e., @var{force} does nothing.
The function returns @code{t} if it actually tried to redisplay, and
@code{nil} otherwise. A value of @code{t} does not mean that
newly arriving input.
@end defun
+@defvar redisplay-dont-pause
+If this variable is @code{nil}, arriving input events preempt
+redisplay; Emacs avoids starting a redisplay, and stops any redisplay
+that is in progress, until the input has been processed. In
+particular, @code{(redisplay)} returns @code{nil} without actually
+redisplaying, if there is pending input.
+
+The default value is @code{t}, which means that pending input does not
+preempt redisplay.
+@end defvar
+
+@defvar redisplay-preemption-period
+If @code{redisplay-dont-pause} is @code{nil}, this variable specifies
+how many seconds Emacs waits between checks for new input during
+redisplay; if input arrives during this interval, redisplay stops and
+the input is processed. The default value is 0.1; if the value is
+@code{nil}, Emacs does not check for input during redisplay.
+
+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.
@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
@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.
-@var{horizontal-type} is not actually meaningful.
+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
+
+@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. @var{window} must be a live window, and defaults to the
-selected window.
+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.
-@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.
-@end defopt
+You can control the appearance of scroll bars for a particular buffer by
+setting the following variables which automatically become buffer-local
+when set.
-@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.
-@end defun
+@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, 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.
+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 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
+
+@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
position. In performing this @dfn{bidirectional reordering}, Emacs
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 currently provides
-a ``Non-isolate Bidirectionality'' class implementation of the
-@acronym{UBA}: it does not yet support the isolate directional
-formatting characters introduced with Unicode Standard v6.3.0.
+(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full
+Bidirectionality'' class implementation of the @acronym{UBA},
+consistent with the requirements of the Unicode Standard v7.0.
@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