What's the minwid in on_click ? What does it mean?

[bew]

I see in the on_click table there is a minwid optional field that is said to be (or should return?) an integer.

What does minwid mean?
At first, seeing this as the 2nd arg of the callback I thought it was Mouse In WinID (a weird way to say it's the clickedwinid) but since it's always 0 unless we pass the minwid field in on_click, and is not necessarily the winid I don't get what that means.

Renaming that to ctx or context would make much more sense don't you think?

Why an integer? Aren't we able to pass anything there?

[rebelot]

on_click callback signature wraps the signature required by functions that are called when clicking on the statusline. please see :h statusline for an example. the parameter minwid will be passed to the callback by vim, you can choose which value to assign to minwid using the appropriate field with the on_click table. That integer value is the only thing that is able to provide some context to the callback (i.e., if multiple components with the same callback are shown in the same window and the callback needs to act differently). See the implementation of the "full nerd" version of the Navic component in the cookbook for some tricks on how to encapsulate information within that integer.

[bew]

Reading :h statusline now make a little more sense, minwid is actually the minimum width N that you repurposed as a way to pass context..
I find it weird that you kept the name since it's really not user-friendly / doesn't mean anything in the context of heirline..

And looking more at the help and the cookbook, I don't understand why you needed to use that minwid to pass context, there are other ways to get the information or pass context...

For example to get the winid the help says we can simply use vim.fn.getscreenpos().winid.

For the navic example you mentioned, instead of doing:

            local pos = self.enc(d.scope.start.line, d.scope.start.character, self.winnr)
            -- ...
                    on_click = {
                        -- pass the encoded position through minwid
                        minwid = pos,
                        callback = function(_, minwid)
                            -- decode
                            local line, col, winnr = self.dec(minwid)
                            vim.api.nvim_win_set_cursor(vim.fn.win_getid(winnr), {line, col})
                        end,

Since you're making a dedicated on_click function for each element, you could use upvalues => use the variables you need directly (d.scope.start.line, ..) in the function, with a separate local var copying the self.winnr to get the correct one (or use getscreenpos as mentioned earlier).
Or to simplify a little, make a ctx table with values you need to pass:

            local pos_ctx = { d.scope.start.line, d.scope.start.character }
            -- ...
                    on_click = {
                        callback = function()
                            local winid = vim.fn.getscreenpos().winid
                            vim.api.nvim_win_set_cursor(winid, pos_ctx)
                        end,

=> no more need for minwid
(I'd even go as far as removing the arg from on_click callback, since it has no use in the context of heirline IMO, although it may not be a good time since you just release v1.0..)

Or am I missing something?

[rebelot]

Vim will call the function specified with the syntax %N@SomeFunc@label%X when clicking on label. The call will be made with the signature SomeFunc(minwid, nclicks, mbutton, mods). I have no control on how the call is made, and arbitrarily changing the signature because "it makes little sense to me", makes little sense to me. Also, SomeFunc must be a global function, this is the main caveat! If multiple lua closures are registered with the name SomeFunc, each one will overwrite the previous one, hence each closure should have a different name, hugely polluting the global namespace. Another possibility is to add each closure to a global table, and the callback function simply uses minwid to select the closure and then propagate the arguments, but also this approach has its drawbacks, as there is still a chance that the global table might grow indefinitely.

[rebelot]

I agree that vim.fn.getscreenpos().winid is a nice trick that makes a lot of the use cases for minwid obsolete, this was added to the docs after this issue

[bew]

Ah... Didn't see that coming ^^'

If multiple lua closures are registered with the name SomeFunc, each one will overwrite the previous one

Is this saying that in your navic example all callbacks functions actually overwrite each other and only the last one wins?
If that is the case, I think that example should be more explicit about that behavior.
(maybe by defining the function outside instead of making multiple ones that overrides each other? Or with a copment explaining that?)

I think I'd be on the side of 'polluting globals' in this case, avoiding weird (limited) tricks to pass context (and cleaning them up when possible).

I think the section talking about click callback should mention minwid as a last resort though.

[rebelot]

closures are not redefined unless the update field is set to true. Otherwise the first closure will be registered as the callback and subsequent evaluations of the component will just return its name. You are free to take a look at the implementation here. Creating the function externally and pass a "static" funcref is always possible but performance should not change.