UI Plugins

[Noordfrees]

Type of change
New feature

Issue(s) closed
Fixes #4801 (at least partially, but more features can be added by and by)
Closes #2117 since there's no reason why it couldn't be used in scenario scripting as well

How it works
Plugins are a new type of add-on that allow creating arbitrary UI components as children of existing components. These work both in the editor and in-game.

Possible regressions
N/A

Screenshots

Additional context
This is a pretty small-ish baseplate. It supports a handful of basic UI widgets and callback events. That's quite enough to write, for example, the attached sample add-on which exchanges two hardcoded terrain types with each other. editor_swap_terrains.wad.zip

It does not support more advanced window components, such as Dropdowns, ListSelects, Editboxes, and, well, most sorts of components actually. So far we have only Windows, Boxes, Buttons, and single-line Textareas.

Note that there are quite some pitfalls when scripting such a plugin. Both in the windowing system – the frontend is actually quite nice to use compared to C++, except for the callbacks, but layouting a complex window properly is a headache no matter what the frontend looks like. And the callbacks – since the Lua context may be deleted during the lifetime of a toolbar button, we can't reuse custom variables or functions, everything has to be a raw string. Read the attached add-on to see what I mean.

The attached add-on is meant to be enabled only in the editor. Comment out the first line to get it in-game as well, but beware – it will desync in replays/MP the moment you use it.

[frankystone]

Puuuhhh 😃 The example addon you gave looks a bit, hm, crazy? I understand the most but can you explain what this syntax means:

on_click = [=[
.....
		]=]

I mean the [ = [?

I will play around with this, but may take some time.

[Noordfrees]

That's just a string literal, exactly like [[text]]. A [[...]] literal can contain any text except its matching closing string delimiter, so if you want to nest multiple levels of string literals you can place any number of = chars between the brackets to have an unlimited number of string delimiters for arbitrary nesting.

-- All of the following are equivalent:
[[Hello World]]
[=[Hello World]=]
[==[Hello World]==]
-- And this is not:
[===[Hello World]==]  -- this is not the correct closing string delimiter, so everything (including this comment) is still part of the string!  --- here's to finally close it: ]===]  -- This comment is not part of the string.

Another way to handle the situation that does not require writing entire functions as strings would be to put each callback into a separate file and simplify the callbacks as just

	on_click = [[ include("addons/addon_name.wad/toolbar_callback.lua") ]],

[frankystone]

Thanks :-)

Another way to handle the situation that does not require writing entire functions as strings would be to put each callback into a separate file and simplify the callbacks as just

	on_click = [[ include("addons/addon_name.wad/toolbar_callback.lua") ]],

I can't get this to work, nothings happens if i try to make it like so. Here is my auto_mountains.wad (just adapted your addon and exchanged the main function): editor_auto_mountains.zip The contained file auto_height.lua does not work with your suggestion (don't be confused about the function get_all_map_fields(), this is not used). Probably i am doing something wrong…

I am also not able to create a window with a textbox and yes-no buttons 🥲 If i try that i get always an error

[string "           push_textdomain("yes_no.wad", true)..."]:34: ')' expected (to close '(' at line 2) near '}'

although i have tried to make it as simple as i can and check all parenthesis and commas i can't get rid of this error.
yes_no.zip

Another question about the value for orientation: In your example the value "vert" is used, but according to the documentation it should be "vertical"?

widelands/src/scripting/lua_ui.cc

Lines 382 to 383 in 13f3dd8

	* ``"orientation"``: **Mandatory**. The box's layouting direction:
	``"vertical"`` or ``"horizontal"``.

---

Instead of having each tool as a button in the main menu of the editor i think it would be better to have an extra dropdown for add-on tools. Ideally not shown, or disabled, if no add-on tools are installed.

If you click several times of an addon entry in the main menu, on each click a new window is created covering the previously opened window. This should be prevented.

[Noordfrees]

