diff options
Diffstat (limited to 'docs/pages/dialogs.rst')
| -rw-r--r-- | docs/pages/dialogs.rst | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/docs/pages/dialogs.rst b/docs/pages/dialogs.rst new file mode 100644 index 0000000..e171995 --- /dev/null +++ b/docs/pages/dialogs.rst @@ -0,0 +1,270 @@ +.. _dialogs: + +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 :func:`~prompt_toolkit.shortcuts.message_dialog` function to display a +simple message box. For instance: + +.. code:: python + + from prompt_toolkit.shortcuts import message_dialog + + message_dialog( + title='Example dialog window', + text='Do you want to continue?\nPress ENTER to quit.').run() + +.. image:: ../images/dialogs/messagebox.png + + +Input box +--------- + +The :func:`~prompt_toolkit.shortcuts.input_dialog` function can display an +input box. It will return the user input as a string. + +.. code:: python + + from prompt_toolkit.shortcuts import input_dialog + + text = input_dialog( + title='Input dialog example', + text='Please type your name:').run() + +.. image:: ../images/dialogs/inputbox.png + + +The ``password=True`` option can be passed to the +:func:`~prompt_toolkit.shortcuts.input_dialog` function to turn this into a +password input box. + + +Yes/No confirmation dialog +-------------------------- + +The :func:`~prompt_toolkit.shortcuts.yes_no_dialog` function displays a yes/no +confirmation dialog. It will return a boolean according to the selection. + +.. code:: python + + from prompt_toolkit.shortcuts import yes_no_dialog + + result = yes_no_dialog( + title='Yes/No dialog example', + text='Do you want to confirm?').run() + +.. image:: ../images/dialogs/confirm.png + + +Button dialog +------------- + +The :func:`~prompt_toolkit.shortcuts.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). + +.. code:: python + + 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() + +.. image:: ../images/dialogs/button.png + + +Radio list dialog +----------------- + +The :func:`~prompt_toolkit.shortcuts.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). + +.. code:: python + + 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 :func:`~prompt_toolkit.shortcuts.checkboxlist_dialog` has the same usage and purpose than the Radiolist dialog, but allows several values to be selected and therefore returned. + +.. code:: python + + 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 :class:`~prompt_toolkit.styles.Style` instance can be passed to all +dialogs to override the default style. Also, text can be styled by passing an +:class:`~prompt_toolkit.formatted_text.HTML` object. + + +.. code:: python + + 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() + +.. image:: ../images/dialogs/styled.png + +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: + +.. code:: python + + 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() |