mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-15 09:47:20 +00:00
bcf244ef9b
2e2a806
Fix copyright years by hand5badc81
Update copyright year to 2017
7535 lines
299 KiB
Plaintext
7535 lines
299 KiB
Plaintext
@c -*- mode: texinfo; coding: utf-8 -*-
|
||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||
@c Copyright (C) 1990-1995, 1998-2017 Free Software Foundation, Inc.
|
||
@c See the file elisp.texi for copying conditions.
|
||
@node Display
|
||
@chapter Emacs Display
|
||
|
||
This chapter describes a number of features related to the display
|
||
that Emacs presents to the user.
|
||
|
||
@menu
|
||
* Refresh Screen:: Clearing the screen and redrawing everything on it.
|
||
* Forcing Redisplay:: Forcing redisplay.
|
||
* Truncation:: Folding or wrapping long text lines.
|
||
* The Echo Area:: Displaying messages at the bottom of the screen.
|
||
* Warnings:: Displaying warning messages for the user.
|
||
* Invisible Text:: Hiding part of the buffer text.
|
||
* 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.
|
||
* 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 scroll bars.
|
||
* Window Dividers:: Separating windows visually.
|
||
* Display Property:: Enabling special display features.
|
||
* Images:: Displaying images in Emacs buffers.
|
||
* Xwidgets:: Displaying native widgets in Emacs buffers.
|
||
* Buttons:: Adding clickable buttons to Emacs buffers.
|
||
* Abstract Display:: Emacs's Widget for Object Collections.
|
||
* Blinking:: How Emacs shows the matching open parenthesis.
|
||
* Character Display:: How Emacs displays individual characters.
|
||
* Beeping:: Audible signal to the user.
|
||
* Window Systems:: Which window system is being used.
|
||
* Tooltips:: Tooltip display in Emacs.
|
||
* Bidirectional Display:: Display of bidirectional scripts, such as
|
||
Arabic and Farsi.
|
||
@end menu
|
||
|
||
@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
|
||
screen is corrupted.
|
||
|
||
@defun redraw-frame &optional frame
|
||
This function clears and redisplays frame @var{frame}. If @var{frame}
|
||
is omitted or nil, it redraws the selected frame.
|
||
@end defun
|
||
|
||
Even more powerful is @code{redraw-display}:
|
||
|
||
@deffn Command redraw-display
|
||
This function clears and redisplays all visible frames.
|
||
@end deffn
|
||
|
||
In Emacs, processing user input takes priority over redisplay. If
|
||
you call these functions when input is available, they don't redisplay
|
||
immediately, but the requested redisplay does happen
|
||
eventually---after all the input has been processed.
|
||
|
||
On text terminals, suspending and resuming Emacs normally also
|
||
refreshes the screen. Some terminal emulators record separate
|
||
contents for display-oriented programs such as Emacs and for ordinary
|
||
sequential display. If you are using such a terminal, you might want
|
||
to inhibit the redisplay on resumption.
|
||
|
||
@defopt no-redraw-on-reenter
|
||
@cindex suspend (cf. @code{no-redraw-on-reenter})
|
||
@cindex resume (cf. @code{no-redraw-on-reenter})
|
||
This variable controls whether Emacs redraws the entire screen after it
|
||
has been suspended and resumed. Non-@code{nil} means there is no need
|
||
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
|
||
@end defopt
|
||
|
||
@node Forcing Redisplay
|
||
@section Forcing Redisplay
|
||
@cindex forcing redisplay
|
||
|
||
Emacs normally tries to redisplay the screen whenever it waits for
|
||
input. With the following function, you can request an immediate
|
||
attempt to redisplay, in the middle of Lisp code, without actually
|
||
waiting for input.
|
||
|
||
@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.
|
||
|
||
The function returns @code{t} if it actually tried to redisplay, and
|
||
@code{nil} otherwise. A value of @code{t} does not mean that
|
||
redisplay proceeded to completion; it could have been preempted by
|
||
newly arriving input.
|
||
@end defun
|
||
|
||
Although @code{redisplay} tries immediately to redisplay, it does
|
||
not change how Emacs decides which parts of its frame(s) to redisplay.
|
||
By contrast, the following function adds certain windows to the
|
||
pending redisplay work (as if their contents had completely changed),
|
||
but does not immediately try to perform redisplay.
|
||
|
||
@defun force-window-update &optional object
|
||
This function forces some or all windows to be updated the next time
|
||
Emacs does a redisplay. If @var{object} is a window, that window is
|
||
to be updated. If @var{object} is a buffer or buffer name, all
|
||
windows displaying that buffer are to be updated. If @var{object} is
|
||
@code{nil} (or omitted), all windows are to be updated.
|
||
|
||
This function does not do a redisplay immediately; Emacs does that as
|
||
it waits for input, or when the function @code{redisplay} is called.
|
||
@end defun
|
||
|
||
@defvar pre-redisplay-function
|
||
A function run just before redisplay. It is called with one argument,
|
||
the set of windows to be redisplayed. The set can be @code{nil},
|
||
meaning only the selected window, or @code{t}, meaning all the
|
||
windows.
|
||
@end defvar
|
||
|
||
@defvar pre-redisplay-functions
|
||
This hook is run just before redisplay. It is called once in each
|
||
window that is about to be redisplayed, with @code{current-buffer} set
|
||
to the buffer displayed in that window.
|
||
@end defvar
|
||
|
||
@node Truncation
|
||
@section Truncation
|
||
@cindex line wrapping
|
||
@cindex line truncation
|
||
@cindex continuation lines
|
||
@cindex @samp{$} in display
|
||
@cindex @samp{\} in display
|
||
|
||
When a line of text extends beyond the right edge of a window, Emacs
|
||
can @dfn{continue} the line (make it wrap to the next screen
|
||
line), or @dfn{truncate} the line (limit it to one screen line). The
|
||
additional screen lines used to display a long text line are called
|
||
@dfn{continuation} lines. Continuation is not the same as filling;
|
||
continuation happens on the screen only, not in the buffer contents,
|
||
and it breaks a line precisely at the right margin, not at a word
|
||
boundary. @xref{Filling}.
|
||
|
||
On a graphical display, tiny arrow images in the window fringes
|
||
indicate truncated and continued lines (@pxref{Fringes}). On a text
|
||
terminal, a @samp{$} in the rightmost column of the window indicates
|
||
truncation; a @samp{\} on the rightmost column indicates a line that
|
||
wraps. (The display table can specify alternate characters to use
|
||
for this; @pxref{Display Tables}).
|
||
|
||
@defopt truncate-lines
|
||
If this buffer-local variable is non-@code{nil}, lines that extend
|
||
beyond the right edge of the window are truncated; otherwise, they are
|
||
continued. As a special exception, the variable
|
||
@code{truncate-partial-width-windows} takes precedence in
|
||
@dfn{partial-width} windows (i.e., windows that do not occupy the
|
||
entire frame width).
|
||
@end defopt
|
||
|
||
@defopt truncate-partial-width-windows
|
||
@cindex partial-width windows
|
||
This variable controls line truncation in @dfn{partial-width} windows.
|
||
A partial-width window is one that does not occupy the entire frame
|
||
width (@pxref{Splitting Windows}). If the value is @code{nil}, line
|
||
truncation is determined by the variable @code{truncate-lines} (see
|
||
above). If the value is an integer @var{n}, lines are truncated if
|
||
the partial-width window has fewer than @var{n} columns, regardless of
|
||
the value of @code{truncate-lines}; if the partial-width window has
|
||
@var{n} or more columns, line truncation is determined by
|
||
@code{truncate-lines}. For any other non-@code{nil} value, lines are
|
||
truncated in every partial-width window, regardless of the value of
|
||
@code{truncate-lines}.
|
||
@end defopt
|
||
|
||
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
|
||
a window, that forces truncation.
|
||
|
||
@defvar wrap-prefix
|
||
If this buffer-local variable is non-@code{nil}, it defines a
|
||
@dfn{wrap prefix} which Emacs displays at the start of every
|
||
continuation line. (If lines are truncated, @code{wrap-prefix} is
|
||
never used.) Its value may be a string or an image (@pxref{Other
|
||
Display Specs}), or a stretch of whitespace such as specified by the
|
||
@code{:width} or @code{:align-to} display properties (@pxref{Specified
|
||
Space}). The value is interpreted in the same way as a @code{display}
|
||
text property. @xref{Display Property}.
|
||
|
||
A wrap prefix may also be specified for regions of text, using the
|
||
@code{wrap-prefix} text or overlay property. This takes precedence
|
||
over the @code{wrap-prefix} variable. @xref{Special Properties}.
|
||
@end defvar
|
||
|
||
@defvar line-prefix
|
||
If this buffer-local variable is non-@code{nil}, it defines a
|
||
@dfn{line prefix} which Emacs displays at the start of every
|
||
non-continuation line. Its value may be a string or an image
|
||
(@pxref{Other Display Specs}), or a stretch of whitespace such as
|
||
specified by the @code{:width} or @code{:align-to} display properties
|
||
(@pxref{Specified Space}). The value is interpreted in the same way
|
||
as a @code{display} text property. @xref{Display Property}.
|
||
|
||
A line prefix may also be specified for regions of text using the
|
||
@code{line-prefix} text or overlay property. This takes precedence
|
||
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}.
|
||
|
||
@defvar cache-long-scans
|
||
If this variable is non-@code{nil} (the default), various indentation
|
||
and motion functions, and Emacs redisplay, cache the results of
|
||
scanning the buffer, and consult the cache to avoid rescanning regions
|
||
of the buffer unless they are modified.
|
||
|
||
Turning off the cache speeds up processing of short lines somewhat.
|
||
|
||
This variable is automatically buffer-local in every buffer.
|
||
@end defvar
|
||
@end ignore
|
||
|
||
@node The Echo Area
|
||
@section The Echo Area
|
||
@cindex error display
|
||
@cindex echo area
|
||
|
||
@c FIXME: Why not use @xref{Minibuffers} directly? --xfq
|
||
The @dfn{echo area} is used for displaying error messages
|
||
(@pxref{Errors}), for messages made with the @code{message} primitive,
|
||
and for echoing keystrokes. It is not the same as the minibuffer,
|
||
despite the fact that the minibuffer appears (when active) in the same
|
||
place on the screen as the echo area. @xref{Minibuffer,, The
|
||
Minibuffer, emacs, The GNU Emacs Manual}.
|
||
|
||
Apart from the functions documented in this section, you can print
|
||
Lisp objects to the echo area by specifying @code{t} as the output
|
||
stream. @xref{Output Streams}.
|
||
|
||
@menu
|
||
* Displaying Messages:: Explicitly displaying text in the echo area.
|
||
* Progress:: Informing user about progress of a long operation.
|
||
* Logging Messages:: Echo area messages are logged for the user.
|
||
* Echo Area Customization:: Controlling the echo area.
|
||
@end menu
|
||
|
||
@node Displaying Messages
|
||
@subsection Displaying Messages in the Echo Area
|
||
@cindex display message in echo area
|
||
|
||
This section describes the standard functions for displaying
|
||
messages in the echo area.
|
||
|
||
@defun message format-string &rest arguments
|
||
This function displays a message in the echo area.
|
||
@var{format-string} is a format string, and @var{arguments} are the
|
||
objects for its format specifications, like in the @code{format-message}
|
||
function (@pxref{Formatting Strings}). The resulting formatted string
|
||
is displayed in the echo area; if it contains @code{face} text
|
||
properties, it is displayed with the specified faces (@pxref{Faces}).
|
||
The string is also added to the @file{*Messages*} buffer, but without
|
||
text properties (@pxref{Logging Messages}).
|
||
|
||
The @code{text-quoting-style} variable controls what quotes are
|
||
generated; @xref{Keys in Documentation}. A call using a format like
|
||
@t{"Missing `%s'"} with grave accents and apostrophes typically
|
||
generates a message like @t{"Missing ‘foo’"} with matching curved
|
||
quotes. In contrast, a call using a format like @t{"Missing '%s'"}
|
||
with only apostrophes typically generates a message like @t{"Missing
|
||
’foo’"} with only closing curved quotes, an unusual style in English.
|
||
|
||
In batch mode, the message is printed to the standard error stream,
|
||
followed by a newline.
|
||
|
||
When @code{inhibit-message} is non-@code{nil}, no message will be displayed
|
||
in the echo area, it will only be logged to @samp{*Messages*}.
|
||
|
||
If @var{format-string} is @code{nil} or the empty string,
|
||
@code{message} clears the echo area; if the echo area has been
|
||
expanded automatically, this brings it back to its normal size. If
|
||
the minibuffer is active, this brings the minibuffer contents back
|
||
onto the screen immediately.
|
||
|
||
@example
|
||
@group
|
||
(message "Reverting `%s'..." (buffer-name))
|
||
@print{} Reverting ‘subr.el’...
|
||
@result{} "Reverting ‘subr.el’..."
|
||
@end group
|
||
|
||
@group
|
||
---------- Echo Area ----------
|
||
Reverting ‘subr.el’...
|
||
---------- Echo Area ----------
|
||
@end group
|
||
@end example
|
||
|
||
To automatically display a message in the echo area or in a pop-buffer,
|
||
depending on its size, use @code{display-message-or-buffer} (see below).
|
||
|
||
@strong{Warning:} If you want to use your own string as a message
|
||
verbatim, don't just write @code{(message @var{string})}. If
|
||
@var{string} contains @samp{%}, @samp{`}, or @samp{'} it may be
|
||
reformatted, with undesirable results. Instead, use @code{(message
|
||
"%s" @var{string})}.
|
||
@end defun
|
||
|
||
@defvar inhibit-message
|
||
When this variable is non-@code{nil}, @code{message} and related functions
|
||
will not use the Echo Area to display messages.
|
||
@end defvar
|
||
|
||
@defmac with-temp-message message &rest body
|
||
This construct displays a message in the echo area temporarily, during
|
||
the execution of @var{body}. It displays @var{message}, executes
|
||
@var{body}, then returns the value of the last body form while restoring
|
||
the previous echo area contents.
|
||
@end defmac
|
||
|
||
@defun message-or-box format-string &rest arguments
|
||
This function displays a message like @code{message}, but may display it
|
||
in a dialog box instead of the echo area. If this function is called in
|
||
a command that was invoked using the mouse---more precisely, if
|
||
@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either
|
||
@code{nil} or a list---then it uses a dialog box or pop-up menu to
|
||
display the message. Otherwise, it uses the echo area. (This is the
|
||
same criterion that @code{y-or-n-p} uses to make a similar decision; see
|
||
@ref{Yes-or-No Queries}.)
|
||
|
||
You can force use of the mouse or of the echo area by binding
|
||
@code{last-nonmenu-event} to a suitable value around the call.
|
||
@end defun
|
||
|
||
@defun message-box format-string &rest arguments
|
||
@anchor{message-box}
|
||
This function displays a message like @code{message}, but uses a dialog
|
||
box (or a pop-up menu) whenever that is possible. If it is impossible
|
||
to use a dialog box or pop-up menu, because the terminal does not
|
||
support them, then @code{message-box} uses the echo area, like
|
||
@code{message}.
|
||
@end defun
|
||
|
||
@defun display-message-or-buffer message &optional buffer-name action frame
|
||
This function displays the message @var{message}, which may be either a
|
||
string or a buffer. If it is shorter than the maximum height of the
|
||
echo area, as defined by @code{max-mini-window-height}, it is displayed
|
||
in the echo area, using @code{message}. Otherwise,
|
||
@code{display-buffer} is used to show it in a pop-up buffer.
|
||
|
||
Returns either the string shown in the echo area, or when a pop-up
|
||
buffer is used, the window used to display it.
|
||
|
||
If @var{message} is a string, then the optional argument
|
||
@var{buffer-name} is the name of the buffer used to display it when a
|
||
pop-up buffer is used, defaulting to @file{*Message*}. In the case
|
||
where @var{message} is a string and displayed in the echo area, it is
|
||
not specified whether the contents are inserted into the buffer anyway.
|
||
|
||
The optional arguments @var{action} and @var{frame} are as for
|
||
@code{display-buffer}, and only used if a buffer is displayed.
|
||
@end defun
|
||
|
||
@defun current-message
|
||
This function returns the message currently being displayed in the
|
||
echo area, or @code{nil} if there is none.
|
||
@end defun
|
||
|
||
@node Progress
|
||
@subsection Reporting Operation Progress
|
||
@cindex progress reporting
|
||
|
||
When an operation can take a while to finish, you should inform the
|
||
user about the progress it makes. This way the user can estimate
|
||
remaining time and clearly see that Emacs is busy working, not hung.
|
||
A convenient way to do this is to use a @dfn{progress reporter}.
|
||
|
||
Here is a working example that does nothing useful:
|
||
|
||
@smallexample
|
||
(let ((progress-reporter
|
||
(make-progress-reporter "Collecting mana for Emacs..."
|
||
0 500)))
|
||
(dotimes (k 500)
|
||
(sit-for 0.01)
|
||
(progress-reporter-update progress-reporter k))
|
||
(progress-reporter-done progress-reporter))
|
||
@end smallexample
|
||
|
||
@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
|
||
This function creates and returns a progress reporter object, which
|
||
you will use as an argument for the other functions listed below. The
|
||
idea is to precompute as much data as possible to make progress
|
||
reporting very fast.
|
||
|
||
When this progress reporter is subsequently used, it will display
|
||
@var{message} in the echo area, followed by progress percentage.
|
||
@var{message} is treated as a simple string. If you need it to depend
|
||
on a filename, for instance, use @code{format-message} before calling this
|
||
function.
|
||
|
||
The arguments @var{min-value} and @var{max-value} should be numbers
|
||
standing for the starting and final states of the operation. For
|
||
instance, an operation that scans a buffer should set these to the
|
||
results of @code{point-min} and @code{point-max} correspondingly.
|
||
@var{max-value} should be greater than @var{min-value}.
|
||
|
||
Alternatively, you can set @var{min-value} and @var{max-value} to
|
||
@code{nil}. In that case, the progress reporter does not report
|
||
process percentages; it instead displays a ``spinner'' that rotates a
|
||
notch each time you update the progress reporter.
|
||
|
||
If @var{min-value} and @var{max-value} are numbers, you can give the
|
||
argument @var{current-value} a numerical value specifying the initial
|
||
progress; if omitted, this defaults to @var{min-value}.
|
||
|
||
The remaining arguments control the rate of echo area updates. The
|
||
progress reporter will wait for at least @var{min-change} more
|
||
percents of the operation to be completed before printing next
|
||
message; the default is one percent. @var{min-time} specifies the
|
||
minimum time in seconds to pass between successive prints; the default
|
||
is 0.2 seconds. (On some operating systems, the progress reporter may
|
||
handle fractions of seconds with varying precision).
|
||
|
||
This function calls @code{progress-reporter-update}, so the first
|
||
message is printed immediately.
|
||
@end defun
|
||
|
||
@defun progress-reporter-update reporter &optional value
|
||
This function does the main work of reporting progress of your
|
||
operation. It displays the message of @var{reporter}, followed by
|
||
progress percentage determined by @var{value}. If percentage is zero,
|
||
or close enough according to the @var{min-change} and @var{min-time}
|
||
arguments, then it is omitted from the output.
|
||
|
||
@var{reporter} must be the result of a call to
|
||
@code{make-progress-reporter}. @var{value} specifies the current
|
||
state of your operation and must be between @var{min-value} and
|
||
@var{max-value} (inclusive) as passed to
|
||
@code{make-progress-reporter}. For instance, if you scan a buffer,
|
||
then @var{value} should be the result of a call to @code{point}.
|
||
|
||
This function respects @var{min-change} and @var{min-time} as passed
|
||
to @code{make-progress-reporter} and so does not output new messages
|
||
on every invocation. It is thus very fast and normally you should not
|
||
try to reduce the number of calls to it: resulting overhead will most
|
||
likely negate your effort.
|
||
@end defun
|
||
|
||
@defun progress-reporter-force-update reporter &optional value new-message
|
||
This function is similar to @code{progress-reporter-update} except
|
||
that it prints a message in the echo area unconditionally.
|
||
|
||
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 function
|
||
always updates the echo area, such a change will be immediately
|
||
presented to the user.
|
||
@end defun
|
||
|
||
@defun progress-reporter-done reporter
|
||
This function should be called when the operation is finished. It
|
||
prints the message of @var{reporter} followed by word @samp{done} in the
|
||
echo area.
|
||
|
||
You should always call this function and not hope for
|
||
@code{progress-reporter-update} to print @samp{100%}. Firstly, it may
|
||
never print it, there are many good reasons for this not to happen.
|
||
Secondly, @samp{done} is more explicit.
|
||
@end defun
|
||
|
||
@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
|
||
This is a convenience macro that works the same way as @code{dotimes}
|
||
does, but also reports loop progress using the functions described
|
||
above. It allows you to save some typing.
|
||
|
||
You can rewrite the example in the beginning of this node using
|
||
this macro this way:
|
||
|
||
@example
|
||
(dotimes-with-progress-reporter
|
||
(k 500)
|
||
"Collecting some mana for Emacs..."
|
||
(sit-for 0.01))
|
||
@end example
|
||
@end defmac
|
||
|
||
@node Logging Messages
|
||
@subsection Logging Messages in @file{*Messages*}
|
||
@cindex logging echo-area messages
|
||
|
||
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}. 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*}
|
||
buffer. The value @code{t} means there is no limit on how many lines to
|
||
keep. The value @code{nil} disables message logging entirely. Here's
|
||
how to display a message and prevent it from being logged:
|
||
|
||
@example
|
||
(let (message-log-max)
|
||
(message @dots{}))
|
||
@end example
|
||
@end defopt
|
||
|
||
To make @file{*Messages*} more convenient for the user, the logging
|
||
facility combines successive identical messages. It also combines
|
||
successive related messages for the sake of two cases: question
|
||
followed by answer, and a series of progress messages.
|
||
|
||
A question followed by an answer has two messages like the
|
||
ones produced by @code{y-or-n-p}: the first is @samp{@var{question}},
|
||
and the second is @samp{@var{question}...@var{answer}}. The first
|
||
message conveys no additional information beyond what's in the second,
|
||
so logging the second message discards the first from the log.
|
||
|
||
A series of progress messages has successive messages like
|
||
those produced by @code{make-progress-reporter}. They have the form
|
||
@samp{@var{base}...@var{how-far}}, where @var{base} is the same each
|
||
time, while @var{how-far} varies. Logging each message in the series
|
||
discards the previous one, provided they are consecutive.
|
||
|
||
The functions @code{make-progress-reporter} and @code{y-or-n-p}
|
||
don't have to do anything special to activate the message log
|
||
combination feature. It operates whenever two consecutive messages
|
||
are logged that share a common prefix ending in @samp{...}.
|
||
|
||
@node Echo Area Customization
|
||
@subsection Echo Area Customization
|
||
@cindex echo area customization
|
||
|
||
These variables control details of how the echo area works.
|
||
|
||
@defvar cursor-in-echo-area
|
||
This variable controls where the cursor appears when a message is
|
||
displayed in the echo area. If it is non-@code{nil}, then the cursor
|
||
appears at the end of the message. Otherwise, the cursor appears at
|
||
point---not in the echo area at all.
|
||
|
||
The value is normally @code{nil}; Lisp programs bind it to @code{t}
|
||
for brief periods of time.
|
||
@end defvar
|
||
|
||
@defvar echo-area-clear-hook
|
||
This normal hook is run whenever the echo area is cleared---either by
|
||
@code{(message nil)} or for any other reason.
|
||
@end defvar
|
||
|
||
@defopt echo-keystrokes
|
||
This variable determines how much time should elapse before command
|
||
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
|
||
begins in a key sequence, all subsequent characters in the same key
|
||
sequence are echoed immediately.)
|
||
|
||
If the value is zero, then command input is not echoed.
|
||
@end defopt
|
||
|
||
@defvar message-truncate-lines
|
||
Normally, displaying a long message resizes the echo area to display
|
||
the entire message. But if the variable @code{message-truncate-lines}
|
||
is non-@code{nil}, the echo area does not resize, and the message is
|
||
truncated to fit it.
|
||
@end defvar
|
||
|
||
The variable @code{max-mini-window-height}, which specifies the
|
||
maximum height for resizing minibuffer windows, also applies to the
|
||
echo area (which is really a special use of the minibuffer window;
|
||
@pxref{Minibuffer Misc}).
|
||
|
||
@node Warnings
|
||
@section Reporting Warnings
|
||
@cindex warnings
|
||
|
||
@dfn{Warnings} are a facility for a program to inform the user of a
|
||
possible problem, but continue running.
|
||
|
||
@menu
|
||
* Warning Basics:: Warnings concepts and functions to report them.
|
||
* Warning Variables:: Variables programs bind to customize their warnings.
|
||
* Warning Options:: Variables users set to control display of warnings.
|
||
* Delayed Warnings:: Deferring a warning until the end of a command.
|
||
@end menu
|
||
|
||
@node Warning Basics
|
||
@subsection Warning Basics
|
||
@cindex severity level
|
||
|
||
Every warning has a textual message, which explains the problem for
|
||
the user, and a @dfn{severity level} which is a symbol. Here are the
|
||
possible severity levels, in order of decreasing severity, and their
|
||
meanings:
|
||
|
||
@table @code
|
||
@item :emergency
|
||
A problem that will seriously impair Emacs operation soon
|
||
if you do not attend to it promptly.
|
||
@item :error
|
||
A report of data or circumstances that are inherently wrong.
|
||
@item :warning
|
||
A report of data or circumstances that are not inherently wrong, but
|
||
raise suspicion of a possible problem.
|
||
@item :debug
|
||
A report of information that may be useful if you are debugging.
|
||
@end table
|
||
|
||
When your program encounters invalid input data, it can either
|
||
signal a Lisp error by calling @code{error} or @code{signal} or report
|
||
a warning with severity @code{:error}. Signaling a Lisp error is the
|
||
easiest thing to do, but it means the program cannot continue
|
||
processing. If you want to take the trouble to implement a way to
|
||
continue processing despite the bad data, then reporting a warning of
|
||
severity @code{:error} is the right way to inform the user of the
|
||
problem. For instance, the Emacs Lisp byte compiler can report an
|
||
error that way and continue compiling other functions. (If the
|
||
program signals a Lisp error and then handles it with
|
||
@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 not part of the warning type. --xfq
|
||
@cindex warning type
|
||
Each warning has a @dfn{warning type} to classify it. The type is a
|
||
list of symbols. The first symbol should be the custom group that you
|
||
use for the program's user options. For example, byte compiler
|
||
warnings use the warning type @code{(bytecomp)}. You can also
|
||
subcategorize the warnings, if you wish, by using more symbols in the
|
||
list.
|
||
|
||
@defun display-warning type message &optional level buffer-name
|
||
This function reports a warning, using @var{message} as the message
|
||
and @var{type} as the warning type. @var{level} should be the
|
||
severity level, with @code{:warning} being the default.
|
||
|
||
@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer
|
||
for logging the warning. By default, it is @file{*Warnings*}.
|
||
@end defun
|
||
|
||
@defun lwarn type level message &rest args
|
||
This function reports a warning using the value of @code{(format-message
|
||
@var{message} @var{args}...)} as the message in the @file{*Warnings*}
|
||
buffer. In other respects it is equivalent to @code{display-warning}.
|
||
@end defun
|
||
|
||
@defun warn message &rest args
|
||
This function reports a warning using the value of @code{(format-message
|
||
@var{message} @var{args}...)} as the message, @code{(emacs)} as the
|
||
type, and @code{:warning} as the severity level. It exists for
|
||
compatibility only; we recommend not using it, because you should
|
||
specify a specific warning type.
|
||
@end defun
|
||
|
||
@node Warning Variables
|
||
@subsection Warning Variables
|
||
@cindex warning variables
|
||
|
||
Programs can customize how their warnings appear by binding
|
||
the variables described in this section.
|
||
|
||
@defvar warning-levels
|
||
This list defines the meaning and severity order of the warning
|
||
severity levels. Each element defines one severity level,
|
||
and they are arranged in order of decreasing severity.
|
||
|
||
Each element has the form @code{(@var{level} @var{string}
|
||
@var{function})}, where @var{level} is the severity level it defines.
|
||
@var{string} specifies the textual description of this level.
|
||
@var{string} should use @samp{%s} to specify where to put the warning
|
||
type information, or it can omit the @samp{%s} so as not to include
|
||
that information.
|
||
|
||
The optional @var{function}, if non-@code{nil}, is a function to call
|
||
with no arguments, to get the user's attention.
|
||
|
||
Normally you should not change the value of this variable.
|
||
@end defvar
|
||
|
||
@defvar warning-prefix-function
|
||
If non-@code{nil}, the value is a function to generate prefix text for
|
||
warnings. Programs can bind the variable to a suitable function.
|
||
@code{display-warning} calls this function with the warnings buffer
|
||
current, and the function can insert text in it. That text becomes
|
||
the beginning of the warning message.
|
||
|
||
The function is called with two arguments, the severity level and its
|
||
entry in @code{warning-levels}. It should return a list to use as the
|
||
entry (this value need not be an actual member of
|
||
@code{warning-levels}). By constructing this value, the function can
|
||
change the severity of the warning, or specify different handling for
|
||
a given severity level.
|
||
|
||
If the variable's value is @code{nil} then there is no function
|
||
to call.
|
||
@end defvar
|
||
|
||
@defvar warning-series
|
||
Programs can bind this variable to @code{t} to say that the next
|
||
warning should begin a series. When several warnings form a series,
|
||
that means to leave point on the first warning of the series, rather
|
||
than keep moving it for each warning so that it appears on the last one.
|
||
The series ends when the local binding is unbound and
|
||
@code{warning-series} becomes @code{nil} again.
|
||
|
||
The value can also be a symbol with a function definition. That is
|
||
equivalent to @code{t}, except that the next warning will also call
|
||
the function with no arguments with the warnings buffer current. The
|
||
function can insert text which will serve as a header for the series
|
||
of warnings.
|
||
|
||
Once a series has begun, the value is a marker which points to the
|
||
buffer position in the warnings buffer of the start of the series.
|
||
|
||
The variable's normal value is @code{nil}, which means to handle
|
||
each warning separately.
|
||
@end defvar
|
||
|
||
@defvar warning-fill-prefix
|
||
When this variable is non-@code{nil}, it specifies a fill prefix to
|
||
use for filling each warning's text.
|
||
@end defvar
|
||
|
||
@defvar warning-type-format
|
||
This variable specifies the format for displaying the warning type
|
||
in the warning message. The result of formatting the type this way
|
||
gets included in the message under the control of the string in the
|
||
entry in @code{warning-levels}. The default value is @code{" (%s)"}.
|
||
If you bind it to @code{""} then the warning type won't appear at
|
||
all.
|
||
@end defvar
|
||
|
||
@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.
|
||
|
||
@defopt warning-minimum-level
|
||
This user option specifies the minimum severity level that should be
|
||
shown immediately to the user. The default is @code{:warning}, which
|
||
means to immediately display all warnings except @code{:debug}
|
||
warnings.
|
||
@end defopt
|
||
|
||
@defopt warning-minimum-log-level
|
||
This user option specifies the minimum severity level that should be
|
||
logged in the warnings buffer. The default is @code{:warning}, which
|
||
means to log all warnings except @code{:debug} warnings.
|
||
@end defopt
|
||
|
||
@defopt warning-suppress-types
|
||
This list specifies which warning types should not be displayed
|
||
immediately for the user. Each element of the list should be a list
|
||
of symbols. If its elements match the first elements in a warning
|
||
type, then that warning is not displayed immediately.
|
||
@end defopt
|
||
|
||
@defopt warning-suppress-log-types
|
||
This list specifies which warning types should not be logged in the
|
||
warnings buffer. Each element of the list should be a list of
|
||
symbols. If it matches the first few elements in a warning type, then
|
||
that warning is not logged.
|
||
@end defopt
|
||
|
||
@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
|
||
use the variable @code{delayed-warnings-list} for this.
|
||
|
||
@defvar delayed-warnings-list
|
||
The value of this variable is a list of warnings to be displayed after
|
||
the current command has finished. Each element must be a list
|
||
|
||
@smallexample
|
||
(@var{type} @var{message} [@var{level} [@var{buffer-name}]])
|
||
@end smallexample
|
||
|
||
@noindent
|
||
with the same form, and the same meanings, as the argument list of
|
||
@code{display-warning} (@pxref{Warning Basics}). Immediately after
|
||
running @code{post-command-hook} (@pxref{Command Overview}), the Emacs
|
||
command loop displays all the warnings specified by this variable,
|
||
then resets it to @code{nil}.
|
||
@end defvar
|
||
|
||
Programs which need to further customize the delayed warnings
|
||
mechanism can change the variable @code{delayed-warnings-hook}:
|
||
|
||
@defvar delayed-warnings-hook
|
||
This is a normal hook which is run by the Emacs command loop, after
|
||
@code{post-command-hook}, in order to to process and display delayed
|
||
warnings.
|
||
|
||
Its default value is a list of two functions:
|
||
|
||
@smallexample
|
||
(collapse-delayed-warnings display-delayed-warnings)
|
||
@end smallexample
|
||
|
||
@findex collapse-delayed-warnings
|
||
@findex display-delayed-warnings
|
||
@noindent
|
||
The function @code{collapse-delayed-warnings} removes repeated entries
|
||
from @code{delayed-warnings-list}. The function
|
||
@code{display-delayed-warnings} calls @code{display-warning} on each
|
||
of the entries in @code{delayed-warnings-list}, in turn, and then sets
|
||
@code{delayed-warnings-list} to @code{nil}.
|
||
@end defvar
|
||
|
||
@node Invisible Text
|
||
@section Invisible Text
|
||
|
||
@cindex invisible text
|
||
You can make characters @dfn{invisible}, so that they do not appear on
|
||
the screen, with the @code{invisible} property. This can be either a
|
||
text property (@pxref{Text Properties}) or an overlay property
|
||
(@pxref{Overlays}). Cursor motion also partly ignores these
|
||
characters; if the command loop finds that point is inside a range of
|
||
invisible text after a command, it relocates point to the other side
|
||
of the text.
|
||
|
||
In the simplest case, any non-@code{nil} @code{invisible} property makes
|
||
a character invisible. This is the default case---if you don't alter
|
||
the default value of @code{buffer-invisibility-spec}, this is how the
|
||
@code{invisible} property works. You should normally use @code{t}
|
||
as the value of the @code{invisible} property if you don't plan
|
||
to set @code{buffer-invisibility-spec} yourself.
|
||
|
||
More generally, you can use the variable @code{buffer-invisibility-spec}
|
||
to control which values of the @code{invisible} property make text
|
||
invisible. This permits you to classify the text into different subsets
|
||
in advance, by giving them different @code{invisible} values, and
|
||
subsequently make various subsets visible or invisible by changing the
|
||
value of @code{buffer-invisibility-spec}.
|
||
|
||
Controlling visibility with @code{buffer-invisibility-spec} is
|
||
especially useful in a program to display the list of entries in a
|
||
database. It permits the implementation of convenient filtering
|
||
commands to view just a part of the entries in the database. Setting
|
||
this variable is very fast, much faster than scanning all the text in
|
||
the buffer looking for properties to change.
|
||
|
||
@defvar buffer-invisibility-spec
|
||
This variable specifies which kinds of @code{invisible} properties
|
||
actually make a character invisible. Setting this variable makes it
|
||
buffer-local.
|
||
|
||
@table @asis
|
||
@item @code{t}
|
||
A character is invisible if its @code{invisible} property is
|
||
non-@code{nil}. This is the default.
|
||
|
||
@item a list
|
||
Each element of the list specifies a criterion for invisibility; if a
|
||
character's @code{invisible} property fits any one of these criteria,
|
||
the character is invisible. The list can have two kinds of elements:
|
||
|
||
@table @code
|
||
@item @var{atom}
|
||
A character is invisible if its @code{invisible} property value is
|
||
@var{atom} or if it is a list with @var{atom} as a member; comparison
|
||
is done with @code{eq}.
|
||
|
||
@item (@var{atom} . t)
|
||
A character is invisible if its @code{invisible} property value is
|
||
@var{atom} or if it is a list with @var{atom} as a member; comparison
|
||
is done with @code{eq}. Moreover, a sequence of such characters
|
||
displays as an ellipsis.
|
||
@end table
|
||
@end table
|
||
@end defvar
|
||
|
||
Two functions are specifically provided for adding elements to
|
||
@code{buffer-invisibility-spec} and removing elements from it.
|
||
|
||
@defun add-to-invisibility-spec element
|
||
This function adds the element @var{element} to
|
||
@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec}
|
||
was @code{t}, it changes to a list, @code{(t)}, so that text whose
|
||
@code{invisible} property is @code{t} remains invisible.
|
||
@end defun
|
||
|
||
@defun remove-from-invisibility-spec element
|
||
This removes the element @var{element} from
|
||
@code{buffer-invisibility-spec}. This does nothing if @var{element}
|
||
is not in the list.
|
||
@end defun
|
||
|
||
A convention for use of @code{buffer-invisibility-spec} is that a
|
||
major mode should use the mode's own name as an element of
|
||
@code{buffer-invisibility-spec} and as the value of the
|
||
@code{invisible} property:
|
||
|
||
@example
|
||
;; @r{If you want to display an ellipsis:}
|
||
(add-to-invisibility-spec '(my-symbol . t))
|
||
;; @r{If you don't want ellipsis:}
|
||
(add-to-invisibility-spec 'my-symbol)
|
||
|
||
(overlay-put (make-overlay beginning end)
|
||
'invisible 'my-symbol)
|
||
|
||
;; @r{When done with the invisibility:}
|
||
(remove-from-invisibility-spec '(my-symbol . t))
|
||
;; @r{Or respectively:}
|
||
(remove-from-invisibility-spec 'my-symbol)
|
||
@end example
|
||
|
||
You can check for invisibility using the following function:
|
||
|
||
@defun invisible-p pos-or-prop
|
||
If @var{pos-or-prop} is a marker or number, this function returns a
|
||
non-@code{nil} value if the text at that position is invisible.
|
||
|
||
If @var{pos-or-prop} is any other kind of Lisp object, that is taken
|
||
to mean a possible value of the @code{invisible} text or overlay
|
||
property. In that case, this function returns a non-@code{nil} value
|
||
if that value would cause text to become invisible, based on the
|
||
current value of @code{buffer-invisibility-spec}.
|
||
@end defun
|
||
|
||
@vindex line-move-ignore-invisible
|
||
Ordinarily, functions that operate on text or move point do not care
|
||
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
|
||
the command; if in doubt, it prefers a position where an inserted char
|
||
would not inherit the @code{invisible} property. Additionally, if the
|
||
text is not replaced by an ellipsis and the command only moved within
|
||
the invisible text, then point is moved one extra character so as to
|
||
try and reflect the command's movement by a visible movement of the
|
||
cursor.
|
||
|
||
Thus, if the command moved point back to an invisible range (with the usual
|
||
stickiness), Emacs moves point back to the beginning of that range. If the
|
||
command moved point forward into an invisible range, Emacs moves point forward
|
||
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}
|
||
@code{isearch-open-invisible} property. The property value should be a
|
||
function to be called with the overlay as an argument. This function
|
||
should make the overlay visible permanently; it is used when the match
|
||
overlaps the overlay on exit from the search.
|
||
|
||
During the search, such overlays are made temporarily visible by
|
||
temporarily modifying their invisible and intangible properties. If you
|
||
want this to be done differently for a certain overlay, give it an
|
||
@code{isearch-open-invisible-temporary} property which is a function.
|
||
The function is called with two arguments: the first is the overlay, and
|
||
the second is @code{nil} to make the overlay visible, or @code{t} to
|
||
make it invisible again.
|
||
|
||
@node Selective Display
|
||
@section Selective Display
|
||
@c @cindex selective display Duplicates selective-display
|
||
|
||
@dfn{Selective display} refers to a pair of related features for
|
||
hiding certain lines on the screen.
|
||
|
||
@cindex explicit selective display
|
||
The first variant, explicit selective display, was designed for use in a Lisp
|
||
program: it controls which lines are hidden by altering the text. This kind of
|
||
hiding is now obsolete; instead you can get the same effect with the
|
||
@code{invisible} property (@pxref{Invisible Text}).
|
||
|
||
In the second variant, the choice of lines to hide is made
|
||
automatically based on indentation. This variant is designed to be a
|
||
user-level feature.
|
||
|
||
The way you control explicit selective display is by replacing a
|
||
newline (control-j) with a carriage return (control-m). The text that
|
||
was formerly a line following that newline is now hidden. Strictly
|
||
speaking, it is temporarily no longer a line at all, since only
|
||
newlines can separate lines; it is now part of the previous line.
|
||
|
||
Selective display does not directly affect editing commands. For
|
||
example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly
|
||
into hidden text. However, the replacement of newline characters with
|
||
carriage return characters affects some editing commands. For
|
||
example, @code{next-line} skips hidden lines, since it searches only
|
||
for newlines. Modes that use selective display can also define
|
||
commands that take account of the newlines, or that control which
|
||
parts of the text are hidden.
|
||
|
||
When you write a selectively displayed buffer into a file, all the
|
||
control-m's are output as newlines. This means that when you next read
|
||
in the file, it looks OK, with nothing hidden. The selective display
|
||
effect is seen only within Emacs.
|
||
|
||
@defvar selective-display
|
||
This buffer-local variable enables selective display. This means that
|
||
lines, or portions of lines, may be made hidden.
|
||
|
||
@itemize @bullet
|
||
@item
|
||
If the value of @code{selective-display} is @code{t}, then the character
|
||
control-m marks the start of hidden text; the control-m, and the rest
|
||
of the line following it, are not displayed. This is explicit selective
|
||
display.
|
||
|
||
@item
|
||
If the value of @code{selective-display} is a positive integer, then
|
||
lines that start with more than that many columns of indentation are not
|
||
displayed.
|
||
@end itemize
|
||
|
||
When some portion of a buffer is hidden, the vertical movement
|
||
commands operate as if that portion did not exist, allowing a single
|
||
@code{next-line} command to skip any number of hidden lines.
|
||
However, character movement commands (such as @code{forward-char}) do
|
||
not skip the hidden portion, and it is possible (if tricky) to insert
|
||
or delete text in an hidden portion.
|
||
|
||
In the examples below, we show the @emph{display appearance} of the
|
||
buffer @code{foo}, which changes with the value of
|
||
@code{selective-display}. The @emph{contents} of the buffer do not
|
||
change.
|
||
|
||
@example
|
||
@group
|
||
(setq selective-display nil)
|
||
@result{} nil
|
||
|
||
---------- Buffer: foo ----------
|
||
1 on this column
|
||
2on this column
|
||
3n this column
|
||
3n this column
|
||
2on this column
|
||
1 on this column
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
|
||
@group
|
||
(setq selective-display 2)
|
||
@result{} 2
|
||
|
||
---------- Buffer: foo ----------
|
||
1 on this column
|
||
2on this column
|
||
2on this column
|
||
1 on this column
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
@end example
|
||
@end defvar
|
||
|
||
@defopt selective-display-ellipses
|
||
If this buffer-local variable is non-@code{nil}, then Emacs displays
|
||
@samp{@dots{}} at the end of a line that is followed by hidden text.
|
||
This example is a continuation of the previous one.
|
||
|
||
@example
|
||
@group
|
||
(setq selective-display-ellipses t)
|
||
@result{} t
|
||
|
||
---------- Buffer: foo ----------
|
||
1 on this column
|
||
2on this column ...
|
||
2on this column
|
||
1 on this column
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
@end example
|
||
|
||
You can use a display table to substitute other text for the ellipsis
|
||
(@samp{@dots{}}). @xref{Display Tables}.
|
||
@end defopt
|
||
|
||
@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 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.
|
||
|
||
@code{with-output-to-temp-buffer} binds @code{standard-output} to the
|
||
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{body} is returned.
|
||
|
||
@example
|
||
@group
|
||
---------- Buffer: foo ----------
|
||
This is the contents of foo.
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
|
||
@group
|
||
(with-output-to-temp-buffer "foo"
|
||
(print 20)
|
||
(print standard-output))
|
||
@result{} #<buffer foo>
|
||
|
||
---------- Buffer: foo ----------
|
||
|
||
20
|
||
|
||
#<buffer foo>
|
||
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
@end example
|
||
@end defmac
|
||
|
||
@defopt temp-buffer-show-function
|
||
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
|
||
calls it as a function to do the job of displaying a help buffer. The
|
||
function gets one argument, which is the buffer it should display.
|
||
|
||
It is a good idea for this function to run @code{temp-buffer-show-hook}
|
||
just as @code{with-output-to-temp-buffer} normally would, inside of
|
||
@code{save-selected-window} and with the chosen window and buffer
|
||
selected.
|
||
@end defopt
|
||
|
||
@defvar temp-buffer-setup-hook
|
||
This normal hook is run by @code{with-output-to-temp-buffer} before
|
||
evaluating @var{body}. When the hook runs, the temporary buffer is
|
||
current. This hook is normally set up with a function to put the
|
||
buffer in Help mode.
|
||
@end defvar
|
||
|
||
@defvar temp-buffer-show-hook
|
||
This normal hook is run by @code{with-output-to-temp-buffer} after
|
||
displaying the temporary buffer. When the hook runs, the temporary buffer
|
||
is current, and the window it was displayed in is selected.
|
||
@end defvar
|
||
|
||
@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.
|
||
|
||
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}
|
||
(@pxref{Choosing Window}) in order to display the buffer.
|
||
|
||
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
|
||
This macro uses the normal hooks @code{temp-buffer-window-setup-hook}
|
||
and @code{temp-buffer-window-show-hook} in place of the analogous hooks
|
||
run by @code{with-output-to-temp-buffer}.
|
||
@end defmac
|
||
|
||
The two constructs described next are mostly identical to
|
||
@code{with-temp-buffer-window} but differ from it as specified:
|
||
|
||
@defmac with-current-buffer-window buffer-or-name action quit-function &rest body
|
||
This macro is like @code{with-temp-buffer-window} but unlike that makes
|
||
the buffer specified by @var{buffer-or-name} current for running
|
||
@var{body}.
|
||
@end defmac
|
||
|
||
@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body
|
||
This macro is like @code{with-current-buffer-window} but unlike that
|
||
displays the buffer specified by @var{buffer-or-name} @emph{before}
|
||
running @var{body}.
|
||
@end defmac
|
||
|
||
A window showing a temporary buffer can be fit to the size of that
|
||
buffer using the following mode:
|
||
|
||
@defopt temp-buffer-resize-mode
|
||
When this minor mode is enabled, windows showing a temporary buffer are
|
||
automatically resized to fit their buffer's contents.
|
||
|
||
A window is resized if and only if it has been specially created for the
|
||
buffer. In particular, windows that have shown another buffer before
|
||
are not resized. By default, this mode uses @code{fit-window-to-buffer}
|
||
(@pxref{Resizing Windows}) for resizing. You can specify a different
|
||
function by customizing the options @code{temp-buffer-max-height} and
|
||
@code{temp-buffer-max-width} below.
|
||
@end defopt
|
||
|
||
@defopt temp-buffer-max-height
|
||
This option specifies the maximum height (in lines) of a window
|
||
displaying a temporary buffer when @code{temp-buffer-resize-mode} is
|
||
enabled. It can also be a function to be called to choose the height
|
||
for such a buffer. It gets one argument, the buffer, and should return
|
||
a positive integer. At the time the function is called, the window to
|
||
be resized is selected.
|
||
@end defopt
|
||
|
||
@defopt temp-buffer-max-width
|
||
This option specifies the maximum width of a window (in columns)
|
||
displaying a temporary buffer when @code{temp-buffer-resize-mode} is
|
||
enabled. It can also be a function to be called to choose the width for
|
||
such a buffer. It gets one argument, the buffer, and should return a
|
||
positive integer. At the time the function is called, the window to be
|
||
resized is selected.
|
||
@end defopt
|
||
|
||
The following function uses the current buffer for temporal display:
|
||
|
||
@defun momentary-string-display string position &optional char message
|
||
This function momentarily displays @var{string} in the current buffer at
|
||
@var{position}. It has no effect on the undo list or on the buffer's
|
||
modification status.
|
||
|
||
The momentary display remains until the next input event. If the next
|
||
input event is @var{char}, @code{momentary-string-display} ignores it
|
||
and returns. Otherwise, that event remains buffered for subsequent use
|
||
as input. Thus, typing @var{char} will simply remove the string from
|
||
the display, while typing (say) @kbd{C-f} will remove the string from
|
||
the display and later (presumably) move point forward. The argument
|
||
@var{char} is a space by default.
|
||
|
||
The return value of @code{momentary-string-display} is not meaningful.
|
||
|
||
If the string @var{string} does not contain control characters, you can
|
||
do the same job in a more general way by creating (and then subsequently
|
||
deleting) an overlay with a @code{before-string} property.
|
||
@xref{Overlay Properties}.
|
||
|
||
If @var{message} is non-@code{nil}, it is displayed in the echo area
|
||
while @var{string} is displayed in the buffer. If it is @code{nil}, a
|
||
default message says to type @var{char} to continue.
|
||
|
||
In this example, point is initially located at the beginning of the
|
||
second line:
|
||
|
||
@example
|
||
@group
|
||
---------- Buffer: foo ----------
|
||
This is the contents of foo.
|
||
@point{}Second line.
|
||
---------- Buffer: foo ----------
|
||
@end group
|
||
|
||
@group
|
||
(momentary-string-display
|
||
"**** Important Message! ****"
|
||
(point) ?\r
|
||
"Type RET when done reading")
|
||
@result{} t
|
||
@end group
|
||
|
||
@group
|
||
---------- Buffer: foo ----------
|
||
This is the contents of foo.
|
||
**** Important Message! ****Second line.
|
||
---------- Buffer: foo ----------
|
||
|
||
---------- Echo Area ----------
|
||
Type RET when done reading
|
||
---------- Echo Area ----------
|
||
@end group
|
||
@end example
|
||
@end defun
|
||
|
||
@node Overlays
|
||
@section Overlays
|
||
@cindex overlays
|
||
@c FIXME: mention intervals in this section?
|
||
|
||
You can use @dfn{overlays} to alter the appearance of a buffer's text on
|
||
the screen, for the sake of presentation features. An overlay is an
|
||
object that belongs to a particular buffer, and has a specified
|
||
beginning and end. It also has properties that you can examine and set;
|
||
these affect the display of the text within the overlay.
|
||
|
||
@cindex scalability of overlays
|
||
@cindex overlays, scalability
|
||
The visual effect of an overlay is the same as of the corresponding
|
||
text property (@pxref{Text Properties}). However, due to a different
|
||
implementation, overlays generally don't scale well (many operations
|
||
take a time that is proportional to the number of overlays in the
|
||
buffer). If you need to affect the visual appearance of many portions
|
||
in the buffer, we recommend using text properties.
|
||
|
||
An overlay uses markers to record its beginning and end; thus,
|
||
editing the text of the buffer adjusts the beginning and end of each
|
||
overlay so that it stays with the text. When you create the overlay,
|
||
you can specify whether text inserted at the beginning should be
|
||
inside the overlay or outside, and likewise for the end of the overlay.
|
||
|
||
@menu
|
||
* Managing Overlays:: Creating and moving overlays.
|
||
* Overlay Properties:: How to read and set properties.
|
||
What properties do to the screen display.
|
||
* Finding Overlays:: Searching for overlays.
|
||
@end menu
|
||
|
||
@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
|
||
recorded in the buffer's undo list, since the overlays are not
|
||
part of the buffer's contents.
|
||
|
||
@defun overlayp object
|
||
This function returns @code{t} if @var{object} is an overlay.
|
||
@end defun
|
||
|
||
@defun make-overlay start end &optional buffer front-advance rear-advance
|
||
This function creates and returns an overlay that belongs to
|
||
@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
|
||
and @var{end} must specify buffer positions; they may be integers or
|
||
markers. If @var{buffer} is omitted, the overlay is created in the
|
||
current buffer.
|
||
|
||
@cindex empty overlay
|
||
@cindex overlay, empty
|
||
An overlay whose @var{start} and @var{end} specify the same buffer
|
||
position is known as @dfn{empty}. A non-empty overlay can become
|
||
empty if the text between its @var{start} and @var{end} is deleted.
|
||
When that happens, the overlay is by default not deleted, but you can
|
||
cause it to be deleted by giving it the @samp{evaporate} property
|
||
(@pxref{Overlay Properties, evaporate property}).
|
||
|
||
The arguments @var{front-advance} and @var{rear-advance} specify the
|
||
marker insertion type for the start of the overlay and for the end of
|
||
the overlay, respectively. @xref{Marker Insertion Types}. If they
|
||
are both @code{nil}, the default, then the overlay extends to include
|
||
any text inserted at the beginning, but not text inserted at the end.
|
||
If @var{front-advance} is non-@code{nil}, text inserted at the
|
||
beginning of the overlay is excluded from the overlay. If
|
||
@var{rear-advance} is non-@code{nil}, text inserted at the end of the
|
||
overlay is included in the overlay.
|
||
@end defun
|
||
|
||
@defun overlay-start overlay
|
||
This function returns the position at which @var{overlay} starts,
|
||
as an integer.
|
||
@end defun
|
||
|
||
@defun overlay-end overlay
|
||
This function returns the position at which @var{overlay} ends,
|
||
as an integer.
|
||
@end defun
|
||
|
||
@defun overlay-buffer overlay
|
||
This function returns the buffer that @var{overlay} belongs to. It
|
||
returns @code{nil} if @var{overlay} has been deleted.
|
||
@end defun
|
||
|
||
@defun delete-overlay overlay
|
||
This function deletes @var{overlay}. The overlay continues to exist as
|
||
a Lisp object, and its property list is unchanged, but it ceases to be
|
||
attached to the buffer it belonged to, and ceases to have any effect on
|
||
display.
|
||
|
||
A deleted overlay is not permanently disconnected. You can give it a
|
||
position in a buffer again by calling @code{move-overlay}.
|
||
@end defun
|
||
|
||
@defun move-overlay overlay start end &optional buffer
|
||
This function moves @var{overlay} to @var{buffer}, and places its bounds
|
||
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
|
||
must specify buffer positions; they may be integers or markers.
|
||
|
||
If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
|
||
was already associated with; if @var{overlay} was deleted, it goes into
|
||
the current buffer.
|
||
|
||
The return value is @var{overlay}.
|
||
|
||
This is the only valid way to change the endpoints of an overlay. Do
|
||
not try modifying the markers in the overlay by hand, as that fails to
|
||
update other vital data structures and can cause some overlays to be
|
||
lost.
|
||
@end defun
|
||
|
||
@defun remove-overlays &optional start end name value
|
||
This function removes all the overlays between @var{start} and
|
||
@var{end} whose property @var{name} has the value @var{value}. It can
|
||
move the endpoints of the overlays in the region, or split them.
|
||
|
||
If @var{name} is omitted or @code{nil}, it means to delete all overlays in
|
||
the specified region. If @var{start} and/or @var{end} are omitted or
|
||
@code{nil}, that means the beginning and end of the buffer respectively.
|
||
Therefore, @code{(remove-overlays)} removes all the overlays in the
|
||
current buffer.
|
||
@end defun
|
||
|
||
@defun copy-overlay overlay
|
||
This function returns a copy of @var{overlay}. The copy has the same
|
||
endpoints and properties as @var{overlay}. However, the marker
|
||
insertion type for the start of the overlay and for the end of the
|
||
overlay are set to their default values (@pxref{Marker Insertion
|
||
Types}).
|
||
@end defun
|
||
|
||
Here are some examples:
|
||
|
||
@example
|
||
;; @r{Create an overlay.}
|
||
(setq foo (make-overlay 1 10))
|
||
@result{} #<overlay from 1 to 10 in display.texi>
|
||
(overlay-start foo)
|
||
@result{} 1
|
||
(overlay-end foo)
|
||
@result{} 10
|
||
(overlay-buffer foo)
|
||
@result{} #<buffer display.texi>
|
||
;; @r{Give it a property we can check later.}
|
||
(overlay-put foo 'happy t)
|
||
@result{} t
|
||
;; @r{Verify the property is present.}
|
||
(overlay-get foo 'happy)
|
||
@result{} t
|
||
;; @r{Move the overlay.}
|
||
(move-overlay foo 5 20)
|
||
@result{} #<overlay from 5 to 20 in display.texi>
|
||
(overlay-start foo)
|
||
@result{} 5
|
||
(overlay-end foo)
|
||
@result{} 20
|
||
;; @r{Delete the overlay.}
|
||
(delete-overlay foo)
|
||
@result{} nil
|
||
;; @r{Verify it is deleted.}
|
||
foo
|
||
@result{} #<overlay in no buffer>
|
||
;; @r{A deleted overlay has no position.}
|
||
(overlay-start foo)
|
||
@result{} nil
|
||
(overlay-end foo)
|
||
@result{} nil
|
||
(overlay-buffer foo)
|
||
@result{} nil
|
||
;; @r{Undelete the overlay.}
|
||
(move-overlay foo 1 20)
|
||
@result{} #<overlay from 1 to 20 in display.texi>
|
||
;; @r{Verify the results.}
|
||
(overlay-start foo)
|
||
@result{} 1
|
||
(overlay-end foo)
|
||
@result{} 20
|
||
(overlay-buffer foo)
|
||
@result{} #<buffer display.texi>
|
||
;; @r{Moving and deleting the overlay does not change its properties.}
|
||
(overlay-get foo 'happy)
|
||
@result{} t
|
||
@end example
|
||
|
||
Emacs stores the overlays of each buffer in two lists, divided
|
||
around an arbitrary center position. One list extends backwards
|
||
through the buffer from that center position, and the other extends
|
||
forwards from that center position. The center position can be anywhere
|
||
in the buffer.
|
||
|
||
@defun overlay-recenter pos
|
||
This function recenters the overlays of the current buffer around
|
||
position @var{pos}. That makes overlay lookup faster for positions
|
||
near @var{pos}, but slower for positions far away from @var{pos}.
|
||
@end defun
|
||
|
||
A loop that scans the buffer forwards, creating overlays, can run
|
||
faster if you do @code{(overlay-recenter (point-max))} first.
|
||
|
||
@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
|
||
most respects they are different. @xref{Text Properties}, for comparison.
|
||
|
||
Text properties are considered a part of the text; overlays and
|
||
their properties are specifically considered not to be part of the
|
||
text. Thus, copying text between various buffers and strings
|
||
preserves text properties, but does not try to preserve overlays.
|
||
Changing a buffer's text properties marks the buffer as modified,
|
||
while moving an overlay or changing its properties does not. Unlike
|
||
text property changes, overlay property changes are not recorded in
|
||
the buffer's undo list.
|
||
|
||
Since more than one overlay can specify a property value for the
|
||
same character, Emacs lets you specify a priority value of each
|
||
overlay. The priority value is used to decide which of the
|
||
overlapping overlays will ``win''.
|
||
|
||
These functions read and set the properties of an overlay:
|
||
|
||
@defun overlay-get overlay prop
|
||
This function returns the value of property @var{prop} recorded in
|
||
@var{overlay}, if any. If @var{overlay} does not record any value for
|
||
that property, but it does have a @code{category} property which is a
|
||
symbol, that symbol's @var{prop} property is used. Otherwise, the value
|
||
is @code{nil}.
|
||
@end defun
|
||
|
||
@defun overlay-put overlay prop value
|
||
This function sets the value of property @var{prop} recorded in
|
||
@var{overlay} to @var{value}. It returns @var{value}.
|
||
@end defun
|
||
|
||
@defun overlay-properties overlay
|
||
This returns a copy of the property list of @var{overlay}.
|
||
@end defun
|
||
|
||
See also the function @code{get-char-property} which checks both
|
||
overlay properties and text properties for a given character.
|
||
@xref{Examining Properties}.
|
||
|
||
Many overlay properties have special meanings; here is a table
|
||
of them:
|
||
|
||
@table @code
|
||
@item priority
|
||
@kindex priority @r{(overlay property)}
|
||
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
|
||
@code{priority} value is larger overrides the other. (For the
|
||
@code{face} property, the higher priority overlay's value does not
|
||
completely override the other value; instead, its face attributes
|
||
override the face attributes of the lower priority @code{face}
|
||
property.) If two overlays have the same priority value, and one is
|
||
nested in the other, then the inner one will prevail over the outer
|
||
one. If neither is nested in the other then you should not make
|
||
assumptions about which overlay will prevail.
|
||
|
||
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). In particular, the
|
||
overlay used for showing the region uses a priority value of the form
|
||
@w{@code{(@var{primary} . @var{secondary})}}, where the @var{primary}
|
||
value is used as described above, and @var{secondary} is the fallback
|
||
value used when @var{primary} and the nesting considerations fail to
|
||
resolve the precedence between overlays. However, you are advised not
|
||
to design Lisp programs based on this implementation detail; 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)}
|
||
If the @code{window} property is non-@code{nil}, then the overlay
|
||
applies only on that window.
|
||
|
||
@item category
|
||
@kindex category @r{(overlay property)}
|
||
If an overlay has a @code{category} property, we call it the
|
||
@dfn{category} of the overlay. It should be a symbol. The properties
|
||
of the symbol serve as defaults for the properties of the overlay.
|
||
|
||
@item face
|
||
@kindex face @r{(overlay property)}
|
||
This property controls the appearance of the text (@pxref{Faces}).
|
||
The value of the property can be the following:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
A face name (a symbol or string).
|
||
|
||
@item
|
||
An anonymous face: a property list of the form @code{(@var{keyword}
|
||
@var{value} @dots{})}, where each @var{keyword} is a face attribute
|
||
name and @var{value} is a value for that attribute.
|
||
|
||
@item
|
||
A list of faces. Each list element should be either a face name or an
|
||
anonymous face. This specifies a face which is an aggregate of the
|
||
attributes of each of the listed faces. Faces occurring earlier in
|
||
the list have higher priority.
|
||
|
||
@item
|
||
A cons cell of the form @code{(foreground-color . @var{color-name})}
|
||
or @code{(background-color . @var{color-name})}. This specifies the
|
||
foreground or background color, similar to @code{(:foreground
|
||
@var{color-name})} or @code{(:background @var{color-name})}. This
|
||
form is supported for backward compatibility only, and should be
|
||
avoided.
|
||
@end itemize
|
||
|
||
@item mouse-face
|
||
@kindex mouse-face @r{(overlay property)}
|
||
This property is used instead of @code{face} when the mouse is within
|
||
the range of the overlay. However, Emacs ignores all face attributes
|
||
from this property that alter the text size (e.g., @code{:height},
|
||
@code{:weight}, and @code{:slant}). Those attributes are always the
|
||
same as in the unhighlighted text.
|
||
|
||
@item display
|
||
@kindex display @r{(overlay property)}
|
||
This property activates various features that change the
|
||
way text is displayed. For example, it can make text appear taller
|
||
or shorter, higher or lower, wider or narrower, or replaced with an image.
|
||
@xref{Display Property}.
|
||
|
||
@item help-echo
|
||
@kindex help-echo @r{(overlay property)}
|
||
If an overlay has a @code{help-echo} property, then when you move the
|
||
mouse onto the text in the overlay, Emacs displays a help string in the
|
||
echo area, or in the tooltip window. For details see @ref{Text
|
||
help-echo}.
|
||
|
||
@item field
|
||
@kindex field @r{(overlay property)}
|
||
@c Copied from Special Properties.
|
||
Consecutive characters with the same @code{field} property constitute a
|
||
@emph{field}. Some motion functions including @code{forward-word} and
|
||
@code{beginning-of-line} stop moving at a field boundary.
|
||
@xref{Fields}.
|
||
|
||
@item modification-hooks
|
||
@kindex modification-hooks @r{(overlay property)}
|
||
This property's value is a list of functions to be called if any
|
||
character within the overlay is changed or if text is inserted strictly
|
||
within the overlay.
|
||
|
||
The hook functions are called both before and after each change.
|
||
If the functions save the information they receive, and compare notes
|
||
between calls, they can determine exactly what change has been made
|
||
in the buffer text.
|
||
|
||
When called before a change, each function receives four arguments: the
|
||
overlay, @code{nil}, and the beginning and end of the text range to be
|
||
modified.
|
||
|
||
When called after a change, each function receives five arguments: the
|
||
overlay, @code{t}, the beginning and end of the text range just
|
||
modified, and the length of the pre-change text replaced by that range.
|
||
(For an insertion, the pre-change length is zero; for a deletion, that
|
||
length is the number of characters deleted, and the post-change
|
||
beginning and end are equal.)
|
||
|
||
If these functions modify the buffer, they should bind
|
||
@code{inhibit-modification-hooks} to @code{t} around doing so, to
|
||
avoid confusing the internal mechanism that calls these hooks.
|
||
|
||
Text properties also support the @code{modification-hooks} property,
|
||
but the details are somewhat different (@pxref{Special Properties}).
|
||
|
||
@item insert-in-front-hooks
|
||
@kindex insert-in-front-hooks @r{(overlay property)}
|
||
This property's value is a list of functions to be called before and
|
||
after inserting text right at the beginning of the overlay. The calling
|
||
conventions are the same as for the @code{modification-hooks} functions.
|
||
|
||
@item insert-behind-hooks
|
||
@kindex insert-behind-hooks @r{(overlay property)}
|
||
This property's value is a list of functions to be called before and
|
||
after inserting text right at the end of the overlay. The calling
|
||
conventions are the same as for the @code{modification-hooks} functions.
|
||
|
||
@item invisible
|
||
@kindex invisible @r{(overlay property)}
|
||
The @code{invisible} property can make the text in the overlay
|
||
invisible, which means that it does not appear on the screen.
|
||
@xref{Invisible Text}, for details.
|
||
|
||
@item intangible
|
||
@kindex intangible @r{(overlay property)}
|
||
The @code{intangible} property on an overlay works just like the
|
||
@code{intangible} text property. It is obsolete. @xref{Special
|
||
Properties}, for details.
|
||
|
||
@item isearch-open-invisible
|
||
This property tells incremental search how to make an invisible overlay
|
||
visible, permanently, if the final match overlaps it. @xref{Invisible
|
||
Text}.
|
||
|
||
@item isearch-open-invisible-temporary
|
||
This property tells incremental search how to make an invisible overlay
|
||
visible, temporarily, during the search. @xref{Invisible Text}.
|
||
|
||
@item before-string
|
||
@kindex before-string @r{(overlay property)}
|
||
This property's value is a string to add to the display at the beginning
|
||
of the overlay. The string does not appear in the buffer in any
|
||
sense---only on the screen.
|
||
|
||
@item after-string
|
||
@kindex after-string @r{(overlay property)}
|
||
This property's value is a string to add to the display at the end of
|
||
the overlay. The string does not appear in the buffer in any
|
||
sense---only on the screen.
|
||
|
||
@item line-prefix
|
||
This property specifies a display spec to prepend to each
|
||
non-continuation line at display-time. @xref{Truncation}.
|
||
|
||
@item wrap-prefix
|
||
This property specifies a display spec to prepend to each continuation
|
||
line at display-time. @xref{Truncation}.
|
||
|
||
@item evaporate
|
||
@kindex evaporate @r{(overlay property)}
|
||
If this property is non-@code{nil}, the overlay is deleted automatically
|
||
if it becomes empty (i.e., if its length becomes zero). If you give
|
||
an empty overlay (@pxref{Managing Overlays, empty overlay}) a
|
||
non-@code{nil} @code{evaporate} property, that deletes it immediately.
|
||
Note that, unless an overlay has this property, it will not be deleted
|
||
when the text between its starting and ending positions is deleted
|
||
from the buffer.
|
||
|
||
@item keymap
|
||
@cindex keymap of character (and overlays)
|
||
@kindex keymap @r{(overlay property)}
|
||
If this property is non-@code{nil}, it specifies a keymap for a portion of the
|
||
text. This keymap is used when the character after point is within the
|
||
overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}.
|
||
|
||
@item local-map
|
||
@kindex local-map @r{(overlay property)}
|
||
The @code{local-map} property is similar to @code{keymap} but replaces the
|
||
buffer's local map rather than augmenting existing keymaps. This also means it
|
||
has lower precedence than minor mode keymaps.
|
||
@end table
|
||
|
||
The @code{keymap} and @code{local-map} properties do not affect a
|
||
string displayed by the @code{before-string}, @code{after-string}, or
|
||
@code{display} properties. This is only relevant for mouse clicks and
|
||
other mouse events that fall on the string, since point is never on
|
||
the string. To bind special mouse events for the string, assign it a
|
||
@code{keymap} or @code{local-map} text property. @xref{Special
|
||
Properties}.
|
||
|
||
@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
|
||
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:
|
||
|
||
@smallexample
|
||
(defun find-overlays-specifying (prop)
|
||
(let ((overlays (overlays-at (point)))
|
||
found)
|
||
(while overlays
|
||
(let ((overlay (car overlays)))
|
||
(if (overlay-get overlay prop)
|
||
(setq found (cons overlay found))))
|
||
(setq overlays (cdr overlays)))
|
||
found))
|
||
@end smallexample
|
||
@end defun
|
||
|
||
@defun overlays-in beg end
|
||
This function returns a list of the overlays that overlap the region
|
||
@var{beg} through @var{end}. An overlay overlaps with a region if it
|
||
contains one or more characters in the region; empty overlays
|
||
(@pxref{Managing Overlays, empty overlay}) overlap if they are at
|
||
@var{beg}, strictly between @var{beg} and @var{end}, or at @var{end}
|
||
when @var{end} denotes the position at the end of the buffer.
|
||
@end defun
|
||
|
||
@defun next-overlay-change pos
|
||
This function returns the buffer position of the next beginning or end
|
||
of an overlay, after @var{pos}. If there is none, it returns
|
||
@code{(point-max)}.
|
||
@end defun
|
||
|
||
@defun previous-overlay-change pos
|
||
This function returns the buffer position of the previous beginning or
|
||
end of an overlay, before @var{pos}. If there is none, it returns
|
||
@code{(point-min)}.
|
||
@end defun
|
||
|
||
As an example, here's a simplified (and inefficient) version of the
|
||
primitive function @code{next-single-char-property-change}
|
||
(@pxref{Property Search}). It searches forward from position
|
||
@var{pos} for the next position where the value of a given property
|
||
@code{prop}, as obtained from either overlays or text properties,
|
||
changes.
|
||
|
||
@smallexample
|
||
(defun next-single-char-property-change (position prop)
|
||
(save-excursion
|
||
(goto-char position)
|
||
(let ((propval (get-char-property (point) prop)))
|
||
(while (and (not (eobp))
|
||
(eq (get-char-property (point) prop) propval))
|
||
(goto-char (min (next-overlay-change (point))
|
||
(next-single-property-change (point) prop)))))
|
||
(point)))
|
||
@end smallexample
|
||
|
||
@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
|
||
@ref{Screen Lines}, for related functions.
|
||
|
||
@defun char-width char
|
||
This function returns the width in columns of the character
|
||
@var{char}, if it were displayed in the current buffer (i.e., taking
|
||
into account the buffer's display table, if any; @pxref{Display
|
||
Tables}). The width of a tab character is usually @code{tab-width}
|
||
(@pxref{Usual Display}).
|
||
@end defun
|
||
|
||
@defun string-width string
|
||
This function returns the width in columns of the string @var{string},
|
||
if it were displayed in the current buffer and the selected window.
|
||
@end defun
|
||
|
||
@defun truncate-string-to-width string width &optional start-column padding ellipsis
|
||
This function returns the part of @var{string} that fits within
|
||
@var{width} columns, as a new string.
|
||
|
||
If @var{string} does not reach @var{width}, then the result ends where
|
||
@var{string} ends. If one multi-column character in @var{string}
|
||
extends across the column @var{width}, that character is not included in
|
||
the result. Thus, the result can fall short of @var{width} but cannot
|
||
go beyond it.
|
||
|
||
The optional argument @var{start-column} specifies the starting column.
|
||
If this is non-@code{nil}, then the first @var{start-column} columns of
|
||
the string are omitted from the value. If one multi-column character in
|
||
@var{string} extends across the column @var{start-column}, that
|
||
character is not included.
|
||
|
||
The optional argument @var{padding}, if non-@code{nil}, is a padding
|
||
character added at the beginning and end of the result string, to extend
|
||
it to exactly @var{width} columns. The padding character is used at the
|
||
end of the result if it falls short of @var{width}. It is also used at
|
||
the beginning of the result if one multi-column character in
|
||
@var{string} extends across the column @var{start-column}.
|
||
|
||
@vindex truncate-string-ellipsis
|
||
If @var{ellipsis} is non-@code{nil}, it should be a string which will
|
||
replace the end of @var{string} (including any padding) if it extends
|
||
beyond @var{width}, unless the display width of @var{string} is equal
|
||
to or less than the display width of @var{ellipsis}. If
|
||
@var{ellipsis} is non-@code{nil} and not a string, it stands for
|
||
the value of the variable @code{truncate-string-ellipsis}.
|
||
|
||
@example
|
||
(truncate-string-to-width "\tab\t" 12 4)
|
||
@result{} "ab"
|
||
(truncate-string-to-width "\tab\t" 12 4 ?\s)
|
||
@result{} " ab "
|
||
@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} and @code{fit-frame-to-buffer}
|
||
(@pxref{Resizing Windows}) 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
|
||
@cindex height of a line
|
||
|
||
The total height of each display line consists of the height of the
|
||
contents of the line, plus optional additional vertical line spacing
|
||
above or below the display line.
|
||
|
||
The height of the line contents is the maximum height of any character
|
||
or image on that display line, including the final newline if there is
|
||
one. (A display line that is continued doesn't include a final
|
||
newline.) That is the default line height, if you do nothing to specify
|
||
a greater height. (In the most common case, this equals the height of
|
||
the corresponding frame's default font, see @ref{Frame Font}.)
|
||
|
||
There are several ways to explicitly specify a larger line height,
|
||
either by specifying an absolute height for the display line, or by
|
||
specifying vertical space. However, no matter what you specify, the
|
||
actual line height can never be less than the default.
|
||
|
||
@kindex line-height @r{(text property)}
|
||
A newline can have a @code{line-height} text or overlay property
|
||
that controls the total height of the display line ending in that
|
||
newline.
|
||
|
||
If the property value is @code{t}, the newline character has no
|
||
effect on the displayed height of the line---the visible contents
|
||
alone determine the height. The @code{line-spacing} property,
|
||
described below, is also ignored in this case. This is useful for
|
||
tiling small images (or image slices) without adding blank areas
|
||
between the images.
|
||
|
||
If the property value is a list of the form @code{(@var{height}
|
||
@var{total})}, that adds extra space @emph{below} the display line.
|
||
First Emacs uses @var{height} as a height spec to control extra space
|
||
@emph{above} the line; then it adds enough space @emph{below} the line
|
||
to bring the total line height up to @var{total}. In this case, any
|
||
value of @code{line-spacing} property for the newline is ignored.
|
||
|
||
@cindex height spec
|
||
Any other kind of property value is a height spec, which translates
|
||
into a number---the specified line height. There are several ways to
|
||
write a height spec; here's how each of them translates into a number:
|
||
|
||
@table @code
|
||
@item @var{integer}
|
||
If the height spec is a positive integer, the height value is that integer.
|
||
@item @var{float}
|
||
If the height spec is a float, @var{float}, the numeric height value
|
||
is @var{float} times the frame's default line height.
|
||
@item (@var{face} . @var{ratio})
|
||
If the height spec is a cons of the format shown, the numeric height
|
||
is @var{ratio} times the height of face @var{face}. @var{ratio} can
|
||
be any type of number, or @code{nil} which means a ratio of 1.
|
||
If @var{face} is @code{t}, it refers to the current face.
|
||
@item (nil . @var{ratio})
|
||
If the height spec is a cons of the format shown, the numeric height
|
||
is @var{ratio} times the height of the contents of the line.
|
||
@end table
|
||
|
||
Thus, any valid height spec determines the height in pixels, one way
|
||
or another. If the line contents' height is less than that, Emacs
|
||
adds extra vertical space above the line to achieve the specified
|
||
total height.
|
||
|
||
If you don't specify the @code{line-height} property, the line's
|
||
height consists of the contents' height plus the line spacing.
|
||
There are several ways to specify the line spacing for different
|
||
parts of Emacs text.
|
||
|
||
On graphical terminals, you can specify the line spacing for all
|
||
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 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 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.
|
||
|
||
@kindex line-spacing @r{(text property)}
|
||
Finally, a newline can have a @code{line-spacing} text or overlay
|
||
property that can enlarge the default frame line spacing and the
|
||
buffer local @code{line-spacing} variable: if its value is larger than
|
||
the buffer or frame defaults, that larger value is used instead, for
|
||
the display line ending in that newline.
|
||
|
||
One way or another, these mechanisms specify a Lisp value for the
|
||
spacing of each line. The value is a height spec, and it translates
|
||
into a Lisp value as described above. However, in this case the
|
||
numeric height value specifies the line spacing, rather than the line
|
||
height.
|
||
|
||
On text terminals, the line spacing cannot be altered.
|
||
|
||
@node Faces
|
||
@section Faces
|
||
@cindex faces
|
||
|
||
A @dfn{face} is a collection of graphical attributes for displaying
|
||
text: font, foreground color, background color, optional underlining,
|
||
etc. Faces control how Emacs displays text in buffers, as well as
|
||
other parts of the frame such as the mode line.
|
||
|
||
@cindex anonymous face
|
||
One way to represent a face is as a property list of attributes,
|
||
like @code{(:foreground "red" :weight bold)}. Such a list is called
|
||
an @dfn{anonymous face}. For example, you can assign an anonymous
|
||
face as the value of the @code{face} text property, and Emacs will
|
||
display the underlying text with the specified attributes.
|
||
@xref{Special Properties}.
|
||
|
||
@cindex face name
|
||
More commonly, a face is referred to via a @dfn{face name}: a Lisp
|
||
symbol associated with a set of face attributes@footnote{For backward
|
||
compatibility, you can also use a string to specify a face name; that
|
||
is equivalent to a Lisp symbol with the same name.}. Named faces are
|
||
defined using the @code{defface} macro (@pxref{Defining Faces}).
|
||
Emacs comes with several standard named faces (@pxref{Basic Faces}).
|
||
|
||
Many parts of Emacs require named faces, and do not accept
|
||
anonymous faces. These include the functions documented in
|
||
@ref{Attribute Functions}, and the variable @code{font-lock-keywords}
|
||
(@pxref{Search-based Fontification}). Unless otherwise stated, we
|
||
will use the term @dfn{face} to refer only to named faces.
|
||
|
||
@defun facep object
|
||
This function returns a non-@code{nil} value if @var{object} is a
|
||
named face: a Lisp symbol or string which serves as a face name.
|
||
Otherwise, it returns @code{nil}.
|
||
@end defun
|
||
|
||
@menu
|
||
* Face Attributes:: What is in a face?
|
||
* Defining Faces:: How to define a face.
|
||
* Attribute Functions:: Functions to examine and set face attributes.
|
||
* Displaying Faces:: How Emacs combines the faces specified for a character.
|
||
* Face Remapping:: Remapping faces to alternative definitions.
|
||
* Face Functions:: How to define and examine faces.
|
||
* Auto Faces:: Hook for automatic face assignment.
|
||
* Basic Faces:: Faces that are defined by default.
|
||
* Font Selection:: Finding the best available font for a face.
|
||
* Font Lookup:: Looking up the names of available fonts
|
||
and information about them.
|
||
* Fontsets:: A fontset is a collection of fonts
|
||
that handle a range of character sets.
|
||
* Low-Level Font:: Lisp representation for character display fonts.
|
||
@end menu
|
||
|
||
@node Face Attributes
|
||
@subsection Face Attributes
|
||
@cindex face attributes
|
||
|
||
@dfn{Face attributes} determine the visual appearance of a face.
|
||
The following table lists all the face attributes, their possible
|
||
values, and their effects.
|
||
|
||
Apart from the values given below, each face attribute can have the
|
||
value @code{unspecified}. This special value means that the face
|
||
doesn't specify that attribute directly. An @code{unspecified}
|
||
attribute tells Emacs to refer instead to a parent face (see the
|
||
description @code{:inherit} attribute below); or, failing that, to an
|
||
underlying face (@pxref{Displaying Faces}). The @code{default} face
|
||
must specify all attributes.
|
||
|
||
Some of these attributes are meaningful only on certain kinds of
|
||
displays. If your display cannot handle a certain attribute, the
|
||
attribute is ignored.
|
||
|
||
@table @code
|
||
@item :family
|
||
Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU
|
||
Emacs Manual}, for more information about font families. The function
|
||
@code{font-family-list} (see below) returns a list of available family
|
||
names. @xref{Fontsets}, for information about fontsets.
|
||
|
||
@item :foundry
|
||
The name of the @dfn{font foundry} for the font family specified by
|
||
the @code{:family} attribute (a string). @xref{Fonts,,, emacs, The
|
||
GNU Emacs Manual}.
|
||
|
||
@item :width
|
||
Relative character width. This should be one of the symbols
|
||
@code{ultra-condensed}, @code{extra-condensed}, @code{condensed},
|
||
@code{semi-condensed}, @code{normal}, @code{semi-expanded},
|
||
@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}.
|
||
|
||
@item :height
|
||
The height of the font. In the simplest case, this is an integer in
|
||
units of 1/10 point.
|
||
|
||
The value can also be floating point or a function, which
|
||
specifies the height relative to an @dfn{underlying face}
|
||
(@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.
|
||
|
||
The height of the default face must be specified using an integer;
|
||
floating point and function values are not allowed.
|
||
|
||
@item :weight
|
||
Font weight---one of the symbols (from densest to faintest)
|
||
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
|
||
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or
|
||
@code{ultra-light}. On text terminals which support
|
||
variable-brightness text, any weight greater than normal is displayed
|
||
as extra bright, and any weight less than normal is displayed as
|
||
half-bright.
|
||
|
||
@cindex italic text
|
||
@item :slant
|
||
Font slant---one of the symbols @code{italic}, @code{oblique},
|
||
@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On
|
||
text terminals that support variable-brightness text, slanted text is
|
||
displayed as half-bright.
|
||
|
||
@item :foreground
|
||
Foreground color, a string. The value can be a system-defined color
|
||
name, or a hexadecimal color specification. @xref{Color Names}. On
|
||
black-and-white displays, certain shades of gray are implemented by
|
||
stipple patterns.
|
||
|
||
@item :distant-foreground
|
||
Alternative foreground color, a string. This is like @code{:foreground}
|
||
but the color is only used as a foreground when the background color is
|
||
near to the foreground that would have been used. This is useful for
|
||
example when marking text (i.e., the region face). If the text has a foreground
|
||
that is visible with the region face, that foreground is used.
|
||
If the foreground is near the region face background,
|
||
@code{:distant-foreground} is used instead so the text is readable.
|
||
|
||
@item :background
|
||
Background color, a string. The value can be a system-defined color
|
||
name, or a hexadecimal color specification. @xref{Color Names}.
|
||
|
||
@cindex underlined text
|
||
@item :underline
|
||
Whether or not characters should be underlined, and in what
|
||
way. The possible values of the @code{:underline} attribute are:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
Don't underline.
|
||
|
||
@item @code{t}
|
||
Underline with the foreground color of the face.
|
||
|
||
@item @var{color}
|
||
Underline in color @var{color}, a string specifying a color.
|
||
|
||
@item @code{(:color @var{color} :style @var{style})}
|
||
@var{color} is either a string, or the symbol @code{foreground-color},
|
||
meaning the foreground color of the face. Omitting the attribute
|
||
@code{:color} means to use the foreground color of the face.
|
||
@var{style} should be a symbol @code{line} or @code{wave}, meaning to
|
||
use a straight or wavy line. Omitting the attribute @code{:style}
|
||
means to use a straight line.
|
||
@end table
|
||
|
||
@cindex overlined text
|
||
@item :overline
|
||
Whether or not characters should be overlined, and in what color.
|
||
If the value is @code{t}, overlining uses the foreground color of the
|
||
face. If the value is a string, overlining uses that color. The
|
||
value @code{nil} means do not overline.
|
||
|
||
@cindex strike-through text
|
||
@item :strike-through
|
||
Whether or not characters should be strike-through, and in what
|
||
color. The value is used like that of @code{:overline}.
|
||
|
||
@cindex 2D box
|
||
@cindex 3D box
|
||
@item :box
|
||
Whether or not a box should be drawn around characters, its color, the
|
||
width of the box lines, and 3D appearance. Here are the possible
|
||
values of the @code{:box} attribute, and what they mean:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
Don't draw a box.
|
||
|
||
@item @code{t}
|
||
Draw a box with lines of width 1, in the foreground color.
|
||
|
||
@item @var{color}
|
||
Draw a box with lines of width 1, in color @var{color}.
|
||
|
||
@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
|
||
This way you can explicitly specify all aspects of the box. The value
|
||
@var{width} specifies the width of the lines to draw; it defaults to
|
||
1. A negative width @var{-n} means to draw a line of width @var{n}
|
||
that occupies the space of the underlying text, thus avoiding any
|
||
increase in the character height or width.
|
||
|
||
The value @var{color} specifies the color to draw with. The default is
|
||
the foreground color of the face for simple boxes, and the background
|
||
color of the face for 3D boxes.
|
||
|
||
The value @var{style} specifies whether to draw a 3D box. If it is
|
||
@code{released-button}, the box looks like a 3D button that is not being
|
||
pressed. If it is @code{pressed-button}, the box looks like a 3D button
|
||
that is being pressed. If it is @code{nil} or omitted, a plain 2D box
|
||
is used.
|
||
@end table
|
||
|
||
@item :inverse-video
|
||
Whether or not characters should be displayed in inverse video. The
|
||
value should be @code{t} (yes) or @code{nil} (no).
|
||
|
||
@item :stipple
|
||
The background stipple, a bitmap.
|
||
|
||
The value can be a string; that should be the name of a file containing
|
||
external-format X bitmap data. The file is found in the directories
|
||
listed in the variable @code{x-bitmap-file-path}.
|
||
|
||
Alternatively, the value can specify the bitmap directly, with a list
|
||
of the form @code{(@var{width} @var{height} @var{data})}. Here,
|
||
@var{width} and @var{height} specify the size in pixels, and
|
||
@var{data} is a string containing the raw bits of the bitmap, row by
|
||
row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes
|
||
in the string (which should be a unibyte string for best results).
|
||
This means that each row always occupies at least one whole byte.
|
||
|
||
If the value is @code{nil}, that means use no stipple pattern.
|
||
|
||
Normally you do not need to set the stipple attribute, because it is
|
||
used automatically to handle certain shades of gray.
|
||
|
||
@item :font
|
||
The font used to display the face. Its value should be a font object.
|
||
@xref{Low-Level Font}, for information about font objects, font specs,
|
||
and font entities.
|
||
|
||
When specifying this attribute using @code{set-face-attribute}
|
||
(@pxref{Attribute Functions}), you may also supply a font spec, a font
|
||
entity, or a string. Emacs converts such values to an appropriate
|
||
font object, and stores that font object as the actual attribute
|
||
value. If you specify a string, the contents of the string should be
|
||
a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
|
||
font name is an XLFD containing wildcards, Emacs chooses the first
|
||
font matching those wildcards. Specifying this attribute also changes
|
||
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
|
||
an underlying face would be, with higher priority than underlying
|
||
faces (@pxref{Displaying Faces}). If a list of faces is used,
|
||
attributes from faces earlier in the list override those from later
|
||
faces.
|
||
@end table
|
||
|
||
@defun font-family-list &optional frame
|
||
This function returns a list of available font family names. The
|
||
optional argument @var{frame} specifies the frame on which the text is
|
||
to be displayed; if it is @code{nil}, the selected frame is used.
|
||
@end defun
|
||
|
||
@defopt underline-minimum-offset
|
||
This variable specifies the minimum distance between the baseline and
|
||
the underline, in pixels, when displaying underlined text.
|
||
@end defopt
|
||
|
||
@defopt x-bitmap-file-path
|
||
This variable specifies a list of directories for searching
|
||
for bitmap files, for the @code{:stipple} attribute.
|
||
@end defopt
|
||
|
||
@defun bitmap-spec-p object
|
||
This returns @code{t} if @var{object} is a valid bitmap specification,
|
||
suitable for use with @code{:stipple} (see above). It returns
|
||
@code{nil} otherwise.
|
||
@end defun
|
||
|
||
@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.
|
||
This macro associates a face name (a symbol) with a default @dfn{face
|
||
spec}. A face spec is a construct which specifies what attributes a
|
||
face should have on any given terminal; for example, a face spec might
|
||
specify one foreground color on high-color terminals, and a different
|
||
foreground color on low-color terminals.
|
||
|
||
People are sometimes tempted to create a variable whose value is a
|
||
face name. In the vast majority of cases, this is not necessary; the
|
||
usual procedure is to define a face with @code{defface}, and then use
|
||
its name directly.
|
||
|
||
@defmac defface face spec doc [keyword value]@dots{}
|
||
This macro declares @var{face} as a named face whose default face spec
|
||
is given by @var{spec}. You should not quote the symbol @var{face},
|
||
and it should not end in @samp{-face} (that would be redundant). The
|
||
argument @var{doc} is a documentation string for the face. The
|
||
additional @var{keyword} arguments have the same meanings as in
|
||
@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
|
||
|
||
If @var{face} already has a default face spec, this macro does
|
||
nothing.
|
||
|
||
The default face spec determines @var{face}'s appearance when no
|
||
customizations are in effect (@pxref{Customization}). If @var{face}
|
||
has already been customized (via Custom themes or via customizations
|
||
read from the init file), its appearance is determined by the custom
|
||
face spec(s), which override the default face spec @var{spec}.
|
||
However, if the customizations are subsequently removed, the
|
||
appearance of @var{face} will again be determined by its default face
|
||
spec.
|
||
|
||
As an exception, if you evaluate a @code{defface} form with
|
||
@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature
|
||
of @code{eval-defun} overrides any custom face specs on the face,
|
||
causing the face to reflect exactly what the @code{defface} says.
|
||
|
||
The @var{spec} argument is a @dfn{face spec}, which states how the
|
||
face should appear on different kinds of terminals. It should be an
|
||
alist whose elements each have the form
|
||
|
||
@example
|
||
(@var{display} . @var{plist})
|
||
@end example
|
||
|
||
@noindent
|
||
@var{display} specifies a class of terminals (see below). @var{plist}
|
||
is a property list of face attributes and their values, specifying how
|
||
the face appears on such terminals. For backward compatibility, you
|
||
can also write an element as @code{(@var{display} @var{plist})}.
|
||
|
||
The @var{display} part of an element of @var{spec} determines which
|
||
terminals the element matches. If more than one element of @var{spec}
|
||
matches a given terminal, the first element that matches is the one
|
||
used for that terminal. There are three possibilities for
|
||
@var{display}:
|
||
|
||
@table @asis
|
||
@item @code{default}
|
||
This element of @var{spec} doesn't match any terminal; instead, it
|
||
specifies defaults that apply to all terminals. This element, if
|
||
used, must be the first element of @var{spec}. Each of the following
|
||
elements can override any or all of these defaults.
|
||
|
||
@item @code{t}
|
||
This element of @var{spec} matches all terminals. Therefore, any
|
||
subsequent elements of @var{spec} are never used. Normally @code{t}
|
||
is used in the last (or only) element of @var{spec}.
|
||
|
||
@item a list
|
||
If @var{display} is a list, each element should have the form
|
||
@code{(@var{characteristic} @var{value}@dots{})}. Here
|
||
@var{characteristic} specifies a way of classifying terminals, and the
|
||
@var{value}s are possible classifications which @var{display} should
|
||
apply to. Here are the possible values of @var{characteristic}:
|
||
|
||
@table @code
|
||
@item type
|
||
The kind of window system the terminal uses---either @code{graphic}
|
||
(any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS
|
||
console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a
|
||
non-graphics-capable display). @xref{Window Systems, window-system}.
|
||
|
||
@item class
|
||
What kinds of colors the terminal supports---either @code{color},
|
||
@code{grayscale}, or @code{mono}.
|
||
|
||
@item background
|
||
The kind of background---either @code{light} or @code{dark}.
|
||
|
||
@item min-colors
|
||
An integer that represents the minimum number of colors the terminal
|
||
should support. This matches a terminal if its
|
||
@code{display-color-cells} value is at least the specified integer.
|
||
|
||
@item supports
|
||
Whether or not the terminal can display the face attributes given in
|
||
@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face
|
||
Attribute Testing}, for more information on exactly how this testing
|
||
is done.
|
||
@end table
|
||
|
||
If an element of @var{display} specifies more than one @var{value} for
|
||
a given @var{characteristic}, any of those values is acceptable. If
|
||
@var{display} has more than one element, each element should specify a
|
||
different @var{characteristic}; then @emph{each} characteristic of the
|
||
terminal must match one of the @var{value}s specified for it in
|
||
@var{display}.
|
||
@end table
|
||
@end defmac
|
||
|
||
For example, here's the definition of the standard face
|
||
@code{highlight}:
|
||
|
||
@example
|
||
(defface highlight
|
||
'((((class color) (min-colors 88) (background light))
|
||
:background "darkseagreen2")
|
||
(((class color) (min-colors 88) (background dark))
|
||
:background "darkolivegreen")
|
||
(((class color) (min-colors 16) (background light))
|
||
:background "darkseagreen2")
|
||
(((class color) (min-colors 16) (background dark))
|
||
:background "darkolivegreen")
|
||
(((class color) (min-colors 8))
|
||
:background "green" :foreground "black")
|
||
(t :inverse-video t))
|
||
"Basic face for highlighting."
|
||
:group 'basic-faces)
|
||
@end example
|
||
|
||
Internally, Emacs stores each face's default spec in its
|
||
@code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
|
||
The @code{saved-face} property stores any face spec saved by the user
|
||
using the customization buffer; the @code{customized-face} property
|
||
stores the face spec customized for the current session, but not
|
||
saved; and the @code{theme-face} property stores an alist associating
|
||
the active customization settings and Custom themes with the face
|
||
specs for that face. The face's documentation string is stored in the
|
||
@code{face-documentation} property.
|
||
|
||
Normally, a face is declared just once, using @code{defface}, and
|
||
any further changes to its appearance are applied using the Customize
|
||
framework (e.g., via the Customize user interface or via the
|
||
@code{custom-set-faces} function; @pxref{Applying Customizations}), or
|
||
by face remapping (@pxref{Face Remapping}). In the rare event that
|
||
you need to change a face spec directly from Lisp, you can use the
|
||
@code{face-spec-set} function.
|
||
|
||
@defun face-spec-set face spec &optional spec-type
|
||
This function applies @var{spec} as a face spec for @code{face}.
|
||
@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{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.
|
||
|
||
@defun face-attribute face attribute &optional frame inherit
|
||
This function returns the value of the @var{attribute} attribute for
|
||
@var{face} on @var{frame}.
|
||
|
||
If @var{frame} is omitted or @code{nil}, that means the selected frame
|
||
(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
|
||
returns the value of the specified attribute for newly-created frames
|
||
(this is normally @code{unspecified}, unless you have specified some
|
||
value using @code{set-face-attribute}; see below).
|
||
|
||
If @var{inherit} is @code{nil}, only attributes directly defined by
|
||
@var{face} are considered, so the return value may be
|
||
@code{unspecified}, or a relative value. If @var{inherit} is
|
||
non-@code{nil}, @var{face}'s definition of @var{attribute} is merged
|
||
with the faces specified by its @code{:inherit} attribute; however the
|
||
return value may still be @code{unspecified} or relative. If
|
||
@var{inherit} is a face or a list of faces, then the result is further
|
||
merged with that face (or faces), until it becomes specified and
|
||
absolute.
|
||
|
||
To ensure that the return value is always specified and absolute, use
|
||
a value of @code{default} for @var{inherit}; this will resolve any
|
||
unspecified or relative values by merging with the @code{default} face
|
||
(which is always completely specified).
|
||
|
||
For example,
|
||
|
||
@example
|
||
(face-attribute 'bold :weight)
|
||
@result{} bold
|
||
@end example
|
||
@end defun
|
||
|
||
@c FIXME: Add an index for "relative face attribute", maybe here? --xfq
|
||
@defun face-attribute-relative-p attribute value
|
||
This function returns non-@code{nil} if @var{value}, when used as the
|
||
value of the face attribute @var{attribute}, is relative. This means
|
||
it would modify, rather than completely override, any value that comes
|
||
from a subsequent face in the face list or that is inherited from
|
||
another face.
|
||
|
||
@code{unspecified} is a relative value for all attributes. For
|
||
@code{:height}, floating point and function values are also relative.
|
||
|
||
For example:
|
||
|
||
@example
|
||
(face-attribute-relative-p :height 2.0)
|
||
@result{} t
|
||
@end example
|
||
@end defun
|
||
|
||
@defun face-all-attributes face &optional frame
|
||
This function returns an alist of attributes of @var{face}. The
|
||
elements of the result are name-value pairs of the form
|
||
@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument
|
||
@var{frame} specifies the frame whose definition of @var{face} to
|
||
return; if omitted or @code{nil}, the returned value describes the
|
||
default attributes of @var{face} for newly created frames.
|
||
@end defun
|
||
|
||
@defun merge-face-attribute attribute value1 value2
|
||
If @var{value1} is a relative value for the face attribute
|
||
@var{attribute}, returns it merged with the underlying value
|
||
@var{value2}; otherwise, if @var{value1} is an absolute value for the
|
||
face attribute @var{attribute}, returns @var{value1} unchanged.
|
||
@end defun
|
||
|
||
Normally, Emacs uses the face specs of each face to automatically
|
||
calculate its attributes on each frame (@pxref{Defining Faces}). The
|
||
function @code{set-face-attribute} can override this calculation by
|
||
directly assigning attributes to a face, either on a specific frame or
|
||
for all frames. This function is mostly intended for internal usage.
|
||
|
||
@defun set-face-attribute face frame &rest arguments
|
||
This function sets one or more attributes of @var{face} for
|
||
@var{frame}. The attributes specifies in this way override the face
|
||
spec(s) belonging to @var{face}.
|
||
|
||
The extra arguments @var{arguments} specify the attributes to set, and
|
||
the values for them. They should consist of alternating attribute
|
||
names (such as @code{:family} or @code{:underline}) and values. Thus,
|
||
|
||
@example
|
||
(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
|
||
@end example
|
||
|
||
@noindent
|
||
sets the attribute @code{:weight} to @code{bold} and the attribute
|
||
@code{:slant} to @code{italic}.
|
||
|
||
|
||
If @var{frame} is @code{t}, this function sets the default attributes
|
||
for newly created frames. If @var{frame} is @code{nil}, this function
|
||
sets the attributes for all existing frames, as well as for newly
|
||
created frames.
|
||
@end defun
|
||
|
||
The following commands and functions mostly provide compatibility
|
||
with old versions of Emacs. They work by calling
|
||
@code{set-face-attribute}. Values of @code{t} and @code{nil} (or
|
||
omitted) for their @var{frame} argument are handled just like
|
||
@code{set-face-attribute} and @code{face-attribute}. The commands
|
||
read their arguments using the minibuffer, if called interactively.
|
||
|
||
@deffn Command set-face-foreground face color &optional frame
|
||
@deffnx Command set-face-background face color &optional frame
|
||
These set the @code{:foreground} attribute (or @code{:background}
|
||
attribute, respectively) of @var{face} to @var{color}.
|
||
@end deffn
|
||
|
||
@deffn Command set-face-stipple face pattern &optional frame
|
||
This sets the @code{:stipple} attribute of @var{face} to
|
||
@var{pattern}.
|
||
@end deffn
|
||
|
||
@deffn Command set-face-font face font &optional frame
|
||
This sets the @code{:font} attribute of @var{face} to @var{font}.
|
||
@end deffn
|
||
|
||
@defun set-face-bold face bold-p &optional frame
|
||
This sets the @code{:weight} attribute of @var{face} to @var{normal}
|
||
if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
|
||
@end defun
|
||
|
||
@defun set-face-italic face italic-p &optional frame
|
||
This sets the @code{:slant} attribute of @var{face} to @var{normal} if
|
||
@var{italic-p} is @code{nil}, and to @var{italic} otherwise.
|
||
@end defun
|
||
|
||
@defun set-face-underline face underline &optional frame
|
||
This sets the @code{:underline} attribute of @var{face} to
|
||
@var{underline}.
|
||
@end defun
|
||
|
||
@defun set-face-inverse-video face inverse-video-p &optional frame
|
||
This sets the @code{:inverse-video} attribute of @var{face} to
|
||
@var{inverse-video-p}.
|
||
@end defun
|
||
|
||
@deffn Command invert-face face &optional frame
|
||
This swaps the foreground and background colors of face @var{face}.
|
||
@end deffn
|
||
|
||
The following functions examine the attributes of a face. They
|
||
mostly provide compatibility with old versions of Emacs. If you don't
|
||
specify @var{frame}, they refer to the selected frame; @code{t} refers
|
||
to the default data for new frames. They return @code{unspecified} if
|
||
the face doesn't define any value for that attribute. If
|
||
@var{inherit} is @code{nil}, only an attribute directly defined by the
|
||
face is returned. If @var{inherit} is non-@code{nil}, any faces
|
||
specified by its @code{:inherit} attribute are considered as well, and
|
||
if @var{inherit} is a face or a list of faces, then they are also
|
||
considered, until a specified attribute is found. To ensure that the
|
||
return value is always specified, use a value of @code{default} for
|
||
@var{inherit}.
|
||
|
||
@defun face-font face &optional frame character
|
||
This function returns the name of the font of face @var{face}.
|
||
|
||
If the optional argument @var{frame} is specified, it returns the name
|
||
of the font of @var{face} for that frame. If @var{frame} is omitted or
|
||
@code{nil}, the selected frame is used. And, in this case, if the
|
||
optional third argument @var{character} is supplied, it returns the font
|
||
name used for @var{character}.
|
||
@end defun
|
||
|
||
@defun face-foreground face &optional frame inherit
|
||
@defunx face-background face &optional frame inherit
|
||
These functions return the foreground color (or background color,
|
||
respectively) of face @var{face}, as a string. If the color is
|
||
unspecified, they return @code{nil}.
|
||
@end defun
|
||
|
||
@defun face-stipple face &optional frame inherit
|
||
This function returns the name of the background stipple pattern of face
|
||
@var{face}, or @code{nil} if it doesn't have one.
|
||
@end defun
|
||
|
||
@defun face-bold-p face &optional frame inherit
|
||
This function returns a non-@code{nil} value if the @code{:weight}
|
||
attribute of @var{face} is bolder than normal (i.e., one of
|
||
@code{semi-bold}, @code{bold}, @code{extra-bold}, or
|
||
@code{ultra-bold}). Otherwise, it returns @code{nil}.
|
||
@end defun
|
||
|
||
@defun face-italic-p face &optional frame inherit
|
||
This function returns a non-@code{nil} value if the @code{:slant}
|
||
attribute of @var{face} is @code{italic} or @code{oblique}, and
|
||
@code{nil} otherwise.
|
||
@end defun
|
||
|
||
@defun face-underline-p face &optional frame inherit
|
||
This function returns non-@code{nil} if face @var{face} specifies
|
||
a non-@code{nil} @code{:underline} attribute.
|
||
@end defun
|
||
|
||
@defun face-inverse-video-p face &optional frame inherit
|
||
This function returns non-@code{nil} if face @var{face} specifies
|
||
a non-@code{nil} @code{:inverse-video} attribute.
|
||
@end defun
|
||
|
||
@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
|
||
these various sources together specify more than one face for a
|
||
particular character, Emacs merges the attributes of the various
|
||
faces. Here is the order in which Emacs merges the faces, from
|
||
highest to lowest priority:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
If the text consists of a special glyph, the glyph can specify a
|
||
particular face. @xref{Glyphs}.
|
||
|
||
@item
|
||
If the text lies within an active region, Emacs highlights it using
|
||
the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs
|
||
Manual}.
|
||
|
||
@item
|
||
If the text lies within an overlay with a non-@code{nil} @code{face}
|
||
property, Emacs applies the face(s) specified by that property. If
|
||
the overlay has a @code{mouse-face} property and the mouse is near
|
||
enough to the overlay, Emacs applies the face or face attributes
|
||
specified by the @code{mouse-face} property instead. @xref{Overlay
|
||
Properties}.
|
||
|
||
When multiple overlays cover one character, an overlay with higher
|
||
priority overrides those with lower priority. @xref{Overlays}.
|
||
|
||
@item
|
||
If the text contains a @code{face} or @code{mouse-face} property,
|
||
Emacs applies the specified faces and face attributes. @xref{Special
|
||
Properties}. (This is how Font Lock mode faces are applied.
|
||
@xref{Font Lock Mode}.)
|
||
|
||
@item
|
||
If the text lies within the mode line of the selected window, Emacs
|
||
applies the @code{mode-line} face. For the mode line of a
|
||
non-selected window, Emacs applies the @code{mode-line-inactive} face.
|
||
For a header line, Emacs applies the @code{header-line} face.
|
||
|
||
@item
|
||
If any given attribute has not been specified during the preceding
|
||
steps, Emacs applies the attribute of the @code{default} face.
|
||
@end itemize
|
||
|
||
At each stage, if a face has a valid @code{:inherit} attribute,
|
||
Emacs treats any attribute with an @code{unspecified} value as having
|
||
the corresponding value drawn from the parent face(s). @pxref{Face
|
||
Attributes}. Note that the parent face(s) may also leave the
|
||
attribute unspecified; in that case, the attribute remains unspecified
|
||
at the next level of face merging.
|
||
|
||
@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
|
||
to implement the @code{text-scale-adjust} command (@pxref{Text
|
||
Scale,,, emacs, The GNU Emacs Manual}).
|
||
|
||
@defvar face-remapping-alist
|
||
The value of this variable is an alist whose elements have the form
|
||
@code{(@var{face} . @var{remapping})}. This causes Emacs to display
|
||
any text having the face @var{face} with @var{remapping}, rather than
|
||
the ordinary definition of @var{face}.
|
||
|
||
@var{remapping} may be any face spec suitable for a @code{face} text
|
||
property: either a face (i.e., a face name or a property list of
|
||
attribute/value pairs), or a list of faces. For details, see the
|
||
description of the @code{face} text property in @ref{Special
|
||
Properties}. @var{remapping} serves as the complete specification for
|
||
the remapped face---it replaces the normal definition of @var{face},
|
||
instead of modifying it.
|
||
|
||
If @code{face-remapping-alist} is buffer-local, its local value takes
|
||
effect only within that buffer.
|
||
|
||
Note: face remapping is non-recursive. If @var{remapping} references
|
||
the same face name @var{face}, either directly or via the
|
||
@code{:inherit} attribute of some other face in @var{remapping}, that
|
||
reference uses the normal definition of @var{face}. For instance, if
|
||
the @code{mode-line} face is remapped using this entry in
|
||
@code{face-remapping-alist}:
|
||
|
||
@example
|
||
(mode-line italic mode-line)
|
||
@end example
|
||
|
||
@noindent
|
||
then the new definition of the @code{mode-line} face inherits from the
|
||
@code{italic} face, and the @emph{normal} (non-remapped) definition of
|
||
@code{mode-line} face.
|
||
@end defvar
|
||
|
||
@cindex relative remapping, faces
|
||
@cindex base remapping, faces
|
||
The following functions implement a higher-level interface to
|
||
@code{face-remapping-alist}. Most Lisp code should use these
|
||
functions instead of setting @code{face-remapping-alist} directly, to
|
||
avoid trampling on remappings applied elsewhere. These functions are
|
||
intended for buffer-local remappings, so they all make
|
||
@code{face-remapping-alist} buffer-local as a side-effect. They manage
|
||
@code{face-remapping-alist} entries of the form
|
||
|
||
@example
|
||
(@var{face} @var{relative-spec-1} @var{relative-spec-2} @var{...} @var{base-spec})
|
||
@end example
|
||
|
||
@noindent
|
||
where, as explained above, each of the @var{relative-spec-N} and
|
||
@var{base-spec} is either a face name, or a property list of
|
||
attribute/value pairs. Each of the @dfn{relative remapping} entries,
|
||
@var{relative-spec-N}, is managed by the
|
||
@code{face-remap-add-relative} and @code{face-remap-remove-relative}
|
||
functions; these are intended for simple modifications like changing
|
||
the text size. The @dfn{base remapping} entry, @var{base-spec}, has
|
||
the lowest priority and is managed by the @code{face-remap-set-base}
|
||
and @code{face-remap-reset-base} functions; it is intended for major
|
||
modes to remap faces in the buffers they control.
|
||
|
||
@defun face-remap-add-relative face &rest specs
|
||
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.
|
||
|
||
The return value is a Lisp object that serves as a cookie; you can
|
||
pass this object as an argument to @code{face-remap-remove-relative}
|
||
if you need to remove the remapping later.
|
||
|
||
@example
|
||
;; Remap the 'escape-glyph' face into a combination
|
||
;; of the 'highlight' and 'italic' faces:
|
||
(face-remap-add-relative 'escape-glyph 'highlight 'italic)
|
||
|
||
;; Increase the size of the 'default' face by 50%:
|
||
(face-remap-add-relative 'default :height 1.5)
|
||
@end example
|
||
@end defun
|
||
|
||
@defun face-remap-remove-relative cookie
|
||
This function removes a relative remapping previously added by
|
||
@code{face-remap-add-relative}. @var{cookie} should be the Lisp
|
||
object returned by @code{face-remap-add-relative} when the remapping
|
||
was added.
|
||
@end defun
|
||
|
||
@defun face-remap-set-base face &rest specs
|
||
This function sets the base remapping of @var{face} in the current
|
||
buffer to @var{specs}. If @var{specs} is empty, the default base
|
||
remapping is restored, similar to calling @code{face-remap-reset-base}
|
||
(see below); note that this is different from @var{specs} containing a
|
||
single value @code{nil}, which has the opposite result (the global
|
||
definition of @var{face} is ignored).
|
||
|
||
This overwrites the default @var{base-spec}, which inherits the global
|
||
face definition, so it is up to the caller to add such inheritance if
|
||
so desired.
|
||
@end defun
|
||
|
||
@defun face-remap-reset-base face
|
||
This function sets the base remapping of @var{face} to its default
|
||
value, which inherits from @var{face}'s global definition.
|
||
@end defun
|
||
|
||
@node Face Functions
|
||
@subsection Functions for Working with Faces
|
||
|
||
Here are additional functions for creating and working with faces.
|
||
|
||
@defun face-list
|
||
This function returns a list of all defined face names.
|
||
@end defun
|
||
|
||
@defun face-id face
|
||
This function returns the @dfn{face number} of face @var{face}. This
|
||
is a number that uniquely identifies a face at low levels within
|
||
Emacs. It is seldom necessary to refer to a face by its face number.
|
||
@end defun
|
||
|
||
@defun face-documentation face
|
||
This function returns the documentation string of face @var{face}, or
|
||
@code{nil} if none was specified for it.
|
||
@end defun
|
||
|
||
@defun face-equal face1 face2 &optional frame
|
||
This returns @code{t} if the faces @var{face1} and @var{face2} have the
|
||
same attributes for display.
|
||
@end defun
|
||
|
||
@defun face-differs-from-default-p face &optional frame
|
||
This returns non-@code{nil} if the face @var{face} displays
|
||
differently from the default face.
|
||
@end defun
|
||
|
||
@cindex face alias
|
||
@cindex alias, for faces
|
||
A @dfn{face alias} provides an equivalent name for a face. You can
|
||
define a face alias by giving the alias symbol the @code{face-alias}
|
||
property, with a value of the target face name. The following example
|
||
makes @code{modeline} an alias for the @code{mode-line} face.
|
||
|
||
@example
|
||
(put 'modeline 'face-alias 'mode-line)
|
||
@end example
|
||
|
||
@defmac define-obsolete-face-alias obsolete-face current-face when
|
||
This macro defines @code{obsolete-face} as an alias for
|
||
@var{current-face}, and also marks it as obsolete, indicating that it
|
||
may be removed in future. @var{when} should be a string indicating
|
||
when @code{obsolete-face} was made obsolete (usually a version number
|
||
string).
|
||
@end defmac
|
||
|
||
@node Auto Faces
|
||
@subsection Automatic Face Assignment
|
||
@cindex automatic face assignment
|
||
@cindex faces, automatic choice
|
||
|
||
This hook is used for automatically assigning faces to text in the
|
||
buffer. It is part of the implementation of Jit-Lock mode, used by
|
||
Font-Lock.
|
||
|
||
@defvar fontification-functions
|
||
This variable holds a list of functions that are called by Emacs
|
||
redisplay as needed, just before doing redisplay. They are called even
|
||
when Font Lock Mode isn't enabled. When Font Lock Mode is enabled, this
|
||
variable usually holds just one function, @code{jit-lock-function}.
|
||
|
||
The functions are called in the order listed, with one argument, a
|
||
buffer position @var{pos}. Collectively they should attempt to assign
|
||
faces to the text in the current buffer starting at @var{pos}.
|
||
|
||
The functions should record the faces they assign by setting the
|
||
@code{face} property. They should also add a non-@code{nil}
|
||
@code{fontified} property to all the text they have assigned faces to.
|
||
That property tells redisplay that faces have been assigned to that text
|
||
already.
|
||
|
||
It is probably a good idea for the functions to do nothing if the
|
||
character after @var{pos} already has a non-@code{nil} @code{fontified}
|
||
property, but this is not required. If one function overrides the
|
||
assignments made by a previous one, the properties after the last
|
||
function finishes are the ones that really matter.
|
||
|
||
For efficiency, we recommend writing these functions so that they
|
||
usually assign faces to around 400 to 600 characters at each call.
|
||
@end defvar
|
||
|
||
@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,
|
||
rather than defining entirely new faces. This way, if other users
|
||
have customized the basic faces to give Emacs a certain look, your
|
||
program will fit in without additional customization.
|
||
|
||
Some of the basic faces defined in Emacs are listed below. In
|
||
addition to these, you might want to make use of the Font Lock faces
|
||
for syntactic highlighting, if highlighting is not already handled by
|
||
Font Lock mode, or if some Font Lock faces are not in use.
|
||
@xref{Faces for Font Lock}.
|
||
|
||
@table @code
|
||
@item default
|
||
The default face, whose attributes are all specified. All other faces
|
||
implicitly inherit from it: any unspecified attribute defaults to the
|
||
attribute on this face (@pxref{Face Attributes}).
|
||
|
||
@item bold
|
||
@itemx italic
|
||
@itemx bold-italic
|
||
@itemx underline
|
||
@itemx fixed-pitch
|
||
@itemx fixed-pitch-serif
|
||
@itemx variable-pitch
|
||
These have the attributes indicated by their names (e.g., @code{bold}
|
||
has a bold @code{:weight} attribute), with all other attributes
|
||
unspecified (and so given by @code{default}).
|
||
|
||
@item shadow
|
||
For dimmed-out text. For example, it is used for the ignored
|
||
part of a filename in the minibuffer (@pxref{Minibuffer File,,
|
||
Minibuffers for File Names, emacs, The GNU Emacs Manual}).
|
||
|
||
@item link
|
||
@itemx link-visited
|
||
For clickable text buttons that send the user to a different
|
||
buffer or location.
|
||
|
||
@item highlight
|
||
For stretches of text that should temporarily stand out. For example,
|
||
it is commonly assigned to the @code{mouse-face} property for cursor
|
||
highlighting (@pxref{Special Properties}).
|
||
|
||
@item match
|
||
@itemx isearch
|
||
@itemx lazy-highlight
|
||
For text matching (respectively) permanent search matches, interactive
|
||
search matches, and lazy highlighting other matches than the current
|
||
interactive one.
|
||
|
||
@item error
|
||
@itemx warning
|
||
@itemx success
|
||
For text concerning errors, warnings, or successes. For example,
|
||
these are used for messages in @file{*Compilation*} buffers.
|
||
@end table
|
||
|
||
@node Font Selection
|
||
@subsection Font Selection
|
||
@cindex font selection
|
||
@cindex selecting a font
|
||
|
||
Before Emacs can draw a character on a graphical display, it must
|
||
select a @dfn{font} for that character@footnote{In this context, the
|
||
term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
|
||
Mode}).}. @xref{Fonts,,, emacs, The GNU Emacs Manual}. Normally,
|
||
Emacs automatically chooses a font based on the faces assigned to that
|
||
character---specifically, the face attributes @code{:family},
|
||
@code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face
|
||
Attributes}). The choice of font also depends on the character to be
|
||
displayed; some fonts can only display a limited set of characters.
|
||
If no available font exactly fits the requirements, Emacs looks for
|
||
the @dfn{closest matching font}. The variables in this section
|
||
control how Emacs makes this selection.
|
||
|
||
@defopt face-font-family-alternatives
|
||
If a given family is specified but does not exist, this variable
|
||
specifies alternative font families to try. Each element should have
|
||
this form:
|
||
|
||
@example
|
||
(@var{family} @var{alternate-families}@dots{})
|
||
@end example
|
||
|
||
If @var{family} is specified but not available, Emacs will try the other
|
||
families given in @var{alternate-families}, one by one, until it finds a
|
||
family that does exist.
|
||
@end defopt
|
||
|
||
@defopt face-font-selection-order
|
||
If there is no font that exactly matches all desired face attributes
|
||
(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
|
||
this variable specifies the order in which these attributes should be
|
||
considered when selecting the closest matching font. The value should
|
||
be a list containing those four attribute symbols, in order of
|
||
decreasing importance. The default is @code{(:width :height :weight
|
||
:slant)}.
|
||
|
||
Font selection first finds the best available matches for the first
|
||
attribute in the list; then, among the fonts which are best in that
|
||
way, it searches for the best matches in the second attribute, and so
|
||
on.
|
||
|
||
The attributes @code{:weight} and @code{:width} have symbolic values in
|
||
a range centered around @code{normal}. Matches that are more extreme
|
||
(farther from @code{normal}) are somewhat preferred to matches that are
|
||
less extreme (closer to @code{normal}); this is designed to ensure that
|
||
non-normal faces contrast with normal ones, whenever possible.
|
||
|
||
One example of a case where this variable makes a difference is when the
|
||
default font has no italic equivalent. With the default ordering, the
|
||
@code{italic} face will use a non-italic font that is similar to the
|
||
default one. But if you put @code{:slant} before @code{:height}, the
|
||
@code{italic} face will use an italic font, even if its height is not
|
||
quite right.
|
||
@end defopt
|
||
|
||
@defopt face-font-registry-alternatives
|
||
This variable lets you specify alternative font registries to try, if a
|
||
given registry is specified and doesn't exist. Each element should have
|
||
this form:
|
||
|
||
@example
|
||
(@var{registry} @var{alternate-registries}@dots{})
|
||
@end example
|
||
|
||
If @var{registry} is specified but not available, Emacs will try the
|
||
other registries given in @var{alternate-registries}, one by one,
|
||
until it finds a registry that does exist.
|
||
@end defopt
|
||
|
||
@cindex scalable fonts
|
||
Emacs can make use of scalable fonts, but by default it does not use
|
||
them.
|
||
|
||
@defopt scalable-fonts-allowed
|
||
This variable controls which scalable fonts to use. A value of
|
||
@code{nil}, the default, means do not use scalable fonts. @code{t}
|
||
means to use any scalable font that seems appropriate for the text.
|
||
|
||
Otherwise, the value must be a list of regular expressions. Then a
|
||
scalable font is enabled for use if its name matches any regular
|
||
expression in the list. For example,
|
||
|
||
@example
|
||
(setq scalable-fonts-allowed '("iso10646-1$"))
|
||
@end example
|
||
|
||
@noindent
|
||
allows the use of scalable fonts with registry @code{iso10646-1}.
|
||
@end defopt
|
||
|
||
@defvar face-font-rescale-alist
|
||
This variable specifies scaling for certain faces. Its value should
|
||
be a list of elements of the form
|
||
|
||
@example
|
||
(@var{fontname-regexp} . @var{scale-factor})
|
||
@end example
|
||
|
||
If @var{fontname-regexp} matches the font name that is about to be
|
||
used, this says to choose a larger similar font according to the
|
||
factor @var{scale-factor}. You would use this feature to normalize
|
||
the font size if certain fonts are bigger or smaller than their
|
||
nominal heights and widths would suggest.
|
||
@end defvar
|
||
|
||
@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
|
||
@var{name}. @var{name} should be a string containing a font name in
|
||
either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The
|
||
GNU Emacs Manual}). Within an XLFD string, wildcard characters may be
|
||
used: the @samp{*} character matches any substring, and the @samp{?}
|
||
character matches any single character. Case is ignored when matching
|
||
font names.
|
||
|
||
If the optional arguments @var{reference-face} and @var{frame} are
|
||
specified, the returned list includes only fonts that are the same
|
||
size as @var{reference-face} (a face name) currently is on the frame
|
||
@var{frame}.
|
||
|
||
The optional argument @var{maximum} sets a limit on how many fonts to
|
||
return. If it is non-@code{nil}, then the return value is truncated
|
||
after the first @var{maximum} matching fonts. Specifying a small
|
||
value for @var{maximum} can make this function much faster, in cases
|
||
where many fonts match the pattern.
|
||
|
||
The optional argument @var{width} specifies a desired font width. If
|
||
it is non-@code{nil}, the function only returns those fonts whose
|
||
characters are (on average) @var{width} times as wide as
|
||
@var{reference-face}.
|
||
@end defun
|
||
|
||
@defun x-family-fonts &optional family frame
|
||
This function returns a list describing the available fonts for family
|
||
@var{family} on @var{frame}. If @var{family} is omitted or @code{nil},
|
||
this list applies to all families, and therefore, it contains all
|
||
available fonts. Otherwise, @var{family} must be a string; it may
|
||
contain the wildcards @samp{?} and @samp{*}.
|
||
|
||
The list describes the display that @var{frame} is on; if @var{frame} is
|
||
omitted or @code{nil}, it applies to the selected frame's display
|
||
(@pxref{Input Focus}).
|
||
|
||
Each element in the list is a vector of the following form:
|
||
|
||
@example
|
||
[@var{family} @var{width} @var{point-size} @var{weight} @var{slant}
|
||
@var{fixed-p} @var{full} @var{registry-and-encoding}]
|
||
@end example
|
||
|
||
The first five elements correspond to face attributes; if you
|
||
specify these attributes for a face, it will use this font.
|
||
|
||
The last three elements give additional information about the font.
|
||
@var{fixed-p} is non-@code{nil} if the font is fixed-pitch.
|
||
@var{full} is the full name of the font, and
|
||
@var{registry-and-encoding} is a string giving the registry and
|
||
encoding of the font.
|
||
@end defun
|
||
|
||
@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
|
||
characters that Emacs supports, but a fontset can. Fontsets have names,
|
||
just as fonts do, and you can use a fontset name in place of a font name
|
||
when you specify the font for a frame or a face. Here is
|
||
information about defining a fontset under Lisp program control.
|
||
|
||
@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
|
||
This function defines a new fontset according to the specification
|
||
string @var{fontset-spec}. The string should have this format:
|
||
|
||
@smallexample
|
||
@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}}
|
||
@end smallexample
|
||
|
||
@noindent
|
||
Whitespace characters before and after the commas are ignored.
|
||
|
||
The first part of the string, @var{fontpattern}, should have the form of
|
||
a standard X font name, except that the last two fields should be
|
||
@samp{fontset-@var{alias}}.
|
||
|
||
The new fontset has two names, one long and one short. The long name is
|
||
@var{fontpattern} in its entirety. The short name is
|
||
@samp{fontset-@var{alias}}. You can refer to the fontset by either
|
||
name. If a fontset with the same name already exists, an error is
|
||
signaled, unless @var{noerror} is non-@code{nil}, in which case this
|
||
function does nothing.
|
||
|
||
If optional argument @var{style-variant-p} is non-@code{nil}, that says
|
||
to create bold, italic and bold-italic variants of the fontset as well.
|
||
These variant fontsets do not have a short name, only a long one, which
|
||
is made by altering @var{fontpattern} to indicate the bold and/or italic
|
||
status.
|
||
|
||
The specification string also says which fonts to use in the fontset.
|
||
See below for the details.
|
||
@end defun
|
||
|
||
The construct @samp{@var{charset}:@var{font}} specifies which font to
|
||
use (in this fontset) for one particular character set. Here,
|
||
@var{charset} is the name of a character set, and @var{font} is the font
|
||
to use for that character set. You can use this construct any number of
|
||
times in the specification string.
|
||
|
||
For the remaining character sets, those that you don't specify
|
||
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
|
||
@samp{fontset-@var{alias}} with a value that names one character set.
|
||
For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced
|
||
with @samp{ISO8859-1}.
|
||
|
||
In addition, when several consecutive fields are wildcards, Emacs
|
||
collapses them into a single wildcard. This is to prevent use of
|
||
auto-scaled fonts. Fonts made by scaling larger fonts are not usable
|
||
for editing, and scaling a smaller font is not useful because it is
|
||
better to use the smaller font in its own size, which Emacs does.
|
||
|
||
Thus if @var{fontpattern} is this,
|
||
|
||
@example
|
||
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
|
||
@end example
|
||
|
||
@noindent
|
||
the font specification for @acronym{ASCII} characters would be this:
|
||
|
||
@example
|
||
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
|
||
@end example
|
||
|
||
@noindent
|
||
and the font specification for Chinese GB2312 characters would be this:
|
||
|
||
@example
|
||
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
|
||
@end example
|
||
|
||
You may not have any Chinese font matching the above font
|
||
specification. Most X distributions include only Chinese fonts that
|
||
have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
|
||
such a case, @samp{Fontset-@var{n}} can be specified as below:
|
||
|
||
@smallexample
|
||
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
|
||
chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
|
||
@end smallexample
|
||
|
||
@noindent
|
||
Then, the font specifications for all but Chinese GB2312 characters have
|
||
@samp{fixed} in the @var{family} field, and the font specification for
|
||
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
|
||
field.
|
||
|
||
@defun set-fontset-font name character font-spec &optional frame add
|
||
This function modifies the existing fontset @var{name} to use the font
|
||
matching with @var{font-spec} for the specified @var{character}.
|
||
|
||
If @var{name} is @code{nil}, this function modifies the fontset of the
|
||
selected frame or that of @var{frame} if @var{frame} is not
|
||
@code{nil}.
|
||
|
||
If @var{name} is @code{t}, this function modifies the default
|
||
fontset, whose short name is @samp{fontset-default}.
|
||
|
||
In addition to specifying a single codepoint, @var{character} may be a
|
||
cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are
|
||
character codepoints. In that case, use @var{font-spec} for all the
|
||
characters in the range @var{from} and @var{to} (inclusive).
|
||
|
||
@var{character} may be a charset. In that case, use
|
||
@var{font-spec} for all character in the charsets.
|
||
|
||
@var{character} may be a script name. In that case, use
|
||
@var{font-spec} for all character in the charsets.
|
||
|
||
@var{font-spec} may be a font-spec object created by the function
|
||
@code{font-spec} (@pxref{Low-Level Font}).
|
||
|
||
@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
|
||
where @var{family} is a family name of a font (possibly including a
|
||
foundry name at the head), @var{registry} is a registry name of a font
|
||
(possibly including an encoding name at the tail).
|
||
|
||
@var{font-spec} may be a font name string.
|
||
|
||
@var{font-spec} may be @code{nil}, which explicitly specifies that
|
||
there's no font for the specified @var{character}. This is useful,
|
||
for example, to avoid expensive system-wide search for fonts for
|
||
characters that have no glyphs, like those from the Unicode Private
|
||
Use Area (PUA).
|
||
|
||
The optional argument @var{add}, if non-@code{nil}, specifies how to
|
||
add @var{font-spec} to the font specifications previously set. If it
|
||
is @code{prepend}, @var{font-spec} is prepended. If it is
|
||
@code{append}, @var{font-spec} is appended. By default,
|
||
@var{font-spec} overrides the previous settings.
|
||
|
||
For instance, this changes the default fontset to use a font of which
|
||
family name is @samp{Kochi Gothic} for all characters belonging to
|
||
the charset @code{japanese-jisx0208}.
|
||
|
||
@smallexample
|
||
(set-fontset-font t 'japanese-jisx0208
|
||
(font-spec :family "Kochi Gothic"))
|
||
@end smallexample
|
||
@end defun
|
||
|
||
@defun char-displayable-p char
|
||
This function returns @code{t} if Emacs ought to be able to display
|
||
@var{char}. More precisely, if the selected frame's fontset has a
|
||
font to display the character set that @var{char} belongs to.
|
||
|
||
Fontsets can specify a font on a per-character basis; when the fontset
|
||
does that, this function's value may not be accurate.
|
||
@end defun
|
||
|
||
@node Low-Level Font
|
||
@subsection Low-Level Font Representation
|
||
@cindex font property
|
||
|
||
Normally, it is not necessary to manipulate fonts directly. In case
|
||
you need to do so, this section explains how.
|
||
|
||
In Emacs Lisp, fonts are represented using three different Lisp
|
||
object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
|
||
entities}.
|
||
|
||
@defun fontp object &optional type
|
||
Return @code{t} if @var{object} is a font object, font spec, or font
|
||
entity. Otherwise, return @code{nil}.
|
||
|
||
The optional argument @var{type}, if non-@code{nil}, determines the
|
||
exact type of Lisp object to check for. In that case, @var{type}
|
||
should be one of @code{font-object}, @code{font-spec}, or
|
||
@code{font-entity}.
|
||
@end defun
|
||
|
||
@cindex font object
|
||
A font object is a Lisp object that represents a font that Emacs has
|
||
@dfn{opened}. Font objects cannot be modified in Lisp, but they can
|
||
be inspected.
|
||
|
||
@defun font-at position &optional window string
|
||
Return the font object that is being used to display the character at
|
||
position @var{position} in the window @var{window}. If @var{window}
|
||
is @code{nil}, it defaults to the selected window. If @var{string} is
|
||
@code{nil}, @var{position} specifies a position in the current buffer;
|
||
otherwise, @var{string} should be a string, and @var{position}
|
||
specifies a position in that string.
|
||
@end defun
|
||
|
||
@cindex font spec
|
||
A font spec is a Lisp object that contains a set of specifications
|
||
that can be used to find a font. More than one font may match the
|
||
specifications in a font spec.
|
||
|
||
@defun font-spec &rest arguments
|
||
Return a new font spec using the specifications in @var{arguments},
|
||
which should come in @code{property}-@code{value} pairs. The possible
|
||
specifications are as follows:
|
||
|
||
@table @code
|
||
@item :name
|
||
The font name (a string), in either XLFD, Fontconfig, or GTK format.
|
||
@xref{Fonts,,, emacs, The GNU Emacs Manual}.
|
||
|
||
@item :family
|
||
@itemx :foundry
|
||
@itemx :weight
|
||
@itemx :slant
|
||
@itemx :width
|
||
These have the same meanings as the face attributes of the same name.
|
||
@xref{Face Attributes}.
|
||
|
||
@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.
|
||
|
||
@item :adstyle
|
||
Additional typographic style information for the font, such as
|
||
@samp{sans}. The value should be a string or a symbol.
|
||
|
||
@cindex font registry
|
||
@item :registry
|
||
The charset registry and encoding of the font, such as
|
||
@samp{iso8859-1}. The value should be a string or a symbol.
|
||
|
||
@item :script
|
||
The script that the font must support (a symbol).
|
||
|
||
@item :lang
|
||
The language that the font should support. The value should be a
|
||
symbol whose name is a two-letter ISO-639 language name. On X, the
|
||
value is matched against the ``Additional Style'' field of the XLFD
|
||
name of a font, if it is non-empty. On MS-Windows, fonts matching the
|
||
spec are required to support codepages needed for the language.
|
||
Currently, only a small set of CJK languages is supported with this
|
||
property: @samp{ja}, @samp{ko}, and @samp{zh}.
|
||
|
||
@item :otf
|
||
@cindex OpenType font
|
||
The font must be an OpenType font that supports these OpenType
|
||
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})}
|
||
@end smallexample
|
||
|
||
where @var{script-tag} is the OpenType script tag symbol;
|
||
@var{langsys-tag} is the OpenType language system tag symbol, or
|
||
@code{nil} to use the default language system; @code{gsub} is a list
|
||
of OpenType GSUB feature tag symbols, or @code{nil} if none is
|
||
required; and @code{gpos} is a list of OpenType GPOS feature tag
|
||
symbols, or @code{nil} if none is required. If @code{gsub} or
|
||
@code{gpos} is a list, a @code{nil} element in that list means that
|
||
the font must not match any of the remaining tag symbols. The
|
||
@code{gpos} element may be omitted.
|
||
@end table
|
||
@end defun
|
||
|
||
@defun font-put font-spec property value
|
||
Set the font property @var{property} in the font-spec @var{font-spec}
|
||
to @var{value}.
|
||
@end defun
|
||
|
||
@cindex font entity
|
||
A font entity is a reference to a font that need not be open. Its
|
||
properties are intermediate between a font object and a font spec:
|
||
like a font object, and unlike a font spec, it refers to a single,
|
||
specific font. Unlike a font object, creating a font entity does not
|
||
load the contents of that font into computer memory. Emacs may open
|
||
multiple font objects of different sizes from a single font entity
|
||
referring to a scalable font.
|
||
|
||
@defun find-font font-spec &optional frame
|
||
This function returns a font entity that best matches the font spec
|
||
@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil},
|
||
it defaults to the selected frame.
|
||
@end defun
|
||
|
||
@defun list-fonts font-spec &optional frame num prefer
|
||
This function returns a list of all font entities that match the font
|
||
spec @var{font-spec}.
|
||
|
||
The optional argument @var{frame}, if non-@code{nil}, specifies the
|
||
frame on which the fonts are to be displayed. The optional argument
|
||
@var{num}, if non-@code{nil}, should be an integer that specifies the
|
||
maximum length of the returned list. The optional argument
|
||
@var{prefer}, if non-@code{nil}, should be another font spec, which is
|
||
used to control the order of the returned list; the returned font
|
||
entities are sorted in order of decreasing closeness to that font
|
||
spec.
|
||
@end defun
|
||
|
||
If you call @code{set-face-attribute} and pass a font spec, font
|
||
entity, or font name string as the value of the @code{:font}
|
||
attribute, Emacs opens the best matching font that is available
|
||
for display. It then stores the corresponding font object as the
|
||
actual value of the @code{:font} attribute for that face.
|
||
|
||
The following functions can be used to obtain information about a
|
||
font. For these functions, the @var{font} argument can be a font
|
||
object, a font entity, or a font spec.
|
||
|
||
@defun font-get font property
|
||
This function returns the value of the font property @var{property}
|
||
for @var{font}.
|
||
|
||
If @var{font} is a font spec and the font spec does not specify
|
||
@var{property}, the return value is @code{nil}. If @var{font} is a
|
||
font object or font entity, the value for the @var{:script} property
|
||
may be a list of scripts supported by the font.
|
||
@end defun
|
||
|
||
@defun font-face-attributes font &optional frame
|
||
This function returns a list of face attributes corresponding to
|
||
@var{font}. The optional argument @var{frame} specifies the frame on
|
||
which the font is to be displayed. If it is @code{nil}, the selected
|
||
frame is used. The return value has the form
|
||
|
||
@smallexample
|
||
(:family @var{family} :height @var{height} :weight @var{weight}
|
||
:slant @var{slant} :width @var{width})
|
||
@end smallexample
|
||
|
||
where the values of @var{family}, @var{height}, @var{weight},
|
||
@var{slant}, and @var{width} are face attribute values. Some of these
|
||
key-attribute pairs may be omitted from the list if they are not
|
||
specified by @var{font}.
|
||
@end defun
|
||
|
||
@defun font-xlfd-name font &optional fold-wildcards
|
||
This function returns the XLFD (X Logical Font Descriptor), a string,
|
||
matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for
|
||
information about XLFDs. If the name is too long for an XLFD (which
|
||
can contain at most 255 characters), the function returns @code{nil}.
|
||
|
||
If the optional argument @var{fold-wildcards} is non-@code{nil},
|
||
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
|
||
|
||
@cindex font information for layout
|
||
The following four functions return size information about fonts used
|
||
by various faces, allowing various layout considerations in Lisp
|
||
programs. These functions take face remapping into consideration,
|
||
returning information about the remapped face, if the face in question
|
||
was remapped. @xref{Face Remapping}.
|
||
|
||
@defun default-font-width
|
||
This function returns the average width in pixels of the font used by
|
||
the current buffer's default face.
|
||
@end defun
|
||
|
||
@defun default-font-height
|
||
This function returns the height in pixels of the font used by the
|
||
current buffer's default face.
|
||
@end defun
|
||
|
||
@defun window-font-width &optional window face
|
||
This function returns the average width in pixels for the font used by
|
||
@var{face} in @var{window}. The specified @var{window} must be a live
|
||
window. If @code{nil} or omitted, @var{window} defaults to the
|
||
selected window, and @var{face} defaults to the default face in
|
||
@var{window}.
|
||
@end defun
|
||
|
||
@defun window-font-height &optional window face
|
||
This function returns the height in pixels for the font used by
|
||
@var{face} in @var{window}. The specified @var{window} must be a live
|
||
window. If @code{nil} or omitted, @var{window} defaults to the
|
||
selected window, and @var{face} defaults to the default face in
|
||
@var{window}.
|
||
@end defun
|
||
|
||
@node Fringes
|
||
@section Fringes
|
||
@cindex fringes
|
||
|
||
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.
|
||
* Fringe Indicators:: Displaying indicator icons in the window fringes.
|
||
* Fringe Cursors:: Displaying cursors in the right fringe.
|
||
* Fringe Bitmaps:: Specifying bitmaps for fringe indicators.
|
||
* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
|
||
* Overlay Arrow:: Display of an arrow to indicate position.
|
||
@end menu
|
||
|
||
@node Fringe Size/Pos
|
||
@subsection Fringe Size and Position
|
||
|
||
The following buffer-local variables control the position and width
|
||
of fringes in windows showing that buffer.
|
||
|
||
@defvar fringes-outside-margins
|
||
The fringes normally appear between the display margins and the window
|
||
text. If the value is non-@code{nil}, they appear outside the display
|
||
margins. @xref{Display Margins}.
|
||
@end defvar
|
||
|
||
@defvar left-fringe-width
|
||
This variable, if non-@code{nil}, specifies the width of the left
|
||
fringe in pixels. A value of @code{nil} means to use the left fringe
|
||
width from the window's frame.
|
||
@end defvar
|
||
|
||
@defvar right-fringe-width
|
||
This variable, if non-@code{nil}, specifies the width of the right
|
||
fringe in pixels. A value of @code{nil} means to use the right fringe
|
||
width from the window's frame.
|
||
@end defvar
|
||
|
||
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}.
|
||
If @var{window} is @code{nil}, the selected window is used.
|
||
|
||
The argument @var{left} specifies the width in pixels of the left
|
||
fringe, and likewise @var{right} for the right fringe. A value of
|
||
@code{nil} for either one stands for the default width. If
|
||
@var{outside-margins} is non-@code{nil}, that specifies that fringes
|
||
should appear outside of the display margins.
|
||
@end defun
|
||
|
||
@defun window-fringes &optional window
|
||
This function returns information about the fringes of a window
|
||
@var{window}. If @var{window} is omitted or @code{nil}, the selected
|
||
window is used. The value has the form @code{(@var{left-width}
|
||
@var{right-width} @var{outside-margins})}.
|
||
@end defun
|
||
|
||
|
||
@node Fringe Indicators
|
||
@subsection Fringe Indicators
|
||
@cindex fringe indicators
|
||
@cindex indicators, fringe
|
||
|
||
@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
|
||
@cindex empty lines, indicating
|
||
When this is non-@code{nil}, Emacs displays a special glyph in the
|
||
fringe of each empty line at the end of the buffer, on graphical
|
||
displays. @xref{Fringes}. This variable is automatically
|
||
buffer-local in every buffer.
|
||
@end defopt
|
||
|
||
@defopt indicate-buffer-boundaries
|
||
@cindex buffer boundaries, indicating
|
||
This buffer-local variable controls how the buffer boundaries and
|
||
window scrolling are indicated in the window fringes.
|
||
|
||
Emacs can indicate the buffer boundaries---that is, the first and last
|
||
line in the buffer---with angle icons when they appear on the screen.
|
||
In addition, Emacs can display an up-arrow in the fringe to show
|
||
that there is text above the screen, and a down-arrow to show
|
||
there is text below the screen.
|
||
|
||
There are three kinds of basic values:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
Don't display any of these fringe icons.
|
||
@item @code{left}
|
||
Display the angle icons and arrows in the left fringe.
|
||
@item @code{right}
|
||
Display the angle icons and arrows in the right fringe.
|
||
@item any non-alist
|
||
Display the angle icons in the left fringe
|
||
and don't display the arrows.
|
||
@end table
|
||
|
||
Otherwise the value should be an alist that specifies which fringe
|
||
indicators to display and where. Each element of the alist should
|
||
have the form @code{(@var{indicator} . @var{position})}. Here,
|
||
@var{indicator} is one of @code{top}, @code{bottom}, @code{up},
|
||
@code{down}, and @code{t} (which covers all the icons not yet
|
||
specified), while @var{position} is one of @code{left}, @code{right}
|
||
and @code{nil}.
|
||
|
||
For example, @code{((top . left) (t . right))} places the top angle
|
||
bitmap in left fringe, and the bottom angle bitmap as well as both
|
||
arrow bitmaps in right fringe. To show the angle bitmaps in the left
|
||
fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
|
||
@end defopt
|
||
|
||
@defvar fringe-indicator-alist
|
||
This buffer-local variable specifies the mapping from logical fringe
|
||
indicators to the actual bitmaps displayed in the window fringes. The
|
||
value is an alist of elements @code{(@var{indicator}
|
||
. @var{bitmaps})}, where @var{indicator} specifies a logical indicator
|
||
type and @var{bitmaps} specifies the fringe bitmaps to use for that
|
||
indicator.
|
||
|
||
Each @var{indicator} should be one of the following symbols:
|
||
|
||
@table @asis
|
||
@item @code{truncation}, @code{continuation}.
|
||
Used for truncation and continuation lines.
|
||
|
||
@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom}
|
||
Used when @code{indicate-buffer-boundaries} is non-@code{nil}:
|
||
@code{up} and @code{down} indicate a buffer boundary lying above or
|
||
below the window edge; @code{top} and @code{bottom} indicate the
|
||
topmost and bottommost buffer text line; and @code{top-bottom}
|
||
indicates where there is just one line of text in the buffer.
|
||
|
||
@item @code{empty-line}
|
||
Used to indicate empty lines when @code{indicate-empty-lines} is
|
||
non-@code{nil}.
|
||
|
||
@item @code{overlay-arrow}
|
||
Used for overlay arrows (@pxref{Overlay Arrow}).
|
||
@c Is this used anywhere?
|
||
@c @item Unknown bitmap indicator:
|
||
@c @code{unknown}.
|
||
@end table
|
||
|
||
Each @var{bitmaps} value may be a list of symbols @code{(@var{left}
|
||
@var{right} [@var{left1} @var{right1}])}. The @var{left} and
|
||
@var{right} symbols specify the bitmaps shown in the left and/or right
|
||
fringe, for the specific indicator. @var{left1} and @var{right1} are
|
||
specific to the @code{bottom} and @code{top-bottom} indicators, and
|
||
are used to indicate that the last text line has no final newline.
|
||
Alternatively, @var{bitmaps} may be a single symbol which is used in
|
||
both left and right fringes.
|
||
|
||
@xref{Fringe Bitmaps}, for a list of standard bitmap symbols and how
|
||
to define your own. In addition, @code{nil} represents the empty
|
||
bitmap (i.e., an indicator that is not shown).
|
||
|
||
When @code{fringe-indicator-alist} has a buffer-local value, and
|
||
there is no bitmap defined for a logical indicator, or the bitmap is
|
||
@code{t}, the corresponding value from the default value of
|
||
@code{fringe-indicator-alist} is used.
|
||
@end defvar
|
||
|
||
@node Fringe Cursors
|
||
@subsection Fringe Cursors
|
||
@cindex fringe cursors
|
||
@cindex cursor, fringe
|
||
|
||
When a line is exactly as wide as the window, Emacs displays the
|
||
cursor in the right fringe instead of using two lines. Different
|
||
bitmaps are used to represent the cursor in the fringe depending on
|
||
the current buffer's cursor type.
|
||
|
||
@defopt overflow-newline-into-fringe
|
||
If this is non-@code{nil}, lines exactly as wide as the window (not
|
||
counting the final newline character) are not continued. Instead,
|
||
when point is at the end of the line, the cursor appears in the right
|
||
fringe.
|
||
@end defopt
|
||
|
||
@defvar fringe-cursor-alist
|
||
This variable specifies the mapping from logical cursor type to the
|
||
actual fringe bitmaps displayed in the right fringe. The value is an
|
||
alist where each element has the form @code{(@var{cursor-type}
|
||
. @var{bitmap})}, which means to use the fringe bitmap @var{bitmap} to
|
||
display cursors of type @var{cursor-type}.
|
||
|
||
Each @var{cursor-type} should be one of @code{box}, @code{hollow},
|
||
@code{bar}, @code{hbar}, or @code{hollow-small}. The first four have
|
||
the same meanings as in the @code{cursor-type} frame parameter
|
||
(@pxref{Cursor Parameters}). The @code{hollow-small} type is used
|
||
instead of @code{hollow} when the normal @code{hollow-rectangle}
|
||
bitmap is too tall to fit on a specific display line.
|
||
|
||
Each @var{bitmap} should be a symbol specifying the fringe bitmap to
|
||
be displayed for that logical cursor type.
|
||
@iftex
|
||
See the next subsection for details.
|
||
@end iftex
|
||
@ifnottex
|
||
@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
|
||
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.
|
||
@end defvar
|
||
|
||
@node Fringe Bitmaps
|
||
@subsection Fringe Bitmaps
|
||
@cindex fringe bitmaps
|
||
@cindex bitmaps, fringe
|
||
|
||
The @dfn{fringe bitmaps} are the actual bitmaps which represent the
|
||
logical fringe indicators for truncated or continued lines, buffer
|
||
boundaries, overlay arrows, etc. Each bitmap is represented by a
|
||
symbol.
|
||
@iftex
|
||
These symbols are referred to by the variables
|
||
@code{fringe-indicator-alist} and @code{fringe-cursor-alist},
|
||
described in the previous subsections.
|
||
@end iftex
|
||
@ifnottex
|
||
These symbols are referred to by the variable
|
||
@code{fringe-indicator-alist}, which maps fringe indicators to bitmaps
|
||
(@pxref{Fringe Indicators}), and the variable
|
||
@code{fringe-cursor-alist}, which maps fringe cursors to bitmaps
|
||
(@pxref{Fringe Cursors}).
|
||
@end ifnottex
|
||
|
||
Lisp programs can also directly display a bitmap in the left or
|
||
right fringe, by using a @code{display} property for one of the
|
||
characters appearing in the line (@pxref{Other Display Specs}). Such
|
||
a display specification has the form
|
||
|
||
@example
|
||
(@var{fringe} @var{bitmap} [@var{face}])
|
||
@end example
|
||
|
||
@noindent
|
||
@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
|
||
@code{fringe-indicator-alist} and @code{fringe-cursor-alist}):
|
||
|
||
@table @asis
|
||
@item @code{left-arrow}, @code{right-arrow}
|
||
Used to indicate truncated lines.
|
||
|
||
@item @code{left-curly-arrow}, @code{right-curly-arrow}
|
||
Used to indicate continued lines.
|
||
|
||
@item @code{right-triangle}, @code{left-triangle}
|
||
The former is used by overlay arrows. The latter is unused.
|
||
|
||
@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle}
|
||
@itemx @code{bottom-left-angle}, @code{bottom-right-angle}
|
||
@itemx @code{top-right-angle}, @code{top-left-angle}
|
||
@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle}
|
||
Used to indicate buffer boundaries.
|
||
|
||
@item @code{filled-rectangle}, @code{hollow-rectangle}
|
||
@itemx @code{filled-square}, @code{hollow-square}
|
||
@itemx @code{vertical-bar}, @code{horizontal-bar}
|
||
Used for different types of fringe cursors.
|
||
|
||
@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark}
|
||
Not used by core Emacs features.
|
||
@end table
|
||
|
||
@noindent
|
||
The next subsection describes how to define your own fringe bitmaps.
|
||
|
||
@defun fringe-bitmaps-at-pos &optional pos window
|
||
This function returns the fringe bitmaps of the display line
|
||
containing position @var{pos} in window @var{window}. The return
|
||
value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
|
||
is the symbol for the fringe bitmap in the left fringe (or @code{nil}
|
||
if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
|
||
is non-@code{nil} if there is an overlay arrow in the left fringe.
|
||
|
||
The value is @code{nil} if @var{pos} is not visible in @var{window}.
|
||
If @var{window} is @code{nil}, that stands for the selected window.
|
||
If @var{pos} is @code{nil}, that stands for the value of point in
|
||
@var{window}.
|
||
@end defun
|
||
|
||
@node Customizing Bitmaps
|
||
@subsection Customizing Fringe Bitmaps
|
||
@cindex fringe bitmaps, customizing
|
||
|
||
@defun define-fringe-bitmap bitmap bits &optional height width align
|
||
This function defines the symbol @var{bitmap} as a new fringe bitmap,
|
||
or replaces an existing bitmap with that name.
|
||
|
||
The argument @var{bits} specifies the image to use. It should be
|
||
either a string or a vector of integers, where each element (an
|
||
integer) corresponds to one row of the bitmap. Each bit of an integer
|
||
corresponds to one pixel of the bitmap, where the low bit corresponds
|
||
to the rightmost pixel of the bitmap.
|
||
|
||
The height is normally the length of @var{bits}. However, you
|
||
can specify a different height with non-@code{nil} @var{height}. The width
|
||
is normally 8, but you can specify a different width with non-@code{nil}
|
||
@var{width}. The width must be an integer between 1 and 16.
|
||
|
||
The argument @var{align} specifies the positioning of the bitmap
|
||
relative to the range of rows where it is used; the default is to
|
||
center the bitmap. The allowed values are @code{top}, @code{center},
|
||
or @code{bottom}.
|
||
|
||
The @var{align} argument may also be a list @code{(@var{align}
|
||
@var{periodic})} where @var{align} is interpreted as described above.
|
||
If @var{periodic} is non-@code{nil}, it specifies that the rows in
|
||
@code{bits} should be repeated enough times to reach the specified
|
||
height.
|
||
@end defun
|
||
|
||
@defun destroy-fringe-bitmap bitmap
|
||
This function destroy the fringe bitmap identified by @var{bitmap}.
|
||
If @var{bitmap} identifies a standard fringe bitmap, it actually
|
||
restores the standard definition of that bitmap, instead of
|
||
eliminating it entirely.
|
||
@end defun
|
||
|
||
@defun set-fringe-bitmap-face bitmap &optional face
|
||
This sets the face for the fringe bitmap @var{bitmap} to @var{face}.
|
||
If @var{face} is @code{nil}, it selects the @code{fringe} face. The
|
||
bitmap's face controls the color to draw it in.
|
||
|
||
@var{face} is merged with the @code{fringe} face, so normally
|
||
@var{face} should specify only the foreground color.
|
||
@end defun
|
||
|
||
@node Overlay Arrow
|
||
@subsection The Overlay Arrow
|
||
@c @cindex overlay arrow Duplicates variable names
|
||
|
||
The @dfn{overlay arrow} is useful for directing the user's attention
|
||
to a particular line in a buffer. For example, in the modes used for
|
||
interface to debuggers, the overlay arrow indicates the line of code
|
||
about to be executed. This feature has nothing to do with
|
||
@dfn{overlays} (@pxref{Overlays}).
|
||
|
||
@defvar overlay-arrow-string
|
||
This variable holds the string to display to call attention to a
|
||
particular line, or @code{nil} if the arrow feature is not in use.
|
||
On a graphical display the contents of the string are ignored; instead a
|
||
glyph is displayed in the fringe area to the left of the display area.
|
||
@end defvar
|
||
|
||
@defvar overlay-arrow-position
|
||
This variable holds a marker that indicates where to display the overlay
|
||
arrow. It should point at the beginning of a line. On a non-graphical
|
||
display the arrow text
|
||
appears at the beginning of that line, overlaying any text that would
|
||
otherwise appear. Since the arrow is usually short, and the line
|
||
usually begins with indentation, normally nothing significant is
|
||
overwritten.
|
||
|
||
The overlay-arrow string is displayed in any given buffer if the value
|
||
of @code{overlay-arrow-position} in that buffer points into that
|
||
buffer. Thus, it is possible to display multiple overlay arrow strings
|
||
by creating buffer-local bindings of @code{overlay-arrow-position}.
|
||
However, it is usually cleaner to use
|
||
@code{overlay-arrow-variable-list} to achieve this result.
|
||
@c !!! overlay-arrow-position: but the overlay string may remain in the display
|
||
@c of some other buffer until an update is required. This should be fixed
|
||
@c now. Is it?
|
||
@end defvar
|
||
|
||
You can do a similar job by creating an overlay with a
|
||
@code{before-string} property. @xref{Overlay Properties}.
|
||
|
||
You can define multiple overlay arrows via the variable
|
||
@code{overlay-arrow-variable-list}.
|
||
|
||
@defvar overlay-arrow-variable-list
|
||
This variable's value is a list of variables, each of which specifies
|
||
the position of an overlay arrow. The variable
|
||
@code{overlay-arrow-position} has its normal meaning because it is on
|
||
this list.
|
||
@end defvar
|
||
|
||
Each variable on this list can have properties
|
||
@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that
|
||
specify an overlay arrow string (for text terminals) or fringe bitmap
|
||
(for graphical terminals) to display at the corresponding overlay
|
||
arrow position. If either property is not set, the default
|
||
@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).
|
||
|
||
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 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
|
||
|
||
@defun frame-scroll-bar-width &optional frame
|
||
This function returns the width of vertical scroll bars of @var{frame}
|
||
in pixels.
|
||
@end defun
|
||
|
||
@defun frame-scroll-bar-height &optional frame
|
||
This function returns the height of horizontal scroll bars of
|
||
@var{frame} in pixels.
|
||
@end defun
|
||
|
||
You can override the frame specific settings for individual windows by
|
||
using the following function:
|
||
|
||
@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
|
||
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
|
||
|
||
@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{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}
|
||
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 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
|
||
@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 the customization of the
|
||
appearance of dividers:
|
||
|
||
@table @code
|
||
@item window-divider
|
||
When a divider is less than three pixels wide, it is drawn solidly with
|
||
the foreground of this face. For larger dividers this face is used for
|
||
the inner part only, excluding the first and last pixel.
|
||
|
||
@item window-divider-first-pixel
|
||
This is the face used for drawing the first pixel of a divider that is
|
||
at least three pixels wide. To obtain a solid appearance, set this to
|
||
the same value used for the @code{window-divider} face.
|
||
|
||
@item window-divider-last-pixel
|
||
This is the face used for drawing the last pixel of a divider that is at
|
||
least three pixels wide. To obtain a solid appearance, set this to the
|
||
same value used for the @code{window-divider} face.
|
||
@end table
|
||
|
||
You can get the sizes of the dividers of a specific window with the
|
||
following two functions.
|
||
|
||
@defun window-right-divider-width &optional window
|
||
Return the width (thickness) in pixels of @var{window}'s right divider.
|
||
@var{window} must be a live window and defaults to the selected one.
|
||
The return value is always zero for a rightmost window.
|
||
@end defun
|
||
|
||
@defun window-bottom-divider-width &optional window
|
||
Return the width (thickness) in pixels of @var{window}'s bottom divider.
|
||
@var{window} must be a live window and defaults to the selected one.
|
||
The return value is zero for the minibuffer window or a bottommost
|
||
window on a minibuffer-less frame.
|
||
@end defun
|
||
|
||
|
||
@node Display Property
|
||
@section The @code{display} Property
|
||
@cindex display specification
|
||
@kindex display @r{(text property)}
|
||
|
||
The @code{display} text property (or overlay property) is used to
|
||
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}
|
||
property value generally apply in parallel to the text they cover.
|
||
|
||
If several sources (overlays and/or a text property) specify values
|
||
for the @code{display} property, only one of the values takes effect,
|
||
following the rules of @code{get-char-property}. @xref{Examining
|
||
Properties}.
|
||
|
||
The rest of this section describes several kinds of
|
||
display specifications and what they mean.
|
||
|
||
@menu
|
||
* Replacing Specs:: Display specs that replace the text.
|
||
* Specified Space:: Displaying one space with a specified width.
|
||
* Pixel Specification:: Specifying space width or height in pixels.
|
||
* Other Display Specs:: Displaying an image; adjusting the height,
|
||
spacing, and other properties of text.
|
||
* Display Margins:: Displaying text or images to the side of the main text.
|
||
@end menu
|
||
|
||
@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
|
||
@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.
|
||
|
||
If a list of display specifications includes more than one replacing
|
||
display specification, the first overrides the rest. Replacing
|
||
display specifications make most other display specifications
|
||
irrelevant, since those don't apply to the replacement.
|
||
|
||
For replacing display specifications, @dfn{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. 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 ()
|
||
(dotimes (i 5)
|
||
(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
|
||
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
|
||
@cindex spaces, specified height or width
|
||
@cindex variable-width spaces
|
||
|
||
To display a space of specified width and/or height, use a display
|
||
specification of the form @code{(space . @var{props})}, where
|
||
@var{props} is a property list (a list of alternating properties and
|
||
values). You can put this property on one or more consecutive
|
||
characters; a space of the specified height and width is displayed in
|
||
place of @emph{all} of those characters. These are the properties you
|
||
can use in @var{props} to specify the weight of the space:
|
||
|
||
@table @code
|
||
@item :width @var{width}
|
||
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}).
|
||
|
||
@item :relative-width @var{factor}
|
||
Specifies that the width of the stretch should be computed from the
|
||
first character in the group of consecutive characters that have the
|
||
same @code{display} property. The space width is the pixel width of
|
||
that character, multiplied by @var{factor}. (On text-mode terminals,
|
||
the ``pixel width'' of a character is usually 1, but it could be more
|
||
for TABs and double-width CJK characters.)
|
||
|
||
@item :align-to @var{hpos}
|
||
Specifies that the space should be wide enough to reach @var{hpos}.
|
||
If @var{hpos} is a number, it is measured in units of the normal
|
||
character width. @var{hpos} can also be a @dfn{pixel width}
|
||
specification (@pxref{Pixel Specification}).
|
||
@end table
|
||
|
||
You should use one and only one of the above properties. You can
|
||
also specify the height of the space, with these properties:
|
||
|
||
@table @code
|
||
@item :height @var{height}
|
||
Specifies the height of the space.
|
||
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}).
|
||
|
||
@item :relative-height @var{factor}
|
||
Specifies the height of the space, multiplying the ordinary height
|
||
of the text having this display specification by @var{factor}.
|
||
|
||
@item :ascent @var{ascent}
|
||
If the value of @var{ascent} is a non-negative number no greater than
|
||
100, it specifies that @var{ascent} percent of the height of the space
|
||
should be considered as the ascent of the space---that is, the part
|
||
above the baseline. The ascent may also be specified in pixel units
|
||
with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}).
|
||
|
||
@end table
|
||
|
||
Don't use both @code{:height} and @code{:relative-height} together.
|
||
|
||
The @code{:width} and @code{:align-to} properties are supported on
|
||
non-graphic terminals, but the other space properties in this section
|
||
are not.
|
||
|
||
Note that space properties are treated as paragraph separators for
|
||
the purposes of reordering bidirectional text for display.
|
||
@xref{Bidirectional Display}, for the details.
|
||
|
||
@node Pixel Specification
|
||
@subsection Pixel Specification for Spaces
|
||
@cindex spaces, pixel specification
|
||
|
||
The value of the @code{:width}, @code{:align-to}, @code{:height},
|
||
and @code{:ascent} properties can be a special kind of expression that
|
||
is evaluated during redisplay. The result of the evaluation is used
|
||
as an absolute number of pixels.
|
||
|
||
The following expressions are supported:
|
||
|
||
@smallexample
|
||
@group
|
||
@var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
|
||
@var{num} ::= @var{integer} | @var{float} | @var{symbol}
|
||
@var{unit} ::= in | mm | cm | width | height
|
||
@end group
|
||
@group
|
||
@var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
|
||
| scroll-bar | text
|
||
@var{pos} ::= left | center | right
|
||
@var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...)
|
||
@var{op} ::= + | -
|
||
@end group
|
||
@end smallexample
|
||
|
||
The form @var{num} specifies a fraction of the default frame font
|
||
height or width. The form @code{(@var{num})} specifies an absolute
|
||
number of pixels. If @var{num} is a symbol, @var{symbol}, its
|
||
buffer-local variable binding is used.
|
||
|
||
The @code{in}, @code{mm}, and @code{cm} units specify the number of
|
||
pixels per inch, millimeter, and centimeter, respectively. The
|
||
@code{width} and @code{height} units correspond to the default width
|
||
and height of the current face. An image specification @code{image}
|
||
corresponds to the width or height of the image.
|
||
|
||
The elements @code{left-fringe}, @code{right-fringe},
|
||
@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
|
||
@code{text} specify to the width of the corresponding area of the
|
||
window.
|
||
|
||
The @code{left}, @code{center}, and @code{right} positions can be
|
||
used with @code{:align-to} to specify a position relative to the left
|
||
edge, center, or right edge of the text area.
|
||
|
||
Any of the above window elements (except @code{text}) can also be
|
||
used with @code{:align-to} to specify that the position is relative to
|
||
the left edge of the given area. Once the base offset for a relative
|
||
position has been set (by the first occurrence of one of these
|
||
symbols), further occurrences of these symbols are interpreted as the
|
||
width of the specified area. For example, to align to the center of
|
||
the left-margin, use
|
||
|
||
@example
|
||
:align-to (+ left-margin (0.5 . left-margin))
|
||
@end example
|
||
|
||
If no specific base offset is set for alignment, it is always relative
|
||
to the left edge of the text area. For example, @samp{:align-to 0} in a
|
||
header-line aligns with the first text column in the text area.
|
||
|
||
A value of the form @code{(@var{num} . @var{expr})} stands for the
|
||
product of the values of @var{num} and @var{expr}. For example,
|
||
@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
|
||
@var{image})} specifies half the width (or height) of the specified
|
||
image.
|
||
|
||
The form @code{(+ @var{expr} ...)} adds up the value of the
|
||
expressions. The form @code{(- @var{expr} ...)} negates or subtracts
|
||
the value of the expressions.
|
||
|
||
@node Other Display Specs
|
||
@subsection Other Display Specifications
|
||
|
||
Here are the other sorts of display specifications that you can use
|
||
in the @code{display} text property.
|
||
|
||
@table @code
|
||
@item @var{string}
|
||
Display @var{string} instead of the text that has this property.
|
||
|
||
Recursive display specifications are not supported---@var{string}'s
|
||
@code{display} properties, if any, are not used.
|
||
|
||
@item (image . @var{image-props})
|
||
This kind of display specification is an image descriptor (@pxref{Images}).
|
||
When used as a display specification, it means to display the image
|
||
instead of the text that has the display specification.
|
||
|
||
@item (slice @var{x} @var{y} @var{width} @var{height})
|
||
This specification together with @code{image} specifies a @dfn{slice}
|
||
(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. 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.
|
||
|
||
@item ((margin nil) @var{string})
|
||
A display specification of this form means to display @var{string}
|
||
instead of the text that has the display specification, at the same
|
||
position as that text. It is equivalent to using just @var{string},
|
||
but it is done as a special case of marginal display (@pxref{Display
|
||
Margins}).
|
||
|
||
@item (left-fringe @var{bitmap} @r{[}@var{face}@r{]})
|
||
@itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]})
|
||
This display specification on any character of a line of text causes
|
||
the specified @var{bitmap} be displayed in the left or right fringes
|
||
for that line, instead of the characters that have the display
|
||
specification. The optional @var{face} specifies the colors to be
|
||
used for the bitmap. @xref{Fringe Bitmaps}, for the details.
|
||
|
||
@item (space-width @var{factor})
|
||
This display specification affects all the space characters within the
|
||
text that has the specification. It displays all of these spaces
|
||
@var{factor} times as wide as normal. The element @var{factor} should
|
||
be an integer or float. Characters other than spaces are not affected
|
||
at all; in particular, this has no effect on tab characters.
|
||
|
||
@item (height @var{height})
|
||
This display specification makes the text taller or shorter.
|
||
Here are the possibilities for @var{height}:
|
||
|
||
@table @asis
|
||
@item @code{(+ @var{n})}
|
||
@c FIXME: Add an index for "step"? --xfq
|
||
This means to use a font that is @var{n} steps larger. A @dfn{step} is
|
||
defined by the set of available fonts---specifically, those that match
|
||
what was otherwise specified for this text, in all attributes except
|
||
height. Each size for which a suitable font is available counts as
|
||
another step. @var{n} should be an integer.
|
||
|
||
@item @code{(- @var{n})}
|
||
This means to use a font that is @var{n} steps smaller.
|
||
|
||
@item a number, @var{factor}
|
||
A number, @var{factor}, means to use a font that is @var{factor} times
|
||
as tall as the default font.
|
||
|
||
@item a symbol, @var{function}
|
||
A symbol is a function to compute the height. It is called with the
|
||
current height as argument, and should return the new height to use.
|
||
|
||
@item anything else, @var{form}
|
||
If the @var{height} value doesn't fit the previous possibilities, it is
|
||
a form. Emacs evaluates it to get the new height, with the symbol
|
||
@code{height} bound to the current specified font height.
|
||
@end table
|
||
|
||
@item (raise @var{factor})
|
||
This kind of display specification raises or lowers the text
|
||
it applies to, relative to the baseline of the line.
|
||
|
||
@var{factor} must be a number, which is interpreted as a multiple of the
|
||
height of the affected text. If it is positive, that means to display
|
||
the characters raised. If it is negative, that means to display them
|
||
lower down.
|
||
|
||
If the text also has a @code{height} display specification, that does
|
||
not affect the amount of raising or lowering, which is based on the
|
||
faces used for the text.
|
||
@end table
|
||
|
||
@c We put all the '@code{(when ...)}' on one line to encourage
|
||
@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot
|
||
@c was at eol; the info file ended up w/ two spaces rendered after it.
|
||
You can make any display specification conditional. To do that,
|
||
package it in another list of the form
|
||
@code{(when @var{condition} . @var{spec})}.
|
||
Then the specification @var{spec} applies only when
|
||
@var{condition} evaluates to a non-@code{nil} value. During the
|
||
evaluation, @code{object} is bound to the string or buffer having the
|
||
conditional @code{display} property. @code{position} and
|
||
@code{buffer-position} are bound to the position within @code{object}
|
||
and the buffer position where the @code{display} property was found,
|
||
respectively. Both positions can be different when @code{object} is a
|
||
string.
|
||
|
||
@node Display Margins
|
||
@subsection Displaying in the Margins
|
||
@cindex display margins
|
||
@cindex margins, display
|
||
|
||
A buffer can have blank areas called @dfn{display margins} on the
|
||
left and on the right. Ordinary text never appears in these areas,
|
||
but you can put things into the display margins using the
|
||
@code{display} property. There is currently no way to make text or
|
||
images in the margin mouse-sensitive.
|
||
|
||
The way to display something in the margins is to specify it in a
|
||
margin display specification in the @code{display} property of some
|
||
text. This is a replacing display specification, meaning that the
|
||
text you put it on does not get displayed; the margin display appears,
|
||
but that text does not.
|
||
|
||
A margin display specification looks like @code{((margin
|
||
right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
|
||
Here, @var{spec} is another display specification that says what to
|
||
display in the margin. Typically it is a string of text to display,
|
||
or an image descriptor.
|
||
|
||
To display something in the margin @emph{in association with}
|
||
certain buffer text, without altering or preventing the display of
|
||
that text, put a @code{before-string} property on the text and put the
|
||
margin display specification on the contents of the before-string.
|
||
|
||
Before the display margins can display anything, you must give
|
||
them a nonzero width. The usual way to do that is to set these
|
||
variables:
|
||
|
||
@defvar left-margin-width
|
||
This variable specifies the width of the left margin, in character
|
||
cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers.
|
||
A value of @code{nil} means no left marginal area.
|
||
@end defvar
|
||
|
||
@defvar right-margin-width
|
||
This variable specifies the width of the right margin, in character
|
||
cell units. It is buffer-local in all buffers. A value of @code{nil}
|
||
means no right marginal area.
|
||
@end defvar
|
||
|
||
Setting these variables does not immediately affect the window. These
|
||
variables are checked when a new buffer is displayed in the window.
|
||
Thus, you can make changes take effect by calling
|
||
@code{set-window-buffer}.
|
||
|
||
You can also set the margin widths immediately.
|
||
|
||
@defun set-window-margins window left &optional right
|
||
This function specifies the margin widths for window @var{window}, in
|
||
character cell units. The argument @var{left} controls the left
|
||
margin, and @var{right} controls the right margin (default @code{0}).
|
||
@end defun
|
||
|
||
@defun window-margins &optional window
|
||
This function returns the width of the left and right margins of
|
||
@var{window} as a cons cell of the form @w{@code{(@var{left}
|
||
. @var{right})}}. If one of the two marginal areas does not exist,
|
||
its width is returned as @code{nil}; if neither of the two margins exist,
|
||
the function returns @code{(nil)}. If @var{window} is @code{nil}, the
|
||
selected window is used.
|
||
@end defun
|
||
|
||
@node Images
|
||
@section Images
|
||
@cindex images in buffers
|
||
|
||
To display an image in an Emacs buffer, you must first create an image
|
||
descriptor, then use it as a display specifier in the @code{display}
|
||
property of text that is displayed (@pxref{Display Property}).
|
||
|
||
Emacs is usually able to display images when it is run on a
|
||
graphical terminal. Images cannot be displayed in a text terminal, on
|
||
certain graphical terminals that lack the support for this, or if
|
||
Emacs is compiled without image support. You can use the function
|
||
@code{display-images-p} to determine if images can in principle be
|
||
displayed (@pxref{Display Feature Testing}).
|
||
|
||
@menu
|
||
* Image Formats:: Supported image formats.
|
||
* Image Descriptors:: How to specify an image for use in @code{:display}.
|
||
* XBM Images:: Special features for XBM format.
|
||
* XPM Images:: Special features for XPM format.
|
||
* ImageMagick Images:: Special features available through ImageMagick.
|
||
* SVG Images:: Creating and manipulating SVG images.
|
||
* Other Image Types:: Various other formats are supported.
|
||
* Defining Images:: Convenient ways to define an image for later use.
|
||
* Showing Images:: Convenient ways to display an image once it is defined.
|
||
* Multi-Frame Images:: Some images contain more than one frame.
|
||
* Image Cache:: Internal mechanisms of image display.
|
||
@end menu
|
||
|
||
@node Image Formats
|
||
@subsection Image Formats
|
||
@cindex image formats
|
||
@cindex image types
|
||
|
||
Emacs can display a number of different image formats. Some of
|
||
these image formats are supported only if particular support libraries
|
||
are installed. On some platforms, Emacs can load support libraries on
|
||
demand; if so, the variable @code{dynamic-library-alist} can be used
|
||
to modify the set of known names for these dynamic libraries.
|
||
@xref{Dynamic Libraries}.
|
||
|
||
Supported image formats (and the required support libraries) include
|
||
PBM and XBM (which do not depend on support libraries and are always
|
||
available), XPM (@code{libXpm}), GIF (@code{libgif} or
|
||
@code{libungif}), JPEG (@code{libjpeg}), TIFF
|
||
(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
|
||
|
||
Each of these image formats is associated with an @dfn{image type
|
||
symbol}. The symbols for the above formats are, respectively,
|
||
@code{pbm}, @code{xbm}, @code{xpm}, @code{gif},
|
||
@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}.
|
||
|
||
Furthermore, if you build Emacs with ImageMagick
|
||
(@code{libMagickWand}) support, Emacs can display any image format
|
||
that ImageMagick can. @xref{ImageMagick Images}. All images
|
||
displayed via ImageMagick have type symbol @code{imagemagick}.
|
||
|
||
@defvar image-types
|
||
This variable contains a list of type symbols for image formats which
|
||
are potentially supported in the current configuration.
|
||
|
||
``Potentially'' means that Emacs knows about the image types, not
|
||
necessarily that they can be used (for example, they could depend on
|
||
unavailable dynamic libraries). To know which image types are really
|
||
available, use @code{image-type-available-p}.
|
||
@end defvar
|
||
|
||
@defun image-type-available-p type
|
||
This function returns non-@code{nil} if images of type @var{type} can
|
||
be loaded and displayed. @var{type} must be an image type symbol.
|
||
|
||
For image types whose support libraries are statically linked, this
|
||
function always returns @code{t}. For image types whose support
|
||
libraries are dynamically loaded, it returns @code{t} if the library
|
||
could be loaded and @code{nil} otherwise.
|
||
@end defun
|
||
|
||
@node Image Descriptors
|
||
@subsection Image Descriptors
|
||
@cindex image descriptor
|
||
|
||
An @dfn{image descriptor} is a list which specifies the underlying
|
||
data for an image, and how to display it. It is typically used as the
|
||
value of a @code{display} overlay or text property (@pxref{Other
|
||
Display Specs}); but @xref{Showing Images}, for convenient helper
|
||
functions to insert images into buffers.
|
||
|
||
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}} that
|
||
specifies the image type.
|
||
|
||
The following is a list of properties that are meaningful for all
|
||
image types (there are also properties which are meaningful only for
|
||
certain image types, as documented in the following subsections):
|
||
|
||
@table @code
|
||
@item :type @var{type}
|
||
The image type.
|
||
@ifnottex
|
||
@xref{Image Formats}.
|
||
@end ifnottex
|
||
Every image descriptor must include this property.
|
||
|
||
@item :file @var{file}
|
||
This says to load the image from file @var{file}. If @var{file} is
|
||
not an absolute file name, it is expanded in @code{data-directory}.
|
||
|
||
@item :data @var{data}
|
||
This specifies the raw image data. Each image descriptor must have
|
||
either @code{:data} or @code{:file}, but not both.
|
||
|
||
For most image types, the value of a @code{:data} property should be a
|
||
string containing the image data. Some image types do not support
|
||
@code{:data}; for some others, @code{:data} alone is not enough, so
|
||
you need to use other image properties along with @code{:data}. See
|
||
the following subsections for details.
|
||
|
||
@item :margin @var{margin}
|
||
This specifies how many pixels to add as an extra margin around the
|
||
image. The value, @var{margin}, must be a non-negative number, or a
|
||
pair @code{(@var{x} . @var{y})} of such numbers. If it is a pair,
|
||
@var{x} specifies how many pixels to add horizontally, and @var{y}
|
||
specifies how many pixels to add vertically. If @code{:margin} is not
|
||
specified, the default is zero.
|
||
|
||
@item :ascent @var{ascent}
|
||
This specifies the amount of the image's height to use for its
|
||
ascent---that is, the part above the baseline. The value,
|
||
@var{ascent}, must be a number in the range 0 to 100, or the symbol
|
||
@code{center}.
|
||
|
||
If @var{ascent} is a number, that percentage of the image's height is
|
||
used for its ascent.
|
||
|
||
If @var{ascent} is @code{center}, the image is vertically centered
|
||
around a centerline which would be the vertical centerline of text drawn
|
||
at the position of the image, in the manner specified by the text
|
||
properties and overlays that apply to the image.
|
||
|
||
If this property is omitted, it defaults to 50.
|
||
|
||
@item :relief @var{relief}
|
||
This adds a shadow rectangle around the image. The value,
|
||
@var{relief}, specifies the width of the shadow lines, in pixels. If
|
||
@var{relief} is negative, shadows are drawn so that the image appears
|
||
as a pressed button; otherwise, it appears as an unpressed button.
|
||
|
||
@item :conversion @var{algorithm}
|
||
This specifies a conversion algorithm that should be applied to the
|
||
image before it is displayed; the value, @var{algorithm}, specifies
|
||
which algorithm.
|
||
|
||
@table @code
|
||
@item laplace
|
||
@itemx emboss
|
||
Specifies the Laplace edge detection algorithm, which blurs out small
|
||
differences in color while highlighting larger differences. People
|
||
sometimes consider this useful for displaying the image for a
|
||
disabled button.
|
||
|
||
@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust})
|
||
@cindex edge detection, images
|
||
Specifies a general edge-detection algorithm. @var{matrix} must be
|
||
either a nine-element list or a nine-element vector of numbers. A pixel
|
||
at position @math{x/y} in the transformed image is computed from
|
||
original pixels around that position. @var{matrix} specifies, for each
|
||
pixel in the neighborhood of @math{x/y}, a factor with which that pixel
|
||
will influence the transformed pixel; element @math{0} specifies the
|
||
factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for
|
||
the pixel at @math{x/y-1} etc., as shown below:
|
||
@iftex
|
||
@tex
|
||
$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr
|
||
x-1/y & x/y & x+1/y \cr
|
||
x-1/y+1& x/y+1 & x+1/y+1 \cr}$$
|
||
@end tex
|
||
@end iftex
|
||
@ifnottex
|
||
@display
|
||
(x-1/y-1 x/y-1 x+1/y-1
|
||
x-1/y x/y x+1/y
|
||
x-1/y+1 x/y+1 x+1/y+1)
|
||
@end display
|
||
@end ifnottex
|
||
|
||
The resulting pixel is computed from the color intensity of the color
|
||
resulting from summing up the RGB values of surrounding pixels,
|
||
multiplied by the specified factors, and dividing that sum by the sum
|
||
of the factors' absolute values.
|
||
|
||
Laplace edge-detection currently uses a matrix of
|
||
@iftex
|
||
@tex
|
||
$$\pmatrix{1 & 0 & 0 \cr
|
||
0& 0 & 0 \cr
|
||
0 & 0 & -1 \cr}$$
|
||
@end tex
|
||
@end iftex
|
||
@ifnottex
|
||
@display
|
||
(1 0 0
|
||
0 0 0
|
||
0 0 -1)
|
||
@end display
|
||
@end ifnottex
|
||
|
||
Emboss edge-detection uses a matrix of
|
||
@iftex
|
||
@tex
|
||
$$\pmatrix{ 2 & -1 & 0 \cr
|
||
-1 & 0 & 1 \cr
|
||
0 & 1 & -2 \cr}$$
|
||
@end tex
|
||
@end iftex
|
||
@ifnottex
|
||
@display
|
||
( 2 -1 0
|
||
-1 0 1
|
||
0 1 -2)
|
||
@end display
|
||
@end ifnottex
|
||
|
||
@item disabled
|
||
Specifies transforming the image so that it looks disabled.
|
||
@end table
|
||
|
||
@item :mask @var{mask}
|
||
If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build
|
||
a clipping mask for the image, so that the background of a frame is
|
||
visible behind the image. If @var{bg} is not specified, or if @var{bg}
|
||
is @code{t}, determine the background color of the image by looking at
|
||
the four corners of the image, assuming the most frequently occurring
|
||
color from the corners is the background color of the image. Otherwise,
|
||
@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})}
|
||
specifying the color to assume for the background of the image.
|
||
|
||
If @var{mask} is @code{nil}, remove a mask from the image, if it has
|
||
one. Images in some formats include a mask which can be removed by
|
||
specifying @code{:mask nil}.
|
||
|
||
@item :pointer @var{shape}
|
||
This specifies the pointer shape when the mouse pointer is over this
|
||
image. @xref{Pointer Shape}, for available pointer shapes.
|
||
|
||
@item :map @var{map}
|
||
@cindex image maps
|
||
This associates an image map of @dfn{hot spots} with this image.
|
||
|
||
An image map is an alist where each element has the format
|
||
@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified
|
||
as either a rectangle, a circle, or a polygon.
|
||
|
||
A rectangle is a cons
|
||
@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))}
|
||
which specifies the pixel coordinates of the upper left and bottom right
|
||
corners of the rectangle area.
|
||
|
||
A circle is a cons
|
||
@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))}
|
||
which specifies the center and the radius of the circle; @var{r} may
|
||
be a float or integer.
|
||
|
||
A polygon is a cons
|
||
@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])}
|
||
where each pair in the vector describes one corner in the polygon.
|
||
|
||
When the mouse pointer lies on a hot-spot area of an image, the
|
||
@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo}
|
||
property, that defines a tool-tip for the hot-spot, and if it contains
|
||
a @code{pointer} property, that defines the shape of the mouse cursor when
|
||
it is on the hot-spot.
|
||
@xref{Pointer Shape}, for available pointer shapes.
|
||
|
||
When you click the mouse when the mouse pointer is over a hot-spot, an
|
||
event is composed by combining the @var{id} of the hot-spot with the
|
||
mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's
|
||
@var{id} is @code{area4}.
|
||
@end table
|
||
|
||
@defun image-mask-p spec &optional frame
|
||
This function returns @code{t} if image @var{spec} has a mask bitmap.
|
||
@var{frame} is the frame on which the image will be displayed.
|
||
@var{frame} @code{nil} or omitted means to use the selected frame
|
||
(@pxref{Input Focus}).
|
||
@end defun
|
||
|
||
@node XBM Images
|
||
@subsection XBM Images
|
||
@cindex XBM
|
||
|
||
To use XBM format, specify @code{xbm} as the image type. This image
|
||
format doesn't require an external library, so images of this type are
|
||
always supported.
|
||
|
||
Additional image properties supported for the @code{xbm} image type are:
|
||
|
||
@table @code
|
||
@item :foreground @var{foreground}
|
||
The value, @var{foreground}, should be a string specifying the image
|
||
foreground color, or @code{nil} for the default color. This color is
|
||
used for each pixel in the XBM that is 1. The default is the frame's
|
||
foreground color.
|
||
|
||
@item :background @var{background}
|
||
The value, @var{background}, should be a string specifying the image
|
||
background color, or @code{nil} for the default color. This color is
|
||
used for each pixel in the XBM that is 0. The default is the frame's
|
||
background color.
|
||
@end table
|
||
|
||
If you specify an XBM image using data within Emacs instead of an
|
||
external file, use the following three properties:
|
||
|
||
@table @code
|
||
@item :data @var{data}
|
||
The value, @var{data}, specifies the contents of the image.
|
||
There are three formats you can use for @var{data}:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
A vector of strings or bool-vectors, each specifying one line of the
|
||
image. Do specify @code{:height} and @code{:width}.
|
||
|
||
@item
|
||
A string containing the same byte sequence as an XBM file would contain.
|
||
You must not specify @code{:height} and @code{:width} in this case,
|
||
because omitting them is what indicates the data has the format of an
|
||
XBM file. The file contents specify the height and width of the image.
|
||
|
||
@item
|
||
A string or a bool-vector containing the bits of the image (plus perhaps
|
||
some extra bits at the end that will not be used). It should contain at
|
||
least @var{width} * @code{height} bits. In this case, you must specify
|
||
@code{:height} and @code{:width}, both to indicate that the string
|
||
contains just the bits rather than a whole XBM file, and to specify the
|
||
size of the image.
|
||
@end itemize
|
||
|
||
@item :width @var{width}
|
||
The value, @var{width}, specifies the width of the image, in pixels.
|
||
|
||
@item :height @var{height}
|
||
The value, @var{height}, specifies the height of the image, in pixels.
|
||
@end table
|
||
|
||
@node XPM Images
|
||
@subsection XPM Images
|
||
@cindex XPM
|
||
|
||
To use XPM format, specify @code{xpm} as the image type. The
|
||
additional image property @code{:color-symbols} is also meaningful with
|
||
the @code{xpm} image type:
|
||
|
||
@table @code
|
||
@item :color-symbols @var{symbols}
|
||
The value, @var{symbols}, should be an alist whose elements have the
|
||
form @code{(@var{name} . @var{color})}. In each element, @var{name} is
|
||
the name of a color as it appears in the image file, and @var{color}
|
||
specifies the actual color to use for displaying that name.
|
||
@end table
|
||
|
||
@node ImageMagick Images
|
||
@subsection ImageMagick Images
|
||
@cindex ImageMagick images
|
||
@cindex images, support for more formats
|
||
|
||
If your Emacs build has ImageMagick support, you can use the
|
||
ImageMagick library to load many image formats (@pxref{File
|
||
Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol
|
||
for images loaded via ImageMagick is @code{imagemagick}, regardless of
|
||
the actual underlying image format.
|
||
|
||
To check for ImageMagick support, use the following:
|
||
|
||
@lisp
|
||
(image-type-available-p 'imagemagick)
|
||
@end lisp
|
||
|
||
@defun imagemagick-types
|
||
This function returns a list of image file extensions supported by the
|
||
current ImageMagick installation. Each list element is a symbol
|
||
representing an internal ImageMagick name for an image type, such as
|
||
@code{BMP} for @file{.bmp} images.
|
||
@end defun
|
||
|
||
@defopt imagemagick-enabled-types
|
||
The value of this variable is a list of ImageMagick image types which
|
||
Emacs may attempt to render using ImageMagick. Each list element
|
||
should be one of the symbols in the list returned by
|
||
@code{imagemagick-types}, or an equivalent string. Alternatively, a
|
||
value of @code{t} enables ImageMagick for all possible image types.
|
||
Regardless of the value of this variable,
|
||
@code{imagemagick-types-inhibit} (see below) takes precedence.
|
||
@end defopt
|
||
|
||
@defopt imagemagick-types-inhibit
|
||
The value of this variable lists the ImageMagick image types which
|
||
should never be rendered using ImageMagick, regardless of the value of
|
||
@code{imagemagick-enabled-types}. A value of @code{t} disables
|
||
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:
|
||
|
||
@table @code
|
||
@item :background @var{background}
|
||
@var{background}, if non-@code{nil}, should be a string specifying a
|
||
color, which is used as the image's background color if the image
|
||
supports transparency. If the value is @code{nil}, it defaults to the
|
||
frame's background color.
|
||
|
||
@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 @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},
|
||
and if @code{:height} is set it will have precedence over
|
||
@code{max-height}, but you can otherwise mix these keywords as you
|
||
wish. @code{:max-width} and @code{:max-height} will always preserve
|
||
the aspect ratio.
|
||
|
||
@item :scale @var{scale}
|
||
This should be a number, where values higher than 1 means to increase
|
||
the size, and lower means to decrease the size. For instance, a value
|
||
of 0.25 will make the image a quarter size of what it originally was.
|
||
If the scaling makes the image larger than specified by
|
||
@code{:max-width} or @code{:max-height}, the resulting size will not
|
||
exceed those two values. If both @code{:scale} and
|
||
@code{:height}/@code{:width} are specified, the height/width will be
|
||
adjusted by the specified scaling factor.
|
||
|
||
@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 @var{angle}
|
||
Specifies a rotation angle in degrees.
|
||
|
||
@item :index @var{frame}
|
||
@c Doesn't work: http://debbugs.gnu.org/7978
|
||
@xref{Multi-Frame Images}.
|
||
@end table
|
||
|
||
@node SVG Images
|
||
@subsection SVG Images
|
||
@cindex SVG images
|
||
|
||
SVG (Scalable Vector Graphics) is an XML format for specifying images.
|
||
If your Emacs build has with SVG support, you can create and manipulate
|
||
these images with the following commands.
|
||
|
||
@defun svg-create width height &rest args
|
||
Create a new, empty SVG image with the specified dimensions.
|
||
@var{args} is an argument plist with you can specify following:
|
||
|
||
@table @code
|
||
@item :stroke-width
|
||
The default width (in pixels) of any lines created.
|
||
|
||
@item :stroke
|
||
The default stroke color on any lines created.
|
||
@end table
|
||
|
||
This function returns an SVG structure, and all the following commands
|
||
work on that structure.
|
||
@end defun
|
||
|
||
@defun svg-gradient svg id type stops
|
||
Create a gradient in @var{svg} with identifier @var{id}. @var{type}
|
||
specifies the gradient type, and can be either @code{linear} or
|
||
@code{radial}. @var{stops} is a list of percentage/color pairs.
|
||
|
||
The following will create a linear gradient that goes from red at the
|
||
start, to green 25% of the way, to blue at the end:
|
||
|
||
@lisp
|
||
(svg-gradient svg "gradient1" 'linear
|
||
'((0 . "red") (25 . "green") (100 . "blue")))
|
||
@end lisp
|
||
|
||
The gradient created (and inserted into the SVG object) can later be
|
||
used by all functions that create shapes.
|
||
@end defun
|
||
|
||
All the following functions take an optional list of keyword
|
||
parameters that alter the various attributes from their default
|
||
values. Valid attributes include:
|
||
|
||
@table @code
|
||
@item :stroke-width
|
||
The width (in pixels) of lines drawn, and outlines around solid
|
||
shapes.
|
||
|
||
@item :stroke-color
|
||
The color of lines drawn, and outlines around solid shapes.
|
||
|
||
@item :fill-color
|
||
The color used for solid shapes.
|
||
|
||
@item :id
|
||
The identified of the shape.
|
||
|
||
@item :gradient
|
||
If given, this should be the identifier of a previously defined
|
||
gradient object.
|
||
@end table
|
||
|
||
@defun svg-rectangle svg x y width height &rest args
|
||
Add a rectangle to @var{svg} where the upper left corner is at
|
||
position @var{x}/@var{y} and is of size @var{width}/@var{height}.
|
||
|
||
@lisp
|
||
(svg-rectangle svg 100 100 500 500 :gradient "gradient1")
|
||
@end lisp
|
||
@end defun
|
||
|
||
@defun svg-circle svg x y radius &rest args
|
||
Add a circle to @var{svg} where the center is at @var{x}/@var{y}
|
||
and the radius is @var{radius}.
|
||
@end defun
|
||
|
||
@defun svg-ellipse svg x y x-radius y-radius &rest args
|
||
Add a circle to @var{svg} where the center is at @var{x}/@var{y} and
|
||
the horizontal radius is @var{x-radius} and the vertical radius is
|
||
@var{y-radius}.
|
||
@end defun
|
||
|
||
@defun svg-line svg x1 y1 x2 y2 &rest args
|
||
Add a line to @var{svg} that starts at @var{x1}/@var{y1} and extends
|
||
to @var{x2}/@var{y2}.
|
||
@end defun
|
||
|
||
@defun svg-polyline svg points &rest args
|
||
Add a multiple segment line to @var{svg} that goes through
|
||
@var{points}, which is a list of X/Y position pairs.
|
||
|
||
@lisp
|
||
(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100))
|
||
:stroke-color "green")
|
||
@end lisp
|
||
@end defun
|
||
|
||
@defun svg-polygon svg points &rest args
|
||
Add a polygon to @var{svg} where @var{points} is a list of X/Y pairs
|
||
that describe the outer circumference of the polygon.
|
||
|
||
@lisp
|
||
(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90))
|
||
:stroke-color "blue" :fill-color "red"")
|
||
@end lisp
|
||
@end defun
|
||
|
||
@defun svg-text svg text &rest args
|
||
Add a text to @var{svg}.
|
||
|
||
@lisp
|
||
(svg-text
|
||
svg "This is a text"
|
||
:font-size "40"
|
||
:font-weight "bold"
|
||
:stroke "black"
|
||
:fill "white"
|
||
:font-family "impact"
|
||
:letter-spacing "4pt"
|
||
:x 300
|
||
:y 400
|
||
:stroke-width 1)
|
||
@end lisp
|
||
@end defun
|
||
|
||
@defun svg-embed svg image image-type datap &rest args
|
||
Add an embedded (raster) image to @var{svg}. If @var{datap} is
|
||
@code{nil}, @var{IMAGE} should be a file name; if not, it should be a
|
||
binary string containing the image data. @var{image-type} should be a
|
||
@acronym{MIME} image type, for instance @samp{"image/jpeg"}.
|
||
|
||
@lisp
|
||
(svg-embed svg "~/rms.jpg" "image/jpeg" nil
|
||
:width "100px" :height "100px"
|
||
:x "50px" :y "75px")
|
||
@end lisp
|
||
@end defun
|
||
|
||
@defun svg-remove svg id
|
||
Remove the element with identifier @code{id} from the @code{svg}.
|
||
@end defun
|
||
|
||
Finally, the @code{svg-image} takes an SVG object as its parameter and
|
||
returns an image object suitable for use in functions like
|
||
@code{insert-image}. Here's a complete example that creates and
|
||
inserts an image with a circle:
|
||
|
||
@lisp
|
||
(let ((svg (svg-create 400 400 :stroke-width 10)))
|
||
(svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue")))
|
||
(svg-circle svg 200 200 100 :gradient "gradient1" :stroke-color "green")
|
||
(insert-image (svg-image svg)))
|
||
@end lisp
|
||
|
||
|
||
@node Other Image Types
|
||
@subsection Other Image Types
|
||
@cindex PBM
|
||
|
||
For PBM images, specify image type @code{pbm}. Color, gray-scale and
|
||
monochromatic images are supported. For mono PBM images, two additional
|
||
image properties are supported.
|
||
|
||
@table @code
|
||
@item :foreground @var{foreground}
|
||
The value, @var{foreground}, should be a string specifying the image
|
||
foreground color, or @code{nil} for the default color. This color is
|
||
used for each pixel in the PBM that is 1. The default is the frame's
|
||
foreground color.
|
||
|
||
@item :background @var{background}
|
||
The value, @var{background}, should be a string specifying the image
|
||
background color, or @code{nil} for the default color. This color is
|
||
used for each pixel in the PBM that is 0. The default is the frame's
|
||
background color.
|
||
@end table
|
||
|
||
@noindent
|
||
The remaining image types that Emacs can support are:
|
||
|
||
@table @asis
|
||
@item GIF
|
||
Image type @code{gif}.
|
||
Supports the @code{:index} property. @xref{Multi-Frame Images}.
|
||
|
||
@item JPEG
|
||
Image type @code{jpeg}.
|
||
|
||
@item PNG
|
||
Image type @code{png}.
|
||
|
||
@item TIFF
|
||
Image type @code{tiff}.
|
||
Supports the @code{:index} property. @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.
|
||
|
||
@defun create-image file-or-data &optional type data-p &rest props
|
||
This function creates and returns an image descriptor which uses the
|
||
data in @var{file-or-data}. @var{file-or-data} can be a file name or
|
||
a string containing the image data; @var{data-p} should be @code{nil}
|
||
for the former case, non-@code{nil} for the latter case.
|
||
|
||
The optional argument @var{type} is a symbol specifying the image type.
|
||
If @var{type} is omitted or @code{nil}, @code{create-image} tries to
|
||
determine the image type from the file's first few bytes, or else
|
||
from the file's name.
|
||
|
||
The remaining arguments, @var{props}, specify additional image
|
||
properties---for example,
|
||
|
||
@c ':heuristic-mask' is not documented?
|
||
@example
|
||
(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
|
||
@end example
|
||
|
||
The function returns @code{nil} if images of this type are not
|
||
supported. Otherwise it returns an image descriptor.
|
||
@end defun
|
||
|
||
@defmac defimage symbol specs &optional doc
|
||
This macro defines @var{symbol} as an image name. The arguments
|
||
@var{specs} is a list which specifies how to display the image.
|
||
The third argument, @var{doc}, is an optional documentation string.
|
||
|
||
Each argument in @var{specs} has the form of a property list, and each
|
||
one should specify at least the @code{:type} property and either the
|
||
@code{:file} or the @code{:data} property. The value of @code{:type}
|
||
should be a symbol specifying the image type, the value of
|
||
@code{:file} is the file to load the image from, and the value of
|
||
@code{:data} is a string containing the actual image data. Here is an
|
||
example:
|
||
|
||
@example
|
||
(defimage test-image
|
||
((:type xpm :file "~/test1.xpm")
|
||
(:type xbm :file "~/test1.xbm")))
|
||
@end example
|
||
|
||
@code{defimage} tests each argument, one by one, to see if it is
|
||
usable---that is, if the type is supported and the file exists. The
|
||
first usable argument is used to make an image descriptor which is
|
||
stored in @var{symbol}.
|
||
|
||
If none of the alternatives will work, then @var{symbol} is defined
|
||
as @code{nil}.
|
||
@end defmac
|
||
|
||
@defun image-property image property
|
||
Return the value of @var{property} in @var{image}. Properties can be
|
||
set by using @code{setf}. Setting a property to @code{nil} will
|
||
remove the property from the image.
|
||
@end defun
|
||
|
||
@defun find-image specs
|
||
This function provides a convenient way to find an image satisfying one
|
||
of a list of image specifications @var{specs}.
|
||
|
||
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
|
||
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
|
||
@var{file} exists, is used to construct the image specification to be
|
||
returned. If no specification is satisfied, @code{nil} is returned.
|
||
|
||
The image is looked for in @code{image-load-path}.
|
||
@end defun
|
||
|
||
@defopt image-load-path
|
||
This variable's value is a list of locations in which to search for
|
||
image files. If an element is a string or a variable symbol whose
|
||
value is a string, the string is taken to be the name of a directory
|
||
to search. If an element is a variable symbol whose value is a list,
|
||
that is taken to be a list of directory names to search.
|
||
|
||
The default is to search in the @file{images} subdirectory of the
|
||
directory specified by @code{data-directory}, then the directory
|
||
specified by @code{data-directory}, and finally in the directories in
|
||
@code{load-path}. Subdirectories are not automatically included in
|
||
the search, so if you put an image file in a subdirectory, you have to
|
||
supply the subdirectory name explicitly. For example, to find the
|
||
image @file{images/foo/bar.xpm} within @code{data-directory}, you
|
||
should specify the image as follows:
|
||
|
||
@example
|
||
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
|
||
@end example
|
||
@end defopt
|
||
|
||
@defun image-load-path-for-library library image &optional path no-error
|
||
This function returns a suitable search path for images used by the
|
||
Lisp package @var{library}.
|
||
|
||
The function searches for @var{image} first using @code{image-load-path},
|
||
excluding @file{@code{data-directory}/images}, and then in
|
||
@code{load-path}, followed by a path suitable for @var{library}, which
|
||
includes @file{../../etc/images} and @file{../etc/images} relative to
|
||
the library file itself, and finally in
|
||
@file{@code{data-directory}/images}.
|
||
|
||
Then this function returns a list of directories which contains first
|
||
the directory in which @var{image} was found, followed by the value of
|
||
@code{load-path}. If @var{path} is given, it is used instead of
|
||
@code{load-path}.
|
||
|
||
If @var{no-error} is non-@code{nil} and a suitable path can't be
|
||
found, don't signal an error. Instead, return a list of directories as
|
||
before, except that @code{nil} appears in place of the image directory.
|
||
|
||
Here is an example of using @code{image-load-path-for-library}:
|
||
|
||
@example
|
||
(defvar image-load-path) ; shush compiler
|
||
(let* ((load-path (image-load-path-for-library
|
||
"mh-e" "mh-logo.xpm"))
|
||
(image-load-path (cons (car load-path)
|
||
image-load-path)))
|
||
(mh-tool-bar-folder-buttons-init))
|
||
@end example
|
||
@end defun
|
||
|
||
@vindex image-scaling-factor
|
||
Images are automatically scaled when created based on the
|
||
@code{image-scaling-factor} variable. The value is either a floating
|
||
point number (where numbers higher than 1 means to increase the size
|
||
and lower means to shrink the size), or the symbol @code{auto}, which
|
||
will compute a scaling factor based on the font pixel size.
|
||
|
||
@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
|
||
section.
|
||
|
||
@defun insert-image image &optional string area slice
|
||
This function inserts @var{image} in the current buffer at point. The
|
||
value @var{image} should be an image descriptor; it could be a value
|
||
returned by @code{create-image}, or the value of a symbol defined with
|
||
@code{defimage}. The argument @var{string} specifies the text to put
|
||
in the buffer to hold the image. If it is omitted or @code{nil},
|
||
@code{insert-image} uses @code{" "} by default.
|
||
|
||
The argument @var{area} specifies whether to put the image in a margin.
|
||
If it is @code{left-margin}, the image appears in the left margin;
|
||
@code{right-margin} specifies the right margin. If @var{area} is
|
||
@code{nil} or omitted, the image is displayed at point within the
|
||
buffer's text.
|
||
|
||
The argument @var{slice} specifies a slice of the image to insert. If
|
||
@var{slice} is @code{nil} or omitted the whole image is inserted.
|
||
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
|
||
0.0--1.0 stands for that fraction of the width or height of the entire
|
||
image.
|
||
|
||
Internally, this function inserts @var{string} in the buffer, and gives
|
||
it a @code{display} property which specifies @var{image}. @xref{Display
|
||
Property}.
|
||
@end defun
|
||
|
||
@cindex slice, image
|
||
@cindex image slice
|
||
@defun insert-sliced-image image &optional string area rows cols
|
||
This function inserts @var{image} in the current buffer at point, like
|
||
@code{insert-image}, but splits the image into @var{rows}x@var{cols}
|
||
equally sized slices.
|
||
|
||
Emacs displays each slice as a
|
||
separate image, and allows more intuitive scrolling up/down, instead of
|
||
jumping up/down the entire image when paging through a buffer that
|
||
displays (large) images.
|
||
@end defun
|
||
|
||
@defun put-image image pos &optional string area
|
||
This function puts image @var{image} in front of @var{pos} in the
|
||
current buffer. The argument @var{pos} should be an integer or a
|
||
marker. It specifies the buffer position where the image should appear.
|
||
The argument @var{string} specifies the text that should hold the image
|
||
as an alternative to the default.
|
||
|
||
The argument @var{image} must be an image descriptor, perhaps returned
|
||
by @code{create-image} or stored by @code{defimage}.
|
||
|
||
The argument @var{area} specifies whether to put the image in a margin.
|
||
If it is @code{left-margin}, the image appears in the left margin;
|
||
@code{right-margin} specifies the right margin. If @var{area} is
|
||
@code{nil} or omitted, the image is displayed at point within the
|
||
buffer's text.
|
||
|
||
Internally, this function creates an overlay, and gives it a
|
||
@code{before-string} property containing text that has a @code{display}
|
||
property whose value is the image. (Whew!)
|
||
@end defun
|
||
|
||
@defun remove-images start end &optional buffer
|
||
This function removes images in @var{buffer} between positions
|
||
@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
|
||
images are removed from the current buffer.
|
||
|
||
This removes only images that were put into @var{buffer} the way
|
||
@code{put-image} does it, not images that were inserted with
|
||
@code{insert-image} or in other ways.
|
||
@end defun
|
||
|
||
@defun image-size spec &optional pixels frame
|
||
@cindex size of image
|
||
This function returns the size of an image as a pair
|
||
@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image
|
||
specification. @var{pixels} non-@code{nil} means return sizes measured
|
||
in pixels, otherwise return sizes measured in the default character size
|
||
of @var{frame} (@pxref{Frame Font}). @var{frame} is the frame on which
|
||
the image will be displayed. @var{frame} null or omitted means use the
|
||
selected frame (@pxref{Input Focus}).
|
||
@end defun
|
||
|
||
@defvar max-image-size
|
||
This variable is used to define the maximum size of image that Emacs
|
||
will load. Emacs will refuse to load (and display) any image that is
|
||
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 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.
|
||
|
||
The purpose of this variable is to prevent unreasonably large images
|
||
from accidentally being loaded into Emacs. It only takes effect the
|
||
first time an image is loaded. Once an image is placed in the image
|
||
cache, it can always be displayed, even if the value of
|
||
@code{max-image-size} is subsequently changed (@pxref{Image Cache}).
|
||
@end defvar
|
||
|
||
Images inserted with the insertion functions above also get a local
|
||
keymap installed in the text properties (or overlays) that span the
|
||
displayed image. This keymap defines the following commands:
|
||
|
||
@table @kbd
|
||
@item +
|
||
Increase the image size (@code{image-increase-size}). A prefix value
|
||
of @samp{4} means to increase the size by 40%. The default is 20%.
|
||
|
||
@item -
|
||
Decrease the image size (@code{image-increase-size}). A prefix value
|
||
of @samp{4} means to decrease the size by 40%. The default is 20%.
|
||
|
||
@item r
|
||
Rotate the image by 90 degrees (@code{image-rotate}).
|
||
|
||
@item o
|
||
Save the image to a file (@code{image-save}).
|
||
@end table
|
||
|
||
@node Multi-Frame Images
|
||
@subsection Multi-Frame Images
|
||
@cindex multi-frame images
|
||
|
||
@cindex animation
|
||
@cindex image animation
|
||
@cindex image frames
|
||
Some image files can contain more than one image. We say that there
|
||
are multiple ``frames'' in the image. At present, Emacs supports
|
||
multiple frames for GIF, TIFF, and certain ImageMagick formats such as
|
||
DJVM@.
|
||
|
||
The frames can be used either to represent multiple pages (this is
|
||
usually the case with multi-frame TIFF files, for example), or to
|
||
create animation (usually the case with multi-frame GIF files).
|
||
|
||
A multi-frame image has a property @code{:index}, whose value is an
|
||
integer (counting from 0) that specifies which frame is being displayed.
|
||
|
||
@defun image-multi-frame-p image
|
||
This function returns non-@code{nil} if @var{image} contains more than
|
||
one frame. The actual return value is a cons @code{(@var{nimages}
|
||
. @var{delay})}, where @var{nimages} is the number of frames and
|
||
@var{delay} is the delay in seconds between them, or @code{nil}
|
||
if the image does not specify a delay. Images that are intended to be
|
||
animated usually specify a frame delay, whereas ones that are intended
|
||
to be treated as multiple pages do not.
|
||
@end defun
|
||
|
||
@defun image-current-frame image
|
||
This function returns the index of the current frame number for
|
||
@var{image}, counting from 0.
|
||
@end defun
|
||
|
||
@defun image-show-frame image n &optional nocheck
|
||
This function switches @var{image} to frame number @var{n}. It
|
||
replaces a frame number outside the valid range with that of the end
|
||
of the range, unless @var{nocheck} is non-@code{nil}. If @var{image}
|
||
does not contain a frame with the specified number, the image displays
|
||
as a hollow box.
|
||
@end defun
|
||
|
||
@defun image-animate image &optional index limit
|
||
This function animates @var{image}. The optional integer @var{index}
|
||
specifies the frame from which to start (default 0). The optional
|
||
argument @var{limit} controls the length of the animation. If omitted
|
||
or @code{nil}, the image animates once only; if @code{t} it loops
|
||
forever; if a number animation stops after that many seconds.
|
||
@end defun
|
||
|
||
@vindex image-minimum-frame-delay
|
||
@vindex image-default-frame-delay
|
||
@noindent Animation operates by means of a timer. Note that Emacs imposes a
|
||
minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds.
|
||
If the image itself does not specify a delay, Emacs uses
|
||
@code{image-default-frame-delay}.
|
||
|
||
@defun image-animate-timer image
|
||
This function returns the timer responsible for animating @var{image},
|
||
if there is one.
|
||
@end defun
|
||
|
||
|
||
@node Image Cache
|
||
@subsection Image Cache
|
||
@cindex image cache
|
||
|
||
Emacs caches images so that it can display them again more
|
||
efficiently. When Emacs displays an image, it searches the image
|
||
cache for an existing image specification @code{equal} to the desired
|
||
specification. If a match is found, the image is displayed from the
|
||
cache. Otherwise, Emacs loads the image normally.
|
||
|
||
@defun image-flush spec &optional frame
|
||
This function removes the image with specification @var{spec} from the
|
||
image cache of frame @var{frame}. Image specifications are compared
|
||
using @code{equal}. If @var{frame} is @code{nil}, it defaults to the
|
||
selected frame. If @var{frame} is @code{t}, the image is flushed on
|
||
all existing frames.
|
||
|
||
In Emacs's current implementation, each graphical terminal possesses an
|
||
image cache, which is shared by all the frames on that terminal
|
||
(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
|
||
also refreshes it in all other frames on the same terminal.
|
||
@end defun
|
||
|
||
One use for @code{image-flush} is to tell Emacs about a change in an
|
||
image file. If an image specification contains a @code{:file}
|
||
property, the image is cached based on the file's contents when the
|
||
image is first displayed. Even if the file subsequently changes,
|
||
Emacs continues displaying the old version of the image. Calling
|
||
@code{image-flush} flushes the image from the cache, forcing Emacs to
|
||
re-read the file the next time it needs to display that image.
|
||
|
||
Another use for @code{image-flush} is for memory conservation. If
|
||
your Lisp program creates a large number of temporary images over a
|
||
period much shorter than @code{image-cache-eviction-delay} (see
|
||
below), you can opt to flush unused images yourself, instead of
|
||
waiting for Emacs to do it automatically.
|
||
|
||
@defun clear-image-cache &optional filter
|
||
This function clears an image cache, removing all the images stored in
|
||
it. If @var{filter} is omitted or @code{nil}, it clears the cache for
|
||
the selected frame. If @var{filter} is a frame, it clears the cache
|
||
for that frame. If @var{filter} is @code{t}, all image caches are
|
||
cleared. Otherwise, @var{filter} is taken to be a file name, and all
|
||
images associated with that file name are removed from all image
|
||
caches.
|
||
@end defun
|
||
|
||
If an image in the image cache has not been displayed for a specified
|
||
period of time, Emacs removes it from the cache and frees the
|
||
associated memory.
|
||
|
||
@defvar image-cache-eviction-delay
|
||
This variable specifies the number of seconds an image can remain in
|
||
the cache without being displayed. When an image is not displayed for
|
||
this length of time, Emacs removes it from the image cache.
|
||
|
||
Under some circumstances, if the number of images in the cache grows
|
||
too large, the actual eviction delay may be shorter than this.
|
||
|
||
If the value is @code{nil}, Emacs does not remove images from the cache
|
||
except when you explicitly clear it. This mode can be useful for
|
||
debugging.
|
||
@end defvar
|
||
|
||
@node Xwidgets
|
||
@section Embedded Native Widgets
|
||
@cindex xwidget
|
||
@cindex embedded widgets
|
||
@cindex webkit browser widget
|
||
|
||
Emacs is able to display native widgets, such as GTK WebKit widgets,
|
||
in Emacs buffers when it was built with the necessary support
|
||
libraries and is running on a graphical terminal. To test whether
|
||
Emacs supports display of embedded widgets, check that the
|
||
@code{xwidget-internal} feature is available (@pxref{Named Features}).
|
||
|
||
To display an embedded widget in a buffer, you must first create an
|
||
xwidget object, and then use that object as the display specifier
|
||
in a @code{display} text or overlay property (@pxref{Display
|
||
Property}).
|
||
|
||
@defun make-xwidget type title width height arguments &optional buffer
|
||
This creates and returns an xwidget object. If
|
||
@var{buffer} is omitted or @code{nil}, it defaults to the current
|
||
buffer. If @var{buffer} names a buffer that doesn't exist, it will be
|
||
created. The @var{type} identifies the type of the xwidget component,
|
||
it can be one of the following:
|
||
|
||
@table @code
|
||
@item webkit
|
||
The WebKit component.
|
||
@end table
|
||
|
||
The @var{width} and @var{height} arguments specify the widget size in
|
||
pixels, and @var{title}, a string, specifies its title.
|
||
@end defun
|
||
|
||
@defun xwidgetp object
|
||
This function returns @code{t} if @var{object} is an xwidget,
|
||
@code{nil} otherwise.
|
||
@end defun
|
||
|
||
@defun xwidget-plist xwidget
|
||
This function returns the property list of @var{xwidget}.
|
||
@end defun
|
||
|
||
@defun set-xwidget-plist xwidget plist
|
||
This function replaces the property list of @var{xwidget} with a new
|
||
property list given by @var{plist}.
|
||
@end defun
|
||
|
||
@defun xwidget-buffer xwidget
|
||
This function returns the buffer of @var{xwidget}.
|
||
@end defun
|
||
|
||
@defun get-buffer-xwidgets buffer
|
||
This function returns a list of xwidget objects associated with the
|
||
@var{buffer}, which can be specified as a buffer object or a name of
|
||
an existing buffer, a string. The value is @code{nil} if @var{buffer}
|
||
contains no xwidgets.
|
||
@end defun
|
||
|
||
@defun xwidget-webkit-goto-uri xwidget uri
|
||
This function browses the specified @var{uri} in the given
|
||
@var{xwidget}. The @var{uri} is a string that specifies the name of a
|
||
file or a URL. @c FIXME: What else can a URI specify in this context?
|
||
@end defun
|
||
|
||
@defun xwidget-webkit-execute-script xwidget script
|
||
This function causes the browser widget specified by @var{xwidget} to
|
||
execute the specified JavaScript @code{script}.
|
||
@end defun
|
||
|
||
@defun xwidget-webkit-execute-script-rv xwidget script &optional default
|
||
This function executes the specified @var{script} like
|
||
@code{xwidget-webkit-execute-script} does, but it also returns the
|
||
script's return value as a string. If @var{script} doesn't return a
|
||
value, this function returns @var{default}, or @code{nil} if
|
||
@var{default} was omitted.
|
||
@end defun
|
||
|
||
@defun xwidget-webkit-get-title xwidget
|
||
This function returns the title of @var{xwidget} as a string.
|
||
@end defun
|
||
|
||
@defun xwidget-resize xwidget width height
|
||
This function resizes the specified @var{xwidget} to the size
|
||
@var{width}x@var{height} pixels.
|
||
@end defun
|
||
|
||
@defun xwidget-size-request xwidget
|
||
This function returns the desired size of @var{xwidget} as a list of
|
||
the form @code{(@var{width} @var{height})}. The dimensions are in
|
||
pixels.
|
||
@end defun
|
||
|
||
@defun xwidget-info xwidget
|
||
This function returns the attributes of @var{xwidget} as a vector of
|
||
the form @code{[@var{type} @var{title} @var{width} @var{height}]}.
|
||
The attributes are usually determined by @code{make-xwidget} when the
|
||
xwidget is created.
|
||
@end defun
|
||
|
||
@defun set-xwidget-query-on-exit-flag xwidget flag
|
||
This function allows you to arrange that Emacs will ask the user for
|
||
confirmation before exiting or before killing a buffer that has
|
||
@var{xwidget} associated with it. If @var{flag} is non-@code{nil},
|
||
Emacs will query the user, otherwise it will not.
|
||
@end defun
|
||
|
||
@defun xwidget-query-on-exit-flag xwidget
|
||
This function returns the current setting of @var{xwidget}s
|
||
query-on-exit flag, either @code{t} or @code{nil}.
|
||
@end defun
|
||
|
||
@node Buttons
|
||
@section Buttons
|
||
@cindex buttons in buffers
|
||
@cindex clickable buttons in buffers
|
||
|
||
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 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.
|
||
|
||
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.
|
||
* Button Types:: Defining common properties for classes of buttons.
|
||
* Making Buttons:: Adding buttons to Emacs buffers.
|
||
* Manipulating Buttons:: Getting and setting properties of buttons.
|
||
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
|
||
@end menu
|
||
|
||
@node Button Properties
|
||
@subsection Button Properties
|
||
@cindex button properties
|
||
|
||
Each button has an associated list of properties defining its
|
||
appearance and behavior, and other arbitrary properties may be used
|
||
for application specific purposes. The following properties have
|
||
special meaning to the Button package:
|
||
|
||
@table @code
|
||
@item action
|
||
@kindex action @r{(button property)}
|
||
The function to call when the user invokes the button, which is passed
|
||
the single argument @var{button}. By default this is @code{ignore},
|
||
which does nothing.
|
||
|
||
@item mouse-action
|
||
@kindex mouse-action @r{(button property)}
|
||
This is similar to @code{action}, and when present, will be used
|
||
instead of @code{action} for button invocations resulting from
|
||
mouse-clicks (instead of the user hitting @key{RET}). If not
|
||
present, mouse-clicks use @code{action} instead.
|
||
|
||
@item face
|
||
@kindex face @r{(button property)}
|
||
This is an Emacs face controlling how buttons of this type are
|
||
displayed; by default this is the @code{button} face.
|
||
|
||
@item mouse-face
|
||
@kindex mouse-face @r{(button property)}
|
||
This is an additional face which controls appearance during
|
||
mouse-overs (merged with the usual button face); by default this is
|
||
the usual Emacs @code{highlight} face.
|
||
|
||
@item keymap
|
||
@kindex keymap @r{(button property)}
|
||
The button's keymap, defining bindings active within the button
|
||
region. By default this is the usual button region keymap, stored
|
||
in the variable @code{button-map}, which defines @key{RET} and
|
||
@key{mouse-2} to invoke the button.
|
||
|
||
@item type
|
||
@kindex type @r{(button property)}
|
||
The button type. @xref{Button Types}.
|
||
|
||
@item help-echo
|
||
@kindex help-index @r{(button property)}
|
||
A string displayed by the Emacs tool-tip help system; by default,
|
||
@code{"mouse-2, RET: Push this button"}.
|
||
|
||
@item follow-link
|
||
@kindex follow-link @r{(button property)}
|
||
The follow-link property, defining how a @key{mouse-1} click behaves
|
||
on this button, @xref{Clickable Text}.
|
||
|
||
@item button
|
||
@kindex button @r{(button property)}
|
||
All buttons have a non-@code{nil} @code{button} property, which may be useful
|
||
in finding regions of text that comprise buttons (which is what the
|
||
standard button functions do).
|
||
@end table
|
||
|
||
There are other properties defined for the regions of text in a
|
||
button, but these are not generally interesting for typical uses.
|
||
|
||
@node Button Types
|
||
@subsection Button Types
|
||
@cindex button types
|
||
|
||
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
|
||
specific tasks.
|
||
|
||
@defun define-button-type name &rest properties
|
||
Define a button type called @var{name} (a symbol).
|
||
The remaining arguments
|
||
form a sequence of @var{property value} pairs, specifying default
|
||
property values for buttons with this type (a button's type may be set
|
||
by giving it a @code{type} property when creating the button, using
|
||
the @code{:type} keyword argument).
|
||
|
||
In addition, the keyword argument @code{:supertype} may be used to
|
||
specify a button-type from which @var{name} inherits its default
|
||
property values. Note that this inheritance happens only when
|
||
@var{name} is defined; subsequent changes to a supertype are not
|
||
reflected in its subtypes.
|
||
@end defun
|
||
|
||
Using @code{define-button-type} to define default properties for
|
||
buttons is not necessary---buttons without any specified type use the
|
||
built-in button-type @code{button}---but it is encouraged, since
|
||
doing so usually makes the resulting code clearer and more efficient.
|
||
|
||
@node Making Buttons
|
||
@subsection Making Buttons
|
||
@cindex making buttons
|
||
|
||
Buttons are associated with a region of text, using an overlay or
|
||
text properties to hold button-specific information, all of which are
|
||
initialized from the button's type (which defaults to the built-in
|
||
button type @code{button}). Like all Emacs text, the appearance of
|
||
the button is governed by the @code{face} property; by default (via
|
||
the @code{face} property inherited from the @code{button} button-type)
|
||
this is a simple underline, like a typical web-page link.
|
||
|
||
For convenience, there are two sorts of button-creation functions,
|
||
those that add button properties to an existing region of a buffer,
|
||
called @code{make-...button}, and those that also insert the button
|
||
text, called @code{insert-...button}.
|
||
|
||
The button-creation functions all take the @code{&rest} argument
|
||
@var{properties}, which should be a sequence of @var{property value}
|
||
pairs, specifying properties to add to the button; see @ref{Button
|
||
Properties}. In addition, the keyword argument @code{:type} may be
|
||
used to specify a button-type from which to inherit other properties;
|
||
see @ref{Button Types}. Any properties not explicitly specified
|
||
during creation will be inherited from the button's type (if the type
|
||
defines such a property).
|
||
|
||
The following functions add a button using an overlay
|
||
(@pxref{Overlays}) to hold the button properties:
|
||
|
||
@defun make-button beg end &rest properties
|
||
This makes a button from @var{beg} to @var{end} in the
|
||
current buffer, and returns it.
|
||
@end defun
|
||
|
||
@defun insert-button label &rest properties
|
||
This insert a button with the label @var{label} at point,
|
||
and returns it.
|
||
@end defun
|
||
|
||
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.
|
||
@end defun
|
||
|
||
@defun insert-text-button label &rest properties
|
||
This inserts a button with the label @var{label} at point, using text
|
||
properties.
|
||
@end defun
|
||
|
||
@node Manipulating Buttons
|
||
@subsection Manipulating Buttons
|
||
@cindex manipulating buttons
|
||
|
||
These are functions for getting and setting properties of buttons.
|
||
Often these are used by a button's invocation function to determine
|
||
what to do.
|
||
|
||
Where a @var{button} parameter is specified, it means an object
|
||
referring to a specific button, either an overlay (for overlay
|
||
buttons), or a buffer-position or marker (for text property buttons).
|
||
Such an object is passed as the first argument to a button's
|
||
invocation function when it is invoked.
|
||
|
||
@defun button-start button
|
||
Return the position at which @var{button} starts.
|
||
@end defun
|
||
|
||
@defun button-end button
|
||
Return the position at which @var{button} ends.
|
||
@end defun
|
||
|
||
@defun button-get button prop
|
||
Get the property of button @var{button} named @var{prop}.
|
||
@end defun
|
||
|
||
@defun button-put button prop val
|
||
Set @var{button}'s @var{prop} property to @var{val}.
|
||
@end defun
|
||
|
||
@defun button-activate button &optional use-mouse-action
|
||
Call @var{button}'s @code{action} property (i.e., invoke the function
|
||
that is the value of that property, passing it the single argument
|
||
@var{button}). If @var{use-mouse-action} is non-@code{nil}, try to
|
||
invoke the button's @code{mouse-action} property instead of
|
||
@code{action}; if the button has no @code{mouse-action} property, use
|
||
@code{action} as normal.
|
||
@end defun
|
||
|
||
@defun button-label button
|
||
Return @var{button}'s text label.
|
||
@end defun
|
||
|
||
@defun button-type button
|
||
Return @var{button}'s button-type.
|
||
@end defun
|
||
|
||
@defun button-has-type-p button type
|
||
Return @code{t} if @var{button} has button-type @var{type}, or one of
|
||
@var{type}'s subtypes.
|
||
@end defun
|
||
|
||
@defun button-at pos
|
||
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
|
||
Set the button-type @var{type}'s @var{prop} property to @var{val}.
|
||
@end defun
|
||
|
||
@defun button-type-get type prop
|
||
Get the property of button-type @var{type} named @var{prop}.
|
||
@end defun
|
||
|
||
@defun button-type-subtype-p type supertype
|
||
Return @code{t} if button-type @var{type} is a subtype of @var{supertype}.
|
||
@end defun
|
||
|
||
@node Button Buffer Commands
|
||
@subsection Button Buffer Commands
|
||
@cindex button buffer commands
|
||
|
||
These are commands and functions for locating and operating on
|
||
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 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
|
||
@code{mouse-1-click-follows-link} is set, a quick @key{mouse-1} click
|
||
will also activate the @code{push-button} command.
|
||
@xref{Clickable Text}.
|
||
|
||
@deffn Command push-button &optional pos use-mouse-action
|
||
Perform the action specified by a button at location @var{pos}.
|
||
@var{pos} may be either a buffer position or a mouse-event. If
|
||
@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
|
||
mouse-event (@pxref{Mouse Events}), try to invoke the button's
|
||
@code{mouse-action} property instead of @code{action}; if the button
|
||
has no @code{mouse-action} property, use @code{action} as normal.
|
||
@var{pos} defaults to point, except when @code{push-button} is invoked
|
||
interactively as the result of a mouse-event, in which case, the mouse
|
||
event's position is used. If there's no button at @var{pos}, do
|
||
nothing and return @code{nil}, otherwise return @code{t}.
|
||
@end deffn
|
||
|
||
@deffn Command forward-button n &optional wrap display-message
|
||
Move to the @var{n}th next button, or @var{n}th previous button if
|
||
@var{n} is negative. If @var{n} is zero, move to the start of any
|
||
button at point. If @var{wrap} is non-@code{nil}, moving past either
|
||
end of the buffer continues from the other end. If
|
||
@var{display-message} is non-@code{nil}, the button's help-echo string
|
||
is displayed. Any button with a non-@code{nil} @code{skip} property
|
||
is skipped over. Returns the button found.
|
||
@end deffn
|
||
|
||
@deffn Command backward-button n &optional wrap display-message
|
||
Move to the @var{n}th previous button, or @var{n}th next button if
|
||
@var{n} is negative. If @var{n} is zero, move to the start of any
|
||
button at point. If @var{wrap} is non-@code{nil}, moving past either
|
||
end of the buffer continues from the other end. If
|
||
@var{display-message} is non-@code{nil}, the button's help-echo string
|
||
is displayed. Any button with a non-@code{nil} @code{skip} property
|
||
is skipped over. Returns the button found.
|
||
@end deffn
|
||
|
||
@defun next-button pos &optional count-current
|
||
@defunx previous-button pos &optional count-current
|
||
Return the next button after (for @code{next-button}) or before (for
|
||
@code{previous-button}) position @var{pos} in the current buffer. If
|
||
@var{count-current} is non-@code{nil}, count any button at @var{pos}
|
||
in the search, instead of starting at the next button.
|
||
@end defun
|
||
|
||
@node Abstract Display
|
||
@section Abstract Display
|
||
@cindex ewoc
|
||
@cindex display, abstract
|
||
@cindex display, arbitrary objects
|
||
@cindex model/view/controller
|
||
@cindex view part, model/view/controller
|
||
|
||
The Ewoc package constructs buffer text that represents a structure
|
||
of Lisp objects, and updates the text to follow changes in that
|
||
structure. This is like the ``view'' component in the
|
||
``model--view--controller'' design paradigm. Ewoc means ``Emacs's
|
||
Widget for Object Collections''.
|
||
|
||
An @dfn{ewoc} is a structure that organizes information required to
|
||
construct buffer text that represents certain Lisp data. The buffer
|
||
text of the ewoc has three parts, in order: first, fixed @dfn{header}
|
||
text; next, textual descriptions of a series of data elements (Lisp
|
||
objects that you specify); and last, fixed @dfn{footer} text.
|
||
Specifically, an ewoc contains information on:
|
||
|
||
@itemize @bullet
|
||
@item
|
||
The buffer which its text is generated in.
|
||
|
||
@item
|
||
The text's start position in the buffer.
|
||
|
||
@item
|
||
The header and footer strings.
|
||
|
||
@item
|
||
@cindex node, ewoc
|
||
@c or "@cindex node, abstract display"?
|
||
A doubly-linked chain of @dfn{nodes}, each of which contains:
|
||
|
||
@itemize
|
||
@item
|
||
A @dfn{data element}, a single Lisp object.
|
||
|
||
@item
|
||
Links to the preceding and following nodes in the chain.
|
||
@end itemize
|
||
|
||
@item
|
||
A @dfn{pretty-printer} function which is responsible for
|
||
inserting the textual representation of a data
|
||
element value into the current buffer.
|
||
@end itemize
|
||
|
||
Typically, you define an ewoc with @code{ewoc-create}, and then pass
|
||
the resulting ewoc structure to other functions in the Ewoc package to
|
||
build nodes within it, and display it in the buffer. Once it is
|
||
displayed in the buffer, other functions determine the correspondence
|
||
between buffer positions and nodes, move point from one node's textual
|
||
representation to another, and so forth. @xref{Abstract Display
|
||
Functions}.
|
||
|
||
@cindex encapsulation, ewoc
|
||
@c or "@cindex encapsulation, abstract display"?
|
||
A node @dfn{encapsulates} a data element much the way a variable
|
||
holds a value. Normally, encapsulation occurs as a part of adding a
|
||
node to the ewoc. You can retrieve the data element value and place a
|
||
new value in its place, like so:
|
||
|
||
@lisp
|
||
(ewoc-data @var{node})
|
||
@result{} value
|
||
|
||
(ewoc-set-data @var{node} @var{new-value})
|
||
@result{} @var{new-value}
|
||
@end lisp
|
||
|
||
@noindent
|
||
You can also use, as the data element value, a Lisp object (list or
|
||
vector) that is a container for the real value, or an index into
|
||
some other structure. The example (@pxref{Abstract Display Example})
|
||
uses the latter approach.
|
||
|
||
When the data changes, you will want to update the text in the
|
||
buffer. You can update all nodes by calling @code{ewoc-refresh}, or
|
||
just specific nodes using @code{ewoc-invalidate}, or all nodes
|
||
satisfying a predicate using @code{ewoc-map}. Alternatively, you can
|
||
delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter},
|
||
and add new nodes in their place. Deleting a node from an ewoc deletes
|
||
its associated textual description from buffer, as well.
|
||
|
||
@menu
|
||
* Abstract Display Functions:: Functions in the Ewoc package.
|
||
* Abstract Display Example:: Example of using Ewoc.
|
||
@end menu
|
||
|
||
@node Abstract Display Functions
|
||
@subsection Abstract Display Functions
|
||
|
||
In this subsection, @var{ewoc} and @var{node} stand for the
|
||
structures described above (@pxref{Abstract Display}), while
|
||
@var{data} stands for an arbitrary Lisp object used as a data element.
|
||
|
||
@defun ewoc-create pretty-printer &optional header footer nosep
|
||
This constructs and returns a new ewoc, with no nodes (and thus no data
|
||
elements). @var{pretty-printer} should be a function that takes one
|
||
argument, a data element of the sort you plan to use in this ewoc, and
|
||
inserts its textual description at point using @code{insert} (and never
|
||
@code{insert-before-markers}, because that would interfere with the
|
||
Ewoc package's internal mechanisms).
|
||
|
||
Normally, a newline is automatically inserted after the header,
|
||
the footer and every node's textual description. If @var{nosep}
|
||
is non-@code{nil}, no newline is inserted. This may be useful for
|
||
displaying an entire ewoc on a single line, for example, or for
|
||
making nodes invisible by arranging for @var{pretty-printer}
|
||
to do nothing for those nodes.
|
||
|
||
An ewoc maintains its text in the buffer that is current when
|
||
you create it, so switch to the intended buffer before calling
|
||
@code{ewoc-create}.
|
||
@end defun
|
||
|
||
@defun ewoc-buffer ewoc
|
||
This returns the buffer where @var{ewoc} maintains its text.
|
||
@end defun
|
||
|
||
@defun ewoc-get-hf ewoc
|
||
This returns a cons cell @code{(@var{header} . @var{footer})}
|
||
made from @var{ewoc}'s header and footer.
|
||
@end defun
|
||
|
||
@defun ewoc-set-hf ewoc header footer
|
||
This sets the header and footer of @var{ewoc} to the strings
|
||
@var{header} and @var{footer}, respectively.
|
||
@end defun
|
||
|
||
@defun ewoc-enter-first ewoc data
|
||
@defunx ewoc-enter-last ewoc data
|
||
These add a new node encapsulating @var{data}, putting it, respectively,
|
||
at the beginning or end of @var{ewoc}'s chain of nodes.
|
||
@end defun
|
||
|
||
@defun ewoc-enter-before ewoc node data
|
||
@defunx ewoc-enter-after ewoc node data
|
||
These add a new node encapsulating @var{data}, adding it to
|
||
@var{ewoc} before or after @var{node}, respectively.
|
||
@end defun
|
||
|
||
@defun ewoc-prev ewoc node
|
||
@defunx ewoc-next ewoc node
|
||
These return, respectively, the previous node and the next node of @var{node}
|
||
in @var{ewoc}.
|
||
@end defun
|
||
|
||
@defun ewoc-nth ewoc n
|
||
This returns the node in @var{ewoc} found at zero-based index @var{n}.
|
||
A negative @var{n} means count from the end. @code{ewoc-nth} returns
|
||
@code{nil} if @var{n} is out of range.
|
||
@end defun
|
||
|
||
@defun ewoc-data node
|
||
This extracts the data encapsulated by @var{node} and returns it.
|
||
@end defun
|
||
|
||
@defun ewoc-set-data node data
|
||
This sets the data encapsulated by @var{node} to @var{data}.
|
||
@end defun
|
||
|
||
@defun ewoc-locate ewoc &optional pos guess
|
||
This determines the node in @var{ewoc} which contains point (or
|
||
@var{pos} if specified), and returns that node. If @var{ewoc} has no
|
||
nodes, it returns @code{nil}. If @var{pos} is before the first node,
|
||
it returns the first node; if @var{pos} is after the last node, it returns
|
||
the last node. The optional third arg @var{guess}
|
||
should be a node that is likely to be near @var{pos}; this doesn't
|
||
alter the result, but makes the function run faster.
|
||
@end defun
|
||
|
||
@defun ewoc-location node
|
||
This returns the start position of @var{node}.
|
||
@end defun
|
||
|
||
@defun ewoc-goto-prev ewoc arg
|
||
@defunx ewoc-goto-next ewoc arg
|
||
These move point to the previous or next, respectively, @var{arg}th node
|
||
in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at
|
||
the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next}
|
||
moves past the last node, returning @code{nil}. Excepting this special
|
||
case, these functions return the node moved to.
|
||
@end defun
|
||
|
||
@defun ewoc-goto-node ewoc node
|
||
This moves point to the start of @var{node} in @var{ewoc}.
|
||
@end defun
|
||
|
||
@defun ewoc-refresh ewoc
|
||
This function regenerates the text of @var{ewoc}. It works by
|
||
deleting the text between the header and the footer, i.e., all the
|
||
data elements' representations, and then calling the pretty-printer
|
||
function for each node, one by one, in order.
|
||
@end defun
|
||
|
||
@defun ewoc-invalidate ewoc &rest nodes
|
||
This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
|
||
@var{ewoc} are updated instead of the entire set.
|
||
@end defun
|
||
|
||
@defun ewoc-delete ewoc &rest nodes
|
||
This deletes each node in @var{nodes} from @var{ewoc}.
|
||
@end defun
|
||
|
||
@defun ewoc-filter ewoc predicate &rest args
|
||
This calls @var{predicate} for each data element in @var{ewoc} and
|
||
deletes those nodes for which @var{predicate} returns @code{nil}.
|
||
Any @var{args} are passed to @var{predicate}.
|
||
@end defun
|
||
|
||
@defun ewoc-collect ewoc predicate &rest args
|
||
This calls @var{predicate} for each data element in @var{ewoc}
|
||
and returns a list of those elements for which @var{predicate}
|
||
returns non-@code{nil}. The elements in the list are ordered
|
||
as in the buffer. Any @var{args} are passed to @var{predicate}.
|
||
@end defun
|
||
|
||
@defun ewoc-map map-function ewoc &rest args
|
||
This calls @var{map-function} for each data element in @var{ewoc} and
|
||
updates those nodes for which @var{map-function} returns non-@code{nil}.
|
||
Any @var{args} are passed to @var{map-function}.
|
||
@end defun
|
||
|
||
@node Abstract Display Example
|
||
@subsection Abstract Display Example
|
||
|
||
Here is a simple example using functions of the ewoc package to
|
||
implement a @dfn{color components} display, an area in a buffer that
|
||
represents a vector of three integers (itself representing a 24-bit RGB
|
||
value) in various ways.
|
||
|
||
@example
|
||
(setq colorcomp-ewoc nil
|
||
colorcomp-data nil
|
||
colorcomp-mode-map nil
|
||
colorcomp-labels ["Red" "Green" "Blue"])
|
||
|
||
(defun colorcomp-pp (data)
|
||
(if data
|
||
(let ((comp (aref colorcomp-data data)))
|
||
(insert (aref colorcomp-labels data) "\t: #x"
|
||
(format "%02X" comp) " "
|
||
(make-string (ash comp -2) ?#) "\n"))
|
||
(let ((cstr (format "#%02X%02X%02X"
|
||
(aref colorcomp-data 0)
|
||
(aref colorcomp-data 1)
|
||
(aref colorcomp-data 2)))
|
||
(samp " (sample text) "))
|
||
(insert "Color\t: "
|
||
(propertize samp 'face
|
||
`(foreground-color . ,cstr))
|
||
(propertize samp 'face
|
||
`(background-color . ,cstr))
|
||
"\n"))))
|
||
|
||
(defun colorcomp (color)
|
||
"Allow fiddling with COLOR in a new buffer.
|
||
The buffer is in Color Components mode."
|
||
(interactive "sColor (name or #RGB or #RRGGBB): ")
|
||
(when (string= "" color)
|
||
(setq color "green"))
|
||
(unless (color-values color)
|
||
(error "No such color: %S" color))
|
||
(switch-to-buffer
|
||
(generate-new-buffer (format "originally: %s" color)))
|
||
(kill-all-local-variables)
|
||
(setq major-mode 'colorcomp-mode
|
||
mode-name "Color Components")
|
||
(use-local-map colorcomp-mode-map)
|
||
(erase-buffer)
|
||
(buffer-disable-undo)
|
||
(let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
|
||
(color-values color))))
|
||
(ewoc (ewoc-create 'colorcomp-pp
|
||
"\nColor Components\n\n"
|
||
(substitute-command-keys
|
||
"\n\\@{colorcomp-mode-map@}"))))
|
||
(set (make-local-variable 'colorcomp-data) data)
|
||
(set (make-local-variable 'colorcomp-ewoc) ewoc)
|
||
(ewoc-enter-last ewoc 0)
|
||
(ewoc-enter-last ewoc 1)
|
||
(ewoc-enter-last ewoc 2)
|
||
(ewoc-enter-last ewoc nil)))
|
||
@end example
|
||
|
||
@cindex controller part, model/view/controller
|
||
This example can be extended to be a color selection widget (in
|
||
other words, the ``controller'' part of the ``model--view--controller''
|
||
design paradigm) by defining commands to modify @code{colorcomp-data}
|
||
and to finish the selection process, and a keymap to tie it all
|
||
together conveniently.
|
||
|
||
@smallexample
|
||
(defun colorcomp-mod (index limit delta)
|
||
(let ((cur (aref colorcomp-data index)))
|
||
(unless (= limit cur)
|
||
(aset colorcomp-data index (+ cur delta)))
|
||
(ewoc-invalidate
|
||
colorcomp-ewoc
|
||
(ewoc-nth colorcomp-ewoc index)
|
||
(ewoc-nth colorcomp-ewoc -1))))
|
||
|
||
(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
|
||
(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
|
||
(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
|
||
(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
|
||
(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
|
||
(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))
|
||
|
||
(defun colorcomp-copy-as-kill-and-exit ()
|
||
"Copy the color components into the kill ring and kill the buffer.
|
||
The string is formatted #RRGGBB (hash followed by six hex digits)."
|
||
(interactive)
|
||
(kill-new (format "#%02X%02X%02X"
|
||
(aref colorcomp-data 0)
|
||
(aref colorcomp-data 1)
|
||
(aref colorcomp-data 2)))
|
||
(kill-buffer nil))
|
||
|
||
(setq colorcomp-mode-map
|
||
(let ((m (make-sparse-keymap)))
|
||
(suppress-keymap m)
|
||
(define-key m "i" 'colorcomp-R-less)
|
||
(define-key m "o" 'colorcomp-R-more)
|
||
(define-key m "k" 'colorcomp-G-less)
|
||
(define-key m "l" 'colorcomp-G-more)
|
||
(define-key m "," 'colorcomp-B-less)
|
||
(define-key m "." 'colorcomp-B-more)
|
||
(define-key m " " 'colorcomp-copy-as-kill-and-exit)
|
||
m))
|
||
@end smallexample
|
||
|
||
Note that we never modify the data in each node, which is fixed when the
|
||
ewoc is created to be either @code{nil} or an index into the vector
|
||
@code{colorcomp-data}, the actual color components.
|
||
|
||
@node Blinking
|
||
@section Blinking Parentheses
|
||
@cindex parenthesis matching
|
||
@cindex blinking parentheses
|
||
@cindex balancing parentheses
|
||
|
||
This section describes the mechanism by which Emacs shows a matching
|
||
open parenthesis when the user inserts a close parenthesis.
|
||
|
||
@defvar blink-paren-function
|
||
The value of this variable should be a function (of no arguments) to
|
||
be called whenever a character with close parenthesis syntax is inserted.
|
||
The value of @code{blink-paren-function} may be @code{nil}, in which
|
||
case nothing is done.
|
||
@end defvar
|
||
|
||
@defopt blink-matching-paren
|
||
If this variable is @code{nil}, then @code{blink-matching-open} does
|
||
nothing.
|
||
@end defopt
|
||
|
||
@defopt blink-matching-paren-distance
|
||
This variable specifies the maximum distance to scan for a matching
|
||
parenthesis before giving up.
|
||
@end defopt
|
||
|
||
@defopt blink-matching-delay
|
||
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 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 parenthesized sexp before point."
|
||
(interactive)
|
||
@end group
|
||
@group
|
||
(let ((blink-matching-paren-distance
|
||
(buffer-size))
|
||
(blink-matching-paren t))
|
||
(blink-matching-open)))
|
||
@end group
|
||
@end smallexample
|
||
@end deffn
|
||
|
||
@node Character Display
|
||
@section Character Display
|
||
|
||
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}.
|
||
|
||
@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
|
||
@subsection Usual Display Conventions
|
||
|
||
Here are the conventions for displaying 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
|
||
The @dfn{printable @acronym{ASCII} characters}, character codes 32
|
||
through 126 (consisting of numerals, English letters, and symbols like
|
||
@samp{#}) are displayed literally.
|
||
|
||
@item
|
||
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
|
||
The newline character (character code 10) has a special effect: it
|
||
ends the preceding line and starts a new line.
|
||
|
||
@cindex ASCII control characters
|
||
@item
|
||
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
|
||
@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
|
||
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 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.
|
||
|
||
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}).
|
||
|
||
@defopt ctl-arrow
|
||
@cindex control characters in display
|
||
This buffer-local variable controls how control characters are
|
||
displayed. If it is non-@code{nil}, they are displayed as a caret
|
||
followed by the character: @samp{^A}. If it is @code{nil}, they are
|
||
displayed as octal escapes: a backslash followed by three octal
|
||
digits, as in @samp{\001}.
|
||
@end defopt
|
||
|
||
@defopt tab-width
|
||
The value of this buffer-local variable is the spacing between tab
|
||
stops used for displaying tab characters in Emacs buffers. The value
|
||
is in units of columns, and the default is 8. Note that this feature
|
||
is completely independent of the user-settable tab stops used by the
|
||
command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
|
||
@end defopt
|
||
|
||
@node Display Tables
|
||
@subsection Display Tables
|
||
|
||
@cindex display table
|
||
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
|
||
@code{nil} in all elements.
|
||
@end defun
|
||
|
||
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} (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
|
||
line.
|
||
|
||
The display table also has six @dfn{extra slots} which serve special
|
||
purposes. Here is a table of their meanings; @code{nil} in any slot
|
||
means to use the default for that slot, as stated below.
|
||
|
||
@table @asis
|
||
@item 0
|
||
The glyph for the end of a truncated screen line (the default for this
|
||
is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses
|
||
arrows in the fringes to indicate truncation, so the display table has
|
||
no effect.
|
||
|
||
@item 1
|
||
The glyph for the end of a continued line (the default is @samp{\}).
|
||
On graphical terminals, Emacs uses curved arrows in the fringes to
|
||
indicate continuation, so the display table has no effect.
|
||
|
||
@item 2
|
||
The glyph for indicating a character displayed as an octal character
|
||
code (the default is @samp{\}).
|
||
|
||
@item 3
|
||
The glyph for indicating a control character (the default is @samp{^}).
|
||
|
||
@item 4
|
||
A vector of glyphs for indicating the presence of invisible lines (the
|
||
default is @samp{...}). @xref{Selective Display}.
|
||
|
||
@item 5
|
||
The glyph used to draw the border between side-by-side windows (the
|
||
default is @samp{|}). @xref{Splitting Windows}. This takes effect only
|
||
when there are no scroll bars; if scroll bars are supported and in use,
|
||
a scroll bar separates the two windows.
|
||
@end table
|
||
|
||
For example, here is how to construct a display table that mimics
|
||
the effect of setting @code{ctl-arrow} to a non-@code{nil} value
|
||
(@pxref{Glyphs}, for the function @code{make-glyph-code}):
|
||
|
||
@example
|
||
(setq disptab (make-display-table))
|
||
(dotimes (i 32)
|
||
(or (= i ?\t)
|
||
(= i ?\n)
|
||
(aset disptab i
|
||
(vector (make-glyph-code ?^ 'escape-glyph)
|
||
(make-glyph-code (+ i 64) 'escape-glyph)))))
|
||
(aset disptab 127
|
||
(vector (make-glyph-code ?^ 'escape-glyph)
|
||
(make-glyph-code ?? 'escape-glyph)))))
|
||
@end example
|
||
|
||
@defun display-table-slot display-table slot
|
||
This function returns the value of the extra slot @var{slot} of
|
||
@var{display-table}. The argument @var{slot} may be a number from 0 to
|
||
5 inclusive, or a slot name (symbol). Valid symbols are
|
||
@code{truncation}, @code{wrap}, @code{escape}, @code{control},
|
||
@code{selective-display}, and @code{vertical-border}.
|
||
@end defun
|
||
|
||
@defun set-display-table-slot display-table slot value
|
||
This function stores @var{value} in the extra slot @var{slot} of
|
||
@var{display-table}. The argument @var{slot} may be a number from 0 to
|
||
5 inclusive, or a slot name (symbol). Valid symbols are
|
||
@code{truncation}, @code{wrap}, @code{escape}, @code{control},
|
||
@code{selective-display}, and @code{vertical-border}.
|
||
@end defun
|
||
|
||
@defun describe-display-table display-table
|
||
This function displays a description of the display table
|
||
@var{display-table} in a help buffer.
|
||
@end defun
|
||
|
||
@deffn Command describe-current-display-table
|
||
This command displays a description of the current display table in a
|
||
help buffer.
|
||
@end deffn
|
||
|
||
@node Active Display Table
|
||
@subsection Active Display Table
|
||
@cindex 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
|
||
there is none. The default for @var{window} is the selected window.
|
||
@end defun
|
||
|
||
@defun set-window-display-table window table
|
||
This function sets the display table of @var{window} to @var{table}.
|
||
The argument @var{table} should be either a display table or
|
||
@code{nil}.
|
||
@end defun
|
||
|
||
@defvar buffer-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
|
||
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, or when Emacs
|
||
is outputting text to the standard output or error streams. Although its
|
||
default is typically @code{nil}, in an interactive session if the
|
||
terminal cannot display curved quotes, its default maps curved quotes
|
||
to ASCII approximations. @xref{Keys in Documentation}.
|
||
@end defvar
|
||
|
||
The @file{disp-table} library defines several functions for changing
|
||
the standard display table.
|
||
|
||
@node Glyphs
|
||
@subsection Glyphs
|
||
@cindex glyph
|
||
|
||
@cindex glyph code
|
||
A @dfn{glyph} is a graphical symbol which occupies a single
|
||
character position on the screen. Each glyph is represented in Lisp
|
||
as a @dfn{glyph code}, which specifies a character and optionally a
|
||
face to display it in (@pxref{Faces}). The main use of glyph codes is
|
||
as the entries of display tables (@pxref{Display Tables}). The
|
||
following functions are used to manipulate glyph codes:
|
||
|
||
@defun make-glyph-code char &optional face
|
||
This function returns a glyph code representing char @var{char} with
|
||
face @var{face}. If @var{face} is omitted or @code{nil}, the glyph
|
||
uses the default face; in that case, the glyph code is an integer. If
|
||
@var{face} is non-@code{nil}, the glyph code is not necessarily an
|
||
integer object.
|
||
@end defun
|
||
|
||
@defun glyph-char glyph
|
||
This function returns the character of glyph code @var{glyph}.
|
||
@end defun
|
||
|
||
@defun glyph-face glyph
|
||
This function returns face of glyph code @var{glyph}, or @code{nil} if
|
||
@var{glyph} uses the default face.
|
||
@end defun
|
||
|
||
@ifnottex
|
||
You can set up a @dfn{glyph table} to change how glyph codes are
|
||
actually displayed on text terminals. This feature is semi-obsolete;
|
||
use @code{glyphless-char-display} instead (@pxref{Glyphless Chars}).
|
||
|
||
@defvar glyph-table
|
||
The value of this variable, if non-@code{nil}, is the current glyph
|
||
table. It takes effect only on character terminals; on graphical
|
||
displays, all glyphs are displayed literally. The glyph table should
|
||
be a vector whose @var{g}th element specifies how to display glyph
|
||
code @var{g}, where @var{g} is the glyph code for a glyph whose face
|
||
is unspecified. Each element should be one of the following:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
Display this glyph literally.
|
||
|
||
@item a string
|
||
Display this glyph by sending the specified string to the terminal.
|
||
|
||
@item a glyph code
|
||
Display the specified glyph code instead.
|
||
@end table
|
||
|
||
Any integer glyph code greater than or equal to the length of the
|
||
glyph table is displayed literally.
|
||
@end defvar
|
||
@end ifnottex
|
||
|
||
@node Glyphless Chars
|
||
@subsection Glyphless Character Display
|
||
@cindex glyphless characters
|
||
|
||
@dfn{Glyphless characters} are characters which are displayed in a
|
||
special way, e.g., as a box containing a hexadecimal code, instead of
|
||
being displayed literally. These include characters which are
|
||
explicitly defined to be glyphless, as well as characters for which
|
||
there is no available font (on a graphical display), and characters
|
||
which cannot be encoded by the terminal's coding system (on a text
|
||
terminal).
|
||
|
||
@defvar glyphless-char-display
|
||
The value of this variable is a char-table which defines glyphless
|
||
characters and how they are displayed. Each entry must be one of the
|
||
following display methods:
|
||
|
||
@table @asis
|
||
@item @code{nil}
|
||
Display the character in the usual way.
|
||
|
||
@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. The string should contain at
|
||
most 6 @acronym{ASCII} characters.
|
||
|
||
@item a cons cell @code{(@var{graphical} . @var{text})}
|
||
Display with @var{graphical} on graphical displays, and with
|
||
@var{text} on text terminals. Both @var{graphical} and @var{text}
|
||
must be one of the display methods described above.
|
||
@end table
|
||
|
||
@noindent
|
||
The @code{thin-space}, @code{empty-box}, @code{hex-code}, and
|
||
@acronym{ASCII} string display methods are drawn with the
|
||
@code{glyphless-char} face. On text terminals, a box is emulated by
|
||
square brackets, @samp{[]}.
|
||
|
||
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.
|
||
|
||
If a character has a non-@code{nil} entry in an active display table,
|
||
the display table takes effect; in this case, Emacs does not consult
|
||
@code{glyphless-char-display} at all.
|
||
@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. Do
|
||
not set its value directly from Lisp code; the value takes effect only
|
||
via a custom @code{:set} function (@pxref{Variable Definitions}),
|
||
which updates @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 Beeping
|
||
@section Beeping
|
||
@cindex bell
|
||
|
||
This section describes how to make Emacs ring the bell (or blink the
|
||
screen) to attract the user's attention. Be conservative about how
|
||
often you do this; frequent bells can become irritating. Also be
|
||
careful not to use just beeping when signaling an error is more
|
||
appropriate (@pxref{Errors}).
|
||
|
||
@defun ding &optional do-not-terminate
|
||
@cindex keyboard macro termination
|
||
This function beeps, or flashes the screen (see @code{visible-bell} below).
|
||
It also terminates any keyboard macro currently executing unless
|
||
@var{do-not-terminate} is non-@code{nil}.
|
||
@end defun
|
||
|
||
@defun beep &optional do-not-terminate
|
||
This is a synonym for @code{ding}.
|
||
@end defun
|
||
|
||
@defopt visible-bell
|
||
This variable determines whether Emacs should flash the screen to
|
||
represent a bell. Non-@code{nil} means yes, @code{nil} means no.
|
||
This is effective on graphical displays, and on text terminals
|
||
provided the terminal's Termcap entry defines the visible bell
|
||
capability (@samp{vb}).
|
||
@end defopt
|
||
|
||
@defopt ring-bell-function
|
||
If this is non-@code{nil}, it specifies how Emacs should ring the
|
||
bell. Its value should be a function of no arguments. If this is
|
||
non-@code{nil}, it takes precedence over the @code{visible-bell}
|
||
variable.
|
||
@end defopt
|
||
|
||
@node Window Systems
|
||
@section Window Systems
|
||
|
||
Emacs works with several window systems, most notably the X Window
|
||
System. Both Emacs and X use the term ``window'', but use it
|
||
differently. An Emacs frame is a single window as far as X is
|
||
concerned; the individual Emacs windows are not known to X at all.
|
||
|
||
@defvar window-system
|
||
This terminal-local variable tells Lisp programs what window system
|
||
Emacs is using for displaying the frame. The possible values are
|
||
|
||
@table @code
|
||
@item x
|
||
@cindex X Window System
|
||
Emacs is displaying the frame using X.
|
||
@item w32
|
||
Emacs is displaying the frame using native MS-Windows GUI.
|
||
@item ns
|
||
Emacs is displaying the frame using the Nextstep interface (used on
|
||
GNUstep and macOS).
|
||
@item pc
|
||
Emacs is displaying the frame using MS-DOS direct screen writes.
|
||
@item nil
|
||
Emacs is displaying the frame on a character-based terminal.
|
||
@end table
|
||
@end defvar
|
||
|
||
@defvar initial-window-system
|
||
This variable holds the value of @code{window-system} used for the
|
||
first frame created by Emacs during startup. (When Emacs is invoked
|
||
as a daemon, it does not create any initial
|
||
frames, so @code{initial-window-system} is @code{nil}, except on
|
||
MS-Windows, where it is still @code{w32}. @xref{Initial Options,
|
||
daemon,, emacs, The GNU Emacs Manual}.)
|
||
@end defvar
|
||
|
||
@defun window-system &optional frame
|
||
This function returns a symbol whose name tells what window system is
|
||
used for displaying @var{frame} (which defaults to the currently
|
||
selected frame). The list of possible symbols it returns is the same
|
||
one documented for the variable @code{window-system} above.
|
||
@end defun
|
||
|
||
Do @emph{not} use @code{window-system} and
|
||
@code{initial-window-system} as predicates or boolean flag variables,
|
||
if you want to write code that works differently on text terminals and
|
||
graphic displays. That is because @code{window-system} is not a good
|
||
indicator of Emacs capabilities on a given display type. Instead, use
|
||
@code{display-graphic-p} or any of the other @code{display-*-p}
|
||
predicates described in @ref{Display Feature Testing}.
|
||
|
||
@node Tooltips
|
||
@section Tooltips
|
||
@cindex tooltips
|
||
@dfn{Tooltips} are special frames (@pxref{Frames}) that are used to
|
||
display helpful hints (a.k.a.@: ``tips'') related to the current
|
||
position of the mouse pointer. Emacs uses tooltips to display help
|
||
strings about active portions of text (@pxref{Special Properties}) and
|
||
about various UI elements, such as menu items (@pxref{Extended Menu
|
||
Items}) and tool-bar buttons (@pxref{Tool Bar}).
|
||
|
||
@defun tooltip-mode
|
||
Tooltip Mode is a minor mode that enables display of tooltips.
|
||
Turning off this mode causes the tooltips be displayed in the echo
|
||
area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always
|
||
displayed in the echo area.
|
||
@end defun
|
||
|
||
@vindex x-gtk-use-system-tooltips
|
||
When Emacs is built with GTK+ support, it by default displays tooltips
|
||
using GTK+ functions, and the appearance of the tooltips is then
|
||
controlled by GTK+ settings. GTK+ tooltips can be disabled by
|
||
changing the value of the variable @code{x-gtk-use-system-tooltips} to
|
||
@code{nil}. The rest of this subsection describes how to control
|
||
non-GTK+ tooltips, which are presented by Emacs itself.
|
||
|
||
Since tooltips are special frames, they have their frame parameters
|
||
(@pxref{Frame Parameters}). Unlike other frames, the frame parameters
|
||
for tooltips are stored in a special variable.
|
||
|
||
@defvar tooltip-frame-parameters
|
||
This customizable option holds the frame parameters used for
|
||
displaying tooltips. Any font and color parameters are ignored, and
|
||
the corresponding attributes of the @code{tooltip} face are used
|
||
instead. If @code{left} or @code{top} parameters are included, they
|
||
are used as absolute frame-relative coordinates where the tooltip
|
||
should be shown. (Mouse-relative position of the tooltip can be
|
||
customized using the variables described in @ref{Tooltips,,, emacs,
|
||
The GNU Emacs Manual}.) Note that the @code{left} and @code{top}
|
||
parameters, if present, override the values of mouse-relative offsets.
|
||
@end defvar
|
||
|
||
@vindex tooltip@r{ face}
|
||
The @code{tooltip} face determines the appearance of text shown in
|
||
tooltips. It should generally use a variable-pitch font of size that
|
||
is preferably smaller than the default frame font.
|
||
|
||
@findex tooltip-help-tips
|
||
@defvar tooltip-functions
|
||
This abnormal hook is a list of functions to call when Emacs needs to
|
||
display a tooltip. Each function is called with a single argument
|
||
@var{event} which is a copy of the last mouse movement event. If a
|
||
function on this list actually displays the tooltip, it should return
|
||
non-@code{nil}, and then the rest of the functions will not be
|
||
called. The default value of this variable is a single function
|
||
@code{tooltip-help-tips}.
|
||
@end defvar
|
||
|
||
If you write your own function to be put on the
|
||
@code{tooltip-functions} list, you may need to know the buffer of the
|
||
mouse event that triggered the tooltip display. The following
|
||
function provides that information.
|
||
|
||
@defun tooltip-event-buffer event
|
||
This function returns the buffer over which @var{event} occurred.
|
||
Call it with the argument of the function from
|
||
@code{tooltip-functions} to obtain the buffer whose text triggered the
|
||
tooltip. Note that the event might occur not over a buffer (e.g.,
|
||
over the tool bar), in which case this function will return
|
||
@code{nil}.
|
||
@end defun
|
||
|
||
Other aspects of tooltip display are controlled by several
|
||
customizable settings; see @ref{Tooltips,,, emacs, The GNU Emacs
|
||
Manual}.
|
||
|
||
@node Bidirectional Display
|
||
@section Bidirectional Display
|
||
@cindex bidirectional display
|
||
@cindex right-to-left text
|
||
|
||
Emacs can display text written in scripts, such as Arabic, Farsi,
|
||
and Hebrew, whose natural ordering for horizontal text display runs
|
||
from right to left. Furthermore, segments of Latin script and digits
|
||
embedded in right-to-left text are displayed left-to-right, while
|
||
segments of right-to-left script embedded in left-to-right text
|
||
(e.g., Arabic or Hebrew text in comments or strings in a program
|
||
source file) are appropriately displayed right-to-left. We call such
|
||
mixtures of left-to-right and right-to-left text @dfn{bidirectional
|
||
text}. This section describes the facilities and options for editing
|
||
and displaying bidirectional text.
|
||
|
||
@cindex logical order
|
||
@cindex reading order
|
||
@cindex visual order
|
||
@cindex unicode bidirectional algorithm
|
||
@cindex UBA
|
||
@cindex bidirectional reordering
|
||
@cindex reordering, of bidirectional text
|
||
Text is stored in Emacs buffers and strings in @dfn{logical} (or
|
||
@dfn{reading}) order, i.e., the order in which a human would read
|
||
each character. In right-to-left and bidirectional text, the order in
|
||
which characters are displayed on the screen (called @dfn{visual
|
||
order}) is not the same as logical order; the characters' screen
|
||
positions do not increase monotonically with string or buffer
|
||
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 provides a ``Full
|
||
Bidirectionality'' class implementation of the @acronym{UBA},
|
||
consistent with the requirements of the Unicode Standard v8.0.
|
||
|
||
@defvar bidi-display-reordering
|
||
If the value of this buffer-local variable is non-@code{nil} (the
|
||
default), Emacs performs bidirectional reordering for display. The
|
||
reordering affects buffer text, as well as display strings and overlay
|
||
strings from text and overlay properties in the buffer (@pxref{Overlay
|
||
Properties}, and @pxref{Display Property}). If the value is
|
||
@code{nil}, Emacs does not perform bidirectional reordering in the
|
||
buffer.
|
||
|
||
The default value of @code{bidi-display-reordering} controls the
|
||
reordering of strings which are not directly supplied by a buffer,
|
||
including the text displayed in mode lines (@pxref{Mode Line Format})
|
||
and header lines (@pxref{Header Lines}).
|
||
@end defvar
|
||
|
||
@cindex unibyte buffers, and bidi reordering
|
||
Emacs never reorders the text of a unibyte buffer, even if
|
||
@code{bidi-display-reordering} is non-@code{nil} in the buffer. This
|
||
is because unibyte buffers contain raw bytes, not characters, and thus
|
||
lack the directionality properties required for reordering.
|
||
Therefore, to test whether text in a buffer will be reordered for
|
||
display, it is not enough to test the value of
|
||
@code{bidi-display-reordering} alone. The correct test is this:
|
||
|
||
@example
|
||
(if (and enable-multibyte-characters
|
||
bidi-display-reordering)
|
||
;; Buffer is being reordered for display
|
||
)
|
||
@end example
|
||
|
||
However, unibyte display and overlay strings @emph{are} reordered if
|
||
their parent buffer is reordered. This is because plain-@sc{ascii}
|
||
strings are stored by Emacs as unibyte strings. If a unibyte display
|
||
or overlay string includes non-@sc{ascii} characters, these characters
|
||
are assumed to have left-to-right direction.
|
||
|
||
@cindex display properties, and bidi reordering of text
|
||
Text covered by @code{display} text properties, by overlays with
|
||
@code{display} properties whose value is a string, and by any other
|
||
properties that replace buffer text, is treated as a single unit when
|
||
it is reordered for display. That is, the entire chunk of text
|
||
covered by these properties is reordered together. Moreover, the
|
||
bidirectional properties of the characters in such a chunk of text are
|
||
ignored, and Emacs reorders them as if they were replaced with a
|
||
single character @code{U+FFFC}, known as the @dfn{Object Replacement
|
||
Character}. This means that placing a display property over a portion
|
||
of text may change the way that the surrounding text is reordered for
|
||
display. To prevent this unexpected effect, always place such
|
||
properties on text whose directionality is identical with text that
|
||
surrounds it.
|
||
|
||
@cindex base direction of a paragraph
|
||
Each paragraph of bidirectional text has a @dfn{base direction},
|
||
either right-to-left or left-to-right. Left-to-right paragraphs are
|
||
displayed beginning at the left margin of the window, and are
|
||
truncated or continued when the text reaches the right margin.
|
||
Right-to-left paragraphs are displayed beginning at the right margin,
|
||
and are continued or truncated at the left margin.
|
||
|
||
By default, Emacs determines the base direction of each paragraph by
|
||
looking at the text at its beginning. The precise method of
|
||
determining the base direction is specified by the @acronym{UBA}; in a
|
||
nutshell, the first character in a paragraph that has an explicit
|
||
directionality determines the base direction of the paragraph.
|
||
However, sometimes a buffer may need to force a certain base direction
|
||
for its paragraphs. For example, buffers containing program source
|
||
code should force all paragraphs to be displayed left-to-right. You
|
||
can use following variable to do this:
|
||
|
||
@defvar bidi-paragraph-direction
|
||
If the value of this buffer-local variable is the symbol
|
||
@code{right-to-left} or @code{left-to-right}, all paragraphs in the
|
||
buffer are assumed to have that specified direction. Any other value
|
||
is equivalent to @code{nil} (the default), which means to determine
|
||
the base direction of each paragraph from its contents.
|
||
|
||
@cindex @code{prog-mode}, and @code{bidi-paragraph-direction}
|
||
Modes for program source code should set this to @code{left-to-right}.
|
||
Prog mode does this by default, so modes derived from Prog mode do not
|
||
need to set this explicitly (@pxref{Basic Major Modes}).
|
||
@end defvar
|
||
|
||
@defun current-bidi-paragraph-direction &optional buffer
|
||
This function returns the paragraph direction at point in the named
|
||
@var{buffer}. The returned value is a symbol, either
|
||
@code{left-to-right} or @code{right-to-left}. If @var{buffer} is
|
||
omitted or @code{nil}, it defaults to the current buffer. If the
|
||
buffer-local value of the variable @code{bidi-paragraph-direction} is
|
||
non-@code{nil}, the returned value will be identical to that value;
|
||
otherwise, the returned value reflects the paragraph direction
|
||
determined dynamically by Emacs. For buffers whose value of
|
||
@code{bidi-display-reordering} is @code{nil} as well as unibyte
|
||
buffers, this function always returns @code{left-to-right}.
|
||
@end defun
|
||
|
||
@cindex visual-order cursor motion
|
||
Sometimes there's a need to move point in strict visual order,
|
||
either to the left or to the right of its current screen position.
|
||
Emacs provides a primitive to do that.
|
||
|
||
@defun move-point-visually direction
|
||
This function moves point of the currently selected window to the
|
||
buffer position that appears immediately to the right or to the left
|
||
of point on the screen. If @var{direction} is positive, point will
|
||
move one screen position to the right, otherwise it will move one
|
||
screen position to the left. Note that, depending on the surrounding
|
||
bidirectional context, this could potentially move point many buffer
|
||
positions away. If invoked at the end of a screen line, the function
|
||
moves point to the rightmost or leftmost screen position of the next
|
||
or previous screen line, as appropriate for the value of
|
||
@var{direction}.
|
||
|
||
The function returns the new buffer position as its value.
|
||
@end defun
|
||
|
||
@cindex layout on display, and bidirectional text
|
||
@cindex jumbled display of bidirectional text
|
||
@cindex concatenating bidirectional strings
|
||
Bidirectional reordering can have surprising and unpleasant effects
|
||
when two strings with bidirectional content are juxtaposed in a
|
||
buffer, or otherwise programmatically concatenated into a string of
|
||
text. A typical problematic case is when a buffer consists of
|
||
sequences of text fields separated by whitespace or punctuation
|
||
characters, like Buffer Menu mode or Rmail Summary Mode. Because the
|
||
punctuation characters used as separators have @dfn{weak
|
||
directionality}, they take on the directionality of surrounding text.
|
||
As result, a numeric field that follows a field with bidirectional
|
||
content can be displayed @emph{to the left} of the preceding field,
|
||
messing up the expected layout. There are several ways to avoid this
|
||
problem:
|
||
|
||
@itemize @minus
|
||
@item
|
||
Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or
|
||
@acronym{LRM}, to the end of each field that may have bidirectional
|
||
content, or prepend it to the beginning of the following field. The
|
||
function @code{bidi-string-mark-left-to-right}, described below, comes
|
||
in handy for this purpose. (In a right-to-left paragraph, use
|
||
@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This
|
||
is one of the solutions recommended by the UBA.
|
||
|
||
@item
|
||
Include the tab character in the field separator. The tab character
|
||
plays the role of @dfn{segment separator} in bidirectional reordering,
|
||
causing the text on either side to be reordered separately.
|
||
|
||
@cindex @code{space} display spec, and bidirectional text
|
||
@item
|
||
Separate fields with a @code{display} property or overlay with a
|
||
property value of the form @code{(space . PROPS)} (@pxref{Specified
|
||
Space}). Emacs treats this display specification as a @dfn{paragraph
|
||
separator}, and reorders the text on either side separately.
|
||
@end itemize
|
||
|
||
@defun bidi-string-mark-left-to-right string
|
||
This function returns its argument @var{string}, possibly modified,
|
||
such that the result can be safely concatenated with another string,
|
||
or juxtaposed with another string in a buffer, without disrupting the
|
||
relative layout of this string and the next one on display. If the
|
||
string returned by this function is displayed as part of a
|
||
left-to-right paragraph, it will always appear on display to the left
|
||
of the text that follows it. The function works by examining the
|
||
characters of its argument, and if any of those characters could cause
|
||
reordering on display, the function appends the @acronym{LRM}
|
||
character to the string. The appended @acronym{LRM} character is made
|
||
invisible by giving it an @code{invisible} text property of @code{t}
|
||
(@pxref{Invisible Text}).
|
||
@end defun
|
||
|
||
The reordering algorithm uses the bidirectional properties of the
|
||
characters stored as their @code{bidi-class} property
|
||
(@pxref{Character Properties}). Lisp programs can change these
|
||
properties by calling the @code{put-char-code-property} function.
|
||
However, doing this requires a thorough understanding of the
|
||
@acronym{UBA}, and is therefore not recommended. Any changes to the
|
||
bidirectional properties of a character have global effect: they
|
||
affect all Emacs frames and windows.
|
||
|
||
Similarly, the @code{mirroring} property is used to display 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
|