Actions

Actions

Menu actions are hooks into your code. That means the object used by the menu system stores a reference to your function, to be called later in response to some events. They are the core of the structure unit (prompt/option) and all other menu structure objects. Every element can have its own custom dispatch function.

The system initializes it from user callback functions with a couple of allowed formats.

At construction moment usually an event mask is also provided to filter the action call.

Callback format

Your functions must belong to a strict set of accepted formats to be used as actions callbacks.

Return

The return type can be:

result - function can return proceed or quit

enum result {proceed=0,quit};

void - menu system will consider it a proceed (with default action).

Returning quit can be ignored or be interpreted as a menu exit in some combination of cases, depending on the context.

Parameters

Callback functions can have these parameter formats:

() - void, no parameters

(eventMask event) - the event being delivered

(eventMask event, prompt &item) - the event and the related menu prompt

examples:

void myFunc1();
result myFunc2();
void myFunc3(eventMask e);
result myFunc4(eventMask e,prompt& p);

etc..

Note that the delivered prompt objects do not provide information about navigation, even that it is a menu. There is no direct information about the selected option. Unless you know beforehand who has the handler and by consequence who's the owner menu or at the very least you are sure that it's a menu... The provided context passed by is somehow short, but because we can customize this functions per element we can have extra, implicit information by knowing the set of actions that has been given a particular callback function. Without this user organization there is no information on the given prompt object about the menu structure it was inserted into or the navigation status. That can only arise from your organization.

example:

If void op2() has been given as a callback function to a single menu option along with an event mask of enterEvent, then no extra info is needed, we already know it was an enter on that single menu option. Menu options can sometimes share the same callback, either because we do not care about any context or because they belong to a group who's context is known, for example, if they are all members of a known menu. If so, we can inquire the known context object about extra information or the navigation root.