Module ui.trapper

Trapper module: provides methods for simple interaction with UI, without the need for explicit callbacks, for use by linear jobs between their steps.

Allows code to trap UI (give progress info to UI, ask for user choice), or get trapped by UI (get interrupted). Mostly done with coroutines, but hides their usage for simplicity.

Functions

Trapper:wrap (func) Executes a function and allows it to be trapped (that is: to use our other methods).
Trapper:isWrapped () Returns if code is wrapped
Trapper:clear () Clears left-over widget
Trapper:reset () Clears left-over widget and resets Trapper state
Trapper:info (text) Displays an InfoMessage, and catches dismissal.
Trapper:setPausedText (text, abort_text, continue_text) Overrides text and button texts on the Paused ConfirmBox.
Trapper:confirm (text, cancel_text, ok_text) Displays a ConfirmBox and gets user's choice.
Trapper:dismissablePopen (cmd, infomessage, check_interval_sec) Dismissable wrapper for io.popen(cmd).


Functions

Trapper:wrap (func)
Executes a function and allows it to be trapped (that is: to use our other methods).

Simple wrapper function for a coroutine, which is a prerequisite for all our methods (this simply abstracts the coroutine business to our callers), and execute it.

(If some code is not wrap()'ed, most of the other methods, when called, will simply log or fallback to a non-UI action or OK choice.)

This call should be the last step in some event processing code, as it may return early (the first coroutine.yield() in any of the other methods will return from this function), and later be resumed by UIManager. So any following (unwrapped) code would be then executed while func is half-done, with unintended consequences.

Parameters:

  • func function reference to function to wrap and execute
Trapper:isWrapped ()
Returns if code is wrapped

Returns:

    boolean true if code is wrapped by Trapper, false otherwise
Trapper:clear ()
Clears left-over widget
Trapper:reset ()
Clears left-over widget and resets Trapper state
Trapper:info (text)
Displays an InfoMessage, and catches dismissal.

Display a InfoMessage with text, or keep existing InfoMessage if text = nil, and return true.

UNLESS the previous widget was itself a InfoMessage and it has been dismissed (by Tap on the screen), in which case the new InfoMessage is not displayed, and false is returned.

One can only know a InfoMessage has been dismissed when trying to display a new one (we can't do better than that with coroutines). So, don't hesitate to call it regularly (each call costs 100ms), between steps of the work, to provide good responsiveness.

Trapper:info() is a shortcut to get dismiss info while keeping the existing InfoMessage displayed.

Parameters:

  • text string text to display as an InfoMessage (or nil to keep existing one)

Returns:

    boolean true if InfoMessage was not dismissed, false if dismissed

Usage:

    Trapper:info("some text about step or progress")
go_on = Trapper:info()
Trapper:setPausedText (text, abort_text, continue_text)
Overrides text and button texts on the Paused ConfirmBox.

A ConfirmBox is displayed when an InfoMessage is dismissed in Trapper:info(), with default text "Paused", and default buttons "Abort" and "Continue".

Parameters:

  • text string ConfirmBox text (default: "Paused")
  • abort_text string ConfirmBox "Abort" button text (Trapper:info() returns false)
  • continue_text string ConfirmBox "Continue" button text
Trapper:confirm (text, cancel_text, ok_text)
Displays a ConfirmBox and gets user's choice.

Display a ConfirmBox with the text and canceltext/oktext buttons, block and wait for user's choice, and return the choice made: false if Cancel tapped or dismissed, true if OK tapped

Parameters:

  • text string text to display in a ConfirmBox
  • cancel_text string text for ConfirmBox Cancel button
  • ok_text string text for ConfirmBox Ok button

Returns:

    boolean false if Cancel tapped or dismissed, true if OK tapped

Usage:

    go_on = Trapper:confirm("Do you want to go on?")
that_selected = Trapper:confirm("Do you want to do this or that?", "this", "that"))
Trapper:dismissablePopen (cmd, infomessage, check_interval_sec)
Dismissable wrapper for io.popen(cmd).

Notes and limitations:

1) It is dismissable as long as cmd as not yet output anything. Once output has started, the reading will block till it is done. (Some shell tricks, included in cmd, could probably be used to accumulate cmd output in some variable, and to output the whole variable to stdout at the end.)

2) cmd needs to output something (we will wait till some data is available) If there are chances for it to not output anything, append "; echo" to cmd

3) We need an InfoMessage, that, as a modal, will catch any Tap event happening during cmd execution. This can be provided as a string (a new InfoMessage will be created), or can be an existing already displayed InfoMessage.

If we really need to have more control, we would need to use select() via ffi or do low level non-blocking reading on the file descriptor. If there are cmd that may not exit, that we would be trying to collect indefinitely, the best option would be to compile any timeout.c and use it as a wrapper.

Parameters:

  • cmd string shell cmd to execute and get output from
  • infomessage string or already shown InfoMessage widget instance
  • check_interval_sec int [opt=0.1] float interval in second for checking pipe for available output

Returns:

  1. boolean completed (true if not interrupted, false if dismissed)
  2. string output of command
generated by LDoc 1.4.6 Last updated 2017-10-08 14:57:40