Next: Reporting Operation Progress, Up: The Echo Area   [Contents][Index]

42.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 (see 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 Faces). The string is also added to the *Messages* buffer, but without text properties (see Logging Messages in *Messages*).

Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., "Missing `%s'" might result in "Missing ‘foo’". See Text Quoting Style, for how to influence or inhibit this translation.

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

The following facilities allow users and Lisp programs to control how echo-area messages are displayed.

Variable: set-message-function ¶

If this variable is non-nil, it should be a function of one argument, the text of a message to display in the echo area. That function will be called by message and related functions. If the function returns nil, the message is displayed in the echo area as usual. If the function returns a string, that string is displayed in the echo area instead of the original message. If the function returns any other non-nil value, that means the message was already handled, so message will not display anything in the echo area.

The default value calls set-minibuffer-message, described below.

Variable: clear-message-function ¶

If this variable is non-nil, it should be a function of no arguments; message and related functions call it when their argument message is nil or the empty string, to clear the echo area.

Usually this function is called when the next input event arrives after displaying an echo-area message. The function is expected to clear the message displayed by its counterpart function specified by set-message-function, but doesn’t have to. If the function wants the echo area to remain uncleared, it should return the symbol dont-clear-message; any other value will result in the echo area being cleared.

The default value is the function that clears the message displayed in an active minibuffer.

User Option: set-message-functions ¶

The value of this user option is a list of functions to be called for handling display of echo-area messages. Each function is called with one argument, the text of the message to display. If the function returns a string, that string replaces the original message, and the next function in the list is called with the new message text. If the function returns nil, the next function in the list is called with the same text; if the last function in the list returns nil, the message text is displayed in the echo area. If the function returns a non-nil value that is not a string, the message is considered to be handled, and no further functions in the list are called.

The three useful functions to be put in the list that is the value of this option are described below.

Function: set-minibuffer-message message ¶

This function displays message in the echo-area when the minibuffer is not active, and at the end of the minibuffer when the minibuffer is active. However, if the text shown in the active minibuffer has the minibuffer-message text property (see Properties with Special Meanings) on some character, the message will be displayed before the first character having that property.

This function is by default the only member of the list in set-message-functions.

Function: inhibit-message message ¶

If an echo-area message matches any regexp in the list that is the value of the user option inhibit-message-regexps, this function suppresses the display of that message and returns a non-nil value that is not a string. Thus, if this function is in the list set-message-functions, the rest of the functions in the list will not be called when message matches the regexps in inhibit-message-regexps. To ensure a matching message will never be displayed, make this function be the first element of the list in set-message-functions.

Function: set-multi-message message ¶

This function accumulates several echo-area messages emitted one after another, and returns them as a single string in which individual messages are separated by newlines. Up to multi-message-max recent messages can be accumulated. The accumulated messages are discarded when more than multi-message-timeout seconds have elapsed since the time the first message was emitted.

Variable: inhibit-message ¶

When this variable is non-nil, message and related functions will not display any messages in the Echo Area, and will also not clear previous echo-area messages when message is called with a nil or an empty argument. Echo-area messages are still logged in the *Messages* buffer, though.

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 (see Information from the Command Loop) 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 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.

Next: Logging Messages in *Messages*, Previous: Displaying Messages in the Echo Area, Up: The Echo Area   [Contents][Index]

42.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 context ¶

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 arguments min-change and min-time 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).

If context is the symbol async, it announces that the updates will occur asynchronously. Backends can use that info to prevent the progress updates from interfering with other data. For example, the backend that displays the progress in the echo area will not display those async updates when the echo area is in use.

This function calls progress-reporter-update, so the first message is printed immediately.

Function: progress-reporter-update reporter &optional value update-text ¶

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.

Optional argument update-text is a string to be displayed after reporter’s main message and progress text. One typical use is as the “step” of a long-running process so the user knows where it is. If reporter is a non-numerical reporter, then value should be nil, or a string to use instead of update-text.

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 update-text ¶

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

reporter, value, and update-text 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]) reporter-or-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. The argument reporter-or-message can be either a string or a progress reporter object.

You can rewrite the example in the beginning of this subsection using this macro as follows:

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

Using a reporter object as the reporter-or-message argument is useful if you want to specify the optional arguments in make-progress-reporter. For instance, you can write the previous example as follows:

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

Macro: dolist-with-progress-reporter (var list [result]) reporter-or-message body… ¶

This is another convenience macro that works the same way as dolist does, but also reports loop progress using the functions described above. As in dotimes-with-progress-reporter, reporter-or-message can be a progress reporter or a string. You can rewrite the previous example with this macro as follows:

(dolist-with-progress-reporter
    (k (number-sequence 0 500))
    "Collecting some mana for Emacs..."
  (sit-for 0.01))

Macro: with-delayed-message (timeout message) body… ¶

Sometimes it’s unclear whether an operation will take a long time to execute or not, or it can be inconvenient to implement a progress reporter. This macro can be used in those situations.

(with-delayed-message (2 (format "Gathering data for %s" entry))
  (setq data (gather-data entry)))

In this example, if the body takes more than two seconds to execute, the message will be displayed. If it takes a shorter time than that, the message won’t be displayed. In either case, the body is evaluated as normally, and the return value of the final element in the body is the return value of the macro.

The message element is evaluated before body, and is always evaluated, whether the message is displayed or not.

Next: Echo Area Customization, Previous: Reporting Operation Progress, Up: The Echo Area   [Contents][Index]

42.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 ...))

Variable: messages-buffer-name ¶

This variable has the name of the buffer where messages should be logged to, and defaults to *Messages*. Some packages may find it useful to temporarily redirect the output to a different buffer (perhaps to write the buffer out to a log file later), and they can bind this variable to a different buffer name. (Note that this buffer (if it doesn’t exist already), will be created and put into messages-buffer-mode.)

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 ‘...’.

Previous: Logging Messages in *Messages*, Up: The Echo Area   [Contents][Index]

