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:
- 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 incmd
, could probably be used to accumulatecmd
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"
tocmd
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()
viaffi
or do low level non-blocking reading on the file descriptor. If there arecmd
that may not exit, that we would be trying to collect indefinitely, the best option would be to compile anytimeout.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:
-
boolean
completed (
true
if not interrupted,false
if dismissed) - string output of command
- cmd
string
shell