# HG changeset patch # User Chong Yidong # Date 1239239828 0 # Node ID 97aebffaf765067759cee728a870f75ef9d4f783 # Parent 524d2ca60ede175f93e398ce1e5d928f054acad8 * text.texi (Yank Commands): Note that yank uses push-mark. (Filling): Clarify REGION argument of fill-paragraph. Document fill-forward-paragraph-function. (Special Properties): Remove "new in Emacs 22" declaration. (Clickable Text): Merge with Links and Mouse-1 node. * display.texi (Button Properties, Button Buffer Commands): Change xref to Clickable Text. * tips.texi (Key Binding Conventions): Change xref to Clickable Text. * elisp.texi (Top): Update node listing. diff -r 524d2ca60ede -r 97aebffaf765 doc/lispref/ChangeLog --- a/doc/lispref/ChangeLog Wed Apr 08 18:03:17 2009 +0000 +++ b/doc/lispref/ChangeLog Thu Apr 09 01:17:08 2009 +0000 @@ -1,3 +1,19 @@ +2009-04-09 Chong Yidong + + * text.texi (Yank Commands): Note that yank uses push-mark. + (Filling): Clarify REGION argument of fill-paragraph. Document + fill-forward-paragraph-function. + (Special Properties): Remove "new in Emacs 22" declaration. + (Clickable Text): Merge with Links and Mouse-1 node. + + * display.texi (Button Properties, Button Buffer Commands): Change + xref to Clickable Text. + + * tips.texi (Key Binding Conventions): Change xref to Clickable + Text. + + * elisp.texi (Top): Update node listing. + 2009-04-05 Chong Yidong * markers.texi (The Mark): Copyedits. Improve description of diff -r 524d2ca60ede -r 97aebffaf765 doc/lispref/display.texi --- a/doc/lispref/display.texi Wed Apr 08 18:03:17 2009 +0000 +++ b/doc/lispref/display.texi Thu Apr 09 01:17:08 2009 +0000 @@ -4801,7 +4801,7 @@ @item follow-link @kindex follow-link @r{(button property)} The follow-link property, defining how a @key{Mouse-1} click behaves -on this button, @xref{Links and Mouse-1}. +on this button, @xref{Clickable Text}. @item button @kindex button @r{(button property)} @@ -4985,7 +4985,7 @@ If the button has a non-@code{nil} @code{follow-link} property, and @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click will also activate the @code{push-button} command. -@xref{Links and Mouse-1}. +@xref{Clickable Text}. @deffn Command push-button &optional pos use-mouse-action Perform the action specified by a button at location @var{pos}. diff -r 524d2ca60ede -r 97aebffaf765 doc/lispref/elisp.texi --- a/doc/lispref/elisp.texi Wed Apr 08 18:03:17 2009 +0000 +++ b/doc/lispref/elisp.texi Thu Apr 09 01:17:08 2009 +0000 @@ -1078,7 +1078,6 @@ 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 diff -r 524d2ca60ede -r 97aebffaf765 doc/lispref/text.texi --- a/doc/lispref/text.texi Wed Apr 08 18:03:17 2009 +0000 +++ b/doc/lispref/text.texi Thu Apr 09 01:17:08 2009 +0000 @@ -978,14 +978,14 @@ @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 @@ -1449,9 +1449,12 @@ @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 @@ -1567,9 +1570,9 @@ @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. @@ -1583,6 +1586,17 @@ @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 @@ -2593,7 +2607,6 @@ 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 @@ -3025,8 +3038,6 @@ The @code{font-lock-mode} property is useful for special modes that implement their own highlighting. @xref{Precalculated Fontification}. -This property is new in Emacs 22.1. - @item mouse-face @kindex mouse-face @r{(text property)} The property @code{mouse-face} is used instead of @code{face} when the @@ -3458,46 +3469,49 @@ @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) @@ -3523,72 +3537,51 @@ @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. - - 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: +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 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}: @@ -3597,12 +3590,12 @@ @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. - -For example, here is how pcvs enables @key{Mouse-1} to follow links on +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 @kbd{Mouse-1} to follow links on file names only: @smallexample @@ -3613,32 +3606,34 @@ @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 @@ -3646,11 +3641,10 @@ '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 diff -r 524d2ca60ede -r 97aebffaf765 doc/lispref/tips.texi --- a/doc/lispref/tips.texi Wed Apr 08 18:03:17 2009 +0000 +++ b/doc/lispref/tips.texi Thu Apr 09 01:17:08 2009 +0000 @@ -301,7 +301,7 @@ way. In addition, they should mark the text as a kind of ``link'' so that -@kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}. +@kbd{mouse-1} will follow it also. @xref{Clickable Text}. @item @cindex reserved keys