Tooltip Guidelines #50283

New Issue

Julian Eisel · 2016-12-20T21:34:42+01:00

Julian Eisel commented

2016-12-20 21:34:42 +01:00

As part of the 2.8 UI workshop, we agreed on having tooltip guidelines to ensure useful and high quality tooltips: https://wiki.blender.org/index.php/Dev:2.8/UI/Workshop_Writeup#Tooltips
An initial guideline page can be found here https://wiki.blender.org/index.php/Dev:Doc/Projects/UI/Tooltip_Guidelines. This task should be used to discuss and finalize it.

Once the page is finalized, we'll ask all contributors to follow it strictly.

# Tooltip Guidelines As part of the 2.8 UI workshop, we agreed on having tooltip guidelines to ensure useful and high quality tooltips: https://wiki.blender.org/index.php/Dev:2.8/UI/Workshop_Writeup#Tooltips An initial guideline page can be found here https://wiki.blender.org/index.php/Dev:Doc/Projects/UI/Tooltip_Guidelines. This task should be used to discuss and finalize it. Once the page is finalized, we'll ask all contributors to follow it strictly.

Julian Eisel commented

2016-12-20 21:34:42 +01:00

Changed status to: 'Open'

Julian Eisel commented

2016-12-20 21:34:42 +01:00

Added subscriber: @JulianEisel

Brendon Murphy commented

2017-01-01 05:51:47 +01:00

Added subscriber: @BrendonMurphy

Brendon Murphy commented

2017-01-01 05:51:47 +01:00

hi, great initiative, some small changes & comments:

General rules
What tooltips May contain
The name of the tool
A description of the tool

(Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements

If a button is disabled, the tooltip should always show useful information on why it is disabled and ideally how to change that.

Indeed, example of this will be in booltools addon release within a few days.
Tooltip Line 1: Please select 2 or more mesh objects
Tooltip Line 2: Boolean Operation to join the mesh (Union)

Additional useful info (Shortcuts, Python path, etc, that are Automatically generated)

The tool description:

The description of the tool should basically be short and to the point. But there are more rules to follow:

Do not use more than 2 lines or 3 only in the case of adding a hotkey that is not auto generated.
Use full sentences (periods and commas are allowed).
Examples of situations where you might use the tool are allowed.
Avoid using the described term to explained itself.

there should also be a character limit applied, some tool tips can get incredibly long

What tooltips should not contain

Code snippets
Anything with very involved details (e.g. troubleshooting, corner cases that might not work, etc.)

+1

These guidelines will also apply to addons.

I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way.

hi, great initiative, some small changes & comments: > General rules > What tooltips May contain > > The name of the tool > A description of the tool (Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements > If a button is disabled, the tooltip should always show useful information on why it is disabled and ideally how to change that. Indeed, example of this will be in booltools addon release within a few days. Tooltip Line 1: Please select 2 or more mesh objects Tooltip Line 2: Boolean Operation to join the mesh (Union) > Additional useful info (Shortcuts, Python path, etc, that are Automatically generated) > > The tool description: > > The description of the tool should basically be short and to the point. But there are more rules to follow: > > Do not use more than 2 lines or 3 only in the case of adding a hotkey that is not auto generated. > Use full sentences (periods and commas are allowed). > Examples of situations where you might use the tool are allowed. > Avoid using the described term to explained itself. > there should also be a character limit applied, some tool tips can get incredibly long > > > What tooltips should not contain > > Code snippets > Anything with very involved details (e.g. troubleshooting, corner cases that might not work, etc.) +1 These guidelines will also apply to addons. I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way.

Gaia Clary commented

2017-01-07 15:41:21 +01:00

Added subscriber: @GaiaClary

Gaia Clary commented

2017-01-07 15:41:21 +01:00

Would it be possible to have 2 tool tips for each item?

description = "contains information when the item is operable."
disablehint = "contains information when the item is disabled."

When disablehint is not defined, then description is used
And of course the naming is just a placeholder for something better :)

Would it be possible to have 2 tool tips for each item? description = "contains information when the item is operable." disablehint = "contains information when the item is disabled." When disablehint is not defined, then description is used And of course the naming is just a placeholder for something better :)

