"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/lispref/display.texi" (14 Apr 2017, 301048 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "display.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Emacs Display

This chapter describes a number of features related to the display that Emacs presents to the user.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Refreshing the Screen

The function redraw-frame clears and redisplays the entire contents of a given frame (@pxref{Frames}). This is useful if the screen is corrupted.

Function: redraw-frame &optional frame

This function clears and redisplays frame frame. If frame is omitted or nil, it redraws the selected frame.

Even more powerful is redraw-display:

Command: redraw-display

This function clears and redisplays all visible frames.

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.

User Option: no-redraw-on-reenter

This variable controls whether Emacs redraws the entire screen after it has been suspended and resumed. Non-nil means there is no need to redraw, nil means redrawing is needed. The default is nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 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.

Function: redisplay &optional force

This function tries immediately to redisplay. The optional argument force, if non-nil, forces the redisplay to be performed, instead of being preempted if input is pending.

The function returns t if it actually tried to redisplay, and nil otherwise. A value of t does not mean that redisplay proceeded to completion; it could have been preempted by newly arriving input.

Although 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.

Function: force-window-update &optional object

This function forces some or all windows to be updated the next time Emacs does a redisplay. If object is a window, that window is to be updated. If object is a buffer or buffer name, all windows displaying that buffer are to be updated. If object is 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 redisplay is called.

Variable: 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 nil, meaning only the selected window, or t, meaning all the windows.

Variable: pre-redisplay-functions

This hook is run just before redisplay. It is called once in each window that is about to be redisplayed, with current-buffer set to the buffer displayed in that window.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Truncation

When a line of text extends beyond the right edge of a window, Emacs can continue the line (make it wrap to the next screen line), or truncate the line (limit it to one screen line). The additional screen lines used to display a long text line are called 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 (see section Fringes). On a text terminal, a ‘$’ in the rightmost column of the window indicates truncation; a ‘\’ on the rightmost column indicates a line that wraps. (The display table can specify alternate characters to use for this; see section Display Tables).

User Option: truncate-lines

If this buffer-local variable is non-nil, lines that extend beyond the right edge of the window are truncated; otherwise, they are continued. As a special exception, the variable truncate-partial-width-windows takes precedence in partial-width windows (i.e., windows that do not occupy the entire frame width).

User Option: truncate-partial-width-windows

This variable controls line truncation in partial-width windows. A partial-width window is one that does not occupy the entire frame width (@pxref{Splitting Windows}). If the value is nil, line truncation is determined by the variable truncate-lines (see above). If the value is an integer n, lines are truncated if the partial-width window has fewer than n columns, regardless of the value of truncate-lines; if the partial-width window has n or more columns, line truncation is determined by truncate-lines. For any other non-nil value, lines are truncated in every partial-width window, regardless of the value of truncate-lines.

When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in a window, that forces truncation.

Variable: wrap-prefix

If this buffer-local variable is non-nil, it defines a wrap prefix which Emacs displays at the start of every continuation line. (If lines are truncated, wrap-prefix is never used.) Its value may be a string or an image (see section Other Display Specifications), or a stretch of whitespace such as specified by the :width or :align-to display properties (see section Specified Spaces). The value is interpreted in the same way as a display text property. See section The display Property.

A wrap prefix may also be specified for regions of text, using the wrap-prefix text or overlay property. This takes precedence over the wrap-prefix variable. @xref{Special Properties}.

Variable: line-prefix

If this buffer-local variable is non-nil, it defines a line prefix which Emacs displays at the start of every non-continuation line. Its value may be a string or an image (see section Other Display Specifications), or a stretch of whitespace such as specified by the :width or :align-to display properties (see section Specified Spaces). The value is interpreted in the same way as a display text property. See section The display Property.

A line prefix may also be specified for regions of text using the line-prefix text or overlay property. This takes precedence over the line-prefix variable. @xref{Special Properties}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 The Echo Area

The echo area is used for displaying error messages (@pxref{Errors}), for messages made with the 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. See The Minibuffer in The GNU Emacs Manual.

Apart from the functions documented in this section, you can print Lisp objects to the echo area by specifying t as the output stream. @xref{Output Streams}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.1 Displaying Messages in the Echo Area

This section describes the standard functions for displaying messages in the echo area.

Function: message format-string &rest arguments

This function displays a message in the echo area. format-string is a format string, and arguments are the objects for its format specifications, like in the format-message function (@pxref{Formatting Strings}). The resulting formatted string is displayed in the echo area; if it contains face text properties, it is displayed with the specified faces (see section Faces). The string is also added to the ‘*Messages*’ buffer, but without text properties (see section Logging Messages in ‘*Messages*).

The text-quoting-style variable controls what quotes are generated; @xref{Keys in Documentation}. A call using a format like "Missing ‘%s’" with grave accents and apostrophes typically generates a message like "Missing ‘foo’" with matching curved quotes. In contrast, a call using a format like "Missing ’%s’" with only apostrophes typically generates a message like "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 inhibit-message is non-nil, no message will be displayed in the echo area, it will only be logged to ‘*Messages*’.

If format-string is nil or the empty string, 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.

(message "Reverting `%s'..." (buffer-name))
 -| Reverting ‘subr.el’...
⇒ "Reverting ‘subr.el’..."
---------- Echo Area ----------
Reverting ‘subr.el’...
---------- Echo Area ----------

To automatically display a message in the echo area or in a pop-buffer, depending on its size, use display-message-or-buffer (see below).

Warning: If you want to use your own string as a message verbatim, don’t just write (message string). If string contains ‘%’, ‘`’, or ‘'’ it may be reformatted, with undesirable results. Instead, use (message "%s" string).

Variable: inhibit-message

When this variable is non-nil, message and related functions will not use the Echo Area to display messages.

Macro: with-temp-message message &rest body

This construct displays a message in the echo area temporarily, during the execution of body. It displays message, executes body, then returns the value of the last body form while restoring the previous echo area contents.

Function: message-or-box format-string &rest arguments

This function displays a message like 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 last-nonmenu-event (@pxref{Command Loop Info}) is either 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 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 last-nonmenu-event to a suitable value around the call.

Function: message-box format-string &rest arguments

This function displays a message like 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 message-box uses the echo area, like message.

Function: display-message-or-buffer message &optional buffer-name action frame

This function displays the message 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 max-mini-window-height, it is displayed in the echo area, using message. Otherwise, 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 message is a string, then the optional argument buffer-name is the name of the buffer used to display it when a pop-up buffer is used, defaulting to ‘*Message*’. In the case where 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 action and frame are as for display-buffer, and only used if a buffer is displayed.

Function: current-message

This function returns the message currently being displayed in the echo area, or nil if there is none.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.2 Reporting Operation Progress

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 progress reporter.

Here is a working example that does nothing useful:

(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))
Function: 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 message in the echo area, followed by progress percentage. message is treated as a simple string. If you need it to depend on a filename, for instance, use format-message before calling this function.

The arguments min-value and 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 point-min and point-max correspondingly. max-value should be greater than min-value.

Alternatively, you can set min-value and max-value to 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 min-value and max-value are numbers, you can give the argument current-value a numerical value specifying the initial progress; if omitted, this defaults to min-value.

The remaining arguments control the rate of echo area updates. The progress reporter will wait for at least min-change more percents of the operation to be completed before printing next message; the default is one percent. 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 progress-reporter-update, so the first message is printed immediately.

Function: progress-reporter-update reporter &optional value

This function does the main work of reporting progress of your operation. It displays the message of reporter, followed by progress percentage determined by value. If percentage is zero, or close enough according to the min-change and min-time arguments, then it is omitted from the output.

reporter must be the result of a call to make-progress-reporter. value specifies the current state of your operation and must be between min-value and max-value (inclusive) as passed to make-progress-reporter. For instance, if you scan a buffer, then value should be the result of a call to point.

This function respects min-change and min-time as passed to 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.

Function: progress-reporter-force-update reporter &optional value new-message

This function is similar to progress-reporter-update except that it prints a message in the echo area unconditionally.

The first two arguments have the same meaning as for progress-reporter-update. Optional new-message allows you to change the message of the reporter. Since this function always updates the echo area, such a change will be immediately presented to the user.

Function: progress-reporter-done reporter

This function should be called when the operation is finished. It prints the message of reporter followed by word ‘done’ in the echo area.

You should always call this function and not hope for progress-reporter-update to print ‘100%’. Firstly, it may never print it, there are many good reasons for this not to happen. Secondly, ‘done’ is more explicit.

Macro: dotimes-with-progress-reporter (var count [result]) message body…

This is a convenience macro that works the same way as 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:

(dotimes-with-progress-reporter
    (k 500)
    "Collecting some mana for Emacs..."
  (sit-for 0.01))

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.3 Logging Messages in ‘*Messages*

Almost all the messages displayed in the echo area are also recorded in the ‘*Messages*’ buffer so that the user can refer back to them. This includes all the messages that are output with message. By default, this buffer is read-only and uses the major mode messages-buffer-mode. Nothing prevents the user from killing the ‘*Messages*’ buffer, but the next display of a message recreates it. Any Lisp code that needs to access the ‘*Messages*’ buffer directly and wants to ensure that it exists should use the function messages-buffer.

Function: messages-buffer

This function returns the ‘*Messages*’ buffer. If it does not exist, it creates it, and switches it to messages-buffer-mode.

User Option: message-log-max

This variable specifies how many lines to keep in the ‘*Messages*’ buffer. The value t means there is no limit on how many lines to keep. The value nil disables message logging entirely. Here’s how to display a message and prevent it from being logged:

(let (message-log-max)
  (message …))

To make ‘*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 y-or-n-p: the first is ‘question’, and the second is ‘question...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 make-progress-reporter. They have the form ‘base...how-far’, where base is the same each time, while how-far varies. Logging each message in the series discards the previous one, provided they are consecutive.

The functions make-progress-reporter and 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 ‘...’.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4.4 Echo Area Customization

These variables control details of how the echo area works.

Variable: cursor-in-echo-area

This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-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 nil; Lisp programs bind it to t for brief periods of time.

Variable: echo-area-clear-hook

This normal hook is run whenever the echo area is cleared—either by (message nil) or for any other reason.

User Option: 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 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.

Variable: message-truncate-lines

Normally, displaying a long message resizes the echo area to display the entire message. But if the variable message-truncate-lines is non-nil, the echo area does not resize, and the message is truncated to fit it.

The variable 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}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Reporting Warnings

Warnings are a facility for a program to inform the user of a possible problem, but continue running.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.1 Warning Basics

Every warning has a textual message, which explains the problem for the user, and a severity level which is a symbol. Here are the possible severity levels, in order of decreasing severity, and their meanings:

:emergency

A problem that will seriously impair Emacs operation soon if you do not attend to it promptly.

:error

A report of data or circumstances that are inherently wrong.

:warning

A report of data or circumstances that are not inherently wrong, but raise suspicion of a possible problem.

:debug

A report of information that may be useful if you are debugging.

When your program encounters invalid input data, it can either signal a Lisp error by calling error or signal or report a warning with severity :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 :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 condition-case, the user won’t see the error message; it could show the message to the user by reporting it as a warning.)

Each warning has a 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 (bytecomp). You can also subcategorize the warnings, if you wish, by using more symbols in the list.

Function: display-warning type message &optional level buffer-name

This function reports a warning, using message as the message and type as the warning type. level should be the severity level, with :warning being the default.

buffer-name, if non-nil, specifies the name of the buffer for logging the warning. By default, it is ‘*Warnings*’.

Function: lwarn type level message &rest args

This function reports a warning using the value of (format-message message args...) as the message in the ‘*Warnings*’ buffer. In other respects it is equivalent to display-warning.

Function: warn message &rest args

This function reports a warning using the value of (format-message message args...) as the message, (emacs) as the type, and :warning as the severity level. It exists for compatibility only; we recommend not using it, because you should specify a specific warning type.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.2 Warning Variables

Programs can customize how their warnings appear by binding the variables described in this section.

Variable: 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 (level string function), where level is the severity level it defines. string specifies the textual description of this level. string should use ‘%s’ to specify where to put the warning type information, or it can omit the ‘%s’ so as not to include that information.

The optional function, if non-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.

Variable: warning-prefix-function

If non-nil, the value is a function to generate prefix text for warnings. Programs can bind the variable to a suitable function. 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 warning-levels. It should return a list to use as the entry (this value need not be an actual member of 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 nil then there is no function to call.

Variable: warning-series

Programs can bind this variable to 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 warning-series becomes nil again.

The value can also be a symbol with a function definition. That is equivalent to 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 nil, which means to handle each warning separately.

Variable: warning-fill-prefix

When this variable is non-nil, it specifies a fill prefix to use for filling each warning’s text.

Variable: 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 warning-levels. The default value is " (%s)". If you bind it to "" then the warning type won’t appear at all.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.3 Warning Options

These variables are used by users to control what happens when a Lisp program reports a warning.

User Option: warning-minimum-level

This user option specifies the minimum severity level that should be shown immediately to the user. The default is :warning, which means to immediately display all warnings except :debug warnings.

User Option: warning-minimum-log-level

This user option specifies the minimum severity level that should be logged in the warnings buffer. The default is :warning, which means to log all warnings except :debug warnings.

User Option: 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.

User Option: 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.4 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 delayed-warnings-list for this.

Variable: 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

(type message [level [buffer-name]])

with the same form, and the same meanings, as the argument list of display-warning (see section Warning Basics). Immediately after running post-command-hook (@pxref{Command Overview}), the Emacs command loop displays all the warnings specified by this variable, then resets it to nil.

Programs which need to further customize the delayed warnings mechanism can change the variable delayed-warnings-hook:

Variable: delayed-warnings-hook

This is a normal hook which is run by the Emacs command loop, after post-command-hook, in order to to process and display delayed warnings.

Its default value is a list of two functions:

(collapse-delayed-warnings display-delayed-warnings)

The function collapse-delayed-warnings removes repeated entries from delayed-warnings-list. The function display-delayed-warnings calls display-warning on each of the entries in delayed-warnings-list, in turn, and then sets delayed-warnings-list to nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Invisible Text

You can make characters invisible, so that they do not appear on the screen, with the invisible property. This can be either a text property (@pxref{Text Properties}) or an overlay property (see section 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-nil invisible property makes a character invisible. This is the default case—if you don’t alter the default value of buffer-invisibility-spec, this is how the invisible property works. You should normally use t as the value of the invisible property if you don’t plan to set buffer-invisibility-spec yourself.

More generally, you can use the variable buffer-invisibility-spec to control which values of the invisible property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different invisible values, and subsequently make various subsets visible or invisible by changing the value of buffer-invisibility-spec.

Controlling visibility with 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.

Variable: buffer-invisibility-spec

This variable specifies which kinds of invisible properties actually make a character invisible. Setting this variable makes it buffer-local.

t

A character is invisible if its invisible property is non-nil. This is the default.

a list

Each element of the list specifies a criterion for invisibility; if a character’s invisible property fits any one of these criteria, the character is invisible. The list can have two kinds of elements:

atom

A character is invisible if its invisible property value is atom or if it is a list with atom as a member; comparison is done with eq.

(atom . t)

A character is invisible if its invisible property value is atom or if it is a list with atom as a member; comparison is done with eq. Moreover, a sequence of such characters displays as an ellipsis.

Two functions are specifically provided for adding elements to buffer-invisibility-spec and removing elements from it.

Function: add-to-invisibility-spec element

This function adds the element element to buffer-invisibility-spec. If buffer-invisibility-spec was t, it changes to a list, (t), so that text whose invisible property is t remains invisible.

Function: remove-from-invisibility-spec element

This removes the element element from buffer-invisibility-spec. This does nothing if element is not in the list.

A convention for use of buffer-invisibility-spec is that a major mode should use the mode’s own name as an element of buffer-invisibility-spec and as the value of the invisible property:

;; If you want to display an ellipsis:
(add-to-invisibility-spec '(my-symbol . t))
;; If you don't want ellipsis:
(add-to-invisibility-spec 'my-symbol)

(overlay-put (make-overlay beginning end)
             'invisible 'my-symbol)

;; When done with the invisibility:
(remove-from-invisibility-spec '(my-symbol . t))
;; Or respectively:
(remove-from-invisibility-spec 'my-symbol)

You can check for invisibility using the following function:

Function: invisible-p pos-or-prop

If pos-or-prop is a marker or number, this function returns a non-nil value if the text at that position is invisible.

If pos-or-prop is any other kind of Lisp object, that is taken to mean a possible value of the invisible text or overlay property. In that case, this function returns a non-nil value if that value would cause text to become invisible, based on the current value of buffer-invisibility-spec.

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 next-line, previous-line, ignore invisible newlines if line-move-ignore-invisible is non-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 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 adjustments of point that ended up in the middle of invisible text can be disabled by setting disable-point-adjustment to a non-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-nil 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 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 nil to make the overlay visible, or t to make it invisible again.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Selective Display

Selective display refers to a pair of related features for hiding certain lines on the screen.

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 invisible property (see section 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, C-f (forward-char) moves point unhesitatingly into hidden text. However, the replacement of newline characters with carriage return characters affects some editing commands. For example, 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.

Variable: selective-display

This buffer-local variable enables selective display. This means that lines, or portions of lines, may be made hidden.

When some portion of a buffer is hidden, the vertical movement commands operate as if that portion did not exist, allowing a single next-line command to skip any number of hidden lines. However, character movement commands (such as 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 display appearance of the buffer foo, which changes with the value of selective-display. The contents of the buffer do not change.

(setq selective-display nil)
     ⇒ 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 ----------
(setq selective-display 2)
     ⇒ 2

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------
User Option: selective-display-ellipses

If this buffer-local variable is non-nil, then Emacs displays ‘’ at the end of a line that is followed by hidden text. This example is a continuation of the previous one.

(setq selective-display-ellipses t)
     ⇒ t

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------

You can use a display table to substitute other text for the ellipsis (‘’). See section Display Tables.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Temporary Displays

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.

Macro: with-output-to-temp-buffer buffer-name body…

This function executes the forms in body while arranging to insert any output they print into the buffer named buffer-name, which is first created if necessary, and put into Help mode. (See the similar form with-temp-buffer-window below.) Finally, the buffer is displayed in some window, but that window is not selected.

If the forms in 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 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 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 with-output-to-temp-buffer exits.

with-output-to-temp-buffer binds standard-output to the temporary buffer, then it evaluates the forms in body. Output using the Lisp output functions within 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 body is returned.

---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------
(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
⇒ #<buffer foo>

---------- Buffer: foo ----------

20

#<buffer foo>

---------- Buffer: foo ----------
User Option: temp-buffer-show-function

If this variable is non-nil, 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 temp-buffer-show-hook just as with-output-to-temp-buffer normally would, inside of save-selected-window and with the chosen window and buffer selected.

Variable: temp-buffer-setup-hook

This normal hook is run by with-output-to-temp-buffer before evaluating 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.

Variable: temp-buffer-show-hook

This normal hook is run by 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.

Macro: with-temp-buffer-window buffer-or-name action quit-function body…

This macro is similar to with-output-to-temp-buffer. Like that construct, it executes body while arranging to insert any output it prints into the buffer named buffer-or-name and displays that buffer in some window. Unlike with-output-to-temp-buffer, however, it does not automatically switch that buffer to Help mode.

The argument 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 with-temp-buffer-window exits.

This macro does not call temp-buffer-show-function. Rather, it passes the action argument to display-buffer (@pxref{Choosing Window}) in order to display the buffer.

The value of the last form in body is returned, unless the argument quit-function is specified. In that case, it is called with two arguments: the window showing the buffer and the result of body. The final return value is then whatever quit-function returns.

This macro uses the normal hooks temp-buffer-window-setup-hook and temp-buffer-window-show-hook in place of the analogous hooks run by with-output-to-temp-buffer.

The two constructs described next are mostly identical to with-temp-buffer-window but differ from it as specified:

Macro: with-current-buffer-window buffer-or-name action quit-function &rest body

This macro is like with-temp-buffer-window but unlike that makes the buffer specified by buffer-or-name current for running body.

Macro: with-displayed-buffer-window buffer-or-name action quit-function &rest body

This macro is like with-current-buffer-window but unlike that displays the buffer specified by buffer-or-name before running body.

A window showing a temporary buffer can be fit to the size of that buffer using the following mode:

User Option: 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 fit-window-to-buffer (@pxref{Resizing Windows}) for resizing. You can specify a different function by customizing the options temp-buffer-max-height and temp-buffer-max-width below.

User Option: temp-buffer-max-height

This option specifies the maximum height (in lines) of a window displaying a temporary buffer when 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.

User Option: temp-buffer-max-width

This option specifies the maximum width of a window (in columns) displaying a temporary buffer when 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.

The following function uses the current buffer for temporal display:

Function: momentary-string-display string position &optional char message

This function momentarily displays string in the current buffer at 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 char, momentary-string-display ignores it and returns. Otherwise, that event remains buffered for subsequent use as input. Thus, typing char will simply remove the string from the display, while typing (say) C-f will remove the string from the display and later (presumably) move point forward. The argument char is a space by default.

The return value of momentary-string-display is not meaningful.

If the string 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 before-string property. See section Overlay Properties.

If message is non-nil, it is displayed in the echo area while string is displayed in the buffer. If it is nil, a default message says to type char to continue.

In this example, point is initially located at the beginning of the second line:

---------- Buffer: foo ----------
This is the contents of foo.
∗Second line.
---------- Buffer: foo ----------
(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
⇒ t
---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Overlays

You can use 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.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9.1 Managing Overlays

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.

Function: overlayp object

This function returns t if object is an overlay.

Function: make-overlay start end &optional buffer front-advance rear-advance

This function creates and returns an overlay that belongs to buffer and ranges from start to end. Both start and end must specify buffer positions; they may be integers or markers. If buffer is omitted, the overlay is created in the current buffer.

An overlay whose start and end specify the same buffer position is known as empty. A non-empty overlay can become empty if the text between its start and 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 ‘evaporate’ property (see section evaporate property).

The arguments front-advance and 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 nil, the default, then the overlay extends to include any text inserted at the beginning, but not text inserted at the end. If front-advance is non-nil, text inserted at the beginning of the overlay is excluded from the overlay. If rear-advance is non-nil, text inserted at the end of the overlay is included in the overlay.

Function: overlay-start overlay

This function returns the position at which overlay starts, as an integer.

Function: overlay-end overlay

This function returns the position at which overlay ends, as an integer.

Function: overlay-buffer overlay

This function returns the buffer that overlay belongs to. It returns nil if overlay has been deleted.

Function: delete-overlay overlay

This function deletes 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 move-overlay.

Function: move-overlay overlay start end &optional buffer

This function moves overlay to buffer, and places its bounds at start and end. Both arguments start and end must specify buffer positions; they may be integers or markers.

If buffer is omitted, overlay stays in the same buffer it was already associated with; if overlay was deleted, it goes into the current buffer.

The return value is 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.

Function: remove-overlays &optional start end name value

This function removes all the overlays between start and end whose property name has the value value. It can move the endpoints of the overlays in the region, or split them.

If name is omitted or nil, it means to delete all overlays in the specified region. If start and/or end are omitted or nil, that means the beginning and end of the buffer respectively. Therefore, (remove-overlays) removes all the overlays in the current buffer.

Function: copy-overlay overlay

This function returns a copy of overlay. The copy has the same endpoints and properties as 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}).

Here are some examples:

;; Create an overlay.
(setq foo (make-overlay 1 10))
     ⇒ #<overlay from 1 to 10 in display.texi>
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 10
(overlay-buffer foo)
     ⇒ #<buffer display.texi>
;; Give it a property we can check later.
(overlay-put foo 'happy t)
     ⇒ t
;; Verify the property is present.
(overlay-get foo 'happy)
     ⇒ t
;; Move the overlay.
(move-overlay foo 5 20)
     ⇒ #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
     ⇒ 5
(overlay-end foo)
     ⇒ 20
;; Delete the overlay.
(delete-overlay foo)
     ⇒ nil
;; Verify it is deleted.
foo
     ⇒ #<overlay in no buffer>
;; A deleted overlay has no position.
(overlay-start foo)
     ⇒ nil
(overlay-end foo)
     ⇒ nil
(overlay-buffer foo)
     ⇒ nil
;; Undelete the overlay.
(move-overlay foo 1 20)
     ⇒ #<overlay from 1 to 20 in display.texi>
;; Verify the results.
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 20
(overlay-buffer foo)
     ⇒ #<buffer display.texi>
;; Moving and deleting the overlay does not change its properties.
(overlay-get foo 'happy)
     ⇒ t

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.

Function: overlay-recenter pos

This function recenters the overlays of the current buffer around position pos. That makes overlay lookup faster for positions near pos, but slower for positions far away from pos.

A loop that scans the buffer forwards, creating overlays, can run faster if you do (overlay-recenter (point-max)) first.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9.2 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:

Function: overlay-get overlay prop

This function returns the value of property prop recorded in overlay, if any. If overlay does not record any value for that property, but it does have a category property which is a symbol, that symbol’s prop property is used. Otherwise, the value is nil.

Function: overlay-put overlay prop value

This function sets the value of property prop recorded in overlay to value. It returns value.

Function: overlay-properties overlay

This returns a copy of the property list of overlay.

See also the function 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:

priority

This property’s value determines the priority of the overlay. If you want to specify a priority value, use either 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 priority value is larger overrides the other. (For the 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 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 (primary . secondary), where the primary value is used as described above, and secondary is the fallback value used when 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 sorted argument of overlays-at. See section Searching for Overlays.

window

If the window property is non-nil, then the overlay applies only on that window.

category

If an overlay has a category property, we call it the category of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay.

face

This property controls the appearance of the text (see section Faces). The value of the property can be the following:

mouse-face

This property is used instead of 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., :height, :weight, and :slant). Those attributes are always the same as in the unhighlighted text.

display

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. See section The display Property.

help-echo

If an overlay has a 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}.

field

Consecutive characters with the same field property constitute a field. Some motion functions including forward-word and beginning-of-line stop moving at a field boundary. @xref{Fields}.

modification-hooks

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, 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, 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 inhibit-modification-hooks to t around doing so, to avoid confusing the internal mechanism that calls these hooks.

Text properties also support the modification-hooks property, but the details are somewhat different (@pxref{Special Properties}).

insert-in-front-hooks

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 modification-hooks functions.

insert-behind-hooks

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 modification-hooks functions.

invisible

The invisible property can make the text in the overlay invisible, which means that it does not appear on the screen. See section Invisible Text, for details.

intangible

The intangible property on an overlay works just like the intangible text property. It is obsolete. @xref{Special Properties}, for details.

isearch-open-invisible

This property tells incremental search how to make an invisible overlay visible, permanently, if the final match overlaps it. See section Invisible Text.

isearch-open-invisible-temporary

This property tells incremental search how to make an invisible overlay visible, temporarily, during the search. See section Invisible Text.

before-string

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.

after-string

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.

line-prefix

This property specifies a display spec to prepend to each non-continuation line at display-time. See section Truncation.

wrap-prefix

This property specifies a display spec to prepend to each continuation line at display-time. See section Truncation.

evaporate

If this property is non-nil, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give an empty overlay (see section empty overlay) a non-nil 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.

keymap

If this property is non-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}.

local-map

The local-map property is similar to keymap but replaces the buffer’s local map rather than augmenting existing keymaps. This also means it has lower precedence than minor mode keymaps.

The keymap and local-map properties do not affect a string displayed by the before-string, after-string, or 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 keymap or local-map text property. @xref{Special Properties}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9.3 Searching for Overlays

Function: overlays-at pos &optional sorted

This function returns a list of all the overlays that cover the character at position pos in the current buffer. If sorted is non-nil, the list is in decreasing order of priority, otherwise it is in no particular order. An overlay contains position pos if it begins at or before pos, and ends after pos.

To illustrate usage, here is a Lisp function that returns a list of the overlays that specify property prop for the character at point:

(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))
Function: overlays-in beg end

This function returns a list of the overlays that overlap the region beg through end. An overlay overlaps with a region if it contains one or more characters in the region; empty overlays (see section empty overlay) overlap if they are at beg, strictly between beg and end, or at end when end denotes the position at the end of the buffer.

Function: next-overlay-change pos

This function returns the buffer position of the next beginning or end of an overlay, after pos. If there is none, it returns (point-max).

Function: previous-overlay-change pos

This function returns the buffer position of the previous beginning or end of an overlay, before pos. If there is none, it returns (point-min).

As an example, here’s a simplified (and inefficient) version of the primitive function next-single-char-property-change (@pxref{Property Search}). It searches forward from position pos for the next position where the value of a given property prop, as obtained from either overlays or text properties, changes.

(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)))

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Size of Displayed Text

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.

Function: char-width char

This function returns the width in columns of the character char, if it were displayed in the current buffer (i.e., taking into account the buffer’s display table, if any; see section Display Tables). The width of a tab character is usually tab-width (see section Usual Display Conventions).

Function: string-width string

This function returns the width in columns of the string string, if it were displayed in the current buffer and the selected window.

Function: truncate-string-to-width string width &optional start-column padding ellipsis

This function returns the part of string that fits within width columns, as a new string.

If string does not reach width, then the result ends where string ends. If one multi-column character in string extends across the column width, that character is not included in the result. Thus, the result can fall short of width but cannot go beyond it.

The optional argument start-column specifies the starting column. If this is non-nil, then the first start-column columns of the string are omitted from the value. If one multi-column character in string extends across the column start-column, that character is not included.

The optional argument padding, if non-nil, is a padding character added at the beginning and end of the result string, to extend it to exactly width columns. The padding character is used at the end of the result if it falls short of width. It is also used at the beginning of the result if one multi-column character in string extends across the column start-column.

If ellipsis is non-nil, it should be a string which will replace the end of string (including any padding) if it extends beyond width, unless the display width of string is equal to or less than the display width of ellipsis. If ellipsis is non-nil and not a string, it stands for the value of the variable truncate-string-ellipsis.

(truncate-string-to-width "\tab\t" 12 4)
     ⇒ "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\s)
     ⇒ "    ab  "

The following function returns the size in pixels of text as if it were displayed in a given window. This function is used by fit-window-to-buffer and fit-frame-to-buffer (@pxref{Resizing Windows}) to make a window exactly as large as the text it contains.

Function: 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 window’s buffer in pixels. 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 from, if non-nil, specifies the first text position to consider and defaults to the minimum accessible position of the buffer. If from is t, it uses the minimum accessible position that is not a newline character. The optional argument to, if non-nil, specifies the last text position to consider and defaults to the maximum accessible position of the buffer. If to is t, it uses the maximum accessible position that is not a newline character.

The optional argument x-limit, if non-nil, specifies the maximum pixel-width that can be returned. x-limit nil or omitted, means to use the pixel-width of window’s body (@pxref{Window Sizes}); this is useful when the caller does not intend to change the width of window. Otherwise, the caller should specify here the maximum width window’s body may assume. Text whose x-coordinate is beyond 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 y-limit, if non-nil, specifies the maximum pixel-height that can be returned. Text lines whose y-coordinate is beyond 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 mode-and-header-line nil or omitted means to not include the height of the mode- or header-line of window in the return value. If it is either the symbol mode-line or header-line, include only the height of that line, if present, in the return value. If it is t, include the height of both, if present, in the return value.

Function: line-pixel-height

This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (see section Line Height).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 Line Height

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.

A newline can have a line-height text or overlay property that controls the total height of the display line ending in that newline.

If the property value is t, the newline character has no effect on the displayed height of the line—the visible contents alone determine the height. The 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 (height total), that adds extra space below the display line. First Emacs uses height as a height spec to control extra space above the line; then it adds enough space below the line to bring the total line height up to total. In this case, any value of line-spacing property for the newline is ignored.

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:

integer

If the height spec is a positive integer, the height value is that integer.

float

If the height spec is a float, float, the numeric height value is float times the frame’s default line height.

(face . ratio)

If the height spec is a cons of the format shown, the numeric height is ratio times the height of face face. ratio can be any type of number, or nil which means a ratio of 1. If face is t, it refers to the current face.

(nil . ratio)

If the height spec is a cons of the format shown, the numeric height is ratio times the height of the contents of the line.

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 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 line-spacing frame parameter (@pxref{Layout Parameters}). However, if the default value of line-spacing is non-nil, it overrides the frame’s 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.

You can specify the line spacing for all lines in a buffer via the buffer-local 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.

Finally, a newline can have a line-spacing text or overlay property that can enlarge the default frame line spacing and the buffer local 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12 Faces

A 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.

One way to represent a face is as a property list of attributes, like (:foreground "red" :weight bold). Such a list is called an anonymous face. For example, you can assign an anonymous face as the value of the face text property, and Emacs will display the underlying text with the specified attributes. @xref{Special Properties}.

More commonly, a face is referred to via a face name: a Lisp symbol associated with a set of face attributes(1). Named faces are defined using the defface macro (see section Defining Faces). Emacs comes with several standard named faces (see section Basic Faces).

Many parts of Emacs required named faces, and do not accept anonymous faces. These include the functions documented in Face Attribute Functions, and the variable font-lock-keywords (@pxref{Search-based Fontification}). Unless otherwise stated, we will use the term face to refer only to named faces.

Function: facep object

This function returns a non-nil value if object is a named face: a Lisp symbol or string which serves as a face name. Otherwise, it returns nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.1 Face Attributes

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 unspecified. This special value means that the face doesn’t specify that attribute directly. An unspecified attribute tells Emacs to refer instead to a parent face (see the description :inherit attribute below); or, failing that, to an underlying face (see section Displaying Faces). The 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.

:family

Font family or fontset (a string). See Fonts in The GNU Emacs Manual, for more information about font families. The function font-family-list (see below) returns a list of available family names. See section Fontsets, for information about fontsets.

:foundry

The name of the font foundry for the font family specified by the :family attribute (a string). See Fonts in The GNU Emacs Manual.

:width

Relative character width. This should be one of the symbols ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, or ultra-expanded.

: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 underlying face (see section 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.

:weight

Font weight—one of the symbols (from densest to faintest) ultra-bold, extra-bold, bold, semi-bold, normal, semi-light, light, extra-light, or 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.

:slant

Font slant—one of the symbols italic, oblique, normal, reverse-italic, or reverse-oblique. On text terminals that support variable-brightness text, slanted text is displayed as half-bright.

: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.

:distant-foreground

Alternative foreground color, a string. This is like :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, :distant-foreground is used instead so the text is readable.

:background

Background color, a string. The value can be a system-defined color name, or a hexadecimal color specification. @xref{Color Names}.

:underline

Whether or not characters should be underlined, and in what way. The possible values of the :underline attribute are:

nil

Don’t underline.

t

Underline with the foreground color of the face.

color

Underline in color color, a string specifying a color.

(:color color :style style)

color is either a string, or the symbol foreground-color, meaning the foreground color of the face. Omitting the attribute :color means to use the foreground color of the face. style should be a symbol line or wave, meaning to use a straight or wavy line. Omitting the attribute :style means to use a straight line.

:overline

Whether or not characters should be overlined, and in what color. If the value is t, overlining uses the foreground color of the face. If the value is a string, overlining uses that color. The value nil means do not overline.

:strike-through

Whether or not characters should be strike-through, and in what color. The value is used like that of :overline.

: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 :box attribute, and what they mean:

nil

Don’t draw a box.

t

Draw a box with lines of width 1, in the foreground color.

color

Draw a box with lines of width 1, in color color.

(:line-width width :color color :style style)

This way you can explicitly specify all aspects of the box. The value width specifies the width of the lines to draw; it defaults to 1. A negative width -n means to draw a line of width n that occupies the space of the underlying text, thus avoiding any increase in the character height or width.

The value 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 style specifies whether to draw a 3D box. If it is released-button, the box looks like a 3D button that is not being pressed. If it is pressed-button, the box looks like a 3D button that is being pressed. If it is nil or omitted, a plain 2D box is used.

:inverse-video

Whether or not characters should be displayed in inverse video. The value should be t (yes) or nil (no).

: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 x-bitmap-file-path.

Alternatively, the value can specify the bitmap directly, with a list of the form (width height data). Here, width and height specify the size in pixels, and data is a string containing the raw bits of the bitmap, row by row. Each row occupies (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 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.

:font

The font used to display the face. Its value should be a font object. See section Low-Level Font Representation, for information about font objects, font specs, and font entities.

When specifying this attribute using set-face-attribute (see section Face 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 (see Fonts in 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 :family, :foundry, :width, :height, :weight, and :slant attributes.

: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 (see section Displaying Faces). If a list of faces is used, attributes from faces earlier in the list override those from later faces.

Function: font-family-list &optional frame

This function returns a list of available font family names. The optional argument frame specifies the frame on which the text is to be displayed; if it is nil, the selected frame is used.

User Option: underline-minimum-offset

This variable specifies the minimum distance between the baseline and the underline, in pixels, when displaying underlined text.

User Option: x-bitmap-file-path

This variable specifies a list of directories for searching for bitmap files, for the :stipple attribute.

Function: bitmap-spec-p object

This returns t if object is a valid bitmap specification, suitable for use with :stipple (see above). It returns nil otherwise.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.2 Defining Faces

The usual way to define a face is through the defface macro. This macro associates a face name (a symbol) with a default 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 defface, and then use its name directly.

Macro: defface face spec doc [keyword value]…

This macro declares face as a named face whose default face spec is given by spec. You should not quote the symbol face, and it should not end in ‘-face’ (that would be redundant). The argument doc is a documentation string for the face. The additional keyword arguments have the same meanings as in defgroup and defcustom (@pxref{Common Keywords}).

If face already has a default face spec, this macro does nothing.

The default face spec determines face’s appearance when no customizations are in effect (@pxref{Customization}). If 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 spec. However, if the customizations are subsequently removed, the appearance of face will again be determined by its default face spec.

As an exception, if you evaluate a defface form with C-M-x in Emacs Lisp mode (eval-defun), a special feature of eval-defun overrides any custom face specs on the face, causing the face to reflect exactly what the defface says.

The spec argument is a 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

(display . plist)

display specifies a class of terminals (see below). 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 (display plist).

The display part of an element of spec determines which terminals the element matches. If more than one element of spec matches a given terminal, the first element that matches is the one used for that terminal. There are three possibilities for display:

default

This element of 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 spec. Each of the following elements can override any or all of these defaults.

t

This element of spec matches all terminals. Therefore, any subsequent elements of spec are never used. Normally t is used in the last (or only) element of spec.

a list

If display is a list, each element should have the form (characteristic value…). Here characteristic specifies a way of classifying terminals, and the values are possible classifications which display should apply to. Here are the possible values of characteristic:

type

The kind of window system the terminal uses—either graphic (any graphics-capable display), x, pc (for the MS-DOS console), w32 (for MS Windows 9X/NT/2K/XP), or tty (a non-graphics-capable display). See section window-system.

class

What kinds of colors the terminal supports—either color, grayscale, or mono.

background

The kind of background—either light or dark.

min-colors

An integer that represents the minimum number of colors the terminal should support. This matches a terminal if its display-color-cells value is at least the specified integer.

supports

Whether or not the terminal can display the face attributes given in value… (see section Face Attributes). @xref{Display Face Attribute Testing}, for more information on exactly how this testing is done.

If an element of display specifies more than one value for a given characteristic, any of those values is acceptable. If display has more than one element, each element should specify a different characteristic; then each characteristic of the terminal must match one of the values specified for it in display.

For example, here’s the definition of the standard face highlight:

(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)

Internally, Emacs stores each face’s default spec in its face-defface-spec symbol property (@pxref{Symbol Properties}). The saved-face property stores any face spec saved by the user using the customization buffer; the customized-face property stores the face spec customized for the current session, but not saved; and the 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 face-documentation property.

Normally, a face is declared just once, using defface, and any further changes to its appearance are applied using the Customize framework (e.g., via the Customize user interface or via the custom-set-faces function; @pxref{Applying Customizations}), or by face remapping (see section Face Remapping). In the rare event that you need to change a face spec directly from Lisp, you can use the face-spec-set function.

Function: face-spec-set face spec &optional spec-type

This function applies spec as a face spec for face. spec should be a face spec, as described in the above documentation for defface.

This function also defines face as a valid face name if it is not already one, and (re)calculates its attributes on existing frames.

The argument spec-type determines which spec to set. If it is nil or face-override-spec, this function sets the override spec, which overrides over all other face specs on face. If it is customized-face or saved-face, this function sets the customized spec or the saved custom spec. If it is face-defface-spec, this function sets the default face spec (the same one set by defface). If it is reset, this function clears out all customization specs and override specs from face (in this case, the value of spec is ignored). Any other value of spec-type is reserved for internal use.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.3 Face Attribute Functions

This section describes functions for directly accessing and modifying the attributes of a named face.

Function: face-attribute face attribute &optional frame inherit

This function returns the value of the attribute attribute for face on frame.

If frame is omitted or nil, that means the selected frame (@pxref{Input Focus}). If frame is t, this function returns the value of the specified attribute for newly-created frames (this is normally unspecified, unless you have specified some value using set-face-attribute; see below).

If inherit is nil, only attributes directly defined by face are considered, so the return value may be unspecified, or a relative value. If inherit is non-nil, face’s definition of attribute is merged with the faces specified by its :inherit attribute; however the return value may still be unspecified or relative. If 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 default for inherit; this will resolve any unspecified or relative values by merging with the default face (which is always completely specified).

For example,

(face-attribute 'bold :weight)
     ⇒ bold
Function: face-attribute-relative-p attribute value

This function returns non-nil if value, when used as the value of the face attribute 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.

unspecified is a relative value for all attributes. For :height, floating point and function values are also relative.

For example:

(face-attribute-relative-p :height 2.0)
     ⇒ t
Function: face-all-attributes face &optional frame

This function returns an alist of attributes of face. The elements of the result are name-value pairs of the form (attr-name . attr-value). Optional argument frame specifies the frame whose definition of face to return; if omitted or nil, the returned value describes the default attributes of face for newly created frames.

Function: merge-face-attribute attribute value1 value2

If value1 is a relative value for the face attribute attribute, returns it merged with the underlying value value2; otherwise, if value1 is an absolute value for the face attribute attribute, returns value1 unchanged.

Normally, Emacs uses the face specs of each face to automatically calculate its attributes on each frame (see section Defining Faces). The function 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.

Function: set-face-attribute face frame &rest arguments

This function sets one or more attributes of face for frame. The attributes specifies in this way override the face spec(s) belonging to face.

The extra arguments arguments specify the attributes to set, and the values for them. They should consist of alternating attribute names (such as :family or :underline) and values. Thus,

(set-face-attribute 'foo nil :weight 'bold :slant 'italic)

sets the attribute :weight to bold and the attribute :slant to italic.

If frame is t, this function sets the default attributes for newly created frames. If frame is nil, this function sets the attributes for all existing frames, as well as for newly created frames.

The following commands and functions mostly provide compatibility with old versions of Emacs. They work by calling set-face-attribute. Values of t and nil (or omitted) for their frame argument are handled just like set-face-attribute and face-attribute. The commands read their arguments using the minibuffer, if called interactively.

Command: set-face-foreground face color &optional frame
Command: set-face-background face color &optional frame

These set the :foreground attribute (or :background attribute, respectively) of face to color.

Command: set-face-stipple face pattern &optional frame

This sets the :stipple attribute of face to pattern.

Command: set-face-font face font &optional frame

This sets the :font attribute of face to font.

Function: set-face-bold face bold-p &optional frame

This sets the :weight attribute of face to normal if bold-p is nil, and to bold otherwise.

Function: set-face-italic face italic-p &optional frame

This sets the :slant attribute of face to normal if italic-p is nil, and to italic otherwise.

Function: set-face-underline face underline &optional frame

This sets the :underline attribute of face to underline.

Function: set-face-inverse-video face inverse-video-p &optional frame

This sets the :inverse-video attribute of face to inverse-video-p.

Command: invert-face face &optional frame

This swaps the foreground and background colors of face face.

The following functions examine the attributes of a face. They mostly provide compatibility with old versions of Emacs. If you don’t specify frame, they refer to the selected frame; t refers to the default data for new frames. They return unspecified if the face doesn’t define any value for that attribute. If inherit is nil, only an attribute directly defined by the face is returned. If inherit is non-nil, any faces specified by its :inherit attribute are considered as well, and if 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 default for inherit.

Function: face-font face &optional frame character

This function returns the name of the font of face face.

If the optional argument frame is specified, it returns the name of the font of face for that frame. If frame is omitted or nil, the selected frame is used. And, in this case, if the optional third argument character is supplied, it returns the font name used for character.

Function: face-foreground face &optional frame inherit
Function: face-background face &optional frame inherit

These functions return the foreground color (or background color, respectively) of face face, as a string. If the color is unspecified, they return nil.

Function: face-stipple face &optional frame inherit

This function returns the name of the background stipple pattern of face face, or nil if it doesn’t have one.

Function: face-bold-p face &optional frame inherit

This function returns a non-nil value if the :weight attribute of face is bolder than normal (i.e., one of semi-bold, bold, extra-bold, or ultra-bold). Otherwise, it returns nil.

Function: face-italic-p face &optional frame inherit

This function returns a non-nil value if the :slant attribute of face is italic or oblique, and nil otherwise.

Function: face-underline-p face &optional frame inherit

This function returns non-nil if face face specifies a non-nil :underline attribute.

Function: face-inverse-video-p face &optional frame inherit

This function returns non-nil if face face specifies a non-nil :inverse-video attribute.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.4 Displaying Faces

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:

At each stage, if a face has a valid :inherit attribute, Emacs treats any attribute with an unspecified value as having the corresponding value drawn from the parent face(s). see section 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.5 Face Remapping

The variable 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 text-scale-adjust command (see Text Scale in The GNU Emacs Manual).

Variable: face-remapping-alist

The value of this variable is an alist whose elements have the form (face . remapping). This causes Emacs to display any text having the face face with remapping, rather than the ordinary definition of face.

remapping may be any face spec suitable for a 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 face text property in @ref{Special Properties}. remapping serves as the complete specification for the remapped face—it replaces the normal definition of face, instead of modifying it.

If face-remapping-alist is buffer-local, its local value takes effect only within that buffer.

Note: face remapping is non-recursive. If remapping references the same face name face, either directly or via the :inherit attribute of some other face in remapping, that reference uses the normal definition of face. For instance, if the mode-line face is remapped using this entry in face-remapping-alist:

(mode-line italic mode-line)

then the new definition of the mode-line face inherits from the italic face, and the normal (non-remapped) definition of mode-line face.

The following functions implement a higher-level interface to face-remapping-alist. Most Lisp code should use these functions instead of setting face-remapping-alist directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make face-remapping-alist buffer-local as a side-effect. They manage face-remapping-alist entries of the form

  (face relative-spec-1 relative-spec-2 ... base-spec)

where, as explained above, each of the relative-spec-N and base-spec is either a face name, or a property list of attribute/value pairs. Each of the relative remapping entries, relative-spec-N, is managed by the face-remap-add-relative and face-remap-remove-relative functions; these are intended for simple modifications like changing the text size. The base remapping entry, base-spec, has the lowest priority and is managed by the face-remap-set-base and face-remap-reset-base functions; it is intended for major modes to remap faces in the buffers they control.

Function: face-remap-add-relative face &rest specs

This function adds the face spec in specs as relative remappings for face face in the current buffer. The remaining arguments, 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 face-remap-remove-relative if you need to remove the remapping later.

;; 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)
Function: face-remap-remove-relative cookie

This function removes a relative remapping previously added by face-remap-add-relative. cookie should be the Lisp object returned by face-remap-add-relative when the remapping was added.

Function: face-remap-set-base face &rest specs

This function sets the base remapping of face in the current buffer to specs. If specs is empty, the default base remapping is restored, similar to calling face-remap-reset-base (see below); note that this is different from specs containing a single value nil, which has the opposite result (the global definition of face is ignored).

This overwrites the default base-spec, which inherits the global face definition, so it is up to the caller to add such inheritance if so desired.

Function: face-remap-reset-base face

This function sets the base remapping of face to its default value, which inherits from face’s global definition.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.6 Functions for Working with Faces

Here are additional functions for creating and working with faces.

Function: face-list

This function returns a list of all defined face names.

Function: face-id face

This function returns the face number of face 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.

Function: face-documentation face

This function returns the documentation string of face face, or nil if none was specified for it.

Function: face-equal face1 face2 &optional frame

This returns t if the faces face1 and face2 have the same attributes for display.

Function: face-differs-from-default-p face &optional frame

This returns non-nil if the face face displays differently from the default face.

A face alias provides an equivalent name for a face. You can define a face alias by giving the alias symbol the face-alias property, with a value of the target face name. The following example makes modeline an alias for the mode-line face.

(put 'modeline 'face-alias 'mode-line)
Macro: define-obsolete-face-alias obsolete-face current-face when

This macro defines obsolete-face as an alias for current-face, and also marks it as obsolete, indicating that it may be removed in future. when should be a string indicating when obsolete-face was made obsolete (usually a version number string).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.7 Automatic Face Assignment

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.

Variable: 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, jit-lock-function.

The functions are called in the order listed, with one argument, a buffer position pos. Collectively they should attempt to assign faces to the text in the current buffer starting at pos.

The functions should record the faces they assign by setting the face property. They should also add a non-nil 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 pos already has a non-nil 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.8 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}.

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 (see section Face Attributes).

bold
italic
bold-italic
underline
fixed-pitch
fixed-pitch-serif
variable-pitch

These have the attributes indicated by their names (e.g., bold has a bold :weight attribute), with all other attributes unspecified (and so given by default).

shadow

For dimmed-out text. For example, it is used for the ignored part of a filename in the minibuffer (see Minibuffers for File Names in The GNU Emacs Manual).

link
link-visited

For clickable text buttons that send the user to a different buffer or location.

highlight

For stretches of text that should temporarily stand out. For example, it is commonly assigned to the mouse-face property for cursor highlighting (@pxref{Special Properties}).

match
isearch
lazy-highlight

For text matching (respectively) permanent search matches, interactive search matches, and lazy highlighting other matches than the current interactive one.

error
warning
success

For text concerning errors, warnings, or successes. For example, these are used for messages in ‘*Compilation*’ buffers.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.9 Font Selection

Before Emacs can draw a character on a graphical display, it must select a font for that character(2). See Fonts in The GNU Emacs Manual. Normally, Emacs automatically chooses a font based on the faces assigned to that character—specifically, the face attributes :family, :weight, :slant, and :width (see section 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 closest matching font. The variables in this section control how Emacs makes this selection.

User Option: 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:

(family alternate-families…)

If family is specified but not available, Emacs will try the other families given in alternate-families, one by one, until it finds a family that does exist.

User Option: face-font-selection-order

If there is no font that exactly matches all desired face attributes (:width, :height, :weight, and :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 (: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 :weight and :width have symbolic values in a range centered around normal. Matches that are more extreme (farther from normal) are somewhat preferred to matches that are less extreme (closer to 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 italic face will use a non-italic font that is similar to the default one. But if you put :slant before :height, the italic face will use an italic font, even if its height is not quite right.

User Option: 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:

(registry alternate-registries…)

If registry is specified but not available, Emacs will try the other registries given in alternate-registries, one by one, until it finds a registry that does exist.

Emacs can make use of scalable fonts, but by default it does not use them.

User Option: scalable-fonts-allowed

This variable controls which scalable fonts to use. A value of nil, the default, means do not use scalable fonts. 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,

(setq scalable-fonts-allowed '("iso10646-1$"))

allows the use of scalable fonts with registry iso10646-1.

Variable: face-font-rescale-alist

This variable specifies scaling for certain faces. Its value should be a list of elements of the form

(fontname-regexp . scale-factor)

If fontname-regexp matches the font name that is about to be used, this says to choose a larger similar font according to the factor 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.10 Looking Up Fonts

Function: x-list-fonts name &optional reference-face frame maximum width

This function returns a list of available font names that match name. name should be a string containing a font name in either the Fontconfig, GTK, or XLFD format (see Fonts in The GNU Emacs Manual). Within an XLFD string, wildcard characters may be used: the ‘*’ character matches any substring, and the ‘?’ character matches any single character. Case is ignored when matching font names.

If the optional arguments reference-face and frame are specified, the returned list includes only fonts that are the same size as reference-face (a face name) currently is on the frame frame.

The optional argument maximum sets a limit on how many fonts to return. If it is non-nil, then the return value is truncated after the first maximum matching fonts. Specifying a small value for maximum can make this function much faster, in cases where many fonts match the pattern.

The optional argument width specifies a desired font width. If it is non-nil, the function only returns those fonts whose characters are (on average) width times as wide as reference-face.

Function: x-family-fonts &optional family frame

This function returns a list describing the available fonts for family family on frame. If family is omitted or nil, this list applies to all families, and therefore, it contains all available fonts. Otherwise, family must be a string; it may contain the wildcards ‘?’ and ‘*’.

The list describes the display that frame is on; if frame is omitted or nil, it applies to the selected frame’s display (@pxref{Input Focus}).

Each element in the list is a vector of the following form:

[family width point-size weight slant
 fixed-p full registry-and-encoding]

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. fixed-p is non-nil if the font is fixed-pitch. full is the full name of the font, and registry-and-encoding is a string giving the registry and encoding of the font.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.11 Fontsets

A 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.

Function: create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror

This function defines a new fontset according to the specification string fontset-spec. The string should have this format:

fontpattern, [charset:font]…

Whitespace characters before and after the commas are ignored.

The first part of the string, fontpattern, should have the form of a standard X font name, except that the last two fields should be ‘fontset-alias’.

The new fontset has two names, one long and one short. The long name is fontpattern in its entirety. The short name is ‘fontset-alias’. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless noerror is non-nil, in which case this function does nothing.

If optional argument style-variant-p is non-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 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.

The construct ‘charset:font’ specifies which font to use (in this fontset) for one particular character set. Here, charset is the name of a character set, and 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 fontpattern: it replaces ‘fontset-alias’ with a value that names one character set. For the ASCII character set, ‘fontset-alias’ is replaced with ‘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 fontpattern is this,

-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

-*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

-*-fixed-medium-r-normal-*-24-*-gb2312*-*

You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that have ‘song ti’ or ‘fangsong ti’ in the family field. In such a case, ‘Fontset-n’ can be specified as below:

Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have ‘fixed’ in the family field, and the font specification for Chinese GB2312 characters has a wild card ‘*’ in the family field.

Function: set-fontset-font name character font-spec &optional frame add

This function modifies the existing fontset name to use the font matching with font-spec for the specified character.

If name is nil, this function modifies the fontset of the selected frame or that of frame if frame is not nil.

If name is t, this function modifies the default fontset, whose short name is ‘fontset-default’.

In addition to specifying a single codepoint, character may be a cons (from . to), where from and to are character codepoints. In that case, use font-spec for all the characters in the range from and to (inclusive).

character may be a charset. In that case, use font-spec for all character in the charsets.

character may be a script name. In that case, use font-spec for all character in the charsets.

font-spec may be a font-spec object created by the function font-spec (see section Low-Level Font Representation).

font-spec may be a cons; (family . registry), where family is a family name of a font (possibly including a foundry name at the head), registry is a registry name of a font (possibly including an encoding name at the tail).

font-spec may be a font name string.

font-spec may be nil, which explicitly specifies that there’s no font for the specified 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 add, if non-nil, specifies how to add font-spec to the font specifications previously set. If it is prepend, font-spec is prepended. If it is append, font-spec is appended. By default, font-spec overrides the previous settings.

For instance, this changes the default fontset to use a font of which family name is ‘Kochi Gothic’ for all characters belonging to the charset japanese-jisx0208.

(set-fontset-font t 'japanese-jisx0208
                  (font-spec :family "Kochi Gothic"))
Function: char-displayable-p char

This function returns t if Emacs ought to be able to display char. More precisely, if the selected frame’s fontset has a font to display the character set that 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12.12 Low-Level Font Representation

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: font objects, font specs, and font entities.

Function: fontp object &optional type

Return t if object is a font object, font spec, or font entity. Otherwise, return nil.

The optional argument type, if non-nil, determines the exact type of Lisp object to check for. In that case, type should be one of font-object, font-spec, or font-entity.

A font object is a Lisp object that represents a font that Emacs has opened. Font objects cannot be modified in Lisp, but they can be inspected.

Function: font-at position &optional window string

Return the font object that is being used to display the character at position position in the window window. If window is nil, it defaults to the selected window. If string is nil, position specifies a position in the current buffer; otherwise, string should be a string, and position specifies a position in that string.

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.

Function: font-spec &rest arguments

Return a new font spec using the specifications in arguments, which should come in property-value pairs. The possible specifications are as follows:

:name

The font name (a string), in either XLFD, Fontconfig, or GTK format. See Fonts in The GNU Emacs Manual.

:family
:foundry
:weight
:slant
:width

These have the same meanings as the face attributes of the same name. See section Face Attributes.

:size

The font size—either a non-negative integer that specifies the pixel size, or a floating-point number that specifies the point size.

:adstyle

Additional typographic style information for the font, such as ‘sans’. The value should be a string or a symbol.

:registry

The charset registry and encoding of the font, such as ‘iso8859-1’. The value should be a string or a symbol.

:script

The script that the font must support (a symbol).

: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: ‘ja’, ‘ko’, and ‘zh’.

:otf

The font must be an OpenType font that supports these OpenType features, provided Emacs is compiled with a library, such as ‘libotf’ on GNU/Linux, that supports complex text layout for scripts which need that. The value must be a list of the form

(script-tag langsys-tag gsub gpos)

where script-tag is the OpenType script tag symbol; langsys-tag is the OpenType language system tag symbol, or nil to use the default language system; gsub is a list of OpenType GSUB feature tag symbols, or nil if none is required; and gpos is a list of OpenType GPOS feature tag symbols, or nil if none is required. If gsub or gpos is a list, a nil element in that list means that the font must not match any of the remaining tag symbols. The gpos element may be omitted.

Function: font-put font-spec property value

Set the font property property in the font-spec font-spec to value.

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.

Function: find-font font-spec &optional frame

This function returns a font entity that best matches the font spec font-spec on frame frame. If frame is nil, it defaults to the selected frame.

Function: list-fonts font-spec &optional frame num prefer

This function returns a list of all font entities that match the font spec font-spec.

The optional argument frame, if non-nil, specifies the frame on which the fonts are to be displayed. The optional argument num, if non-nil, should be an integer that specifies the maximum length of the returned list. The optional argument prefer, if non-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.

If you call set-face-attribute and pass a font spec, font entity, or font name string as the value of the :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 :font attribute for that face.

The following functions can be used to obtain information about a font. For these functions, the font argument can be a font object, a font entity, or a font spec.

Function: font-get font property

This function returns the value of the font property property for font.

If font is a font spec and the font spec does not specify property, the return value is nil. If font is a font object or font entity, the value for the :script property may be a list of scripts supported by the font.

Function: font-face-attributes font &optional frame

This function returns a list of face attributes corresponding to font. The optional argument frame specifies the frame on which the font is to be displayed. If it is nil, the selected frame is used. The return value has the form

(:family family :height height :weight weight
   :slant slant :width width)

where the values of family, height, weight, slant, and width are face attribute values. Some of these key-attribute pairs may be omitted from the list if they are not specified by font.

Function: font-xlfd-name font &optional fold-wildcards

This function returns the XLFD (X Logical Font Descriptor), a string, matching font. See Fonts in 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 nil.

If the optional argument fold-wildcards is non-nil, consecutive wildcards in the XLFD are folded into one.

The following two functions return important information about a font.

Function: font-info name &optional frame

This function returns information about a font specified by its name, a string, as it is used on frame. If frame is omitted or nil, it defaults to the selected frame.

The value returned by the function is a vector of the form [opened-name full-name size height baseline-offset relative-compose default-ascent max-width ascent descent space-width average-width filename capability]. Here’s the description of each components of this vector:

opened-name

The name used to open the font, a string.

full-name

The full name of the font, a string.

size

The pixel size of the font.

height

The height of the font in pixels.

baseline-offset

The offset in pixels from the ASCII baseline, positive upward.

relative-compose
default-ascent

Numbers controlling how to compose characters.

ascent
descent

The ascent and descent of this font. The sum of these two numbers should be equal to the value of height above.

space-width

The width, in pixels, of the font’s space character.

average-width

The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.

filename

The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font’s file name.

capability

A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the GSUB and GPOS features supported by the font. Each of these elements is a list of the form ((script (langsys feature …) …) …), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

Function: query-font font-object

This function returns information about a font-object. (This is in contrast to font-info, which takes the font name, a string, as its argument.)

The value returned by the function is a vector of the form [name filename pixel-size max-width ascent descent space-width average-width capability]. Here’s the description of each components of this vector:

name

The font name, a string.

filename

The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font’s file name.

pixel-size

The pixel size of the font used to open the font.

max-width

The maximum advance width of the font.

ascent
descent

The ascent and descent of this font. The sum of these two numbers gives the font height.

space-width

The width, in pixels, of the font’s space character.

average-width

The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.

capability

A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the GSUB and GPOS features supported by the font. Each of these elements is a list of the form ((script (langsys feature …) …) …), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

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. See section Face Remapping.

Function: default-font-width

This function returns the average width in pixels of the font used by the current buffer’s default face.

Function: default-font-height

This function returns the height in pixels of the font used by the current buffer’s default face.

Function: window-font-width &optional window face

This function returns the average width in pixels for the font used by face in window. The specified window must be a live window. If nil or omitted, window defaults to the selected window, and face defaults to the default face in window.

Function: window-font-height &optional window face

This function returns the height in pixels for the font used by face in window. The specified window must be a live window. If nil or omitted, window defaults to the selected window, and face defaults to the default face in window.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13 Fringes

On graphical displays, Emacs draws fringes next to each window: thin vertical strips down the sides which can display bitmaps indicating truncation, continuation, horizontal scrolling, and so on.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.1 Fringe Size and Position

The following buffer-local variables control the position and width of fringes in windows showing that buffer.

Variable: fringes-outside-margins

The fringes normally appear between the display margins and the window text. If the value is non-nil, they appear outside the display margins. See section Displaying in the Margins.

Variable: left-fringe-width

This variable, if non-nil, specifies the width of the left fringe in pixels. A value of nil means to use the left fringe width from the window’s frame.

Variable: right-fringe-width

This variable, if non-nil, specifies the width of the right fringe in pixels. A value of nil means to use the right fringe width from the window’s frame.

Any buffer which does not specify values for these variables uses the values specified by the left-fringe and right-fringe frame parameters (@pxref{Layout Parameters}).

The above variables actually take effect via the function set-window-buffer (@pxref{Buffers and Windows}), which calls 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 set-window-buffer again in each affected window. You can also use set-window-fringes to control the fringe display in individual windows.

Function: set-window-fringes window left &optional right outside-margins

This function sets the fringe widths of window window. If window is nil, the selected window is used.

The argument left specifies the width in pixels of the left fringe, and likewise right for the right fringe. A value of nil for either one stands for the default width. If outside-margins is non-nil, that specifies that fringes should appear outside of the display margins.

Function: window-fringes &optional window

This function returns information about the fringes of a window window. If window is omitted or nil, the selected window is used. The value has the form (left-width right-width outside-margins).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.2 Fringe Indicators

Fringe indicators are tiny icons displayed in the window fringe to indicate truncated or continued lines, buffer boundaries, etc.

User Option: indicate-empty-lines

When this is non-nil, Emacs displays a special glyph in the fringe of each empty line at the end of the buffer, on graphical displays. See section Fringes. This variable is automatically buffer-local in every buffer.

User Option: indicate-buffer-boundaries

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:

nil

Don’t display any of these fringe icons.

left

Display the angle icons and arrows in the left fringe.

right

Display the angle icons and arrows in the right fringe.

any non-alist

Display the angle icons in the left fringe and don’t display the arrows.

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 (indicator . position). Here, indicator is one of top, bottom, up, down, and t (which covers all the icons not yet specified), while position is one of left, right and nil.

For example, ((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 ((top . left) (bottom . left)).

Variable: 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 (indicator . bitmaps), where indicator specifies a logical indicator type and bitmaps specifies the fringe bitmaps to use for that indicator.

Each indicator should be one of the following symbols:

truncation, continuation.

Used for truncation and continuation lines.

up, down, top, bottom, top-bottom

Used when indicate-buffer-boundaries is non-nil: up and down indicate a buffer boundary lying above or below the window edge; top and bottom indicate the topmost and bottommost buffer text line; and top-bottom indicates where there is just one line of text in the buffer.

empty-line

Used to indicate empty lines when indicate-empty-lines is non-nil.

overlay-arrow

Used for overlay arrows (see section The Overlay Arrow).

Each bitmaps value may be a list of symbols (left right [left1 right1]). The left and right symbols specify the bitmaps shown in the left and/or right fringe, for the specific indicator. left1 and right1 are specific to the bottom and top-bottom indicators, and are used to indicate that the last text line has no final newline. Alternatively, bitmaps may be a single symbol which is used in both left and right fringes.

See section Fringe Bitmaps, for a list of standard bitmap symbols and how to define your own. In addition, nil represents the empty bitmap (i.e., an indicator that is not shown).

When fringe-indicator-alist has a buffer-local value, and there is no bitmap defined for a logical indicator, or the bitmap is t, the corresponding value from the default value of fringe-indicator-alist is used.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.3 Fringe Cursors

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.

User Option: overflow-newline-into-fringe

If this is non-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.

Variable: 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 (cursor-type . bitmap), which means to use the fringe bitmap bitmap to display cursors of type cursor-type.

Each cursor-type should be one of box, hollow, bar, hbar, or hollow-small. The first four have the same meanings as in the cursor-type frame parameter (@pxref{Cursor Parameters}). The hollow-small type is used instead of hollow when the normal hollow-rectangle bitmap is too tall to fit on a specific display line.

Each bitmap should be a symbol specifying the fringe bitmap to be displayed for that logical cursor type. See section Fringe Bitmaps.

When 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 fringes-indicator-alist is used.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.4 Fringe Bitmaps

The 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. These symbols are referred to by the variable fringe-indicator-alist, which maps fringe indicators to bitmaps (see section Fringe Indicators), and the variable fringe-cursor-alist, which maps fringe cursors to bitmaps (see section Fringe Cursors).

Lisp programs can also directly display a bitmap in the left or right fringe, by using a display property for one of the characters appearing in the line (see section Other Display Specifications). Such a display specification has the form

(fringe bitmap [face])

fringe is either the symbol left-fringe or right-fringe. bitmap is a symbol identifying the bitmap to display. The optional face names a face whose foreground color is used to display the bitmap; this face is automatically merged with the fringe face.

Here is a list of the standard fringe bitmaps defined in Emacs, and how they are currently used in Emacs (via fringe-indicator-alist and fringe-cursor-alist):

left-arrow, right-arrow

Used to indicate truncated lines.

left-curly-arrow, right-curly-arrow

Used to indicate continued lines.

right-triangle, left-triangle

The former is used by overlay arrows. The latter is unused.

up-arrow, down-arrow, top-left-angle top-right-angle
bottom-left-angle, bottom-right-angle
top-right-angle, top-left-angle
left-bracket, right-bracket, top-right-angle, top-left-angle

Used to indicate buffer boundaries.

filled-rectangle, hollow-rectangle
filled-square, hollow-square
vertical-bar, horizontal-bar

Used for different types of fringe cursors.

empty-line, exclamation-mark, question-mark, exclamation-mark

Not used by core Emacs features.

The next subsection describes how to define your own fringe bitmaps.

Function: fringe-bitmaps-at-pos &optional pos window

This function returns the fringe bitmaps of the display line containing position pos in window window. The return value has the form (left right ov), where left is the symbol for the fringe bitmap in the left fringe (or nil if no bitmap), right is similar for the right fringe, and ov is non-nil if there is an overlay arrow in the left fringe.

The value is nil if pos is not visible in window. If window is nil, that stands for the selected window. If pos is nil, that stands for the value of point in window.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.5 Customizing Fringe Bitmaps

Function: define-fringe-bitmap bitmap bits &optional height width align

This function defines the symbol bitmap as a new fringe bitmap, or replaces an existing bitmap with that name.

The argument 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 bits. However, you can specify a different height with non-nil height. The width is normally 8, but you can specify a different width with non-nil width. The width must be an integer between 1 and 16.

The argument 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 top, center, or bottom.

The align argument may also be a list (align periodic) where align is interpreted as described above. If periodic is non-nil, it specifies that the rows in bits should be repeated enough times to reach the specified height.

Function: destroy-fringe-bitmap bitmap

This function destroy the fringe bitmap identified by bitmap. If bitmap identifies a standard fringe bitmap, it actually restores the standard definition of that bitmap, instead of eliminating it entirely.

Function: set-fringe-bitmap-face bitmap &optional face

This sets the face for the fringe bitmap bitmap to face. If face is nil, it selects the fringe face. The bitmap’s face controls the color to draw it in.

face is merged with the fringe face, so normally face should specify only the foreground color.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13.6 The Overlay Arrow

The 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 overlays (see section Overlays).

Variable: overlay-arrow-string

This variable holds the string to display to call attention to a particular line, or 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.

Variable: 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 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 overlay-arrow-position. However, it is usually cleaner to use overlay-arrow-variable-list to achieve this result.

You can do a similar job by creating an overlay with a before-string property. See section Overlay Properties.

You can define multiple overlay arrows via the variable overlay-arrow-variable-list.

Variable: 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 overlay-arrow-position has its normal meaning because it is on this list.

Each variable on this list can have properties overlay-arrow-string and 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 overlay-arrow-string or overlay-arrow fringe indicator is used.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.14 Scroll Bars

Normally the frame parameter 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 scroll-bar-width specifies how wide they are (nil meaning the default).

The frame parameter horizontal-scroll-bars controls whether the windows in the frame have horizontal scroll bars. The frame parameter scroll-bar-height specifies how high they are (nil meaning the default). @xref{Layout Parameters}.

Horizontal scroll bars are not available on all platforms. The function horizontal-scroll-bars-available-p which takes no argument returns non-nil if they are available on your system.

The following three functions take as argument a live frame which defaults to the selected one.

Function: frame-current-scroll-bars &optional frame

This function reports the scroll bar types for frame frame. The value is a cons cell (vertical-type . horizontal-type), where vertical-type is either left, right, or nil (which means no vertical scroll bar.) horizontal-type is either bottom or nil (which means no horizontal scroll bar).

Function: frame-scroll-bar-width &optional frame

This function returns the width of vertical scroll bars of frame in pixels.

Function: frame-scroll-bar-height &optional frame

This function returns the height of horizontal scroll bars of frame in pixels.

You can override the frame specific settings for individual windows by using the following function:

Function: 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 window.

width specifies the width of the vertical scroll bar in pixels (nil means use the width specified for the frame). vertical-type specifies whether to have a vertical scroll bar and, if so, where. The possible values are left, right, t, which means to use the frame’s default, and nil for no vertical scroll bar.

height specifies the height of the horizontal scroll bar in pixels (nil means use the height specified for the frame). horizontal-type specifies whether to have a horizontal scroll bar. The possible values are bottom, t, which means to use the frame’s default, and nil for no horizontal scroll bar.

If window is nil, the selected window is used.

The following four functions take as argument a live window which defaults to the selected one.

Function: window-scroll-bars &optional window

This function returns a list of the form (width columns vertical-type height lines horizontal-type).

The value width is the value that was specified for the width of the vertical scroll bar (which may be nil); columns is the (possibly rounded) number of columns that the vertical scroll bar actually occupies.

The value height is the value that was specified for the height of the horizontal scroll bar (which may be nil); lines is the (possibly rounded) number of lines that the horizontally scroll bar actually occupies.

Function: window-current-scroll-bars &optional window

This function reports the scroll bar type for window window. The value is a cons cell (vertical-type . horizontal-type). Unlike window-scroll-bars, this reports the scroll bar type actually used, once frame defaults and scroll-bar-mode are taken into account.

Function: window-scroll-bar-width &optional window

This function returns the width in pixels of window’s vertical scrollbar.

Function: window-scroll-bar-height &optional window

This function returns the height in pixels of window’s horizontal scrollbar.

If you don’t specify these values for a window with set-window-scroll-bars, the buffer-local variables vertical-scroll-bar, horizontal-scroll-bar, scroll-bar-width and scroll-bar-height in the buffer being displayed control the window’s scroll bars. The function 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 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.

Variable: vertical-scroll-bar

This variable specifies the location of the vertical scroll bar. The possible values are left, right, t, which means to use the frame’s default, and nil for no scroll bar.

Variable: horizontal-scroll-bar

This variable specifies the location of the horizontal scroll bar. The possible values are bottom, t, which means to use the frame’s default, and nil for no scroll bar.

Variable: scroll-bar-width

This variable specifies the width of the buffer’s vertical scroll bars, measured in pixels. A value of nil means to use the value specified by the frame.

Variable: scroll-bar-height

This variable specifies the height of the buffer’s horizontal scroll bar, measured in pixels. A value of nil means to use the value specified by the frame.

Finally you can toggle the display of scroll bars on all frames by customizing the variables scroll-bar-mode and horizontal-scroll-bar-mode.

User Option: scroll-bar-mode

This variable controls whether and where to put vertical scroll bars in all frames. The possible values are nil for no scroll bars, left to put scroll bars on the left and right to put scroll bars on the right.

User Option: horizontal-scroll-bar-mode

This variable controls whether to display horizontal scroll bars on all frames.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.15 Window 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 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 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:

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.

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 window-divider face.

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 window-divider face.

You can get the sizes of the dividers of a specific window with the following two functions.

Function: window-right-divider-width &optional window

Return the width (thickness) in pixels of window’s right divider. window must be a live window and defaults to the selected one. The return value is always zero for a rightmost window.

Function: window-bottom-divider-width &optional window

Return the width (thickness) in pixels of window’s bottom divider. 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16 The display Property

The 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 display property should be a display specification, or a list or vector containing several display specifications. Display specifications in the same 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 display property, only one of the values takes effect, following the rules of get-char-property. @xref{Examining Properties}.

The rest of this section describes several kinds of display specifications and what they mean.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16.1 Display Specs That Replace The Text

Some kinds of display specifications specify something to display instead of the text that has the property. These are called 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, the text that has the property means all the consecutive characters that have the same Lisp object as their display property; these characters are replaced as a single unit. If two characters have different Lisp objects as their display properties (i.e., objects which are not 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 (see section Other Display Specifications). Consider the following function:

(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))))

This function gives each of the first ten characters in the buffer a display property which is a string "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 ‘A’; the fact that the display property was assigned in two separate calls to put-text-property is irrelevant. Similarly, the next two characters get a second string (concat creates a new string object), so they are replaced with one ‘A’; and so on. Thus, the ten characters appear as five A’s.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16.2 Specified Spaces

To display a space of specified width and/or height, use a display specification of the form (space . props), where 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 all of those characters. These are the properties you can use in props to specify the weight of the space:

:width width

If width is a number, it specifies that the space width should be width times the normal character width. width can also be a pixel width specification (see section Pixel Specification for Spaces).

:relative-width 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 display property. The space width is the pixel width of that character, multiplied by 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.)

:align-to hpos

Specifies that the space should be wide enough to reach hpos. If hpos is a number, it is measured in units of the normal character width. hpos can also be a pixel width specification (see section Pixel Specification for Spaces).

You should use one and only one of the above properties. You can also specify the height of the space, with these properties:

:height height

Specifies the height of the space. If height is a number, it specifies that the space height should be height times the normal character height. The height may also be a pixel height specification (see section Pixel Specification for Spaces).

:relative-height factor

Specifies the height of the space, multiplying the ordinary height of the text having this display specification by factor.

:ascent ascent

If the value of ascent is a non-negative number no greater than 100, it specifies that 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 pixel ascent specification (see section Pixel Specification for Spaces).

Don’t use both :height and :relative-height together.

The :width and :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. See section Bidirectional Display, for the details.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16.3 Pixel Specification for Spaces

The value of the :width, :align-to, :height, and :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:

  expr ::= num | (num) | unit | elem | pos | image | form
  num  ::= integer | float | symbol
  unit ::= in | mm | cm | width | height
  elem ::= left-fringe | right-fringe | left-margin | right-margin
        |  scroll-bar | text
  pos  ::= left | center | right
  form ::= (num . expr) | (op expr ...)
  op   ::= + | -

The form num specifies a fraction of the default frame font height or width. The form (num) specifies an absolute number of pixels. If num is a symbol, symbol, its buffer-local variable binding is used.

The in, mm, and cm units specify the number of pixels per inch, millimeter, and centimeter, respectively. The width and height units correspond to the default width and height of the current face. An image specification image corresponds to the width or height of the image.

The elements left-fringe, right-fringe, left-margin, right-margin, scroll-bar, and text specify to the width of the corresponding area of the window.

The left, center, and right positions can be used with :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 text) can also be used with :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

:align-to (+ left-margin (0.5 . left-margin))

If no specific base offset is set for alignment, it is always relative to the left edge of the text area. For example, ‘:align-to 0’ in a header-line aligns with the first text column in the text area.

A value of the form (num . expr) stands for the product of the values of num and expr. For example, (2 . in) specifies a width of 2 inches, while (0.5 . image) specifies half the width (or height) of the specified image.

The form (+ expr ...) adds up the value of the expressions. The form (- expr ...) negates or subtracts the value of the expressions.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16.4 Other Display Specifications

Here are the other sorts of display specifications that you can use in the display text property.

string

Display string instead of the text that has this property.

Recursive display specifications are not supported—string’s display properties, if any, are not used.

(image . image-props)

This kind of display specification is an image descriptor (see section Images). When used as a display specification, it means to display the image instead of the text that has the display specification.

(slice x y width height)

This specification together with image specifies a slice (a partial area) of the image to display. The elements y and x specify the top left corner of the slice, within the image; width and 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.

((margin nil) string)

A display specification of this form means to display string instead of the text that has the display specification, at the same position as that text. It is equivalent to using just string, but it is done as a special case of marginal display (see section Displaying in the Margins).

(left-fringe bitmap [face])
(right-fringe bitmap [face])

This display specification on any character of a line of text causes the specified bitmap be displayed in the left or right fringes for that line, instead of the characters that have the display specification. The optional face specifies the colors to be used for the bitmap. See section Fringe Bitmaps, for the details.

(space-width factor)

This display specification affects all the space characters within the text that has the specification. It displays all of these spaces factor times as wide as normal. The element 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.

(height height)

This display specification makes the text taller or shorter. Here are the possibilities for height:

(+ n)

This means to use a font that is n steps larger. A 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. n should be an integer.

(- n)

This means to use a font that is n steps smaller.

a number, factor

A number, factor, means to use a font that is factor times as tall as the default font.

a symbol, 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.

anything else, form

If the height value doesn’t fit the previous possibilities, it is a form. Emacs evaluates it to get the new height, with the symbol height bound to the current specified font height.

(raise factor)

This kind of display specification raises or lowers the text it applies to, relative to the baseline of the line. It is mainly meant to support display of subscripts and superscripts.

The 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.

Note that if the text also has a height display specification, which was specified before (i.e. to the left of) raise, the latter will affect the amount of raising or lowering in pixels, because that is based on the height of the text being raised. Therefore, if you want to display a sub- or superscript that is smaller than the normal text height, consider specifying raise before height.

You can make any display specification conditional. To do that, package it in another list of the form (when condition . spec). Then the specification spec applies only when condition evaluates to a non-nil value. During the evaluation, object is bound to the string or buffer having the conditional display property. position and buffer-position are bound to the position within object and the buffer position where the display property was found, respectively. Both positions can be different when object is a string.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16.5 Displaying in the Margins

A buffer can have blank areas called 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 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 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 ((margin right-margin) spec) or ((margin left-margin) spec). Here, 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 in association with certain buffer text, without altering or preventing the display of that text, put a 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:

Variable: 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 nil means no left marginal area.

Variable: 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 nil means no right marginal area.

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 set-window-buffer.

You can also set the margin widths immediately.

Function: set-window-margins window left &optional right

This function specifies the margin widths for window window, in character cell units. The argument left controls the left margin, and right controls the right margin (default 0).

Function: window-margins &optional window

This function returns the width of the left and right margins of window as a cons cell of the form (left . right). If one of the two marginal areas does not exist, its width is returned as nil; if neither of the two margins exist, the function returns (nil). If window is nil, the selected window is used.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17 Images

To display an image in an Emacs buffer, you must first create an image descriptor, then use it as a display specifier in the display property of text that is displayed (see section The 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 display-images-p to determine if images can in principle be displayed (@pxref{Display Feature Testing}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.1 Image Formats

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 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 (libXpm), GIF (libgif or libungif), PostScript (gs), JPEG (libjpeg), TIFF (libtiff), PNG (libpng), and SVG (librsvg).

Each of these image formats is associated with an image type symbol. The symbols for the above formats are, respectively, pbm, xbm, xpm, gif, postscript, jpeg, tiff, png, and svg.

Furthermore, if you build Emacs with ImageMagick (libMagickWand) support, Emacs can display any image format that ImageMagick can. See section ImageMagick Images. All images displayed via ImageMagick have type symbol imagemagick.

Variable: 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 image-type-available-p.

Function: image-type-available-p type

This function returns non-nil if images of type type can be loaded and displayed. type must be an image type symbol.

For image types whose support libraries are statically linked, this function always returns t. For image types whose support libraries are dynamically loaded, it returns t if the library could be loaded and nil otherwise.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.2 Image Descriptors

An 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 display overlay or text property (see section Other Display Specifications); but See section Showing Images, for convenient helper functions to insert images into buffers.

Each image descriptor has the form (image . props), where props is a property list of alternating keyword symbols and values, including at least the pair :type 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):

:type type

The image type. See section Image Formats. Every image descriptor must include this property.

:file file

This says to load the image from file file. If file is not an absolute file name, it is expanded in data-directory.

:data data

This specifies the raw image data. Each image descriptor must have either :data or :file, but not both.

For most image types, the value of a :data property should be a string containing the image data. Some image types do not support :data; for some others, :data alone is not enough, so you need to use other image properties along with :data. See the following subsections for details.

:margin margin

This specifies how many pixels to add as an extra margin around the image. The value, margin, must be a non-negative number, or a pair (x . y) of such numbers. If it is a pair, x specifies how many pixels to add horizontally, and y specifies how many pixels to add vertically. If :margin is not specified, the default is zero.

:ascent ascent

This specifies the amount of the image’s height to use for its ascent—that is, the part above the baseline. The value, ascent, must be a number in the range 0 to 100, or the symbol center.

If ascent is a number, that percentage of the image’s height is used for its ascent.

If ascent is 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.

:relief relief

This adds a shadow rectangle around the image. The value, relief, specifies the width of the shadow lines, in pixels. If relief is negative, shadows are drawn so that the image appears as a pressed button; otherwise, it appears as an unpressed button.

:conversion algorithm

This specifies a conversion algorithm that should be applied to the image before it is displayed; the value, algorithm, specifies which algorithm.

laplace
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.

(edge-detection :matrix matrix :color-adjust adjust)

Specifies a general edge-detection algorithm. matrix must be either a nine-element list or a nine-element vector of numbers. A pixel at position x/y in the transformed image is computed from original pixels around that position. matrix specifies, for each pixel in the neighborhood of x/y, a factor with which that pixel will influence the transformed pixel; element 0 specifies the factor for the pixel at x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as shown below:

  (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)

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

  (1  0  0
   0  0  0
   0  0 -1)

Emboss edge-detection uses a matrix of

  ( 2 -1  0
   -1  0  1
    0  1 -2)
disabled

Specifies transforming the image so that it looks disabled.

:mask mask

If mask is heuristic or (heuristic bg), build a clipping mask for the image, so that the background of a frame is visible behind the image. If bg is not specified, or if bg is 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, bg must be a list (red green blue) specifying the color to assume for the background of the image.

If mask is nil, remove a mask from the image, if it has one. Images in some formats include a mask which can be removed by specifying :mask nil.

:pointer shape

This specifies the pointer shape when the mouse pointer is over this image. @xref{Pointer Shape}, for available pointer shapes.

:map map

This associates an image map of hot spots with this image.

An image map is an alist where each element has the format (area id plist). An area is specified as either a rectangle, a circle, or a polygon.

A rectangle is a cons (rect . ((x0 . y0) . (x1 . y1))) which specifies the pixel coordinates of the upper left and bottom right corners of the rectangle area.

A circle is a cons (circle . ((x0 . y0) . r)) which specifies the center and the radius of the circle; r may be a float or integer.

A polygon is a cons (poly . [x0 y0 x1 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 plist of that hot-spot is consulted; if it contains a help-echo property, that defines a tool-tip for the hot-spot, and if it contains a 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 id of the hot-spot with the mouse event; for instance, [area4 mouse-1] if the hot-spot’s id is area4.

Function: image-mask-p spec &optional frame

This function returns t if image spec has a mask bitmap. frame is the frame on which the image will be displayed. frame nil or omitted means to use the selected frame (@pxref{Input Focus}).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.3 XBM Images

To use XBM format, specify 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 xbm image type are:

:foreground foreground

The value, foreground, should be a string specifying the image foreground color, or 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.

:background background

The value, background, should be a string specifying the image background color, or 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.

If you specify an XBM image using data within Emacs instead of an external file, use the following three properties:

:data data

The value, data, specifies the contents of the image. There are three formats you can use for data:

:width width

The value, width, specifies the width of the image, in pixels.

:height height

The value, height, specifies the height of the image, in pixels.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.4 XPM Images

To use XPM format, specify xpm as the image type. The additional image property :color-symbols is also meaningful with the xpm image type:

:color-symbols symbols

The value, symbols, should be an alist whose elements have the form (name . color). In each element, name is the name of a color as it appears in the image file, and color specifies the actual color to use for displaying that name.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.5 PostScript Images

To use PostScript for an image, specify image type postscript. This works only if you have Ghostscript installed. You must always use these three properties:

:pt-width width

The value, width, specifies the width of the image measured in points (1/72 inch). width must be an integer.

:pt-height height

The value, height, specifies the height of the image in points (1/72 inch). height must be an integer.

:bounding-box box

The value, box, must be a list or vector of four integers, which specifying the bounding box of the PostScript image, analogous to the ‘BoundingBox’ comment found in PostScript files.

%%BoundingBox: 22 171 567 738

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.6 ImageMagick Images

If you build Emacs with ImageMagick support, you can use the ImageMagick library to load many image formats (see File Conveniences in The GNU Emacs Manual). The image type symbol for images loaded via ImageMagick is imagemagick, regardless of the actual underlying image format.

To check for ImageMagick support, use the following:

(image-type-available-p 'imagemagick)
Function: 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 BMP for ‘.bmp’ images.

User Option: 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 imagemagick-types, or an equivalent string. Alternatively, a value of t enables ImageMagick for all possible image types. Regardless of the value of this variable, imagemagick-types-inhibit (see below) takes precedence.

User Option: 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 imagemagick-enabled-types. A value of t disables ImageMagick entirely.

Variable: image-format-suffixes

This variable is an alist mapping image types to file name extensions. Emacs uses this in conjunction with the :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 (type extension), where type is a symbol specifying an image content-type, and extension is a string that specifies the associated file name extension.

Images loaded with ImageMagick support the following additional image descriptor properties:

:background background

background, if non-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 nil, it defaults to the frame’s background color.

:width width, :height height

The :width and :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.

:max-width max-width, :max-height max-height

The :max-width and :max-height keywords are used for scaling if the size of the image of the image exceeds these values. If :width is set it will have precedence over max-width, and if :height is set it will have precedence over max-height, but you can otherwise mix these keywords as you wish. :max-width and :max-height will always preserve the aspect ratio.

:format type

The value, type, should be a symbol specifying the type of the image data, as found in 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.

:rotation angle

Specifies a rotation angle in degrees.

:index frame

See section Multi-Frame Images.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.7 Other Image Types

For PBM images, specify image type pbm. Color, gray-scale and monochromatic images are supported. For mono PBM images, two additional image properties are supported.

:foreground foreground

The value, foreground, should be a string specifying the image foreground color, or 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.

:background background

The value, background, should be a string specifying the image background color, or 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.

The remaining image types that Emacs can support are:

GIF

Image type gif. Supports the :index property. See section Multi-Frame Images.

JPEG

Image type jpeg.

PNG

Image type png.

SVG

Image type svg.

TIFF

Image type tiff. Supports the :index property. See section Multi-Frame Images.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.8 Defining Images

The functions create-image, defimage and find-image provide convenient ways to create image descriptors.

Function: create-image file-or-data &optional type data-p &rest props

This function creates and returns an image descriptor which uses the data in file-or-data. file-or-data can be a file name or a string containing the image data; data-p should be nil for the former case, non-nil for the latter case.

The optional argument type is a symbol specifying the image type. If type is omitted or nil, 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, props, specify additional image properties—for example,

(create-image "foo.xpm" 'xpm nil :heuristic-mask t)

The function returns nil if images of this type are not supported. Otherwise it returns an image descriptor.

Macro: defimage symbol specs &optional doc

This macro defines symbol as an image name. The arguments specs is a list which specifies how to display the image. The third argument, doc, is an optional documentation string.

Each argument in specs has the form of a property list, and each one should specify at least the :type property and either the :file or the :data property. The value of :type should be a symbol specifying the image type, the value of :file is the file to load the image from, and the value of :data is a string containing the actual image data. Here is an example:

(defimage test-image
  ((:type xpm :file "~/test1.xpm")
   (:type xbm :file "~/test1.xbm")))

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 symbol.

If none of the alternatives will work, then symbol is defined as nil.

Function: find-image specs

This function provides a convenient way to find an image satisfying one of a list of image specifications specs.

Each specification in specs is a property list with contents depending on image type. All specifications must at least contain the properties :type type and either :file file or :data data, where type is a symbol specifying the image type, e.g., xbm, file is the file to load the image from, and data is a string containing the actual image data. The first specification in the list whose type is supported, and file exists, is used to construct the image specification to be returned. If no specification is satisfied, nil is returned.

The image is looked for in image-load-path.

User Option: 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 ‘images’ subdirectory of the directory specified by data-directory, then the directory specified by data-directory, and finally in the directories in 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 ‘images/foo/bar.xpm’ within data-directory, you should specify the image as follows:

(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
Function: 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 library.

The function searches for image first using image-load-path, excluding ‘data-directory/images’, and then in load-path, followed by a path suitable for library, which includes ‘../../etc/images’ and ‘../etc/images’ relative to the library file itself, and finally in ‘data-directory/images’.

Then this function returns a list of directories which contains first the directory in which image was found, followed by the value of load-path. If path is given, it is used instead of load-path.

If no-error is non-nil and a suitable path can’t be found, don’t signal an error. Instead, return a list of directories as before, except that nil appears in place of the image directory.

Here is an example of using image-load-path-for-library:

(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))

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.9 Showing Images

You can use an image descriptor by setting up the display property yourself, but it is easier to use the functions in this section.

Function: insert-image image &optional string area slice

This function inserts image in the current buffer at point. The value image should be an image descriptor; it could be a value returned by create-image, or the value of a symbol defined with defimage. The argument string specifies the text to put in the buffer to hold the image. If it is omitted or nil, insert-image uses " " by default.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer’s text.

The argument slice specifies a slice of the image to insert. If slice is nil or omitted the whole image is inserted. Otherwise, slice is a list (x y width height) which specifies the x and y positions and width and 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 string in the buffer, and gives it a display property which specifies image. See section The display Property.

Function: insert-sliced-image image &optional string area rows cols

This function inserts image in the current buffer at point, like insert-image, but splits the image into rowsxcols 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.

Function: put-image image pos &optional string area

This function puts image image in front of pos in the current buffer. The argument pos should be an integer or a marker. It specifies the buffer position where the image should appear. The argument string specifies the text that should hold the image as an alternative to the default.

The argument image must be an image descriptor, perhaps returned by create-image or stored by defimage.

The argument area specifies whether to put the image in a margin. If it is left-margin, the image appears in the left margin; right-margin specifies the right margin. If area is nil or omitted, the image is displayed at point within the buffer’s text.

Internally, this function creates an overlay, and gives it a before-string property containing text that has a display property whose value is the image. (Whew!)

Function: remove-images start end &optional buffer

This function removes images in buffer between positions start and end. If buffer is omitted or nil, images are removed from the current buffer.

This removes only images that were put into buffer the way put-image does it, not images that were inserted with insert-image or in other ways.

Function: image-size spec &optional pixels frame

This function returns the size of an image as a pair (width . height). spec is an image specification. pixels non-nil means return sizes measured in pixels, otherwise return sizes measured in the default character size of frame (@pxref{Frame Font}). frame is the frame on which the image will be displayed. frame null or omitted means use the selected frame (@pxref{Input Focus}).

Variable: 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 max-image-size is subsequently changed (see section Image Cache).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.10 Multi-Frame Images

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 :index, whose value is an integer (counting from 0) that specifies which frame is being displayed.

Function: image-multi-frame-p image

This function returns non-nil if image contains more than one frame. The actual return value is a cons (nimages . delay), where nimages is the number of frames and delay is the delay in seconds between them, or 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.

Function: image-current-frame image

This function returns the index of the current frame number for image, counting from 0.

Function: image-show-frame image n &optional nocheck

This function switches image to frame number n. It replaces a frame number outside the valid range with that of the end of the range, unless nocheck is non-nil. If image does not contain a frame with the specified number, the image displays as a hollow box.

Function: image-animate image &optional index limit

This function animates image. The optional integer index specifies the frame from which to start (default 0). The optional argument limit controls the length of the animation. If omitted or nil, the image animates once only; if t it loops forever; if a number animation stops after that many seconds.

Animation operates by means of a timer. Note that Emacs imposes a minimum frame delay of 0.01 (image-minimum-frame-delay) seconds. If the image itself does not specify a delay, Emacs uses image-default-frame-delay.

Function: image-animate-timer image

This function returns the timer responsible for animating image, if there is one.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17.11 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 equal to the desired specification. If a match is found, the image is displayed from the cache. Otherwise, Emacs loads the image normally.

Function: image-flush spec &optional frame

This function removes the image with specification spec from the image cache of frame frame. Image specifications are compared using equal. If frame is nil, it defaults to the selected frame. If frame is 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.

One use for image-flush is to tell Emacs about a change in an image file. If an image specification contains a :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 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 image-flush is for memory conservation. If your Lisp program creates a large number of temporary images over a period much shorter than image-cache-eviction-delay (see below), you can opt to flush unused images yourself, instead of waiting for Emacs to do it automatically.

Function: clear-image-cache &optional filter

This function clears an image cache, removing all the images stored in it. If filter is omitted or nil, it clears the cache for the selected frame. If filter is a frame, it clears the cache for that frame. If filter is t, all image caches are cleared. Otherwise, filter is taken to be a file name, and all images associated with that file name are removed from all image caches.

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.

Variable: 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 nil, Emacs does not remove images from the cache except when you explicitly clear it. This mode can be useful for debugging.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.18 Embedded Native Widgets

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 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 display text or overlay property (see section The display Property).

Function: make-xwidget type title width height arguments &optional buffer

This creates and returns an xwidget object. If buffer is omitted or nil, it defaults to the current buffer. If buffer names a buffer that doesn’t exist, it will be created. The type identifies the type of the xwidget component, it can be one of the following:

webkit

The WebKit component.

The width and height arguments specify the widget size in pixels, and title, a string, specifies its title.

Function: xwidgetp object

This function returns t if object is an xwidget, nil otherwise.

Function: xwidget-plist xwidget

This function returns the property list of xwidget.

Function: set-xwidget-plist xwidget plist

This function replaces the property list of xwidget with a new property list given by plist.

Function: xwidget-buffer xwidget

This function returns the buffer of xwidget.

Function: get-buffer-xwidgets buffer

This function returns a list of xwidget objects associated with the buffer, which can be specified as a buffer object or a name of an existing buffer, a string. The value is nil if buffer contains no xwidgets.

Function: xwidget-webkit-goto-uri xwidget uri

This function browses the specified uri in the given xwidget. The uri is a string that specifies the name of a file or a URL.

Function: xwidget-webkit-execute-script xwidget script

This function causes the browser widget specified by xwidget to execute the specified JavaScript script.

Function: xwidget-webkit-execute-script-rv xwidget script &optional default

This function executes the specified script like xwidget-webkit-execute-script does, but it also returns the script’s return value as a string. If script doesn’t return a value, this function returns default, or nil if default was omitted.

Function: xwidget-webkit-get-title xwidget

This function returns the title of xwidget as a string.

Function: xwidget-resize xwidget width height

This function resizes the specified xwidget to the size widthxheight pixels.

Function: xwidget-size-request xwidget

This function returns the desired size of xwidget as a list of the form (width height). The dimensions are in pixels.

Function: xwidget-info xwidget

This function returns the attributes of xwidget as a vector of the form [type title width height]. The attributes are usually determined by make-xwidget when the xwidget is created.

Function: 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 xwidget associated with it. If flag is non-nil, Emacs will query the user, otherwise it will not.

Function: xwidget-query-on-exit-flag xwidget

This function returns the current setting of xwidgets query-on-exit flag, either t or nil.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19 Buttons

The Button package defines functions for inserting and manipulating 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 button properties. One of these properties, the 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. See Introduction in 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19.1 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:

action

The function to call when the user invokes the button, which is passed the single argument button. By default this is ignore, which does nothing.

mouse-action

This is similar to action, and when present, will be used instead of action for button invocations resulting from mouse-clicks (instead of the user hitting <RET>). If not present, mouse-clicks use action instead.

face

This is an Emacs face controlling how buttons of this type are displayed; by default this is the button face.

mouse-face

This is an additional face which controls appearance during mouse-overs (merged with the usual button face); by default this is the usual Emacs highlight face.

keymap

The button’s keymap, defining bindings active within the button region. By default this is the usual button region keymap, stored in the variable button-map, which defines <RET> and <mouse-2> to invoke the button.

type

The button type. See section Button Types.

help-echo

A string displayed by the Emacs tool-tip help system; by default, "mouse-2, RET: Push this button".

follow-link

The follow-link property, defining how a <mouse-1> click behaves on this button, @xref{Clickable Text}.

button

All buttons have a non-nil button property, which may be useful in finding regions of text that comprise buttons (which is what the standard button functions do).

There are other properties defined for the regions of text in a button, but these are not generally interesting for typical uses.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19.2 Button Types

Every button has a 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.

Function: define-button-type name &rest properties

Define a button type called name (a symbol). The remaining arguments form a sequence of property value pairs, specifying default property values for buttons with this type (a button’s type may be set by giving it a type property when creating the button, using the :type keyword argument).

In addition, the keyword argument :supertype may be used to specify a button-type from which name inherits its default property values. Note that this inheritance happens only when name is defined; subsequent changes to a supertype are not reflected in its subtypes.

Using define-button-type to define default properties for buttons is not necessary—buttons without any specified type use the built-in button-type button—but it is encouraged, since doing so usually makes the resulting code clearer and more efficient.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19.3 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 button). Like all Emacs text, the appearance of the button is governed by the face property; by default (via the face property inherited from the 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 make-...button, and those that also insert the button text, called insert-...button.

The button-creation functions all take the &rest argument properties, which should be a sequence of property value pairs, specifying properties to add to the button; see Button Properties. In addition, the keyword argument :type may be used to specify a button-type from which to inherit other properties; see 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 (see section Overlays) to hold the button properties:

Function: make-button beg end &rest properties

This makes a button from beg to end in the current buffer, and returns it.

Function: insert-button label &rest properties

This insert a button with the label label at point, and returns it.

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.

Function: make-text-button beg end &rest properties

This makes a button from beg to end in the current buffer, using text properties.

Function: insert-text-button label &rest properties

This inserts a button with the label label at point, using text properties.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19.4 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 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.

Function: button-start button

Return the position at which button starts.

Function: button-end button

Return the position at which button ends.

Function: button-get button prop

Get the property of button button named prop.

Function: button-put button prop val

Set button’s prop property to val.

Function: button-activate button &optional use-mouse-action

Call button’s action property (i.e., invoke the function that is the value of that property, passing it the single argument button). If use-mouse-action is non-nil, try to invoke the button’s mouse-action property instead of action; if the button has no mouse-action property, use action as normal.

Function: button-label button

Return button’s text label.

Function: button-type button

Return button’s button-type.

Function: button-has-type-p button type

Return t if button has button-type type, or one of type’s subtypes.

Function: button-at pos

Return the button at position pos in the current buffer, or nil. If the button at pos is a text property button, the return value is a marker pointing to pos.

Function: button-type-put type prop val

Set the button-type type’s prop property to val.

Function: button-type-get type prop

Get the property of button-type type named prop.

Function: button-type-subtype-p type supertype

Return t if button-type type is a subtype of supertype.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.19.5 Button Buffer Commands

These are commands and functions for locating and operating on buttons in an Emacs buffer.

push-button is the command that a user uses to actually push a button, and is bound by default in the button itself to <RET> and to <mouse-2> using a local keymap in the button’s overlay or text properties. Commands that are useful outside the buttons itself, such as forward-button and backward-button are additionally available in the keymap stored in button-buffer-map; a mode which uses buttons may want to use button-buffer-map as a parent keymap for its keymap.

If the button has a non-nil follow-link property, and mouse-1-click-follows-link is set, a quick <mouse-1> click will also activate the push-button command. @xref{Clickable Text}.

Command: push-button &optional pos use-mouse-action

Perform the action specified by a button at location pos. pos may be either a buffer position or a mouse-event. If use-mouse-action is non-nil, or pos is a mouse-event (@pxref{Mouse Events}), try to invoke the button’s mouse-action property instead of action; if the button has no mouse-action property, use action as normal. pos defaults to point, except when 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 pos, do nothing and return nil, otherwise return t.

Command: forward-button n &optional wrap display-message

Move to the nth next button, or nth previous button if n is negative. If n is zero, move to the start of any button at point. If wrap is non-nil, moving past either end of the buffer continues from the other end. If display-message is non-nil, the button’s help-echo string is displayed. Any button with a non-nil skip property is skipped over. Returns the button found.

Command: backward-button n &optional wrap display-message

Move to the nth previous button, or nth next button if n is negative. If n is zero, move to the start of any button at point. If wrap is non-nil, moving past either end of the buffer continues from the other end. If display-message is non-nil, the button’s help-echo string is displayed. Any button with a non-nil skip property is skipped over. Returns the button found.

Function: next-button pos &optional count-current
Function: previous-button pos &optional count-current

Return the next button after (for next-button) or before (for previous-button) position pos in the current buffer. If count-current is non-nil, count any button at pos in the search, instead of starting at the next button.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.20 Abstract Display

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 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 header text; next, textual descriptions of a series of data elements (Lisp objects that you specify); and last, fixed footer text. Specifically, an ewoc contains information on:

Typically, you define an ewoc with 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. See section Abstract Display Functions.

A node 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:

(ewoc-data node)
⇒ value

(ewoc-set-data node new-value)
⇒ new-value

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 (see section 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 ewoc-refresh, or just specific nodes using ewoc-invalidate, or all nodes satisfying a predicate using ewoc-map. Alternatively, you can delete invalid nodes using ewoc-delete or ewoc-filter, and add new nodes in their place. Deleting a node from an ewoc deletes its associated textual description from buffer, as well.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.20.1 Abstract Display Functions

In this subsection, ewoc and node stand for the structures described above (see section Abstract Display), while data stands for an arbitrary Lisp object used as a data element.

Function: ewoc-create pretty-printer &optional header footer nosep

This constructs and returns a new ewoc, with no nodes (and thus no data elements). 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 insert (and never 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 nosep is non-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 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 ewoc-create.

Function: ewoc-buffer ewoc

This returns the buffer where ewoc maintains its text.

Function: ewoc-get-hf ewoc

This returns a cons cell (header . footer) made from ewoc’s header and footer.

Function: ewoc-set-hf ewoc header footer

This sets the header and footer of ewoc to the strings header and footer, respectively.

Function: ewoc-enter-first ewoc data
Function: ewoc-enter-last ewoc data

These add a new node encapsulating data, putting it, respectively, at the beginning or end of ewoc’s chain of nodes.

Function: ewoc-enter-before ewoc node data
Function: ewoc-enter-after ewoc node data

These add a new node encapsulating data, adding it to ewoc before or after node, respectively.

Function: ewoc-prev ewoc node
Function: ewoc-next ewoc node

These return, respectively, the previous node and the next node of node in ewoc.

Function: ewoc-nth ewoc n

This returns the node in ewoc found at zero-based index n. A negative n means count from the end. ewoc-nth returns nil if n is out of range.

Function: ewoc-data node

This extracts the data encapsulated by node and returns it.

Function: ewoc-set-data node data

This sets the data encapsulated by node to data.

Function: ewoc-locate ewoc &optional pos guess

This determines the node in ewoc which contains point (or pos if specified), and returns that node. If ewoc has no nodes, it returns nil. If pos is before the first node, it returns the first node; if pos is after the last node, it returns the last node. The optional third arg guess should be a node that is likely to be near pos; this doesn’t alter the result, but makes the function run faster.

Function: ewoc-location node

This returns the start position of node.

Function: ewoc-goto-prev ewoc arg
Function: ewoc-goto-next ewoc arg

These move point to the previous or next, respectively, argth node in ewoc. ewoc-goto-prev does not move if it is already at the first node or if ewoc is empty, whereas ewoc-goto-next moves past the last node, returning nil. Excepting this special case, these functions return the node moved to.

Function: ewoc-goto-node ewoc node

This moves point to the start of node in ewoc.

Function: ewoc-refresh ewoc

This function regenerates the text of 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.

Function: ewoc-invalidate ewoc &rest nodes

This is similar to ewoc-refresh, except that only nodes in ewoc are updated instead of the entire set.

Function: ewoc-delete ewoc &rest nodes

This deletes each node in nodes from ewoc.

Function: ewoc-filter ewoc predicate &rest args

This calls predicate for each data element in ewoc and deletes those nodes for which predicate returns nil. Any args are passed to predicate.

Function: ewoc-collect ewoc predicate &rest args

This calls predicate for each data element in ewoc and returns a list of those elements for which predicate returns non-nil. The elements in the list are ordered as in the buffer. Any args are passed to predicate.

Function: ewoc-map map-function ewoc &rest args

This calls map-function for each data element in ewoc and updates those nodes for which map-function returns non-nil. Any args are passed to map-function.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.20.2 Abstract Display Example

Here is a simple example using functions of the ewoc package to implement a 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.

(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)))

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 colorcomp-data and to finish the selection process, and a keymap to tie it all together conveniently.

(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))

Note that we never modify the data in each node, which is fixed when the ewoc is created to be either nil or an index into the vector colorcomp-data, the actual color components.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.21 Blinking Parentheses

This section describes the mechanism by which Emacs shows a matching open parenthesis when the user inserts a close parenthesis.

Variable: 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 blink-paren-function may be nil, in which case nothing is done.

User Option: blink-matching-paren

If this variable is nil, then blink-matching-open does nothing.

User Option: blink-matching-paren-distance

This variable specifies the maximum distance to scan for a matching parenthesis before giving up.

User Option: 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.

Command: blink-matching-open

This function is the default value of 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 blink-matching-paren-distance characters.

Here is an example of calling this function explicitly.

(defun interactive-blink-matching-open ()
  "Indicate momentarily the start of parenthesized sexp before point."
  (interactive)
  (let ((blink-matching-paren-distance
         (buffer-size))
        (blink-matching-paren t))
    (blink-matching-open)))

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22 Character Display

This section describes how characters are actually displayed by Emacs. Typically, a character is displayed as a glyph (a graphical symbol which occupies one character position on the screen), whose appearance corresponds to the character itself. For example, the character ‘a’ (character code 97) is displayed as ‘a’. Some characters, however, are displayed specially. For example, the formfeed character (character code 12) is usually displayed as a sequence of two glyphs, ‘^L’, while the newline character (character code 10) starts a new screen line.

You can modify how each character is displayed by defining a display table, which maps each character code into a sequence of glyphs. See section Display Tables.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22.1 Usual Display Conventions

Here are the conventions for displaying each character code (in the absence of a display table, which can override these conventions; see section Display Tables).

The above display conventions apply even when there is a display table, for any character whose entry in the active display table is 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 force-mode-line-update (@pxref{Mode Line Format}).

User Option: ctl-arrow

This buffer-local variable controls how control characters are displayed. If it is non-nil, they are displayed as a caret followed by the character: ‘^A’. If it is nil, they are displayed as octal escapes: a backslash followed by three octal digits, as in ‘\001’.

User Option: 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 tab-to-tab-stop. @xref{Indent Tabs}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22.2 Display Tables

A display table is a special-purpose char-table (@pxref{Char-Tables}), with 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.

Function: make-display-table

This creates and returns a display table. The table initially has nil in all elements.

The ordinary elements of the display table are indexed by character codes; the element at index c says how to display the character code c. The value should be nil (which means to display the character c according to the usual display conventions; see section Usual Display Conventions), or a vector of glyph codes (which means to display the character c as those glyphs; see section Glyphs).

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 extra slots which serve special purposes. Here is a table of their meanings; nil in any slot means to use the default for that slot, as stated below.

0

The glyph for the end of a truncated screen line (the default for this is ‘$’). See section Glyphs. On graphical terminals, Emacs uses arrows in the fringes to indicate truncation, so the display table has no effect.

1

The glyph for the end of a continued line (the default is ‘\’). On graphical terminals, Emacs uses curved arrows in the fringes to indicate continuation, so the display table has no effect.

2

The glyph for indicating a character displayed as an octal character code (the default is ‘\’).

3

The glyph for indicating a control character (the default is ‘^’).

4

A vector of glyphs for indicating the presence of invisible lines (the default is ‘...’). See section Selective Display.

5

The glyph used to draw the border between side-by-side windows (the default is ‘|’). @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.

For example, here is how to construct a display table that mimics the effect of setting ctl-arrow to a non-nil value (see section Glyphs, for the function make-glyph-code):

(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)))))
Function: display-table-slot display-table slot

This function returns the value of the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Function: set-display-table-slot display-table slot value

This function stores value in the extra slot slot of display-table. The argument slot may be a number from 0 to 5 inclusive, or a slot name (symbol). Valid symbols are truncation, wrap, escape, control, selective-display, and vertical-border.

Function: describe-display-table display-table

This function displays a description of the display table display-table in a help buffer.

Command: describe-current-display-table

This command displays a description of the current display table in a help buffer.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22.3 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 nil, Emacs uses the usual character display conventions (see section Usual Display Conventions).

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 force-mode-line-update (@pxref{Mode Line Format}).

Function: window-display-table &optional window

This function returns window’s display table, or nil if there is none. The default for window is the selected window.

Function: set-window-display-table window table

This function sets the display table of window to table. The argument table should be either a display table or nil.

Variable: buffer-display-table

This variable is automatically buffer-local in all buffers; its value specifies the buffer’s display table. If it is nil, there is no buffer display table.

Variable: 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 nil, in an interactive session if the terminal cannot display curved quotes, its default maps curved quotes to ASCII approximations. @xref{Keys in Documentation}.

The ‘disp-table’ library defines several functions for changing the standard display table.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22.4 Glyphs

A glyph is a graphical symbol which occupies a single character position on the screen. Each glyph is represented in Lisp as a glyph code, which specifies a character and optionally a face to display it in (see section Faces). The main use of glyph codes is as the entries of display tables (see section Display Tables). The following functions are used to manipulate glyph codes:

Function: make-glyph-code char &optional face

This function returns a glyph code representing char char with face face. If face is omitted or nil, the glyph uses the default face; in that case, the glyph code is an integer. If face is non-nil, the glyph code is not necessarily an integer object.

Function: glyph-char glyph

This function returns the character of glyph code glyph.

Function: glyph-face glyph

This function returns face of glyph code glyph, or nil if glyph uses the default face.

You can set up a glyph table to change how glyph codes are actually displayed on text terminals. This feature is semi-obsolete; use glyphless-char-display instead (see section Glyphless Character Display).

Variable: glyph-table

The value of this variable, if non-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 gth element specifies how to display glyph code g, where g is the glyph code for a glyph whose face is unspecified. Each element should be one of the following:

nil

Display this glyph literally.

a string

Display this glyph by sending the specified string to the terminal.

a glyph code

Display the specified glyph code instead.

Any integer glyph code greater than or equal to the length of the glyph table is displayed literally.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.22.5 Glyphless Character Display

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).

Variable: 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:

nil

Display the character in the usual way.

zero-width

Don’t display the character.

thin-space

Display a thin space, 1-pixel wide on graphical displays, or 1-character wide on text terminals.

empty-box

Display an empty box.

hex-code

Display a box containing the Unicode codepoint of the character, in hexadecimal notation.

an ASCII string

Display a box containing that string. The string should contain at most 6 ASCII characters.

a cons cell (graphical . text)

Display with graphical on graphical displays, and with text on text terminals. Both graphical and text must be one of the display methods described above.

The thin-space, empty-box, hex-code, and ASCII string display methods are drawn with the glyphless-char face. On text terminals, a box is emulated by square brackets, ‘[]’.

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 zero-width or a cons cell.

If a character has a non-nil entry in an active display table, the display table takes effect; in this case, Emacs does not consult glyphless-char-display at all.

User Option: glyphless-char-display-control

This user option provides a convenient way to set 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 :set function (@pxref{Variable Definitions}), which updates glyphless-char-display.

Its value should be an alist of elements (group . method), where group is a symbol specifying a group of characters, and method is a symbol specifying how to display them.

group should be one of the following:

c0-control

ASCII control characters U+0000 to U+001F, excluding the newline and tab characters (normally displayed as escape sequences like ‘^A’; see How Text Is Displayed in The GNU Emacs Manual).

c1-control

Non-ASCII, non-printing characters U+0080 to U+009F (normally displayed as octal escape sequences like ‘\230’).

format-control

Characters of Unicode General Category [Cf], such as ‘U+200E’ (Left-to-Right Mark), but excluding characters that have graphic images, such as ‘U+00AD’ (Soft Hyphen).

no-font

Characters for there is no suitable font, or which cannot be encoded by the terminal’s coding system.

The method symbol should be one of zero-width, thin-space, empty-box, or hex-code. These have the same meanings as in glyphless-char-display, above.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.23 Beeping

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}).

Function: ding &optional do-not-terminate

This function beeps, or flashes the screen (see visible-bell below). It also terminates any keyboard macro currently executing unless do-not-terminate is non-nil.

Function: beep &optional do-not-terminate

This is a synonym for ding.

User Option: visible-bell

This variable determines whether Emacs should flash the screen to represent a bell. Non-nil means yes, nil means no. This is effective on graphical displays, and on text terminals provided the terminal’s Termcap entry defines the visible bell capability (‘vb’).

User Option: ring-bell-function

If this is non-nil, it specifies how Emacs should ring the bell. Its value should be a function of no arguments. If this is non-nil, it takes precedence over the visible-bell variable.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.24 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.

Variable: window-system

This terminal-local variable tells Lisp programs what window system Emacs is using for displaying the frame. The possible values are

x

Emacs is displaying the frame using X.

w32

Emacs is displaying the frame using native MS-Windows GUI.

ns

Emacs is displaying the frame using the Nextstep interface (used on GNUstep and macOS).

pc

Emacs is displaying the frame using MS-DOS direct screen writes.

nil

Emacs is displaying the frame on a character-based terminal.

Variable: initial-window-system

This variable holds the value of window-system used for the first frame created by Emacs during startup. (When Emacs is invoked with the ‘--daemon’ option, it does not create any initial frames, so initial-window-system is nil, except on MS-Windows, where it is still w32. See daemon in The GNU Emacs Manual.)

Function: window-system &optional frame

This function returns a symbol whose name tells what window system is used for displaying frame (which defaults to the currently selected frame). The list of possible symbols it returns is the same one documented for the variable window-system above.

Do not use window-system and 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 window-system is not a good indicator of Emacs capabilities on a given display type. Instead, use display-graphic-p or any of the other display-*-p predicates described in @ref{Display Feature Testing}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.25 Tooltips

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}).

Function: 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.

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 x-gtk-use-system-tooltips to 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.

Variable: 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 tooltip face are used instead. If left or 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 Tooltips in The GNU Emacs Manual.) Note that the left and top parameters, if present, override the values of mouse-relative offsets.

The 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.

Variable: 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 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-nil, and then the rest of the functions will not be called. The default value of this variable is a single function tooltip-help-tips.

If you write your own function to be put on the 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.

Function: tooltip-event-buffer event

This function returns the buffer over which event occurred. Call it with the argument of the function from 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 nil.

Other aspects of tooltip display are controlled by several customizable settings; see Tooltips in The GNU Emacs Manual.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.26 Bidirectional Display

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 bidirectional text. This section describes the facilities and options for editing and displaying bidirectional text.

Text is stored in Emacs buffers and strings in logical (or 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 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 bidirectional reordering, Emacs follows the Unicode Bidirectional Algorithm (a.k.a. UBA), which is described in Annex #9 of the Unicode standard (http://www.unicode.org/reports/tr9/). Emacs provides a “Full Bidirectionality” class implementation of the UBA, consistent with the requirements of the Unicode Standard v8.0.

Variable: bidi-display-reordering

If the value of this buffer-local variable is non-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 (see section Overlay Properties, and see section The display Property). If the value is nil, Emacs does not perform bidirectional reordering in the buffer.

The default value of 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}).

Emacs never reorders the text of a unibyte buffer, even if bidi-display-reordering is non-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 bidi-display-reordering alone. The correct test is this:

 (if (and enable-multibyte-characters
          bidi-display-reordering)
     ;; Buffer is being reordered for display
   )

However, unibyte display and overlay strings are reordered if their parent buffer is reordered. This is because plain-ASCII strings are stored by Emacs as unibyte strings. If a unibyte display or overlay string includes non-ASCII characters, these characters are assumed to have left-to-right direction.

Text covered by display text properties, by overlays with 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 U+FFFC, known as the 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.

Each paragraph of bidirectional text has a 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 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:

Variable: bidi-paragraph-direction

If the value of this buffer-local variable is the symbol right-to-left or left-to-right, all paragraphs in the buffer are assumed to have that specified direction. Any other value is equivalent to nil (the default), which means to determine the base direction of each paragraph from its contents.

Modes for program source code should set this to 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}).

Function: current-bidi-paragraph-direction &optional buffer

This function returns the paragraph direction at point in the named buffer. The returned value is a symbol, either left-to-right or right-to-left. If buffer is omitted or nil, it defaults to the current buffer. If the buffer-local value of the variable bidi-paragraph-direction is non-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 bidi-display-reordering is nil as well as unibyte buffers, this function always returns left-to-right.

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.

Function: 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 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 direction.

The function returns the new buffer position as its value.

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 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 to the left of the preceding field, messing up the expected layout. There are several ways to avoid this problem:

Function: bidi-string-mark-left-to-right string

This function returns its argument 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 LRM character to the string. The appended LRM character is made invisible by giving it an invisible text property of t (see section Invisible Text).

The reordering algorithm uses the bidirectional properties of the characters stored as their bidi-class property (@pxref{Character Properties}). Lisp programs can change these properties by calling the put-char-code-property function. However, doing this requires a thorough understanding of the 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 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.

The bidirectional properties of characters can be overridden by inserting into the text special directional control characters, LEFT-TO-RIGHT OVERRIDE (LRO) and RIGHT-TO-LEFT OVERRIDE (RLO). Any characters between a RLO and the following newline or POP DIRECTIONAL FORMATTING (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 LRO and PDF or newline will display as if they were strong left-to-right, and will not be reversed even if they are strong right-to-left characters.

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 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.

Function: bidi-find-overridden-directionality from to &optional object

This function looks at the text of the specified object between positions from (inclusive) and 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 nil.

The optional argument object specifies which text to search, and defaults to the current buffer. If object is non-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.

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 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.

Function: buffer-substring-with-bidi-context start end &optional no-properties

This function works similar to 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 no-properties, if non-nil, means remove the text properties from the copy of the text.


[Top] [Contents] [Index] [ ? ]

Footnotes

(1)

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.

(2)

In this context, the term font has nothing to do with Font Lock (@pxref{Font Lock Mode}).


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 23, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on September 23, 2017 using texi2html.