Re: Community improvements to the Emacs Widget Library manual?

[Bryce <bovine@cyberscientist.ca>]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Bryce Carson <bovine@cyberscientist.ca> writes:
>
>> 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.
>
> What keyword handling do you mean, exactly (example)? I ask because
> AFAIR, `widget-create' works fine for user-defined widget types.

Writing :widget-create functions works, but there are no examples in the
manual. Using a function which specially handles arguments (I do not
mean the :args keyword [though in some cases, this would be what I do
mean (Widget is strange like that)]) is only suggested as possible by
the manual stating some built-in widgets do this. An example is the ITEM
widget, which has the following type definitionf:

     ITEM ::= (item [KEYWORD ARGUMENT]... VALUE)

This type definition syntax shows that after all of the
keyword-argument/keyword-value pairs that a VALUE must be supplied, but
that it does not need to be supplied as in the first form in the example
below.

    (widget-create 'item "Example item VALUE")
    (widget-create 'item :value "Example item :value ARGUMENT")

In the second form, I used ARGUMENT to match the type definition syntax
quoted above. Normally when writing about widgets, I will say
"Keyword-value pairs," because in most cases the :args keyword is simply
the list of arguments supplied to widget-create after the type argument,
like below.

    (widget-create 'TYPE ARGUMENTS...)
      => ()

> Then either these are used implicitly (by the widget type you are
> deriving from) - or you can refer to the values using `widget-get' in
> the functions implementing the widget behavior (in `define-widget').

The widget-get function will retrieve values of properties (which are
defined with keyword-argument and value pairs [:keyword-argument
value]). Perhaps I simply did not think long enough about how to write a
function which will access the elements of a list after exhausting any
keyword value pairs. The widget-put function can be used to set the
value of an arbitrary property, which yes, can then be retrieved with
widget-get.

Perhaps a new macro should be introduced into the library which
facilitates accessing the nth argument _past the keyword-argument value
pairs_ in a reproducible way. The function widget-convert loops over the
arguments, assessing if they are keywords and makes them part of the
value of the :args property of the widget being created (if it is using
the default widget-convert functionality).

> What I missed in the documentation most of all was an explanation of
> the meaning of the keywords. There are a lot, and I recall that some
> widget types totally ignore some keywords and one has to use another
> one with a similar name instead, etc. I.e. it would be good to
> document which keywords are meaningful for which builtin widget types.
>
> Michael.

Regards, Michael. Thanks for asking the pointed question, it did guide
my thinking a bit.