Idling

Execute other tasks when menu is suspended.

When exiting from the main menu, either with '/' escape or by selecting an exit option if available. The menu enters an idle state. By default a blank screen doing nothing.

This idle state can be called or activated by other methods.

When using the menu API for idling functions it is also a way of providing user dialogues or alerts.

to return to menu again press select or escape (keys: '*' or '/')

Enter or exit sleep state by code command

call idleOn() to force menu into an idle state with the predefined idle function or idleOn(myFunct) for an alternative one.

call idleOff() to resume

menu enters idle state on next poll.

menu state is preserved.

Note: Also it is possible to call exit() method to enter the idle state.

Enter idle state by timeout

Set navRoot::timeOut to the number of seconds of "inactivity" to auto enter idle state.

Inactivity is measured by output change (not input). This allows monitoring changing values.

The menu state is preserved.

Idle background

From version 4.7.2, if compiled with MENU_IDLE_BKGND defined, then the idleTask function is also called whenever on idle state with a user defined sleepTask.

Inside the idleTask one can distinguish the case by checking if the sleepTask is the same as idleTask.

ex:

nav.idleTask!=nav.sleepTask

this allows some common idle/sleep tasks to be performed when menu executing user defined sleep functions.

Handling idle task

Often you want to do other tasks on idle/sleep state. There are multiple methods of doing so.

The efficient way

Just don't call the menu poll function, clear the screen and use it for whatever purpose you desire. This is efficient because the menu is not being polled and its completely inactive.

• This method can be used at any time and is independent of the menu state.
• The menu state is preserved
• Just start calling the poll function again to resume.
• you have to manage input on your own and activate the menu again when needed

The easy way

Check the menu state and do alternative tasks when menu exited. The alternative tasks are only executed when exiting from the main menu or menu forced intro idle state.

example:

//on a device that uses poll
void loop() {
  nav.poll();
  if (nav.sleepTask) {
    //do your update here...
  }
}

  //...
  //on u8g2 or other devices that uses doInpu/doOutput instead of poll
  nav.doInput()
  if (nav.sleepTask) {
    u8g2.firstPage();
    do {
      u8g2.setCursor(0, 15);
      u8g2.print("suspended");
    } while ( u8g2.nextPage() );
  } else {
    if (nav.changed(0)) {
      u8g2.firstPage();
      do nav.doOutput(); while(u8g2.nextPage());
    }
  }
  //...

The only disadvantage of this method is that you are responsible to update the multiple output devices, in case you are using them. Otherwise its just fine.

The hard way

provide an idling function and do stuff inside it. This method is non blocking, if your function is non blocking and the alternative tasks are called when exiting from main menu.

start by pointing your alternative idle function

nav.idleTask=myFunct;//can do this on setup or when appropriate

myFunct will then be called when the menu is suspended/idling, and when exiting from main menu.

myFunct is of type idleFunct

result (*idleFunc)(menuOut& o,idleEvent);

your function will be called for each defined output device (passed it as first parameter) and with one of the following events as second parameter:

enum idleEvent {idleStart,idling,idleEnd};

Therefor it will be called at least 3 time per output device, one for each event. On some devices that require redraw the idling event might repeat for each poll until exit.

If you have a task that needs constant attention, like drawing a clock on idle screen you can signal that with:

nav.idleChanged=true;

somewhere inside your idle handler code. This will cause the menu system to call your idle function every poll with the event idling