lisp/help-at-pt.el

   1 ;;; help-at-pt.el --- local help through the keyboard
   2
   3 ;; Copyright (C) 2003-2018 Free Software Foundation, Inc.
   4
   5 ;; Author: Luc Teirlinck <teirllm@auburn.edu>
   6 ;; Keywords: help
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software: you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation, either version 3 of the License, or
  13 ;; (at your option) any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
  22
  23 ;;; Commentary:
  24
  25 ;; This file contains functionality to make the help provided by the
  26 ;; help-echo text or overlay property available to the keyboard user.
  27 ;; It also supports a more keyboard oriented alternative to
  28 ;; `help-echo', namely a new text or overlay property `kbd-help'.
  29 ;;
  30 ;; It provides facilities to access the local help available at point
  31 ;; either on demand, using the command `display-local-help', or
  32 ;; automatically after a suitable idle time, through the customizable
  33 ;; variable `help-at-pt-display-when-idle'.
  34 ;;
  35 ;; You can get a more global overview of the local help available in
  36 ;; the buffer, using the commands `scan-buf-next-region' and
  37 ;; `scan-buf-previous-region', which move to the start of the next or
  38 ;; previous region with available local help and print the help found
  39 ;; there.
  40 ;;
  41 ;; Suggested key bindings:
  42 ;;
  43 ;; (global-set-key [C-tab] 'scan-buf-next-region)
  44 ;; (global-set-key [C-M-tab] 'scan-buf-previous-region)
  45 ;;
  46 ;; You do not have to do anything special to use the functionality
  47 ;; provided by this file, because all important functions autoload.
  48
  49 ;;; Code:
  50
  51 (defgroup help-at-pt nil
  52   "Features for displaying local help."
  53   :group 'help
  54   :version "22.1")
  55
  56 ;;;###autoload
  57 (defun help-at-pt-string (&optional kbd)
  58   "Return the help-echo string at point.
  59 Normally, the string produced by the `help-echo' text or overlay
  60 property, or nil, is returned.
  61 If KBD is non-nil, `kbd-help' is used instead, and any
  62 `help-echo' property is ignored.  In this case, the return value
  63 can also be t, if that is the value of the `kbd-help' property."
  64   (save-excursion
  65     (let* ((prop (if kbd 'kbd-help 'help-echo))
  66            (pair (get-char-property-and-overlay (point) prop))
  67            (pair (if (car pair) pair
  68                      (unless (bobp)
  69                        (backward-char)
  70                        (get-char-property-and-overlay (point) prop))))
  71            (val (car pair))
  72            (ov (cdr pair)))
  73       (if (functionp val)
  74           (funcall val (selected-window) (if ov ov (current-buffer)) (point))
  75           (eval val)))))
  76
  77 ;;;###autoload
  78 (defun help-at-pt-kbd-string ()
  79   "Return the keyboard help string at point.
  80 If the `kbd-help' text or overlay property at point produces a
  81 string, return it.  Otherwise, use the `help-echo' property.
  82 If this produces no string either, return nil."
  83   (let ((kbd (help-at-pt-string t))
  84         (echo (help-at-pt-string)))
  85     (if (and kbd (not (eq kbd t))) kbd echo)))
  86
  87 ;;;###autoload
  88 (defun display-local-help (&optional arg)
  89   "Display local help in the echo area.
  90 This displays a short help message, namely the string produced by
  91 the `kbd-help' property at point.  If `kbd-help' does not produce
  92 a string, but the `help-echo' property does, then that string is
  93 printed instead.
  94
  95 A numeric argument ARG prevents display of a message in case
  96 there is no help.  While ARG can be used interactively, it is
  97 mainly meant for use from Lisp."
  98   (interactive "P")
  99   (let ((help (help-at-pt-kbd-string)))
 100     (if help
 101         (message "%s" help)
 102       (if (not arg) (message "No local help at point")))))
 103
 104 (defvar help-at-pt-timer nil
 105   "Non-nil means that a timer is set that checks for local help.
 106 If non-nil, this is the value returned by the call of
 107 `run-with-idle-timer' that set that timer.  This variable is used
 108 internally to enable `help-at-pt-display-when-idle'.  Do not set it
 109 yourself.")
 110
 111 (defcustom help-at-pt-timer-delay 1
 112   "Delay before displaying local help.
 113 This is used if `help-at-pt-display-when-idle' is enabled.
 114 The value may be an integer or floating point number.
 115
 116 If a timer is already active, there are two ways to make the new
 117 value take effect immediately.  After setting the value, you can
 118 first call `help-at-pt-cancel-timer' and then set a new timer
 119 with `help-at-pt-set-timer'.  Alternatively, you can set this
 120 variable through Custom.  This will not set a timer if none is
 121 active, but if one is already active, Custom will make it use the
 122 new value."
 123   :group 'help-at-pt
 124   :type 'number
 125   :initialize 'custom-initialize-default
 126   :set (lambda (variable value)
 127          (set-default variable value)
 128          (and (boundp 'help-at-pt-timer)
 129               help-at-pt-timer
 130               (timer-set-idle-time help-at-pt-timer value t))))
 131
 132 ;;;###autoload
 133 (defun help-at-pt-cancel-timer ()
 134   "Cancel any timer set by `help-at-pt-set-timer'.
 135 This disables `help-at-pt-display-when-idle'."
 136   (interactive)
 137   (let ((inhibit-quit t))
 138     (when help-at-pt-timer
 139       (cancel-timer help-at-pt-timer)
 140       (setq help-at-pt-timer nil))))
 141
 142 ;;;###autoload
 143 (defun help-at-pt-set-timer ()
 144   "Enable `help-at-pt-display-when-idle'.
 145 This is done by setting a timer, if none is currently active."
 146   (interactive)
 147   (unless help-at-pt-timer
 148     (setq help-at-pt-timer
 149           (run-with-idle-timer
 150            help-at-pt-timer-delay t #'help-at-pt-maybe-display))))
 151
 152 ;;;###autoload
 153 (defcustom help-at-pt-display-when-idle 'never
 154   "Automatically show local help on point-over.
 155 If the value is t, the string obtained from any `kbd-help' or
 156 `help-echo' property at point is automatically printed in the
 157 echo area, if nothing else is already displayed there, or after a
 158 quit.  If both `kbd-help' and `help-echo' produce help strings,
 159 `kbd-help' is used.  If the value is a list, the help only gets
 160 printed if there is a text or overlay property at point that is
 161 included in this list.  Suggested properties are `keymap',
 162 `local-map', `button' and `kbd-help'.  Any value other than t or
 163 a non-empty list disables the feature.
 164
 165 This variable only takes effect after a call to
 166 `help-at-pt-set-timer'.  The help gets printed after Emacs has
 167 been idle for `help-at-pt-timer-delay' seconds.  You can call
 168 `help-at-pt-cancel-timer' to cancel the timer set by, and the
 169 effect of, `help-at-pt-set-timer'.
 170
 171 When this variable is set through Custom, `help-at-pt-set-timer'
 172 is called automatically, unless the value is `never', in which
 173 case `help-at-pt-cancel-timer' is called.  Specifying an empty
 174 list of properties through Custom will set the timer, thus
 175 enabling buffer local values.  It sets the actual value to nil.
 176 Thus, Custom distinguishes between a nil value and other values
 177 that disable the feature, which Custom identifies with `never'.
 178 The default is `never'."
 179   :group 'help-at-pt
 180   :type '(choice  (const :tag "Always"
 181                          :format "%t\n%h"
 182                          :doc
 183                          "This choice can get noisy.
 184 The text printed from the `help-echo' property is often only
 185 relevant when using the mouse.  If you mind about too many
 186 messages getting printed in the echo area, use \"In certain
 187 situations\".  See the documentation there for more information."
 188                          t)
 189                   (repeat :tag "In certain situations"
 190                           ;; unless we specify 0 offset the doc string
 191                           ;; for this choice gets indented very
 192                           ;; differently than for the other two
 193                           ;; choices, when "More" is selected.
 194                           :offset 0
 195                           :format "%{%t%}:\n%v%i\n%h"
 196                           :doc
 197                           "This choice lets you specify a list of \
 198 text properties.
 199 Presence of any of these properties will trigger display of
 200 available local help on point-over.
 201 If you use this alternative through Custom without listing any
 202 properties, a timer will be set anyway.  This will enable buffer
 203 local values.  Use \"Never\" if you do not want a timer to be set.
 204
 205 Suggested properties:
 206 The `keymap' and `local-map' properties change keybindings in
 207 parts of the buffer.  Some of these keymaps are mode independent
 208 and are not mentioned in the mode documentation.  Hence, the help
 209 text is likely to be useful.
 210 Specifying `button' is relevant in Custom and similar buffers.
 211 In these buffers, most, but not all, of the text shown this way is
 212 available by default when using tab, but not on regular point-over.
 213 The presence of a `kbd-help' property guarantees that non mouse
 214 specific help is available."
 215                           :value (keymap local-map button kbd-help)
 216                           symbol)
 217                   (other :tag "Never"
 218                          :format "%t\n%h"
 219                          :doc
 220                          "This choice normally disables buffer local values.
 221 If you choose this value through Custom and a timer checking for
 222 local help is currently active, it will be canceled.  No new
 223 timer will be set.  Call `help-at-pt-set-timer' after choosing
 224 this option, or use \"In certain situations\" and specify no text
 225 properties, to enable buffer local values."
 226                          never))
 227   :initialize 'custom-initialize-default
 228   :set #'(lambda (variable value)
 229            (set-default variable value)
 230            (if (eq value 'never)
 231                (help-at-pt-cancel-timer)
 232              (help-at-pt-set-timer)))
 233   :set-after '(help-at-pt-timer-delay)
 234   :require 'help-at-pt)
 235
 236 ;; Function for use in `help-at-pt-set-timer'.
 237 (defun help-at-pt-maybe-display ()
 238   (and (or (eq help-at-pt-display-when-idle t)
 239            (and (consp help-at-pt-display-when-idle)
 240                 (catch 'found
 241                   (dolist (prop help-at-pt-display-when-idle)
 242                     (if (get-char-property (point) prop)
 243                         (throw 'found t)))
 244                   (unless (bobp)
 245                     (save-excursion
 246                       (backward-char)
 247                       (dolist (prop help-at-pt-display-when-idle)
 248                         (if (get-char-property (point) prop)
 249                             (throw 'found t))))))))
 250        (or (not (current-message))
 251            (string= (current-message) "Quit"))
 252        (display-local-help t)))
 253
 254 ;;;###autoload
 255 (defun scan-buf-move-to-region (prop &optional arg hook)
 256   "Go to the start of the next region with non-nil PROP property.
 257 Then run HOOK, which should be a quoted symbol that is a normal
 258 hook variable, or an expression evaluating to such a symbol.
 259 Adjacent areas with different non-nil PROP properties are
 260 considered different regions.
 261
 262 With numeric argument ARG, move to the start of the ARGth next
 263 such region, then run HOOK.  If ARG is negative, move backward.
 264 If point is already in a region, then that region does not count
 265 toward ARG.  If ARG is 0 and point is inside a region, move to
 266 the start of that region.  If ARG is 0 and point is not in a
 267 region, print a message to that effect, but do not move point and
 268 do not run HOOK.  If there are not enough regions to move over,
 269 an error results and the number of available regions is mentioned
 270 in the error message.  Point is not moved and HOOK is not run."
 271   (cond ((> arg 0)
 272          (if (= (point) (point-max))
 273              (error "No further `%s' regions" prop))
 274          (let ((pos (point)))
 275            (dotimes (x arg)
 276              (setq pos (next-single-char-property-change pos prop))
 277              (unless (get-char-property pos prop)
 278                (setq pos (next-single-char-property-change pos prop))
 279                (unless (get-char-property pos prop)
 280                  (cond ((= x 0)
 281                         (error "No further `%s' regions" prop))
 282                        ((= x 1)
 283                         (error "There is only one further `%s' region" prop))
 284                        (t
 285                         (error
 286                          "There are only %d further `%s' regions"
 287                          x prop))))))
 288            (goto-char pos)
 289            (run-hooks hook)))
 290         ((= arg 0)
 291          (let ((val (get-char-property (point) prop)))
 292            (cond ((not val)
 293                   (message "Point is not in a `%s' region" prop))
 294                  ((eq val (get-char-property (1- (point)) prop))
 295                   (goto-char
 296                    (previous-single-char-property-change (point) prop))
 297                   (run-hooks hook))
 298                  (t (run-hooks hook)))))
 299         ((< arg 0)
 300          (let ((pos (point)) (val (get-char-property (point) prop)))
 301            (and val
 302                 (eq val (get-char-property (1- pos) prop))
 303                 (setq pos
 304                       (previous-single-char-property-change pos prop)))
 305            (if (= pos (point-min))
 306                (error "No prior `%s' regions" prop))
 307            (dotimes (x (- arg))
 308              (setq pos (previous-single-char-property-change pos prop))
 309              (unless (get-char-property pos prop)
 310                (setq pos (previous-single-char-property-change pos prop))
 311                (unless (get-char-property pos prop)
 312                  (cond ((= x 0)
 313                         (error "No prior `%s' regions" prop))
 314                        ((= x 1)
 315                         (error "There is only one prior `%s' region" prop))
 316                        (t
 317                         (error "There are only %d prior `%s' regions"
 318                                x prop))))))
 319            (goto-char pos)
 320            (run-hooks hook)))))
 321
 322 ;; To be moved to a different file and replaced by a defcustom in a
 323 ;; future version.
 324 (defvar scan-buf-move-hook '(display-local-help)
 325   "Normal hook run by `scan-buf-next-region'.
 326 Also used by `scan-buf-previous-region'.  The hook is run after
 327 positioning point.")
 328
 329 ;;;###autoload
 330 (defun scan-buf-next-region (&optional arg)
 331   "Go to the start of the next region with non-nil help-echo.
 332 Print the help found there using `display-local-help'.  Adjacent
 333 areas with different non-nil help-echo properties are considered
 334 different regions.
 335
 336 With numeric argument ARG, move to the start of the ARGth next
 337 help-echo region.  If ARG is negative, move backward.  If point
 338 is already in a help-echo region, then that region does not count
 339 toward ARG.  If ARG is 0 and point is inside a help-echo region,
 340 move to the start of that region.  If ARG is 0 and point is not
 341 in such a region, just print a message to that effect.  If there
 342 are not enough regions to move over, an error results and the
 343 number of available regions is mentioned in the error message.
 344
 345 A potentially confusing subtlety is that point can be in a
 346 help-echo region without any local help being available.  This is
 347 because `help-echo' can be a function evaluating to nil.  This
 348 rarely happens in practice."
 349   (interactive "p")
 350   (scan-buf-move-to-region 'help-echo arg 'scan-buf-move-hook))
 351
 352 ;;;###autoload
 353 (defun scan-buf-previous-region (&optional arg)
 354   "Go to the start of the previous region with non-nil help-echo.
 355 Print the help found there using `display-local-help'.  Adjacent
 356 areas with different non-nil help-echo properties are considered
 357 different regions.  With numeric argument ARG, behaves like
 358 `scan-buf-next-region' with argument -ARG."
 359   (interactive "p")
 360   (scan-buf-move-to-region 'help-echo (- arg) 'scan-buf-move-hook))
 361
 362 (provide 'help-at-pt)
 363
 364 ;;; help-at-pt.el ends here