42.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, wrapping long line as needed. But if the variable message-truncate-lines is non-nil, long lines of echo-area message are instead truncated to fit the mini-window width.

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; see Minibuffer Windows).

Next: Warning Variables, Up: Reporting Warnings   [Contents][Index]

42.5.1 Warning Basics ¶

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

:emergency

A problem that will seriously impair Emacs operation soon if the user does not attend to it promptly.

:error

A report about data or circumstances that are inherently wrong.

:warning

A report about 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 the user is currently debugging the Lisp program which issues the warning.

When your program encounters invalid input data, it can either signal a Lisp error by calling error or signal (see How to Signal an Error) or report a warning with severity :error. Signaling a Lisp error is the easiest thing to do, but it means the signaling program cannot continue execution. If you want to take the trouble of implementing a way to continue processing despite the invalid data, then reporting a warning of severity :error is the right way of informing 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; reporting that as a warning instead avoids that problem.)

In addition to severity level, each warning has a warning type to classify it. The warning type is either a symbol or a list of symbols. If it is a symbol, it should be the custom group that you use for the program’s user options; if it is a list, the first element of the list should be that custom group. For example, byte compiler warnings use the warning type (bytecomp). If the warning type is a list, the elements of the list after the first one, which should be arbitrary symbols, represent subcategories of the warning: they will be displayed to the user to better explain the nature of the warning.

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

This function reports a warning, using the string message as the warning text and type as the warning type. level should be the severity level, and defaults to :warning if omitted or nil.

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

Function: lwarn type level message &rest args ¶

This function reports a warning using the value returned by (format-message message args…) as the message text 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 returned by (format-message message args…) as the message text, emacs as the warning 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.

Next: Warning Options, Previous: Warning Basics, Up: Reporting Warnings   [Contents][Index]

42.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. A notable example is ding (see Beeping).

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 the current buffer, and the function can insert text into 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 instead of that entry (the value need not be an actual member of warning-levels, but it must have the same structure). 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, there’s no prefix text, before the warning is displayed, starting with the string part of the entry in warning-levels corresponding to the warning’s level.

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 of this variable 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 the current buffer. The function can, for example, insert text which will serve as a header for the series of warnings.

Once a series has begun, the value of this variable 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 the text of each warning.

Variable: warning-fill-column ¶

The column at which to fill warnings.

Variable: warning-type-format ¶

This variable specifies the format for displaying the warning type in the warning text. 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 the empty string "" then the warning type won’t appear at all.

Next: Delayed Warnings, Previous: Warning Variables, Up: Reporting Warnings   [Contents][Index]

42.5.3 Warning Options ¶

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

User Option: warning-display-at-bottom ¶

This user option controls the window in which the warnings buffer is shown. By default, the value is t, and Emacs displays the warnings buffer in a window at the bottom of the selected frame, creating a new window there if needed. If customized to nil, the warnings buffer will be shown using the default rules of display-buffer (see Choosing a Window for Displaying a Buffer); in that case the warning category can be used in display-buffer-alist to customize how display-buffer will display these buffers (see Action Alists for Buffer Display).

User Option: warning-minimum-level ¶

This user option specifies the minimum severity level that should be shown immediately to the user, by popping the warnings buffer in some window. The default is :warning, which means to show the warning buffer for any warning severity except :debug. The warnings of lower severity levels will still be written into the warnings buffer, but the buffer will not be forced onto display.

User Option: warning-minimum-log-level ¶

This user option specifies the minimum severity level that should be logged in the warnings buffer. Warnings of lower severity will be completely ignored: not written to the warnings buffer and not displayed. The default is :warning, which means to log warnings of any severity except :debug.

User Option: warning-suppress-types ¶

This list specifies which warning types should not be displayed immediately when they occur. Each element of the list should be a list of symbols. If an element of this list has the same elements as the first elements in a warning type, then the warning of that type will not be shown on display by popping the warnings buffer in some window (the warning will still be logged in the warnings buffer).

For example, if the value of this variable is a list like this:

((foo) (bar subtype))

then warnings whose types are foo or (foo) or (foo something) or (bar subtype other) will not be shown to the user.

User Option: warning-suppress-log-types ¶

This list specifies which warning types should be ignored: not logged in the warnings buffer and not shown to the user. The structure and the matching of warning types are the same as for warning-suppress-types above.

During startup, Emacs delays showing any warnings until after it loads and processes the site-wide and user’s init files (see Summary: Sequence of Actions at Startup). Let-binding (see Local Variables) the values of these options around some code in your init files which might emit a warning will therefore not work, because it will not be in effect by the time the warning is actually processed. Thus, if you want to suppress some warnings during startup, change the values of the above options in your init file early enough, or put those let-binding forms in your after-init-hook or emacs-startup-hook functions. See The Init File.

Previous: Warning Options, Up: Reporting Warnings   [Contents][Index]

42.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 function delay-warning for this. Emacs automatically delays any warnings emitted during the early stages of startup, and shows them only after the init files are processed.

Function: delay-warning type message &optional level buffer-name ¶

This function is the delayed counterpart to display-warning (see Warning Basics), and it is called with the same arguments. The warning message is queued into delayed-warnings-list.

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. Immediately after running post-command-hook (see Command Loop Overview), the Emacs command loop displays all the warnings specified by this variable, then resets the variable 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 process and display delayed warnings. Emacs also runs this hook during startup, after loading the site-start and user init files (see Summary: Sequence of Actions at Startup), because warnings emitted before that are automatically delayed.

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.

Next: Overlay Properties, Up: Overlays   [Contents][Index]

42.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 considered 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 evaporate property).

The arguments front-advance and rear-advance specify what happens when text is inserted at the beginning (i.e., before start) and at the end. 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 the specified 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 in that buffer. 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 previously deleted (and thus isn’t associated with any buffer), it goes into the current buffer.

The return value is overlay.

This function is the only valid way to change the endpoints of an overlay.

Function: remove-overlays &optional start end name value ¶

This function clears the text in the region between start and end of any overlays whose property named name has the specified value, such that no such overlay will affect the text in the region. To do this, the function can remove overlays in the region, or move their endpoints, or split them, or do some combination of these. Specifically:

