GNU Info

(elisp)Overlay Properties

---

Next: Managing Overlays Up: Overlays

---

Enter node , (file) or (file)node

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.  Text properties are
considered a part of the text; overlays 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 changes are not recorded in the
buffer's undo list.  Note: Text Properties, for comparison.

   These functions are used for reading and writing 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.

   See also the function `get-char-property' which checks both overlay
properties and text properties for a given character.  Note: Examining
Properties.

   Many overlay properties have special meanings; here is a table of
them:

`priority'
     This property's value (which should be a nonnegative number)
     determines the priority of the overlay.  The priority matters when
     two or more overlays cover the same character and both specify a
     face for display; the one whose `priority' value is larger takes
     priority over the other, and its face attributes override the face
     attributes of the lower priority overlay.

     Currently, all overlays take priority over text properties.  Please
     avoid using negative priority values, as we have not yet decided
     just what they should mean.

`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 way text is displayed--for example,
     which font and which colors.  Note: Faces, for more information.

     In the simplest case, the value is a face name.  It can also be a
     list; then each element can be any of these possibilities:

        * A face name (a symbol or string).

        * Starting in Emacs 21, a property list of face attributes.
          This has the form (KEYWORD VALUE ...), where each KEYWORD is a
          face attribute name and VALUE is a meaningful value for that
          attribute.  With this feature, you do not need to create a
          face each time you want to specify a particular attribute for
          certain text.  Note: Face Attributes.

        * A cons cell of the form `(foreground-color . COLOR-NAME)' or
          `(background-color . COLOR-NAME)'.  These elements specify
          just the foreground color or just the background color.

          `(foreground-color . COLOR-NAME)' is equivalent to
          `(:foreground COLOR-NAME)', and likewise for the background.

`mouse-face'
     This property is used instead of `face' when the mouse is within
     the range of the overlay.

`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.  Note: Display Property.

`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 in the tooltip window.  For details see Note:
     Text help-echo.  This feature is available starting in Emacs 21.

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

`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.
     Note: Invisible Text, for details.

`intangible'
     The `intangible' property on an overlay works just like the
     `intangible' text property.  Note: Special Properties, for
     details.

`isearch-open-invisible'
     This property tells incremental search how to make an invisible
     overlay visible, permanently, if the final match overlaps it.
     Note: Invisible Text.

`isearch-open-invisible-temporary'
     This property tells incremental search how to make an invisible
     overlay visible, temporarily, during the search.  Note: 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.

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

`evaporate'
     If this property is non-`nil', the overlay is deleted automatically
     if it ever becomes empty (i.e., if it spans no characters).

`local-map'
     If this property is non-`nil', it specifies a keymap for a portion
     of the text.  The property's value replaces the buffer's local
     map, when the character after point is within the overlay.  Note:
     Active Keymaps.

`keymap'
     The `keymap' property is similar to `local-map' but overrides the
     buffer's local map (and the map specified by the `local-map'
     property) rather than replacing it.