* bug#66229: 30.0.50; Add examples to the Widget Library Manual
2023-09-27 10:47 bug#66229: 30.0.50; Add examples to the Widget Library Manual Mauro Aranda
@ 2023-09-27 10:51 ` Mauro Aranda
2024-01-10 21:29 ` Stefan Kangas
0 siblings, 1 reply; 3+ messages in thread
From: Mauro Aranda @ 2023-09-27 10:51 UTC (permalink / raw)
To: 66229
[-- Attachment #1: Type: text/plain, Size: 39 bytes --]
Patch attached.
Please review, thanks.
[-- Attachment #2: 0001-Add-examples-to-the-Widget-manual-Bug-66229.patch --]
[-- Type: text/x-patch, Size: 9302 bytes --]
From c426718837acd71c5ea1b175de2f0488048095ab Mon Sep 17 00:00:00 2001
From: Mauro Aranda <maurooaranda@gmail.com>
Date: Fri, 22 Sep 2023 20:45:00 -0300
Subject: [PATCH] Add examples to the Widget manual (Bug#66229)
* doc/misc/widget.texi (Widget Gallery, Defining New Widgets): Add
examples.
---
doc/misc/widget.texi | 206 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 206 insertions(+)
diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi
index eb411f29c5c..2d4545c68d2 100644
--- a/doc/misc/widget.texi
+++ b/doc/misc/widget.texi
@@ -1384,6 +1384,15 @@ item
@code{:value} property. When created, it inserts the value as a
string in the buffer.
+@noindent
+Example:
+
+@lisp
+(widget-create 'item :tag "Today is" :format "%t: %v\n"
+ (format-time-string "%d-%m-%Y"))
+@end lisp
+
+
By default, it has the following properties:
@table @code
@@ -1428,6 +1437,20 @@ link
property. The value should be a string, which will be inserted in the
buffer.
+@noindent
+Example:
+
+@lisp
+(widget-create 'link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Mail yourself"
+ :action #'(lambda (widget &optional _event)
+ (compose-mail-other-window (widget-value widget)))
+ user-mail-address)
+@end lisp
+
+
By default, it has the following properties:
@table @code
@@ -1471,6 +1494,29 @@ url-link
It overrides the @code{:action} property to open up the @var{url}
specified.
+@noindent
+Example:
+
+@lisp
+(widget-create 'url-link
+ :button-prefix ""
+ :button-suffix ""
+ ;; Return appropriate face.
+ :button-face-get (lambda (widget)
+ (if (widget-get widget :visited)
+ 'link-visited
+ 'link))
+ :format "%[%t%]"
+ :tag "Browse this manual"
+ :action (lambda (widget &optional _event)
+ (widget-put widget :visited t)
+ ;; Takes care of redrawing the widget.
+ (widget-value-set widget (widget-value widget))
+ ;; And then call the original function.
+ (widget-url-link-action widget))
+ "https://www.gnu.org/software/emacs/manual/html_mono/widget.html")
+@end lisp
+
@node info-link
@subsection The @code{info-link} Widget
@findex info-link@r{ widget}
@@ -1487,6 +1533,17 @@ info-link
It overrides the @code{:action} property, to a function to start the
built-in Info reader on @var{address}, when invoked.
+@noindent
+Example:
+
+@lisp
+(widget-create 'info-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Browse this manual"
+ "(widget) info-link")))
+@end lisp
+
@node function-link
@subsection The @code{function-link} Widget
@findex function-link@r{ widget}
@@ -1502,6 +1559,17 @@ function-link
It overrides the @code{:action} property, to a function to describe
@var{function}.
+@noindent
+Example:
+
+@lisp
+(widget-create 'function-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Describe the function that gets called"
+ #'widget-function-link-action)
+@end lisp
+
@node variable-link
@subsection The @code{variable-link} Widget
@findex variable-link@r{ widget}
@@ -1517,6 +1585,17 @@ variable-link
It overrides the @code{:action} property, to a function to describe
@var{var}.
+@noindent
+Example:
+
+@lisp
+(widget-create 'variable-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "What setting controlls button-prefix?"
+ 'widget-button-prefix)
+@end lisp
+
@node face-link
@subsection The @code{face-link} Widget
@findex face-link@r{ widget}
@@ -1532,6 +1611,17 @@ face-link
It overrides the @code{:action} property, to a function to describe
@var{face}.
+@noindent
+Example:
+
+@lisp
+(widget-create 'face-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Which face is this one?"
+ 'widget-button)
+@end lisp
+
@node file-link
@subsection The @code{file-link} Widget
@findex file-link@r{ widget}
@@ -1547,6 +1637,19 @@ file-link
It overrides the @code{:action} property, to a function to find the file
@var{file}.
+@noindent
+Example:
+
+@lisp
+(let ((elisp-files (directory-files user-emacs-directory t ".el$")))
+ (dolist (file elisp-files)
+ (widget-create 'file-link
+ :button-prefix ""
+ :button-suffix ""
+ file)
+ (widget-insert "\n")))
+@end lisp
+
@node emacs-library-link
@subsection The @code{emacs-library-link} Widget
@findex emacs-library-link@r{ widget}
@@ -1562,6 +1665,17 @@ emacs-library-link
It overrides the @code{:action} property, to a function to find the file
@var{file}.
+@noindent
+Example:
+
+@lisp
+(widget-create 'emacs-library-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Show yourself, Widget Library!"
+ "wid-edit.el")
+@end lisp
+
@node emacs-commentary-link
@subsection The @code{emacs-commentary-link} Widget
@findex emacs-commentary-link@r{ widget}
@@ -1577,6 +1691,17 @@ emacs-commentary-link
It overrides the @code{:action} property, to a function to find the file
@var{file} and put point in the Comment section.
+@noindent
+Example:
+
+@lisp
+(widget-create 'emacs-commentary-link
+ :button-prefix ""
+ :button-suffix ""
+ :tag "Check our good friend Customize"
+ "cus-edit.el")
+@end lisp
+
@node push-button
@subsection The @code{push-button} Widget
@findex push-button@r{ widget}
@@ -2009,6 +2134,29 @@ toggle
The widget has two possible states, @samp{on} and @samp{off}, which
correspond to a @code{t} or @code{nil} value, respectively.
+@noindent
+Example:
+
+@lisp
+(widget-insert "Press the button to activate/deactivate the field: ")
+(widget-create 'toggle
+ :notify (lambda (widget &rest _ignored)
+ (widget-apply widget-example-field
+ (if (widget-value widget)
+ :activate
+ :deactivate))))
+(widget-insert "\n")
+(setq widget-example-field
+ (widget-create 'editable-field
+ :deactivate (lambda (widget)
+ (widget-specify-inactive
+ widget
+ (widget-field-start widget)
+ (widget-get widget :to)))))
+(widget-apply widget-example-field :deactivate)))
+@end lisp
+
+
It either overrides or adds the following properties:
@table @code
@@ -2148,6 +2296,21 @@ checklist
value will be a list containing the values of all checked @var{type}
arguments.
+@noindent
+Example:
+
+@lisp
+(widget-create 'checklist
+ :notify (lambda (widget child &optional _event)
+ (funcall
+ (widget-value (widget-get-sibling child))
+ 'toggle))
+ :value (list 'tool-bar-mode 'menu-bar-mode)
+ '(item :tag "Tool-bar" tool-bar-mode)
+ '(item :tag "Menu-bar" menu-bar-mode))))
+@end lisp
+
+
It either overrides or adds the following properties:
@table @code
@@ -2899,6 +3062,49 @@ Defining New Widgets
@code{widget-value-convert-widget} can be used here.
@end table
+@noindent
+Example:
+
+@lisp
+(defvar widget-ranged-integer-map
+ (let ((map (copy-keymap widget-keymap)))
+ (define-key map [up] #'widget-ranged-integer-increase)
+ (define-key map [down] #'widget-ranged-integer-decrease)
+ map))
+
+(define-widget 'ranged-integer 'integer
+ "A ranged integer widget."
+ :min-value most-negative-fixnum
+ :max-value most-positive-fixnum
+ :keymap widget-ranged-integer-map)
+
+(defun widget-ranged-integer-change (widget how)
+ "Change the value of the ranged-integer WIDGET, according to HOW."
+ (let* ((value (widget-value widget))
+ (newval (cond
+ ((eq how 'up)
+ (if (< (1+ value) (widget-get widget :max-value))
+ (1+ value)
+ (widget-get widget :max-value)))
+ ((eq how 'down)
+ (if (> (1- value) (widget-get widget :min-value))
+ (1- value)
+ (widget-get widget :min-value)))
+ (t (error "HOW has a bad value"))))
+ (inhibit-read-only t))
+ (widget-value-set widget newval)))
+
+(defun widget-ranged-integer-increase (widget)
+ "Increase the value of the ranged-integer WIDGET."
+ (interactive (list (widget-at)))
+ (widget-ranged-integer-change widget 'up))
+
+(defun widget-ranged-integer-decrease (widget)
+ "Decrease the value of the ranged-integer WIDGET."
+ (interactive (list (widget-at)))
+ (widget-ranged-integer-change widget 'down))
+@end lisp
+
@node Inspecting Widgets
@chapter Inspecting Widgets
@cindex widget browser
--
2.34.1
^ permalink raw reply related [flat|nested] 3+ messages in thread