Dialogs¶

Prompt_toolkit ships with a high level API for displaying dialogs, similar to the Whiptail program, but in pure Python.

Message box¶

Use the message_dialog() function to display a simple message box. For instance:

from prompt_toolkit.shortcuts import message_dialog

message_dialog(
    title='Example dialog window',
    text='Do you want to continue?\nPress ENTER to quit.').run()

Input box¶

The input_dialog() function can display an input box. It will return the user input as a string.

from prompt_toolkit.shortcuts import input_dialog

text = input_dialog(
    title='Input dialog example',
    text='Please type your name:').run()

The password=True option can be passed to the input_dialog() function to turn this into a password input box.

Yes/No confirmation dialog¶

The yes_no_dialog() function displays a yes/no confirmation dialog. It will return a boolean according to the selection.

from prompt_toolkit.shortcuts import yes_no_dialog

result = yes_no_dialog(
    title='Yes/No dialog example',
    text='Do you want to confirm?').run()

Button dialog¶

The button_dialog() function displays a dialog with choices offered as buttons. Buttons are indicated as a list of tuples, each providing the label (first) and return value if clicked (second).

from prompt_toolkit.shortcuts import button_dialog

result = button_dialog(
    title='Button dialog example',
    text='Do you want to confirm?',
    buttons=[
        ('Yes', True),
        ('No', False),
        ('Maybe...', None)
    ],
).run()

Radio list dialog¶

The radiolist_dialog() function displays a dialog with choices offered as a radio list. The values are provided as a list of tuples, each providing the return value (first element) and the displayed value (second element).

from prompt_toolkit.shortcuts import radiolist_dialog

result = radiolist_dialog(
    title="RadioList dialog",
    text="Which breakfast would you like ?",
    values=[
        ("breakfast1", "Eggs and beacon"),
        ("breakfast2", "French breakfast"),
        ("breakfast3", "Equestrian breakfast")
    ]
).run()

Checkbox list dialog¶

The checkboxlist_dialog() has the same usage and purpose than the Radiolist dialog, but allows several values to be selected and therefore returned.

from prompt_toolkit.shortcuts import checkboxlist_dialog

results_array = checkboxlist_dialog(
    title="CheckboxList dialog",
    text="What would you like in your breakfast ?",
    values=[
        ("eggs", "Eggs"),
        ("bacon", "Bacon"),
        ("croissants", "20 Croissants"),
        ("daily", "The breakfast of the day")
    ]
).run()

Styling of dialogs¶

A custom Style instance can be passed to all dialogs to override the default style. Also, text can be styled by passing an HTML object.

from prompt_toolkit.formatted_text import HTML
from prompt_toolkit.shortcuts import message_dialog
from prompt_toolkit.styles import Style

example_style = Style.from_dict({
    'dialog':             'bg:#88ff88',
    'dialog frame.label': 'bg:#ffffff #000000',
    'dialog.body':        'bg:#000000 #00ff00',
    'dialog shadow':      'bg:#00aa00',
})

message_dialog(
    title=HTML('<style bg="blue" fg="white">Styled</style> '
               '<style fg="ansired">dialog</style> window'),
    text='Do you want to continue?\nPress ENTER to quit.',
    style=example_style).run()

Styling reference sheet¶

In reality, the shortcut commands presented above build a full-screen frame by using a list of components. The two tables below allow you to get the classnames available for each shortcut, therefore you will be able to provide a custom style for every element that is displayed, using the method provided above.

Note

All the shortcuts use the Dialog component, therefore it isn’t specified explicitly below.

Shortcut	Components used
`yes_no_dialog`	`Label` `Button` (x2)
`button_dialog`	`Label` `Button`
`input_dialog`	`TextArea` `Button` (x2)
`message_dialog`	`Label` `Button`
`radiolist_dialog`	`Label` `RadioList` `Button` (x2)
`checkboxlist_dialog`	`Label` `CheckboxList` `Button` (x2)
`progress_dialog`	`Label` `TextArea` (locked) `ProgressBar`

Components	Available classnames
Dialog	`dialog` `dialog.body`
TextArea	`text-area` `text-area.prompt`
Label	`label`
Button	`button` `button.focused` `button.arrow` `button.text`
Frame	`frame` `frame.border` `frame.label`
Shadow	`shadow`
RadioList	`radio-list` `radio` `radio-checked` `radio-selected`
CheckboxList	`checkbox-list` `checkbox` `checkbox-checked` `checkbox-selected`
VerticalLine	`line` `vertical-line`
HorizontalLine	`line` `horizontal-line`
ProgressBar	`progress-bar` `progress-bar.used`

Example¶

Let’s customize the example of the checkboxlist_dialog.

It uses 2 Button, a CheckboxList and a Label, packed inside a Dialog. Therefore we can customize each of these elements separately, using for instance:

from prompt_toolkit.shortcuts import checkboxlist_dialog
from prompt_toolkit.styles import Style

results = checkboxlist_dialog(
    title="CheckboxList dialog",
    text="What would you like in your breakfast ?",
    values=[
        ("eggs", "Eggs"),
        ("bacon", "Bacon"),
        ("croissants", "20 Croissants"),
        ("daily", "The breakfast of the day")
    ],
    style=Style.from_dict({
        'dialog': 'bg:#cdbbb3',
        'button': 'bg:#bf99a4',
        'checkbox': '#e8612c',
        'dialog.body': 'bg:#a9cfd0',
        'dialog shadow': 'bg:#c98982',
        'frame.label': '#fcaca3',
        'dialog.body label': '#fd8bb6',
    })
).run()