Julian Eisel commented

2017-02-12 19:46:01 +01:00

In #50283#410433, @BrendonMurphy wrote:
(Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements

Indeed, there isn't a need to show the tool name in most cases, a short, general description would be enough, followed by a more detailed description. Kind of like we do currently already. E.g.
Also, I realize "tool name" is the wrong term, we're actually talking about the name of the entity a button represents (can be an operator, property or a enum-property value).

I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way.

It's a bit tricky to solve that. What we could do is make tooltips follow the radial layout. Meaning for a button at the left, the tooltip would appear on its left side (if enough space is available), for a button at the top, the tooltip would appear above it, etc.

In #50283#411205, @GaiaClary wrote:
Would it be possible to have 2 tool tips for each item?

description = "contains information when the item is operable."
disablehint = "contains information when the item is disabled."

When disablehint is not defined, then description is used
And of course the naming is just a placeholder for something better :)

The info on why a button is disabled (and how to fix that?) should always be additional info, when showing it, the normal button description should still be visible.
Since 6f8060450, we can already return a string in RNA _editable callbacks containing info on why the button is disabled. Operators can also store such strings through CTX_wm_operator_poll_msg_set. These strings are then displayed in tooltips.
So these approaches allow context-sensitive usage and thus are a bit more dynamic than just storing a fixed description for an item for the case that it's disabled. I think that's the right direction to go, for Python we should do something similar.

> In #50283#410433, @BrendonMurphy wrote: > (Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements Indeed, there isn't a need to show the tool name in most cases, a short, general description would be enough, followed by a more detailed description. Kind of like we do currently already. E.g. ![tooltip.png](https://archive.blender.org/developer/F484175/tooltip.png) Also, I realize "tool name" is the wrong term, we're actually talking about the name of the entity a button represents (can be an operator, property or a enum-property value). > I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way. It's a bit tricky to solve that. What we could do is make tooltips follow the radial layout. Meaning for a button at the left, the tooltip would appear on its left side (if enough space is available), for a button at the top, the tooltip would appear above it, etc. > In #50283#411205, @GaiaClary wrote: > Would it be possible to have 2 tool tips for each item? > > description = "contains information when the item is operable." > disablehint = "contains information when the item is disabled." > > When disablehint is not defined, then description is used > And of course the naming is just a placeholder for something better :) The info on why a button is disabled (and how to fix that?) should always be *additional* info, when showing it, the normal button description should still be visible. Since 6f8060450, we can already return a string in RNA `_editable` callbacks containing info on why the button is disabled. Operators can also store such strings through `CTX_wm_operator_poll_msg_set`. These strings are then displayed in tooltips. So these approaches allow context-sensitive usage and thus are a bit more dynamic than just storing a fixed description for an item for the case that it's disabled. I think that's the right direction to go, for Python we should do something similar.

Duarte Farrajota Ramos commented

2017-02-13 06:30:25 +01:00

Added subscriber: @DuarteRamos

Reiner Prokein commented

2017-02-13 08:37:32 +01:00

Added subscriber: @tiles

Reiner Prokein commented

2017-02-13 08:37:32 +01:00

Icon only buttons would need the tool name too.

Aaron Carlisle commented

2017-04-13 19:34:42 +02:00

Added subscriber: @Blendify

Aaron Carlisle commented

2017-04-13 19:34:42 +02:00

For 2.8 I purpose that by default we disable developer information in tooltips. This will make the tooltips look simpler and also follows the proposal of "no code snippets" What will also help tooltips is the adjust the styling a little. For example, a while ago @PawelLyczkowski-1 made this mockup but it got lost:

