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.
|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(
- Trapper:wrap (func)
Executes a function and allows it to be trapped (that is: to use our
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
funcis half-done, with unintended consequences.
- func function reference to function to wrap and execute
- Trapper:isWrapped ()
Returns if code is wrapped
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.
- text string text to display as an InfoMessage (or nil to keep existing one)
true if InfoMessage was not dismissed, false if dismissed
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".
- 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
- text string text to display in a ConfirmBox
- cancel_text string text for ConfirmBox Cancel button
- ok_text string text for ConfirmBox Ok button
false if Cancel tapped or dismissed, true if OK tapped
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(
Notes and limitations:
1) It is dismissable as long as
cmdas 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
cmdoutput in some variable, and to output the whole variable to stdout at the end.)
cmdneeds to output something (we will wait till some data is available) If there are chances for it to not output anything, append
3) We need an InfoMessage, that, as a modal, will catch any Tap event happening during
cmdexecution. 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
ffior do low level non-blocking reading on the file descriptor. If there are
cmdthat may not exit, that we would be trying to collect indefinitely, the best option would be to compile any
timeout.cand use it as a wrapper.
cmdto 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
trueif not interrupted,
- string output of command
- cmd string shell