@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
@node Echo Area Customization
@subsection Echo Area Customization
+@cindex echo area customization
These variables control details of how the echo area works.
@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
@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
@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
@node Finding Overlays
@subsection Searching for Overlays
+@cindex searching for overlays
+@cindex overlays, searching for
@defun overlays-at pos &optional sorted
This function returns a list of all the overlays that cover the character at
@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
@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.
@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
@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,
@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 :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
@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
@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.
@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
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