help-echo in Custom

help-echo in Custom

[Luc Teirlinck]

The CVS Elisp manual seems to suggest that the syntax for help-echo's
used in :help-echo type keywords in Custom is exactly the same as for
`help-echo' text properties used elsewhere. In Info do: 

(elisp)Type Keywords

There we find:

`:help-echo MOTION-DOC'
     When you move to this item with `widget-forward' or
     `widget-backward', it will display the string MOTION-DOC in the
     echo area.  In addition, MOTION-DOC is used as the mouse
     `help-echo' string and may actually be a function or form
     evaluated to yield a help string as for `help-echo' text
     properties.

First of all, :help-echo type keywords in Custom can not be variables
evaluating to strings.  I guess this one is just a bug and can be
fixed by putting two eval's in the last two lines of
`widget-echo-help':

(defun widget-echo-help (pos)
  "Display help-echo text for widget at POS."
  (let* ((widget (widget-at pos))
   (help-echo (and widget (widget-get widget :help-echo))))
    (if (functionp help-echo)
    (setq help-echo (funcall help-echo widget)))
    (if (stringp (eval help-echo))
    (message "%s" (eval help-echo)))))

There also is a fundamental difference in functional help-echo's.
Such help-echo's written for :help-echo type keywords in Custom have
to take one argument WIDGET.  help-echo's written for text properties
take three arguments.

Custom apparently goes to quite some length to do this conversion: it
actually uses `widget-mouse-help' as a place-holder 'echo-help
property with three arguments and then makes that one call the one
argument function:

(defun widget-mouse-help (window overlay point)
  "Help-echo callback for widgets whose :help-echo is a function."
  (with-current-buffer (overlay-buffer overlay)
    (let* ((widget (widget-at (overlay-start overlay)))
       (help-echo (if widget (widget-get widget :help-echo))))
      (if (functionp help-echo)
        (funcall help-echo widget)
	help-echo))))

Is this intentional (to make all the information in WIDGET available
to the function)?  If so, the documentation in the Elisp manual is not
only incomplete, but misleading.

If this is an unintentional bug, then I could send a test case
illustrating the problem, if desired.

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

>From my previous message:

   Custom apparently goes to quite some length to do this conversion: it
   actually uses `widget-mouse-help' as a place-holder 'echo-help
   property

I meant `help-echo' property, of course.

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

>From my previous message:

   First of all, :help-echo type keywords in Custom can not be variables
   evaluating to strings.

Well, they actually _do_ work on mouse-over, but not with <tab> and
S-<tab>.

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

Since at least one of the things I described seems to be a bug, here
is a test case anyway.

Load:

===File ~/helpfun.el========================================
(defvar silly-string "Silly string")

(defun silly-help (win obj pos)
  "Used as help-echo for debugging purposes."
  (format "%s %s %s" win obj pos))

(defun silly-custom-help (widget)
  (substring (format "%s" widget) 0 70))

