31.19.4 Properties with Special Meanings

Here is a table of text property names that have special built-in meanings. The following sections list a few additional special property names that control filling and property inheritance. All other names have no standard meaning, and you can use them as you like.

Note: the properties composition, display, invisible and intangible can also cause point to move to an acceptable place, after each Emacs command. See Adjusting Point.

category

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

face

The face property controls the appearance of the character (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.

Font Lock mode (see Font Lock Mode) works in most buffers by dynamically updating the face property of characters based on the context.

The add-face-text-property function provides a convenient way to set this text property. See Changing Properties.

font-lock-face

This property specifies a value for the face property that Font Lock mode should apply to the underlying text. It is one of the fontification methods used by Font Lock mode, and is useful for special modes that implement their own highlighting. See Precalculated Fontification. When Font Lock mode is disabled, font-lock-face has no effect.

mouse-face

This property is used instead of face when the mouse is on or near the character. For this purpose, “near” means that all text between the character and where the mouse is have the same mouse-face property value.

Emacs ignores all face attributes from the mouse-face property that alter the text size (e.g., :height, :weight, and :slant). Those attributes are always the same as for the unhighlighted text.

fontified

This property says whether the text is ready for display. If nil, Emacs’s redisplay routine calls the functions in fontification-functions (see Auto Faces) to prepare this part of the buffer before it is displayed. It is used internally by the “just in time” font locking code.

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 narrow, or replaced with an image. See Display Property.

help-echo

If text has a string as its help-echo property, then when you move the mouse onto that text, Emacs displays that string in the echo area, or in the tooltip window (see Tooltips in The GNU Emacs Manual).

If the value of the help-echo property is a function, that function is called with three arguments, window, object and pos and should return a help string or nil for none. The first argument, window is the window in which the help was found. The second, object, is the buffer, overlay or string which had the help-echo property. The pos argument is as follows:

• If object is a buffer, pos is the position in the buffer.
• If object is an overlay, that overlay has a help-echo property, and pos is the position in the overlay’s buffer.
• If object is a string (an overlay string or a string displayed with the display property), pos is the position in that string.

If the value of the help-echo property is neither a function nor a string, it is evaluated to obtain a help string.

You can alter the way help text is displayed by setting the variable show-help-function (see Help display).

This feature is used in the mode line and for other active text.

keymap

The keymap property specifies an additional keymap for commands. When this keymap applies, it is used for key lookup before the minor mode keymaps and before the buffer’s local map. See Active Keymaps. If the property value is a symbol, the symbol’s function definition is used as the keymap.

The property’s value for the character before point applies if it is non-nil and rear-sticky, and the property’s value for the character after point applies if it is non-nil and front-sticky. (For mouse clicks, the position of the click is used instead of the position of point.)

local-map

This property works like keymap except that it specifies a keymap to use instead of the buffer’s local map. For most purposes (perhaps all purposes), it is better to use the keymap property.

syntax-table

The syntax-table property overrides what the syntax table says about this particular character. See Syntax Properties.

read-only

If a character has the property read-only, then modifying that character is not allowed. Any command that would do so gets an error, text-read-only. If the property value is a string, that string is used as the error message.

Insertion next to a read-only character is an error if inserting ordinary text there would inherit the read-only property due to stickiness. Thus, you can control permission to insert next to read-only text by controlling the stickiness. See Sticky Properties.

Since changing properties counts as modifying the buffer, it is not possible to remove a read-only property unless you know the special trick: bind inhibit-read-only to a non-nil value and then remove the property. See Read Only Buffers.

invisible

A non-nil invisible property can make a character invisible on the screen. See Invisible Text, for details.

intangible

If a group of consecutive characters have equal and non-nil intangible properties, then you cannot place point between them. If you try to move point forward into the group, point actually moves to the end of the group. If you try to move point backward into the group, point actually moves to the start of the group.

If consecutive characters have unequal non-nil intangible properties, they belong to separate groups; each group is separately treated as described above.

When the variable inhibit-point-motion-hooks is non-nil, the intangible property is ignored.

Beware: this property operates at a very low level, and affects a lot of code in unexpected ways. So use it with extreme caution. A common misuse is to put an intangible property on invisible text, which is actually unnecessary since the command loop will move point outside of the invisible text at the end of each command anyway. See Adjusting Point.

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

cursor

Normally, the cursor is displayed at the beginning or the end of any overlay and text property strings present at the current buffer position. You can place the cursor on any desired character of these strings by giving that character a non-nil cursor text property. In addition, if the value of the cursor property is an integer, it specifies the number of buffer’s character positions, starting with the position where the overlay or the display property begins, for which the cursor should be displayed on that character. Specifically, if the value of the cursor property of a character is the number n, the cursor will be displayed on this character for any buffer position in the range [ovpos..ovpos+n), where ovpos is the overlay’s starting position given by overlay-start (see Managing Overlays), or the position where the display text property begins in the buffer.

In other words, the string character with the cursor property of any non-nil value is the character where to display the cursor. The value of the property says for which buffer positions to display the cursor there. If the value is an integer n, the cursor is displayed there when point is anywhere between the beginning of the overlay or display property and n positions after that. If the value is anything else and non-nil, the cursor is displayed there only when point is at the beginning of the display property or at overlay-start.

When the buffer has many overlay strings (e.g., see before-string) or display properties that are strings, it is a good idea to use the cursor property on these strings to cue the Emacs display about the places where to put the cursor while traversing these strings. This directly communicates to the display engine where the Lisp program wants to put the cursor, or where the user would expect the cursor.

pointer

This specifies a specific pointer shape when the mouse pointer is over this text or image. See Pointer Shape, for possible pointer shapes.

line-spacing

A newline can have a line-spacing text or overlay property that controls the height of the display line ending with that newline. The property value overrides the default frame line spacing and the buffer local line-spacing variable. See Line Height.

line-height

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

wrap-prefix

If text has a wrap-prefix property, the prefix it defines will be added at display time to the beginning of every continuation line due to text wrapping (so if lines are truncated, the wrap-prefix is never used). It may be a string or an image (see Other Display Specs), or a stretch of whitespace such as specified by the :width or :align-to display properties (see Specified Space).

A wrap-prefix may also be specified for an entire buffer using the wrap-prefix buffer-local variable (however, a wrap-prefix text-property takes precedence over the value of the wrap-prefix variable). See Truncation.

line-prefix

If text has a line-prefix property, the prefix it defines will be added at display time to the beginning of every non-continuation line. It may be a string or an image (see Other Display Specs), or a stretch of whitespace such as specified by the :width or :align-to display properties (see Specified Space).

A line-prefix may also be specified for an entire buffer using the line-prefix buffer-local variable (however, a line-prefix text-property takes precedence over the value of the line-prefix variable). See Truncation.

modification-hooks

If a character has the property modification-hooks, then its value should be a list of functions; modifying that character calls all of those functions before the actual modification. Each function receives two arguments: the beginning and end of the part of the buffer being modified. Note that if a particular modification hook function appears on several characters being modified by a single primitive, you can’t predict how many times the function will be called. Furthermore, insertion will not modify any existing character, so this hook will only be run when removing some characters, replacing them with others, or changing their text-properties.

If these functions modify the buffer, they should bind inhibit-modification-hooks to t around doing so, to avoid confusing the internal mechanism that calls these hooks.

Overlays also support the modification-hooks property, but the details are somewhat different (see Overlay Properties).

insert-in-front-hooks

insert-behind-hooks

The operation of inserting text in a buffer also calls the functions listed in the insert-in-front-hooks property of the following character and in the insert-behind-hooks property of the preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called after the actual insertion takes place.

See also Change Hooks, for other hooks that are called when you change text in a buffer.

point-entered

point-left

The special properties point-entered and point-left record hook functions that report motion of point. Each time point moves, Emacs compares these two property values:

• the point-left property of the character after the old location, and
• the point-entered property of the character after the new location.

If these two values differ, each of them is called (if not nil) with two arguments: the old value of point, and the new one.

The same comparison is made for the characters before the old and new locations. The result may be to execute two point-left functions (which may be the same function) and/or two point-entered functions (which may be the same function). In any case, all the point-left functions are called first, followed by all the point-entered functions.

It is possible to use char-after to examine characters at various buffer positions without moving point to those positions. Only an actual change in the value of point runs these hook functions.

The variable inhibit-point-motion-hooks can inhibit running the point-left and point-entered hooks, see Inhibit point motion hooks.

composition

This text property is used to display a sequence of characters as a single glyph composed from components. But the value of the property itself is completely internal to Emacs and should not be manipulated directly by, for instance, put-text-property.

Variable: inhibit-point-motion-hooks

When this variable is non-nil, point-left and point-entered hooks are not run, and the intangible property has no effect. Do not set this variable globally; bind it with let.

Variable: show-help-function

If this variable is non-nil, it specifies a function called to display help strings. These may be help-echo properties, menu help strings (see Simple Menu Items, see Extended Menu Items), or tool bar help strings (see Tool Bar). The specified function is called with one argument, the help string to display. Tooltip mode (see Tooltips in The GNU Emacs Manual) provides an example.