Skip to content

GitLab

Commit 2bad3299 authored by Chong Yidong's avatar Chong Yidong
Browse files
Options

* 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
Hide whitespace changes
Inline Side-by-side
Showing with 138 additions and 129 deletions
doc/lispref/ChangeLog
View file @ 2bad3299
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>
* markers.texi (The Mark): Copyedits. Improve description of
......
doc/lispref/display.texi
View file @ 2bad3299
......@@ -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}.
......
doc/lispref/elisp.texi
View file @ 2bad3299
......@@ -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
......
doc/lispref/text.texi
View file @ 2bad3299
......@@ -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
......
doc/lispref/tips.texi
View file @ 2bad3299
......@@ -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
......
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