• Overlays that start at or after start and end before end will be removed completely.
• Overlays that start before start and end after start, but before end, will be altered so that they end at start.
• Overlays that start at or after start and end after end will be altered so that they start at end.
• Overlays that start before start and end after end will be split into two overlays: one that ends at start and the other that begins at end.
• Empty overlays (see empty overlays) will be removed if they are either at start, or strictly between start and end excluding end, or at end when end denotes the position at the end of the buffer.

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

Values of the named overlay property are compared using eq, which is important if the values are anything but symbols or fixnums (see Equality Predicates). It means the values passed to the function must be the same values used to set the overlay property, not their copies; objects which are different will not compare equal even if they have identical contents.

The optional arguments name and value should either both be passed and non-nil, or both omitted or nil.

Function: copy-overlay overlay ¶

This function returns a copy of overlay. The copy has the same endpoints and properties as overlay. However, the text insertion type for the start of the overlay and for the end of the overlay are set to their default values.

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

Next: Searching for Overlays, Previous: Managing Overlays, Up: Overlays   [Contents][Index]

42.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. See 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. See Examining Text 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, or a cons of two values. Any other value triggers undefined behavior.

The priority matters when two or more overlays cover the same character and both specify the same property with different values; the one whose priority value is higher overrides the other. (For the face property, the higher priority overlay’s value does not completely override the other value; instead, its individual face attributes override the corresponding face attributes of the face property whose priority is lower.) If two overlays have the same priority value, and one is “nested” in the other (i.e., covers fewer buffer or string positions), 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.

When a Lisp program puts overlays with defined priorities on text that might have overlays without priorities, this could cause undesirable results, because any overlay with a positive priority value will override all the overlays without a priority. Since most Emacs features that use overlays don’t specify priorities for their overlays, integer priorities should be used with care. Instead of using integer priorities and risk overriding other overlays, you can use priority values 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. In particular, priority value (nil . n), with n a positive integer, enables you to have the overlays ordered by priority when necessary without completely overriding other overlays.

Currently, all overlays take priority over text properties.

If you need to put overlays in priority order, use the sorted argument of overlays-at. See 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 Faces). The value of the property can be the following:

• A face name (a symbol or string).
• An anonymous face: a property list of the form (keyword value …), where each keyword is a face attribute name and value is a value for that attribute.
• A list of faces. Each list element should be either a face name or an anonymous face. This specifies a face which is an aggregate of the attributes of each of the listed faces. Faces occurring earlier in the list have higher priority.
• A cons cell of the form (foreground-color . color-name) or (background-color . color-name). This specifies the foreground or background color, similar to (:foreground color-name) or (:background color-name). This form is supported for backward compatibility only, and should be avoided.

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 The display Property. Note that, if the display property is a replacing one (see Display Specs That Replace The Text), the invisible property of the same overlay will be ignored.

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 as a tooltip. For details see 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. See Defining and Using 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.)

When these functions are called, inhibit-modification-hooks is bound to non-nil. If the functions modify the buffer, you might want to bind inhibit-modification-hooks to nil, so as to cause the change hooks to run for these modifications. However, doing this may call your own change hook recursively, so be sure to prepare for that. See Change Hooks.

Text properties also support the modification-hooks property, but the details are somewhat different (see Properties with Special Meanings).

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. However, if the text covered by the overlay has a replacing display property, the invisible property will be ignored, because a replacing display property skips the text without examining its properties. See Invisible Text, for details.

intangible ¶

The intangible property on an overlay works just like the intangible text property. It is obsolete. See Properties with Special Meanings, for details.

isearch-open-invisible

This property tells incremental search (see Incremental Search in The GNU Emacs Manual) how to make an invisible overlay visible, permanently, if the final match overlaps it. See Invisible Text.

isearch-open-invisible-temporary

This property tells incremental search how to make an invisible overlay visible, temporarily, during the search. See 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. Note that if the text at the beginning of the overlay is made invisible, the string will not be displayed.

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. Note that if the text at the end of the overlay is made invisible, the string will not be displayed.

line-prefix

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

wrap-prefix

This property specifies a display spec to prepend to each continuation line at display-time. See 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 empty overlays) 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.

display-line-numbers-disable ¶

This property prevents display of line numbers (see display-line-numbers in The GNU Emacs Manual) for the text which is within an overlay having this property. One situation where using an overlay with this property is useful is an empty overlay at end-of-buffer, since otherwise there’s no way of preventing the display of the line number there.

keymap ¶

If this property is non-nil, it specifies a keymap for a portion of the text. This keymap takes precedence over most other keymaps (see Active Keymaps), and it is used when point is within the overlay, where the front- and rear-advance properties define whether the boundaries are considered as being within or not.

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. See Properties with Special Meanings.

Previous: Overlay Properties, Up: Overlays   [Contents][Index]

42.9.3 Searching for Overlays ¶

Function: overlays-at pos &optional sorted ¶

This function returns a list of all the overlays that contain the character at position pos in the current buffer. If sorted is non-nil, the returned list is in decreasing order of priority, otherwise it is in no particular order. An overlay contains the character at 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))

Empty overlays (see empty overlays) do not contain any characters, so this function does not return them. Use overlays-in, described below, instead if empty overlays are of interest.

Note that this function can return overlays outside of the current narrowing of the buffer (see Narrowing) if pos is outside of the narrowing.

Function: overlays-in beg end ¶

This function returns a list of the overlays that overlap with the region beg through end. An overlay overlaps with a region if it contains one or more characters between beg and end; this excludes the characters at (i.e. after) end.

Empty overlays do not contain any characters, so the rule for including them is different: they are said to overlap if they are at beg, strictly between beg and end excluding end, or at end when end denotes the position at the end of the buffer. (The special handling of empty overlays at end of buffer is to allow such overlays to be found and processed. For any other value of end you could increment the end position instead.) Note that if beg and end are the same position, an empty overlay that is at beg is also at end, so this case is somewhat similar to an empty overlay at the end of the buffer.

