Prompt
cmd2
issues a configurable prompt before soliciting user input.
Customizing the Prompt
This prompt can be configured by setting the cmd2.Cmd.prompt
instance attribute. This contains the string which should be printed as a prompt for user input. See the Pirate example for the simple use case of statically setting the prompt.
Continuation Prompt
When a user types a Multiline Command it may span more than one line of input. The prompt for the first line of input is specified by the cmd2.Cmd.prompt
instance attribute. The prompt for subsequent lines of input is defined by the cmd2.Cmd.continuation_prompt
attribute.See the Initialization example for a demonstration of customizing the continuation prompt.
Updating the prompt
If you wish to update the prompt between commands, you can do so using one of the Application Lifecycle Hooks such as a Postcommand hook. See PythonScripting for an example of dynamically updating the prompt.
Asynchronous Feedback
cmd2
provides these 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 a terminal that supports VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these.
cmd2.Cmd.async_alert
Display an important message to the user while they are at a command line prompt. 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.
This function needs to acquire self.terminal_lock to ensure a prompt is on screen. Therefore, it is best to acquire the lock before calling this function to avoid raising a RuntimeError.
This function is only needed when you need to print an alert or update the prompt while the main thread is blocking at the prompt. Therefore, this should never be called from the main thread. Doing so will raise a RuntimeError.
PARAMETER | DESCRIPTION |
---|---|
alert_msg
|
the message to display to the user
TYPE:
|
new_prompt
|
If you also want to change the prompt that is displayed, then include it here. See async_update_prompt() docstring for guidance on updating a prompt.
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
if called from the main thread. |
RuntimeError
|
if called while another thread holds |
Source code in cmd2/cmd2.py
5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 |
|
cmd2.Cmd.async_update_prompt
Update the command line 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. If you do alter the actual text of the prompt, it is best to keep the prompt the same width as what's on screen. Otherwise the user's input text will be shifted and the update will not be seamless.
If user is at a continuation prompt while entering a multiline command, the onscreen prompt will not change. However, self.prompt will still be updated and display immediately after the multiline line command completes.
PARAMETER | DESCRIPTION |
---|---|
new_prompt
|
what to change the prompt to
TYPE:
|
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
if called from the main thread. |
RuntimeError
|
if called while another thread holds |
Source code in cmd2/cmd2.py
cmd2.Cmd.async_refresh_prompt
Refresh the oncreen prompt to match self.prompt.
One case where the onscreen prompt and self.prompt can get out of sync is when async_alert() is called while a user is in search mode (e.g. Ctrl-r). To prevent overwriting readline's onscreen search prompt, self.prompt is updated but readline's saved prompt isn't.
Therefore when a user aborts a search, the old prompt is still on screen until they press Enter or this method is called. Call need_prompt_refresh() in an async print thread to know when a refresh is needed.
RAISES | DESCRIPTION |
---|---|
RuntimeError
|
if called from the main thread. |
RuntimeError
|
if called while another thread holds |
Source code in cmd2/cmd2.py
cmd2.Cmd.need_prompt_refresh
Check whether the onscreen prompt needs to be asynchronously refreshed to match self.prompt.
Source code in cmd2/cmd2.py
cmd2
also provides a function to change the title of the terminal window. This feature requires the application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and greater all support these.
cmd2.Cmd.set_window_title
staticmethod
Set the terminal window title.
NOTE: This function writes to stderr. Therefore, if you call this during a command run by a pyscript, the string which updates the title will appear in that command's CommandResult.stderr data.
PARAMETER | DESCRIPTION |
---|---|
title
|
the new window title
TYPE:
|
Source code in cmd2/cmd2.py
The easiest way to understand these functions is to see the AsyncPrinting example for a demonstration.