Delayed tooltips

[rswinkle]

This is not quite a DRAFT/RFC but I definitely want feedback before it gets merged. I have no issues with the code or ideas in general, but I'm open to alternative names for functions and additional functions or different defaults. Or of course if we could all agree on a complete breaking redesign of the tooltip API that uses and exposes all the features we want with a nicer/simpler API with good defaults that would be nice too.

Here's my thought/dev process:

So adding an origin and offset to avoid the cursor covering up the text solved the most glaring issue, but tooltips still feel a little janky and unprofessional in Nuklear. This PR is an attempt to fix that.

The first thing I noticed when comparing ours to other software is that tooltips do not show up immediately. There is a delay of usually 0.3-0.5 seconds. Adding nk_is_mouse_hovering_delay_rect() solves this in a basic way.

Most applications have the same delay for all tooltips, which sounds like something that should be a default style value. Unfortunately there's no easy way to add that to the existing tooltip API. Fortunately I've always sort of wanted some convenience wrappers so I added two, and the delay only applies to one of those at a higher level than the existing tooltip API.

Lastly, I noticed that not only do other tooltips have a delay, they also do not show up from hovering alone. You have to hover motionless over the item for the time required. And once the tooltip appears, movement while still hovering does not make it disappear. This required adding additional input functions (again I can imagine users wanting all varieties under various circumstances:

NK_API nk_bool nk_input_is_mouse_hovering_rect(const struct nk_input*, struct nk_rect);
NK_API nk_bool nk_input_is_mouse_hovering_still_rect(const struct nk_input*, struct nk_rect);
NK_API nk_bool nk_input_is_mouse_hovering_delay_rect(const struct nk_context*, struct nk_rect, float*, float);
NK_API nk_bool nk_input_is_mouse_hovering_still_delay_rect(const struct nk_context*, struct nk_rect, float*, float);

I decided it is better to bake in the "once the delay is reached motion does not reset it" behavior. Again that could be handled with a bool argument or (less likely) another pair of functions.

At this point, the only behavior I notice in other tooltips that we don't have is that tooltips do not follow the mouse. Some, like Gnome, appear in the same place regardless of where you hover the mouse over the item to trigger it. Others, like Chrome (not counting hovering over tabs which are a special case), appear at a set offset to the mouse but then remain stationary as long as you are still hovering over the item. Between the two, I think the latter is probably a better goal, if we bother with either behavior. Honestly I don't think it's too terrible for the tooltip to follow the mouse since most users will continue to hold still to read it after they held still to trigger it.

Here is the current behavior, at least for the two examples I added to the Overview:

2026-04-20.17-49-50.mp4

[RobLoach]

I like the idea, but would you be willing to add some doc comments for the functions? We don't really have inline ones yet, but I think it would be a good opportunity to start adding some.

[rswinkle]

I like the idea, but would you be willing to add some doc comments for the functions? We don't really have inline ones yet, but I think it would be a good opportunity to start adding some.

Do we want comments on the declarations or the definitions? Looking at src/nuklear.h it looks like we have documentation for some functions declarations there, along with larger category/topic blocks and some structure comments, but I feel like it makes more sense to keep the function documentation with the definitions where it'll be easier to remember to update them if you're updating the function. Plus it just makes the lists of declarations so spread out and harder to see a related cluster at a glance.

[RobLoach]

Good question. What do you think makes the most sense? Above the declaration means it'd be available right at the top, but means you'd have to scroll far between the doc comments. Perhaps down below in the definition may make more sense?

[rswinkle]

Good question. What do you think makes the most sense? Above the declaration means it'd be available right at the top, but means you'd have to scroll far between the doc comments. Perhaps down below in the definition may make more sense?

I think it makes more sense to put it with the definitions, not just for the reasons I already listed. First, if someone is looking at the generated documentation it doesn't matter where it is in the source code the end result is the same on the website or whatever format is generated. Second, if they're actually bothering to look at the source to figure out how something works, they're going to want to look at the definition anyway, not just the declaration so then they'll have both in view.

The only argument against in my mind is the fact that we already have a few above the declarations but those could easily be moved if we feel the need for perfect consistency ... which would be inconsistent with the rest of Nuklear haha.

[rswinkle]

Here's a quick clip showing the newest addition where the tooltip disappears on click which is another thing most professional tooltips do which I agree makes sense as it doesn't make much sense to keep it hovering around getting in the way if you presumably know what you're doing since you've already clicked it.

2026-05-06.18-22-48.mp4

EDIT: A video that actually shows the cursor. I need to stop using Peek even though it's convenient. It never seems to capture the mouse no matter what I try.

[RobLoach]

Did some testing. When delta isn't supported by the renderer, the tooltip never shows up. Maybe we only use the delay if there is a delta?