DFHack
The DFHack GUI
The number one request our users have is for a unified DFHack GUI that gives them a convenient and informative interface to DFHack functionality where they can discover tools and get help. This proposal sketches out how we might be able to provide this.
Script name: gui/launcher? gui/dfhack? gui/console? Suggestions welcome.
Global hotkey: backtick (this hotkey hint is displayed in one of the screen corners by default)
A dialog is shown that has three panels in the following layout:
----------------------------------
| | |
| | |
| | |
| | |
-------------------------| |
| | |
----------------------------------
- The top panel shows context-sensitive information and help.
- The bottom panel is for the commandline the user is typing and executing
- The right panel shows context-sensitive autocomplete options
When the user opens the dialog, a welcome message is displayed in the help area with instructions on how to operate the dialog. Also, hotkeys relevant to the current screen are displayed. Favorite and recent commands are displayed in the autocomplete area, which the user can click on with the mouse to select or iterate through using TAB and SHIFT-TAB. As the autocomplete suggestion is selected, it appears in the input area, but does not change the autocomplete options until the user types an additional character.
If the user hits one of the hotkeys listed in the help area, the command bound to that hotkey is copied to the input area and the user can edit the command before executing.
If the user starts typing, the autocomplete area is filled with options based on what was typed so far. Suggestions are ordered by:
- GUI version of currently-typed commandline command or commandline version of currently-typed gui command
- substring matches of command names
- commands that are associated with the currently typed complete command (e.g. are referenced from the command help, have the same tags as the command, etc.)
- commands whose tags match the currently typed words (this is a new concept that will have to be defined)
- commands whose help text matches the currently typed words
If the input area starts with a command name, the help text for that command is displayed in the help area. Users can scroll this help text with the arrow keys or pgup/pgdn (and maybe the mouse wheel if we can support that). If the input area has a command option as the last token, the autocomplete are may be filled with relevant potential options (if the command supports that, through an API we have not yet defined).
The user can search through the command history with the Ctrl-R hotkey (same behavior as bash).
When the user hits ENTER, the GUI is dismissed and the command is executed. Output from the command goes--where? in a popup window? to the console? This needs to be thought out.
The launcher configuration can be accessed with some hotkey, where the user can configure favorites. Initial favorites could default to popular tools, or maybe to new help/tutorial tools we will write. Also if/where the backtick hotkey text is displayed. We could also potentially subsume hotkey configuration into this interface (though that might be more at home in the proposed gui/assistant in #2213).
In order for help text to be displayed, we'll need to make all our help text programmatically available. This is already done for scripts, but we'll need to rethink how plugin documentation works.
All commands will need to be tagged with some set of words that the user can use to explore different types of tools. e.g. "automation", "info", "unit", etc. These tags can appear in the command metadata, maybe following the syntax set out in #2221.
How much room will be required for this GUI? I don't know. I'll have to write a proof of concept to see how feasible it is to have all this info on one screen.
Is it feasible to search through our entire corpus of help text on every keypress? Maybe. We'll have to see what the performance is like. There are algorithms and data structures that can help with this. It could be that the autocomplete list is often filled in the earlier steps and the help text search rarely happens.
Do we need a way to pass a literal backtick to DF? Will the hotkey shadow anything useful?
Related to this, we should have a global hotkey that displays the help text for the currently running DFHack GUI script, as identified by the focus string.
I like the idea! A couple really minor things I thought of:
-
This sounds kind of like an editor "command palette" to me. In that case, I would prefer the search box at the top. No strong reason other than familiarity.
-
we should have a global hotkey that displays the help text for the currently running DFHack GUI script, as identified by the focus string
From an implementation perspective, this might be tricky. I wonder if we could do some magic to associate
gui.Screeninstances with the value ofdfhack.current_script_name()when they are created. (Well, doing that is easy, but making it accessible fromgui.getCurViewscreen()is harder)
- This sounds kind of like an editor "command palette" to me. In that case, I would prefer the search box at the top. No strong reason other than familiarity.
We could mock that up and see how it looks. I was thinking of it more as a commandline than a search box, which is why I thought it looked more at home at the bottom. However, it will be easy enough to try both options and send them out for feedback.
we should have a global hotkey that displays the help text for the currently running DFHack GUI script, as identified by the focus string
From an implementation perspective, this might be tricky. I wonder if we could do some magic to associate
gui.Screeninstances with the value ofdfhack.current_script_name()when they are created. (Well, doing that is easy, but making it accessible fromgui.getCurViewscreen()is harder)
Another option is to enforce a standard that gui scripts are required to intercept the same hotkey and display their own help. Not quite as elegant, but when you can't do elegant, you go for policy.
Maybe we could implement the functionality in gui.Screen.
we'll need to order the autocomplete suggestions somehow. we have perhaps an initial ordering based on the survey results, but that only covers a few tools. maybe we can track the frequency that each command is used by the player and use that to shape the autocomplete ordering over time.
more thoughts and plans:
- integration with the console history (both should use the same history list)
- ctrl-C to clear the edit box
- ctrl-R to search through command history with a substring, more ctrl-R keypresses go to the next match, and so on
- ctrl-up / ctrl-down for walking through the history line by line (same as up/down in the console, but plain up and down are already assigned to scroll the help text window)
- ctrl-/ for help on all these extra hotkeys since there's no more room in the UI for hotkey hints I'm also considering adding history matches to the autocomplete window so users can just TAB to them instead of having to search. I'm not sure if this will work well, though, since the autocomplete window section is only 20 characters wide, so you wouldn't really be able to see what was there until you TABbed to it. also, the autocomplete window might get filled up with history matches, and tool matches would get pushed offscreen oh, also Ctrl-PgUp to do a prefix search through the history, based on what's in the edit box so far. this would differ from the Ctrl-R search because Ctrl-R would search for the substring you typed after you hit Ctrl-R, and Ctrl-PgUp would search for the substring you typed before you hit Ctrl-PgUp (both behaviors directly borrowed from *nix shell features, which I find extremely useful on a daily basis) one feature we're missing right now that might be needed is the ability to use the left/right cursor keys (and home and end and ctrl-cursor keys to move by word) to move the cursor and edit the middle of a command. Our current EditField widget only supports editing the end of the current line. modifying an existing command (say, one that you pulled up from your command history) requires backspacing over all the characters until you get to the place you want to edit, then retyping all the stuff you deleted. This will probably frustrate users. It's a little wonky since we can't render a cursor over an existing character. we might have to displace the characters with a space where we render a blinking underline to represent the cursor position. myk002 — Today at 10:00 PM one more thing before I forget, the UI should disappear if it's already open and the user hits
`
again, mimicking how the debug console appears and disappears in many first-person games