From 5bce3d00675a46c7b0b8ecb3934c5d7d5d9034af Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Mon, 24 Sep 2018 23:58:59 -0400 Subject: Documented async functions --- docs/unfreefeatures.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) (limited to 'docs') diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index cd27745d..fd8b0a6d 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -189,3 +189,26 @@ Exit code to shell The ``self.exit_code`` attribute of your ``cmd2`` application controls what exit code is sent to the shell when your application exits from ``cmdloop()``. + + +Asynchronous printing +===================== +``cmd2`` provides two functions to provide asynchronous feedback to the user without interfering with +the command line. This means the feedback is provided to the user when they are still entering text at +the prompt. To use this functionality, the application must be running in any terminal that supports +VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these. + +_async_alert() + Used to display an important message to the user while they are at the prompt in between commands. + To the user it appears as if an alert message is printed above the prompt and their current input + text and cursor location is left alone. + +_async_update_prompt() + Updates the prompt while the user is still typing at it. This is good for alerting the user to system + changes dynamically in between commands. For instance you could alter the color of the prompt to indicate + a system status or increase a counter to report an event. + + +The easiest way to understand these function is to see the AsyncPrinting_ example for a demonstration. + +.. _AsyncPrinting: https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py -- cgit v1.2.1