lisp/button.el

   1 ;;; button.el --- clickable buttons
   2 ;;
   3 ;; Copyright (C) 2001, 2002, 2003, 2004, 2005,
   4 ;;   2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
   5 ;;
   6 ;; Author: Miles Bader <miles@gnu.org>
   7 ;; Keywords: extensions
   8 ;; Package: emacs
   9 ;;
  10 ;; This file is part of GNU Emacs.
  11 ;;
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public License for more details.
  21
  22 ;; You should have received a copy of the GNU General Public License
  23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
  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 ;; FIXME if MS-DOS correctly answers the (supports) question, it need
  55 ;; no longer be a special case.
  56 (defface button '((((type pc) (class color))
  57                    (:foreground "lightblue"))
  58                   (((supports :underline t)) :underline t)
  59                   (t (:foreground "lightblue")))
  60   "Default face used for buttons."
  61   :group 'basic-faces)
  62
  63 (defvar button-map
  64   (let ((map (make-sparse-keymap)))
  65     ;; The following definition needs to avoid using escape sequences that
  66     ;; might get converted to ^M when building loaddefs.el
  67     (define-key map [(control ?m)] 'push-button)
  68     (define-key map [mouse-2] 'push-button)
  69     map)
  70   "Keymap used by buttons.")
  71
  72 (defvar button-buffer-map
  73   (let ((map (make-sparse-keymap)))
  74     (define-key map [?\t] 'forward-button)
  75     (define-key map "\e\t" 'backward-button)
  76     (define-key map [backtab] 'backward-button)
  77     map)
  78   "Keymap useful for buffers containing buttons.
  79 Mode-specific keymaps may want to use this as their parent keymap.")
  80
  81 ;; Default properties for buttons
  82 (put 'default-button 'face 'button)
  83 (put 'default-button 'mouse-face 'highlight)
  84 (put 'default-button 'keymap button-map)
  85 (put 'default-button 'type 'button)
  86 ;; action may be either a function to call, or a marker to go to
  87 (put 'default-button 'action 'ignore)
  88 (put 'default-button 'help-echo (purecopy "mouse-2, RET: Push this button"))
  89 ;; Make overlay buttons go away if their underlying text is deleted.
  90 (put 'default-button 'evaporate t)
  91 ;; Prevent insertions adjacent to the text-property buttons from
  92 ;; inheriting its properties.
  93 (put 'default-button 'rear-nonsticky 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 (defun define-button-type (name &rest properties)
 117   "Define a `button type' called NAME (a symbol).
 118 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 119 specifying properties to use as defaults for buttons with this type
 120 \(a button's type may be set by giving it a `type' property when
 121 creating the button, using the :type keyword argument).
 122
 123 In addition, the keyword argument :supertype may be used to specify a
 124 button-type from which NAME inherits its default property values
 125 \(however, the inheritance happens only when NAME is defined; subsequent
 126 changes to a supertype are not reflected in its subtypes)."
 127   (let ((catsym (make-symbol (concat (symbol-name name) "-button")))
 128         (super-catsym
 129          (button-category-symbol
 130           (or (plist-get properties 'supertype)
 131               (plist-get properties :supertype)
 132               'button))))
 133     ;; Provide a link so that it's easy to find the real symbol.
 134     (put name 'button-category-symbol catsym)
 135     ;; Initialize NAME's properties using the global defaults.
 136     (let ((default-props (symbol-plist super-catsym)))
 137       (while default-props
 138         (put catsym (pop default-props) (pop default-props))))
 139     ;; Add NAME as the `type' property, which will then be returned as
 140     ;; the type property of individual buttons.
 141     (put catsym 'type name)
 142     ;; Add the properties in PROPERTIES to the real symbol.
 143     (while properties
 144       (let ((prop (pop properties)))
 145         (when (eq prop :supertype)
 146           (setq prop 'supertype))
 147         (put catsym prop (pop properties))))
 148     ;; Make sure there's a `supertype' property
 149     (unless (get catsym 'supertype)
 150       (put catsym 'supertype 'button))
 151     name))
 152
 153 (defun button-type-put (type prop val)
 154   "Set the button-type TYPE's PROP property to VAL."
 155   (put (button-category-symbol type) prop val))
 156
 157 (defun button-type-get (type prop)
 158   "Get the property of button-type TYPE named PROP."
 159   (get (button-category-symbol type) prop))
 160
 161 (defun button-type-subtype-p (type supertype)
 162   "Return t if button-type TYPE is a subtype of SUPERTYPE."
 163   (or (eq type supertype)
 164       (and type
 165            (button-type-subtype-p (button-type-get type 'supertype)
 166                                   supertype))))
 167
 168 \f
 169 ;; Button properties and other attributes
 170
 171 (defun button-start (button)
 172   "Return the position at which BUTTON starts."
 173   (if (overlayp button)
 174       (overlay-start button)
 175     ;; Must be a text-property button.
 176     (or (previous-single-property-change (1+ button) 'button)
 177         (point-min))))
 178
 179 (defun button-end (button)
 180   "Return the position at which BUTTON ends."
 181   (if (overlayp button)
 182       (overlay-end button)
 183     ;; Must be a text-property button.
 184     (or (next-single-property-change button 'button)
 185         (point-max))))
 186
 187 (defun button-get (button prop)
 188   "Get the property of button BUTTON named PROP."
 189   (if (overlayp button)
 190       (overlay-get button prop)
 191     ;; Must be a text-property button.
 192     (get-text-property button prop)))
 193
 194 (defun button-put (button prop val)
 195   "Set BUTTON's PROP property to VAL."
 196   ;; Treat some properties specially.
 197   (cond ((memq prop '(type :type))
 198          ;; We translate a `type' property a `category' property, since
 199          ;; that's what's actually used by overlays/text-properties for
 200          ;; inheriting properties.
 201          (setq prop 'category)
 202          (setq val (button-category-symbol val)))
 203         ((eq prop 'category)
 204          ;; Disallow updating the `category' property directly.
 205          (error "Button `category' property may not be set directly")))
 206   ;; Add the property.
 207   (if (overlayp button)
 208       (overlay-put button prop val)
 209     ;; Must be a text-property button.
 210     (put-text-property
 211      (or (previous-single-property-change (1+ button) 'button)
 212          (point-min))
 213      (or (next-single-property-change button 'button)
 214          (point-max))
 215      prop val)))
 216
 217 (defsubst button-activate (button &optional use-mouse-action)
 218   "Call BUTTON's action property.
 219 If USE-MOUSE-ACTION is non-nil, invoke the button's mouse-action
 220 instead of its normal action; if the button has no mouse-action,
 221 the normal action is used instead."
 222   (let ((action (or (and use-mouse-action (button-get button 'mouse-action))
 223                     (button-get button 'action))))
 224     (if (markerp action)
 225         (save-selected-window
 226           (select-window (display-buffer (marker-buffer action)))
 227           (goto-char action)
 228           (recenter 0))
 229       (funcall action button))))
 230
 231 (defun button-label (button)
 232   "Return BUTTON's text label."
 233   (buffer-substring-no-properties (button-start button) (button-end button)))
 234
 235 (defsubst button-type (button)
 236   "Return BUTTON's button-type."
 237   (button-get button 'type))
 238
 239 (defun button-has-type-p (button type)
 240   "Return t if BUTTON has button-type TYPE, or one of TYPE's subtypes."
 241   (button-type-subtype-p (button-get button 'type) type))
 242
 243 \f
 244 ;; Creating overlay buttons
 245
 246 (defun make-button (beg end &rest properties)
 247   "Make a button from BEG to END in the current buffer.
 248 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 249 specifying properties to add to the button.
 250 In addition, the keyword argument :type may be used to specify a
 251 button-type from which to inherit other properties; see
 252 `define-button-type'.
 253
 254 Also see `make-text-button', `insert-button'."
 255   (let ((overlay (make-overlay beg end nil t nil)))
 256     (while properties
 257       (button-put overlay (pop properties) (pop properties)))
 258     ;; Put a pointer to the button in the overlay, so it's easy to get
 259     ;; when we don't actually have a reference to the overlay.
 260     (overlay-put overlay 'button overlay)
 261     ;; If the user didn't specify a type, use the default.
 262     (unless (overlay-get overlay 'category)
 263       (overlay-put overlay 'category 'default-button))
 264     ;; OVERLAY is the button, so return it
 265     overlay))
 266
 267 (defun insert-button (label &rest properties)
 268   "Insert a button with the label LABEL.
 269 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 270 specifying properties to add to the button.
 271 In addition, the keyword argument :type may be used to specify a
 272 button-type from which to inherit other properties; see
 273 `define-button-type'.
 274
 275 Also see `insert-text-button', `make-button'."
 276   (apply #'make-button
 277          (prog1 (point) (insert label))
 278          (point)
 279          properties))
 280
 281 \f
 282 ;; Creating text-property buttons
 283
 284 (defun make-text-button (beg end &rest properties)
 285   "Make a button from BEG to END in the current buffer.
 286 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 287 specifying properties to add to the button.
 288 In addition, the keyword argument :type may be used to specify a
 289 button-type from which to inherit other properties; see
 290 `define-button-type'.
 291
 292 This function is like `make-button', except that the button is actually
 293 part of the text instead of being a property of the buffer.  Creating
 294 large numbers of buttons can also be somewhat faster using
 295 `make-text-button'.
 296
 297 BEG can also be a string, in which case it is made into a button.
 298
 299 Also see `insert-text-button'."
 300   (let ((object nil)
 301         (type-entry
 302          (or (plist-member properties 'type)
 303              (plist-member properties :type))))
 304     (when (stringp beg)
 305       (setq object beg beg 0 end (length object)))
 306     ;; Disallow setting the `category' property directly.
 307     (when (plist-get properties 'category)
 308       (error "Button `category' property may not be set directly"))
 309     (if (null type-entry)
 310         ;; The user didn't specify a `type' property, use the default.
 311         (setq properties (cons 'category (cons 'default-button properties)))
 312       ;; The user did specify a `type' property.  Translate it into a
 313       ;; `category' property, which is what's actually used by
 314       ;; text-properties for inheritance.
 315       (setcar type-entry 'category)
 316       (setcar (cdr type-entry)
 317               (button-category-symbol (car (cdr type-entry)))))
 318     ;; Now add all the text properties at once
 319     (add-text-properties beg end
 320                          ;; Each button should have a non-eq `button'
 321                          ;; property so that next-single-property-change can
 322                          ;; detect boundaries reliably.
 323                          (cons 'button (cons (list t) properties))
 324                          object)
 325     ;; Return something that can be used to get at the button.
 326     beg))
 327
 328 (defun insert-text-button (label &rest properties)
 329   "Insert a button with the label LABEL.
 330 The remaining arguments form a sequence of PROPERTY VALUE pairs,
 331 specifying properties to add to the button.
 332 In addition, the keyword argument :type may be used to specify a
 333 button-type from which to inherit other properties; see
 334 `define-button-type'.
 335
 336 This function is like `insert-button', except that the button is
 337 actually part of the text instead of being a property of the buffer.
 338 Creating large numbers of buttons can also be somewhat faster using
 339 `insert-text-button'.
 340
 341 Also see `make-text-button'."
 342   (apply #'make-text-button
 343          (prog1 (point) (insert label))
 344          (point)
 345          properties))
 346
 347 \f
 348 ;; Finding buttons in a buffer
 349
 350 (defun button-at (pos)
 351   "Return the button at position POS in the current buffer, or nil."
 352   (let ((button (get-char-property pos 'button)))
 353     (if (or (overlayp button) (null button))
 354         button
 355       ;; Must be a text-property button; return a marker pointing to it.
 356       (copy-marker pos t))))
 357
 358 (defun next-button (pos &optional count-current)
 359   "Return the next button after position POS in the current buffer.
 360 If COUNT-CURRENT is non-nil, count any button at POS in the search,
 361 instead of starting at the next button."
 362     (unless count-current
 363       ;; Search for the next button boundary.
 364       (setq pos (next-single-char-property-change pos 'button)))
 365     (and (< pos (point-max))
 366          (or (button-at pos)
 367              ;; We must have originally been on a button, and are now in
 368              ;; the inter-button space.  Recurse to find a button.
 369              (next-button pos))))
 370
 371 (defun previous-button (pos &optional count-current)
 372   "Return the previous button before position POS in the current buffer.
 373 If COUNT-CURRENT is non-nil, count any button at POS in the search,
 374 instead of starting at the next button."
 375   (let ((button (button-at pos)))
 376     (if button
 377         (if count-current
 378             button
 379           ;; We started out on a button, so move to its start and look
 380           ;; for the previous button boundary.
 381           (setq pos (previous-single-char-property-change
 382                      (button-start button) 'button))
 383           (let ((new-button (button-at pos)))
 384             (if new-button
 385                 ;; We are in a button again; this can happen if there
 386                 ;; are adjacent buttons (or at bob).
 387                 (unless (= pos (button-start button)) new-button)
 388               ;; We are now in the space between buttons.
 389               (previous-button pos))))
 390       ;; We started out in the space between buttons.
 391       (setq pos (previous-single-char-property-change pos 'button))
 392       (or (button-at pos)
 393           (and (> pos (point-min))
 394                (button-at (1- pos)))))))
 395
 396 \f
 397 ;; User commands
 398
 399 (defun push-button (&optional pos use-mouse-action)
 400   "Perform the action specified by a button at location POS.
 401 POS may be either a buffer position or a mouse-event.  If
 402 USE-MOUSE-ACTION is non-nil, invoke the button's mouse-action
 403 instead of its normal action; if the button has no mouse-action,
 404 the normal action is used instead.  The action may be either a
 405 function to call or a marker to display.
 406 POS defaults to point, except when `push-button' is invoked
 407 interactively as the result of a mouse-event, in which case, the
 408 mouse event is used.
 409 If there's no button at POS, do nothing and return nil, otherwise
 410 return t."
 411   (interactive
 412    (list (if (integerp last-command-event) (point) last-command-event)))
 413   (if (and (not (integerp pos)) (eventp pos))
 414       ;; POS is a mouse event; switch to the proper window/buffer
 415       (let ((posn (event-start pos)))
 416         (with-current-buffer (window-buffer (posn-window posn))
 417           (push-button (posn-point posn) t)))
 418     ;; POS is just normal position
 419     (let ((button (button-at (or pos (point)))))
 420       (if (not button)
 421           nil
 422         (button-activate button use-mouse-action)
 423         t))))
 424
 425 (defun forward-button (n &optional wrap display-message)
 426   "Move to the Nth next button, or Nth previous button if N is negative.
 427 If N is 0, move to the start of any button at point.
 428 If WRAP is non-nil, moving past either end of the buffer continues from the
 429 other end.
 430 If DISPLAY-MESSAGE is non-nil, the button's help-echo string is displayed.
 431 Any button with a non-nil `skip' property is skipped over.
 432 Returns the button found."
 433   (interactive "p\nd\nd")
 434   (let (button)
 435     (if (zerop n)
 436         ;; Move to start of current button
 437         (if (setq button (button-at (point)))
 438             (goto-char (button-start button)))
 439       ;; Move to Nth next button
 440       (let ((iterator (if (> n 0) #'next-button #'previous-button))
 441             (wrap-start (if (> n 0) (point-min) (point-max)))
 442             opoint fail)
 443         (setq n (abs n))
 444         (setq button t)                 ; just to start the loop
 445         (while (and (null fail) (> n 0) button)
 446           (setq button (funcall iterator (point)))
 447           (when (and (not button) wrap)
 448             (setq button (funcall iterator wrap-start t)))
 449           (when button
 450             (goto-char (button-start button))
 451             ;; Avoid looping forever (e.g., if all the buttons have
 452             ;; the `skip' property).
 453             (cond ((null opoint)
 454                    (setq opoint (point)))
 455                   ((= opoint (point))
 456                    (setq fail t)))
 457             (unless (button-get button 'skip)
 458               (setq n (1- n)))))))
 459     (if (null button)
 460         (error (if wrap "No buttons!" "No more buttons"))
 461       (let ((msg (and display-message (button-get button 'help-echo))))
 462         (when msg
 463           (message "%s" msg)))
 464       button)))
 465
 466 (defun backward-button (n &optional wrap display-message)
 467   "Move to the Nth previous button, or Nth next button if N is negative.
 468 If N is 0, move to the start of any button at point.
 469 If WRAP is non-nil, moving past either end of the buffer continues from the
 470 other end.
 471 If DISPLAY-MESSAGE is non-nil, the button's help-echo string is displayed.
 472 Any button with a non-nil `skip' property is skipped over.
 473 Returns the button found."
 474   (interactive "p\nd\nd")
 475   (forward-button (- n) wrap display-message))
 476
 477
 478 (provide 'button)
 479
 480 ;; arch-tag: 5f2c7627-413b-4097-b282-630f89d9c5e9
 481 ;;; button.el ends here