From 14ffab8263eb219fe0c49ad4e0a3476316c542c0 Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Fri, 11 Dec 2020 14:25:20 +0100
Subject: [PATCH] Add a new function `button-buttonize'

* doc/lispref/display.texi (Manipulating Buttons): Document it.

* lisp/button.el (button-buttonize): Implement it.
---
 doc/lispref/display.texi | 10 ++++++++++
 etc/NEWS                 | 22 +++++++++++++++-------
 lisp/button.el           | 12 ++++++++++++
 3 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ed26ae88087..590b54668f7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6881,6 +6881,16 @@ This inserts a button with the label @var{label} at point, using text
 properties.
 @end defun
 
+@defun button-buttonize string callback &optional data
+Sometimes it's more convenient to make a string into a button without
+inserting it into a buffer immediately, for instance when creating
+data structures that may then, later, be inserted into a buffer.  This
+function makes @var{string} into such a string, and @var{callback}
+will be called when the user clicks on the button.  The optional
+@var{data} parameter will be used as the parameter when @var{callback}
+is called.  If @code{nil}, the button is used as the parameter instead.
+@end defun
+
 @node Manipulating Buttons
 @subsection Manipulating Buttons
 @cindex manipulating buttons
diff --git a/etc/NEWS b/etc/NEWS
index 83fe7a349e3..f2772843e76 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1368,6 +1368,21 @@ This face is used for error messages from 'diff'.
 *** New command 'diff-refresh-hunk'.
 This new command (bound to 'C-c C-l') regenerates the current hunk.
 
+** Buttons
+
++++
+*** New minor mode 'button-mode'.
+This minor mode does nothing else than install 'button-buffer-map' as
+a minor mode map (which binds the 'TAB' / 'S-TAB' key bindings to navigate
+to buttons), and can be used in any view-mode-like buffer that has
+buttons in it.
+
++++
+*** New utility function 'button-buttonize'.
+This function takes a string and returns a string propertized in a way
+that makes it a valid button.
+
+
 ** Miscellaneous
 
 ---
@@ -1480,13 +1495,6 @@ both modes are on).
 This works like 'report-emacs-bug', but is more geared towards sending
 patches to the Emacs issue tracker.
 
-+++
-*** New minor mode 'button-mode'.
-This minor mode does nothing else than install 'button-buffer-map' as
-a minor mode map (which binds the 'TAB' / 'S-TAB' key bindings to navigate
-to buttons), and can be used in any view-mode-like buffer that has
-buttons in it.
-
 ---
 *** 'icomplete-show-matches-on-no-input' behavior change.
 Previously, choosing a different completion with commands like 'C-.'
diff --git a/lisp/button.el b/lisp/button.el
index ba0682348df..8dbb763281a 100644
--- a/lisp/button.el
+++ b/lisp/button.el
@@ -613,6 +613,18 @@ button at point is the button to describe."
       (button--describe props)
       t)))
 
+(defun button-buttonize (string callback &optional data)
+  "Make STRING into a button and return it.
+When clicked, CALLBACK will be called with the optional DATA parameter."
+  (propertize string
+              'face 'button
+              'button t
+              'follow-link t
+              'category t
+              'button-data data
+              'keymap button-map
+              'action callback))
+
 (provide 'button)
 
 ;;; button.el ends here
-- 
2.39.2