(defcustom silly-string-var 7
  "*This is a silly variable"
  :type '(integer :help-echo silly-string)
  :group 'convenience)

(defcustom silly-help-var 7
  "*This is an silly variable"
  :type '(integer :help-echo silly-help)
  :group 'convenience)

(defcustom silly-custom-help-var 7
  "*This is a silly variable"
  :type '(integer :help-echo silly-custom-help)
  :group 'convenience)
============================================================

Do "M-x customize-group convenience" and start <tab>-ing around.

`silly-string-var' will not display "Silly string" after <tab>,
although it will on mouse-over.  This seems to be definitely a bug and
is trivial to fix by adding two eval's, as I pointed out in my
original message.

`silly-help-var' produces a "Wrong number of arguments" error when
<tab> gets there, even though `silly-help' works perfectly as a
help-echo text or overlay property.  Maybe not a bug, but pretty
confusing, since the Elisp manual clearly suggests that my function
needs to have three arguments.

`silly-custom-help-var' displays the silly help string I wanted it to
display.  Maybe this is actually a useful feature, but if so, where is
it documented and why does the Elisp manual not refer to that place,
or, better, document it itself?

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

OK, I figured out the anwer to my problem myself in (widget)Basic Types:

`:help-echo'
     Specifies how to display a message whenever you move to the
     widget with either `widget-forward' or `widget-backward' or move
     the mouse over it (using the standard `help-echo' mechanism).
     The argument is either a string to display or a function of one
     argument, the widget, which should return a string to display.

Why not provide that same information in (elisp)Type Keywords?

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

   `:help-echo'
	Specifies how to display a message whenever you move to the
	widget with either `widget-forward' or `widget-backward' or move
	the mouse over it (using the standard `help-echo' mechanism).
	The argument is either a string to display or a function of one
	argument, the widget, which should return a string to display.

This strictly speaking means that the fact that forms which evaluate
to strings do not work, is actually _not_ a bug after all.  But such
help-echo's _are_ going to be shown on mouse-over regardless.  So why
not make them admissible values for widget help-echo's anyway and make
<tab> and S-<tab> show them too by putting in those two eval's ?

Sincerely,

Luc.

Re: help-echo in Custom

[Luc Teirlinck]

>From my earlier message:

   So why not make them admissible values for widget help-echo's
   anyway and make <tab> and S-<tab> show them too by putting in those
   two eval's ?

Well better:

(defun widget-echo-help (pos)
  "Display help-echo text for widget at POS."
  (let* ((widget (widget-at pos))
	 (help-echo (and widget (widget-get widget :help-echo))))
    (if (functionp help-echo)
	(setq help-echo (funcall help-echo widget)))
    (if help-echo (message "%s" (eval help-echo)))))


Sincerely,

Luc.

Re: help-echo in Custom

[Per Abrahamsen]

Since I'm CC'ed:  

I believe :help-echo in widget.el existed before the help-echo text
property.  When Emacs got the property, someone made sure widget.el
set it with the value given.  Which works fine for the simple case of
a string, where the two API's are identical.

The correct solution would probably be for the code to carefully
translate the argument to :help-echo into the format expected by
help-echo, probably by creating a helper function on the fly.

Re: help-echo in Custom

[Luc Teirlinck]

Per Abrahamsen wrote:

   The correct solution would probably be for the code to carefully
   translate the argument to :help-echo into the format expected by
   help-echo, probably by creating a helper function on the fly.

Actually, that appears to be exactly what is done.  What confused me
was that the Elisp manual suggests that the rules for correct
arguments to :help-echo are exactly the same as for 'help-echo values.
I have no problem with them actually being different, as long as that
would be clearly mentioned in the Elisp manual.  The usual arguments
to 'help-echo make indeed no sense in the case of widgets.

The only change I suggest (apart from the change in the Elisp manual)
is to allow expressions that evaluate to strings in :help-echo, as
they are for `help-echo values.  This is easy to do by making the
minor change in `widget-echo-help' I suggested.  Otherwise, authors
who only check their code using mouse-over are going to believe such
arguments work anyway, whereas with the present version of
`widget-echo-help', they do not work with <tab>.

Sincerely,

Luc.

Re: help-echo in Custom

[Richard Stallman]

    Actually, that appears to be exactly what is done.  What confused me
    was that the Elisp manual suggests that the rules for correct
    arguments to :help-echo are exactly the same as for 'help-echo values.

Can someone please write changes to make the manual correct?
Don't worry about making the English perfect--as long as I understand
what this does, I can clean up the English when I install the change.

Re: help-echo in Custom

[Luc Teirlinck]

Richard Stallman wrote:

   Can someone please write changes to make the manual correct?
   Don't worry about making the English perfect--as long as I understand
   what this does, I can clean up the English when I install the change.

Once I know whether you agree with my proposed change to
`widget-echo-help' (and hence whether expressions that evaluate to
strings are going to be allowed in :help-echo, as they are in
'help-echo), I could send suggested changes to the Elisp manual.

Sincerely,

Luc.