Re: Community improvements to the Emacs Widget Library manual?

[Michael Heerdegen]

Mauro Aranda <maurooaranda@gmail.com> writes:

> Creation of a widget takes two steps: conversion and creation.
>
> Conversion means to take a specification of the widget to be created
> (type and properties) and convert that specification into another one,
> suitable for creating the widget.  So if you want to handle those extra
> args in a specific way, or to manipulate the widget before creation, you
> need a :convert-widget function, that widget-convert (which is
> undocumented in the manual) will make sure to call.  It will call the
> most specific :convert-widget function first, and then the
> :convert-widget of the parents.

This would be a nice paragraph to add to the manual I think.

> You can see an example of this in the following code:
>
> (defun completion--update-styles-options (widget)
>   "Function to keep updated the options in
> `completion-category-overrides'."
>   (let ((lst (mapcar (lambda (x)
>                        (list 'const (car x)))
>              completion-styles-alist)))
>     (widget-put widget :args (mapcar #'widget-convert lst))
>     widget))
>
> (defconst completion--styles-type
>   `(repeat :tag "insert a new menu to add more styles"
>            (choice :convert-widget completion--update-styles-options)))
>
> Here completion--styles-type holds a type definition for a defcustom,
> and the idea is to make the choices available build dynamically.
> Without a custom :convert-widget function, the :args would've been
> defined in a static way as soon as the type gets defined.  So we use a
> :convert-widget function that builds the choices, and puts them into the
> :args property, as required by the choice widget.  Then, when creating
> it, all the choices in :args show up in the buffer.

And this is a nice example for it!



BTW, one thing I often wondered about (I think it's missing in the
manual): one often sees code using list values like

`(widget-type :keyword1 ,(lambda ...) ...)

What is that?  Already a widget?  A widget definition?  What functions
accept such list values, and how do I create a real widget using such
values?


Michael.