X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/f76840f36cf60feecaf21d55d24ace948800fef7..8d7f026f625a02854b3214f7a54e778121d266bc:/doc/lispref/text.texi diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 5b935bc6e2..2510607475 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,7 +1,8 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/text @node Text, Non-ASCII Characters, Markers, Top @@ -42,7 +43,7 @@ the character after point. * The Kill Ring:: Where removed text sometimes is saved for later use. * Undo:: Undoing changes to the text of a buffer. * Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. + How to control how much information is kept. * Filling:: Functions for explicit filling. * Margins:: How to specify margins for filling commands. * Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. @@ -821,7 +822,7 @@ would be difficult to change the terminology now. * Kill Functions:: Functions that kill text. * Yanking:: How yanking is done. * Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. +* Low-Level Kill Ring:: Functions and variables for kill ring access. * Internals of Kill Ring:: Variables that hold kill ring data. @end menu @@ -899,10 +900,10 @@ from the buffer. It returns @code{nil}. The command does not set @code{this-command} to @code{kill-region}, so a subsequent kill command does not append to the same kill ring entry. -Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to -support Emacs 18. For newer Emacs versions, it is better to use -@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill -Ring}. +@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then? +@c Why is it used in many places in Emacs? +In Lisp programs, it is better to use @code{kill-new} or +@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}. @end deffn @node Yanking @@ -978,14 +979,14 @@ property (@pxref{Yanking}). @deffn Command yank &optional arg @cindex inserting killed text -This command inserts before point the text at the front of the -kill ring. It positions the mark at the beginning of that text, and -point at the end. +This command inserts before point the text at the front of the kill +ring. It sets the mark at the beginning of that text, using +@code{push-mark} (@pxref{The Mark}), and puts point at the end. If @var{arg} is a non-@code{nil} list (which occurs interactively when the user types @kbd{C-u} with no digits), then @code{yank} inserts the text as described above, but puts point before the yanked text and -puts the mark after it. +sets the mark after it. If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most recently killed text---the @var{arg}th element of the kill ring @@ -1040,8 +1041,8 @@ text property, if there is one. @subsection Low-Level Kill Ring These functions and variables provide access to the kill ring at a -lower level, but still convenient for use in Lisp programs, because they -take care of interaction with window system selections +lower level, but are still convenient for use in Lisp programs, +because they take care of interaction with window system selections (@pxref{Window System Selections}). @defun current-kill n &optional do-not-move @@ -1057,12 +1058,14 @@ If @var{n} is zero, indicating a request for the latest kill, @code{current-kill} calls the value of @code{interprogram-paste-function} (documented below) before consulting the kill ring. If that value is a function and calling it -returns a string, @code{current-kill} pushes that string onto the kill -ring and returns it. It also sets the yanking pointer to point to -that new entry, regardless of the value of @var{do-not-move}. -Otherwise, @code{current-kill} does not treat a zero value for @var{n} -specially: it returns the entry pointed at by the yanking pointer and -does not move the yanking pointer. +returns a string or a list of several string, @code{current-kill} +pushes the strings onto the kill ring and returns the first string. +It also sets the yanking pointer to point to the kill-ring entry of +the first string returned by @code{interprogram-paste-function}, +regardless of the value of @var{do-not-move}. Otherwise, +@code{current-kill} does not treat a zero value for @var{n} specially: +it returns the entry pointed at by the yanking pointer and does not +move the yanking pointer. @end defun @defun kill-new string &optional replace yank-handler @@ -1105,9 +1108,19 @@ If the value is a function, @code{current-kill} calls it to get the 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 +To facilitate support for window systems that support multiple +selections, this function may also return a list of strings. In that +case, the first string is used as the ``most recent kill'', and all +the other strings are pushed onto the kill ring, for easy access by +@code{yank-pop}. + +The normal use of this function is to get the window system's primary selection as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. +another application. @xref{Window System Selections}. However, if +the selection was provided by the current Emacs session, this function +should return @code{nil}. (If it is hard to tell whether Emacs or +some other program provided the selection, it should be good enough to +use @code{string=} to compare it with the last text Emacs provided.) @end defvar @defvar interprogram-cut-function @@ -1121,7 +1134,7 @@ The second, optional, argument has the same meaning as the @var{push} argument to @code{x-set-cut-buffer} (@pxref{Definition of x-set-cut-buffer}) and only affects the second and later cut buffers. -The normal use of this hook is to set the window system's primary +The normal use of this function is to set the window system's primary selection (and first cut buffer) from the newly killed text. @xref{Window System Selections}. @end defvar @@ -1286,13 +1299,16 @@ This function places a boundary element in the undo list. The undo command stops at such a boundary, and successive undo commands undo to earlier and earlier boundaries. This function returns @code{nil}. -The editor command loop automatically creates an undo boundary before -each key sequence is executed. Thus, each undo normally undoes the -effects of one command. Self-inserting input characters are an -exception. The command loop makes a boundary for the first such -character; the next 19 consecutive self-inserting input characters do -not make boundaries, and then the 20th does, and so on as long as -self-inserting characters continue. +The editor command loop automatically calls @code{undo-boundary} just +before executing each key sequence, so that each undo normally undoes +the effects of one command. As an exception, the command +@code{self-insert-command}, which produces self-inserting input +characters (@pxref{Commands for Insertion}), may remove the boundary +inserted by the command loop: a boundary is accepted for the first +such character, the next 19 consecutive self-inserting input +characters do not have boundaries, and then the 20th does; and so on +as long as the self-inserting characters continue. Hence, sequences +of consecutive character insertions can be undone as a group. All buffer modifications add a boundary whenever the previous undoable change was made in some other buffer. This is to ensure that @@ -1437,9 +1453,12 @@ This command fills the paragraph at or after point. If @var{justify} is non-@code{nil}, each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. -Interactively, when @var{region} is non-@code{nil} in Transient Mark -mode and the mark is active, this command calls @code{fill-region} -on the active region. + +When @var{region} is non-@code{nil}, then if Transient Mark mode is +enabled and the mark is active, this command calls @code{fill-region} +to fill all the paragraphs in the region, instead of filling only the +current paragraph. When this command is called interactively, +@var{region} is @code{t}. @end deffn @deffn Command fill-region start end &optional justify nosqueeze to-eop @@ -1555,9 +1574,9 @@ characters that can end a sentence without following spaces. @end defopt @defvar fill-paragraph-function -This variable provides a way for major modes to override the filling of -paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls -this function to do the work. If the function returns a non-@code{nil} +This variable provides a way to override the filling of paragraphs. +If its value is non-@code{nil}, @code{fill-paragraph} calls this +function to do the work. If the function returns a non-@code{nil} value, @code{fill-paragraph} assumes the job is done, and immediately returns that value. @@ -1571,6 +1590,17 @@ way, it can do so as follows: @end example @end defvar +@defvar fill-forward-paragraph-function +This variable provides a way to override how the filling functions, +such as @code{fill-region} and @code{fill-paragraph}, move forward to +the next paragraph. Its value should be a function, which is called +with a single argument @var{n}, the number of paragraphs to move, and +should return the difference between @var{n} and the number of +paragraphs actually moved. The default value of this variable is +@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs +Manual}. +@end defvar + @defvar use-hard-newlines If this variable is non-@code{nil}, the filling functions do not delete newlines that have the @code{hard} text property. These ``hard @@ -1603,15 +1633,9 @@ As a practical matter, if you are writing text for other people to read, you should set @code{fill-column} to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy. -@end defopt -@defvar default-fill-column -The value of this variable is the default value for @code{fill-column} in -buffers that do not override it. This is the same as -@code{(default-value 'fill-column)}. - -The default value for @code{default-fill-column} is 70. -@end defvar +The default value for @code{fill-column} is 70. +@end defopt @deffn Command set-left-margin from to margin This sets the @code{left-margin} property on the text from @var{from} to @@ -1664,20 +1688,20 @@ may involve either inserting or deleting whitespace.) This function is value of @code{indent-line-function} in Paragraph-Indent Text mode. @end defun -@defvar left-margin +@defopt left-margin This variable specifies the base left margin column. In Fundamental mode, @kbd{C-j} indents to this column. This variable automatically becomes buffer-local when set in any fashion. -@end defvar +@end defopt -@defvar fill-nobreak-predicate +@defopt 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. 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 +@end defopt @node Adaptive Fill @section Adaptive Fill Mode @@ -2103,14 +2127,17 @@ For an example of using @code{current-column}, see the description of @code{count-lines} in @ref{Text Lines}. @end defun -@defun move-to-column column &optional force +@deffn Command move-to-column column &optional force This function moves point to @var{column} in the current line. The calculation of @var{column} takes into account the widths of the displayed representations of the characters between the start of the line and point. -If column @var{column} is beyond the end of the line, point moves to the -end of the line. If @var{column} is negative, point moves to the +When called interactively, @var{column} is the value of prefix numeric +argument. If @var{column} is not an integer, an error is signaled. + +If column @var{column} is beyond the end of the line, point moves to +the end of the line. If @var{column} is negative, point moves to the beginning of the line. If it is impossible to move to column @var{column} because that is in @@ -2125,10 +2152,8 @@ The argument @var{force} also has an effect if the line isn't long enough to reach column @var{column}; if it is @code{t}, that means to add whitespace at the end of the line to reach that column. -If @var{column} is not an integer, an error is signaled. - The return value is the column number actually moved to. -@end defun +@end deffn @node Indentation @section Indentation @@ -2209,15 +2234,17 @@ This command calls the function in @code{indent-line-function} to indent the current line in a way appropriate for the current major mode. @end deffn -@deffn Command indent-for-tab-command -This command calls the function in @code{indent-line-function} to indent -the current line; however, if that function is -@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That -is a trivial command that inserts a tab character.) +@deffn Command indent-for-tab-command &optional rigid +This command calls the function in @code{indent-line-function} to +indent the current line; however, if that function is +@code{indent-to-left-margin}, @code{insert-tab} is called instead. +(That is a trivial command that inserts a tab character.) If +@var{rigid} is non-@code{nil}, this function also rigidly indents the +entire balanced expression that starts at the beginning of the current +line, to reflect change in indentation of the current line. @end deffn @deffn Command newline-and-indent -@comment !!SourceFile simple.el This function inserts a newline, then indents the new line (the one following the newline just inserted) according to the major mode. @@ -2248,7 +2275,7 @@ by @code{left-margin}. This section describes commands that indent all the lines in the region. They return unpredictable values. -@deffn Command indent-region start end to-column +@deffn Command indent-region start end &optional to-column This command indents each nonblank line starting between @var{start} (inclusive) and @var{end} (exclusive). If @var{to-column} is @code{nil}, @code{indent-region} indents each nonblank line by calling @@ -2286,7 +2313,6 @@ a different meaning and does not use this variable. @end defvar @deffn Command indent-rigidly start end count -@comment !!SourceFile indent.el This command indents all lines starting between @var{start} (inclusive) and @var{end} (exclusive) sideways by @var{count} columns. This ``preserves the shape'' of the affected region, moving it as a @@ -2302,13 +2328,13 @@ In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses replied to. @end deffn -@defun indent-code-rigidly start end columns &optional nochange-regexp +@deffn Command indent-code-rigidly start end columns &optional nochange-regexp This is like @code{indent-rigidly}, except that it doesn't alter lines that start within strings or comments. In addition, it doesn't alter a line if @var{nochange-regexp} matches at the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). -@end defun +@end deffn @node Relative Indent @subsection Indentation Relative to Previous Lines @@ -2571,9 +2597,9 @@ along with the characters; this includes such diverse functions as @menu * Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. * Format Properties:: Properties for representing formatting of text. * Sticky Properties:: How inserted text gets properties from neighboring text. @@ -2581,11 +2607,10 @@ along with the characters; this includes such diverse functions as only when text is examined. * Clickable Text:: Using text properties to make regions of text do something when you click on them. -* Links and Mouse-1:: How to make @key{Mouse-1} follow a link. * Fields:: The @code{field} property defines fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. +* Not Intervals:: Why text properties do not use + Lisp-visible text intervals. @end menu @node Examining Properties @@ -2990,33 +3015,28 @@ time you want to specify a particular attribute for certain text. @xref{Face Attributes}. @item -A cons cell with 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. @xref{Color -Names}, for the supported forms of @var{color-name}. - -A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to -specifying @code{(:foreground @var{color-name})}; likewise for the -background. +A cons cell with the form @code{(foreground-color . @var{color-name})} +or @code{(background-color . @var{color-name})}. These are old, +deprecated equivalents for @code{(:foreground @var{color-name})} and +@code{(:background @var{color-name})}. Please convert code that uses +them. @end itemize -You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically -update @code{face} properties based on the contents of the text. +It works to use the latter two forms directly as the value +of the @code{face} property. + +Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by +dynamically updating the @code{face} property of characters based on +the context. @item font-lock-face @kindex font-lock-face @r{(text property)} -The @code{font-lock-face} property is the same in all respects as the -@code{face} property, but its state of activation is controlled by -@code{font-lock-mode}. This can be advantageous for special buffers -which are not intended to be user-editable, or for static areas of -text which are always fontified in the same way. -@xref{Precalculated Fontification}. +The @code{font-lock-face} property is equivalent to the @code{face} +property when Font Lock mode is enabled. When Font Lock mode is disabled, +@code{font-lock-face} has no effect. -Strictly speaking, @code{font-lock-face} is not a built-in text -property; rather, it is implemented in Font Lock mode using -@code{char-property-alias-alist}. @xref{Examining Properties}. - -This property is new in Emacs 22.1. +The @code{font-lock-face} property is useful for special modes that +implement their own highlighting. @xref{Precalculated Fontification}. @item mouse-face @kindex mouse-face @r{(text property)} @@ -3150,9 +3170,20 @@ Consecutive characters with the same @code{field} property constitute a @item cursor @kindex cursor @r{(text property)} Normally, the cursor is displayed at the end of any overlay and text -property strings present at the current window position. You can +property strings present at the current buffer position. You can place the cursor on any desired character of these strings by giving -that character a non-@code{nil} @var{cursor} text property. +that character a non-@code{nil} @code{cursor} text property. In +addition, if the value of the @code{cursor} property of an overlay +string is an integer number, it specifies the number of buffer's +character positions associated with the overlay string; this way, +Emacs will display the cursor on the character with that property +regardless of whether the current buffer position is actually covered +by the overlay. Specifically, if the value of the @code{cursor} +property of a character is the number @var{n}, the cursor will be +displayed on this character for any buffer position in the range +@code{[@var{ovpos}..@var{ovpos}+@var{n}]}, where @var{ovpos} is the +starting buffer position covered by the overlay (@pxref{Managing +Overlays}). @item pointer @kindex pointer @r{(text property)} @@ -3173,6 +3204,29 @@ A newline can have a @code{line-height} text or overlay property that controls the total height of the display line ending in that newline. @xref{Line Height}. +@item wrap-prefix +If text has a @code{wrap-prefix} 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, an image, or a stretch-glyph such as +used by the @code{display} text-property. @xref{Display Property}. + +A wrap-prefix may also be specified for an entire buffer using the +@code{wrap-prefix} buffer-local variable (however, a +@code{wrap-prefix} text-property takes precedence over the value of +the @code{wrap-prefix} variable). @xref{Truncation}. + +@item line-prefix +If text has a @code{line-prefix} property, the prefix it defines will +be added at display-time to the beginning of every non-continuation +line. It may be a string, an image, or a stretch-glyph such as used +by the @code{display} text-property. @xref{Display Property}. + +A line-prefix may also be specified for an entire buffer using the +@code{line-prefix} buffer-local variable (however, a +@code{line-prefix} text-property takes precedence over the value of +the @code{line-prefix} variable). @xref{Truncation}. + @item modification-hooks @cindex change hooks for a character @cindex hooks for changing a character @@ -3426,58 +3480,60 @@ being called over and over for the same text. @node Clickable Text @subsection Defining Clickable Text @cindex clickable text +@cindex follow links +@cindex mouse-1 @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: +mouse or via a keyboard command, to produce some result. Many major +modes use clickable text to implement textual hyper-links, or +@dfn{links} for short. + + The easiest way to insert and manipulate links is to use the +@code{button} package. @xref{Buttons}. In this section, we will +explain how to manually set up clickable text in a buffer, using text +properties. For simplicity, we will refer to the clickable text as a +@dfn{link}. + + Implementing a link involves three separate steps: (1) indicating +clickability when the mouse moves over the link; (2) making @kbd{RET} +or @kbd{Mouse-2} on that link do something; and (3) setting up a +@code{follow-link} condition so that the link obeys +@code{mouse-1-click-follows-link}. + + To indicate clickability, add the @code{mouse-face} text property to +the text of the link; then Emacs will highlight the link when the +mouse moves over it. In addition, you should define a tooltip or echo +area message, using the @code{help-echo} text property. @xref{Special +Properties}. For instance, here is how Dired indicates that file +names are clickable: @smallexample -(condition-case nil - (if (dired-move-to-filename) - (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)) + (if (dired-move-to-filename) + (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"))) @end smallexample -@noindent -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 -on this text is to define @code{mouse-2} in the major mode's -keymap. The job of checking whether the click was on clickable text -is done by the command definition. Here is how Dired does it: + To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to +commands that perform the desired action. Each command should check +to see whether it was called on a link, and act accordingly. For +instance, Dired's major mode keymap binds @kbd{Mouse-2} to the +following command: @smallexample (defun dired-mouse-find-file-other-window (event) "In Dired, visit the file or directory name you click on." (interactive "e") - (let (window pos file) - (save-excursion - (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)) + (let ((window (posn-window (event-end event))) + (pos (posn-point (event-end event))) + file) + (if (not (windowp window)) + (error "No file chosen")) + (with-current-buffer (window-buffer window) (goto-char pos) (setq file (dired-get-file-for-visit))) (if (file-directory-p file) @@ -3491,72 +3547,51 @@ is done by the command definition. Here is how Dired does it: @end smallexample @noindent -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. +This command uses the functions @code{posn-window} and +@code{posn-point} to determine where the click occurred, and +@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} -text property: + Instead of binding the mouse command in a major mode keymap, you can +bind it within the link text, using the @code{keymap} text property +(@pxref{Special Properties}). For instance: @example (let ((map (make-sparse-keymap))) (define-key map [mouse-2] 'operate-this-button) - (put-text-property (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - 'keymap map)) + (put-text-property link-start link-end 'keymap map)) @end example @noindent -This method makes it possible to define different commands for various -clickable pieces of text. Also, the major mode definition (or the -global definition) remains available for the rest of the text in the -buffer. - -@node Links and Mouse-1 -@subsection Links and Mouse-1 -@cindex follow links -@cindex mouse-1 - - The normal Emacs command for activating text in read-only buffers is -@key{Mouse-2}, which includes following textual links. However, most -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 behavior through the variable -@code{mouse-1-click-follows-link}. - - To define text as a link at the Lisp level, you should bind the -@code{mouse-2} event to a command to follow the link. Then, to indicate that -@key{Mouse-1} should also follow the link, you should specify a -@code{follow-link} condition either as a text property or as a key -binding: - -@table @asis -@item @code{follow-link} property -If the clickable text has a non-@code{nil} @code{follow-link} text or overlay -property, that specifies the condition. - -@item @code{follow-link} event -If there is a binding for the @code{follow-link} event, either on the -clickable text or in the local keymap, the binding is the condition. -@end table - - Regardless of how you set the @code{follow-link} condition, its -value is used as follows to determine whether the given position is -inside a link, and (if so) to compute an @dfn{action code} saying how -@key{Mouse-1} should handle the link. +With this method, you can easily define different commands for +different links. Furthermore, the global definition of @key{RET} and +@kbd{Mouse-2} remain available for the rest of the text in the buffer. + +@vindex mouse-1-click-follows-link + The basic Emacs command for clicking on links is @kbd{Mouse-2}. +However, for compatibility with other graphical applications, Emacs +also recognizes @kbd{Mouse-1} clicks on links, provided the user +clicks on the link quickly without moving the mouse. This behavior is +controlled by the user option @code{mouse-1-click-follows-link}. +@xref{Mouse References,,, emacs, The GNU Emacs Manual}. + + To set up the link so that it obeys +@code{mouse-1-click-follows-link}, you must either (1) apply a +@code{follow-link} text or overlay property to the link text, or (2) +bind the @code{follow-link} event to a keymap (which can be a major +mode keymap or a local keymap specified via the @code{keymap} text +property). The value of the @code{follow-link} property, or the +binding for the @code{follow-link} event, acts as a ``condition'' for +the link action. This condition tells Emacs two things: the +circumstances under which a @kbd{Mouse-1} click should be regarded as +occurring ``inside'' the link, and how to compute an ``action code'' +that says what to translate the @kbd{Mouse-1} click into. The link +action condition can be one of the following: @table @asis @item @code{mouse-face} -If the condition is @code{mouse-face}, a position is inside a link if -there is a non-@code{nil} @code{mouse-face} property at that position. -The action code is always @code{t}. +If the condition is the symbol @code{mouse-face}, a position is inside +a link if there is a non-@code{nil} @code{mouse-face} property at that +position. The action code is always @code{t}. For example, here is how Info mode handles @key{Mouse-1}: @@ -3565,12 +3600,12 @@ For example, here is how Info mode handles @key{Mouse-1}: @end smallexample @item a function -If the condition is a valid function, @var{func}, then a position -@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates -to non-@code{nil}. The value returned by @var{func} serves as the -action code. +If the condition is a function, @var{func}, then a position @var{pos} +is inside a link if @code{(@var{func} @var{pos})} evaluates to +non-@code{nil}. The value returned by @var{func} serves as the action +code. -For example, here is how pcvs enables @key{Mouse-1} to follow links on +For example, here is how pcvs enables @kbd{Mouse-1} to follow links on file names only: @smallexample @@ -3581,32 +3616,34 @@ file names only: @item anything else If the condition value is anything else, then the position is inside a -link and the condition itself is the action code. Clearly you should -only specify this kind of condition on the text that constitutes a -link. +link and the condition itself is the action code. Clearly, you should +specify this kind of condition only when applying the condition via a +text or property overlay on the link text (so that it does not apply +to the entire buffer). @end table @noindent -The action code tells @key{Mouse-1} how to follow the link: +The action code tells @kbd{Mouse-1} how to follow the link: @table @asis @item a string or vector -If the action code is a string or vector, the @key{Mouse-1} event is +If the action code is a string or vector, the @kbd{Mouse-1} event is translated into the first element of the string or vector; i.e., the -action of the @key{Mouse-1} click is the local or global binding of +action of the @kbd{Mouse-1} click is the local or global binding of that character or symbol. Thus, if the action code is @code{"foo"}, -@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, -@key{Mouse-1} translates into @key{foo}. +@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, +@kbd{Mouse-1} translates into @key{foo}. @item anything else -For any other non-@code{nil} action code, the @code{mouse-1} event is -translated into a @code{mouse-2} event at the same position. +For any other non-@code{nil} action code, the @kbd{Mouse-1} event is +translated into a @kbd{Mouse-2} event at the same position. @end table - To define @key{Mouse-1} to activate a button defined with + To define @kbd{Mouse-1} to activate a button defined with @code{define-button-type}, give the button a @code{follow-link} -property with a value as specified above to determine how to follow -the link. For example, here is how Help mode handles @key{Mouse-1}: +property. The property value should be a link action condition, as +described above. @xref{Buttons}. For example, here is how Help mode +handles @kbd{Mouse-1}: @smallexample (define-button-type 'help-xref @@ -3614,11 +3651,10 @@ the link. For example, here is how Help mode handles @key{Mouse-1}: 'action #'help-button-action) @end smallexample - To define @key{Mouse-1} on a widget defined with -@code{define-widget}, give the widget a @code{:follow-link} property -with a value as specified above to determine how to follow the link. - -For example, here is how the @code{link} widget specifies that + To define @kbd{Mouse-1} on a widget defined with +@code{define-widget}, give the widget a @code{:follow-link} property. +The property value should be a link action condition, as described +above. For example, here is how the @code{link} widget specifies that a @key{Mouse-1} click shall be translated to @key{RET}: @smallexample @@ -3634,7 +3670,7 @@ a @key{Mouse-1} click shall be translated to @key{RET}: @defun mouse-on-link-p pos This function returns non-@code{nil} if position @var{pos} in the current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Events}). +location, as returned by @code{event-start} (@pxref{Accessing Mouse}). @end defun @node Fields @@ -3841,7 +3877,7 @@ ThXs Xs the contents of the buffer before. @end example @end defun -@defun translate-region start end table +@deffn Command translate-region start end table This function applies a translation table to the characters in the buffer between positions @var{start} and @var{end}. @@ -3855,7 +3891,7 @@ The return value of @code{translate-region} is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table. -@end defun +@end deffn @node Registers @section Registers @@ -3930,27 +3966,6 @@ expect only certain data types. The return value is @var{value}. This command displays what is contained in register @var{reg}. @end deffn -@ignore -@deffn Command point-to-register reg -This command stores both the current location of point and the current -buffer in register @var{reg} as a marker. -@end deffn - -@deffn Command jump-to-register reg -@deffnx Command register-to-point reg -@comment !!SourceFile register.el -This command restores the status recorded in register @var{reg}. - -If @var{reg} contains a marker, it moves point to the position stored in -the marker. Since both the buffer and the location within the buffer -are stored by the @code{point-to-register} function, this command can -switch you to another buffer. - -If @var{reg} contains a window configuration or a frame configuration. -@code{jump-to-register} restores that configuration. -@end deffn -@end ignore - @deffn Command insert-register reg &optional beforep This command inserts contents of register @var{reg} into the current buffer. @@ -3970,43 +3985,6 @@ a rectangle (a list), currently useless things happen. This may be changed in the future. @end deffn -@ignore -@deffn Command copy-to-register reg start end &optional delete-flag -This command copies the region from @var{start} to @var{end} into -register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes -the region from the buffer after copying it into the register. -@end deffn - -@deffn Command prepend-to-register reg start end &optional delete-flag -This command prepends the region from @var{start} to @var{end} into -register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes -the region from the buffer after copying it to the register. -@end deffn - -@deffn Command append-to-register reg start end &optional delete-flag -This command appends the region from @var{start} to @var{end} to the -text already in register @var{reg}. If @var{delete-flag} is -non-@code{nil}, it deletes the region from the buffer after copying it -to the register. -@end deffn - -@deffn Command copy-rectangle-to-register reg start end &optional delete-flag -This command copies a rectangular region from @var{start} to @var{end} -into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it -deletes the region from the buffer after copying it to the register. -@end deffn - -@deffn Command window-configuration-to-register reg -This function stores the window configuration of the selected frame in -register @var{reg}. -@end deffn - -@deffn Command frame-configuration-to-register reg -This function stores the current frame configuration in register -@var{reg}. -@end deffn -@end ignore - @node Transposition @section Transposition of Text @@ -4041,7 +4019,7 @@ manner. }2045. This section describes the functions for converting to and from this code. -@defun base64-encode-region beg end &optional no-line-break +@deffn Command base64-encode-region beg end &optional no-line-break 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 @@ -4053,9 +4031,9 @@ Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument @var{no-line-break} is non-@code{nil}, these newlines are not added, so the output is just one long line. -@end defun +@end deffn -@defun base64-encode-string string &optional no-line-break +@deffn Command base64-encode-string string &optional no-line-break 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 @@ -4065,7 +4043,7 @@ Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument @var{no-line-break} is non-@code{nil}, these newlines are not added, so the result string is just one long line. -@end defun +@end deffn @defun base64-decode-region beg end This function converts the region from @var{beg} to @var{end} from base @@ -4301,6 +4279,4 @@ code that is itself run from a modification hook, then rebind locally @code{inhibit-modification-hooks} to @code{nil}. @end defvar -@ignore - arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b -@end ignore +