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()

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 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Components |
Available classnames |
---|---|
Dialog |
|
TextArea |
|
Label |
|
Button |
|
Frame |
|
Shadow |
|
RadioList |
|
CheckboxList |
|
VerticalLine |
|
HorizontalLine |
|
ProgressBar |
|
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()