MenuGraphr/docs/lists.md

Lists

Menus can have scrollable lists of selectable text options in them. Users can use direction inputs to scroll through the items.

Lists can be one-dimensional or two-dimensional. This is determined by the computed height of list options within the menu's height. If enough options are added to a list to pass the bottom, unless the menu specifies singleColumnList, they will overflow to a column to the right.

IListMenuSchema

When creating or declaring schemas for list menus, there are some additional properties you can apply to them. These are all optional.

saveIndex

Whether the last selected index should be saved. When true, the parent EightBittr's ItemsHoldr will save the selected index of the menu under the menu's name. Recreating the menu will read from that stored index if available.

{
    saveIndex: true,
},

clearedIndicesOnDeletion

Names of menus whose whose selected indices that should be cleared when this menu is deleted. Use this when there are multiple related list menus open at once, and finishing one clears another.

{
    clearedIndicesOnDeletion: [
        "KeyboardKeys",
        "NameCollection",
    ],
},

scrollingItems

How many scrolling items should be visible within the menu vertically. List menus will by default show all the items at once, which is bad if there are many options and not enough menu height to display them all. Specify a scrollingItems number to hardcode a maximum to display at once.

If the user shifts their selected index to below the lowest displayed item or above the highest displayed item, the menu will "scroll" items vertically. It does this by shifting their Things vertically and setting hidden on items not allowed to be seen.

{
    scrollingItems: 10,
},

There is no equivalent for horizontal items.

scrollingItemsComputed

As an alternative to scrollingItems, you can have the maximum displayed number of items computed as a function of menu height and expected height per list option. This will set the scrollingItems member of the menu on list creation.

{
    scrollingItemsComputed: true,
},

singleColumnList

Whether the list should always be a single column, rather than auto-flow.

{
    singleColumnList: true,
},

addMenuList

Adds a list of text options to a menu.

Parameters:

• menuName: Name of the menu.
• settings: Settings for the list, particularly its options.

IListMenuOption

Individual option within a list. Only text is required.

callback

Callback for when the option is triggered. Receives just the menu name.

{
    options: [
        {
            callback: () => console.log("First!"),
            text: "First",
        },
    ],
},

position

Position offsets to shift the option by, allowing top, right, bottom, left.

{
    options: [
        {
            position: {
                top: 30,
                right: -20,
            },
            text: "First",
        },
    ],
},

text

Text displayed as the option. This text will be rendered all in one row, similar to dialogs.

IListMenuOptions

Settings to create a new list menu. Only

bottom

A bottom option to display underneath displayed options. If the list is two-dimensional, this will span across all rows.

{
    bottom: {
        callback: () => console.log("Cancelled."),
        text: "Cancel",
    },
},

options

Options within the menu, or a function to generate them. This is a flat list of options regarldess of whether the menu is one- or two-dimensional.

{
    options: [
        {
            callback: () => console.log("First!"),
            text: "First",
        },
    ],
},

See IListMenuOption above.

selectedIndex

Each list contains a selectedIndex: [number, number] of the position of the currently selected index. This option overrides the starting selected index. It defaults to [0, 0].

Examples

Showing a simple "Yes/No" menu after a general text dialog that stays alive:

const finalize = (choice) => {
    console.log("Choice:", choice);
    menuGrapher.deleteMenu("Yes/No");
};

const createOptions = () => {
    menuGrapher.createMenu("Yes/No", {
        killOnB: ["GeneralText"],
    });

    menuGrapher.addMenuList("Yes/No", {
        options: [
            {
                text: "YES",
                callback: () => finalize(true),
            },
            {
                text: "NO",
                callback: () => finalize(false),
            }
        ],
    });

    menuGrapher.setActiveMenu("Yes/No");
};

menuGrapher.createMenu("GeneralText", {
    finishAutomatically: true,
    keepOnBack: true,
});
menuGrapher.addMenuDialog("GeneralText", "Are you sure?", createOptions);
menuGrapher.setActiveMenu("GeneralText");