47.1 Introduction to Extents

An extent is a region of text within a buffer or string that has certain properties associated with it. The properties of an extent primarily affect the way the text contained in the extent is displayed. Extents can freely overlap each other in a buffer or string. Extents are invisible to functions that merely examine the text of a buffer or string.

Please note: An alternative way to add properties to a buffer or string is to use text properties. See Text Properties.

An extent is logically a Lisp object consisting of a start position, an end position, a buffer or string to which these positions refer, and a property list. As text is inserted into a buffer, the start and end positions of the extent are automatically adjusted as necessary to keep the extent referring to the same text in the buffer. If text is inserted at the boundary of an extent, the extent’s start-open and end-open properties control whether the text is included as part of the extent. If the text bounded by an extent is deleted, the extent becomes detached; its start and end positions are no longer meaningful, but it maintains all its other properties and can later be reinserted into a buffer. (None of these considerations apply to strings, because text cannot be inserted into or deleted from a string.)

Each extent has a face or list of faces associated with it, which controls the way in which the text bounded by the extent is displayed. If an extent’s face is nil or its properties are partially undefined, the corresponding properties from the default face for the frame is used. If two or more extents overlap, or if a list of more than one face is specified for a particular extent, the corresponding faces are merged to determine the text’s displayed properties. Every extent has a priority that determines which face takes precedence if the faces conflict. (If two extents have the same priority, the one that comes later in the display order takes precedence. See display order.) Higher-numbered priority values correspond to a higher priority, and priority values can be negative. Every extent is created with a priority of 0, but this can be changed with set-extent-priority. Within a single extent with a list of faces, faces earlier in the list have a higher priority than faces later in the list.

Extents can be set to respond specially to key and mouse events within the extent. An extent’s keymap property controls the effect of key and mouse strokes within the extent’s text, and the mouse-face property controls whether the extent is highlighted when the mouse moves over it. See Extents and Events.

An extent can optionally have a begin-glyph or end-glyph associated with it. A begin-glyph or end-glyph is a pixmap or string that will be displayed either at the start or end of an extent or in the margin of the line that the start or end of the extent lies in, depending on the extent’s layout policy. Begin-glyphs and end-glyphs are used to implement annotations, and you should use the annotation API functions in preference to the lower-level extent functions. For more information, See Annotations.

If an extent has its detachable property set, it will become detached (i.e. no longer in the buffer) when all its text is deleted. Otherwise, it will simply shrink down to zero-length and sit in the same place in the buffer. By default, the detachable property is set on newly-created extents. See Detached Extents.

If an extent has its duplicable property set, it will be remembered when a string is created from text bounded by the extent. When the string is re-inserted into a buffer, the extent will also be re-inserted. This mechanism is used in the kill, yank, and undo commands. See Duplicable Extents.