Commit 2bad3299 authored by Chong Yidong's avatar 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.
parent bcd76f45
2009-04-09 Chong Yidong <cyd@stupidchicken.com>
* 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 <cyd@stupidchicken.com> 2009-04-05 Chong Yidong <cyd@stupidchicken.com>
* markers.texi (The Mark): Copyedits. Improve description of * markers.texi (The Mark): Copyedits. Improve description of
......
...@@ -4801,7 +4801,7 @@ A string displayed by the Emacs tool-tip help system; by default, ...@@ -4801,7 +4801,7 @@ A string displayed by the Emacs tool-tip help system; by default,
@item follow-link @item follow-link
@kindex follow-link @r{(button property)} @kindex follow-link @r{(button property)}
The follow-link property, defining how a @key{Mouse-1} click behaves 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 @item button
@kindex button @r{(button property)} @kindex button @r{(button property)}
...@@ -4985,7 +4985,7 @@ parent keymap for its keymap. ...@@ -4985,7 +4985,7 @@ parent keymap for its keymap.
If the button has a non-@code{nil} @code{follow-link} property, and 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 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
will also activate the @code{push-button} command. 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 @deffn Command push-button &optional pos use-mouse-action
Perform the action specified by a button at location @var{pos}. Perform the action specified by a button at location @var{pos}.
......
...@@ -1078,7 +1078,6 @@ Text Properties ...@@ -1078,7 +1078,6 @@ Text Properties
only when text is examined. only when text is examined.
* Clickable Text:: Using text properties to make regions of text * Clickable Text:: Using text properties to make regions of text
do something when you click on them. 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:: The @code{field} property defines
fields within the buffer. fields within the buffer.
* Not Intervals:: Why text properties do not use * Not Intervals:: Why text properties do not use
......
...@@ -978,14 +978,14 @@ property (@pxref{Yanking}). ...@@ -978,14 +978,14 @@ property (@pxref{Yanking}).
@deffn Command yank &optional arg @deffn Command yank &optional arg
@cindex inserting killed text @cindex inserting killed text
This command inserts before point the text at the front of the This command inserts before point the text at the front of the kill
kill ring. It positions the mark at the beginning of that text, and ring. It sets the mark at the beginning of that text, using
point at the end. @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 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 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 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 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 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 ...@@ -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. @var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph It uses the ordinary paragraph motion commands to find paragraph
boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. 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} When @var{region} is non-@code{nil}, then if Transient Mark mode is
on the active region. 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 @end deffn
@deffn Command fill-region start end &optional justify nosqueeze to-eop @deffn Command fill-region start end &optional justify nosqueeze to-eop
...@@ -1567,9 +1570,9 @@ characters that can end a sentence without following spaces. ...@@ -1567,9 +1570,9 @@ characters that can end a sentence without following spaces.
@end defopt @end defopt
@defvar fill-paragraph-function @defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of This variable provides a way to override the filling of paragraphs.
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls If its value is non-@code{nil}, @code{fill-paragraph} calls this
this function to do the work. If the function returns a non-@code{nil} function to do the work. If the function returns a non-@code{nil}
value, @code{fill-paragraph} assumes the job is done, and immediately value, @code{fill-paragraph} assumes the job is done, and immediately
returns that value. returns that value.
...@@ -1583,6 +1586,17 @@ way, it can do so as follows: ...@@ -1583,6 +1586,17 @@ way, it can do so as follows:
@end example @end example
@end defvar @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 @defvar use-hard-newlines
If this variable is non-@code{nil}, the filling functions do not delete If this variable is non-@code{nil}, the filling functions do not delete
newlines that have the @code{hard} text property. These ``hard newlines that have the @code{hard} text property. These ``hard
...@@ -2593,7 +2607,6 @@ along with the characters; this includes such diverse functions as ...@@ -2593,7 +2607,6 @@ along with the characters; this includes such diverse functions as
only when text is examined. only when text is examined.
* Clickable Text:: Using text properties to make regions of text * Clickable Text:: Using text properties to make regions of text
do something when you click on them. 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:: The @code{field} property defines
fields within the buffer. fields within the buffer.
* Not Intervals:: Why text properties do not use * 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, ...@@ -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 The @code{font-lock-mode} property is useful for special modes that
implement their own highlighting. @xref{Precalculated Fontification}. implement their own highlighting. @xref{Precalculated Fontification}.
This property is new in Emacs 22.1.
@item mouse-face @item mouse-face
@kindex mouse-face @r{(text property)} @kindex mouse-face @r{(text property)}
The property @code{mouse-face} is used instead of @code{face} when the 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. ...@@ -3458,46 +3469,49 @@ being called over and over for the same text.
@node Clickable Text @node Clickable Text
@subsection Defining Clickable Text @subsection Defining Clickable Text
@cindex clickable text @cindex clickable text
@cindex follow links
@cindex mouse-1
@dfn{Clickable text} is text that can be clicked, with either the @dfn{Clickable text} is text that can be clicked, with either the
the mouse or via keyboard commands, to produce some result. Many mouse or via a keyboard command, to produce some result. Many major
major modes use clickable text to implement features such as modes use clickable text to implement textual hyper-links, or
hyper-links. The @code{button} package provides an easy way to insert @dfn{links} for short.
and manipulate clickable text. @xref{Buttons}.
The easiest way to insert and manipulate links is to use the
In this section, we will explain how to manually set up clickable @code{button} package. @xref{Buttons}. In this section, we will
text in a buffer using text properties. This involves two things: (1) explain how to manually set up clickable text in a buffer, using text
indicating clickability when the mouse moves over the text, and (2) properties. For simplicity, we will refer to the clickable text as a
making @kbd{RET} or a mouse click on that text do something. @dfn{link}.
Indicating clickability usually involves highlighting the text, and Implementing a link involves three separate steps: (1) indicating
often involves displaying helpful information about the action, such clickability when the mouse moves over the link; (2) making @kbd{RET}
as which mouse button to press, or a short summary of the action. or @kbd{Mouse-2} on that link do something; and (3) setting up a
This can be done with the @code{mouse-face} and @code{help-echo} @code{follow-link} condition so that the link obeys
text properties. @xref{Special Properties}. @code{mouse-1-click-follows-link}.
Here is an example of how Dired does it:
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 @smallexample
(condition-case nil (if (dired-move-to-filename)
(if (dired-move-to-filename) (add-text-properties
(add-text-properties (point)
(point) (save-excursion
(save-excursion (dired-move-to-end-of-filename)
(dired-move-to-end-of-filename) (point))
(point)) '(mouse-face highlight
'(mouse-face highlight help-echo "mouse-2: visit this file in other window")))
help-echo "mouse-2: visit this file in other window")))
(error nil))
@end smallexample @end smallexample
@noindent To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
The first two arguments to @code{add-text-properties} specify the commands that perform the desired action. Each command should check
beginning and end of the text. 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
The usual way to make the mouse do something when you click it following command:
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:
@smallexample @smallexample
(defun dired-mouse-find-file-other-window (event) (defun dired-mouse-find-file-other-window (event)
...@@ -3523,72 +3537,51 @@ is done by the command definition. Here is how Dired does it: ...@@ -3523,72 +3537,51 @@ is done by the command definition. Here is how Dired does it:
@end smallexample @end smallexample
@noindent @noindent
The reason for the @code{save-excursion} construct is to avoid This command uses the functions @code{posn-window} and
changing the current buffer. In this case, @code{posn-point} to determine where the click occurred, and
Dired uses the functions @code{posn-window} and @code{posn-point} @code{dired-get-file-for-visit} to determine which file to visit.
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 Instead of binding the mouse command in a major mode keymap, you can
a key binding for the clickable text itself, using the @code{keymap} bind it within the link text, using the @code{keymap} text property
text property: (@pxref{Special Properties}). For instance:
@example @example
(let ((map (make-sparse-keymap))) (let ((map (make-sparse-keymap)))
(define-key map [mouse-2] 'operate-this-button) (define-key map [mouse-2] 'operate-this-button)
(put-text-property (point) (put-text-property link-start link-end 'keymap map))
(save-excursion
(dired-move-to-end-of-filename)
(point))
'keymap map))
@end example @end example
@noindent @noindent
This method makes it possible to define different commands for various With this method, you can easily define different commands for
clickable pieces of text. Also, the major mode definition (or the different links. Furthermore, the global definition of @key{RET} and
global definition) remains available for the rest of the text in the @kbd{Mouse-2} remain available for the rest of the text in the buffer.
buffer.
@vindex mouse-1-click-follows-link
@node Links and Mouse-1 The basic Emacs command for clicking on links is @kbd{Mouse-2}.
@subsection Links and Mouse-1 However, for compatibility with other graphical applications, Emacs
@cindex follow links also recognizes @kbd{Mouse-1} clicks on links, provided the user
@cindex mouse-1 clicks on the link quickly without moving the mouse. This behavior is
controlled by the user option @code{mouse-1-click-follows-link}.
The normal Emacs command for activating text in read-only buffers is @xref{Mouse References,,, emacs, The GNU Emacs Manual}.
@key{Mouse-2}, which includes following textual links. However, most
graphical applications use @key{Mouse-1} for following links. For To set up the link so that it obeys
compatibility, @key{Mouse-1} follows links in Emacs too, when you @code{mouse-1-click-follows-link}, you must either (1) apply a
click on a link quickly without moving the mouse. The user can @code{follow-link} text or overlay property to the link text, or (2)
customize this behavior through the variable bind the @code{follow-link} event to a keymap (which can be a major
@code{mouse-1-click-follows-link}. mode keymap or a local keymap specified via the @code{keymap} text
property). The value of the @code{follow-link} property, or the
To define text as a link at the Lisp level, you should bind the binding for the @code{follow-link} event, acts as a ``condition'' for
@code{mouse-2} event to a command to follow the link. Then, to indicate that the link action. This condition tells Emacs two things: the
@key{Mouse-1} should also follow the link, you should specify a circumstances under which a @kbd{Mouse-1} click should be regarded as
@code{follow-link} condition either as a text property or as a key occurring ``inside'' the link, and how to compute an ``action code''
binding: 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{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.
@table @asis @table @asis
@item @code{mouse-face} @item @code{mouse-face}
If the condition is @code{mouse-face}, a position is inside a link if If the condition is the symbol @code{mouse-face}, a position is inside
there is a non-@code{nil} @code{mouse-face} property at that position. a link if there is a non-@code{nil} @code{mouse-face} property at that
The action code is always @code{t}. position. The action code is always @code{t}.
For example, here is how Info mode handles @key{Mouse-1}: 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}: ...@@ -3597,12 +3590,12 @@ For example, here is how Info mode handles @key{Mouse-1}:
@end smallexample @end smallexample
@item a function @item a function
If the condition is a valid function, @var{func}, then a position If the condition is a function, @var{func}, then a position @var{pos}
@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates is inside a link if @code{(@var{func} @var{pos})} evaluates to
to non-@code{nil}. The value returned by @var{func} serves as the non-@code{nil}. The value returned by @var{func} serves as the action
action code. 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: file names only:
@smallexample @smallexample
...@@ -3613,32 +3606,34 @@ file names only: ...@@ -3613,32 +3606,34 @@ file names only:
@item anything else @item anything else
If the condition value is anything else, then the position is inside a 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 link and the condition itself is the action code. Clearly, you should
only specify this kind of condition on the text that constitutes a specify this kind of condition only when applying the condition via a
link. text or property overlay on the link text (so that it does not apply
to the entire buffer).
@end table @end table
@noindent @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 @table @asis
@item a string or vector @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 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"}, that character or symbol. Thus, if the action code is @code{"foo"},
@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, @kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
@key{Mouse-1} translates into @key{foo}. @kbd{Mouse-1} translates into @key{foo}.
@item anything else @item anything else
For any other non-@code{nil} action code, the @code{mouse-1} event is For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
translated into a @code{mouse-2} event at the same position. translated into a @kbd{Mouse-2} event at the same position.
@end table @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} @code{define-button-type}, give the button a @code{follow-link}
property with a value as specified above to determine how to follow property. The property value should be a link action condition, as
the link. For example, here is how Help mode handles @key{Mouse-1}: described above. @xref{Buttons}. For example, here is how Help mode
handles @kbd{Mouse-1}:
@smallexample @smallexample
(define-button-type 'help-xref (define-button-type 'help-xref
...@@ -3646,11 +3641,10 @@ the link. For example, here is how Help mode handles @key{Mouse-1}: ...@@ -3646,11 +3641,10 @@ the link. For example, here is how Help mode handles @key{Mouse-1}:
'action #'help-button-action) 'action #'help-button-action)
@end smallexample @end smallexample
To define @key{Mouse-1} on a widget defined with To define @kbd{Mouse-1} on a widget defined with
@code{define-widget}, give the widget a @code{:follow-link} property @code{define-widget}, give the widget a @code{:follow-link} property.
with a value as specified above to determine how to follow the link. The property value should be a link action condition, as described
above. For example, here is how the @code{link} widget specifies that
For example, here is how the @code{link} widget specifies that
a @key{Mouse-1} click shall be translated to @key{RET}: a @key{Mouse-1} click shall be translated to @key{RET}:
@smallexample @smallexample
......
...@@ -301,7 +301,7 @@ Modes such as Dired, Info, Compilation, and Occur redefine it in this ...@@ -301,7 +301,7 @@ Modes such as Dired, Info, Compilation, and Occur redefine it in this
way. way.
In addition, they should mark the text as a kind of ``link'' so that 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 @item
@cindex reserved keys @cindex reserved keys
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment