bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Drew Adams]

1. If you create a tooltip using, say, `x-show-tip', you can control the
font, text color and size, background color, etc.  Well, only some frame
parameters seem to have any effect, when passed in argument PARMS.  Just
which parameters can or cannot be used for PARMS should be documented.

2. The word `tooltip' is hardly mentioned in the doc.  Another doc fix
would be to document `tooltip-mode' properly in the Elisp manual, saying
which frame parameters you can use for `tooltip-frame-parameters', etc.

3. A related bug in `tooltip.el' is that the defcustom for
`tooltip-frame-parameters' has no :type.  Impossible for a user to
customize the value properly using Customize.  And no help about which
parameters can be used effectively (see #2, above).

4. `help-echo': No doc saying whether the string can be propertized, and
if so, which properties have any effect.  Although `x-show-tip' seems to
let you change the char size, color, background color, etc., and you can
use property `display' with `help-echo', apparently you cannot change
the face attributes of the `help-echo' string so that the appearance
changes.  This is quite a limitation, AFAICT.

All of this kind of thing should be documented: what you can and cannot
do - which parameters have an effect.  You can make `help-echo' show an
image instead of text, but you cannot simply change the text appearance
of a `help-echo' string?  How are users supposed to guess what is
possible?  Should be documented.



In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Eli Zaretskii]

> Date: Sat, 9 May 2015 16:27:05 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. If you create a tooltip using, say, `x-show-tip', you can control the
> font, text color and size, background color, etc.  Well, only some frame
> parameters seem to have any effect, when passed in argument PARMS.  Just
> which parameters can or cannot be used for PARMS should be documented.
> 
> 2. The word `tooltip' is hardly mentioned in the doc.  Another doc fix
> would be to document `tooltip-mode' properly in the Elisp manual, saying
> which frame parameters you can use for `tooltip-frame-parameters', etc.
> 
> 3. A related bug in `tooltip.el' is that the defcustom for
> `tooltip-frame-parameters' has no :type.  Impossible for a user to
> customize the value properly using Customize.  And no help about which
> parameters can be used effectively (see #2, above).
> 
> 4. `help-echo': No doc saying whether the string can be propertized, and
> if so, which properties have any effect.  Although `x-show-tip' seems to
> let you change the char size, color, background color, etc., and you can
> use property `display' with `help-echo', apparently you cannot change
> the face attributes of the `help-echo' string so that the appearance
> changes.  This is quite a limitation, AFAICT.
> 
> All of this kind of thing should be documented: what you can and cannot
> do - which parameters have an effect.  You can make `help-echo' show an
> image instead of text, but you cannot simply change the text appearance
> of a `help-echo' string?  How are users supposed to guess what is
> possible?  Should be documented.

You've omitted the facts you've found, for some reason.  That's a bad
idea: since no one really knows about these limitations, if you want
to raise the chances that this bug report will be acted upon, I urge
you to describe everything you tried and found not to work, so that
whoever takes upon this task will have the "bread-crumbs" to go by.

Otherwise, researching this issue from scratch is an unpleasant task
that is unlikely to find its volunteer.

Thanks.

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Drew Adams]

> You've omitted the facts you've found, for some reason.  That's a
> bad idea: since no one really knows about these limitations,

Someone who understands the code (C code, IIUC) can discover them.

> if you want to raise the chances that this bug report will be acted
> upon, I urge you to describe everything you tried and found not to
> work, so that whoever takes upon this task will have the "bread-crumbs"
> to go by.  Otherwise, researching this issue from scratch is an
> unpleasant task that is unlikely to find its volunteer.  Thanks.

I'll try.  But I don't have many such "facts".  Someone familiar with
the code would need to specify what is and is not possible for users
to do. I would hope that some of the limitations would be removed,
but any limitations should be documented.

I mention here some superficial tests I tried, in case it helps.

> > 1. If you create a tooltip using, say, `x-show-tip', you can
> > control the font, text color and size, background color, etc.
> > Well, only some frame parameters seem to have any effect, when
> > passed in argument PARMS.  Just which parameters can or cannot be
> > used for PARMS should be documented.

(defun foo (&optional height)
  (interactive (list (and current-prefix-arg
                          (prefix-numeric-value current-prefix-arg))))
  (unless height (setq height  1))
  (x-show-tip (propertize (string (char-after))
                          'face `(:foreground "red"
                                  :height ,(* 200 height)))))

Other face parameters (e.g. :font) do not seem to be reflected.

Likewise frame parameters (arg PARMS).  I also tried binding
`tooltip-frame-parameters' in such a function, but couldn't get that to
change the tooltip frame parameters either.

I also tried customizing face `tooltip', but that seems to have no
effect for `x-show-tip' or for `help-echo' tooltips for `tooltip-mode'.
Perhaps that is normal for MS Windows, but I don't see any doc about it.

> > 2. The word `tooltip' is hardly mentioned in the doc.  Another doc
> > fix would be to document `tooltip-mode' properly in the Elisp manual,
> > saying which frame parameters you can use for `tooltip-frame-parameters',
> > etc.

The only "facts" here are from searching the Emacs and Elisp manuals.
The Emacs manual has node `Tooltips', and there are other places where
"tooltip" is mentioned, but they essentially refer to node `Tooltips'.

The Elisp manual, which is really what I care about in this context,
has a few occurrences of "tooltip", which say that tooltip frames do
not count for this or that operation.  E.g. `Deleting Frames' says
"Unless FRAME is a tooltip...".

Node `Special Properties' mentions the word in passing, and sends you
to the Emacs manual, node `Tooltips'.  IOW, nothing technical about
tooltips here - just mention of what a tooltip is.  Other occurrences
of the term in the Elisp manual do not add anything in this regard.

> > 3. A related bug in `tooltip.el' is that the defcustom for
> > `tooltip-frame-parameters' has no :type.  Impossible for a user to
> > customize the value properly using Customize.  And no help about
> > which parameters can be used effectively (see #2, above).

That fact is expressed clearly enough, no?

> > 4. `help-echo': No doc saying whether the string can be
> > propertized, and if so, which properties have any effect.

That fact is expressed clearly enough, no?

> > Although `x-show-tip' seems to let you change the char size, color,
> > background color, etc., and you can use property `display' with
> > `help-echo',

Do you need an example of using `display' with `help-echo'?  I use
a sexp like this for `help-echo' in dired+.el, to show a thumbnail
preview of an image file on mouseover:

(propertize " " 'display (create-image file))

> > apparently you cannot change the face attributes of the `help-echo'
> > string so that the appearance changes.  This is quite a limitation,
> > AFAICT.

(defun foo ()
  (interactive)
  (add-text-properties
   (line-beginning-position) (+ 20 (line-beginning-position))
   `(mouse-face underline help-echo
                ,(propertize (word-at-point)
                             'face '(:foreground "red" :height 200)))))

The tooltip does not reflect what `propertize' should do here.

> > All of this kind of thing should be documented: what you can and
> > cannot do - which parameters have an effect.  You can make
> > `help-echo' show an image instead of text,

See above.

> > but you cannot simply change the text appearance of a `help-echo'
> > string?  How are users supposed to guess what is possible?
> > Should be documented.

HTH.  I don't really know what is allowed and what is not - or why.

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Eli Zaretskii]

> Date: Sat, 9 May 2015 16:27:05 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 3. A related bug in `tooltip.el' is that the defcustom for
> `tooltip-frame-parameters' has no :type.  Impossible for a user to
> customize the value properly using Customize.  And no help about which
> parameters can be used effectively (see #2, above).

I cannot reproduce this one: my tooltip.el has this:

  (defcustom tooltip-frame-parameters
    '((name . "tooltip")
      (internal-border-width . 2)
      (border-width . 1))
    "Frame parameters used for tooltips.

  If `left' or `top' parameters are included, they specify the absolute
  position to pop up the tooltip.

  Note that font and color parameters are ignored, and the attributes
  of the `tooltip' face are used instead."
    :type 'sexp <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
    :group 'tooltip)

According to Git, this line was there for the last 18 years.

> 4. `help-echo': No doc saying whether the string can be propertized, and
> if so, which properties have any effect.  Although `x-show-tip' seems to
> let you change the char size, color, background color, etc., and you can
> use property `display' with `help-echo', apparently you cannot change
> the face attributes of the `help-echo' string so that the appearance
> changes.  This is quite a limitation, AFAICT.

See above: the doc string of tooltip-frame-parameters says font and
color parameters are ignored.

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Eli Zaretskii]

> Date: Sun, 10 May 2015 07:36:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 20540@debbugs.gnu.org
> 
> > You've omitted the facts you've found, for some reason.  That's a
> > bad idea: since no one really knows about these limitations,
> 
> Someone who understands the code (C code, IIUC) can discover them.

Yes, but there are a lot of frame parameters; trying them one by one
is a lot of work.

Just by looking at the code, I see nothing special, except the obvious
omissions, such as scroll bars.

> > if you want to raise the chances that this bug report will be acted
> > upon, I urge you to describe everything you tried and found not to
> > work, so that whoever takes upon this task will have the "bread-crumbs"
> > to go by.  Otherwise, researching this issue from scratch is an
> > unpleasant task that is unlikely to find its volunteer.  Thanks.
> 
> I'll try.  But I don't have many such "facts".

Whatever you tried and saw failed will be helpful, TIA.

> I mention here some superficial tests I tried, in case it helps.

Thanks, it does help.

> > > Although `x-show-tip' seems to let you change the char size, color,
> > > background color, etc., and you can use property `display' with
> > > `help-echo',
> 
> Do you need an example of using `display' with `help-echo'?  I use
> a sexp like this for `help-echo' in dired+.el, to show a thumbnail
> preview of an image file on mouseover:
> 
> (propertize " " 'display (create-image file))

This is good enough, thanks.

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Drew Adams]

> > 3. ... the defcustom for `tooltip-frame-parameters' has no :type...
> 
> I cannot reproduce this one: my tooltip.el has this:

Sorry, my bad.

(Perhaps it was the gratuitous extra blank line after the first
doc-string line that threw me off and made me think the doc string
and definition ended there.  Dunno why such lines are added sometimes.
Those are (minor) bugs, AFAICT.  I don't mean this as an excuse for
my not reading the defcustom more carefully, but it might be the
reason that I was mistaken.)

And I see now that the doc string says that "font and color parameters
are ignored, and the attributes of the `tooltip' face are used instead."
It would be good to add info that to the doc in the manual, IMO.

So yes, there is a :type.  But the :type value should, I think, be
something more like this, not just `sexp':

:type '(alist :key-type   (symbol :tag "Parameter")
              :value-type (sexp :tag "Value"))

The :tag's are not required, but at least the type should be
:alist, I think.  Unless I'm missing something - can it ever be
something besides an alist?

Especially if only some frame parameters are allowed as keys (the
others are ignored, so why allow them for customization?), maybe a
more restrictive type than `symbol' should be used - e.g.
`restricted-sexp' with matching for the allowed symbols.

(You will perhaps argue that we didn't exclude including ignored
parameters before, so this would be an incompatible change.  I can't
really argue against that, except to say that it still might not be
bad to start now, raising an error when you try to add an "ignored"
parameter.)

> > 4. `help-echo': No doc saying whether the string can be
> > propertized, and if so, which properties have any effect.
> > Although `x-show-tip' seems to let you change the char size, color,
> > background color, etc., and you can use property `display' with
> > `help-echo', apparently you cannot change the face attributes of
> > the `help-echo' string so that the appearance
> > changes.  This is quite a limitation, AFAICT.
> 
> See above: the doc string of tooltip-frame-parameters says font and
> color parameters are ignored.

#4 is about `help-echo'.  Search the Elisp manual for `help-echo'.
See node `Special Properties', for instance.  Nowhere does it specify
such limitations, AFAICT.

And font and color parameters are not the only ones ignored.

And see the rest of the bug report, including the part about
`x-show-tip' - which face attributes and which frame parameters
have no effect?  And why is `help-echo' more limited wrt specifying
tooltip appearance than is `x-show-tip'?

There are several things said in the doc or doc strings here and
there about tooltips, but (a) the doc is incomplete and (b) it's not
clear what the relations between the various things are: `help-echo'
string properties, `x-show-tip' frame, `tooltip-frame-parameters'.

Apparently (from experimentation) `x-show-tip' does not bother with
`tooltip-frame-parameters'.

But you seem to be suggesting that a `help-echo' tooltip does, and
that `help-echo' string properties are overridden by
`tooltip-frame-parameters' frame-parameter limitations, and that
all of this should be obvious.  At least that's my guess, based on
your repeating, for #4 (`help-echo'), the info about the doc string
of `tooltip-frame-parameters'.

bug#20540: 25.0.50; Document tooltip woes, including `help-echo'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> 4. `help-echo': No doc saying whether the string can be propertized, and
> if so, which properties have any effect.  Although `x-show-tip' seems to
> let you change the char size, color, background color, etc., and you can
> use property `display' with `help-echo', apparently you cannot change
> the face attributes of the `help-echo' string so that the appearance
> changes.  This is quite a limitation, AFAICT.

This was apparently fixed in:

commit 4a112fd7a6f0dcbd1b99b811b324123f5699bdfb
Author:     Stefan Kangas <stefan@marxist.se>
AuthorDate: Mon Mar 8 03:29:42 2021 +0100

Some of the other documentation things discussed in this bug report
should then be OK (since it now works), and the tooltip frame parameter
stuff was (if I'm skimming this thread correctly) working as supposed.
So I'm closing this bug report.  If there's more to be done in this
area, please open a new bug report with those specifics.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no