www.delorie.com/gnu/docs/elisp-manual-21/elisp_527.html   search  
Buy the book!

GNU Emacs Lisp Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

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

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.

You can use the property face to control the font and color of text. See section 38.11 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;

See section 23.5 Font Lock Mode, for information on how to update face properties automatically based on the contents of the text.

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.

This property, if non-nil, says that text in the buffer has had faces assigned automatically by a feature such as Font-Lock mode. See section 38.11.8 Automatic Face Assignment.

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. See section 38.12 The display Property.

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 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 (see Help display).

This feature is used in the mode line and for other active text. It is available starting in Emacs 21.

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. See section 22.6 Active Keymaps.

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.

The syntax-table property overrides what the syntax table says about this particular character. See section 35.4 Syntax Properties.

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. See section 32.19.6 Stickiness of Text 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. See section 27.7 Read-Only Buffers.

A non-nil invisible property can make a character invisible on the screen. See section 38.5 Invisible Text, for details.

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.

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. See section 32.19.10 Defining and Using Fields.

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.

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 32.25 Change Hooks, for other hooks that are called when you change text in a buffer.

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:

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 (see section Simple Menu Items, see section Extended Menu Items), or tool bar help strings (see section 22.12.6 Tool bars). The specified function is called with one argument, the help string to display. Tooltip mode (see section `Tooltips' in The GNU Emacs Manual) provides an example.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003