The order in which the overlays appear in the returned list is unpredictable.

Note that this function can return overlays outside of the current narrowing of the buffer if beg and/or end are outside of the narrowing.

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 (see Text Property Search Functions). 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)))

Next: Defining Faces, Up: Faces   [Contents][Index]

42.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 Displaying Faces). (However, unspecified is not a valid value in defface.)

A face attribute can also have the value reset. This special value stands for the value of the corresponding attribute of the default face.

The default face must explicitly specify all attributes, and cannot use the special value reset.

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 name (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.

: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, regular, medium, 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 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. See 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. See 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 :position position)

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 is a symbol which sets the line-style to of the underline. It should be one of line, double-line, wave, dots, or dashes. GUI frames under most window systems support all the aforementioned underline styles, while on text terminals double-line, wave and dots are contingent on the availability of the Smulx or Su terminfo capabilities. Omitting the attribute :style means to use a straight line. position, if non-nil, means to display the underline at the descent of the text, instead of at the baseline level. If it is a number, then it specifies the amount of pixels above the descent to display the underline.

: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 (vwidth . hwidth) :color color :style style)

You can explicitly specify all aspects of the box with a plist of this form. Any element in this plist can be omitted.

The values of vwidth and hwidth specify respectively the width of the vertical and horizontal lines to draw; they default to (1 . 1). A negative horizontal or vertical 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. For simplification the width could be specified with only a single number n instead of a list, such case is equivalent to ((abs n) . n).

The value of color specifies the color to draw with. The default is the background color of the face for 3D boxes and flat-button, and the foreground color of the face for other boxes.

The value of 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, flat-button or omitted, a plain 2D box is used.

If you use the :box face attribute on strings displayed instead of buffer text via the display text property, special considerations might apply if the surrounding buffer text also has the :box face attribute. See Display Specs That Replace The Text. Also note that the vertical lines of the box are only drawn when :box attribute changes from nil to non-nil or vice versa; two consecutive face properties with a non-nil :box attribute will be displayed without the vertical line between them.

: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 or a fontset. If it is a font object, it specifies the font to be used by the face for displaying ASCII characters. See Low-Level Font Representation, for information about font objects, font specs, and font entities. See Fontsets, for information about fontsets.

When specifying this attribute using set-face-attribute or set-face-font (see 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 Displaying Faces). If the face to inherit from is unspecified, it is treated the same as nil, since Emacs never merges :inherit attributes. If a list of faces is used, attributes from faces earlier in the list override those from later faces.

:extend

Whether or not this face will be extended beyond end of line and will affect the display of the empty space between the end of line and the edge of the window. The value should be t to display the empty space between end of line and edge of the window using this face, or nil to not use this face for the space between the end of the line and the edge of the window. When Emacs merges several faces for displaying the empty space beyond end of line, only those faces with :extend non-nil will be merged. By default, only a small number of faces, notably, region, have this attribute set. This attribute is different from the others in that when a theme doesn’t specify an explicit value for a face, the value from the original face definition by defface is inherited (see Defining Faces).

Some modes, like hl-line-mode, use a face with an :extend property to mark the entire current line. Note, however, that Emacs will always allow you to move point after the final character in a buffer, and if the buffer ends with a newline character, point can be placed on what is seemingly a line at the end of the buffer—but Emacs can’t highlight that “line”, because it doesn’t really exist.

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.

Next: Face Attribute Functions, Previous: Face Attributes, Up: Faces   [Contents][Index]

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

Note that once you have defined a face (usually with defface), you cannot later undefine this face safely, except by restarting Emacs.

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 (see Common Item 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 (see Customization Settings). 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 (eval-defun) or with C-x C-e (eval-last-sexp) in Emacs Lisp mode, a special feature of these commands 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), haiku (for Haiku), pgtk (for pure GTK), android (for Android), or tty (a non-graphics-capable display). See 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 Face Attributes). See 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 (see 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; see Applying Customizations), or by face remapping (see 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 optional argument spec-type determines which spec to set. If it is omitted or nil or face-override-spec, this function sets the override spec, which overrides face specs on face of all the other types mentioned below. This is useful when calling this function outside of Custom code. If spec-type is customized-face or saved-face, this function sets the customized spec or the saved custom spec, respectively. 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). The effect of any other value of spec-type on the face specs is reserved for internal use, but the function will still define face itself and recalculate its attributes, as described above.

Next: Displaying Faces, Previous: Defining Faces, Up: Faces   [Contents][Index]

42.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. See Face Attributes, for the supported attributes.

If frame is omitted or nil, that means the selected frame (see Input Focus). If frame is t, this function returns the value of the specified attribute for newly-created frames, i.e. the value of the attribute before applying the face spec in the face’s defface definition (see Defining Faces) or the spec set by face-spec-set. This default value of attribute is normally unspecified, unless you have specified some other 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 inherit ¶

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, i.e. the values these attributes have before applying the face spec in the face’s defface definition or the spec set by face-spec-set. These default values of the attributes are normally unspecified, unless you have specified some other value using set-face-attribute; see below. The optional argument inherit has the same meaning as the same argument to face-attribute, which see. This is useful when you want the face attributes to be absolute and not unspecified.

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 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 specified in this way override the face spec(s) belonging to face. See Face Attributes, for the supported attributes.

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; they will effectively override the attribute values specified by defface. If frame is nil, this function sets the attributes for all existing frames, as well as for newly created frames.

To reset the value of an attribute, that is, to indicate that the face doesn’t by itself specify a value for the attribute, use the special value unspecified (not nil!) for the attribute, and set the frame argument to t, in addition to the call with frame set to nil. This is because the default attributes for newly created frames are merged with the face’s spec in defface when a new frame is created, and so having unspecified in the default attributes for new frames will be unable to override defface; the special call to this function as described above will arrange for defface to be overridden.

