elisp: Sticky Properties
31.19.6 Stickiness of Text Properties
-------------------------------------
Self-inserting characters, the ones that get inserted into a buffer when
the user types them (Commands for Insertion), normally take on
the same properties as the preceding character. This is called
“inheritance” of properties.
By contrast, a Lisp program can do insertion with inheritance or
without, depending on the choice of insertion primitive. The ordinary
text insertion functions, such as ‘insert’, do not inherit any
properties. They insert text with precisely the properties of the
string being inserted, and no others. This is correct for programs that
copy text from one context to another—for example, into or out of the
kill ring. To insert with inheritance, use the special primitives
described in this section. Self-inserting characters inherit properties
because they work using these primitives.
When you do insertion with inheritance, _which_ properties are
inherited, and from where, depends on which properties are “sticky”.
Insertion after a character inherits those of its properties that are
“rear-sticky”. Insertion before a character inherits those of its
properties that are “front-sticky”. When both sides offer different
sticky values for the same property, the previous character’s value
takes precedence.
By default, a text property is rear-sticky but not front-sticky;
thus, the default is to inherit all the properties of the preceding
character, and nothing from the following character.
You can control the stickiness of various text properties with two
specific text properties, ‘front-sticky’ and ‘rear-nonsticky’, and with
the variable ‘text-property-default-nonsticky’. You can use the
variable to specify a different default for a given property. You can
use those two text properties to make any specific properties sticky or
nonsticky in any particular part of the text.
If a character’s ‘front-sticky’ property is ‘t’, then all its
properties are front-sticky. If the ‘front-sticky’ property is a list,
then the sticky properties of the character are those whose names are in
the list. For example, if a character has a ‘front-sticky’ property
whose value is ‘(face read-only)’, then insertion before the character
can inherit its ‘face’ property and its ‘read-only’ property, but no
others.
The ‘rear-nonsticky’ property works the opposite way. Most
properties are rear-sticky by default, so the ‘rear-nonsticky’ property
says which properties are _not_ rear-sticky. If a character’s
‘rear-nonsticky’ property is ‘t’, then none of its properties are
rear-sticky. If the ‘rear-nonsticky’ property is a list, properties are
rear-sticky _unless_ their names are in the list.
-- Variable: text-property-default-nonsticky
This variable holds an alist which defines the default
rear-stickiness of various text properties. Each element has the
form ‘(PROPERTY . NONSTICKINESS)’, and it defines the stickiness of
a particular text property, PROPERTY.
If NONSTICKINESS is non-‘nil’, this means that the property
PROPERTY is rear-nonsticky by default. Since all properties are
front-nonsticky by default, this makes PROPERTY nonsticky in both
directions by default.
The text properties ‘front-sticky’ and ‘rear-nonsticky’, when used,
take precedence over the default NONSTICKINESS specified in
‘text-property-default-nonsticky’.
Here are the functions that insert text with inheritance of
properties:
-- Function: insert-and-inherit &rest strings
Insert the strings STRINGS, just like the function ‘insert’, but
inherit any sticky properties from the adjoining text.
-- Function: insert-before-markers-and-inherit &rest strings
Insert the strings STRINGS, just like the function
‘insert-before-markers’, but inherit any sticky properties from the
adjoining text.
Insertion, for the ordinary insertion functions which do not
inherit.