procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Updates to Display chapter of Lisp manual.

Browse source 
* doc/lispref/display.texi (Fringes): Note that fringes are shown on graphical
displays only.
(Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications.
(Replacing Specs): Clarify example.
(Manipulating Buttons): Note that button-at can return a marker.
(Buttons): Minor rewrite.
(Character Display): New node.  Consolidate all character display
related nodes into its subsections.
(Usual Display): Character 127 is also affected by ctl-arrow.
(Display Tables): Improve example.

* lisp/button.el (button-at): Minor addition to docstring.
This commit is contained in:
Chong Yidong 2012-03-25 15:58:59 +08:00
parent 8a0c01dd25
commit 9a69676ae6
7 changed files with 345 additions and 340 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
doc/lispref/ChangeLog
View file

@ -1,3 +1,16 @@
2012-03-25 Chong Yidong <cyd@gnu.org>
* display.texi (Fringes): Note that fringes are shown on graphical
displays only.
(Fringe Size/Pos, Fringe Bitmaps, Making Buttons): Clarifications.
(Replacing Specs): Clarify example.
(Manipulating Buttons): Note that button-at can return a marker.
(Buttons): Minor rewrite.
(Character Display): New node. Consolidate all character display
related nodes into its subsections.
(Usual Display): Character 127 is also affected by ctl-arrow.
(Display Tables): Improve example.
2012-03-22 Glenn Morris <rgm@gnu.org>
* strings.texi (Text Comparison): Mention string-prefix-p.

619
doc/lispref/display.texi
View file

@ -30,13 +30,11 @@ that Emacs presents to the user.
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying nonprinting chars.
* Display Tables:: How to specify other conventions.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Refresh Screen
@ -46,7 +44,6 @@ that Emacs presents to the user.
contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted.
@c Emacs 19 feature
@defun redraw-frame frame
This function clears and redisplays frame @var{frame}.
@end defun
@ -3206,9 +3203,9 @@ consecutive wildcards in the XLFD are folded into one.
@section Fringes
@cindex fringes
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
continuation, horizontal scrolling, and the overlay arrow.
On graphical displays, Emacs draws @dfn{fringes} next to each
window: thin vertical strips down the sides which can display bitmaps
indicating truncation, continuation, horizontal scrolling, and so on.
@menu
* Fringe Size/Pos:: Specifying where to put the window fringes.
@ -3223,7 +3220,7 @@ continuation, horizontal scrolling, and the overlay arrow.
@subsection Fringe Size and Position
The following buffer-local variables control the position and width
of the window fringes.
of fringes in windows showing that buffer.
@defvar fringes-outside-margins
The fringes normally appear between the display margins and the window
@ -3243,12 +3240,17 @@ fringe in pixels. A value of @code{nil} means to use the right fringe
width from the window's frame.
@end defvar
The values of these variables take effect when you display the
buffer in a window. If you change them while the buffer is visible,
you can call @code{set-window-buffer} to display it once again in the
same window, to make the changes take effect. A buffer that does not
specify values for these variables will use the default values
specified for the frame; see @ref{Layout Parameters}.
Any buffer which does not specify values for these variables uses
the values specified by the @code{left-fringe} and @code{right-fringe}
frame parameters (@pxref{Layout Parameters}).
The above variables actually take effect via the function
@code{set-window-buffer} (@pxref{Buffers and Windows}), which calls
@code{set-window-fringes} as a subroutine. If you change one of these
variables, the fringe display is not updated in existing windows
showing the buffer, unless you call @code{set-window-buffer} again in
each affected window. You can also use @code{set-window-fringes} to
control the fringe display in individual windows.
@defun set-window-fringes window left &optional right outside-margins
This function sets the fringe widths of window @var{window}.
@ -3274,9 +3276,9 @@ window is used. The value has the form @code{(@var{left-width}
@cindex fringe indicators
@cindex indicators, fringe
The @dfn{fringe indicators} are tiny icons Emacs displays in the
window fringe (on a graphic display) to indicate truncated or
continued lines, buffer boundaries, overlay arrow, etc.
@dfn{Fringe indicators} are tiny icons displayed in the window
fringe to indicate truncated or continued lines, buffer boundaries,
etc.
@defopt indicate-empty-lines
@cindex fringes, and empty line indication
@ -3448,21 +3450,15 @@ characters appearing in the line (@pxref{Other Display Specs}). Such
a display specification has the form
@example
(left-fringe @var{bitmap} [@var{face}])
(@var{fringe} @var{bitmap} [@var{face}])
@end example
@noindent
or
@example
(right-fringe @var{bitmap} [@var{face}])
@end example
@noindent
The symbol @var{bitmap} identifies the bitmap to display. The
optional @var{face} names a face whose foreground color is used to
display the bitmap; this face is automatically merged with the
@code{fringe} face.
@var{fringe} is either the symbol @code{left-fringe} or
@code{right-fringe}. @var{bitmap} is a symbol identifying the bitmap
to display. The optional @var{face} names a face whose foreground
color is used to display the bitmap; this face is automatically merged
with the @code{fringe} face.
Here is a list of the standard fringe bitmaps defined in Emacs, and
how they are currently used in Emacs (via
@ -3710,7 +3706,7 @@ to use the value specified by the frame.
@kindex display @r{(text property)}
The @code{display} text property (or overlay property) is used to
insert images into text, and also control other aspects of how text
insert images into text, and to control other aspects of how text
displays. The value of the @code{display} property should be a
display specification, or a list or vector containing several display
specifications. Display specifications in the same @code{display}
@ -3736,8 +3732,8 @@ display specifications and what they mean.
@node Replacing Specs
@subsection Display Specs That Replace The Text
Some kinds of @code{display} specifications specify something to
display instead of the text that has the property. These are called
Some kinds of display specifications specify something to display
instead of the text that has the property. These are called
@dfn{replacing} display specifications. Emacs does not allow the user
to interactively move point into the middle of buffer text that is
replaced in this way.
@ -3750,47 +3746,34 @@ irrelevant, since those don't apply to the replacement.
For replacing display specifications, ``the text that has the
property'' means all the consecutive characters that have the same
Lisp object as their @code{display} property; these characters are
replaced as a single unit. By contrast, characters that have similar
but distinct Lisp objects as their @code{display} properties are
handled separately. Here's a function that illustrates this point:
replaced as a single unit. If two characters have different Lisp
objects as their @code{display} properties (i.e.@: objects which are
not @code{eq}), they are handled separately.
Here is an example which illustrates this point. A string serves as
a replacing display specification, which replaces the text that has
the property with the specified string (@pxref{Other Display Specs}).
Consider the following function:
@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(let ((string (concat "A")))
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 1)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 1))))
(let ((string (concat "A"))
(start (+ i i (point-min))))
(put-text-property start (1+ start) 'display string)
(put-text-property start (+ 2 start) 'display string))))
@end smallexample
@noindent
It gives each of the first ten characters in the buffer string
@code{"A"} as the @code{display} property, but they don't all get the
same string. The first two characters get the same string, so they
together are replaced with one @samp{A}. The next two characters get
a second string, so they together are replaced with one @samp{A}.
Likewise for each following pair of characters. Thus, the ten
characters appear as five A's. This function would have the same
results:
@smallexample
(defun foo ()
(goto-char (point-min))
(dotimes (i 5)
(let ((string (concat "A")))
(put-text-property (point) (+ 2 (point)) 'display string)
(put-text-property (point) (1+ (point)) 'display string)
(forward-char 2))))
@end smallexample
@noindent
This illustrates that what matters is the property value for
each character. If two consecutive characters have the same
object as the @code{display} property value, it's irrelevant
whether they got this property from a single call to
@code{put-text-property} or from two different calls.
This function gives each of the first ten characters in the buffer a
@code{display} property which is a string @code{"A"}, but they don't
all get the same string object. The first two characters get the same
string object, so they are replaced with one @samp{A}; the fact that
the display property was assigned in two separate calls to
@code{put-text-property} is irrelevant. Similarly, the next two
characters get a second string (@code{concat} creates a new string
object), so they are replaced with one @samp{A}; and so on. Thus, the
ten characters appear as five A's.
@node Specified Space
@subsection Specified Spaces
@ -4952,29 +4935,24 @@ debugging.
@cindex buttons in buffers
@cindex clickable buttons in buffers
The @emph{button} package defines functions for inserting and
manipulating clickable (with the mouse, or via keyboard commands)
buttons in Emacs buffers, such as might be used for help hyper-links,
etc. Emacs uses buttons for the hyper-links in help text and the like.
The Button package defines functions for inserting and manipulating
@dfn{buttons} that can be activated with the mouse or via keyboard
commands. These buttons are typically used for various kinds of
hyperlinks.
A button is essentially a set of properties attached (via text
properties or overlays) to a region of text in an Emacs buffer. These
properties are called @dfn{button properties}.
A button is essentially a set of text or overlay properties,
attached to a stretch of text in a buffer. These properties are
called @dfn{button properties}. One of these properties, the
@dfn{action property}, specifies a function which is called when the
user invokes the button using the keyboard or the mouse. The action
function may examine the button and use its other properties as
desired.
One of these properties (@code{action}) is a function, which will
be called when the user invokes it using the keyboard or the mouse.
The invoked function may then examine the button and use its other
properties as desired.
In some ways the Emacs button package duplicates functionality offered
by the widget package (@pxref{Top, , Introduction, widget, The Emacs
Widget Library}), but the button package has the advantage that it is
much faster, much smaller, and much simpler to use (for elisp
programmers---for users, the result is about the same). The extra
speed and space savings are useful mainly if you need to create many
buttons in a buffer (for instance an @code{*Apropos*} buffer uses
buttons to make entries clickable, and may contain many thousands of
entries).
In some ways, the Button package duplicates the functionality in the
Widget package. @xref{Top, , Introduction, widget, The Emacs Widget
Library}. The advantage of the Button package is that it is faster,
smaller, and simpler to program. From the point of view of the user,
the interfaces produced by the two packages are very similar.
@menu
* Button Properties:: Button properties with special meanings.
@ -4988,10 +4966,10 @@ entries).
@subsection Button Properties
@cindex button properties
Buttons have an associated list of properties defining their
Each button has an associated list of properties defining its
appearance and behavior, and other arbitrary properties may be used
for application specific purposes. Some properties that have special
meaning to the button package include:
for application specific purposes. The following properties have
special meaning to the Button package:
@table @code
@item action
@ -5027,9 +5005,7 @@ in the variable @code{button-map}, which defines @key{RET} and
@item type
@kindex type @r{(button property)}
The button-type of the button. When creating a button, this is
usually specified using the @code{:type} keyword argument.
@xref{Button Types}.
The button type. @xref{Button Types}.
@item help-echo
@kindex help-index @r{(button property)}
@ -5055,7 +5031,7 @@ button, but these are not generally interesting for typical uses.
@subsection Button Types
@cindex button types
Every button has a button @emph{type}, which defines default values
Every button has a @dfn{button type}, which defines default values
for the button's properties. Button types are arranged in a
hierarchy, with specialized types inheriting from more general types,
so that it's easy to define special-purpose types of buttons for
@ -5120,18 +5096,17 @@ This insert a button with the label @var{label} at point,
and returns it.
@end defun
The following functions are similar, but use Emacs text properties
(@pxref{Text Properties}) to hold the button properties, making the
button actually part of the text instead of being a property of the
buffer. Buttons using text properties do not create markers into the
buffer, which is important for speed when you use extremely large
numbers of buttons. (However, if there is an existing face text
property at the site of the button, the button face may not be visible.)
Both functions return the position of the start of the new button:
The following functions are similar, but using text properties
(@pxref{Text Properties}) to hold the button properties. Such buttons
do not add markers to the buffer, so editing in the buffer does not
slow down if there is an extremely large numbers of buttons. However,
if there is an existing face text property on the text (e.g.@: a face
assigned by Font Lock mode), the button face may not be visible. Both
of these functions return the starting position of the new button.
@defun make-text-button beg end &rest properties
This makes a button from @var{beg} to @var{end} in the current buffer, using
text properties.
This makes a button from @var{beg} to @var{end} in the current buffer,
using text properties.
@end defun
@defun insert-text-button label &rest properties
@ -5190,7 +5165,9 @@ Return @code{t} if @var{button} has button-type @var{type}, or one of
@end defun
@defun button-at pos
Return the button at position @var{pos} in the current buffer, or @code{nil}.
Return the button at position @var{pos} in the current buffer, or
@code{nil}. If the button at @var{pos} is a text property button, the
return value is a marker pointing to @var{pos}.
@end defun
@defun button-type-put type prop val
@ -5214,12 +5191,12 @@ buttons in an Emacs buffer.
@code{push-button} is the command that a user uses to actually `push'
a button, and is bound by default in the button itself to @key{RET}
and to @key{mouse-2} using a region-specific keymap. Commands
that are useful outside the buttons itself, such as
@code{forward-button} and @code{backward-button} are additionally
available in the keymap stored in @code{button-buffer-map}; a mode
which uses buttons may want to use @code{button-buffer-map} as a
parent keymap for its keymap.
and to @key{mouse-2} using a local keymap in the button's overlay or
text properties. Commands that are useful outside the buttons itself,
such as @code{forward-button} and @code{backward-button} are
additionally available in the keymap stored in
@code{button-buffer-map}; a mode which uses buttons may want to use
@code{button-buffer-map} as a parent keymap for its keymap.
If the button has a non-@code{nil} @code{follow-link} property, and
@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
@ -5662,70 +5639,111 @@ Here is an example of calling this function explicitly.
@end smallexample
@end deffn
@node Character Display
@section Character Display
@cindex glyph
This section describes how characters are actually displayed by Emacs.
Typically, a character is displayed as a @dfn{glyph} (a graphical
symbol which occupies one character position on the screen), whose
appearance corresponds to the character itself. For example, the
character @samp{a} (character code 97) is displayed as @samp{a}. Some
characters, however, are displayed specially. For example, the
formfeed character (character code 12) is usually displayed as a
sequence of two glyphs, @samp{^L}, while the newline character
(character code 10) starts a new screen line.
You can modify how each character is displayed by defining a
@dfn{display table}, which maps each character code into a sequence of
glyphs. @xref{Display Tables}. A related feature, called the
@dfn{glyph table}, allows you to control how each character is
displayed on a text terminal. @xref{Glyphs}.
@menu
* Usual Display:: The usual conventions for displaying characters.
* Display Tables:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Usual Display
@section Usual Display Conventions
@subsection Usual Display Conventions
The usual display conventions define how to display each character
code. You can override these conventions by setting up a display table
(@pxref{Display Tables}). Here are the usual display conventions:
Here are the usual conventions for display each character code (in
the absence of a display table, which can override these
@iftex
conventions).
@end iftex
@ifnottex
conventions; @pxref{Display Tables}).
@end ifnottex
@cindex printable ASCII characters
@itemize @bullet
@item
Character codes 32 through 126 map to glyph codes 32 through 126.
Normally this means they display as themselves, but a display table
can change that.
The @dfn{printable @acronym{ASCII} characters}, character codes 32
through 126 (consisting of numerals, English letters, and symbols like
@samp{#}) are displayed literally, i.e.@: they map onto glyph codes 32
through 126.
@item
Character code 9 is a horizontal tab. It displays as whitespace
up to a position determined by @code{tab-width}.
The tab character (character code 9) displays as whitespace stretching
up to the next tab stop column. @xref{Text Display,,, emacs, The GNU
Emacs Manual}. The variable @code{tab-width} controls the number of
spaces per tab stop (see below).
@item
Character code 10 is a newline. It is normally invisible on display,
and has the effect of ending the preceding line and starting a new
line.
The newline character (character code 10) has the effect of ending the
preceding line and starting a new line.
@cindex ASCII control characters
@item
All other codes in the range 0 through 31 display in one of two ways
according to the value of @code{ctl-arrow}. If it is non-@code{nil},
these codes map to sequences of two glyphs, where the first glyph is
the @acronym{ASCII} code for @samp{^}. (A display table can specify a
glyph to use instead of @samp{^}.) Otherwise, these codes map just
like the raw bytes in the range 128 to 255 (described below).
The non-printable @dfn{@acronym{ASCII} control characters}---character
codes 0 through 31, as well as the @key{DEL} character (character code
127)---display in one of two ways according to the variable
@code{ctl-arrow}. If this variable is non-@code{nil} (the default),
these characters are displayed as sequences of two glyphs, where the
first glyph is @samp{^} (a display table can specify a glyph to use
instead of @samp{^}); e.g.@: the @key{DEL} character is displayed as
@samp{^?}.
If @code{ctl-arrow} is @code{nil}, these characters are displayed as
octal escapes (see below).
This rule also applies to carriage return (character code 13), if that
character appears in the buffer. But carriage returns usually do not
appear in buffer text; they are eliminated as part of end-of-line
conversion (@pxref{Coding System Basics}).
@cindex octal escapes
@item
Raw bytes (@pxref{Text Representations}) with codes 128 through 255,
and the @acronym{ASCII} control character with code 127, display as
sequences of four glyphs, where the first glyph is the @acronym{ASCII}
code for @samp{\}, and the others are digit characters representing
the character code in octal. (A display table can specify a glyph to
use instead of @samp{\}.) This is known as the @dfn{octal escape}
display.
@dfn{Raw bytes} are non-@acronym{ASCII} characters with codes 128
through 255 (@pxref{Text Representations}). These characters display
as @dfn{octal escapes}: sequences of four glyphs, where the first
glyph is the @acronym{ASCII} code for @samp{\}, and the others are
digit characters representing the character code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
@item
Non-@acronym{ASCII} character codes above 127 are displayed as
themselves, if the terminal and the available fonts support them.
Characters that are not supported by the terminal, or (on window
systems) have no fonts available for them, are displayed as a question
mark or a hex code or an empty box. @xref{Glyphless Chars}, for how
to control display of the characters not supported by the terminal or
fonts. Display tables can change how a character is displayed, even
if it is supported.
Each non-@acronym{ASCII} character with code above 255 is displayed
literally, if the terminal supports it. If the terminal does not
support it, the character is said to be @dfn{glyphless}, and it is
usually displayed using a placeholder glyph. For example, if a
graphical terminal has no font for a character, Emacs usually displays
a box containing the character code in hexadecimal. @xref{Glyphless
Chars}.
@end itemize
The usual display conventions apply even when there is a display
The above display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
specify the characters for which you want special behavior.
These display rules apply to carriage return (character code 13), when
it appears in the buffer. But that character may not appear in the
buffer where you expect it, if it was eliminated as part of end-of-line
conversion (@pxref{Coding System Basics}).
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
they also affect the indentation functions. These variables also affect
The following variables affect how certain characters are displayed
on the screen. Since they change the number of columns the characters
occupy, they also affect the indentation functions. They also affect
how the mode line is displayed; if you want to force redisplay of the
mode line using the new values, call the function
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@ -5748,34 +5766,14 @@ command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
@node Display Tables
@section Display Tables
@subsection Display Tables
@cindex display table
You can use the @dfn{display table} feature to control how all possible
character codes display on the screen. This is useful for displaying
European languages that have letters not in the @acronym{ASCII} character
set.
The display table maps each character code into a sequence of
@dfn{glyphs}, each glyph being a graphic that takes up one character
position on the screen. You can also define how to display each glyph
on your terminal, using the @dfn{glyph table}.
Display tables affect how the mode line is displayed; if you want to
force redisplay of the mode line using a new display table, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@menu
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
@end menu
@node Display Table Format
@subsection Display Table Format
A display table is actually a char-table (@pxref{Char-Tables}) with
@code{display-table} as its subtype.
A display table is a special-purpose char-table
(@pxref{Char-Tables}), with @code{display-table} as its subtype, which
is used to override the usual character display conventions. This
section describes how to make, inspect, and assign elements to a
display table object.
@defun make-display-table
This creates and returns a display table. The table initially has
@ -5784,10 +5782,10 @@ This creates and returns a display table. The table initially has
The ordinary elements of the display table are indexed by character
codes; the element at index @var{c} says how to display the character
code @var{c}. The value should be @code{nil} or a vector of the
glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the
character @var{c} according to the usual display conventions
(@pxref{Usual Display}).
code @var{c}. The value should be @code{nil} (which means to display
the character @var{c} according to the usual display conventions;
@pxref{Usual Display}), or a vector of glyph codes (which means to
display the character @var{c} as those glyphs; @pxref{Glyphs}).
@strong{Warning:} if you use the display table to change the display
of newline characters, the whole buffer will be displayed as one long
@ -5832,12 +5830,11 @@ effect of setting @code{ctl-arrow} to a non-@code{nil} value:
@example
(setq disptab (make-display-table))
(let ((i 0))
(while (< i 32)
(or (= i ?\t) (= i ?\n)
(aset disptab i (vector ?^ (+ i 64))))
(setq i (1+ i)))
(aset disptab 127 (vector ?^ ??)))
(dotimes (i 32)
(or (= i ?\t)
(= i ?\n)
(aset disptab i (vector ?^ (+ i 64)))))
(aset disptab 127 (vector ?^ ??))
@end example
@defun display-table-slot display-table slot
@ -5870,17 +5867,19 @@ help buffer.
@subsection Active Display Table
@cindex active display table
Each window can specify a display table, and so can each buffer. When
a buffer @var{b} is displayed in window @var{w}, display uses the
display table for window @var{w} if it has one; otherwise, the display
table for buffer @var{b} if it has one; otherwise, the standard display
table if any. The display table chosen is called the @dfn{active}
display table.
Each window can specify a display table, and so can each buffer.
The window's display table, if there is one, takes precedence over the
buffer's display table. If neither exists, Emacs tries to use the
standard display table; if that is @code{nil}, Emacs uses the usual
character display conventions (@pxref{Usual Display}).
Note that display tables affect how the mode line is displayed, so
if you want to force redisplay of the mode line using a new display
table, call @code{force-mode-line-update} (@pxref{Mode Line Format}).
@defun window-display-table &optional window
This function returns @var{window}'s display table, or @code{nil}
if @var{window} does not have an assigned display table. The default
for @var{window} is the selected window.
This function returns @var{window}'s display table, or @code{nil} if
there is none. The default for @var{window} is the selected window.
@end defun
@defun set-window-display-table window table
@ -5890,39 +5889,29 @@ The argument @var{table} should be either a display table or
@end defun
@defvar buffer-display-table
This variable is automatically buffer-local in all buffers; its value in
a particular buffer specifies the display table for that buffer. If it
is @code{nil}, that means the buffer does not have an assigned display
table.
This variable is automatically buffer-local in all buffers; its value
specifies the buffer's display table. If it is @code{nil}, there is
no buffer display table.
@end defvar
@defvar standard-display-table
This variable's value is the default display table, used whenever a
window has no display table and neither does the buffer displayed in
that window. This variable is @code{nil} by default.
The value of this variable is the standard display table, which is
used when Emacs is displaying a buffer in a window with neither a
window display table nor a buffer display table defined. Its default
is @code{nil}.
@end defvar
If there is no display table to use for a particular window---that is,
if the window specifies none, its buffer specifies none, and
@code{standard-display-table} is @code{nil}---then Emacs uses the usual
display conventions for all character codes in that window. @xref{Usual
Display}.
A number of functions for changing the standard display table
are defined in the library @file{disp-table}.
The @file{disp-table} library defines several functions for changing
the standard display table.
@node Glyphs
@subsection Glyphs
@cindex glyph
A @dfn{glyph} is a generalization of a character; it stands for an
image that takes up a single character position on the screen. Normally
glyphs come from vectors in the display table (@pxref{Display Tables}).
A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code
can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A
simple glyph code is just a way of specifying a character and a face
to output it in. @xref{Faces}.
A @dfn{glyph} is a graphical symbol which occupies a single
character position on the screen. Each glyph is represented in Lisp
as a @dfn{glyph code}. A glyph code can be @dfn{simple}, or it can be
defined by the @dfn{glyph table}. A simple glyph code is just a way
of specifying a character and a face to output it in. @xref{Faces}.
The following functions are used to manipulate simple glyph codes:
@ -6015,6 +6004,99 @@ non-@code{nil}, it takes precedence over the @code{visible-bell}
variable.
@end defvar
@node Glyphless Chars
@subsection Glyphless Character Display
@cindex glyphless characters
@dfn{Glyphless characters} are not displayed in the usual way when
they appear in a buffer, but in some special way (e.g. as a box
containing a hexadecimal code). These include characters that cannot
be displayed with any available font (on a graphical display), or that
cannot be encoded by the terminal's coding system (on a text
terminal). Specific characters can also be defined to be glyphless.
@defvar glyphless-char-display
The value of this variable is a char-table that defines glyphless
characters and how they are displayed. If an entry is @code{nil}, the
corresponding character is displayed in its usual way. Otherwise, an
entry should be one of the following display methods:
@table @asis
@item @code{zero-width}
Don't display the character.
@item @code{thin-space}
Display a thin space, 1-pixel wide on graphical displays, or
1-character wide on text terminals.
@item @code{empty-box}
Display an empty box.
@item @code{hex-code}
Display a box containing the Unicode codepoint of the character, in
hexadecimal notation.
@item an @acronym{ASCII} string
Display a box containing that string.
@end table
@noindent
Except for @code{zero-width}, these methods display using the
@code{glyphless-char} face.
An entry can also be a cons cell @code{(@var{graphical}
. @var{text})}, where @var{graphical} and @var{text} are the display
methods on graphical displays and text terminals respectively.
The char-table has one extra slot, which determines how to display any
character that cannot be displayed with any available font, or cannot
be encoded by the terminal's coding system. Its value should be one
of the above display methods, except @code{zero-width} or a cons cell.
@end defvar
@defopt glyphless-char-display-control
This user option provides a convenient way to set
@code{glyphless-char-display} for groups of similar characters. It
takes effect via a custom @code{:set} function (@pxref{Variable
Definitions}), which update @code{glyphless-char-display}.
Its value should be an alist of elements @code{(@var{group}
. @var{method})}, where @var{group} is a symbol specifying a group of
characters, and @var{method} is a symbol specifying how to display
them.
@var{group} should be one of the following:
@table @code
@item c0-control
@acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
excluding the newline and tab characters (normally displayed as escape
sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
emacs, The GNU Emacs Manual}).
@item c1-control
Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
@code{U+009F} (normally displayed as octal escape sequences like
@samp{\230}).
@item format-control
Characters of Unicode General Category `Cf', such as @samp{U+200E}
(Left-to-Right Mark), but excluding characters that have graphic
images, such as @samp{U+00AD} (Soft Hyphen).
@item no-font
Characters for there is no suitable font, or which cannot be encoded
by the terminal's coding system.
@end table
@c FIXME: this can also be `acronym', but that's not currently
@c completely implemented; it applies only to the format-control
@c group, and only works if the acronym is in `char-acronym-table'.
The @var{method} symbol should be one of @code{zero-width},
@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
the same meanings as in @code{glyphless-char-display}, above.
@end defopt
@node Window Systems
@section Window Systems
@ -6290,96 +6372,3 @@ affect all Emacs frames and windows.
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.
@node Glyphless Chars
@section Glyphless Character Display
@cindex glyphless characters
@dfn{Glyphless characters} are not displayed in the usual way when
they appear in a buffer, but in some special way (e.g. as a box
containing a hexadecimal code). These include characters that cannot
be displayed with any available font (on a graphical display), or that
cannot be encoded by the terminal's coding system (on a text
terminal). Specific characters can also be defined to be glyphless.
@defvar glyphless-char-display
The value of this variable is a char-table that defines glyphless
characters and how they are displayed. If an entry is @code{nil}, the
corresponding character is displayed in its usual way. Otherwise, an
entry should be one of the following display methods:
@table @asis
@item @code{zero-width}
Don't display the character.
@item @code{thin-space}
Display a thin space, 1-pixel wide on graphical displays, or
1-character wide on text terminals.
@item @code{empty-box}
Display an empty box.
@item @code{hex-code}
Display a box containing the Unicode codepoint of the character, in
hexadecimal notation.
@item an @acronym{ASCII} string
Display a box containing that string.
@end table
@noindent
Except for @code{zero-width}, these methods display using the
@code{glyphless-char} face.
An entry can also be a cons cell @code{(@var{graphical}
. @var{text})}, where @var{graphical} and @var{text} are the display
methods on graphical displays and text terminals respectively.
The char-table has one extra slot, which determines how to display any
character that cannot be displayed with any available font, or cannot
be encoded by the terminal's coding system. Its value should be one
of the above display methods, except @code{zero-width} or a cons cell.
@end defvar
@defopt glyphless-char-display-control
This user option provides a convenient way to set
@code{glyphless-char-display} for groups of similar characters. It
takes effect via a custom @code{:set} function (@pxref{Variable
Definitions}), which update @code{glyphless-char-display}.
Its value should be an alist of elements @code{(@var{group}
. @var{method})}, where @var{group} is a symbol specifying a group of
characters, and @var{method} is a symbol specifying how to display
them.
@var{group} should be one of the following:
@table @code
@item c0-control
@acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
excluding the newline and tab characters (normally displayed as escape
sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
emacs, The GNU Emacs Manual}).
@item c1-control
Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
@code{U+009F} (normally displayed as octal escape sequences like
@samp{\230}).
@item format-control
Characters of Unicode General Category `Cf', such as @samp{U+200E}
(Left-to-Right Mark), but excluding characters that have graphic
images, such as @samp{U+00AD} (Soft Hyphen).
@item no-font
Characters for there is no suitable font, or which cannot be encoded
by the terminal's coding system.
@end table
@c FIXME: this can also be `acronym', but that's not currently
@c completely implemented; it applies only to the format-control
@c group, and only works if the acronym is in `char-acronym-table'.
The @var{method} symbol should be one of @code{zero-width},
@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
the same meanings as in @code{glyphless-char-display}, above.
@end defopt

15
doc/lispref/elisp.texi
View file

@ -1265,14 +1265,11 @@ Emacs Display
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying
nonprinting chars.
* Display Tables:: How to specify other conventions.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@ -1361,11 +1358,13 @@ Abstract Display
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
Display Tables
Character Display
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Usual Display:: The usual conventions for displaying characters.
* Display Tables:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface

15
doc/lispref/vol1.texi
View file

@ -1287,14 +1287,11 @@ Emacs Display
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying
nonprinting chars.
* Display Tables:: How to specify other conventions.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@ -1383,11 +1380,13 @@ Abstract Display
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
Display Tables
Character Display
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Usual Display:: The usual conventions for displaying characters.
* Display Tables:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface

15
doc/lispref/vol2.texi
View file

@ -1286,14 +1286,11 @@ Emacs Display
* Buttons:: Adding clickable buttons to Emacs buffers.
* Abstract Display:: Emacs's Widget for Object Collections.
* Blinking:: How Emacs shows the matching open parenthesis.
* Usual Display:: The usual conventions for displaying
nonprinting chars.
* Display Tables:: How to specify other conventions.
* Character Display:: How Emacs displays individual characters.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
* Bidirectional Display:: Display of bidirectional scripts, such as
Arabic and Farsi.
* Glyphless Chars:: How glyphless characters are drawn.
The Echo Area
@ -1382,11 +1379,13 @@ Abstract Display
* Abstract Display Functions:: Functions in the Ewoc package.
* Abstract Display Example:: Example of using Ewoc.
Display Tables
Character Display
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Usual Display:: The usual conventions for displaying characters.
* Display Tables:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* Glyphless Chars:: How glyphless characters are drawn.
Operating System Interface

4
lisp/ChangeLog
View file

@ -1,3 +1,7 @@
2012-03-25 Chong Yidong <cyd@gnu.org>
* button.el (button-at): Minor addition to docstring.
2012-03-24 Simon Leinen <simon.leinen@gmail.com>
* vc/vc.el (vc-merge): Fix a prompt.

4
lisp/button.el
View file

@ -349,7 +349,9 @@ Also see `make-text-button'."
;; Finding buttons in a buffer
(defun button-at (pos)
"Return the button at position POS in the current buffer, or nil."
"Return the button at position POS in the current buffer, or nil.
If the button at POS is a text property button, the return value
is a marker pointing to POS."
(let ((button (get-char-property pos 'button)))
(if (or (overlayp button) (null button))
button