Skip to content

prompt.md

Latest commit

 

History

History
115 lines (80 loc) · 4.1 KB

prompt.md

File metadata and controls

115 lines (80 loc) · 4.1 KB
Raw

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 getting_started.py 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 getting_started.py 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 python_scripting.py for an example of dynamically updating the prompt.

Asynchronous Feedback

cmd2 provides a function to deliver asynchronous feedback to the user without interfering with the command line. This allows feedback to be provided while the user is still entering text at the prompt.

  • [cmd2.Cmd.add_alert][]

Asynchronous Feedback Mechanisms

Alerts can interact with the CLI in two ways:

  1. Message Printing: It can print a message directly above the current prompt line.
  2. Prompt Updates: It can dynamically replace the text of the active prompt to reflect changing state.

!!! note

To ensure the user interface remains accurate, a prompt update is ignored if the alert
was created before the current prompt was rendered. This prevents older alerts from overwriting a newer
prompt, though the alert's message will still be printed.

Terminal Window Management

cmd2 also provides a function to change the title of the terminal window.

  • [cmd2.Cmd.set_window_title][]

The easiest way to understand these functions is to see the async_printing.py example for a demonstration.

Bottom Toolbar

cmd2 supports an optional, persistent bottom toolbar that is always visible at the bottom of the terminal window while the application is idle and waiting for input.

Enabling the Toolbar

To enable the toolbar, set enable_bottom_toolbar=True in the [cmd2.Cmd.init][] constructor:

class App(cmd2.Cmd):
    def __init__(self):
        super().__init__(enable_bottom_toolbar=True)

Customizing Toolbar Content

You can customize the content of the toolbar by overriding the [cmd2.Cmd.get_bottom_toolbar][] method.

from prompt_toolkit.formatted_text import AnyFormattedText


def get_bottom_toolbar(self) -> AnyFormattedText:
    return [
        ("ansigreen", "My Application Name"),
        ("", " - "),
        ("ansiyellow", "Current Status: Idle"),
    ]

Refreshing the Toolbar

Since the toolbar is rendered by prompt-toolkit as part of the prompt, it is naturally redrawn whenever the prompt is refreshed. If you want the toolbar to update automatically (for example, to display a clock), you can set refresh_interval in the [cmd2.Cmd.init][] constructor to a value greater than 0.0.

class App(cmd2.Cmd):
    def __init__(self):
        super().__init__(refresh_interval=0.5)

See the getting_started.py example for a demonstration of this technique.

!!! tip

If you want to show more realtime status information than fits in a toolbar, you can run your
`cmd2` application inside a [Textual](https://textual.textualize.io/) application, next to
widgets which display that information. See
[Embedding in Textual](../examples/embedding_in_textual.md).