For 2.8 I purpose that by default we disable developer information in tooltips. This will make the tooltips look simpler and also follows the proposal of "no code snippets" What will also help tooltips is the adjust the styling a little. For example, a while ago @PawelLyczkowski-1 made this mockup but it got lost: ![tooltip_02.png](https://archive.blender.org/developer/F28797/tooltip_02.png)

Aaron Carlisle commented

2017-04-13 20:18:23 +02:00

Added subscriber: @PawelLyczkowski-1

Mateus Arruda commented

2019-12-26 22:29:36 +01:00

Added subscriber: @Arruda23

Mateus Arruda commented

2019-12-26 22:29:36 +01:00

Hi guys. I'm trying to do an addon that will show an specific brush in an animated gif tooltip. This is what I have so far

Do you think this could be useful for the new users? I'm just doing for increase my knowledge in Python and Blender API, but you guys think it would be any helpful to have in the software?

Hi guys. I'm trying to do an addon that will show an specific brush in an animated gif tooltip. This is what I have so far ![ezgif.com-video-to-gif.gif](https://archive.blender.org/developer/F8245385/ezgif.com-video-to-gif.gif) Do you think this could be useful for the new users? I'm just doing for increase my knowledge in Python and Blender API, but you guys think it would be any helpful to have in the software?

William Reynish commented

2019-12-26 23:10:14 +01:00

Added subscriber: @WilliamReynish

William Reynish commented

2019-12-26 23:10:14 +01:00

@Arruda23: would it be useful? Yes. Some other apps do this kind of thing. Should we include this by default? Not sure.

There’s an aversion to adding too much data in the Blender binary, although I think it might be nice.

Related question is, how deep should that concept go? Just for brushes? All active tools? Any tooltip?

@Arruda23: would it be useful? Yes. Some other apps do this kind of thing. Should we include this by default? Not sure. There’s an aversion to adding too much data in the Blender binary, although I think it might be nice. Related question is, how deep should that concept go? Just for brushes? All active tools? Any tooltip?

Julien Kaspar commented

2019-12-27 13:32:25 +01:00

Added subscriber: @JulienKaspar

Julien Kaspar commented

2019-12-27 13:32:25 +01:00

@WilliamReynish

I was also thinking about this for a while and I definitely believe that adding images or even animated images would be very helpful for specific options that are hard to explain with text only.
Concepts like the "sculpt plane orientation" for example are not understood by most users since it's an aspect to a brush that is invisible to the user.
But I wouldn't add extra images to the vast majority of tooltips.

@WilliamReynish I was also thinking about this for a while and I definitely believe that adding images or even animated images would be very helpful for specific options that are hard to explain with text only. Concepts like the "sculpt plane orientation" for example are not understood by most users since it's an aspect to a brush that is invisible to the user. But I wouldn't add extra images to the vast majority of tooltips.

Konstantina Anagnostou commented

2019-12-28 13:06:58 +01:00

Added subscriber: @Constantina32

Mateus Arruda commented

2020-01-09 22:24:48 +01:00

Hello again. I've been developing the addon I just mentioned above and I finished. I had a lot of struggles with blender addon structure and native methods such as modal, execute, poll, etc. but that's because I'm noob at programming and I also learned a lot. Here is how it looks like now:

I want to say that I did this focusing on new users experience but it is not very useful since the new user would have to install the addon and activate it to use. But I want to leave this work as an idea if the developers want to implement it natively into the software, since I used third party libraries to do so (I think this made things even more complicated).

This is the project link if anyone wants to check it out.

Hello again. I've been developing the addon I just mentioned above and I finished. I had a lot of struggles with blender addon structure and native methods such as modal, execute, poll, etc. but that's because I'm noob at programming and I also learned a lot. Here is how it looks like now: ![tutorial.gif](https://archive.blender.org/developer/F8267867/tutorial.gif) ![tutorial2.gif](https://archive.blender.org/developer/F8267873/tutorial2.gif) I want to say that I did this focusing on new users experience but it is not very useful since the new user would have to install the addon and activate it to use. But I want to leave this work as an idea if the developers want to implement it natively into the software, since I used third party libraries to do so (I think this made things even more complicated). [This ](https://github.com/mati23/AnimatedPreview) is the project link if anyone wants to check it out.

Julian Eisel commented

2020-04-30 14:03:44 +02:00

Closed as duplicate of #76261

Julian Eisel closed this issue

2020-04-30 14:03:44 +02:00

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Tooltip Guidelines #50283

Tooltip Guidelines