Re: Community improvements to the Emacs Widget Library manual?

[Mauro Aranda]

Bryce <bovine@cyberscientist.ca> writes:

> Mauro Aranda <maurooaranda@gmail.com> writes:
>
>> Bryce Carson <bovine@cyberscientist.ca> writes:

>> I'm absolutely willing to help.  If you have the code somewhere, or if
>> you want to tell me what are the things you're finding difficult, I can
>> try to help you out.  And maybe that can give me some ideas about what
>> to improve in the Widget documentation.
>
> I haven't made any code public yet because I am still deciding on how I
> want to publish it. I may provide the code on my GitHub, or I might
> provide it on my personal website to churn up some traffic.
>
> The biggest issue I've had with the library is creating a working SEXP
> widget. I wanted to match _any_ symoblic expression that would create an
> object of a specific type (using :validate). I have settled on something
> much more reasonable (a choice-menu) instead, especially while I dogfood
> and bootstrap the application.

It sounds to me like you want to use a custom widget type whose parent
is the 'restricted-sexp widget, and define a :match function to do the
matching.   Do you recall if you tried to use that widget, or what
widget did you try to use? If you did, do you recall what problems you
ran into?

>>  > One aspect that is confusing is widget definition with 
widget-specific
>>  > argument handling. Built-in widgets handle arguments after the
>>  > keyword-value pairs in widget-specific ways. How do end users create
>>  > such behaviour in their own widgets? The answer is a function 
value for
>>  > the widget-create keyword, but this is a difficult thing to 
implement.
>>
>> Please tell more about the difficulties you have encountered. If you
>> can show a piece of code to show what you expected and what really
>> happens, then better yet.
>
> I responded to Michael in detail concerning :widget-create and the
> handling of further (non-keyword) arguments.
>
> To quote the library,
>
>     | This is the general syntax of a type specification:
>     |
>     |      NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS)
>     |           |   NAME
>     |
>     |    Where, NAME is a widget name, KEYWORD is the name of a
>     | property, ARGUMENT is the value of the property, and ARGS are
>     | interpreted in a widget specific way.
>
> ARGS in the general type specification is not one of the pairs of
> :keyword value pairs, it is anything else. I forget where it is stated,
> but I believe the manual says that any non-keyword value pair arguments
> must follow the pairs (if any pairs exist). How to define the handling
> of such ARGS in a custom widget is never exampled in the manual; it
> certainly isn't a simple (widget-args) function call away.

The widget specific way is handled via a :convert-widget function.

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.

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.

> When replying to Michael, I gave the example of the ITEM widget, which
> doesn't handle any of the §5 keyword arguments in a special way, but
> will initialize :value on behalf of the user with VALUE (see §5.9).

Yes.  And that's another undocumented thing.  The :convert-widget
function for the 'item widget is widget-value-convert-widget, which is
documented.

> The description of the ITEM widget, while on the topic, should probably
> be expanded to elaborate on what last sentence means. When matching
> against widgets, is a (widget-find type) function being used?

No, the last sentence "This widget will only match the specified value."
means that the :match function will return non-nil if the value passed
to it is equal to the :value upon creation.

> It would be nice if there was a Widget Object Model, where all widgets
> are rooted in the buffer they belong to, but that's a lofty, far off
> goal like a WidgeTRY™ RAD for the Emacs Widget Library.

Yes, it'd be nice if we could show the hierarchy.  For now, all we have
is widget-browse, and navigate through the super widgets.

>>  > The Emacs Widget Library manual could use a re-write [...]
>>
>> I'm not sure about a re-write.  But yes, I feel like there's more room
>> for improvement.  And count me in as one possible collaborator to
>> improve it.
>
> Great! I hope the possibility is realized.
>
> Considering the age of the library (twenty-three years! [if the
> earlier copyright year is correct]), and the support for embedded
> graphics like GTK+ widgets (so far only WebkitGTK…) _has_ improved,
> perhaps this statement could be removed or edited in some way? At least
> the part about the _automatic_ improvement in graphical appearance. I
> feel like that is not correct, but I could easily be wrong (if these are
> merely _goals_ for the library, not the state of affairs).
>
>     7. As support for embedded graphics improve, the widget library will
>        be extended to use the GUI features.  This means that your code
>        using the widget library will also use the new graphic features
>        automatically.

I don't know if that item is relevant anymore.  Maybe should be moved to
the Wishlist section, which surely needs an update.