Glk Mapping extension

Technical Development Interpreters
29

I’m not ready to do a full write up, but as I’ve been waiting for a gestalt code for this, I’ve changed my mind about the shape of this API.

I now think that it fits better into the Glk API to just make a wintype_Map. It’s like a graphics window, but the user can pan/zoom it, and it supports overlays, hyperlinks, and SVG strings.

I do still think it’s best for maps to display in their own OS window, if possible, but I think that “maps” aren’t the only thing that belong there. Other things that could benefit from their own OS window:

  • ADRIFT has a floating map window (which users can “dock” to the main window) as well as an ambient graphics window for room graphics, which can optionally appear inline in the text buffer, or in a separate window (which can also be docked).
  • Hadean Lands has a Map window and also a Journal window (with a list of rituals/formulas/facts you’ve discovered)
  • Cairn has tabs for Map, Manual, and Hints. Anything that you might use Inform Menus/Basic Menus for could credibly go in an OS window.

To satisfy these use cases, I think Glk should have an “external window” API, perhaps something like:

winid_t glk_window_open_external(
    glui32 wintype,
    glui32 rock,
    glui32 *title,
    glui32 titlelen);

There would then need to be new events for these external windows, evtype_WindowUserFocus and evtype_WindowUserClose.

One reason I didn’t go for this at first was so the interpreter could choose its own “Show Map” UI, whether that’s a menu item in the macOS menu bar, or a pinned toolbar at the top of the screen, or a tab switcher like Hadean Lands for iOS.

But, based on the Glk, author control, and player control thread, I’ve been persuaded that Glk APIs are simpler to implement and understand if they’re under the author’s control. (We can build Inform extensions that implement responsive-design best practices.)

So, in order to give users a way to open the map using interpreter chrome, there could be a Glk Menu Bar API, like this:

void glk_menu_bar_add_item(
    glui32 id,
    glui32 *label,
    glui32 labellen,
    glui32 icon,
    glui32 flags);

It would add a “Game” menu to the OS menu bar, (or to a section of the interpreter’s hamburger menu, if the interpreter doesn’t have a native menu bar), which would fire off an evtype_MenuBarSelect event when the user selects an item.

And there could be a Glk Tab Bar API, like this:

#define wintype_Tabs                0xXXXX  /* TBD */

winid_t glk_tab_add(
    winid_t tabs,
    glui32 wintype,
    glui32 rock,
    glui32 *title,
    glui32 titlelen,
    glui32 icon);

A tab bar would show a tab switcher, allowing users to switch between different Glk windows.

Game code (e.g. the Inform extension) could decide whether to use tabs and a menu bar, or to prefer one over the other, or whether to have no UI at all except an in-game suggestion to “Type HELP for help.”

So, uh, now, instead of one gestalt and 16 functions, I think I’d want at least four gestalts, two window types, at least three event IDs, and, uh, more functions than that.

(I’m also musing about a Glk Menu Window API, for showing hints/help instead of the char-input menus that are standard today. That would need another window type, wintype_Menu, more functions, and more events.)