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 From 10dd79e9dee5f0286cd413d513645083e7c44e8a Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Tue, 25 Sep 2018 00:19:20 -0400 Subject: Made async stuff public --- docs/unfreefeatures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index fd8b0a6d..1b8adb8d 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -198,12 +198,12 @@ the command line. This means the feedback is provided to the user when they are 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() +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() +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. -- cgit v1.2.1 From ecbaf000ca0384b5caafb0d79725a127e65bb2d5 Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Tue, 25 Sep 2018 17:57:52 -0400 Subject: Added more examples and documentation --- docs/unfreefeatures.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 1b8adb8d..60630258 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -191,11 +191,11 @@ what exit code is sent to the shell when your application exits from ``cmdloop()``. -Asynchronous printing +Asynchronous Feedback ===================== ``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 +the prompt. To use this functionality, the application must be running in a terminal that supports VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these. async_alert() @@ -208,6 +208,13 @@ async_update_prompt() 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. +``cmd2`` also provides a function to change the title of the terminal window. This feature requires the +application be running in a terminal that support VT100 control characters. Linux, Mac, and Windows 10 and +greater all support these. + +set_window_title() + Sets the terminal window title + The easiest way to understand these function is to see the AsyncPrinting_ example for a demonstration. -- cgit v1.2.1 From 39e43d6329eb517ac58f95a8ca37e7e489d446cb Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Tue, 25 Sep 2018 19:10:46 -0400 Subject: Addressing code review comments --- docs/unfreefeatures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 60630258..b5f9415d 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -209,13 +209,13 @@ async_update_prompt() a system status or increase a counter to report an event. ``cmd2`` also provides a function to change the title of the terminal window. This feature requires the -application be running in a terminal that support VT100 control characters. Linux, Mac, and Windows 10 and +application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and greater all support these. set_window_title() Sets the terminal window title -The easiest way to understand these function is to see the AsyncPrinting_ example for a demonstration. +The easiest way to understand these functions 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