make UI reusable and clean

[ahicks92]

I mean for background read the code or be on Discord. Basically we don't have reusable UI and what we have now is...amusing. I promised a plan. This is a plan.

Background

Let's ignore how GUIs are implemented today. It's not useful to get into that mostly because it's slightly different everywhere. Instead, let's list the workflows we have, plus a couple things I personally want.

What we have:

• Vertical menus (not the travel menu, though).
• Grids of known, but possibly changing, size (the travel menu, by virtue of having the same commands on everything, is jhust this but with labels instead of x,y coords).
• Categorized menus like the crafting menu where up/down changes the category and left/right goes through items. These aren't grids. Each category may have a different number of items.
• A "tree" for items. This one is hard to describe well because using it is kind of counterintuitivbe and I think we actually have two implementations.
• All of the above can be found under a GUI with tabs. We might as well call tabs focus, as it is one control per tab.

It's also worth noting We cannot express the armor grid, because that's multi-cell items that can rotate. I think that we have to code that as a oneoff. See below for how.

The problems with what we have:

• Controls aren't standard, and there's no way for a user to get help. Indeed we do such silly things as the crafting queue being presented as some sort of grid-thing.
• When using a GUI, keystrokes can get passed through to the non-GUI handlers. We fix those only to have more arise.
• Menu search is at the mercy of whether or not an extremely complicated block of code was extended to support this specific menu on a case by case basis. Very obvious things where it would be very useful to have it do not support it, for example the travel menu, which is consequently almost too slow beyond 10 or so travel points.
• No jumping to the top or bottom or beginning/end.

now I also said it'd be good if we could support two additional things:

• Vertical menus with horizontal "commands" on only some items. Consider the circuit menu where there's a ton of things to edit the condition just thrown down and you have to arrow past them to get to the right field. This is very useful for editing properties like that: move to the right or whatever for textbox or (like circuit networks) move to the right for the parts. This can be extrremely useful for train schedules, as well, since effectively each set of conditions is a row.
• The ability to jump to another UI and back. Suppose we do all the nice things and have a fast travel that's a tree. Now it's time to change something or delete it. Where's the menu going? We already had to use all of wasd.

So, plan time.

1. Get rid of the events problem.

Eph has been proposing a prioritized event handler that runs oinly one event, but it keeps getting bogged down and I at least am skeptical of integer priorities and the like. Let us therefore declare event handlers like this:

{
  ... Other events,
  {
    name = 'cursor-north', -- or whatever else.
    handler = handle_this,
    when = condition_fn, -- but see below.
  }
}

The condition handler is annoying but fopr the sake of this discussion take it as a given that we will do:

or_(item_in_hand("iron-plate"), gui_closed)

or and_, nested to arbitrary depth, and yes it would work with pindex. We can get into how this would be implemented if needed. The trailing _ is because leading _ usually means private in languages without proper privacy, and these functions are named for Lua keywords.

Just put events down in the order they should run, it runs down it, it hits them till it finds one that matches, it runs it. very simple. For debugging we just print out if there's ever more than one. This drops things like letting the player know there were two possibilities which Eph wanted, but today we can't even reliably fire only one when only one is relevant. Also writing conditions like that should let us pretty print what happened, if we really need to.

This ties into the rest because, as above, that ui_open bit. Do that, or alternatively just flag whether or not the event only implies when a UI is open, or whatever--the primary thing is that we'd then have a way to call only one event handler. Also this is a possible solution to #198 as the mod can record internal custom input events and then replay them inside lua if we wanted to go that far (detecting which are custom events is something I am 99% sure we can do without making you write it).

This part is fast to write but long to explain. Here comes the hard stuff.

New GUIs

new GUIs will consist of a table, one per widget type. This table will be built only from state in global. As seen below we won't support dynamic controls: you declare the GUI at the top level on load and that's it too bad sucks to be you.

To use a menu for example, it would have:

• A name. For example "travel-menu". This identifies the UI.
• Some number of menu items. Each of the form { key? = unique-never-changing-value, label = LocalisedString, action? = "the_action", search_text = "iron ore" }. (? menaning optional).
• A handler function which would take a string that matches the handler name above, and switch on it to figure out what to do.
• (see below wrt other clicks)

This menu would be declared effectively as a global variable. We would offer an object oriented menu builder. You would use that to divorce yourself from the format. There are a few parts that make this work:

• In the event handler registration we divert UI-relevant events to a ui library submodule.
• Each kind of unique UI widget is implemented specifically by that module, with no real chance to extend it. Everyone outside that module cannot add new kinds. For example "menu" is the widget, "fast-travel" is just one someone declared somewhere.
• A UI is opened with open_ui(name), closed with close_ui(), and back_uii() closes one "level" (see below). Names subject to change.
• When done or whatever term you like, the handfler function gets called and the user does string comparison. But;
• We offer a function to build the handler function based off a table of the form { name = handler } rather than making you write it all yourself every time.
• Everything else is an implementation detail subject to change.

One notable thing not described so far: how do controls handle dynamic changes? We will do that by allowing (some) controls to describe themselves with a function callback instead of a static definition. For example menus will need to be able to take a function which can return the genuine menu structure. As above, one thing a menu specifically gets (when possible) is key, which can be used to re-sync focus as items are added. For other controls such as grids, you'd need a function for dimensions and to get a slot, etc.

Now, time for nesting UIs, generic pieces like textboxes etc. What we don't need is a full, detailed, and robust stack. It would be nice but ultimately we have so far been able to fit everything in what we currently have, it's pretty nice modulo bugs and limitations, let's just make people keep doing that. To make this work, every time something calls ui_open we record which UI opened and then to go "back" is just to descend one level. The difference between this and the more generic solution: we won't allow cycles. No oepning a UI that's already open.

There is one final elephant in the room: textboxes. It's not practical to code up something which makes you declare a textbox to go with every menu item, so it'll be necessary to have a textbox-only GUI declaration path. We will make all text boxes the same. When a textbox is opened the control can pass additional arguments to be returned to itself in whatever fashion. When trbhe textbox closes to return to the GUI it's going to return to, it passes that along. To make that work fine we just need to be sure that users can never open a second GUI somehow, which is already impossible via the virtue of input handling but can be enforced simply buy closing all GUIs.

One final question wrt using it which may come up: don't menus have multiple kinds of things? yes. But ultimately only 4 of them:

• Static labels.
• Toggles: click it and it changes the value.
• Sliders: they can be adjusted up and down. Click it to open a text box.
• uh, call it text entry for now. Items which bopen a textbox for string data, e.g. renaming trains.

That's small enough that we can bite the bullet and make the generic menu just understand it. Same with other controls. Realistically we should never need more, and 1 and 2 come for free (1 is obvious; 2 bec ause the only way it changes is via a handler, because the value must also be written). Similar philosophy applies to other controls, as we can keep things simple if we choose to do so.

2. State

This seems worth a section. For background Factorio supports global state which must be synced between all clients in a game, and local lua-vm specific state which is wiped out on restarts of the client. This is the breakdown of that.

In local state:

• Event handler registration, obviously.
• The static tables or functions etc. that describe the UI itself.

In global state, let's call this the "render state":

• The current list of open UIs in order.
• The last fully realized form of whatever UIs are open (e.g. after all functions are called, whatever). links back to the functions via strings, thus the handler being like I described. So for example a dynamic menu, but only after the items are known for this tick.
• A version counter. If the version counter changes all UI is closed. This would be part of the UI module and is a way for devs to get UIs to close during development, and the mechanism for release. E.g. whenever an incompatible change is made just tick it up by one.

3. "timelines"

This is an OSS project so really just estimates of difficulty.

The event handler is idk, 2 hours. It's not that complicated. Add another hour for preparinjg. these steps are required: lift event handlers to named functions, even if this means making them global to avoid import cycles since most are in control.lua, write the logic, insert them into the table, convert their conditions into the condition expressions. Thbose condition exprtessions are just some closure tricks, not actually complex to set up (or_ itself returns a function, so on).

I think our next target should be some menu. Travel menu in this model is a bit...special. Not hard as such but not easy either. Maybe we target the blueprint menu fiorst to get something. I'm going to say this, sadly, is about a man-day but not complicated enough to be done in one wall clock day; there's a lot of experimentation and code shuffling and throwing thigns at the wall here to get the basic structure up and running.

Finally is the rest of it. That's the biggest unknown. We do things one by one as we can, we probably do the main inventory/crafting menus last, we do the ability to put UI components in tabs at this stage, and so on. Then just move things over as people have time, and always use it in new projects instead of the legacy patterns.

[ahicks92]

This is effectively blocked on https://github.com/Factorio-Access/FactorioAccess/discussions/225

if we decide to not continue down the road of key overloads how we do them now, that entirely changes how we handle input here. Handling input blocks doing anything else for hopefully obvious rasons. Don't want to write what's proposed herre if it's possible to just avoid it.

[ahicks92]

I'm closing this. I've got new job looming. Scanner took longer than expected. Etc. Plus we had various discussions since around input handling.

Instead we will do #262, followed by #263. This will unlock our ability to experiment and deal with this problem more gradually.