Note that the attribute-value pairs are evaluated in the order they are specified, with the exception of the :family and :foundry attributes, which are evaluated first. This means that if a certain attribute is specified more than once, only the last value will be used. It also means that in some cases a different order of attributes will produce different results. For example, when :weight is placed before :font, the weight value is applied to the current font of the face, and might be rounded to the closest available weight of that font, whereas when :font is placed before :weight the weight value is applied to the specified font.

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 ¶

Change the font-related attributes of face to those of font (a string or a font object). See face-font-attribute, for the supported formats of the font argument. This function sets the attribute :font of the face, and indirectly also the :family, :foundry, :width, :height, :weight, and :slant attributes, as defined by the font. If frame is non-nil, only change the attributes on the specified frame.

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.

Command: set-face-underline face underline &optional frame ¶

This sets the :underline attribute of face to underline.

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

Command: set-face-extend face extend &optional frame ¶

This sets the :extend attribute of face to extend.

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 used by the specified face.

If the optional argument frame is specified, it returns the name of the font of face for that frame; frame defaults to the selected frame if it is nil or omitted. If frame is t, the function reports on the font defaults for face to be used for new frames.

By default, the returned font is for displaying ASCII characters, but if frame is anything but t, and the optional third argument character is supplied, the function returns the font name used by face for that 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.

Function: face-extend-p face &optional frame inherit ¶

This function returns non-nil if face face specifies a non-nil :extend attribute. The inherit argument is passed to face-attribute.

Next: Face Remapping, Previous: Face Attribute Functions, Up: Faces   [Contents][Index]

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

• If the text consists of a special glyph, the glyph can specify a particular face. See Glyphs.
• If the text lies within an active region, Emacs highlights it using the region face. See Standard Faces in The GNU Emacs Manual.
• If the text lies within an overlay with a non-nil face property, Emacs applies the face(s) specified by that property. If the overlay has a mouse-face property and the mouse is near enough to the overlay, Emacs applies the face or face attributes specified by the mouse-face property instead. See Overlay Properties.

  When multiple overlays cover the same character, an overlay with higher priority overrides those with lower priority. See Overlays.

• If the text contains a face or mouse-face property, Emacs applies the specified faces and face attributes. See Properties with Special Meanings. (This is how Font Lock mode faces are applied. See Font Lock Mode.)
• If the text lies within the mode line of the selected window, Emacs applies the mode-line face. For the mode line of a non-selected window, Emacs applies the mode-line-inactive face. For a header line, Emacs applies the header-line face. For a tab line, Emacs applies the tab-line face.
• If the text comes from an overlay string via before-string or after-string properties (see Overlay Properties), or from a display string (see Other Display Specifications), and the string doesn’t contain a face or mouse-face property, or these properties leave some face attributes undefined, but the buffer text affected by the overlay/display property does define a face or those attributes, Emacs applies the face attributes of the “underlying” buffer text. However, this does not apply to strings displayed in the display margins, which use the margin face as the base instead (see Displaying in the Margins).
• If the text is to be shown in the display margins, Emacs uses the margin face as the base, so any attribute not specified by the string’s own face is taken from the margin face.
• If any given attribute has not been specified during the preceding steps, Emacs applies the attribute of the default face.

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

Next: Functions for Working with Faces, Previous: Displaying Faces, Up: Faces   [Contents][Index]

42.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 Properties with Special Meanings. 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. If face-remapping-alist includes faces applicable only to certain windows, by using the (:filtered (:window param val) spec), that face takes effect only in windows that match the filter conditions (see Properties with Special Meanings). To turn off face filtering temporarily, bind face-filters-always-match to a non-nil value, then all face filters will match any window.

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 specs as relative remappings for face face in the current buffer. specs should be a list where each element is either a face name, 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)

Note that buffer-local face remapping does not work reliably for parent faces of basic faces (see Basic Faces). (These are the faces that are used in mode lines, header lines, and other basic decorations of windows and frames.) For instance, mode-line-inactive inherits from mode-line, but remapping mode-line won’t normally have the desired effect on mode-line-inactive, especially if done locally for some buffers. Instead you have to remap mode-line-inactive directly.

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.

Next: Automatic Face Assignment, Previous: Face Remapping, Up: Faces   [Contents][Index]

42.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. However, functions that manipulate glyphs, such as make-glyph-code and glyph-face (see Glyphs) access the face numbers internally. Note that the face number is stored as the value of the face property of the face symbol, so we recommend not to set that property of a face to any value of your own.

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 the future. when should be a string indicating when obsolete-face was made obsolete (usually a version number string).

Next: Basic Faces, Previous: Functions for Working with Faces, Up: Faces   [Contents][Index]

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

Note that, when the buffer text includes very long lines, these functions are called as if they were in a with-restriction form (see Narrowing), with a long-line-optimizations-in-fontification-functions label and with the buffer narrowed to a portion around pos.

Next: Font Selection, Previous: Automatic Face Assignment, Up: Faces   [Contents][Index]

42.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 those existing 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. See 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 Face Attributes).

mode-line-active ¶

mode-line-inactive

header-line

tab-line

Basic faces used for the mode line, header line, and tab line.

tool-bar ¶

tab-bar

fringe

scroll-bar

window-divider

border

child-frame-border

Basic faces used for the corresponding decorations of GUI frames.

cursor ¶

The basic face used for the text cursor.

margin ¶

The basic face used for window margins, both on the left and on the right. It is commonly used to customize the background of the empty areas of the margins, and it also provides the base attributes for strings displayed in the margins (see Displaying in the Margins). It inherits from the default face.

mouse ¶

The basic face used for displaying mouse-sensitive text when the mouse pointer is on that text.

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 (see Properties with Special Meanings).

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.

Next: Looking Up Fonts, Previous: Basic Faces, Up: Faces   [Contents][Index]

42.12.9 Font Selection ¶

Before Emacs can draw a character on a graphical display, it must select a font for that character³³. 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 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.

Next: Fontsets, Previous: Font Selection, Up: Faces   [Contents][Index]