• Re Yes/No: You have a Lua syntax error, a { is missing after line 39. Then it works.
  
  Note that errors in stringified Lua code snippets always give their line number relative to the code snippet's start, so if the snippet starts at e.g. line 30 then an error in line 10 is actually near the source file line 40.
• Re "vert" : It is annoying to always spell out h-o-r-i-z-o-n-t-a-l and v-e-r-t-i-c-a-l, especially since any complex window has lots of boxes. So I added some shorthands for their Lua equivalents. Will add them to the documentation as well.
• Re dropdowns: Dropdowns (along with tables and listselects) are actually the hardest UI elements to handle in the Lua interface. I will definitely add those features, but that's for a separate branch to keep the PR reviewable.
• Re windows: I will also add Unique Windows. Again, in a separate branch for reviewability.
• Re AutoHeight: The following works for me:

    					on_click = [=[
    						include("addons/editor_auto_mountains.wad/auto_height.lua")
    						auto_mountains()
    					]=]

[frankystone]

• Re Yes/No: You have a Lua syntax error, a { is missing after line 39. Then it works.

Oh, stupid me :-) That's the reason why i always need some time.

How can i determine which button a user has clicked on? Or is this also for a later branch?

Note that errors in stringified Lua code snippets always give their line number relative to the code snippet's start, so if the snippet starts at e.g. line 30 then an error in line 10 is actually near the source file line 40.

Good to know, thanks.

• Re dropdowns: Dropdowns (along with tables and listselects) are actually the hardest UI elements to handle in the Lua interface. I will definitely add those features, but that's for a separate branch to keep the PR reviewable.

Maybe a misunderstanding: I don't meant to add dropdowns for add-on windows, i meant a dropdown for the editors main menu which contains all add-on ui-plugins. Similar to the Tools menu.

• Re AutoHeight: The following works for me:

    					on_click = [=[
    						include("addons/editor_auto_mountains.wad/auto_height.lua")
    						auto_mountains()
    					]=]

Ah, thanks again.

[Noordfrees]

How can i determine which button a user has clicked on? Or is this also for a later branch?

Each button has its own on_click callback code. If you want to use the multiple-files approach, you can use a different file for each button, or set a global variable before including the file (ACTION="yes"; include("filename.lua")), or use only exported functions (like in automountains – include("filename.lua"); callback_function_3()).

Re dropdowns: Dropdowns (along with tables and listselects) are actually the hardest UI elements to handle in the Lua interface. I will definitely add those features, but that's for a separate branch to keep the PR reviewable.

Maybe a misunderstanding: I don't meant to add dropdowns for add-on windows, i meant a dropdown for the editors main menu which contains all add-on ui-plugins. Similar to the Tools menu.

No that's the same case. Adding new entries to an existing dropdown is equally hard. Also, UI plugins have a lot of flexibility since they can edit arbitrary aspects of the GUI; I don't want to restrict the functionality to allow only a handful of dropdown entries and nothing else as plugin entry points.
So yes I will add such a dropdown when implementing scripting support for dropdowns and make it the recommended place for plugins' starting points, but right now that would be a lot of code… unless of course someone who wants to do the code review tells me it's fine, in which case I would add a lot more functionality here :)

[frankystone]

Will it be possible to have some sort of templates for ui-plugins? E.g. a yes_no template which contains a textbox and two buttons and one can do something like:

mv.toolbar:create_child({
	widget = "button",
	name   = "auto_mountains_plugin_toolbar_button",
	w      = styles.get_size("toolbar_button_size"),
	h      = styles.get_size("toolbar_button_size"),
	tooltip  = _("Set height of mountains automatically"),
	icon     = "images/wui/editor/tools/height.png",
	on_click = [[  template("yes_no", "_(This is the text for the textbox)", 
                                include("addons/editor_auto_mountains.wad/auto_height.lua")
  				auto_mountains() )  ]],
})

Something along that would make the handling much easier. And i think such templates can cover most of the use cases.

[Noordfrees]

Will it be possible to have some sort of templates for ui-plugins?

Hm… we have one such C++ UI element, the WLMessageBox – a simple modal window with a multiline textarea and an OK button and optionally a Cancel button. Would exposing this to Lua be sufficient for most such cases I think?

If we really need more complicated templates that will actually be used by many add-ons, that can be done too, but I'd consider this lower priority than getting all the basic UI widget types createable and – very important, and currently only rudimentarily supported – allowing scripts to access them and change their properties later. What sort of templates would you need?

[frankystone]

Think of the fourth empire campaign where the player has to decide to attack Vesta or to deliver some wine. Here a simple yes/no template would be fine. A Yes/No template would be one of the most used, i guess, because simple decisions can be made as a question which only can be answered with yes or no.

And in general like described in #2117 , e.g. a mutiline optionbox to make it possible to make some sort of conversation with different possible answers:

Protagonist: "Hey, nice to meet you!"
Possible answers from the player

• I am fine, thank you (leaving)
• Who are you?
• Hey, nice to meet you also. May i ask you some thing?
• I don't have the time to speak to you

Depending on the players choice, a scenario can act different. Either start a conversation with the protagonist or not.

For the editor i think having just a OK-template is enough. More difficult things can be implemented later, or if (ever) needed.

[frankystone]

One question and suggestions to improve the example with comments.

[frankystone]

From my side this is good to go now :-)

[frankystone]

Instead of of using checkboxes one can also create a window with buttons to achieve a multi-answer approach. I have tried that, but it fails with

expected a userdata, but got something else.

Any advice?

The scenario: test_UI-Plugin.zip

[Noordfrees]

Lua function call syntax: mv.create_child( → mv:create_child(

[frankystone]

Always the same stupid mistakes, thanks a lot!

all comments were resolved

[tothxa]

I've gone through lua_ui.cc once, and it looks OK, but I want to double-check against the docs.

Meanwhile some minor comments.

[tothxa]

Thank you. I only tested with your attached add-on, otherwise I rely on @frankystone's earlier testing.

The generic get_table_{string,int,boolean} functions could be moved to lua.{cc,h}.

[tothxa]

Sorry, I didn't realise they needed another header.

[Noordfrees]

Thanks for the review :)