bug#73178: 31.0.50; [PATCH] Improve the widget to customize icon

[David Ponce via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

[-- Attachment #1: Type: text/plain, Size: 3524 bytes --]

Hello,

Whenever I try to use Emacs' built-in icons, I have some difficulty
understanding the user interface for customizing an icon. For example,
regardless of the type of icon element, all the fields have similar
labels, which makes the interface difficult to understand and use.
For instance, for Images, it is not clear that the String field is
intended to enter the image file name:

Choice: Value Menu [Images|Colorful Emojis|Monochrome Symbols|Text only]
Repeat:
INS DEL String:
INS
Plist:
INS DEL :
             Key:
             Value:
INS

Also, nothing guides you regarding usage of this complex widget.

I propose the attached patch that improves the widget used to
customize an icon. Possible ChangeLog:

2024-09-11  David Ponce  <da_vid@orange.fr>

	Improve usability of the widget used to customize icon.

	* lisp/cus-edit.el (custom-icon--images-sub-type)
	(custom-icon--emojis-sub-type, custom-icon--symbols-sub-type)
	(custom-icon--texts-sub-type): New constant.
	(custom-icon--type): New constant.
	(custom-icon-value-create): Use it.

With this patch, a quick help summarizes usage, and the different
fields are named according to the kind of icon element.

Here is a view of the new UI when customizing the default `button' icon:

---------------------------------------------------------------
Hide Button:
Icon elements:
- Only the first occurrence of a same element counts.
- Missing elements will take their default value.:
- At least one element should be provided with a valid value.

INS DEL Choice: Value Menu Images:
          
          Values:
          INS DEL Image filename:
          INS
          Image attributes:
          INS DEL :
                      Key: :face
                      Value: icon-button
          INS

INS DEL Choice: Value Menu Colorful Emojis:
          
          Values:
          INS DEL Emoji text: 🔵
          INS
          Emoji text properties:
          INS DEL :
                      Key: :face
                      Value: icon
          INS

INS DEL Choice: Value Menu Monochrome Symbols:
          
          Values:
          INS DEL Symbol text: ●
          INS
          Symbol text properties:
          INS DEL :
                      Key: :face
                      Value: icon-button
          INS

INS DEL Choice: Value Menu Texts Only:
          
          Values:
          INS DEL Text: button
          INS
          Text properties:
          INS DEL :
                      Key: :face
                      Value: icon-button
          INS

INS
---------------------------------------------------------------

WDYT?

Thanks!


In GNU Emacs 31.0.50 (build 3, x86_64-pc-linux-gnu, GTK+ Version
  3.24.43, cairo version 1.18.0) of 2024-09-11
Repository revision: 69e1aca041c57ba425425d31471e1c8f86d3bf04
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12014000
System Description: Fedora Linux 40 (KDE Plasma)

Configured using:
  'configure --with-x-toolkit=gtk3 --with-cairo-xcb
  --with-native-compilation=no
  PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig'

Configured features:
ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG
LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NOTIFY
INOTIFY PDUMPER PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB

Important settings:
   value of $LC_TIME: fr_FR.utf8
   value of $LANG: fr_FR.UTF-8
   locale-coding-system: utf-8-unix

[-- Attachment #2: improve-widget-to-customize-icon-V0.patch --]
[-- Type: text/x-patch, Size: 2776 bytes --]

diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el
index 3ab5f11532e..fd790b18630 100644
--- a/lisp/cus-edit.el
+++ b/lisp/cus-edit.el
@@ -5525,6 +5525,53 @@ custom-icon-extended-menu
   "A menu for `custom-icon' widgets.
 Used in `custom-icon-action' to show a menu to the user.")
 
+(defconst custom-icon--images-sub-type
+  '(list :format "%{%t%}:\n%v\n"
+         :tag "Images"
+         (const  :tag "" image)
+         (repeat :tag "Values"
+                 (string :tag "Image filename"))
+         (plist  :tag "Image attributes")))
+
+(defconst custom-icon--emojis-sub-type
+  '(list :format "%{%t%}:\n%v\n"
+         :tag "Colorful Emojis"
+         (const  :tag "" emoji)
+         (repeat :tag "Values"
+                 (string :tag "Emoji text"))
+         (plist  :tag "Emoji text properties")))
+
+(defconst custom-icon--symbols-sub-type
+  '(list :format "%{%t%}:\n%v\n"
+         :tag "Monochrome Symbols"
+         (const  :tag "" symbol)
+         (repeat :tag "Values"
+                 (string :tag "Symbol text"))
+         (plist  :tag "Symbol text properties")))
+
+(defconst custom-icon--texts-sub-type
+  '(list :format "%{%t%}:\n%v\n"
+         :tag "Texts Only"
+         (const  :tag "" text)
+         (repeat :tag "Values"
+                 (string :tag "Text"))
+         (plist  :tag "Text properties")))
+
+(defconst custom-icon--type
+  `(repeat :format ,(concat "%{%t%}"
+                            (propertize ":" 'display "")
+                            "\n\n%v%i\n")
+           :tag "Icon elements:
+- Only the first occurrence of a same element counts.
+- Missing elements will take their default value.
+- At least one element should be provided with a valid value."
+    (choice :void ,custom-icon--texts-widget
+            :extra-offset -3
+            ,custom-icon--images-sub-type
+            ,custom-icon--emojis-sub-type
+            ,custom-icon--symbols-sub-type
+            ,custom-icon--texts-sub-type)))
+
 (defun custom-icon-value-create (widget)
   "Here is where you edit the icon's specification."
   (custom-load-widget widget)
@@ -5535,13 +5582,7 @@ custom-icon-value-create
 	 (form (widget-get widget :custom-form))
 	 (symbol (widget-get widget :value))
 	 (tag (widget-get widget :tag))
-	 (type '(repeat
-                 (list (choice (const :tag "Images" image)
-                               (const :tag "Colorful Emojis" emoji)
-                               (const :tag "Monochrome Symbols" symbol)
-                               (const :tag "Text Only" text))
-                       (repeat string)
-                       plist)))
+	 (type custom-icon--widget)
 	 (prefix (widget-get widget :custom-prefix))
 	 (last (widget-get widget :custom-last))
 	 (style (widget-get widget :custom-style))