@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Non-ASCII Characters, Markers, Top
In an interactive call, @var{count} is the numeric prefix argument.
This command calls @code{auto-fill-function} whenever that is
-non-@code{nil} and the character inserted is a space or a newline
-(@pxref{Auto Filling}).
+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
@end deffn
@deffn Command delete-region start end
-This command deletes the text in the current buffer in the region
-defined by @var{start} and @var{end}. The value is @code{nil}. If
-point was inside the deleted region, its value afterward is @var{start}.
+This command deletes the text between positions @var{start} and
+@var{end} in the current buffer, and returns @code{nil}. If point was
+inside the deleted region, its value afterward is @var{start}.
Otherwise, point relocates with the surrounding text, as markers do.
@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.
+
+If point was inside the deleted region, its value afterward is
+@var{start}. Otherwise, point relocates with the surrounding text, as
+markers do.
+@end defun
+
@deffn Command delete-char count &optional killp
This command deletes @var{count} characters directly after point, or
before point if @var{count} is negative. If @var{killp} is
@end deffn
@defopt backward-delete-char-untabify-method
-@tindex backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
@end defvar
@defvar fill-nobreak-predicate
-@tindex 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 function. This function is
called during filling, with no arguments and with point located at the
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to be
-called after self-inserting a space or a newline. It may be @code{nil},
-in which case nothing special is done in that case.
+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.
The value of @code{auto-fill-function} is @code{do-auto-fill} when
Auto-Fill mode is enabled. That is a function whose sole purpose is to
Fill works.
@end defvar
+@defvar auto-fill-chars
+A char table of characters which invoke @code{auto-fill-function} when
+self-inserted---space and newline in most language environments. They
+have an entry @code{t} in the table.
+@end defvar
+
@node Sorting
@section Sorting Text
@cindex sorting text
@end defun
@defun next-char-property-change position &optional limit
-@tindex next-char-property-change
This is like @code{next-property-change} except that it considers
overlay properties as well as text properties. There is no @var{object}
operand because this function operates only on the current buffer. It
@end defun
@defun previous-char-property-change position &optional limit
-@tindex previous-char-property-change
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun
@kindex display @r{(text property)}
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 narror, or replaced with an image.
+or shorter, higher or lower, wider or narrow, or replaced with an image.
@xref{Display Property}.
@item help-echo
@kindex help-echo @r{(text property)}
+@anchor{Text help-echo}
If text has a string as its @code{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. This feature is used in the mode line.
-It is available starting in Emacs 21.
+area, or in the tooltip window.
+
+If the value of the @code{help-echo} property is a function, that
+function is called with three arguments, @var{window}, @var{object} and
+@var{position} and should return a help string or @var{nil} for
+none. The first argument, @var{window} is the window in which
+the help was found. The second, @var{object}, is the buffer, overlay or
+string which had the @code{help-echo} property. The @var{position}
+argument is as follows:
+
+@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.
+@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.
+@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.
+@end itemize
+
+If the value of the @code{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
+@code{show-help-function} (@pxref{Help display}).
+
+This feature is used in the mode line and for other active text. It is
+available starting in Emacs 21.
@item local-map
@cindex keymap of character
@code{let}.
@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},
+@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool
+Bar}). The specified function is called with one argument, the help
+string to display. Tooltip mode (@pxref{(emacs)Tooltips}) provides an
+example.
+@end defvar
+
@node Format Properties
@subsection Formatted Text Properties
then insertion before the character can inherit its @code{face} property
and its @code{read-only} property, but no others.
- The @code{rear-nonsticky} works the opposite way. A property is
-normally rear-sticky by default, so the @code{rear-nonsticky} property
-says which properties are @emph{not} rear-sticky. If a character's
-@code{rear-nonsticky} property is @code{t}, then none of its properties
-are rear-sticky. If the @code{rear-nonsticky} property is a list,
-properties are rear-sticky @emph{unless} their names are in the list.
+ The @code{rear-nonsticky} property works the opposite way. Most
+properties are rear-sticky by default, so the @code{rear-nonsticky}
+property says which properties are @emph{not} rear-sticky. If a
+character's @code{rear-nonsticky} property is @code{t}, then none of its
+properties are rear-sticky. If the @code{rear-nonsticky} property is a
+list, properties are rear-sticky @emph{unless} their names are in the
+list.
@defvar text-property-default-nonsticky
@tindex text-property-default-nonsticky
file to visit, based on the position found in the event.
Instead of defining a mouse command for the major mode, you can define
-a key binding for the clickable text itself, using the @code{local-map}
+a key binding for the clickable text itself, using the @code{keymap}
text property:
@example
(let ((map (make-sparse-keymap)))
- (define-key-binding map [mouse-2] 'operate-this-button)
+ (define-key map [mouse-2] 'operate-this-button)
(put-text-property (point)
(save-excursion
(dired-move-to-end-of-filename)
(point))
- 'local-map map))
+ 'keymap map))
@end example
@noindent
A field is a range of consecutive characters in the buffer that are
identified by having the same value (comparing with @code{eq}) of the
-@code{field} property. This section describes special functions that
-are available for operating on fields.
+@code{field} property (either a text-property or an overlay property).
+This section describes special functions that are available for
+operating on fields.
You specify a field with a buffer position, @var{pos}. We think of
each field as containing a range of buffer positions, so the position
@tindex field-beginning
This function returns the beginning of the field specified by @var{pos}.
-If @var{pos} is at the end of a field, and @var{escape-from-edge} is
-non-@code{nil}, then the return value is always the beginning of the
-field that @emph{ends} at @var{pos}, regardless of the stickiness of the
-@code{field} properties around @var{pos}.
+If @var{pos} is at the beginning of its field, and
+@var{escape-from-edge} is non-@code{nil}, then the return value is
+always the beginning of the preceding field that @emph{ends} at @var{pos},
+regardless of the stickiness of the @code{field} properties around
+@var{pos}.
@end defun
@defun field-end &optional pos escape-from-edge
@tindex field-end
This function returns the end of the field specified by @var{pos}.
-If @var{pos} is at the beginning of a field, and @var{escape-from-edge}
-is non-@code{nil}, then the return value is always the end of the field
-that @emph{begins} at @var{pos}, regardless of the stickiness of the
-@code{field} properties around @var{pos}.
+If @var{pos} is at the end of its field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the end of the following
+field that @emph{begins} at @var{pos}, regardless of the stickiness of
+the @code{field} properties around @var{pos}.
@end defun
@defun field-string &optional pos
This function deletes the text of the field specified by @var{pos}.
@end defun
-@deffn beginning-of-line-or-field &optional count
-@tindex beginning-of-line-or-field
-Like @code{beginning-of-line}, except that this function does not move
-across a field boundary (@pxref{Fields}), unless it moves to another
-line beyond the one that contains the field boundary. Therefore, if
-@var{count} is zero, and point is initially at a field boundary, point
-does not move.
-@end deffn
-
-@deffn end-of-line-or-field &optional count
-@tindex end-of-line-or-field
-Like @code{end-of-line}, except that this function does not move
-across a field boundary (@pxref{Fields}), unless it moves to another
-line beyond the one that contains the field boundary.
-@end deffn
-
-@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line
+@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
If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
the value of point instead, and moves point to the resulting position.
-If @var{old-pos} is at the boundary of two fields, then the allowable
-positions for @var{new-pos} depends on the value of the optional
-argument @var{escape-from-edge}. If @var{escape-from-edge} is
-@code{nil}, then @var{new-pos} is constrained to the field that has the
-same @code{field} text-property that new characters inserted at
-@var{old-pos} would get. (This depends on the stickiness of the
-@code{field} property for the characters before and after
-@var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
+If @var{old-pos} is at the boundary of two fields, then the acceptable
+positions for @var{new-pos} depend on the value of the optional argument
+@var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then
+@var{new-pos} is constrained to the field that has the same @code{field}
+property (either a text-property or an overlay property) that new
+characters inserted at @var{old-pos} would get. (This depends on the
+stickiness of the @code{field} property for the characters before and
+after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
@var{new-pos} is constrained to the union of the two adjacent fields.
+Additionally, if two fields are separated by another field with the
+special value @code{boundary}, then any point within this special field
+is also considered to be ``on the boundary.''
If the optional argument @var{only-in-line} is non-@code{nil}, and
constraining @var{new-pos} in the usual way would move it to a different
that move by line, such as @code{next-line} and
@code{beginning-of-line}, so that they respect field boundaries only in
the case where they can still move to the right line.
+
+If the optional argument @var{inhibit-capture-property} is
+non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
+name, then any field boundaries are ignored.
+
+You can cause @code{constrain-to-field} to ignore all field boundaries
+(and so never constrain anything) by binding the variable
+@code{inhibit-field-text-motion} to a non-nil value.
@end defun
@node Not Intervals
A register is a sort of variable used in Emacs editing that can hold a
variety of different kinds of values. Each register is named by a
-single character. All ASCII characters and their meta variants (but
-with the exception of @kbd{C-g}) can be used to name registers. Thus,
-there are 255 possible registers. A register is designated in Emacs
-Lisp by the character that is its name.
+single character. All @sc{ascii} characters and their meta variants
+(but with the exception of @kbd{C-g}) can be used to name registers.
+Thus, there are 255 possible registers. A register is designated in
+Emacs Lisp by the character that is its name.
@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
@end defvar
@defmac combine-after-change-calls body...
-@tindex combine-after-change-calls
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.
made within the @code{combine-after-change-calls} body.
@strong{Warning:} You must not alter the values of
-@code{after-change-functions} and @code{after-change-function} within
+@code{after-change-functions} within
the body of a @code{combine-after-change-calls} form.
@strong{Note:} If the changes you combine occur in widely scattered
functions.
@end defmac
-@defvar before-change-function
-This obsolete variable holds one function to call before any buffer
-modification (or @code{nil} for no function). It is called just like
-the functions in @code{before-change-functions}.
-@end defvar
-
-@defvar after-change-function
-This obsolete variable holds one function to call after any buffer modification
-(or @code{nil} for no function). It is called just like the functions in
-@code{after-change-functions}.
-@end defvar
-
-The four variables above are temporarily bound to @code{nil} during the
+The two variables above are temporarily bound to @code{nil} during the
time that any of these functions is running. This means that if one of
these functions changes the buffer, that change won't run these
functions. If you do want a hook function to make changes that run
HCoop / bpt / emacs.git / blobdiff