From fc0ba1d08092f5daedde890cb26e01883ab8afeb Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Mon, 31 Jul 2006 20:33:33 +0000 Subject: [PATCH] (Clickable Text): Mention `help-echo' text property. Update intro, examples and associated explanations. --- lispref/ChangeLog | 11 ++++++--- lispref/text.texi | 60 ++++++++++++++++++++++++++++++----------------- 2 files changed, 46 insertions(+), 25 deletions(-) diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 2bb3f1b1874..f64f9eb56df 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,20 +1,25 @@ +2006-07-31 Thien-Thi Nguyen + + * text.texi (Clickable Text): Mention `help-echo' text property. + Update intro, examples and associated explanations. + 2006-07-31 Richard Stallman * commands.texi: Update xrefs. (Event Mod): New node, cut out from old Translating Input. * maps.texi: Update xrefs. - + * keymaps.texi (Translation Keymaps): New node. Update xrefs from Translating Input to Translation Keymaps. - + * elisp.texi (Top): Update subnode menu. * display.texi (Face Functions): Fix explanations of FRAME=t or nil. * os.texi (System Interface): Fix menu descriptions of some nodes. (Translating Input): Node deleted. - + 2006-07-31 Nick Roberts * modes.texi (Minor Mode Conventions): Update link for add-to-list. diff --git a/lispref/text.texi b/lispref/text.texi index fccc72d3d0b..08e55f18f05 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -3480,25 +3480,31 @@ being called over and over for the same text. @cindex clickable text There are two parts of setting up @dfn{clickable text} in a buffer: -(1) to make that text highlight when the mouse moves over it, and (2) +(1) to indicate clickability when the mouse moves over the text, and (2) to make a mouse button do something when you click on that text. - For highlighting, use the @code{mouse-face} text property. Here is -an example of how Dired does it: + 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: @smallexample (condition-case nil (if (dired-move-to-filename) - (put-text-property (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - 'mouse-face 'highlight)) + (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)) @end smallexample @noindent -The first two arguments to @code{put-text-property} specify the +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 @@ -3508,24 +3514,34 @@ is done by the command definition. Here is how Dired does it: @smallexample (defun dired-mouse-find-file-other-window (event) - "In dired, visit the file or directory name you click on." + "In Dired, visit the file or directory name you click on." (interactive "e") - (let (file) + (let (window pos file) (save-excursion - (set-buffer (window-buffer (posn-window (event-end event)))) - (save-excursion - (goto-char (posn-point (event-end event))) - (setq file (dired-get-filename)))) - (select-window (posn-window (event-end event))) - (find-file-other-window (file-name-sans-versions file t)))) + (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)) + (goto-char pos) + (setq file (dired-get-file-for-visit))) + (if (file-directory-p file) + (or (and (cdr dired-subdir-alist) + (dired-goto-subdir file)) + (progn + (select-window window) + (dired-other-window file))) + (select-window window) + (find-file-other-window (file-name-sans-versions file t))))) @end smallexample @noindent -The reason for the outer @code{save-excursion} construct is to avoid -changing the current buffer; the reason for the inner one is to avoid -permanently altering point in the buffer you click on. In this case, -Dired uses the function @code{dired-get-filename} to determine which -file to visit, based on the position found in the event. +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} -- 2.39.2