Re: Getting help for a widget

[Lennart Borgman <lennart.borgman.073@student.lu.se>]

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 &^!@% 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))))