47.6 Properties of Extents

Each extent has a property list associating property names with values. Some property names have predefined meanings, and can usually only assume particular values. Assigning other values to such a property either cause the value to be converted into a legal value (e.g., assigning anything but nil to a Boolean property will cause the value of t to be assigned to the property) or will cause an error. Property names without predefined meanings can be assigned any value. An undefined property is equivalent to a property with a value of nil, or with a particular default value in the case of properties with predefined meanings. Note that, when an extent is created, the end-open and detachable properties are set on it.

If an extent has a parent, all of its properties actually derive from that parent (or from the root ancestor if the parent in turn has a parent), and setting a property of the extent actually sets that property on the parent. See Extent Parents.

Function: extent-property extent property &optional default

This function returns extent’s value for property, or default if no such property exists.

Function: extent-properties extent

This function returns a list of all of extent’s properties that do not have the value of nil (or the default value, for properties with predefined meanings).

Function: set-extent-property extent property value

This function sets property to value in extent. (If property has a predefined meaning, only certain values are allowed, and some values may be converted to others before being stored.)

Function: set-extent-properties extent plist

Change some properties of extent. plist is a property list. This is useful to change many extent properties at once.

The following table lists the properties with predefined meanings, along with their allowable values.

detached

(Boolean) Whether the extent is detached. Setting this is the same as calling detach-extent. See Detached Extents.

destroyed

(Boolean) Whether the extent has been deleted. Setting this is the same as calling delete-extent.

priority

(integer) The extent’s redisplay priority. Defaults to 0. See priority. This property can also be set with set-extent-priority and accessed with extent-priority.

start-open

(Boolean) Whether the start position of the extent is open, meaning that characters inserted at that position go outside of the extent. See Extent Endpoints.

start-closed

(Boolean) Same as start-open but with the opposite sense. Setting this property clears start-open and vice-versa.

end-open

(Boolean) Whether the end position of the extent is open, meaning that characters inserted at that position go outside of the extent. This is t by default. See Extent Endpoints.

end-closed

(Boolean) Same as end-open but with the opposite sense. Setting this property clears end-open and vice-versa.

read-only

(Boolean) Whether text within this extent will be unmodifiable.

face

(face, face name, list of faces or face names, or nil) The face in which to display the extent’s text. This property can also be set with set-extent-face and accessed with extent-face. Note that if a list of faces is specified, the faces are merged together, with faces earlier in the list having priority over faces later in the list.

mouse-face

(face, face name, list of faces or face names, or nil) The face used to display the extent when the mouse moves over it. This property can also be set with set-extent-mouse-face and accessed with extent-mouse-face. Note that if a list of faces is specified, the faces are merged together, with faces earlier in the list having priority over faces later in the list. See Extents and Events.

pointer

(pointer glyph) The glyph used as the pointer when the mouse moves over the extent. This takes precedence over the text-pointer-glyph and nontext-pointer-glyph variables. If for any reason this glyph is an invalid pointer, the standard glyphs will be used as fallbacks. See External Glyphs.

detachable

(Boolean) Whether this extent becomes detached when all of the text it covers is deleted. This is t by default. See Detached Extents.

duplicable

(Boolean) Whether this extent should be copied into strings, so that kill, yank, and undo commands will restore or copy it. See Duplicable Extents.

unique

(Boolean) Meaningful only in conjunction with duplicable. When this is set, there may be only one instance of this extent attached at a time. See Duplicable Extents.

invisible

(Boolean) If t, text under this extent will not be displayed – it will look as if the text and the begin-glyph is not there at all. The end-glyph will still be displayed.

keymap

(keymap or nil) This keymap is consulted for mouse clicks on this extent or keypresses made while point is within the extent. See Extents and Events.

copy-function

This is a hook that is run when a duplicable extent is about to be copied from a buffer to a string (or the kill ring). See Duplicable Extents.

paste-function

This is a hook that is run when a duplicable extent is about to be copied from a string (or the kill ring) into a buffer. See Duplicable Extents.

begin-glyph

(glyph or nil) This extent’s begin glyph. See Annotations.

end-glyph

(glyph or nil) This extent’s end glyph. See Annotations.

begin-glyph-layout

(text, whitespace, inside-margin, or outside-margin) The layout policy for this extent’s begin glyph. Defaults to text. See Annotations.

end-glyph-layout

(text, whitespace, inside-margin, or outside-margin) The layout policy for this extent’s end glyph. Defaults to text. See Annotations.

initial-redisplay-function

(any funcallable object) The function to be called the first time (a part of) the extent is redisplayed. It will be called with the extent as its argument.

This is used by lazy-shot to implement lazy font-locking. The functionality is still experimental, and may change without further notice.

The following convenience functions are provided for accessing particular properties of an extent.

Function: extent-face extent

This function returns the face property of extent. This might also return a list of face names. Do not modify this list directly! Instead, use set-extent-face.

Note that you can use eq to compare lists of faces as returned by extent-face. In other words, if you set the face of two different extents to two lists that are equal but not eq, then the return value of extent-face on the two extents will return the identical list.

Function: extent-mouse-face extent

This function returns the mouse-face property of extent. This might also return a list of face names. Do not modify this list directly! Instead, use set-extent-mouse-face.

Note that you can use eq to compare lists of faces as returned by extent-mouse-face, just like for extent-face.

Function: extent-priority extent

This function returns the priority property of extent.

Function: extent-keymap extent

This function returns the keymap property of extent.

Function: extent-begin-glyph-layout extent

This function returns the begin-glyph-layout property of extent, i.e. the layout policy associated with the extent’s begin glyph.

Function: extent-end-glyph-layout extent

This function returns the end-glyph-layout property of extent, i.e. the layout policy associated with the extent’s end glyph.

Function: extent-begin-glyph extent

This function returns the begin-glyph property of extent, i.e. the glyph object displayed at the beginning of extent. If there is none, nil is returned.

Function: extent-end-glyph extent

This function returns the end-glyph property of extent, i.e. the glyph object displayed at the end of extent. If there is none, nil is returned.

The following convenience functions are provided for setting particular properties of an extent.

Function: set-extent-priority extent priority

This function sets the priority property of extent to priority.

Function: set-extent-face extent face

This function sets the face property of extent to face.

Function: set-extent-mouse-face extent face

This function sets the mouse-face property of extent to face.

Function: set-extent-keymap extent keymap

This function sets the keymap property of extent to keymap. keymap must be either a keymap object, or nil.

Function: set-extent-begin-glyph-layout extent layout

This function sets the begin-glyph-layout property of extent to layout.

Function: set-extent-end-glyph-layout extent layout

This function sets the end-glyph-layout property of extent to layout.

Function: set-extent-begin-glyph extent begin-glyph &optional layout

This function sets the begin-glyph and glyph-layout properties of extent to begin-glyph and layout, respectively. (layout defaults to text if not specified.)

Function: set-extent-end-glyph extent end-glyph &optional layout

This function sets the end-glyph and glyph-layout properties of extent to end-glyph and layout, respectively. (layout defaults to text if not specified.)

Function: set-extent-initial-redisplay-function extent function

This function sets the initial-redisplay-function property of the extent to function.