GNU Info
(elisp)Special Properties
Properties with Special Meanings
--------------------------------
Here is a table of text property names that have special built-in
meanings. The following sections list a few additional special property
names that control filling and property inheritance. All other names
have no standard meaning, and you can use them as you like.
`category'
If a character has a `category' property, we call it the
"category" of the character. It should be a symbol. The
properties of the symbol serve as defaults for the properties of
the character.
`face'
You can use the property `face' to control the font and color of
text. 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.
Note: Font Lock Mode, for information on how to update `face'
properties automatically based on the contents of the text.
`mouse-face'
The property `mouse-face' is used instead of `face' when the mouse
is on or near the character. For this purpose, "near" means that
all text between the character and where the mouse is have the same
`mouse-face' property value.
`fontified'
This property, if non-`nil', says that text in the buffer has had
faces assigned automatically by a feature such as Font-Lock mode.
Note: Auto Faces.
`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 narrow, or replaced with an
image. Note: Display Property.
`help-echo'
If text has a string as its `help-echo' property, then when you
move the mouse onto that text, Emacs displays that string in the
echo area, or in the tooltip window.
If the value of the `help-echo' property is a function, that
function is called with three arguments, WINDOW, OBJECT and
POSITION and should return a help string or NIL for none. The
first argument, WINDOW is the window in which the help was found.
The second, OBJECT, is the buffer, overlay or string which had the
`help-echo' property. The POSITION argument is as follows:
* If OBJECT is a buffer, POS is the position in the buffer
where the `help-echo' text property was found.
* If OBJECT is an overlay, that overlay has a `help-echo'
property, and POS is the position in the overlay's buffer
under the mouse.
* If OBJECT is a string (an overlay string or a string displayed
with the `display' property), POS is the position in that
string under the mouse.
If the value of the `help-echo' property is neither a function nor
a string, it is evaluated to obtain a help string.
You can alter the way help text is displayed by setting the
variable `show-help-function' (Note: Help display).
This feature is used in the mode line and for other active text.
It is available starting in Emacs 21.
`local-map'
You can specify a different keymap for some of the text in a
buffer by means of the `local-map' property. The property's value
for the character after point, if non-`nil', is used for key
lookup instead of the buffer's local map. If the property value
is a symbol, the symbol's function definition is used as the
keymap. 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.
`syntax-table'
The `syntax-table' property overrides what the syntax table says
about this particular character. Note: Syntax Properties.
`read-only'
If a character has the property `read-only', then modifying that
character is not allowed. Any command that would do so gets an
error, `text-read-only'.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the `read-only' property due to
stickiness. Thus, you can control permission to insert next to
read-only text by controlling the stickiness. Note: Sticky
Properties.
Since changing properties counts as modifying the buffer, it is not
possible to remove a `read-only' property unless you know the
special trick: bind `inhibit-read-only' to a non-`nil' value and
then remove the property. Note: Read Only Buffers.
`invisible'
A non-`nil' `invisible' property can make a character invisible on
the screen. Note: Invisible Text, for details.
`intangible'
If a group of consecutive characters have equal and non-`nil'
`intangible' properties, then you cannot place point between them.
If you try to move point forward into the group, point actually
moves to the end of the group. If you try to move point backward
into the group, point actually moves to the start of the group.
When the variable `inhibit-point-motion-hooks' is non-`nil', the
`intangible' property is ignored.
`field'
Consecutive characters with the same `field' property constitute a
"field". Some motion functions including `forward-word' and
`beginning-of-line' stop moving at a field boundary. Note:
Fields.
`modification-hooks'
If a character has the property `modification-hooks', then its
value should be a list of functions; modifying that character
calls all of those functions. Each function receives two
arguments: the beginning and end of the part of the buffer being
modified. Note that if a particular modification hook function
appears on several characters being modified by a single
primitive, you can't predict how many times the function will be
called.
`insert-in-front-hooks'
`insert-behind-hooks'
The operation of inserting text in a buffer also calls the
functions listed in the `insert-in-front-hooks' property of the
following character and in the `insert-behind-hooks' property of
the preceding character. These functions receive two arguments,
the beginning and end of the inserted text. The functions are
called _after_ the actual insertion takes place.
See also Note: Change Hooks, for other hooks that are called
when you change text in a buffer.
`point-entered'
`point-left'
The special properties `point-entered' and `point-left' record
hook functions that report motion of point. Each time point
moves, Emacs compares these two property values:
* the `point-left' property of the character after the old
location, and
* the `point-entered' property of the character after the new
location.
If these two values differ, each of them is called (if not `nil')
with two arguments: the old value of point, and the new one.
The same comparison is made for the characters before the old and
new locations. The result may be to execute two `point-left'
functions (which may be the same function) and/or two
`point-entered' functions (which may be the same function). In
any case, all the `point-left' functions are called first,
followed by all the `point-entered' functions.
It is possible using `char-after' to examine characters at various
positions without moving point to those positions. Only an actual
change in the value of point runs these hook functions.
- Variable: inhibit-point-motion-hooks
When this variable is non-`nil', `point-left' and `point-entered'
hooks are not run, and the `intangible' property has no effect.
Do not set this variable globally; bind it with `let'.
- Variable: show-help-function
If this variable is non-`nil', it specifies a function called to
display help strings. These may be `help-echo' properties, menu
help strings (Note: Simple Menu Items, Note: Extended Menu
Items), or tool bar help strings (Note: Tool Bar). The
specified function is called with one argument, the help string to
display. Tooltip mode (Note: Tooltips.) provides
an example.
automatically generated by info2www version 1.2.2.9