Improve Tooltips to provide more information
Closed, ResolvedPublic

Description

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

There are a very large number of changes, so older changes are hidden. Show Older Changes

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 (katsbits) added a comment.EditedNov 20 2013, 8:45 PM

@Brecht Van Lommel (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.

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

@gsr b3d (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.

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.

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.

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.

@Dmitry Medvedev (d-medvedev) Nice.

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).

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

The mockup by @Paweł Łyczkowski (plyczkowski) 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.

Ken Beyer (katsbits) added a comment.EditedNov 24 2013, 3:20 PM

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?).

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.

@Andrew Price (andrewprice) great points from MS on placement. I run into that problem fairly often with tooltips being in the way.

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?

+1 for the mockup by @Paweł Łyczkowski (plyczkowski)
This is a reasonable and good looking direction I think.

@Gabriel Gazzán (gab3d) 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.

@Thomas Dinges (dingto), good by me.

@Brecht Van Lommel (brecht), any qualms with going for @Paweł Łyczkowski (plyczkowski)'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.

@Jonathan Williamson (carter2422), 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.

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

@Jonathan Williamson (carter2422): 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.

@Andrew Price (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.

@Brecht Van Lommel (brecht) @Jonathan Williamson (carter2422) The font used in the tooltip title in DejaVu Condensed Bold. It was in the font packed with Blender.

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

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 @Andrew Price (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.

the mockup for tooltips from @Paweł Łyczkowski (plyczkowski) look good. But colors to much dark

@jorge Guerrrero (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).

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.

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.

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

@Tobias Johansson (mutze), go for it. No one has started on it that I'm aware of either.

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?

We have discussed a bit with @Campbell Barton (campbellbarton) on irc today on this task. @Julian Eisel (Severin) 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 (Severin) edited this Maniphest Task.Jun 20 2014, 1:07 AM

Here is the revision and the patch @Antony Riakiotakis (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!

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 (@Andrew Price (andrewprice), @William Reynish (billrey) and @Pablo Vazquez (venomgfx). I already talked with Plyczkowski)

Thanks a lot!

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.

Hi @Julian Eisel (Severin),

+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!

Committed this rB16baa8c273e0c344dcf985205e43957591cf5ad6

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?

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

+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.

Using the cursors x-position sounds good to me! I agree with the points from @Pablo Vazquez (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

Julian Eisel (Severin) reopened this task as Open.Jun 28 2014, 4:33 PM

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
Julian Eisel (Severin) edited this Maniphest Task.Jun 28 2014, 4:33 PM

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 :)

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

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.

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.

@Campbell Barton (campbellbarton), a hard limit sounds good to me

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. 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.
  1. 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.
  1. 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.

Pressing a modifier (alt)

Make it Ctrl, since ZBrush already uses Ctrl.

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.

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.

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.

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.

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

@Sean Olson (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.

/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.

@Sean Olson (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.

The Alt+F1 shortcut proposed here has been committed (cf366c8b668), 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.

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

That's nice @Campbell Barton (campbellbarton)! 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?

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.

@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.

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

eg:

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'}

@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 rB30d72d682a8 and rB55280eecad). Although *maybe* @Campbell Barton (campbellbarton) has an idea on a fancy way to do this ;)

@codemanx & @Julian Eisel (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 rBb41bf7a1711f66c8f5b41d313315a644612ef165).

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

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 (Severin) closed this task as Resolved.Dec 20 2016, 9:15 PM

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!