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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Wed, 11 Sep 2024 16:28:24 +0200
> From:  David Ponce via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> 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!

Thanks.  Mauro, could you please review and comment?

> 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))