+File: lispref.info, Node: Extent Properties, Next: Detached Extents, Prev: Mapping Over Extents, Up: Extents
+
+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. *Note 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'. *Note 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. *Note
+ priority: Intro to Extents. 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. *Note 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. *Note 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. *Note
+ 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. *Note Mouse Pointer::.
+
+`detachable'
+ (Boolean) Whether this extent becomes detached when all of the
+ text it covers is deleted. This is `t' by default. *Note
+ Detached Extents::.
+
+`duplicable'
+ (Boolean) Whether this extent should be copied into strings, so
+ that kill, yank, and undo commands will restore or copy it. *Note
+ 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. *Note Duplicable Extents::.
+
+`invisible'
+ (Boolean) If `t', text under this extent will not be displayed -
+ it will look as if the text is not there at all.
+
+`keymap'
+ (keymap or `nil') This keymap is consulted for mouse clicks on this
+ extent or keypresses made while `point' is within the extent.
+ *Note 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). *Note
+ 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. *Note
+ Duplicable Extents::.
+
+`begin-glyph'
+ (glyph or `nil') This extent's begin glyph. *Note Annotations::.
+
+`end-glyph'
+ (glyph or `nil') This extent's end glyph. *Note Annotations::.
+
+`begin-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's begin glyph. Defaults to `text'.
+ *Note Annotations::.
+
+`end-glyph-layout'
+ (`text', `whitespace', `inside-margin', or `outside-margin') The
+ layout policy for this extent's end glyph. Defaults to `text'.
+ *Note 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.