Improve Tooltips to provide more information #37478

New Issue

Jonathan Williamson · 2013-11-15T19:44:16+01:00

2013-11-15 19:44:16 +01:00

The current tooltips in Blender are limited to a single line and often do not provide enough information for the people that need them (new users and/or those that aren't familiar with the tool/option). The tooltips can be dramatically improved with a few things:

Allow multiple line descriptions
Allow formatting for breaking it into sections, such as Name, Description, Instructions
Allow URLs for documentation links

For example, the tooltip for the Knife mesh tool could be:

Cut new topology into mesh
Use by clicking on vertices, edges, and faces to insert new cut lines. Allows multiple cut lines via modal options.
*View Documentation //

The current tooltips in Blender are limited to a single line and often do not provide enough information for the people that need them (new users and/or those that aren't familiar with the tool/option). The tooltips can be dramatically improved with a few things: - Allow multiple line descriptions - Allow formatting for breaking it into sections, such as **Name, Description, Instructions** - Allow URLs for documentation links For example, the tooltip for the **Knife** mesh tool could be: ***Cut new topology into mesh*** *Use by clicking on vertices, edges, and faces to insert new cut lines. Allows multiple cut lines via modal options.* *[View Documentation ](http:*wiki.blender.org/index.php/Doc:2.6/Manual/Modeling/Meshes/Editing/Subdividing/Knife_Subdivide) //

Jonathan Williamson commented

2013-11-15 19:44:16 +01:00

Changed status to: 'Open'

Jonathan Williamson commented

2013-11-15 19:44:16 +01:00

Added subscribers: @JonathanWilliamson, @brecht

Brecht Van Lommel commented

2013-11-15 19:56:32 +01:00

URLs in tooltips, can that work? Tooltips are generally supposed to get out of your way as soon as you move the mouse, so it may be that you still have to right click to open the link, unless there is a clever trick to avoid this.

Somewhat technical comments:

Multiline tooltips is something I'd really like to see implemented (and might do myself if no one picks this up). Mostly involves adding some (multi-lingual?) word wrapping function and handling line breaks in tooltips.
Formatting could be useful, but not sure how far we want to take that. There is already the name of the property or tool which can be the title. Then the description and instructions could just be the same string, with line breaks added between the description and instructions.

URLs in tooltips, can that work? Tooltips are generally supposed to get out of your way as soon as you move the mouse, so it may be that you still have to right click to open the link, unless there is a clever trick to avoid this. Somewhat technical comments: * Multiline tooltips is something I'd really like to see implemented (and might do myself if no one picks this up). Mostly involves adding some (multi-lingual?) word wrapping function and handling line breaks in tooltips. * Formatting could be useful, but not sure how far we want to take that. There is already the name of the property or tool which can be the title. Then the description and instructions could just be the same string, with line breaks added between the description and instructions.

Jonathan Williamson commented

2013-11-15 20:05:40 +01:00

@brecht, for formatting, if we can support line breaks then that should be enough. Mostly we just need to be able to separate sections by lines. Actual formatting, like bold, italics, etc, probably isn't necessary (although it would be nice).

As for URLs, I'm not sure. Having it in the Contextual menu is probably enough, but some softwares have very powerful tooltips that act as mini-manuals. These are very useful because you don't need to leave the software nearly so much for external documentation. From what I've seen, these generally work by having two tooltips, simple and advanced. Advanced is called by holding a modifier key I believe.

@brecht, for formatting, if we can support line breaks then that should be enough. Mostly we just need to be able to separate sections by lines. Actual formatting, like bold, italics, etc, probably isn't necessary (although it would be nice). As for URLs, I'm not sure. Having it in the Contextual menu is probably enough, but some softwares have very powerful tooltips that act as mini-manuals. These are very useful because you don't need to leave the software nearly so much for external documentation. From what I've seen, these generally work by having two tooltips, simple and advanced. Advanced is called by holding a modifier key I believe.

Rexford Nkansah commented

2013-11-18 10:59:00 +01:00

Added subscriber: @nkansahrexford

Rexford Nkansah commented

2013-11-18 10:59:00 +01:00

Instead of the URL in the tooltip, I think showing the shortcut key for the task if available will be better. Links in tooltips will lead to much work in targeting the right tasks to the right documentation.

Brecht Van Lommel commented

2013-11-18 11:05:57 +01:00

The tooltip generally shows shortcut keys already, though there are a few cases where Blender isn't smart enough yet to detect them.

We already have a system to link to documentation, see #37479 (Improve "Online Manual" Operator for Tools and Options), so that would use the same link, although that system needs some work.

The tooltip generally shows shortcut keys already, though there are a few cases where Blender isn't smart enough yet to detect them. We already have a system to link to documentation, see #37479 (Improve "Online Manual" Operator for Tools and Options), so that would use the same link, although that system needs some work.

Harley Acheson commented

2013-11-18 16:58:44 +01:00

Added subscriber: @Harley

Harley Acheson commented

2013-11-18 16:58:44 +01:00

Not quite on topic for adding "additional information", but the following is a mockup I did quite a while ago. It uses only the current information from the tooltips, but changes text alignment, color, ordering, and adds a horizontal rule to make them a bit easier to follow:

Tooltip Mockup

Not quite on topic for adding "additional information", but the following is a mockup I did quite a while ago. It uses only the current information from the tooltips, but changes text alignment, color, ordering, and adds a horizontal rule to make them a bit easier to follow: [Tooltip Mockup ](http://www.hacheson.com/files/Articles/Blender%20UI/Popup%20Hints/hints7.png)

Gabriel Gazzán commented

2013-11-19 01:52:50 +01:00

Added subscriber: @GabrielGazzan

CodeManX commented

2013-11-19 02:19:05 +01:00

Added subscriber: @CodeManX

CodeManX commented

2013-11-19 02:19:05 +01:00

Blender could use line wrapping in general (e.g. in panels).

There are open-source hyphenation dicts btw,
IIRC http://code.google.com/p/hyphenator/ uses

http://packages.debian.org/de/wheezy/all/hyphen-en-us

They exist for several languages and even variations:
http://packages.debian.org/en/wheezy/all/hyphen-de/filelist

NodeJS implementation:
https://github.com/bramstein/hypher

Blender could use line wrapping in general (e.g. in panels). There are open-source hyphenation dicts btw, IIRC http://code.google.com/p/hyphenator/ uses http://packages.debian.org/de/wheezy/all/hyphen-en-us They exist for several languages and even variations: http://packages.debian.org/en/wheezy/all/hyphen-de/filelist NodeJS implementation: https://github.com/bramstein/hypher

Shane Ambler commented

2013-11-19 03:26:17 +01:00

Added subscriber: @sambler

Shane Ambler commented

2013-11-19 03:26:17 +01:00

I would think of making this optional eg. Expanded Tooltips, similar to Python Tooltips

Ken Beyer commented

2013-11-19 03:27:41 +01:00

Added subscriber: @katsbits

Ken Beyer commented

2013-11-19 03:27:41 +01:00

If a lot of effort is going to be put into this, wouldn't it be better to address the issue within the broader context of Blenders overall documentation and how that can be used more effectively; its under-utilisation has been a big complaint for a long time after all.

Perhaps a better approach might be restrict tool tips to a single text string with a link that opens or accesses a "Help" panel when clicked, loading in/displaying an appropriate section of the online docs directly in Blender. Best of both worlds maybe?.

If a lot of effort is going to be put into this, wouldn't it be better to address the issue within the broader context of Blenders overall documentation and how that can be used more effectively; its under-utilisation has been a big complaint for a long time after all. Perhaps a better approach might be restrict tool tips to a single text string with a link that opens or accesses a "Help" panel when clicked, loading in/displaying an appropriate section of the online docs directly in Blender. Best of both worlds maybe?.

Brecht Van Lommel commented

2013-11-19 08:35:15 +01:00

@sambler: on the contrary, I would rather remove the Python Tooltips option and just make a well formatted tooltip that draws your attention to the right place.

@katsbits: there is another task about the Online Manual tool about linking to the documentation. But that's not mutually exclusive with this.

As a developer I have often encountered the problem that I just can't add enough information in a tooltip to explain something well, not because I wanted to write a tutorial but just because sometimes a single line is not enough to explain the bare basics.

@sambler: on the contrary, I would rather remove the Python Tooltips option and just make a well formatted tooltip that draws your attention to the right place. @katsbits: there is another task about the Online Manual tool about linking to the documentation. But that's not mutually exclusive with this. As a developer I have often encountered the problem that I just can't add enough information in a tooltip to explain something well, not because I wanted to write a tutorial but just because sometimes a single line is not enough to explain the bare basics.

Paweł Łyczkowski commented

2013-11-19 10:23:10 +01:00

Added subscriber: @PawelLyczkowski-1

Paweł Łyczkowski commented

2013-11-19 10:23:10 +01:00

"Make it optional" seems to be a common reaction to interface changes. Please be careful with complying with this request - this could make the Preferences bloated and/or the code jumbled I suppose.

@katsbits To propose something like that you have to define how this link would be clickable, since popups get out of the way (which is a good thing).

I personally like the extended tooltip idea with a mini tutorial, or more extensive explanation, that shows up when a modifier key is pressed.

Maybe this would also allow for clickable things inside the tooltip - you press and hold the modifier key over the tooltip, and as long as you hold it, this particular tooltip stays displayed, so you can click on things inside it.

"Make it optional" seems to be a common reaction to interface changes. Please be careful with complying with this request - this could make the Preferences bloated and/or the code jumbled I suppose. @katsbits To propose something like that you have to define how this link would be clickable, since popups get out of the way (which is a good thing). I personally like the extended tooltip idea with a mini tutorial, or more extensive explanation, that shows up when a modifier key is pressed. Maybe this would also allow for clickable things inside the tooltip - you press and hold the modifier key over the tooltip, and as long as you hold it, this particular tooltip stays displayed, so you can click on things inside it.

Brecht Van Lommel commented

2013-11-19 10:38:46 +01:00

Let's also remember that we do not even have an organized team to maintain the wiki manual documentation. If anyone wants to organize a group of people to do that it would be great, and then we can think about linking that up to the Blender UI and adding tutorials etc. But until that happens I think we are talking about adding something more basic here.

Ken Beyer commented

2013-11-19 13:08:20 +01:00

@brecht absolutely agree with your first comment regards there not being enough space... Given that it is limited, how much (typically mental) effort is expended trying to reduce or condense an entire subject into a single sentence when that effort may be better spent re-tasked towards the online documentation. That might then free up the tooltip engineers time and resources so they only have to worry about functionality, rather than that +content.

For your latter point, perhaps rethinking about tooltips might be the impetus needed to push the online docs to be updated and/or actively monitored. Again there's a duplication of effort when it comes to adding "Description" text for each tool so why not re-direct that at the online docs, even if that initially means the only info on a Wiki page might be the tooltip text itself.

Just a thought.

@PawelLyczkowski-1 The general problem with tooltips and the 'mini tutorials' approach is that information is only actually needed maybe once or twice before the user 'learns' it and subsequently finds it's constant appearance a nuisance (there not being a way to selectively disable tips). Are the short term gains for tooltip use better than encouraging long term use of the docs? What are the trade-offs?. Further to your point, there might not need to be a link as "F1" is typically used to bring up help docs in other application so perhaps there is a way that can be contextually linked to the documentation - mouse is over the "Layers" buttons for example, user presses "F1" which opens docs at the "Layers" component of the Wiki.

@brecht absolutely agree with your first comment regards there not being enough space... Given that *it is* limited, how much (typically mental) effort is expended trying to reduce or condense an entire subject into a single sentence when that effort may be better spent re-tasked towards the online documentation. *That might then free up the tooltip engineers time and resources so they only have to worry about functionality, rather than that +content*. For your latter point, perhaps rethinking about tooltips might be the impetus needed to push the online docs to be updated and/or actively monitored. Again there's a duplication of effort when it comes to adding "Description" text for each tool so why not re-direct that at the online docs, even if that initially means the only info on a Wiki page might be the tooltip text itself. Just a thought. @PawelLyczkowski-1 The general problem with tooltips and the 'mini tutorials' approach is that information is only actually needed maybe once or twice before the user 'learns' it and subsequently finds it's constant appearance a nuisance (there not being a way to *selectively disable* tips). Are the short term gains for tooltip use better than encouraging long term use of the docs? What are the trade-offs?. Further to your point, there might not need to be a link as "F1" is typically used to bring up help docs in other application so perhaps there is a way that can be contextually linked to the documentation - mouse is over the "Layers" buttons for example, user presses "F1" which opens docs at the "Layers" component of the Wiki.

Paweł Łyczkowski commented

2013-11-19 14:15:19 +01:00

@katsbits As was stated, the mini tutorials/extended tooltips are to be displayed only when hovering over a button with a modifier key pressed (alt/ctr), so they wouldn't become a nuisance, since they wouldn't be visible unless the user wants a specific extended tooltip to be visible.

so perhaps there is a way that can be contextually linked to the documentation - mouse is over the "Layers" buttons for example, user presses "F1" which opens docs at the "Layers" component of the Wiki

There already is a way - RMB on Layers and choose Online Manual from the menu. But since you did not know that, and many users also do not know about that, shows that it's not very discoverable.

Here is an idea to solve the discoverability problem on contextual documentation links - Add a small "Press X to see Online Manual entry" text in the tooltip, X being a hotkey like Alt-F1 (F1 being taken). Remove "Online Manual" RMB entry.

@katsbits As was stated, the mini tutorials/extended tooltips are to be displayed only when hovering over a button with a modifier key pressed (alt/ctr), so they wouldn't become a nuisance, since they wouldn't be visible unless the user wants a specific extended tooltip to be visible. >so perhaps there is a way that can be contextually linked to the documentation - mouse is over the "Layers" buttons for example, user presses "F1" which opens docs at the "Layers" component of the Wiki There already is a way - RMB on Layers and choose Online Manual from the menu. But since you did not know that, and many users also do not know about that, shows that it's not very discoverable. Here is an **idea to solve the discoverability problem on contextual documentation links** - Add a small "Press X to see Online Manual entry" text in the tooltip, X being a hotkey like Alt-F1 (F1 being taken). Remove "Online Manual" RMB entry.

Ken Beyer commented

2013-11-19 14:53:08 +01:00

@PawelLyczkowski-1 There needs to be an concerted effort to maximise on the time and energy developers are going to need to expend implement the proposal being suggested here, versus what the user needs, what they should be encouraged to do (for their long term benefit), and efficient use of currently available materials - if all that is wanted is to press "X" (or whatever contortional combinations one might argue the use of) to hold open or expand the tooltip what does that actually do for the user? If that action is to include a mini-tutorial, who determines that content and how many people are involved in that decision; why waste that precious time & energy writing (ostensibly duplicated materials) and approving content that will only be seen in Blender when that same effort can be better spent elsewhere (maintaining the Wiki which becomes the centralised info hub for tooltip info, help panel content, and online browsing - that's three separate functions pulling from the same source)?

Re: RMB; I did know that actually ;)

@PawelLyczkowski-1 There needs to be an concerted effort to maximise on the time and energy developers are going to need to expend implement the proposal being suggested here, versus what the user needs, what they should be encouraged to do (for *their* long term benefit), and efficient use of currently available materials - if all that is wanted is to press "X" (or whatever contortional combinations one might argue the use of) to hold open or expand the tooltip what does that actually do for the user? If that action is to include a mini-tutorial, who determines that content and how many people are involved in that decision; why waste that precious time & energy writing (ostensibly duplicated materials) and approving content that will only be seen in Blender when that same effort can be better spent elsewhere (maintaining the Wiki which becomes the centralised info hub for tooltip info, help panel content, and online browsing - that's three separate functions pulling from the same source)? Re: RMB; I did know that actually ;)

Paweł Łyczkowski commented

2013-11-19 15:06:14 +01:00

@katsbits Hence my second proposition, better discoverability of the contextual Online Manual links, rather than extended tooltips.

help panel content

What are you referring here to?

@katsbits Hence my second proposition, better discoverability of the contextual Online Manual links, rather than extended tooltips. >help panel content What are you referring here to?

Brecht Van Lommel commented

2013-11-19 15:10:00 +01:00

@PawelLyczkowski-1 showing a shortcut key in the tooltip for the online documentation link is a nice practical idea, I like it.

@katsbits: I don't really understand what you are proposing. Are you saying we shouldn't have tooltips in Blender at all, or that they should be automatically synced with documentation in the wiki?

@PawelLyczkowski-1 showing a shortcut key in the tooltip for the online documentation link is a nice practical idea, I like it. @katsbits: I don't really understand what you are proposing. Are you saying we shouldn't have tooltips in Blender at all, or that they should be automatically synced with documentation in the wiki?

Ken Beyer commented

2013-11-19 15:41:14 +01:00

@brecht The latter. They should be linked to, or better yet, pull in information from the wiki. This would be especially so if tooltips are to include more that a single sentence, if so then its going to be far better for the user to link them through to the wiki. For example; "Knife ("K"): Allows multiple cut lines via modal options (i)" - "(i)" being either a text or image link (but the text itself might also be linkable - or however it's done) to the appropriate section of the Wiki about the knife tool - there isn't really a need to be writing extended tooltip info when documentation already exists explaining features in-depth (and where they don't exist, defaulting to Blender having a link even to a blank page at least means the associated page in the Wiki can be managed independently by non-coders et-al).

@PawelLyczkowski-1 I mentioned above there is a need to unify the way Blender treats documentation with the suggestion that a 'help' panel or window (Editor) opening in Blender might be a useful consideration with respect to tooltips and what they contextually linked to when clicked, expanded or whatever adjective to want to use to indicate to the user "more information available here". And yes, I know that's why you made the additional point, hence my response to it rolleyes

@brecht The latter. They should be linked to, or better yet, pull in information from the wiki. This would be especially so if tooltips are to include more that a single sentence, if so then its going to be far better *for the user* to link them through to the wiki. For example; "**Knife ("K"): Allows multiple cut lines via modal options (i)**" - "(i)" being either a text or image link (but the text itself might also be linkable - *or however it's done*) to the appropriate section of the Wiki about the knife tool - there isn't really a need to be writing extended tooltip info when documentation already exists explaining features in-depth (and where they don't exist, defaulting to Blender having a link even to a blank page at least means the associated page in the Wiki can be managed independently by non-coders et-al). @PawelLyczkowski-1 I mentioned above there is a need to unify the way Blender treats documentation with the suggestion that a 'help' panel or window (Editor) opening in Blender might be a useful consideration with respect to tooltips and what they contextually linked to when clicked, expanded or whatever adjective to want to use to indicate to the user "more information available here". And yes, I know that's why you made the additional point, hence my response to it *rolleyes*

Brecht Van Lommel commented

2013-11-19 15:52:53 +01:00

@katsbits: Ok, but that is a huge job to organize and find volunteers for. So yes, if someone wants to organize that kind of thing that would be awesome. But, the proposed changes to add multiline tooltips, add some link to documentation, and give them a better layout will be helpful if that happens but also if it doesn't.

So, let's keep this design task about taking that smaller step forward.

@katsbits: Ok, but that is a huge job to organize and find volunteers for. So yes, if someone wants to organize that kind of thing that would be awesome. But, the proposed changes to add multiline tooltips, add some link to documentation, and give them a better layout will be helpful if that happens but also if it doesn't. So, let's keep this design task about taking that smaller step forward.

Ken Beyer commented

2013-11-19 16:23:17 +01:00

@brecht no problem.

Ken Beyer commented

2013-11-19 16:45:40 +01:00

Removed subscriber: @katsbits

Paweł Łyczkowski commented

2013-11-19 17:21:12 +01:00

@brecht @JonathanWilliamson Here you have a revised tooltip mockup with the shortcut key for online documentation:

@brecht @JonathanWilliamson Here you have a revised tooltip mockup with the shortcut key for online documentation: ![tooltip_02.png](https://archive.blender.org/developer/F28797/tooltip_02.png)

Jonathan Williamson commented

2013-11-19 17:54:21 +01:00

@PawelLyczkowski-1 that's looking quite nice. The Python portion is probably much too dark, it's difficult to read clearly. But otherwise I like that. My only qualm is that More doesn't clearly say to me to go to online documentation. Any way we can make that more clear?

@PawelLyczkowski-1 that's looking quite nice. The Python portion is probably much too dark, it's difficult to read clearly. But otherwise I like that. My only qualm is that **More** doesn't clearly say to me to *go to online documentation*. Any way we can make that more clear?

Paweł Łyczkowski commented

2013-11-19 18:03:53 +01:00

@JonathanWilliamson We can write "Press Alt-F1 to see Online Manual entry", or "More in Online Manual - Alt-F1". I put it in like that and got an impression that it is too verbose. Andrew posted a link some time ago I think with examples how such verbose statements are glanced over by the users. "Online Manual - Alt-F1" would seem to lead to the Online Manual in general. "More - Alt-F1" seemed both most concise and straightforward.

Paweł Łyczkowski commented

2013-11-19 18:09:53 +01:00

I guess "More in Online Manual - Alt-F1" would be ok.

gsr b3d commented

2013-11-19 20:27:02 +01:00

Added subscriber: @gsrb3d

gsr b3d commented

2013-11-19 20:27:02 +01:00

From the patch I did long ago (#7347) I know it provided better readability and also allowed for the "growth" you normally get with translated messages.

So watching this project in hope, better late than never.

From the patch I did long ago (#7347) I know it provided better readability and also allowed for the "growth" you normally get with translated messages. So watching this project in hope, better late than never.

Ken Beyer commented

2013-11-19 20:36:39 +01:00

Added subscriber: @katsbits

Ken Beyer commented

2013-11-19 20:41:26 +01:00

"Continue Reading..."
"Learn more about this tool..."
"More about this tool..."
"Read More..."
"Learn More..."
etc..

It's not explicitly necessary to inform users they're going online or they're necessarily going to be reading extended documentation because that's in inherent given by implication of the feature.

"*Continue Reading...*" "*Learn more about this tool...*" "*More about this tool...*" "*Read More...*" "*Learn More...*" etc.. It's not explicitly necessary to inform users they're going online or they're necessarily going to be reading extended documentation because *that's in inherent given **by implication of the feature***.

gsr b3d commented

2013-11-19 20:47:56 +01:00

No, it is not an implication, it could be a manual on the same computer.

Ken Beyer commented

2013-11-19 21:29:28 +01:00

@gsrb3d not sure I follow you.

The manual being online or offline is of no real consequence with respect to the tool tip and what it does for the user.. in fact your point over-complicates the matter because you're potentially over-explaining something which, in this particular instance, actually necessitates asking a question, "Alt+F1 for online or Alt+Shift+F1 for offline reading?", instead of making a statement, "Press/click/whatever here to read more" - to be pedantic, how far down the granularity does this go in terms of where the documentation comes from? A local copy is cached from online; do users need to be asked for that to happen? When does it happen? And so on and so forth. Keep it simple.

@gsrb3d not sure I follow you. The manual being online or offline is of no real consequence with respect to the tool tip and what it does for the user.. in fact your point over-complicates the matter because you're potentially over-explaining something which, in this particular instance, actually necessitates asking a question, "*Alt+F1 for online or Alt+Shift+F1 for offline reading?*", instead of making a statement, "*Press/click/whatever here to read more*" - to be pedantic, how far down the granularity does this go in terms of where the documentation comes from? A local copy is cached from online; do users need to be asked for that to happen? When does it happen? And so on and so forth. Keep it simple.

Zsolt Stefan commented

2013-11-20 17:55:15 +01:00

Added subscriber: @ZsoltStefan

Zsolt Stefan commented

2013-11-20 17:55:15 +01:00

Yes it is of consequence whether it is online. It is very annoying how some software open up documentation, sometimes in an in-program window, just to load a "page not found message" when I am not connected to the internet, without any sign beforehand that it is only available online. The relative unavailability of offline Blender documentation is bad enough, let us not reduce the info available inside the program even more. There are many use cases with no internet connection, whether on the go with a laptop, or at work with internet limitations, or in less connected parts of the world.

Ken Beyer commented

2013-11-20 18:35:30 +01:00

@ZsoltStefan there are a number of simple and effective ways to deal with loss of connection, caching for example, so your point is pretty trivial, if not moot. In fact.. by keeping tooltip info local to Blenders installation it means they cannot be updated/corrected until the next revision comes out (unless the user tinkers with Blender, something those new to the app are highly unlikely to do). But this is all neither here nor there anywho.

Brecht Van Lommel commented

2013-11-20 18:39:27 +01:00

If executing some tool in Blender is going to open a web browser there should be an indication of that, right now that's with an icon in the help menu and splash screen, the same could be used here.

Ken Beyer commented

2013-11-20 20:45:03 +01:00

@brecht not at all. Looking at (testing) the way other software handles this very issue; of the dozen or so varied applications I just inspected before posting (html editors, browsers, image editors and even a level design application), NONE, yes that was NONE, indicated they were going online or even about to open up another application or window (typically a browser, but more usually a separate 'help' app), they ALL just did it, and typically from a menu option simply saying "[application name] Manual" or "[application name] Help" (there isn't even a mouse-over or tooltip suggestion the user is about to go online or another window is about to open either). I'm sure there are some apps that do warn, ask or prompt users, they are a minority though.

@brecht not at all. Looking at (testing) the way other software handles this very issue; of the dozen or so varied applications I just inspected before posting (html editors, browsers, image editors and even a level design application), **NONE**, ***yes that was NONE***, indicated they were going online or even about to open up another application or window (typically a browser, but more usually a separate 'help' app), **they ALL just did it**, and typically from a menu option simply saying "[application name] Manual" or "[application name] Help" (there isn't even a mouse-over or tooltip suggestion the user is about to go online or another window is about to open either). I'm sure there are some apps that do warn, ask or prompt users, they are a minority though.

gsr b3d commented

2013-11-20 21:31:42 +01:00

"Many do it, so let's do it too" just reinforces "it", ignoring if "it" is good or bad.

Ken Beyer commented

2013-11-20 22:44:27 +01:00

@gsrb3d the use of other applications by way of comparison was for the benefit of those absent the requisite knowledge or experience attributable to real world UI design concepts and practice, and to illustrate the problem being discussed - this particular issue is a common problem ALL application developers have to deal with (not just Blender); the way users are informed about what things do follows a very particular convention with respect to catering to the their understand of software (plural), and how they expect certain functions to work. It's not some pithy "me too" feature request.

@gsrb3d the use of other applications by way of comparison was for the benefit of those absent the requisite knowledge or experience attributable to real world UI design concepts and practice, and to illustrate the problem being discussed - this particular issue is a common problem ALL application developers have to deal with (not just Blender); the way users are informed about what things do follows *a very particular convention* with respect to *catering to the their understand of software (plural)*, and how they ***expect*** certain functions to work. It's not some pithy "me too" feature request.

koil commented

2013-11-21 00:41:58 +01:00

Added subscriber: @koilz

koil commented

2013-11-21 00:41:58 +01:00

At the moment, people right click to go to the Online Manual.
Same as, Online Python Reference, Edit Source, Edit Translation.

A hotkey and a mention of a hotkey on the tooltip, for the Online Manual, i dont like this idear.
Online Manual, its two clicks.
Plus moving the mouse into a little box, then to hit Alt+F1, seems kinda awkward.
Also, I think it would just be better to note the hotkeys for the tools which have them, or they will be two hotkeys on some of the tool tips.

..

I like the proposed tool tip by plyczkowski, It looks very easy to read.
Though no online manual hotkey.
Also i like the python text blue.

At the moment, people right click to go to the Online Manual. Same as, Online Python Reference, Edit Source, Edit Translation. A hotkey and a mention of a hotkey on the tooltip, for the Online Manual, i dont like this idear. Online Manual, its two clicks. Plus moving the mouse into a little box, then to hit Alt+F1, seems kinda awkward. Also, I think it would just be better to note the hotkeys for the tools which have them, or they will be two hotkeys on some of the tool tips. .. I like the proposed tool tip by plyczkowski, It looks very easy to read. Though no online manual hotkey. Also i like the python text blue.

Dmitry Medvedev commented

2013-11-21 07:19:21 +01:00

Added subscriber: @d-medvedev

Dmitry Medvedev commented

2013-11-21 07:19:21 +01:00

I'm not sure, I'm on topic. Anyway, it's all about tooltips.
My idea is to add some tooltips for beginners to the startup window.

I think of using small animated gifs inside this tooltips area.

I'm not sure, I'm on topic. Anyway, it's all about tooltips. My idea is to add some tooltips for beginners to the startup window. ![original-copy.jpg](https://archive.blender.org/developer/F29793/original-copy.jpg) ![original-copy-2.jpg](https://archive.blender.org/developer/F29795/original-copy-2.jpg) I think of using small animated gifs inside this tooltips area.

Paweł Łyczkowski commented

2013-11-21 09:45:21 +01:00

Online Manual, its two clicks.

And this is one click - hover over button, press hotkey.

The problem with the current Online Manual link is that it's hard to discover. Tooltips, on the other hand, are not, which will also make the Online Manual link easy to discover.

@d-medvedev Nice.

>Online Manual, its two clicks. And this is one click - hover over button, press hotkey. The problem with the current Online Manual link is that it's hard to discover. Tooltips, on the other hand, are not, which will also make the Online Manual link easy to discover. @d-medvedev Nice.

CodeManX commented

2013-11-21 12:18:32 +01:00

I agree the "Online Manual" link is hard to discover, since blender teaches you that RMB is not used (in many areas) for a context menu. There should be a hint in the tooltip, but if you actually press that keycombo, it should call the "Online Manual" operator. So really just a hint in the tooltip, and as short as possible (if it was F1, just that, as everyone should know what F1 stands for).

In the context menu, the "Online Manual" entry should show its hotkey too. And I recommend to make it F1, 'cause this is a standard.

I'm not a fan of a modal tooltip, which stays visible for a while and user can click it. It would allow for the following however: The description would be a link to that operator's reference, the first line of the py tooltip info a link to the bpy.type in API docs, the second line to a (to be created) API page about data access paths to this particular type (bpy.data).

I agree the "Online Manual" link is hard to discover, since blender teaches you that RMB is not used (in many areas) for a context menu. There should be a hint in the tooltip, but if you actually press that keycombo, it should call the "Online Manual" operator. So really just a hint in the tooltip, and as short as possible (if it was F1, just that, as everyone should know what F1 stands for). In the context menu, the "Online Manual" entry should show its hotkey too. And I recommend to make it F1, 'cause this is a standard. I'm not a fan of a modal tooltip, which stays visible for a while and user can click it. It would allow for the following however: The description would be a link to that operator's reference, the first line of the py tooltip info a link to the bpy.type in API docs, the second line to a (to be created) API page about data access paths to this particular type (bpy.data).

Brecht Van Lommel commented

2013-11-21 14:47:09 +01:00

@d-medvedev that's out of scope for this design task, better to make a proposal in the wiki.

Andrew Price commented

2013-11-24 13:44:57 +01:00

Added subscriber: @AndrewPrice

Andrew Price commented

2013-11-24 13:44:57 +01:00

The mockup by @PawelLyczkowski-1 is the best I've seen so far.

On a sidenote, I'd add that as a rule the tooltip shouldn't block the button or function.

This is what Microsoft recommends :
"//Avoid covering the object the user is about to view or interact with. Always place the tip on the side of the object, even if that requires separation between the pointer and the tip. Some separation isn't a problem as long as the relationship between the object and its tip is clear.
For collections of items, avoid covering the next object that the user is likely to view or interact with. For horizontally arranged items, avoid placing tips to the right; for vertically arranged items, avoid placing tips below.//"

The last point is particularly important since a large amount of Blender's functions lie in the vertical properties panel.
What do you guys think about the tooltip appearing adjacent to the cursor in the 3d viewport? So for example, in plyczkowski's mockup the box would appear above the cursor in the 3d view area.

The mockup by @PawelLyczkowski-1 is the best I've seen so far. On a sidenote, I'd add that as a rule the tooltip shouldn't block the button or function. This is what [Microsoft recommends ](http://msdn.microsoft.com/en-us/library/windows/desktop/aa511331.aspx): "//**Avoid covering the object the user is about to view or interact with**. Always place the tip on the side of the object, even if that requires separation between the pointer and the tip. Some separation isn't a problem as long as the relationship between the object and its tip is clear. **For collections of items, avoid covering the next object that the user is likely to view or interact with.** For horizontally arranged items, avoid placing tips to the right; for vertically arranged items, avoid placing tips below.//" The last point is particularly important since a large amount of Blender's functions lie in the vertical properties panel. What do you guys think about the tooltip appearing adjacent to the cursor in the 3d viewport? So for example, in plyczkowski's mockup the box would appear above the cursor in the 3d view area.

Ken Beyer commented

2013-11-24 15:20:31 +01:00

With respect to that last point from MS; perhaps the tooltip might then be better placed displayed in the 3DView to one side (left/right, up/down) of whatever panel the mouse is over (but perpendicular to the the mouse itself).. That would avoid coverage issues whilst still keeping the tips display localised (and visually contextualised). Or similarly perhaps use a fixed location on screen (suggest not mouse cursor as that means the tip changes position relative to where the user last clicked the mouse), top-right of the 3DView for example, that way the the user 'learns' to look in that location for the tips regardless as to what they're moused over (this does however mean covering a section of the 3DView which might get annoying when working - perhaps make it's location optional?).

With respect to that last point from MS; perhaps the tooltip might then be better placed displayed in the 3DView to one side (left/right, up/down) of whatever panel the mouse is over (but perpendicular to the the mouse itself).. That would avoid coverage issues whilst still keeping the tips display localised (and visually contextualised). Or similarly perhaps use a fixed location on screen (suggest *not* mouse cursor as that means the tip changes position relative to where the user last clicked the mouse), top-right of the 3DView for example, that way the the user 'learns' to look in that location for the tips regardless as to what they're moused over (this does however mean covering a section of the 3DView which might get annoying when working - perhaps make it's location optional?).

Brecht Van Lommel commented

2013-11-24 15:30:51 +01:00

Displaying the tooltip above the button when possible seems like a reasonable solution to me, and when there is not enough space above it can be displayed below or to the left depending if it's a horizontal or vertical layout.

I rather not add any logic here to take into account 3D views, sometimes it's near the button, sometimes it's far away, sometimes there is no 3D view. It makes the tooltip location quite unpredictable.

Displaying the tooltip above the button when possible seems like a reasonable solution to me, and when there is not enough space above it can be displayed below or to the left depending if it's a horizontal or vertical layout. I rather not add any logic here to take into account 3D views, sometimes it's near the button, sometimes it's far away, sometimes there is no 3D view. It makes the tooltip location quite unpredictable.

Jonathan Williamson commented

2013-11-24 16:12:19 +01:00

@AndrewPrice great points from MS on placement. I run into that problem fairly often with tooltips being in the way.

Gabriel Gazzán commented

2013-11-24 22:56:59 +01:00

Can't a plus sign (or similar) be shown in the tooltip box for users wanting more advanced tips (like Python tooltips) to click on it?

Thomas Dinges commented

2013-11-24 23:02:22 +01:00

Added subscriber: @ThomasDinges

Thomas Dinges commented

2013-11-24 23:02:22 +01:00

+1 for the mockup by @PawelLyczkowski-1
This is a reasonable and good looking direction I think.

+1 for the mockup by @PawelLyczkowski-1 This is a reasonable and good looking direction I think.

Jonathan Williamson commented

2013-11-24 23:47:13 +01:00

@GabrielGazzan it could, but that would require the tooltip to stay up while moving the mouse away. This can quickly become very annoying and there's no good way (that I'm aware of) to determine if the tooltip should be hidden immediately or stay up.

@ThomasDinges, good by me.

@brecht, any qualms with going for @PawelLyczkowski-1's proposal? Aside from better formatting and tooltip location relative to the mouse, I believe we just need to add hotkey support for going to the Online Manual while mouse is over operator.

@GabrielGazzan it could, but that would require the tooltip to stay up while moving the mouse away. This can quickly become very annoying and there's no good way (that I'm aware of) to determine if the tooltip should be hidden immediately or stay up. @ThomasDinges, good by me. @brecht, any qualms with going for @PawelLyczkowski-1's proposal? Aside from better formatting and tooltip location relative to the mouse, I believe we just need to add hotkey support for going to the **Online Manual** while mouse is over operator.

Brecht Van Lommel commented

2013-11-25 00:35:22 +01:00

@JonathanWilliamson, I'm fine with that proposal, it looks great to me. One technical problem is that we do not currently bundle a bold font with Blender. There may be other places we can use it too, so could be worth adding.

Jonathan Williamson commented

2013-11-25 00:37:28 +01:00

@brecht I think it would be worth adding. There is a bold version of DejaVu Sans: http://dejavu-fonts.org/wiki/PDF_samples

Gabriel Gazzán commented

2013-11-25 00:52:48 +01:00

@JonathanWilliamson: yes, I know, it should stay up only while moving the mouse in the direction of the tooltip, and (after having moved it over the tooltip) when the mouse goes out of the tooltip bounds.

Besides the technical possibilities of actually implementing such hiding conditions (which goes far from my understanding), I think that if done right it should not necessarily be annoying to users.

@JonathanWilliamson: yes, I know, it should stay up only while moving the mouse in the direction of the tooltip, and (after having moved it over the tooltip) when the mouse goes out of the tooltip bounds. Besides the technical possibilities of actually implementing such hiding conditions (which goes far from my understanding), I think that if done right it should not necessarily be annoying to users.

Shane Ambler commented

2013-11-25 07:26:17 +01:00

@AndrewPrice I remember back before tooltips became little yellow squares next to the cursor, Apple's balloon help used a speech bubble that was placed away from the object with the little triangular piece bridging the gap to the item. That gave an unobscured view of the item with a clear indication of what it belonged to.

Paweł Łyczkowski commented

2013-11-25 09:12:34 +01:00

@brecht @JonathanWilliamson The font used in the tooltip title in DejaVu Condensed Bold. It was in the font packed with Blender.

Sebastian Brachi commented

2013-11-26 05:09:20 +01:00

Added subscriber: @Brachi

Jorge_G commented

2013-11-28 15:19:02 +01:00

(Migrated from localhost:3001)

Added subscriber: @Jorge_G

Jorge_G commented

2013-11-28 15:19:02 +01:00

(Migrated from localhost:3001)

@d-medvedev tooltips for beginners to the startup window. Really good

[@d-medvedev ](URL) tooltips for beginners to the startup window. Really good

Adam Dominec commented

2013-11-28 21:12:07 +01:00

Added subscriber: @emu-3

Adam Dominec commented

2013-11-28 21:12:07 +01:00

So, if the right-click menu is hard to discover, shouldn't the Python path be better there? That way, it could be copy/pastable as well.

Another idea: the tooltip could expand if displayed for a few seconds. A one-line summary is useful when looking for a specific tool, in which case a long description (maybe?) slows down the user. If the user is willing to read a whole paragraph they would probably not mind waiting a moment before it shows. There could then be a small timer animation to suggest waiting.

For a similar reason, I agree with @AndrewPrice's suggestion about placement. If possible, tooltips should display besides the panel they relate to.

edit: And icon-only menus should have a tooltip displayed immediately, like this site's formatting tools do.

So, if the right-click menu is hard to discover, shouldn't the Python path be better there? That way, it could be copy/pastable as well. Another idea: the tooltip could expand if displayed for a few seconds. A one-line summary is useful when looking for a specific tool, in which case a long description (maybe?) slows down the user. If the user is willing to read a whole paragraph they would probably not mind waiting a moment before it shows. There could then be a small timer animation to suggest waiting. For a similar reason, I agree with @AndrewPrice's suggestion about placement. If possible, tooltips should display besides the panel they relate to. edit: And icon-only menus should have a tooltip displayed immediately, like this site's formatting tools do.

Jorge_G commented

2013-11-29 14:12:27 +01:00

(Migrated from localhost:3001)

the mockup for tooltips from @PawelLyczkowski-1 look good. But colors to much dark

Jonathan Williamson commented

2013-11-29 18:17:00 +01:00

@Jorge_G, for mockups like this always try and ignore colors. Those are dependent on the theme and are unlikely to be the same (unless mockup is presented in default theme).

Sean Olson commented

2014-01-06 15:21:59 +01:00

Added subscriber: @liquidape

Sean Olson commented

2014-01-06 15:21:59 +01:00

I've seen other software show brief tooltips on mouseover, and extended "tutorialized" tooltips when pressing a modifier while mousing over the option. Links could also be nested in the extended tooltip as when a tutorialized tooltip is up your focus is on how the tool works and not on the project. It works well and keeps the annoyance of seeing pages of text down when you don't need it. Downside is discoverability is also down. Perhaps nesting option in right click menu in addition would be a solution.

Tobias Johansson commented

2014-01-20 20:48:07 +01:00

Added subscriber: @TobiasJohansson

Tobias Johansson commented

2014-01-20 20:48:07 +01:00

Have someone started with this one? If not, I would like to contribute. I think I will have a first version ready for code review at the end of the week.

Thomas Dinges commented

2014-01-20 20:53:50 +01:00

@TobiasJohansson: As far as I know, no one started with this yet, so feel free to try it. :)

Jonathan Williamson commented

2014-01-20 20:55:48 +01:00

@TobiasJohansson, go for it. No one has started on it that I'm aware of either.

Tene commented

2014-02-14 11:58:17 +01:00

(Migrated from localhost:3001)

Added subscriber: @Tene

Tene commented

2014-02-14 11:58:17 +01:00

(Migrated from localhost:3001)

I think reference to online manual is ok, but what if a user doesn't have internet connection atm? Maybe it'd be good to go GIMP way and give the users an option to download the docs (in preferred language, if possible) to their HDD and have a link from the tooltips to this documents? It works fine with GIMP, so maybe here it will be good as well?

michael knubben commented

2014-02-22 12:35:19 +01:00

Added subscriber: @michaelknubben

Bastien Montagne commented

2014-05-20 16:24:37 +02:00

Added subscriber: @mont29

Antonis Ryakiotakis commented

2014-06-19 15:55:50 +02:00

Added subscribers: @JulianEisel, @ideasman42, @Psy-Fi

Antonis Ryakiotakis commented

2014-06-19 15:55:50 +02:00

We have discussed a bit with @ideasman42 on irc today on this task. @JulianEisel also has implemented the proposal here. While it would be nice to have a bold font in blender we are worried it will eat too much memory. Better we could use a bigger or shadowed font for the important information.

Julian Eisel commented

2014-06-20 01:20:05 +02:00

Here is the revision and the patch @Psy-Fi was talking about: D611

I'm not using a bold font in there because of the given reasons. I still have a branch with the bold fonts in case we decide to use it nevertheless.

Thanks!

Here is the revision and the patch @Psy-Fi was talking about: [D611](https://archive.blender.org/developer/D611) I'm not using a bold font in there because of the given reasons. I still have a branch with the bold fonts in case we decide to use it nevertheless. Thanks!

Julian Eisel commented

2014-06-22 21:10:32 +02:00

Added subscribers: @billrey, @pablovazquez

Julian Eisel commented

2014-06-22 21:10:32 +02:00

On IRC we decided to use a monospaced font for the python text. Problem is, there are mostly developers, who of course prefer the mono font over the standard one.
So I would like to get some opinions from the users here. Standard or Mono?
(for more screenshots with the standard font, look at D611)

Feedback would be welcome, especially from the official UI-designers (@AndrewPrice, @billrey and @venomgfx. I already talked with Plyczkowski)

Thanks a lot!

On IRC we decided to use a monospaced font for the python text. Problem is, there are mostly developers, who of course prefer the mono font over the standard one. So I would like to get some opinions from the users here. Standard or Mono? ![tootlips_python_mono_compare.png](https://archive.blender.org/developer/F95289/tootlips_python_mono_compare.png) ![tooltips_mono.png](https://archive.blender.org/developer/F95293/tooltips_mono.png) (for more screenshots with the standard font, look at [D611](https://archive.blender.org/developer/D611)) Feedback would be welcome, especially from the official UI-designers (@AndrewPrice, @billrey and @venomgfx. I already talked with Plyczkowski) Thanks a lot!

Paweł Łyczkowski commented

2014-06-22 21:24:38 +02:00

Things to consider here: Standard is more pleasing aesthetically, but the tight spacing around the dot makes python paths hard to read. The monospace one makes the paths more readable, but the spacing around the dot is extreme in the other direction there (much spacing), to the point where empty space can be mistaken for a real space by a user who is unfamiliar with monospace.

I suggested a compromise, with spaces somewhere between these two fonts, but it appears it's not an option, so if I have to choose between the two, I favor usability and choose monospace.

Things to consider here: Standard is more pleasing aesthetically, but the tight spacing around the dot makes python paths hard to read. The monospace one makes the paths more readable, but the spacing around the dot is extreme in the other direction there (much spacing), to the point where empty space can be mistaken for a real space by a user who is unfamiliar with monospace. I suggested a compromise, with spaces somewhere between these two fonts, but it appears it's not an option, so if I have to choose between the two, I favor usability and choose monospace.

Julian Eisel self-assigned this 2014-06-22 22:40:38 +02:00

Pablo Vazquez commented

2014-06-23 22:10:10 +02:00

Hi @JulianEisel,

+1 for monospaced fonts whenever we have to display code, be it on the tooltips or anywhere else in the UI.

Thanks for your work!

Hi @JulianEisel, +1 for monospaced fonts whenever we have to display code, be it on the tooltips or anywhere else in the UI. Thanks for your work!

Campbell Barton commented

2014-06-24 11:12:22 +02:00

Committed this 16baa8c273

But left out the change to place relative to the mouse cursor since it overlaps the button sometimes (depending on zoom-level).

Read over some of the comments here but didn't see a good rationale for this change, it was suggested and nobody disagreed... but why is this an improvement?

Committed this 16baa8c273 But left out the change to place relative to the mouse cursor since it overlaps the button sometimes (depending on zoom-level). Read over some of the comments here but didn't see a good rationale for this change, it was suggested and nobody disagreed... but why is this an improvement?

Campbell Barton commented

2014-06-24 11:50:20 +02:00

My impression is that it would be fine to align the tip with the cursor on the X axis only, hows that sound?

Pablo Vazquez commented

2014-06-24 11:58:27 +02:00

+1

The position for the tooltips should be predictable, muscle memory will lead our eyes to read where the tooltip is supposed to appear, making it faster. Instead of making us look for it/guess it's position first and then read.

For cases when the tooltip is too wide because the text doesn't fit, it should be X aligned left/right.

+1 The position for the tooltips should be predictable, muscle memory will lead our eyes to read where the tooltip is supposed to appear, making it faster. Instead of making us look for it/guess it's position first and then read. For cases when the tooltip is too wide because the text doesn't fit, it should be X aligned left/right.

Julian Eisel commented

2014-06-26 22:52:32 +02:00

Using the cursors x-position sounds good to me! I agree with the points from @venomgfx. We've talked a bit more about the behaviour he proposed above, so let me quickly recap this:

align tooltips under the button but use the mouse to determine the horizontal position
if we're close to the window border, offset the tooltip to not go out of frame
as a result of this, it may happen that the mouse overlaps the tooltip, so we'll move the tooltip to the other side of the mouse if this is the case

+1 for this proposal

Using the cursors x-position sounds good to me! I agree with the points from @venomgfx. We've talked a bit more about the behaviour he proposed above, so let me quickly recap this: - align tooltips under the button but use the mouse to determine the horizontal position - if we're close to the window border, offset the tooltip to not go out of frame - as a result of this, it may happen that the mouse overlaps the tooltip, so we'll move the tooltip to the other side of the mouse if this is the case +1 for this proposal

Campbell Barton commented

2014-06-27 15:10:29 +02:00

Changed status from 'Open' to: 'Resolved'

Campbell Barton closed this issue

2014-06-27 15:10:29 +02:00

Campbell Barton commented

2014-06-27 15:10:29 +02:00

Committed x-axis alignment b9522e557a

Committed x-axis alignment b9522e557a

Julian Eisel commented

2014-06-28 16:33:25 +02:00

Changed status from 'Resolved' to: 'Open'

Julian Eisel reopened this issue

2014-06-28 16:33:25 +02:00

Julian Eisel commented

2014-06-28 16:33:25 +02:00

Reopened 'cause updated design and position are just a part of this.

In this task was also decided to include:

Multiline descriptions
Updated "Open Manual" behaviour with hint in tooltips

Reopened 'cause updated design and position are just a part of this. In this task was also decided to include: - Multiline descriptions - Updated "Open Manual" behaviour with hint in tooltips

Campbell Barton commented

2014-06-28 18:36:12 +02:00

In general I like the ability to have multi-line tips, however I think it would be good to have some official guidelines for what tooltips can include.

Enforcing a single line meant that tooltips had to be brief, if we have multiple lines theres nothing stopping entire paragraphs being included in tooltips.

I've used applications that do this, and it can be good in a few cases, but I'd rather keep these being tips, and not attempt to put comprehensive documentation here.
(Instead, we should make use of our link-to-manual feature).

Of course our manual is currently not that great, even so I would rather improve it, and not just include a lot of text in our tips.

Extra text which I think would be inappropriate (in most cases).

Examples of situations you might use the tool
Hints on troubleshooting
Listing corner cases that might not work (anything with very involved details at least).
Code snippets.

This list are more examples, exactly what is/isn't OK is open for discussion, Just to say I think it should stay limited to basic info for most cases.

If we add this, it means our tooltips are basically a manual, and we need to maintain documentation there.

So I think allowing longer tips is OK, but we should keep the scope limited, and provide some guidelines.

Its hard to know if this really ends up being an issue in practice or not. Perhaps developers natural dislike for writing docs ensures the feature isn't misused :)

In general I like the ability to have multi-line tips, however I think it would be good to have some official guidelines for what tooltips can include. Enforcing a single line meant that tooltips had to be brief, if we have multiple lines theres nothing stopping entire paragraphs being included in tooltips. I've used applications that do this, and it _can_ be good in a few cases, but I'd rather keep these being tips, and not attempt to put comprehensive documentation here. (Instead, we should make use of our link-to-manual feature). Of course our manual is currently not that great, even so I would rather improve it, and not just include a lot of text in our tips. Extra text which I think would be inappropriate *(in most cases)*. - Examples of situations you might use the tool - Hints on troubleshooting - Listing corner cases that might not work (anything with very involved details at least). - Code snippets. This list are more examples, exactly what is/isn't OK is open for discussion, Just to say I think it should stay limited to basic info for most cases. If we add this, it means our tooltips are basically a manual, and we need to maintain documentation there. So I think allowing longer tips is OK, but we should keep the scope limited, and provide some guidelines. Its hard to know if this really ends up being an issue in practice or not. Perhaps developers natural dislike for writing docs ensures the feature isn't misused :)

Thomas Dinges commented

2014-06-28 18:38:53 +02:00

I agree, this is a thing that we need to be careful about. Some guidelines will be great.

Campbell Barton commented

2014-06-28 18:46:55 +02:00

We have a habit of not following own guidelines :S, I'd be temped to do compile-time hard limit for tips - Blender fails to compile if its reached!

We can re-evaluate the limit if needed.

We have a habit of not following own guidelines :S, I'd be temped to do compile-time hard limit for tips - Blender fails to compile if its reached! We can re-evaluate the limit if needed.

Julian Eisel commented

2014-06-29 03:10:31 +02:00

I do also agree! My intend wasn't to make it possible to write novels in the descriptions, it was to make it possible to write useful descriptions, which often means that two or three sentences are needed.

To the guidelines: I just created a wiki page with some initial guidelines (UI Tooltip Guidelines). Everything there can still be discussed and changed.

@ideasman42, a hard limit sounds good to me

I do also agree! My intend wasn't to make it possible to write novels in the descriptions, it was to make it possible to write useful descriptions, which often means that two or three sentences are needed. To the guidelines: I just created a wiki page with some initial guidelines (**[UI Tooltip Guidelines](http://wiki.blender.org/index.php/Dev:Doc/Projects/UI/Tooltip_Guidelines)**). Everything there can still be discussed and changed. @ideasman42, a hard limit sounds good to me

Sean Olson commented

2014-06-29 19:44:53 +02:00

Hey All, I wanted to chime in here since I actually wrote the initial request and had carter2422 post it.
First off, I'd like to congratulate Severin on the fantastic job done so far. The tooltips are much clearer to read, and having them at the mouse is really quite nice and has the added benifit of working with the upcoming pie-menus as well.

What I would like to elaborate on is the reason for the initial request. That is the fact that sometimes to really expand upon a subject, more than 3 lines is necessary. If we come up with a way to really put to use the linking to wiki, that would be fine, but it is still much slower than seeing an "expanded" tooltip. Here is how I see it idealy in my minds eye.

Floating Tooltip with limits suggested in your UI Tooltip Guidelines . This should give a 'quick view' of the functionality of the given button. It can act as a reminder of what the functionality of the button is if you have used it before, but are struggling with remembering what it is 6 months later.
Expanded Tooltip. Pressing a modifier (alt) and mousing over a button would show an "expanded tooltip" This would be a much more robust tooltip, with much larger limits. Perhaps limited to 3 or 4 paragraphs. This is for people who have never used the tool, and need instruction on it's use.
Wiki - As a last resort, I think it proper to link to the wiki. This can already be achieved with the right click menu, but it might be possible to do our same modifier + click to open the wiki page.

TLDR Recap: Mouseover=short tooltip, alt+mouseover=expanded tooltip, alt+click button = link to wiki

I've used a very similar system in other software and it works marvelously. It's fast, you have accurate information at your fingertips, and you can learn the tool from within the tool. No need to 'RTFM' as is often used in the linux world.

Again, thanks for your hard work! I just feel we can take this a few steps further to make it REALLY shine.

Hey All, I wanted to chime in here since I actually wrote the initial request and had carter2422 post it. First off, I'd like to congratulate Severin on the fantastic job done so far. The tooltips are much clearer to read, and having them at the mouse is really quite nice and has the added benifit of working with the upcoming pie-menus as well. What I would like to elaborate on is the reason for the initial request. That is the fact that sometimes to really expand upon a subject, more than 3 lines is necessary. If we come up with a way to really put to use the linking to wiki, that would be fine, but it is still much slower than seeing an "expanded" tooltip. Here is how I see it idealy in my minds eye. 1. Floating Tooltip with limits suggested in your [UI Tooltip Guidelines ](http://wiki.blender.org/index.php/Dev:Doc/Projects/UI/Tooltip_Guidelines). This should give a 'quick view' of the functionality of the given button. It can act as a reminder of what the functionality of the button is if you have used it before, but are struggling with remembering what it is 6 months later. 2. Expanded Tooltip. Pressing a modifier (alt) and mousing over a button would show an "expanded tooltip" This would be a much more robust tooltip, with much larger limits. Perhaps limited to 3 or 4 paragraphs. This is for people who have never used the tool, and need instruction on it's use. 3. Wiki - As a last resort, I think it proper to link to the wiki. This can already be achieved with the right click menu, but it might be possible to do our same modifier + click to open the wiki page. TLDR Recap: Mouseover=short tooltip, alt+mouseover=expanded tooltip, alt+click button = link to wiki I've used a very similar system in other software and it works marvelously. It's fast, you have accurate information at your fingertips, and you can learn the tool from within the tool. No need to 'RTFM' as is often used in the linux world. Again, thanks for your hard work! I just feel we can take this a few steps further to make it REALLY shine.

Paweł Łyczkowski commented

2014-06-29 20:15:22 +02:00

Pressing a modifier (alt)

Make it Ctrl, since ZBrush already uses Ctrl.

>Pressing a modifier (alt) Make it Ctrl, since ZBrush already uses Ctrl.

Marco G commented

2014-06-29 22:31:56 +02:00

Added subscriber: @marcog

Marco G commented

2014-06-29 22:31:56 +02:00

What zbrush does is a really weak argument.

Anyways, just dropping to say that if Alt will be choosen, please be careful to not remove the Alt+mousewheel increments behaviour, is an amazing little feature. (hover mouse on a field or dropdown menu ->alt+mmb go up or down accordingly to mouse wheel, tons of clicks saved)

Thanks everybody.

What zbrush does is a really weak argument. Anyways, just dropping to say that if Alt will be choosen, please be careful to not remove the Alt+mousewheel increments behaviour, is an amazing little feature. (hover mouse on a field or dropdown menu ->alt+mmb go up or down accordingly to mouse wheel, tons of clicks saved) Thanks everybody.

Paweł Łyczkowski commented

2014-06-29 22:54:13 +02:00

What zbrush does is a really weak argument.

What other graphic programs do is very important, because, if possible, it would be optimal for new UI elements to fit in existing artists toolset.

>What zbrush does is a really weak argument. What other graphic programs do is very important, because, if possible, it would be optimal for new UI elements to fit in existing artists toolset.

Marco G commented

2014-06-29 23:47:48 +02:00

Blender has its own paradigms, there are plenty of other places where Blender could be closer to "standards", Ctrl for tooltips "because zbrush does this way" is really weak imo, but i don't care whether it will be one or another...the point i want to take care of is the second part of my comment, to not accidentally remove Alt+mmb scroll over input fields and dropdown menus.

Sean Olson commented

2014-06-30 01:55:37 +02:00

One argument for alt would be alt stands for alternate. So the use alt to see the alternate shortcut. In practice, I could care less which it is. Ctrl is fine by me.

Campbell Barton commented

2014-06-30 08:35:40 +02:00

Discussing which key-modifier to use at this point isn't especially important.

@liquidape - is suggesting having 2x tooltips (at least optionally 2x tooltips).

The main issue I see with this is it assumes we have the ability to maintain another, lager set of documentation, on-top of our existing docs (speaking generally - tips, wiki, python api, py-examples, translations... etc).
So far we manage OK in some of these areas, but still to struggle to maintain really comprehensive docs.
It also worries me that this would end up duplicating text from the manual. (if we have large paragraphs its inevitable there would be cross-over of content).

Users like to think about features, but really we could improve our existing tooltips considerably, without adding any new features, but we dont get many people interested to do this.

So for now, I'm strongly against adding a second layer of documentation.

Discussing which key-modifier to use at this point isn't especially important. @liquidape - is suggesting having 2x tooltips (at least optionally 2x tooltips). The main issue I see with this is it assumes we have the ability to maintain another, lager set of documentation, on-top of our existing docs *(speaking generally - tips, wiki, python api, py-examples, translations... etc).* So far we manage OK in some of these areas, but still to struggle to maintain really comprehensive docs. It also worries me that this would end up duplicating text from the manual. (if we have large paragraphs its inevitable there would be cross-over of content). Users like to think about features, but really we could improve our existing tooltips considerably, without adding any new features, but we dont get many people interested to do this. So for now, I'm strongly against adding a second layer of documentation.

Sean Olson commented

2014-06-30 21:43:55 +02:00

/agree on key discussion

As far as tooltips goes, I agree it would be more work, but for a significant boost in knowledge. I'm not a big fan of sending people elsewhere to learn a tool.

On work investment. I don't think it would take significantly more work than is already happening for new features. It would just be a requirement for patches that the documentation be written, which it already is in wiki form, and is just not enforced very well. The bigger problem that I foresee is when a feature changes, forcing an update of tooltip in blender as well as external one from wiki (Possible to link them through database?).

Features already in Blender would be the biggest work investment, getting longer tooltips up to speed. I would suggest that it be optional to have the extended tooltip and then they can be filled in over time. Additionally, there are a lot of features that simply do not need extended tooltips, a short concise explanation works fine, but others need more explanation, and it is these more complicated tools that could benefit from such a thing.

What we could do is place some sort of icon (like the common '...' icon ) on a short tooltip that has a longer tooltip associated with it.

I don't feel like, "it's a lot of work" is a good argument against doing something, especially when the work can be spread out over a long period of time, as this can be.

/agree on key discussion As far as tooltips goes, I agree it would be more work, but for a significant boost in knowledge. I'm not a big fan of sending people elsewhere to learn a tool. On work investment. I don't think it would take significantly more work than is already happening for new features. It would just be a requirement for patches that the documentation be written, which it already is in wiki form, and is just not enforced very well. The bigger problem that I foresee is when a feature changes, forcing an update of tooltip in blender as well as external one from wiki (Possible to link them through database?). Features already in Blender would be the biggest work investment, getting longer tooltips up to speed. I would suggest that it be optional to have the extended tooltip and then they can be filled in over time. Additionally, there are a lot of features that simply do not need extended tooltips, a short concise explanation works fine, but others need more explanation, and it is these more complicated tools that could benefit from such a thing. What we could do is place some sort of icon (like the common '...' icon ) on a short tooltip that has a longer tooltip associated with it. I don't feel like, "it's a lot of work" is a good argument against doing something, especially when the work can be spread out over a long period of time, as this can be.

Campbell Barton commented

2014-07-01 06:25:22 +02:00

@liquidape, The issue with "it's a lot of work" - is you are proposing work for other people to do (thats ok, its design discussion), even so - If you can find people who already write docs or do translations to accept the extra workload. I would be more interested.
At the moment I have the sense that such a project wouldn't end up getting very far but I may be wrong.

@liquidape, The issue with *"it's a lot of work"* - is you are proposing work for other people to do *(thats ok, its design discussion)*, even so - If you can find people who already write docs or do translations to accept the extra workload. I would be more interested. At the moment I have the sense that such a project wouldn't end up getting very far but I may be wrong.

Sv. Lockal commented

2014-07-03 07:01:58 +02:00

Added subscriber: @Lockal

Julian Eisel commented

2015-04-26 23:59:48 +02:00

The Alt+F1 shortcut proposed here has been committed (cf366c8b66), but we left out the tooltip hint as decided in D1031. So the only thing that's missing here now is support for multilined tooltips.

The Alt+F1 shortcut proposed here has been committed (cf366c8b668), but we left out the tooltip hint as decided in [D1031](https://archive.blender.org/developer/D1031). So the only thing that's missing here now is support for multilined tooltips.

Arnaud Couturier commented

2015-06-23 09:34:33 +02:00

Added subscriber: @piiichan

Campbell Barton commented

2015-08-29 14:05:59 +02:00

Note that while I still have reservations about moving large paragraphs of text into tooltips, here is a path to support multi-line tooltips. D1493

Note that while I still have reservations about moving large paragraphs of text into tooltips, here is a path to support multi-line tooltips. [D1493](https://archive.blender.org/developer/D1493)

Jonathan Williamson commented

2015-09-09 16:47:56 +02:00

That's nice @ideasman42! I don't really agree with the idea of having full paragraphs in tool-tips but supported multiple lines is really valuable.

A quick test doesn't look like it, but are we able to do multi-line tips for Python operators?

That's nice @ideasman42! I don't really agree with the idea of having full paragraphs in tool-tips but supported multiple lines is really valuable. A quick test doesn't look like it, but are we able to do multi-line tips for Python operators?

CodeManX commented

2015-09-09 17:13:04 +02:00

People complain about truncated bpy access paths in tooltips - like bpy.data.screen...use_manipulators, is that what you mean Jonathan? If no, please add it as a to-do. It should wrap if necessary, preferably at periods, but shouldn't matter much.

Jonathan Williamson commented

2015-09-09 18:19:23 +02:00

@CodeManX I was referring to the ability to explicitly start a new line with \n and whether it was supported when defining tool tips in Python for new operators.

@CodeManX I was referring to the ability to explicitly start a new line with `\n` and whether it was supported when defining tool tips in Python for new operators.

Campbell Barton commented

2015-09-09 19:03:21 +02:00

Yes, this works with Python too, though you don't need to have explicit newlines (the lines will wrap automatically).

eg:

  lang=python
  class SimpleOperator(bpy.types.Operator):
      """\
  This is a multi-line tooltip.

- Line one
- Line two"""

      bl_idname = "render.render_"
      bl_label = "Simple Object Operator"

      def execute(self, context):
          return {'FINISHED'}

Yes, this works with Python too, though you don't need to have explicit newlines (the lines will wrap automatically). eg: ``` lang=python class SimpleOperator(bpy.types.Operator): """\ This is a multi-line tooltip. ``` - Line one - Line two""" ``` bl_idname = "render.render_" bl_label = "Simple Object Operator" ``` ``` def execute(self, context): return {'FINISHED'}

Julian Eisel commented

2015-09-09 21:28:22 +02:00

@CodeManX, re truncated tooltips: Actually they aren't truncated because of saving space or so, we just can't get the full path (well, afaics - I tried it previously, see 30d72d682a and 55280eecad). Although maybe @ideasman42 has an idea on a fancy way to do this ;)

@CodeManX, re truncated tooltips: Actually they aren't truncated because of saving space or so, we just can't get the full path (well, afaics - I tried it previously, see 30d72d682a and 55280eecad). Although *maybe* @ideasman42 has an idea on a fancy way to do this ;)

Campbell Barton commented

2016-02-26 02:10:19 +01:00

@CodeManX & @Severin. There is some crossed wires here..

In the example codemanx gave, eg: bpy.data.screen["Default"] ... use_manipulators
The ... is added because we are missing internal functionality to create the data path.
So far we only added these callbacks for properties which need to be animated (since this is needed for inserting key-frames), and its Screen data doesn't need to be animated. So if we added this, it would only to so the Python tooltips display properly.

(for devs, we would need a RNA_def_struct_path_func that would give us the data path to the manipulator).

Truncating the Python tool-tip was done because there are times when operators Python expression can become unreasonably long, something like...

bpy.ops.mesh.primitive_circle_add(vertices=32, radius=1, fill_type='NOTHING', calc_uvs=False, view_align=False, enter_editmode=False, location=(0, 0, 0), rotation=(0, 0, 0), layers=(False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False))

And in these cases its rarely useful to include, the full text, even now with word wrapping I don't think its worth doing.
If you really want the whole command you're better off copy-pasting it (now available from the right-click menu b41bf7a171).

@CodeManX & @Severin. There is some crossed wires here.. In the example codemanx gave, eg: `bpy.data.screen["Default"] ... use_manipulators` The `...` is added because we are missing internal functionality to create the data path. So far we only added these callbacks for properties which need to be animated (since this is needed for inserting key-frames), and its *Screen* data doesn't need to be animated. So if we added this, it would only to so the Python tooltips display properly. *(for devs, we would need a `RNA_def_struct_path_func` that would give us the data path to the manipulator).* ---- Truncating the Python tool-tip was done because there are times when operators Python expression can become unreasonably long, something like... `bpy.ops.mesh.primitive_circle_add(vertices=32, radius=1, fill_type='NOTHING', calc_uvs=False, view_align=False, enter_editmode=False, location=(0, 0, 0), rotation=(0, 0, 0), layers=(False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False, False))` And in these cases its rarely useful to include, the full text, even now with word wrapping I don't think its worth doing. If you really want the whole command you're better off copy-pasting it (now available from the right-click menu b41bf7a171).

Jonathan Williamson commented

2016-03-08 16:42:14 +01:00

Unless there's anything else I suggest we close this out.

Julian Eisel commented

2016-03-08 17:24:42 +01:00

The only open todo I see is actually using multi-line tooltips now. Maybe we should discuss that in a separate task though.

Julian Eisel commented

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

Changed status from 'Open' to: 'Resolved'

Julian Eisel closed this issue

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

Julian Eisel commented

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

As part of the 2.8 UI workshop we made some decisions regarding tooltips: https://wiki.blender.org/index.php/Dev:2.8/UI/Workshop_Writeup#Tooltips
Most of the initial points of this tasks have been addressed, I think it's better to open new tasks for work on the newly proposed changes.

Closing as resolved. Thanks everyone!

As part of the 2.8 UI workshop we made some decisions regarding tooltips: https://wiki.blender.org/index.php/Dev:2.8/UI/Workshop_Writeup#Tooltips Most of the initial points of this tasks have been addressed, I think it's better to open new tasks for work on the newly proposed changes. Closing as resolved. Thanks everyone!

Sign in to join this conversation.