42.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 (see 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.

Next: Low-Level Font Representation, Previous: Looking Up Fonts, Up: Faces   [Contents][Index]

42.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 fontset characters font-spec &optional frame add ¶

This function modifies the existing fontset to use the font specified by font-spec for displaying the specified characters.

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

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

The characters argument can be a single character which should be displayed using font-spec. It can also be a cons cell (from . to), where from and to are characters. In that case, use font-spec for all the characters in the range from and to (inclusive).

characters may be a charset symbol (see Character Sets). In that case, use font-spec for all the characters in the charset.

characters may be a script symbol (see char-script-table). In that case, use font-spec for all the characters belonging to the script. See also use-default-font-for-symbols, which affects font selection when characters specify or belong to the symbol script (which includes symbol and punctuation characters).

characters may be nil, which means to use font-spec for any character in fontset for which no font-spec is specified.

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

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

font-spec may be a font name, a string.

font-spec may be nil, which explicitly specifies that there’s no font for the specified characters. 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 for characters. If it is prepend, font-spec is prepended to the existing specs. If it is append, font-spec is appended. By default, font-spec overwrites the previously set font specs.

For instance, this changes the default fontset to use a font whose 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"))

Note that this function should generally be called from the user’s init files, and more generally before any of characters were displayed in the current Emacs session. That’s because for some scripts, Emacs caches the way they are displayed, and the cached information includes the font used for them – once these characters are displayed once, the cached font will continue to be used regardless of changes in the fontsets.

Function: char-displayable-p char ¶

This function returns non-nil if Emacs ought to be able to display char. Or 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.

This function may return non-nil even when there is no font available, since it also checks whether the coding system for the text terminal can encode the character (see Terminal I/O Encoding).

Function: char-displayable-on-frame-p char frame ¶

This function behaves like char-displayable-p does (relative to frame), but in the graphical case, it does not perform the final check of whether the underlying text terminal can encode the character. It thus provides a displayability check for char more specific to frame.

Previous: Fontsets, Up: Faces   [Contents][Index]

42.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 Face Attributes. :family and :foundry are strings or symbols, while the other three are either symbols or numbers, the numerical values of the valid style symbols. As example values, :slant may be italic, :weight may be bold and :width may be normal.

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

:dpi

The resolution in dots per inch for which the font is designed. The value must be a non-negative number.

:spacing

The spacing of the font: proportional, dual, mono, or charcell. The value should be either an integer (0 for proportional, 90 for dual, 100 for mono, 110 for charcell) or a one-letter symbol (one of P, D, M, or C).

:avgwidth

The average width of the font in 1/10 pixel units. The value should be a non-negative number.

: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. For the list of OpenType script, language, and feature tags, see the list of registered OTF tags.

:type ¶

The symbol that specifies the font backend used to draw the characters. The possible values depend on the platform and on how Emacs was configured at build time. Typical values include ftcrhb and xfthb on X, harfbuzz on MS-Windows, ns on GNUstep, etc. It can also be nil if left unspecified, typically in a font-spec.

Function: font-put font-spec property value ¶

Set the font property property in the font-spec font-spec to value. The property can any of the ones described above.

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. The property can any of the ones that font-spec supports.

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, and the value of the :otf property is a cons of the form (gsub . gpos), where gsub and gpos are lists representing OpenType features supported by the font, of the form

((script-tag (langsys-tag feature...) ...) ...)

where script-tag, langsys-tag, and feature are symbols representing OpenType layout tags.

If font is a font object, the special property :combining-capability is non-nil if the font backend of font supports rendering of combining characters for non-OpenType fonts.

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 long-xlfds ¶

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 optional argument fold-wildcards is non-nil, consecutive wildcards in the XLFD are folded into one.

If the optional argument long-xlfds is omitted or nil, then the function returns nil if the XLFD would exceed 255 characters in length; this is for compatibility with the X protocol, which mandates that XLFDs are restricted to that length. If long-xlfds is non-nil, this restriction is lifted, and the function can return XLFDs of any length.

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.

max-width

The maximum advance width of the font.

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. Emacs uses this for calculating text layout on display; if the value of average-width is zero, Emacs uses the value of space-width instead for those purposes.

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 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, as that face is defined for the selected frame.

Function: default-font-height ¶

This function returns the height in pixels of the font used by the current buffer’s default face, as that face is defined for the selected frame.

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.

Next: Fringe Indicators, Up: Fringes   [Contents][Index]

42.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 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 (see Layout Parameters).

The above variables actually take effect via the function set-window-buffer (see 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 persistent ¶

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.

If window is not large enough to accommodate fringes of the desired width, this leaves the fringes of window unchanged.

The values specified here may be later overridden by invoking set-window-buffer (see Buffers and Windows) on window with its keep-margins argument nil or omitted. However, if the optional fifth argument persistent is non-nil and the other arguments are processed successfully, the values specified here unconditionally survive subsequent invocations of set-window-buffer. This can be used to permanently turn off fringes in the minibuffer window, consult the description of set-window-scroll-bars for an example (see Scroll Bars).

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 persistent).

Next: Fringe Cursors, Previous: Fringe Size and Position, Up: Fringes   [Contents][Index]

42.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 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 after the buffer end when indicate-empty-lines is non-nil.

overlay-arrow

Used for overlay arrows (see 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 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.

Next: Fringe Bitmaps, Previous: Fringe Indicators, Up: Fringes   [Contents][Index]

42.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 (see 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 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.

Next: Customizing Fringe Bitmaps, Previous: Fringe Cursors, Up: Fringes   [Contents][Index]

42.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 Fringe Indicators), and the variable fringe-cursor-alist, which maps fringe cursors to bitmaps (see 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 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 and background colors are to be used to display the bitmap, using the attributes of the fringe face for colors that face didn’t specify. If face is omitted, that means to use the attributes of the default face for the colors which the fringe face didn’t specify. For predictable results that don’t depend on the attributes of the default and fringe faces, we recommend you never omit face, but always provide a specific face. In particular, if you want the bitmap to be always displayed in the fringe face, use fringe as face.

For instance, to display an arrow in the left fringe, using the warning face, you could say something like:

(overlay-put
 (make-overlay (point) (point))
 'before-string (propertize
                 "x" 'display
                 `(left-fringe right-arrow warning)))

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

bottom-left-angle, bottom-right-angle

top-left-angle, top-right-angle

left-bracket, right-bracket

empty-line

Used to indicate buffer boundaries.

filled-rectangle, hollow-rectangle

filled-square, hollow-square

vertical-bar, horizontal-bar

Used for different types of fringe cursors.

exclamation-mark, question-mark

large-circle

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.

Next: The Overlay Arrow, Previous: Fringe Bitmaps, Up: Fringes   [Contents][Index]

42.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. (Note that this order of bits is the opposite of the order in XBM images; see XBM Images.)

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

Previous: Customizing Fringe Bitmaps, Up: Fringes   [Contents][Index]

42.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 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 if the left fringe is shown; 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, or when the left fringe is not shown, 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 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 graphical terminals without the left fringe shown) or fringe bitmap (for graphical terminals with a left fringe) 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.

Next: Specified Spaces, Up: The display Property   [Contents][Index]

42.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. In addition, any invisible and composition properties of the text that is replaced are ignored, because the replaced text is skipped and its properties are not processed.

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

Note: Using :box face attribute (see Face Attributes) on a replacing display string that is adjacent to normal text with the same :box style can lead to display artifacts when moving the cursor across the text with this face attribute. These can be avoided by applying the :box attribute directly to the text being replaced, rather than (or in addition to) the display string itself. Here’s an example:

;; Causes display artifacts when moving the cursor across text
(progn
  (put-text-property 1 2 'display (propertize "  [" 'face '(:box t)))
  (put-text-property 2 3 'face '(:box t))
  (put-text-property 3 4 'display (propertize "]  " 'face '(:box t))))

;; No display artifacts due to `:box'
(progn
  (add-text-properties 1 2 '(face (:box t) display "  ["))
  (put-text-property 2 3 'face '(:box t))
  (add-text-properties 3 4 '(face (:box t) display "]  ")))

Next: Pixel Specification for Spaces, Previous: Display Specs That Replace The Text, Up: The display Property   [Contents][Index]

42.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 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 the column hpos. If hpos is a number, it is a column number, and is measured in units of the canonical character width (see Frame Font). hpos can also be a pixel width specification (see Pixel Specification for Spaces). When the current line is wider than the window, and is either displayed by one or more continuation lines, or is truncated and possibly scrolled horizontally (see Horizontal Scrolling), hpos is measured from the beginning of the logical line, not from the visual beginning of the screen line. This way, alignment produced by :align-to is consistent with functions that count columns, such as current-column and move-to-column (see Counting Columns). (There’s a single exception from this rule: when :align-to is used to specify whitespace of the wrap-prefix variable or text property, see Truncation.)

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 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 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 Bidirectional Display, for the details.

Next: Other Display Specifications, Previous: Specified Spaces, Up: The display Property   [Contents][Index]

42.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 | xwidget | 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; that binding can be either a number or a cons cell of the forms shown above (including yet another cons cell whose car is a symbol that has a buffer-local binding).

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 of the form (image . props) (see Image Descriptors) corresponds to the width or height of the specified image. Similarly, an xwidget specification of the form (xwidget . props) stands for the width or height of the specified xwidget. See Embedded Native Widgets.

The elements left-fringe, right-fringe, left-margin, right-margin, scroll-bar, and text specify the width of the corresponding area of the window. When the window displays line numbers (see Size of Displayed Text), the width of the text area is decreased by the screen space taken by the line-number display.

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. When the window displays line numbers, and :align-to is used in display properties of buffer text (as opposed to header line, see below), the left and the center positions are offset to account for the screen space taken by the line-number display.

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’ aligns with the first text column in the text area. When the window displays line numbers, the text is considered to start where the space used for line-number display ends.

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 (which should be given by its image spec).

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

Text shown in the header line that uses :align-to display specifications is not automatically realigned when display-line-numbers-mode is turned on and off, or when the width of line numbers on display changes. To arrange for the header-line text alignment to be updated, thus keeping the header-line text aligned with the buffer text, turn on the header-line-indent-mode in the buffer and use its two variables, header-line-indent and header-line-indent-width, in the display specification. See Window Header Lines. Here’s a simple example:

(setq header-line-format
      (concat (propertize " "
                          'display
                          '(space :align-to
                                  (+ header-line-indent-width 10)))
              "Column"))

This will keep the text ‘Column’ on the header line aligned with column 10 of buffer text, regardless of whether display-line-numbers-mode is on or off, and also when line-number display changes its width.

Next: Displaying in the Margins, Previous: Pixel Specification for Spaces, Up: The display Property   [Contents][Index]

42.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 Image Descriptors). 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. More precisely, the specification should have the following form:

 ((slice x y width height) image-desc)

where image-desc is an image descriptor described above. The elements x and y 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 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 face whose colors are to be used for the bitmap display. See Fringe Bitmaps, for the details.

It also possible to add context help for fringe bitmaps through the show-help-function mechanism by using left-fringe-help and right-fringe-help text properties (see Properties with Special Meanings).

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

(min-width (width))

This display specification ensures the text that has it takes at least width space on display, by adding a stretch of white space to the end of the text if the text is shorter than width. The text is partitioned using the identity of the parameter, which is why the parameter is a list with one element. For instance:

(insert (propertize "foo" 'display '(min-width (6.0))))

This will add padding after ‘foo’ bringing the total width up to the width of six normal characters. Note that the affected characters are identified by the (6.0) list in the display property, compared with eq. The element width can be either an integer or a float specifying the required minimum width of the text (see Pixel Specification for Spaces).

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

Note that condition will only be evaluated when redisplay examines the text where this display spec is located, so this feature is best suited for conditions that are relatively stable, i.e. yield, for each particular buffer position, the same results on every evaluation. If the results change for the same text location, e.g., if the result depends on the position of point, then the conditional specification might not do what you want, because redisplay examines only those parts of buffer text where it has reasons to assume that something changed since the last display cycle.

Previous: Other Display Specifications, Up: The display Property   [Contents][Index]

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

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 on that text an overlay with a before-string property, and put the margin display specification on the contents of the before-string.

Note that if the string to be displayed in the margin doesn’t fully specify its face, the nonspecified attributes are inherited from the margin face (see Basic Faces). If you want a margin string to have a specific appearance independent of the margin face, make sure the string has a face specifying all required attributes.

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. Do not use these variables to try to determine the current width of the left or right margin. Instead, use the function window-margins.

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

If window is not large enough to accommodate margins of the desired width, this leaves the margins of window unchanged.

The values specified here may be later overridden by invoking set-window-buffer (see Buffers and Windows) on window with its keep-margins argument nil or omitted.

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.

Next: Image Descriptors, Up: Images   [Contents][Index]

42.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. See Dynamically Loaded 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), JPEG (libjpeg), TIFF (libtiff), PNG (libpng), SVG (librsvg), and WebP (libwebp).

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

On some platforms, the built-in image support that doesn’t require any optional libraries includes BMP images.³⁴

Furthermore, if you build Emacs with ImageMagick (libMagickWand) support, Emacs can display any image format that ImageMagick can. See 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.

Next: XBM Images, Previous: Image Formats, Up: Images   [Contents][Index]

42.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 Other Display Specifications); but See 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.

Image descriptors which define image dimensions, :width, :height, :max-width and :max-height, may take either an integer, which represents the dimension in pixels, or a pair (value . em), where value is the dimension’s length in ems³⁵. One em is equivalent to the size of the font and value may be an integer or a float. Also, dimension can be specified in (value . ch) and (value . cw) forms, where ch means height of the canonical character and cw means width of the canonical character.

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 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 relative to each of the directories mentioned by image-load-path (see Defining Images).

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

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

If both :max-width and :height are specified, but :width is not, preserving the aspect ratio might require that width exceeds :max-width. If this happens, scaling will use a smaller value for the height so as to preserve the aspect ratio while not exceeding :max-width. Similarly when both :max-height and :width are specified, but :height is not. For example, if you have a 200x100 image and specify that :width should be 400 and :max-height should be 150, you’ll end up with an image that is 300x150: Preserving the aspect ratio and not exceeding the “max” setting. This combination of parameters is a useful way of saying “display this image as large as possible, but no larger than the available display area”.

:scale scale

This should be a scaling factor for the image, a number. Values higher than 1 mean to increase the image size, and lower values mean to decrease the size, by multiplying both the width and height of the image by the factor. For instance, a value of 0.25 will make the image a quarter size of what it originally was. If the scaling makes the image larger than specified by :max-width or :max-height, the resulting size will not exceed those two values. If both :scale and :height/:width are specified, the height/width will be adjusted by the specified scaling factor.

The value of scale can also be the symbol default, which means to use the value of image-scaling-factor. If that value is a number, it is the scale factor to use; if it is auto (the default), it means to compute the scaling factor based on pixel size of the font used by the frame’s default face (see Low-Level Font Representation). Specifically, if the pixel width of the default face’s font is greater than 10, the image is enlarged by the factor computed as the ratio of the font width to 10; if the font width is 10 pixels or less, the image is not scaled. For example, if the default font’s width is 15, the image will be scaled by the factor 1.5.

If scale is not provided, create-image scales the image according to the value of image-scaling-factor.

:rotation angle

Specifies a rotation angle in degrees. Only multiples of 90 degrees are supported, unless the image type is imagemagick. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping.

:flip flip

If this is t, the image will be horizontally flipped. Currently it has no effect if the image type is imagemagick. Vertical flipping can be achieved by rotating the image 180 degrees and toggling this value.

:transform-smoothing smooth

If this is t, any image transform will have smoothing applied; if nil, no smoothing will be applied. The exact algorithm used is platform dependent, but should be equivalent to bilinear filtering. Disabling smoothing will use the nearest neighbor algorithm.

If this property is not specified, create-image will use the image-transform-smoothing user option to say whether smoothing should be done or not. This option can be nil (no smoothing), t (use smoothing) or a predicate function that’s called with the image object as the only parameter, and should return either nil or t. The default is for down-scaling to apply smoothing, and for large up-scaling to not apply smoothing.

:index frame

See Multi-Frame Images.

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

Note that the map’s coordinates should reflect the displayed image after all transforms have been done (rotation, scaling and so on), and also note that Emacs (by default) performs auto-scaling of images, so to make things match up, you should either specify :scale 1.0 when creating the image, or use the result of image-compute-scaling-factor to compute the elements of the map.

When an image’s :scale, :rotation, or :flip is changed, :map will be recomputed based on the value of :original-map and the values of those transformation.

:original-map original-map ¶

This specifies the untransformed image map which will be used to recompute :map after the image’s :scale, :rotation, or :flip is changed.

If :original-map is not specified when creating an image with create-image, it will be computed based on the supplied :map, as well as any of :scale, :rotation, or :flip which are non-nil.

Conversely, if :original-map is specified but :map is not, :map will be computed based on :original-map, :scale, :rotation, and :flip.

User Option: image-recompute-map-p ¶

Set this user option to nil to prevent Emacs from automatically recomputing an image :map based on its :original-map.

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 (see Input Focus).

Function: image-transforms-p &optional frame ¶

This function returns non-nil if frame supports image scaling and rotation. frame nil or omitted means to use the selected frame (see Input Focus). The returned list includes symbols that indicate which image transform operations are supported:

scale

Image scaling is supported by frame via the :scale, :width, :height, :max-width, and :max-height properties.

rotate90

Image rotation is supported by frame if the rotation angle is an integral multiple of 90 degrees.

If image transforms are not supported, :rotation, :crop, :width, :height, :scale, :max-width and :max-height will only be usable through ImageMagick, if available (see ImageMagick Images).

Next: XPM Images, Previous: Image Descriptors, Up: Images   [Contents][Index]

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