@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2000, 2001, 2004, 2005
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Base 64:: Conversion to or from base 64 encoding.
-* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''.
-* Atomic Changes:: Installing several buffer changes ``atomically''.
+* MD5 Checksum:: Compute the MD5 "message digest"/"checksum".
+* Atomic Changes:: Installing several buffer changes "atomically".
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
buffer. This is similar to @code{(char-after (point))}. However, if
point is at the end of the buffer, then @code{following-char} returns 0.
-Remember that point is always between characters, and the terminal
-cursor normally appears over the character following point. Therefore,
-the character returned by @code{following-char} is the character the
+Remember that point is always between characters, and the cursor
+normally appears over the character following point. Therefore, the
+character returned by @code{following-char} is the character the
cursor is over.
In this example, point is between the @samp{a} and the @samp{c}.
arguments can be given in either order. But most often the smaller
argument is written first.
-If the text being copied has any text properties, these are copied into
-the string along with the characters they belong to. @xref{Text
-Properties}. However, overlays (@pxref{Overlays}) in the buffer and
-their properties are ignored, not copied.
+Here's an example which assumes Font-Lock mode is not enabled:
@example
@group
@group
(buffer-substring 1 10)
-@result{} "This is t"
+ @result{} "This is t"
@end group
@group
(buffer-substring (point-max) 10)
-@result{} "he contents of buffer foo
-"
+ @result{} "he contents of buffer foo\n"
+@end group
+@end example
+
+If the text being copied has any text properties, these are copied into
+the string along with the characters they belong to. @xref{Text
+Properties}. However, overlays (@pxref{Overlays}) in the buffer and
+their properties are ignored, not copied.
+
+For example, if Font-Lock mode is enabled, you might get results like
+these:
+
+@example
+@group
+(buffer-substring 1 10)
+ @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t))
@end group
@end example
@end defun
properties, just the characters themselves. @xref{Text Properties}.
@end defun
-@defun filter-buffer-substring start end &optional delete
+@defun filter-buffer-substring start end &optional delete noprops
This function passes the buffer text between @var{start} and @var{end}
through the filter functions specified by the variable
@code{buffer-substring-filters}, and returns the value from the last
between @var{start} and @var{end} after copying it, like
@code{delete-and-extract-region}.
-Lisp code should use this function instead of @code{buffer-substring}
+If @var{noprops} is non-@code{nil}, the final string returned does not
+include text properties, while the string passed through the filters
+still includes text properties from the buffer text.
+
+Lisp code should use this function instead of @code{buffer-substring},
+@code{buffer-substring-no-properties},
or @code{delete-and-extract-region} when copying into user-accessible
data structures such as the kill-ring, X clipboard, and registers.
Major and minor modes can add functions to
---------- Buffer: foo ----------
(buffer-string)
- @result{} "This is the contents of buffer foo
-"
+ @result{} "This is the contents of buffer foo\n"
@end group
@end example
@end defun
-@tindex current-word
@defun current-word &optional strict really-word
This function returns the symbol (or word) at or near point, as a string.
The return value includes no text properties.
@defun insert-char character count &optional inherit
This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} should be a
-number, and @var{character} must be a character. The value is @code{nil}.
+current buffer before point. The argument @var{count} should be an
+integer, and @var{character} must be a character. The value is @code{nil}.
This function does not convert unibyte character codes 128 through 255
to multibyte characters, not even if the current buffer is a multibyte
In an interactive call, @var{count} is the numeric prefix argument.
+Self-insertion translates the input character through
+@code{translation-table-for-input}. @xref{Translation of Characters}.
+
This command calls @code{auto-fill-function} whenever that is
non-@code{nil} and the character inserted is in the table
@code{auto-fill-chars} (@pxref{Auto Filling}).
@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
This command performs abbrev expansion if Abbrev mode is enabled and
the inserted character does not have word-constituent
-syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
-
-This is also responsible for calling @code{blink-paren-function} when
-the inserted character has close parenthesis syntax (@pxref{Blinking}).
+syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also
+responsible for calling @code{blink-paren-function} when the inserted
+character has close parenthesis syntax (@pxref{Blinking}).
Do not try substituting your own definition of
@code{self-insert-command} for the standard one. The editor command
is the numeric prefix argument.
@end deffn
-@deffn Command split-line
-This command splits the current line, moving the portion of the line
-after point down vertically so that it is on the next line directly
-below where it was before. Whitespace is inserted as needed at the
-beginning of the lower line, using the @code{indent-to} function.
-@code{split-line} returns the position of point.
-
-Programs hardly ever use this function.
-@end deffn
-
@defvar overwrite-mode
This variable controls whether overwrite mode is in effect. The value
should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
-auto-saving of that buffer ``because it has shrunk''. However,
+auto-saving of that buffer ``because it has shrunk.'' However,
@code{erase-buffer} does not do this, the idea being that the future
text is not really related to the former text, and its size should not
be compared with that of the former text.
@end deffn
@defun delete-and-extract-region start end
-@tindex delete-and-extract-region
This function deletes the text between positions @var{start} and
@var{end} in the current buffer, and returns a string containing the
text just deleted.
Some people think this use of the word ``kill'' is unfortunate, since
it refers to operations that specifically @emph{do not} destroy the
-entities ``killed''. This is in sharp contrast to ordinary life, in
+entities ``killed.'' This is in sharp contrast to ordinary life, in
which death is permanent and ``killed'' entities do not come back to
life. Therefore, other metaphors have been proposed. For example, the
term ``cut ring'' makes sense to people who, in pre-computer days, used
@comment node-name, next, previous, up
@subsection Functions for Yanking
- @dfn{Yanking} means reinserting an entry of previously killed text
-from the kill ring. The text properties are copied too.
+ This section describes higher-level commands for yanking, which are
+intended primarily for the user but useful also in Lisp programs.
+Both @code{yank} and @code{yank-pop} honor the
+@code{yank-excluded-properties} variable and @code{yank-handler} text
+property (@pxref{Yanking}).
@deffn Command yank &optional arg
@cindex inserting killed text
@code{nil} or a function of no arguments.
If the value is a function, @code{current-kill} calls it to get the
-``most recent kill''. If the function returns a non-@code{nil} value,
-then that value is used as the ``most recent kill''. If it returns
+``most recent kill.'' If the function returns a non-@code{nil} value,
+then that value is used as the ``most recent kill.'' If it returns
@code{nil}, then the front of the kill ring is used.
The normal use of this hook is to get the window system's primary
Most buffers have an @dfn{undo list}, which records all changes made
to the buffer's text so that they can be undone. (The buffers that
don't have one are usually special-purpose buffers for which Emacs
-assumes that undoing is not useful.) All the primitives that modify the
+assumes that undoing is not useful. In particular, any buffer whose
+name begins with a space has its undo recording off by default;
+see @ref{Buffer Names}.) All the primitives that modify the
text in the buffer automatically add elements to the front of the undo
list, which is in the variable @code{buffer-undo-list}.
@defvar buffer-undo-list
-This variable's value is the undo list of the current buffer.
-A value of @code{t} disables the recording of undo information.
+This buffer-local variable's value is the undo list of the current
+buffer. A value of @code{t} disables the recording of undo information.
@end defvar
Here are the kinds of elements an undo list can have:
(put-text-property @var{beg} @var{end} @var{property} @var{value})
@end example
-@item (apply @var{funname} . @var{args})
-This kind of element records a change that can be undone by evaluating
-(@code{apply} @var{funname} @var{args}).
-
-@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args})
-This kind of element records a change that can be undone by evaluating
-(@code{apply} @var{funname} @var{args}). The integer values @var{beg}
-and @var{end} is buffer positions of the range affected by this change
-and @var{delta} is an integer value which is the number of bytes added
-or deleted in that range by this change. This kind of element
-enables undo limited to a region to determine whether the element
-pertains to that region.
-
@item (@var{marker} . @var{adjustment})
This kind of element records the fact that the marker @var{marker} was
relocated due to deletion of surrounding text, and that it moved
by @var{delta}. It is undone by calling @var{funname} with arguments
@var{args}.
+This kind of element enables undo limited to a region to determine
+whether the element pertains to that region.
+
@item nil
This element is a boundary. The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
@defun primitive-undo count list
This is the basic function for undoing elements of an undo list.
It undoes the first @var{count} elements of @var{list}, returning
-the rest of @var{list}. You could write this function in Lisp,
-but it is convenient to have it in C.
+the rest of @var{list}.
@code{primitive-undo} adds elements to the buffer's undo list when it
changes the buffer. Undo commands avoid confusion by saving the undo
of an undo list measures the cons cells that make up the list, plus the
strings of deleted text.) Three variables control the range of acceptable
sizes: @code{undo-limit}, @code{undo-strong-limit} and
-@code{undo-outer-limit}.
+@code{undo-outer-limit}. In these variables, size is counted as the
+number of bytes occupied, which includes both saved text and other
+data.
@defopt undo-limit
This is the soft limit for the acceptable size of an undo list. The
This is a last ditch limit to prevent memory overflow.
@end defopt
+@defopt undo-ask-before-discard
+If this variable is non-@code{nil}, when the undo info exceeds
+@code{undo-outer-limit}, Emacs asks in the echo area whether to
+discard the info. The default value is @code{nil}, which means to
+discard it automatically.
+
+This option is mainly intended for debugging. Garbage collection is
+inhibited while the question is asked, which means that Emacs might
+leak memory if the user waits too long before answering the question.
+@end defopt
+
@node Filling
@comment node-name, next, previous, up
@section Filling
between paragraphs are removed. This function justifies as well as
filling when @var{justify} is non-@code{nil}.
-In an interactive call, any prefix argument requests justification.
-
If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
other than line breaks untouched. If @var{squeeze-after} is
non-@code{nil}, it specifies a position in the region, and means don't
@defun current-justification
This function returns the proper justification style to use for filling
the text around point.
+
+This returns the value of the @code{justification} text property at
+point, or the variable @var{default-justification} if there is no such
+text property. However, it returns @code{nil} rather than @code{none}
+to mean ``don't justify''.
@end defun
@defopt sentence-end-double-space
@section Margins for Filling
@defopt fill-prefix
-This buffer-local variable specifies a string of text that appears at
-the beginning
-of normal text lines and should be disregarded when filling them. Any
-line that fails to start with the fill prefix is considered the start of
-a paragraph; so is any line that starts with the fill prefix followed by
-additional whitespace. Lines that start with the fill prefix but no
-additional whitespace are ordinary text lines that can be filled
-together. The resulting filled lines also start with the fill prefix.
+This buffer-local variable, if non-@code{nil}, specifies a string of
+text that appears at the beginning of normal text lines and should be
+disregarded when filling them. Any line that fails to start with the
+fill prefix is considered the start of a paragraph; so is any line
+that starts with the fill prefix followed by additional whitespace.
+Lines that start with the fill prefix but no additional whitespace are
+ordinary text lines that can be filled together. The resulting filled
+lines also start with the fill prefix.
The fill prefix follows the left margin whitespace, if any.
@end defopt
@defvar fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line
-at certain places. Its value should be a list of functions, but a
-single function is also supported for compatibility. Whenever filling
-considers breaking the line at a certain place in the buffer, it calls
-each of these functions with no arguments and with point located at
-that place. If any of the functions returns non-@code{nil}, then the
-line won't be broken there.
+at certain places. Its value should be a list of functions. Whenever
+filling considers breaking the line at a certain place in the buffer,
+it calls each of these functions with no arguments and with point
+located at that place. If any of the functions returns
+non-@code{nil}, then the line won't be broken there.
@end defvar
@node Adaptive Fill
starting after the left margin whitespace (if any) on a line; the
characters it matches are that line's candidate for the fill prefix.
-@w{@samp{"[ \t]*\\([-|#;>*]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
+@w{@code{"[ \t]*\\([-!|#%;>*·•‣⁃◦]+[ \t]*\\|(?[0-9]+[.)][ \t]*\\)*"}} is the
default value. This matches a number enclosed in parentheses or
followed by a period, or certain punctuation characters, or any
sequence of these intermingled with whitespace. In particular, it
replaces the candidate with a string of spaces ``of the same width''
as it.
-The default value of this variable is @w{@samp{"\\`[ \t]*\\'"}}, which
+The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which
matches only a string of whitespace. The effect of this default is to
force the fill prefixes found in one-line paragraphs always to be pure
whitespace.
justification style to refill portions of the text. @xref{Margins}.
@defvar auto-fill-function
-The value of this variable should be a function (of no arguments) to be
-called after self-inserting a character from the table
+The value of this buffer-local variable should be a function (of no
+arguments) to be called after self-inserting a character from the table
@code{auto-fill-chars}. It may be @code{nil}, in which case nothing
special is done in that case.
rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.
-@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
+@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate
This function is the general text-sorting routine that subdivides a
buffer into records and then sorts them. Most of the commands in this
section use this function.
non-@code{nil} value.
@end enumerate
+The argument @var{predicate} is the function to use to compare keys.
+If keys are numbers, it defaults to @code{<}; otherwise it defaults to
+@code{string<}.
+
As an example of @code{sort-subr}, here is the complete function
definition for @code{sort-lines}:
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
- (sort-subr reverse 'forward-line 'end-of-line))))
+ (let ((inhibit-field-text-motion t))
+ (sort-subr reverse 'forward-line 'end-of-line)))))
@end group
@end example
containing position @var{beg}, and the entire line containing position
@var{end}, are included in the region sorted.
-Note that @code{sort-columns} uses the @code{sort} utility program,
-and so cannot work properly on text containing tab characters. Use
-@kbd{M-x untabify} to convert tabs to spaces before sorting.
+Note that @code{sort-columns} rejects text that contains tabs, because
+tabs could be split across the specified columns. Use @kbd{M-x
+untabify} to convert tabs to spaces before sorting.
+
+When possible, this command actually works by calling the @code{sort}
+utility program.
@end deffn
@node Columns
affect the display of tab characters in the buffer (@pxref{Usual
Display}). Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.
+@xref{Tab Stops,,, emacs, The GNU Emacs Manual}.
@deffn Command tab-to-tab-stop
This command inserts spaces or tabs before point, up to the next tab
Lists}). The properties belong to a particular character at a
particular place, such as, the letter @samp{T} at the beginning of this
sentence or the first @samp{o} in @samp{foo}---if the same character
-occurs in two different places, the two occurrences generally have
+occurs in two different places, the two occurrences in general have
different properties.
Each property has a name and a value. Both of these can be any Lisp
-object, but the name is normally a symbol. The usual way to access the
-property list is to specify a name and ask what value corresponds to it.
+object, but the name is normally a symbol. Typically each property
+name symbol is used for a particular purpose; for instance, the text
+property @code{face} specifies the faces for displaying the character
+(@pxref{Special Properties}). The usual way to access the property
+list is to specify a name and ask what value corresponds to it.
If a character has a @code{category} property, we call it the
@dfn{category} of the character. It should be a symbol. The properties
@defun remove-list-of-text-properties start end list-of-properties &optional object
Like @code{remove-text-properties} except that
-@var{list-of-properties} is a list property names only, not an
+@var{list-of-properties} is a list of property names only, not an
alternating list of property names and values.
@end defun
@example
(set-text-properties @var{start} @var{end} nil)
@end example
+
+Do not rely on the return value of this function.
@end defun
The easiest way to make a string with text properties
is with @code{propertize}:
@defun propertize string &rest properties
-@tindex propertize
This function returns a copy of @var{string} which has the text
properties @var{properties}. These properties apply to all the
characters in the string that is returned. Here is an example that
@end smallexample
@end defun
+@defun previous-property-change pos &optional object limit
+This is like @code{next-property-change}, but scans back from @var{pos}
+instead of forward. If the value is non-@code{nil}, it is a position
+less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
+equals @var{pos}.
+@end defun
+
@defun next-single-property-change pos prop &optional object limit
-The function scans the text forward from position @var{pos} in the
-string or buffer @var{object} till it finds a change in the @var{prop}
-property, then returns the position of the change. In other words, it
-returns the position of the first character beyond @var{pos} whose
-@var{prop} property differs from that of the character just after
-@var{pos}.
+The function scans text for a change in the @var{prop} property, then
+returns the position of the change. The scan goes forward from
+position @var{pos} in the string or buffer @var{object}. In other
+words, this function returns the position of the first character
+beyond @var{pos} whose @var{prop} property differs from that of the
+character just after @var{pos}.
If @var{limit} is non-@code{nil}, then the scan ends at position
@var{limit}. If there is no property change before that point,
equals @var{pos} only if @var{limit} equals @var{pos}.
@end defun
-@defun previous-property-change pos &optional object limit
-This is like @code{next-property-change}, but scans back from @var{pos}
-instead of forward. If the value is non-@code{nil}, it is a position
-less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
-equals @var{pos}.
-@end defun
-
@defun previous-single-property-change pos prop &optional object limit
This is like @code{next-single-property-change}, but scans back from
@var{pos} instead of forward. If the value is non-@code{nil}, it is a
@end defun
@defun next-single-char-property-change pos prop &optional object limit
-@tindex next-single-char-property-change
This is like @code{next-single-property-change} except that it
considers overlay properties as well as text properties, and if no
change is found before the end of the @var{object}, it returns the
@end defun
@defun previous-single-char-property-change pos prop &optional object limit
-@tindex previous-single-char-property-change
This is like @code{next-single-char-property-change}, but scans back
from @var{pos} instead of forward, and returns the minimum valid
position in @var{object} if no change is found.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
-just the foreground color or just the background color.
+just the foreground color or just the background color. @xref{Color
+Names}, for the supported forms of @var{color-name}.
@code{(foreground-color . @var{color-name})} is equivalent to
specifying @code{(:foreground @var{color-name})}, and likewise for the
@item fontified
@kindex fontified @r{(text property)}
-This property, if non-@code{nil}, says that text in the buffer has
-had faces assigned automatically by a feature such as Font-Lock mode.
-@xref{Auto Faces}.
+This property says whether the character has a face assigned to it by font
+locking. The display engine tests it to decide whether a buffer
+portion needs refontifying before display. @xref{Auto Faces}. It
+takes one of three values:
+
+@table @asis
+@item @code{nil}
+Font locking is disabled, or the character's @code{face} property, if
+any, is invalid.
+
+@item @code{defer}
+This value is only used when ``just in time'' font locking is enabled
+and it means that the character's @code{face} property is invalid and
+needs deferred fontification.
+
+@item @code{t}
+The character's @code{face} property, or absence of one, is valid.
+@end table
@item display
@kindex display @r{(text property)}
@itemize @bullet{}
@item
-If @var{object} is a buffer, @var{pos} is the position in the buffer
-where the @code{help-echo} text property was found.
+If @var{object} is a buffer, @var{pos} is the position in the buffer.
@item
If @var{object} is an overlay, that overlay has a @code{help-echo}
-property, and @var{pos} is the position in the overlay's buffer under
-the mouse.
+property, and @var{pos} is the position in the overlay's buffer.
@item
If @var{object} is a string (an overlay string or a string displayed
with the @code{display} property), @var{pos} is the position in that
-string under the mouse.
+string.
@end itemize
If the value of the @code{help-echo} property is neither a function nor
@cindex keymap of character
@kindex keymap @r{(text property)}
The @code{keymap} property specifies an additional keymap for
-commands. The property's value for the character before point applies
-if it is non-@code{nil} and rear-sticky, and the property's value for
-the character after point applies if it is non-@code{nil} and
+commands. When this keymap applies, it is used for key lookup before
+the minor mode keymaps and before the buffer's local map.
+@xref{Active Keymaps}. If the property value is a symbol, the
+symbol's function definition is used as the keymap.
+
+The property's value for the character before point applies if it is
+non-@code{nil} and rear-sticky, and the property's value for the
+character after point applies if it is non-@code{nil} and
front-sticky. (For mouse clicks, the position of the click is used
-instead of the position of point.) If the property value is a symbol,
-the symbol's function definition is used as the keymap.
-
-When this keymap applies, it is used for key lookup before the minor
-mode keymaps and before the buffer's local map. @xref{Active
-Keymaps}.
+instead of the position of point.)
@item local-map
@kindex local-map @r{(text property)}
This property works like @code{keymap} except that it specifies a
keymap to use @emph{instead of} the buffer's local map. For most
-purposes (perhaps all purposes), the @code{keymap} is superior.
+purposes (perhaps all purposes), it is better to use the @code{keymap}
+property.
@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that
character is not allowed. Any command that would do so gets an error,
-@code{text-read-only}.
+@code{text-read-only}. If the property value is a string, that string
+is used as the error message.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the @code{read-only} property due to
being modified by a single primitive, you can't predict how many times
the function will be called.
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@item insert-in-front-hooks
@itemx insert-behind-hooks
@kindex insert-in-front-hooks @r{(text property)}
@end defvar
@defvar show-help-function
-@tindex show-help-function
@anchor{Help display} If this variable is non-@code{nil}, it specifies a
function called to display help strings. These may be @code{help-echo}
properties, menu help strings (@pxref{Simple Menu Items},
list.
@defvar text-property-default-nonsticky
-@tindex text-property-default-nonsticky
This variable holds an alist which defines the default rear-stickiness
of various text properties. Each element has the form
@code{(@var{property} . @var{nonstickiness})}, and it defines the
@subsection Defining Clickable Text
@cindex clickable text
- There are two ways to set up @dfn{clickable text} in a buffer.
-There are typically two parts of this: to make the text highlight
-when the mouse is over it, and to make a mouse button do something
-when you click it on that part of the text.
-
- Highlighting is done with the @code{mouse-face} text property.
+ @dfn{Clickable text} is text that can be clicked, with either the
+the mouse or via keyboard commands, to produce some result. Many
+major modes use clickable text to implement features such as
+hyper-links. The @code{button} package provides an easy way to insert
+and manipulate clickable text. @xref{Buttons}.
+
+ In this section, we will explain how to manually set up clickable
+text in a buffer using text properties. This involves two things: (1)
+indicating clickability when the mouse moves over the text, and (2)
+making @kbd{RET} or a mouse click on that text do something.
+
+ Indicating clickability usually involves highlighting the text, and
+often involves displaying helpful information about the action, such
+as which mouse button to press, or a short summary of the action.
+This can be done with the @code{mouse-face} and @code{help-echo}
+text properties. @xref{Special Properties}.
Here is an example of how Dired does it:
@smallexample
(condition-case nil
(if (dired-move-to-filename)
- (put-text-property (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- 'mouse-face 'highlight))
+ (add-text-properties
+ (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ '(mouse-face highlight
+ help-echo "mouse-2: visit this file in other window")))
(error nil))
@end smallexample
@noindent
-The first two arguments to @code{put-text-property} specify the
+The first two arguments to @code{add-text-properties} specify the
beginning and end of the text.
The usual way to make the mouse do something when you click it
@smallexample
(defun dired-mouse-find-file-other-window (event)
- "In dired, visit the file or directory name you click on."
+ "In Dired, visit the file or directory name you click on."
(interactive "e")
- (let (file)
+ (let (window pos file)
(save-excursion
- (set-buffer (window-buffer (posn-window (event-end event))))
- (save-excursion
- (goto-char (posn-point (event-end event)))
- (setq file (dired-get-filename))))
- (select-window (posn-window (event-end event)))
- (find-file-other-window (file-name-sans-versions file t))))
+ (setq window (posn-window (event-end event))
+ pos (posn-point (event-end event)))
+ (if (not (windowp window))
+ (error "No file chosen"))
+ (set-buffer (window-buffer window))
+ (goto-char pos)
+ (setq file (dired-get-file-for-visit)))
+ (if (file-directory-p file)
+ (or (and (cdr dired-subdir-alist)
+ (dired-goto-subdir file))
+ (progn
+ (select-window window)
+ (dired-other-window file)))
+ (select-window window)
+ (find-file-other-window (file-name-sans-versions file t)))))
@end smallexample
@noindent
-The reason for the outer @code{save-excursion} construct is to avoid
-changing the current buffer; the reason for the inner one is to avoid
-permanently altering point in the buffer you click on. In this case,
-Dired uses the function @code{dired-get-filename} to determine which
-file to visit, based on the position found in the event.
+The reason for the @code{save-excursion} construct is to avoid
+changing the current buffer. In this case,
+Dired uses the functions @code{posn-window} and @code{posn-point}
+to determine which buffer the click happened in and where, and
+in that buffer, @code{dired-get-file-for-visit} to determine which
+file to visit.
Instead of defining a mouse command for the major mode, you can define
a key binding for the clickable text itself, using the @code{keymap}
graphical applications use @key{Mouse-1} for following links. For
compatibility, @key{Mouse-1} follows links in Emacs too, when you
click on a link quickly without moving the mouse. The user can
-customize this behaviour through the variable
+customize this behavior through the variable
@code{mouse-1-click-follows-link}.
To define text as a link at the Lisp level, you should bind the
@end smallexample
@defun mouse-on-link-p pos
-@tindex mouse-on-link-p
This function returns non-@code{nil} if position @var{pos} in the
-current buffer is on a link.
+current buffer is on a link. @var{pos} can also be a mouse event
+location, as returned by @code{event-start} (@pxref{Accessing Events}).
@end defun
@node Fields
to an empty field whose beginning and end are both at @var{pos}.
In all of these functions, if @var{pos} is omitted or @code{nil}, the
-value of point is used by default.
+value of point is used by default. If narrowing is in effect, then
+@var{pos} should fall within the accessible portion. @xref{Narrowing}.
@defun field-beginning &optional pos escape-from-edge limit
-@tindex field-beginning
This function returns the beginning of the field specified by @var{pos}.
If @var{pos} is at the beginning of its field, and
@end defun
@defun field-end &optional pos escape-from-edge limit
-@tindex field-end
This function returns the end of the field specified by @var{pos}.
If @var{pos} is at the end of its field, and @var{escape-from-edge} is
@end defun
@defun field-string &optional pos
-@tindex field-string
This function returns the contents of the field specified by @var{pos},
as a string.
@end defun
@defun field-string-no-properties &optional pos
-@tindex field-string-no-properties
This function returns the contents of the field specified by @var{pos},
as a string, discarding text properties.
@end defun
@defun delete-field &optional pos
-@tindex delete-field
This function deletes the text of the field specified by @var{pos}.
@end defun
@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
-@tindex constrain-to-field
This function ``constrains'' @var{new-pos} to the field that
@var{old-pos} belongs to---in other words, it returns the position
closest to @var{new-pos} that is in the same field as @var{old-pos}.
converting to and from this code.
@defun base64-encode-region beg end &optional no-line-break
-@tindex base64-encode-region
This function converts the region from @var{beg} to @var{end} into base
64 code. It returns the length of the encoded text. An error is
signaled if a character in the region is multibyte, i.e.@: in a
@end defun
@defun base64-encode-string string &optional no-line-break
-@tindex base64-encode-string
This function converts the string @var{string} into base 64 code. It
returns a string containing the encoded text. As for
@code{base64-encode-region}, an error is signaled if a character in the
@end defun
@defun base64-decode-region beg end
-@tindex base64-decode-region
This function converts the region from @var{beg} to @var{end} from base
64 code into the corresponding decoded text. It returns the length of
the decoded text.
@end defun
@defun base64-decode-string string
-@tindex base64-decode-string
This function converts the string @var{string} from base 64 code into
the corresponding decoded text. It returns a unibyte string containing the
decoded text.
Output of messages into the @samp{*Messages*} buffer does not
call these functions.
-@defmac combine-after-change-calls body...
+@defmac combine-after-change-calls body@dots{}
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.
@end defvar
@defvar inhibit-modification-hooks
-@tindex inhibit-modification-hooks
If this variable is non-@code{nil}, all of the change hooks are
disabled; none of them run. This affects all the hook variables
described above in this section, as well as the hooks attached to