From: Chong Yidong Date: Thu, 9 Apr 2009 01:17:08 +0000 (+0000) Subject: * text.texi (Yank Commands): Note that yank uses push-mark. X-Git-Tag: emacs-pretest-23.0.93~194 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=2bad32998530c0436021451dcde6e524351cc3ed;p=emacs.git * 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 --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e8ebb3ee1ce..50e87de8332 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -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 --git a/doc/lispref/display.texi b/doc/lispref/display.texi index e5c257f0b23..b017ce70704 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -4801,7 +4801,7 @@ A string displayed by the Emacs tool-tip help system; by default, @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 @@ parent keymap for its keymap. 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 --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index aa443350c1a..76a1529dfd7 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1078,7 +1078,6 @@ Text Properties 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 --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 72a2feda683..f3b034b5fb4 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -978,14 +978,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 @@ -1449,9 +1449,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 @@ -1567,9 +1570,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. @@ -1583,6 +1586,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 @@ -2593,7 +2607,6 @@ 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 @@ -3025,8 +3038,6 @@ property when Font Lock mode is enabled. When Font Lock mode is disabled, 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 @@ 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) @@ -3523,72 +3537,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}: @@ -3597,12 +3590,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 @@ -3613,32 +3606,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 @@ -3646,11 +3641,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 diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index af141386645..6cd34187b5e 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -301,7 +301,7 @@ Modes such as Dired, Info, Compilation, and Occur redefine it in this 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