lisp/button.el

   1 ;;; button.el --- clickable buttons
   2 ;;
   3 ;; Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
   4 ;;
   5 ;; Author: Miles Bader <miles@gnu.org>
   6 ;; Keywords: extensions
   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 2, or (at your option)
  13 ;; 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; see the file COPYING.  If not, write to the
  22 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  23 ;; Boston, MA 02110-1301, USA.
  24
  25 ;;; Commentary:
  26 ;;
  27 ;; This package defines functions for inserting and manipulating
  28 ;; clickable buttons in Emacs buffers, such as might be used for help
  29 ;; hyperlinks, etc.
  30 ;;
  31 ;; In some ways it duplicates functionality also offered by the
  32 ;; `widget' package, but the button package has the advantage that it
  33 ;; is (1) much faster, (2) much smaller, and (3) much, much, simpler
  34 ;; (the code, that is, not the interface).
  35 ;;
  36 ;; Buttons can either use overlays, in which case the button is
  37 ;; represented by the overlay itself, or text-properties, in which case
  38 ;; the button is represented by a marker or buffer-position pointing
  39 ;; somewhere in the button.  In the latter case, no markers into the
  40 ;; buffer are retained, which is important for speed if there are are
  41 ;; extremely large numbers of buttons.
  42 ;;
  43 ;; Using `define-button-type' to define default properties for buttons
  44 ;; is not necessary, but it is is encouraged, since doing so makes the
  45 ;; resulting code clearer and more efficient.
  46 ;;
  47
  48 ;;; Code:
  49
  50 \f
  51 ;; Globals
  52
  53 ;; Use color for the MS-DOS port because it doesn't support underline.
  54 (defface button '((((type pc) (class color))
  55                    (:foreground "lightblue"))
  56                   (t :underline t))
  57   "Default face used for buttons."
  58   :group 'basic-faces)
  59
  60 ;;;###autoload
  61 (defvar button-map
  62   (let ((map (make-sparse-keymap)))
  63     (define-key map "\r" 'push-button)
  64     (define-key map [mouse-2] 'push-button)
  65     map)
  66   "Keymap used by buttons.")
  67
  68 ;;;###autoload
  69 (defvar button-buffer-map
  70   (let ((map (make-sparse-keymap)))
  71     (define-key map [?\t] 'forward-button)
  72     (define-key map "\e\t" 'backward-button)
  73     (define-key map [backtab] 'backward-button)
  74     map)
  75   "Keymap useful for buffers containing buttons.
  76 Mode-specific keymaps may want to use this as their parent keymap.")
  77
  78 ;; Default properties for buttons
  79 (put 'default-button 'face 'button)
  80 (put 'default-button 'mouse-face 'highlight)
  81 (put 'default-button 'keymap button-map)
  82 (put 'default-button 'type 'button)
  83 ;; action may be either a function to call, or a marker to go to
  84 (put 'default-button 'action 'ignore)
  85 (put 'default-button 'help-echo "mouse-2, RET: Push this button")
  86 ;; Make overlay buttons go away if their underlying text is deleted.
  87 (put 'default-button 'evaporate t)
  88 ;; Prevent insertions adjacent to the text-property buttons from
  89 ;; inheriting its properties.
  90 (put 'default-button 'rear-nonsticky t)
  91 ;; Text property buttons don't have a `button' property of their own, so
  92 ;; they inherit this.
  93 (put 'default-button 'button t)
  94
  95 ;; A `category-symbol' property for the default button type
  96 (put 'button 'button-category-symbol 'default-button)
  97
  98 \f
  99 ;; Button types (which can be used to hold default properties for buttons)
 100
 101 ;; Because button-type properties are inherited by buttons using the
 102 ;; special `category' property (implemented by both overlays and
 103 ;; text-properties), we need to store them on a symbol to which the
 104 ;; `category' properties can point.  Instead of using the symbol that's
 105 ;; the name of each button-type, however, we use a separate symbol (with
 106 ;; `-button' appended, and uninterned) to store the properties.  This is
 107 ;; to avoid name clashes.
 108
 109 ;; [this is an internal function]
 110 (defsubst button-category-symbol (type)
 111   "Return the symbol used by button-type TYPE to store properties.
 112 Buttons inherit them by setting their `category' property to that symbol."
 113   (or (get type 'button-category-symbol)
 114       (error "Unknown button type `%s'" type)))
 115
 116 ;;;###autoload
 117 (defun define-button-type (name &rest properties)
 118   "Define a `button type' called NAME.
 119 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 120 specifying properties to use as defaults for buttons with this type
 121 \(a button's type may be set by giving it a `type' property when
 122 creating the button, using the :type keyword argument).
 123
 124 In addition, the keyword argument :supertype may be used to specify a
 125 button-type from which NAME inherits its default property values
 126 \(however, the inheritance happens only when NAME is defined; subsequent
 127 changes to a supertype are not reflected in its subtypes)."
 128   (let ((catsym (make-symbol (concat (symbol-name name) "-button")))
 129         (super-catsym
 130          (button-category-symbol
 131           (or (plist-get properties 'supertype)
 132               (plist-get properties :supertype)
 133               'button))))
 134     ;; Provide a link so that it's easy to find the real symbol.
 135     (put name 'button-category-symbol catsym)
 136     ;; Initialize NAME's properties using the global defaults.
 137     (let ((default-props (symbol-plist super-catsym)))
 138       (while default-props
 139         (put catsym (pop default-props) (pop default-props))))
 140     ;; Add NAME as the `type' property, which will then be returned as
 141     ;; the type property of individual buttons.
 142     (put catsym 'type name)
 143     ;; Add the properties in PROPERTIES to the real symbol.
 144     (while properties
 145       (let ((prop (pop properties)))
 146         (when (eq prop :supertype)
 147           (setq prop 'supertype))
 148         (put catsym prop (pop properties))))
 149     ;; Make sure there's a `supertype' property
 150     (unless (get catsym 'supertype)
 151       (put catsym 'supertype 'button))
 152     name))
 153
 154 (defun button-type-put (type prop val)
 155   "Set the button-type TYPE's PROP property to VAL."
 156   (put (button-category-symbol type) prop val))
 157
 158 (defun button-type-get (type prop)
 159   "Get the property of button-type TYPE named PROP."
 160   (get (button-category-symbol type) prop))
 161
 162 (defun button-type-subtype-p (type supertype)
 163   "Return t if button-type TYPE is a subtype of SUPERTYPE."
 164   (or (eq type supertype)
 165       (and type
 166            (button-type-subtype-p (button-type-get type 'supertype)
 167                                   supertype))))
 168
 169 \f
 170 ;; Button properties and other attributes
 171
 172 (defun button-start (button)
 173   "Return the position at which BUTTON starts."
 174   (if (overlayp button)
 175       (overlay-start button)
 176     ;; Must be a text-property button.
 177     (or (previous-single-property-change (1+ button) 'button)
 178         (point-min))))
 179
 180 (defun button-end (button)
 181   "Return the position at which BUTTON ends."
 182   (if (overlayp button)
 183       (overlay-end button)
 184     ;; Must be a text-property button.
 185     (or (next-single-property-change button 'button)
 186         (point-max))))
 187
 188 (defun button-get (button prop)
 189   "Get the property of button BUTTON named PROP."
 190   (if (overlayp button)
 191       (overlay-get button prop)
 192     ;; Must be a text-property button.
 193     (get-text-property button prop)))
 194
 195 (defun button-put (button prop val)
 196   "Set BUTTON's PROP property to VAL."
 197   ;; Treat some properties specially.
 198   (cond ((memq prop '(type :type))
 199          ;; We translate a `type' property a `category' property, since
 200          ;; that's what's actually used by overlays/text-properties for
 201          ;; inheriting properties.
 202          (setq prop 'category)
 203          (setq val (button-category-symbol val)))
 204         ((eq prop 'category)
 205          ;; Disallow updating the `category' property directly.
 206          (error "Button `category' property may not be set directly")))
 207   ;; Add the property.
 208   (if (overlayp button)
 209       (overlay-put button prop val)
 210     ;; Must be a text-property button.
 211     (put-text-property
 212      (or (previous-single-property-change (1+ button) 'button)
 213          (point-min))
 214      (or (next-single-property-change button 'button)
 215          (point-max))
 216      prop val)))
 217
 218 (defsubst button-activate (button &optional use-mouse-action)
 219   "Call BUTTON's action property.
 220 If USE-MOUSE-ACTION is non-nil, invoke the button's mouse-action
 221 instead of its normal action; if the button has no mouse-action,
 222 the normal action is used instead."
 223   (let ((action (or (and use-mouse-action (button-get button 'mouse-action))
 224                     (button-get button 'action))))
 225     (if (markerp action)
 226         (save-selected-window
 227           (select-window (display-buffer (marker-buffer action)))
 228           (goto-char action)
 229           (recenter 0))
 230       (funcall action button))))
 231
 232 (defun button-label (button)
 233   "Return BUTTON's text label."
 234   (buffer-substring-no-properties (button-start button) (button-end button)))
 235
 236 (defsubst button-type (button)
 237   "Return BUTTON's button-type."
 238   (button-get button 'type))
 239
 240 (defun button-has-type-p (button type)
 241   "Return t if BUTTON has button-type TYPE, or one of TYPE's subtypes."
 242   (button-type-subtype-p (button-get button 'type) type))
 243
 244 \f
 245 ;; Creating overlay buttons
 246
 247 ;;;###autoload
 248 (defun make-button (beg end &rest properties)
 249   "Make a button from BEG to END in the current buffer.
 250 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 251 specifying properties to add to the button.
 252 In addition, the keyword argument :type may be used to specify a
 253 button-type from which to inherit other properties; see
 254 `define-button-type'.
 255
 256 Also see `make-text-button', `insert-button'."
 257   (let ((overlay (make-overlay beg end nil t nil)))
 258     (while properties
 259       (button-put overlay (pop properties) (pop properties)))
 260     ;; Put a pointer to the button in the overlay, so it's easy to get
 261     ;; when we don't actually have a reference to the overlay.
 262     (overlay-put overlay 'button overlay)
 263     ;; If the user didn't specify a type, use the default.
 264     (unless (overlay-get overlay 'category)
 265       (overlay-put overlay 'category 'default-button))
 266     ;; OVERLAY is the button, so return it
 267     overlay))
 268
 269 ;;;###autoload
 270 (defun insert-button (label &rest properties)
 271   "Insert a button with the label LABEL.
 272 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 273 specifying properties to add to the button.
 274 In addition, the keyword argument :type may be used to specify a
 275 button-type from which to inherit other properties; see
 276 `define-button-type'.
 277
 278 Also see `insert-text-button', `make-button'."
 279   (apply #'make-button
 280          (prog1 (point) (insert label))
 281          (point)
 282          properties))
 283
 284 \f
 285 ;; Creating text-property buttons
 286
 287 ;;;###autoload
 288 (defun make-text-button (beg end &rest properties)
 289   "Make a button from BEG to END in the current buffer.
 290 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 291 specifying properties to add to the button.
 292 In addition, the keyword argument :type may be used to specify a
 293 button-type from which to inherit other properties; see
 294 `define-button-type'.
 295
 296 This function is like `make-button', except that the button is actually
 297 part of the text instead of being a property of the buffer.  Creating
 298 large numbers of buttons can also be somewhat faster using
 299 `make-text-button'.
 300
 301 Also see `insert-text-button'."
 302   (let ((type-entry
 303          (or (plist-member properties 'type)
 304              (plist-member properties :type))))
 305     ;; Disallow setting the `category' property directly.
 306     (when (plist-get properties 'category)
 307       (error "Button `category' property may not be set directly"))
 308     (if (null type-entry)
 309         ;; The user didn't specify a `type' property, use the default.
 310         (setq properties (cons 'category (cons 'default-button properties)))
 311       ;; The user did specify a `type' property.  Translate it into a
 312       ;; `category' property, which is what's actually used by
 313       ;; text-properties for inheritance.
 314       (setcar type-entry 'category)
 315       (setcar (cdr type-entry)
 316               (button-category-symbol (car (cdr type-entry))))))
 317   ;; Now add all the text properties at once
 318   (add-text-properties beg end properties)
 319   ;; Return something that can be used to get at the button.
 320   beg)
 321
 322 ;;;###autoload
 323 (defun insert-text-button (label &rest properties)
 324   "Insert a button with the label LABEL.
 325 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 326 specifying properties to add to the button.
 327 In addition, the keyword argument :type may be used to specify a
 328 button-type from which to inherit other properties; see
 329 `define-button-type'.
 330
 331 This function is like `insert-button', except that the button is
 332 actually part of the text instead of being a property of the buffer.
 333 Creating large numbers of buttons can also be somewhat faster using
 334 `insert-text-button'.
 335
 336 Also see `make-text-button'."
 337   (apply #'make-text-button
 338          (prog1 (point) (insert label))
 339          (point)
 340          properties))
 341
 342 \f
 343 ;; Finding buttons in a buffer
 344
 345 (defun button-at (pos)
 346   "Return the button at position POS in the current buffer, or nil."
 347   (let ((button (get-char-property pos 'button)))
 348     (if (or (overlayp button) (null button))
 349         button
 350       ;; Must be a text-property button; return a marker pointing to it.
 351       (copy-marker pos t))))
 352
 353 (defun next-button (pos &optional count-current)
 354   "Return the next button after position POS in the current buffer.
 355 If COUNT-CURRENT is non-nil, count any button at POS in the search,
 356 instead of starting at the next button."
 357     (unless count-current
 358       ;; Search for the next button boundary.
 359       (setq pos (next-single-char-property-change pos 'button)))
 360     (and (< pos (point-max))
 361          (or (button-at pos)
 362              ;; We must have originally been on a button, and are now in
 363              ;; the inter-button space.  Recurse to find a button.
 364              (next-button pos))))
 365
 366 (defun previous-button (pos &optional count-current)
 367   "Return the Nth button before position POS in the current buffer.
 368 If COUNT-CURRENT is non-nil, count any button at POS in the search,
 369 instead of starting at the next button."
 370   (unless count-current
 371     (setq pos (previous-single-char-property-change pos 'button)))
 372   (and (> pos (point-min))
 373        (or (button-at (1- pos))
 374            ;; We must have originally been on a button, and are now in
 375            ;; the inter-button space.  Recurse to find a button.
 376            (previous-button pos))))
 377
 378 \f
 379 ;; User commands
 380
 381 (defun push-button (&optional pos use-mouse-action)
 382   "Perform the action specified by a button at location POS.
 383 POS may be either a buffer position or a mouse-event.  If
 384 USE-MOUSE-ACTION is non-nil, invoke the button's mouse-action
 385 instead of its normal action; if the button has no mouse-action,
 386 the normal action is used instead.  The action may be either a
 387 function to call or a marker to display.
 388 POS defaults to point, except when `push-button' is invoked
 389 interactively as the result of a mouse-event, in which case, the
 390 mouse event is used.
 391 If there's no button at POS, do nothing and return nil, otherwise
 392 return t."
 393   (interactive
 394    (list (if (integerp last-command-event) (point) last-command-event)))
 395   (if (and (not (integerp pos)) (eventp pos))
 396       ;; POS is a mouse event; switch to the proper window/buffer
 397       (let ((posn (event-start pos)))
 398         (with-current-buffer (window-buffer (posn-window posn))
 399           (push-button (posn-point posn) t)))
 400     ;; POS is just normal position
 401     (let ((button (button-at (or pos (point)))))
 402       (if (not button)
 403           nil
 404         (button-activate button use-mouse-action)
 405         t))))
 406
 407 (defun forward-button (n &optional wrap display-message)
 408   "Move to the Nth next button, or Nth previous button if N is negative.
 409 If N is 0, move to the start of any button at point.
 410 If WRAP is non-nil, moving past either end of the buffer continues from the
 411 other end.
 412 If DISPLAY-MESSAGE is non-nil, the button's help-echo string is displayed.
 413 Any button with a non-nil `skip' property is skipped over.
 414 Returns the button found."
 415   (interactive "p\nd\nd")
 416   (let (button)
 417     (if (zerop n)
 418         ;; Move to start of current button
 419         (if (setq button (button-at (point)))
 420             (goto-char (button-start button)))
 421       ;; Move to Nth next button
 422       (let ((iterator (if (> n 0) #'next-button #'previous-button))
 423             (wrap-start (if (> n 0) (point-min) (point-max))))
 424         (setq n (abs n))
 425         (setq button t)                 ; just to start the loop
 426         (while (and (> n 0) button)
 427           (setq button (funcall iterator (point)))
 428           (when (and (not button) wrap)
 429             (setq button (funcall iterator wrap-start t)))
 430           (when button
 431             (goto-char (button-start button))
 432             (unless (button-get button 'skip)
 433               (setq n (1- n)))))))
 434     (if (null button)
 435         (error (if wrap "No buttons!" "No more buttons"))
 436       (let ((msg (and display-message (button-get button 'help-echo))))
 437         (when msg
 438           (message "%s" msg)))
 439       button)))
 440
 441 (defun backward-button (n &optional wrap display-message)
 442   "Move to the Nth previous button, or Nth next button if N is negative.
 443 If N is 0, move to the start of any button at point.
 444 If WRAP is non-nil, moving past either end of the buffer continues from the
 445 other end.
 446 If DISPLAY-MESSAGE is non-nil, the button's help-echo string is displayed.
 447 Any button with a non-nil `skip' property is skipped over.
 448 Returns the button found."
 449   (interactive "p\nd\nd")
 450   (forward-button (- n) wrap display-message))
 451
 452
 453 (provide 'button)
 454
 455 ;;; arch-tag: 5f2c7627-413b-4097-b282-630f89d9c5e9
 456 ;;; button.el ends here