Add 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?

[rswinkle]

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?

Good catch. Hmm. I mean we could do something like that:

        if (NK_INBOX(i->mouse.pos.x, i->mouse.pos.y, rect.x, rect.y, rect.w, rect.h)) {
            *timer += ctx->delta_time_seconds;
            return *timer >= delay || !ctx->delta_time_seconds;

But I feel like not implementing delta_time_seconds should be considered a bug in the backend and Nuklear shouldn't start making making allowances for something like that. This isn't something that is toggled on or off with a user configuration macro, this is always used. If the backend doesn't correctly update delta_time_seconds scrollbar hiding doesn't work either and there's no workaround for that even if we wanted one. Better to just fix it in the broken backends (or at least document that it's broken/unfinished).

[rswinkle]

@RobLoach

So I added some doxygen comments. Not sure how I feel about them. I waffled on whether to stick with a simple description or match the fancier style in src/nuklear.h. I feel like the latter is kind of overkill, especially on the ones I didn't bother doing it for. Also if we really go down this road of having doxygen docs for every single function (whether it's in on the declaration or definition)... well how many functions are there in nuklear, multiplied by 3-15 lines each?

[RobLoach]

It would increase the size, yes. If we keep the doxygen docs to the definitions instead of the declarations, it would still allow the header to be quickly scanned, and intellisense to pick up the doxygen hints.

To save duplciate docs, doxygen has some special commands to inherit docs and such. Soemthing we could consider if it becomes a problem down the line.

In the meantime, I'd be good with this change.

[RobLoach]

Anything else you'd like on before we merge it? Seems pretty solid to me.

[rswinkle]

Nah. Merge away. The only thing left on my TODO list for tooltips is keeping them from going off the edge of the window and that's a problem/fix for other popups too. I'll get to it eventually. Rob

…

On Fri, May 22, 2026, 5:23 AM Rob Loach ***@***.***> wrote: *RobLoach* left a comment (Immediate-Mode-UI/Nuklear#943) <#943 (comment)> Anything else you'd like on before we merge it? Seems pretty solid to me. — Reply to this email directly, view it on GitHub <#943 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEMQ47BSQ6Z2JPGA65HSN344BBCXAVCNFSM6AAAAACYAJKA4SVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKMJYGYYDAMBUGY> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[RobLoach]

Sounds good with me. Thanks muchly. Nice work.