Re: Getting help for a widget

[Lennart Borgman]

Richard Stallman wrote:
>     This is perhaps the main difficulty of working with or even talking about
>     widgets (and, so, with Customize too) as either a user or a casual
>     developer: understanding what the &address@hidden is going on.
>
> I agree.  I find it very hard to understand that code.
>
> But what does it mean to "get help for a widget"?
> It is not clear to me, and maybe there is more than one
> kind we need.
>
>     If you press
>
>         C-h k
>
>     on a file you get help for `widget-button-press'. But what does the 
>     button do?
>
> I don't really follow that, but it seems to be a request
> for a better answer to the question, "What happens if i click here"?
>
> That could be useful, and perhaps C-h k ought to make a special
> case for the function widget-button-press.  That would not be hard.
> But where can it get the useful doc string to display?
>
> Meanwhile, this would not help people who are doing programming with
> widgets.  They need a different kind of help.
>
> In other words, it will take some real thought and study to figure out
> what "good help for widgets" would mean.  It would be useful for
> people to start exploring this now.
>   

As a little starter the two functions below can be used. The first one 
is new. Pub point over a widget or button and do

   M-x describe-field

This will open the widget browser. Badly needed in this are back and 
forward buttons (widgets of course ;-). Also badly needed IMHO are links 
to where widget-create are called. Can anyone explain how to add this? 
The information is available to the debugger, but is there a fast and 
simple way to get this information in `widget-create'?

The second function just makes links out of descriptions that are 
function names.

(defun describe-field(pos &optional use-mouse-action)
 (interactive (list (point)))
 ;; widget-browse-at
 (let* ((field (get-char-property pos 'field))
    (wbutton (get-char-property pos 'button))
    (doc (get-char-property pos 'widget-doc))
    (widget (or field wbutton doc)))
   ;;(message "widget=%s" widget)(sit-for 1)
   (if (and widget
            (if (symbolp widget)
                (get widget 'widget-type)
              (and (consp widget)
                   (get (widget-type widget) 'widget-type))))
       (widget-browse-at pos)
     ;; push-button
     (let ((button (button-at pos)))
       ;;(message "button=%s" button)(sit-for 1)
       (if button
           (let ((action (or (and use-mouse-action
                                  (button-get button 'mouse-action))
                             (button-get button 'action))))
             (message "action=%s" action)(sit-for 1)
             (describe-function (intern-soft action)))
         (message "No widget or button at point"))))))

(defun widget-browse-sexp (widget key value)
 "Insert description of WIDGET's KEY VALUE.
Nothing is assumed about value."
 (let ((pp (condition-case signal
       (pp-to-string value)
         (error (prin1-to-string signal)))))
   (when (string-match "\n\\'" pp)
     (setq pp (substring pp 0 (1- (length pp)))))
   (if (cond ((string-match "\n" pp)
          nil)
         ((> (length pp) (- (window-width) (current-column)))
          nil)
         (t t))
       (progn
         ;;(message "pp=<%s>" pp) (sit-for 1)
         (let ((pp-sym (intern-soft pp)))
         (if (and pp-sym
                  (fboundp pp-sym))
             (widget-create 'push-button
                            :tag pp
                            :value pp
                            :action '(lambda (widget &optional event)
                                       (let ((pp-symf (intern-soft 
(widget-get widget :value))))
                                         (describe-function pp-symf)))
                            pp)
           (widget-insert pp))))
     (widget-create 'push-button
            :tag "show"
            :action (lambda (widget &optional event)
                  (with-output-to-temp-buffer
                  "*Pp Eval Output*"
                (princ (widget-get widget :value))))
            pp))))