diff options
Diffstat (limited to 'devdocs/elisp/special-properties.html')
| -rw-r--r-- | devdocs/elisp/special-properties.html | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/devdocs/elisp/special-properties.html b/devdocs/elisp/special-properties.html new file mode 100644 index 00000000..43c2b4fd --- /dev/null +++ b/devdocs/elisp/special-properties.html @@ -0,0 +1,57 @@ + <h4 class="subsection">Properties with Special Meanings</h4> <p>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. </p> <p>Note: the properties <code>composition</code>, <code>display</code>, <code>invisible</code> and <code>intangible</code> can also cause point to move to an acceptable place, after each Emacs command. See <a href="adjusting-point">Adjusting Point</a>. </p> <dl compact> <dt><code>category</code></dt> <dd> +<p>If a character has a <code>category</code> property, we call it the <em>property category</em> of the character. It should be a symbol. The properties of this symbol serve as defaults for the properties of the character. </p> </dd> <dt><code>face</code></dt> <dd> + <p>The <code>face</code> property controls the appearance of the character (see <a href="faces">Faces</a>). The value of the property can be the following: </p> <ul> <li> A face name (a symbol or string). </li> +<li> An anonymous face: a property list of the form <code>(<var>keyword</var> +<var>value</var> …)</code>, where each <var>keyword</var> is a face attribute name and <var>value</var> is a value for that attribute. </li> +<li> A list of faces. Each list element should be either a face name or an anonymous face. This specifies a face which is an aggregate of the attributes of each of the listed faces. Faces occurring earlier in the list have higher priority. </li> +<li> A cons cell of the form <code>(foreground-color . <var>color-name</var>)</code> or <code>(background-color . <var>color-name</var>)</code>. This specifies the foreground or background color, similar to <code>(:foreground +<var>color-name</var>)</code> or <code>(:background <var>color-name</var>)</code>. This form is supported for backward compatibility only, and should be avoided. </li> +<li> A cons cell of the form <code>(:filtered <var>filter</var> <var><span class="nolinebreak">face-spec</span></var>)</code>, that specifies the face given by <var>face-spec</var>, but only if <var>filter</var> matches when the face is used for display. The <var>face-spec</var> can use any of the forms mentioned above. The <var>filter</var> should be of the form <code>(:window <var>param</var> <var>value</var>)</code>, which matches for windows whose parameter <var>param</var> is <code>eq</code> to <var>value</var>. If the variable <code>face-filters-always-match</code> is non-<code>nil</code>, all face filters are deemed to have matched. </li> +</ul> <p>Font Lock mode (see <a href="font-lock-mode">Font Lock Mode</a>) works in most buffers by dynamically updating the <code>face</code> property of characters based on the context. </p> <p>The <code>add-face-text-property</code> function provides a convenient way to set this text property. See <a href="changing-properties">Changing Properties</a>. </p> </dd> <dt><code>font-lock-face</code></dt> <dd> + <p>This property specifies a value for the <code>face</code> property that Font Lock mode should apply to the underlying text. It is one of the fontification methods used by Font Lock mode, and is useful for special modes that implement their own highlighting. See <a href="precalculated-fontification">Precalculated Fontification</a>. When Font Lock mode is disabled, <code>font-lock-face</code> has no effect. </p> </dd> <dt><code>mouse-face</code></dt> <dd> + <p>This property is used instead of <code>face</code> 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 <code>mouse-face</code> property value. </p> <p>Emacs ignores all face attributes from the <code>mouse-face</code> property that alter the text size (e.g., <code>:height</code>, <code>:weight</code>, and <code>:slant</code>). Those attributes are always the same as for the unhighlighted text. </p> </dd> <dt><code>fontified</code></dt> <dd> + <p>This property says whether the text is ready for display. If <code>nil</code>, Emacs’s redisplay routine calls the functions in <code>fontification-functions</code> (see <a href="auto-faces">Auto Faces</a>) to prepare this part of the buffer before it is displayed. It is used internally by the just-in-time font locking code. </p> </dd> <dt><code>display</code></dt> <dd> +<p>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 <a href="display-property">Display Property</a>. </p> </dd> <dt><code>help-echo</code></dt> <dd> + <p>If text has a string as its <code>help-echo</code> property, then when you move the mouse onto that text, Emacs displays that string in the echo area, or in the tooltip window (see <a href="tooltips">Tooltips</a>), after passing it through <code>substitute-command-keys</code>. </p> <p>If the value of the <code>help-echo</code> property is a function, that function is called with three arguments, <var>window</var>, <var>object</var> and <var>pos</var> and should return a help string or <code>nil</code> for none. The first argument, <var>window</var> is the window in which the help was found. The second, <var>object</var>, is the buffer, overlay or string which had the <code>help-echo</code> property. The <var>pos</var> argument is as follows: </p> <ul> <li> If <var>object</var> is a buffer, <var>pos</var> is the position in the buffer. </li> +<li> If <var>object</var> is an overlay, that overlay has a <code>help-echo</code> property, and <var>pos</var> is the position in the overlay’s buffer. </li> +<li> If <var>object</var> is a string (an overlay string or a string displayed with the <code>display</code> property), <var>pos</var> is the position in that string. </li> +</ul> <p>If the value of the <code>help-echo</code> property is neither a function nor a string, it is evaluated to obtain a help string. </p> <p>You can alter the way help text is displayed by setting the variable <code>show-help-function</code> (see <a href="#Help-display">Help display</a>). </p> <p>This feature is used in the mode line and for other active text. </p> </dd> <dt><code>help-echo-inhibit-substitution</code></dt> <dd> + <p>If the first character of a <code>help-echo</code> string has a non-<code>nil</code> <code>help-echo-inhibit-substitution</code> property, then it is displayed as-is by <code>show-help-function</code>, without being passed through <code>substitute-command-keys</code>. </p> </dd> <dt><code>keymap</code></dt> <dd> + <p>The <code>keymap</code> property specifies an additional keymap for commands. When this keymap applies, it is used for key lookup before the minor mode keymaps and before the buffer’s local map. See <a href="active-keymaps">Active Keymaps</a>. If the property value is a symbol, the symbol’s function definition is used as the keymap. </p> <p>The property’s value for the character before point applies if it is non-<code>nil</code> and rear-sticky, and the property’s value for the character after point applies if it is non-<code>nil</code> and front-sticky. (For mouse clicks, the position of the click is used instead of the position of point.) </p> </dd> <dt><code>local-map</code></dt> <dd> + <p>This property works like <code>keymap</code> except that it specifies a keymap to use <em>instead of</em> the buffer’s local map. For most purposes (perhaps all purposes), it is better to use the <code>keymap</code> property. </p> </dd> <dt><code>syntax-table</code></dt> <dd> +<p>The <code>syntax-table</code> property overrides what the syntax table says about this particular character. See <a href="syntax-properties">Syntax Properties</a>. </p> </dd> <dt><code>read-only</code></dt> <dd> + <p>If a character has the property <code>read-only</code>, then modifying that character is not allowed. Any command that would do so gets an error, <code>text-read-only</code>. If the property value is a string, that string is used as the error message. </p> <p>Insertion next to a read-only character is an error if inserting ordinary text there would inherit the <code>read-only</code> property due to stickiness. Thus, you can control permission to insert next to read-only text by controlling the stickiness. See <a href="sticky-properties">Sticky Properties</a>. </p> <p>Since changing properties counts as modifying the buffer, it is not possible to remove a <code>read-only</code> property unless you know the special trick: bind <code>inhibit-read-only</code> to a non-<code>nil</code> value and then remove the property. See <a href="read-only-buffers">Read Only Buffers</a>. </p> </dd> <dt><code>inhibit-read-only</code></dt> <dd> + <p>Characters that have the property <code>inhibit-read-only</code> can be edited even in read-only buffers. See <a href="read-only-buffers">Read Only Buffers</a>. </p> </dd> <dt><code>invisible</code></dt> <dd> + <p>A non-<code>nil</code> <code>invisible</code> property can make a character invisible on the screen. See <a href="invisible-text">Invisible Text</a>, for details. </p> </dd> <dt><code>intangible</code></dt> <dd> + <p>If a group of consecutive characters have equal and non-<code>nil</code> <code>intangible</code> 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. </p> <p>If consecutive characters have unequal non-<code>nil</code> <code>intangible</code> properties, they belong to separate groups; each group is separately treated as described above. </p> <p>When the variable <code>inhibit-point-motion-hooks</code> is non-<code>nil</code> (as it is by default), the <code>intangible</code> property is ignored. </p> <p>Beware: this property operates at a very low level, and affects a lot of code in unexpected ways. So use it with extreme caution. A common misuse is to put an intangible property on invisible text, which is actually unnecessary since the command loop will move point outside of the invisible text at the end of each command anyway. See <a href="adjusting-point">Adjusting Point</a>. For these reasons, this property is obsolete; use the <code>cursor-intangible</code> property instead. </p> </dd> <dt><code>cursor-intangible</code></dt> <dd> + <p>When the minor mode <code>cursor-intangible-mode</code> is turned on, point is moved away from any position that has a non-<code>nil</code> <code>cursor-intangible</code> property, just before redisplay happens. </p> <p>When the variable <code>cursor-sensor-inhibit</code> is non-<code>nil</code>, the <code>cursor-intangible</code> property and the <code>cursor-sensor-functions</code> property (described below) are ignored. </p> </dd> <dt><code>field</code></dt> <dd> + <p>Consecutive characters with the same <code>field</code> property constitute a <em>field</em>. Some motion functions including <code>forward-word</code> and <code>beginning-of-line</code> stop moving at a field boundary. See <a href="fields">Fields</a>. </p> </dd> <dt><code>cursor</code></dt> <dd> + <p>Normally, the cursor is displayed at the beginning or the end of any overlay and text property strings present at the current buffer position. You can instead tell Emacs to place the cursor on any desired character of these strings by giving that character a non-<code>nil</code> <code>cursor</code> text property. In addition, if the value of the <code>cursor</code> property is an integer, it specifies the number of buffer’s character positions, starting with the position where the overlay or the <code>display</code> property begins, for which the cursor should be displayed on that character. Specifically, if the value of the <code>cursor</code> property of a character is the number <var>n</var>, the cursor will be displayed on this character for any buffer position in the range <code>[<var>ovpos</var>..<var>ovpos</var>+<var>n</var>)</code>, where <var>ovpos</var> is the overlay’s starting position given by <code>overlay-start</code> (see <a href="managing-overlays">Managing Overlays</a>), or the position where the <code>display</code> text property begins in the buffer. </p> <p>In other words, the string character with the <code>cursor</code> property of any non-<code>nil</code> value is the character where to display the cursor when the overlay or display string make point not visible on display. The value of the property says for which buffer positions to display the cursor there. If the value is an integer <var>n</var>, the cursor is displayed there when point is anywhere between the beginning of the overlay or <code>display</code> property and <var>n</var> positions after that. If the value is anything else and non-<code>nil</code>, the cursor is displayed there only when point is at the buffer position that is the beginning of the <code>display</code> property, or at <code>overlay-start</code> if that position is not visible on display. Note that an integer value of the <code>cursor</code> property could mean that the cursor is displayed on that character even when point is visible on display. </p> <p>One subtlety of this property is that it doesn’t work to put this property on a newline character that is part of a display or overlay string. That’s because the newline doesn’t have a graphic representation on the screen for Emacs to find when it looks for a character on display with that <code>cursor</code> property. </p> <p>When the buffer has many overlay strings (e.g., see <a href="overlay-properties">before-string</a>) that conceal some of the buffer text or <code>display</code> properties that are strings, it is a good idea to use the <code>cursor</code> property on these strings to cue the Emacs display about the places where to put the cursor while traversing these strings. This directly communicates to the display engine where the Lisp program wants to put the cursor, or where the user would expect the cursor, when point is located on some buffer position that is “covered” by the display or overlay string. </p> </dd> <dt><code>pointer</code></dt> <dd> + <p>This specifies a specific pointer shape when the mouse pointer is over this text or image. See <a href="pointer-shape">Pointer Shape</a>, for possible pointer shapes. </p> </dd> <dt><code>line-spacing</code></dt> <dd> + <p>A newline can have a <code>line-spacing</code> text or overlay property that controls the height of the display line ending with that newline. The property value overrides the default frame line spacing and the buffer local <code>line-spacing</code> variable. See <a href="line-height">Line Height</a>. </p> </dd> <dt><code>line-height</code></dt> <dd> + <p>A newline can have a <code>line-height</code> text or overlay property that controls the total height of the display line ending in that newline. See <a href="line-height">Line Height</a>. </p> </dd> <dt><code>wrap-prefix</code></dt> <dd> +<p>If text has a <code>wrap-prefix</code> property, the prefix it defines will be added at display time to the beginning of every continuation line due to text wrapping (so if lines are truncated, the wrap-prefix is never used). It may be a string or an image (see <a href="other-display-specs">Other Display Specs</a>), or a stretch of whitespace such as specified by the <code>:width</code> or <code>:align-to</code> display properties (see <a href="specified-space">Specified Space</a>). </p> <p>A wrap-prefix may also be specified for an entire buffer using the <code>wrap-prefix</code> buffer-local variable (however, a <code>wrap-prefix</code> text-property takes precedence over the value of the <code>wrap-prefix</code> variable). See <a href="truncation">Truncation</a>. </p> </dd> <dt><code>line-prefix</code></dt> <dd> +<p>If text has a <code>line-prefix</code> property, the prefix it defines will be added at display time to the beginning of every non-continuation line. It may be a string or an image (see <a href="other-display-specs">Other Display Specs</a>), or a stretch of whitespace such as specified by the <code>:width</code> or <code>:align-to</code> display properties (see <a href="specified-space">Specified Space</a>). </p> <p>A line-prefix may also be specified for an entire buffer using the <code>line-prefix</code> buffer-local variable (however, a <code>line-prefix</code> text-property takes precedence over the value of the <code>line-prefix</code> variable). See <a href="truncation">Truncation</a>. </p> </dd> <dt><code>modification-hooks</code></dt> <dd> + <p>If a character has the property <code>modification-hooks</code>, then its value should be a list of functions; modifying that character calls all of those functions before the actual modification. 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. Furthermore, insertion will not modify any existing character, so this hook will only be run when removing some characters, replacing them with others, or changing their text-properties. </p> <p>Unlike with other similar hooks, when Emacs calls these functions, <code>inhibit-modification-hooks</code> does <em>not</em> get bound to non-<code>nil</code>. If the functions modify the buffer, you should consider binding this variable to non-<code>nil</code> to prevent any buffer changes running the change hooks. Otherwise, you must be prepared for recursive calls. See <a href="change-hooks">Change Hooks</a>. </p> <p>Overlays also support the <code>modification-hooks</code> property, but the details are somewhat different (see <a href="overlay-properties">Overlay Properties</a>). </p> </dd> <dt><code>insert-in-front-hooks</code></dt> <dt><code>insert-behind-hooks</code></dt> <dd> + <p>The operation of inserting text in a buffer also calls the functions listed in the <code>insert-in-front-hooks</code> property of the following character and in the <code>insert-behind-hooks</code> property of the preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called <em>after</em> the actual insertion takes place. </p> <p>When these functions are called, <code>inhibit-modification-hooks</code> is bound to non-<code>nil</code>. If the functions modify the buffer, you might want to bind <code>inhibit-modification-hooks</code> to <code>nil</code>, so as to cause the change hooks to run for these modifications. However, doing this may call your own change hook recursively, so be sure to prepare for that. </p> <p>See also <a href="change-hooks">Change Hooks</a>, for other hooks that are called when you change text in a buffer. </p> </dd> <dt><code>point-entered</code></dt> <dt><code>point-left</code></dt> <dd> + <p>The special properties <code>point-entered</code> and <code>point-left</code> record hook functions that report motion of point. Each time point moves, Emacs compares these two property values: </p> <ul> <li> the <code>point-left</code> property of the character after the old location, and </li> +<li> the <code>point-entered</code> property of the character after the new location. </li> +</ul> <p>If these two values differ, each of them is called (if not <code>nil</code>) with two arguments: the old value of point, and the new one. </p> <p>The same comparison is made for the characters before the old and new locations. The result may be to execute two <code>point-left</code> functions (which may be the same function) and/or two <code>point-entered</code> functions (which may be the same function). In any case, all the <code>point-left</code> functions are called first, followed by all the <code>point-entered</code> functions. </p> <p>It is possible to use <code>char-after</code> to examine characters at various buffer positions without moving point to those positions. Only an actual change in the value of point runs these hook functions. </p> <p>The variable <code>inhibit-point-motion-hooks</code> by default inhibits running the <code>point-left</code> and <code>point-entered</code> hooks, see <a href="#Inhibit-point-motion-hooks">Inhibit point motion hooks</a>. </p> <p>These properties are obsolete; please use <code>cursor-sensor-functions</code> instead. </p> </dd> <dt><code>cursor-sensor-functions</code></dt> <dd> + <p>This special property records a list of functions that react to cursor motion. Each function in the list is called, just before redisplay, with 3 arguments: the affected window, the previous known position of the cursor, and one of the symbols <code>entered</code> or <code>left</code>, depending on whether the cursor is entering the text that has this property or leaving it. The functions are called only when the minor mode <code>cursor-sensor-mode</code> is turned on. </p> <p>When the variable <code>cursor-sensor-inhibit</code> is non-<code>nil</code>, the <code>cursor-sensor-functions</code> property is ignored. </p> </dd> <dt><code>composition</code></dt> <dd> + <p>This text property is used to display a sequence of characters as a single glyph composed from components. But the value of the property itself is completely internal to Emacs and should not be manipulated directly by, for instance, <code>put-text-property</code>. </p> </dd> <dt><code>minibuffer-message</code></dt> <dd> + <p>This text property tells where to display temporary messages in an active minibuffer. Specifically, the first character of the minibuffer text which has this property will have the temporary message displayed before it. The default is to display temporary messages at the end of the minibuffer text. This text property is used by the function that is the default value of <code>set-message-function</code> (see <a href="displaying-messages">Displaying Messages</a>). </p> </dd> </dl> <dl> <dt id="inhibit-point-motion-hooks">Variable: <strong>inhibit-point-motion-hooks</strong> +</dt> <dd> +<p>When this obsolete variable is non-<code>nil</code>, <code>point-left</code> and <code>point-entered</code> hooks are not run, and the <code>intangible</code> property has no effect. Do not set this variable globally; bind it with <code>let</code>. Since the affected properties are obsolete, this variable’s default value is <code>t</code>, to effectively disable them. </p> +</dd> +</dl> <dl> <dt id="show-help-function">Variable: <strong>show-help-function</strong> +</dt> <dd> +<p>If this variable is non-<code>nil</code>, it specifies a function called to display help strings. These may be <code>help-echo</code> properties, menu help strings (see <a href="simple-menu-items">Simple Menu Items</a>, see <a href="extended-menu-items">Extended Menu Items</a>), or tool bar help strings (see <a href="tool-bar">Tool Bar</a>). The specified function is called with one argument, the help string to display, which is passed through <code>substitute-command-keys</code> before being given to the function, unless the help string has a non-<code>nil</code> <code>help-echo-inhibit-substitution</code> property on its first character; see <a href="keys-in-documentation">Keys in Documentation</a>. See the code of Tooltip mode (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Tooltips.html#Tooltips">Tooltips</a> in <cite>The GNU Emacs Manual</cite>) for an example of a mode that uses <code>show-help-function</code>. </p> +</dd> +</dl> <dl> <dt id="face-filters-always-match">Variable: <strong>face-filters-always-match</strong> +</dt> <dd><p>If this variable is non-<code>nil</code>, face filters that specify attributes applied only when certain conditions are met will be deemed to match always. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Special-Properties.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Special-Properties.html</a> + </p> +</div> |