States

Overview

The menu uses a stack based approach to transition between different states. Each state represents the logic for one screen, which can be displayed in the browser. In addition to states, it is possible to add views, which consists of html and JS code which is run in the browser.

States

Each state has to be put in its own file, located in the states directory. The file has to export a function with the parameters helperFunctionsand api and return an object with the following keys.

name

The name of the state. It is used to load the state via the API.

captions

The captions which should be displayed below the buttons and above the rotary encoders. The keys can be A, B,C and D for the buttons and R1, R2, R3 and R4 for the encoders. The values can either be the text which should be displayed or a colon in conjunction with a Fontawesome icon name([https://fontawesome.com/icons?d=gallery&m=free]). If a key is left out, the corresponding caption is hidden on that screen.

data

The mutable parts of the states data.

start

The function is called when the state is loaded and put on the stack. The initial data object is passed as a parameter.

resume

This function is called when a state is being resumed. This happens when a state loads another state, which later is unloaded. The state which is being removed from the stack can pass information to the resumed state. This is used for example by the keyboard state, which passes the entered text to the previous state. The resume function is called with the name of the unloaded state, the provided data and the data of the resumed state.

events

An object which holds the callback functions for incoming events. The key represents the event name. The value has to be an array with check-callback pairs (described below)

extends

An array with state which events should be inherited. The events are added after the handlers defined inside the state, but before any `Else` handler.

Example state

module.exports = ({Arg0, Else}, api) => {
    return {
        name: "root",
        captions: {
            "A": ":battery-half",//Icon
            "C": "Search",//text
            "D": "Record"
        },

        data: {
            settings: {}
        },
        resume: (name, returnData, data) => {
            console.log("Resume root from:", name, returnData);
            console.log("a", data);
            api.getSettings().then((tmp) => {
                data.settings = tmp
            });
            api.display("root", data);
        },
        start: (data) => {
            api.display("root", data);
        },

        events: {
            "BUTTON_UP": [
                [Arg0("A"), [
                    (api, data, event) => {
                        api.pushState("load_sample", data);
                    }
                ]],
                [Arg0("C"), [
                    (api, data, event) => {
                        api.pushState("sample_search", data);
                    }
                ]],
                [Arg0("D"), [
                    (api, data, event) => {
                        api.pushState("sample_record", data);
                    }
                ]]
            ]
        }
    };
};

Event Handler

The entries of the events array have to be an array where the first element has to be a function which later is called with the events parameters. The function should check if the handler has to be called for the specific event and return the results in form of a boolean value. All other entries are the actual callback function which are called with the api, the states data and the event.

[
  (parameters)=>parameters[0]>5,
  (api,data,{event,data})=>{console.log("The first parameter is > 5!")},
  (api,data,{event,data})=>{console.log("I am also being called :-)")}
]

There exist two helperFunctions which ease the generation of check functions.

Arg0(testValue)

Checks if the first parameter equals `testValue`. Shorthand for

(args)=>args[0]===testValue

Else

A function which returns `true` all the time. It is used as a default case, or when the parameters of an event do not matter. Additionally the usage of the `Else` function is used to determine the insert position of events of extended states (they are inserted below the states own handlers, but above the first `Else` handler).

Api

pushState(stateName, data={})

Loads another state with the given name. If the data parameter is provided, it is merged with the states data.

popState(data={})

Unloads the current and resumes the previous state. The data is being passed to the resume function.

send(event,parameters,recipient=3)

Sends an event to the MessageQueue. Parameters has to be an array.

sendView(event,parameters={})

Sends an event to the Browser

sendCaptions(captions)

Sends new captions to the view. The structure of the parameter has to be the same as the `captions` key of the state definition.

display(viewName,data)

Loads a view inside the browser.

settings.setDefault(key,value)

Set a default value for a setting.

settings.set(key,value)

Set a setting.

settings.unset(key)

Unsets a setting.

settings.get(name,[default])

Loads a setting by name. If the specific key is not present, the default parameter is returned. If no default parameter was provided, the saved default for the key(if any) or `undefined` is returned.

file.settings

Same as `settings.*` but for settings for the currently loaded file.