[REQUEST] Document which values of menu_retv can be passed to mode_result

[SabrinaJewson]

Before opening a feature request

• I checked the next branch to see if the feature has already been implemented
• I searched existing reports to see if it is already requested.

What is the user problem or growth opportunity you want to see solved?

It's not made clear in the documentation what values of menu_retv can be legally passed to mode_result, or what menu_retv even is. I initially assumed that any MENU_* constant can be passed into it, but after reading the source code I'm unsure:

• As far as I can tell it's not possible for MENU_NEXT and MENU_PREVIOUS to be passed in there, since those events are only generated as a response to a keypress which doesn't trigger the rofi_view_maybe_update function. I haven't dived into the code for some of the other variants but I imagine it's true for some of them as well.
• Some of the MENU_* values seem to implicitly come with other bits set containing other state, but it's not clear which ones. This should probably be documented in mode.h.

So this feature request doubles up as a question and a request for documentation. If you answer the question I would also be happy to submit a PR to update the documentation.

How do you know that this problem exists today? Why is this important?

As far as I can tell this is not documented anywhere.

Who will benefit from it?

Plugin authors

Rofi version (rofi -v)

1.7.3

Configuration

N/A

Additional information

No response

[DaveDavenport]

I am completely lost what the request/question is.

But Ill try to answer, might be the wrong answer.

MenuReturn (that is passed to menu_retv) consists of 2 parts:

Higher bits are documented in mode.h these are the basic commands.

The lower bits (contained by MENU_LOWER_MASK) are used to pass extra parameters, this is used in QUICK_SWITCH and CUSTOM_COMMAND to indicate an index.

Example in script mode: https://github.com/davatorium/rofi/blob/next/source/modes/script.c#L292 here this allows you to send -kb-custom-* to the script.

Normally this is filtered out and passed as result (https://github.com/davatorium/rofi/blob/next/source/modes/help-keys.c#L71). See next reply for what that does.

[DaveDavenport]

The same goes for ModeMode.
If a number < MODE_EXIT is passed, its used to directly jump to a mode.
See here
The ENUM entries are specific commands.

This should be cleaned up, but would mean breaking plugins.

[DaveDavenport]

What is it you are trying to do in your plugin? that might help me answer the question better?

[DaveDavenport]

I guess this is the goal? https://github.com/SabrinaJewson/rofi-plugin-sys.rs

[DaveDavenport]

For binding the mode.h header file is the important bit. Most of the other header files are optional (if I remember correctly, its been a while I look at plugins.).
I think it would be the best plan to start with that one first.

Moving rofi (partially) over to rust is on my to-do, this would make a nice first start.

[SabrinaJewson]

Thank you for the response! My other question was whether it's possible for MENU_NEXT to be passed into mode_result. I just need to know whether I should be thinking about that case or not.

[SabrinaJewson]

I guess this is the goal? https://github.com/SabrinaJewson/rofi-plugin-sys.rs

That binding is actually complete now, I ported over all the header files. Since it's so raw I didn't need to know the exact semantics of the functions, just their C types. But now I'm working on a higher-level binding and it would be useful to know exactly which values can/can't be passed into that function so I can define a correct enumeration of all the possible values.

Moving rofi (partially) over to rust is on my to-do, this would make a nice first start.

That's nice to hear 😄

[DaveDavenport]

MENU_NEXT should normally not be passed to a plugin.
I am unsure about this, need to look to look at this again.:

As you noticed, this is a lot of legacy code where a lot of stuff got bolted on top of it, trying to force new features in.

[DaveDavenport]

I see how it is done, in mode.c line 93 it catches MENU_NEXT, MENU_PREV and MENU_QUICK_SWITCH before calling the Mode::mode_result .

So in theory it can be passed to it, but I seem to have avoided every mode needing to handle this separately .

[DaveDavenport]

this is a bit out of date, but was my 'plugin' template:
https://github.com/davatorium/rofi-plugin-template/blob/master/src/myplugin.c

[SabrinaJewson]

I see how it is done, in mode.c line 93 it catches MENU_NEXT, MENU_PREV and MENU_QUICK_SWITCH before calling the Mode::mode_result .

Oh thank you very much, I don't know how I didn't spot that earlier!

https://github.com/davatorium/rofi-plugin-template/blob/master/src/myplugin.c

Yes, I read through that and it was very helpful.

[DaveDavenport]

Might be important for binding, mode_token_match can be called from multiple threads at the same time.
They are never concurrent calls that have the same 'index' set.

[DaveDavenport]

I was trail running a discord: https://discord.gg/64ycuVPf might be useful if we need to have a discussion.

[SabrinaJewson]

By the way, I finished the library now: https://docs.rs/rofi-mode. I'm pretty pleased with it, it allows creating Rofi plugins from purely safe Rust :D

[DaveDavenport]

neat, I am gonna play with it when I get some time.