CheckboxList & more Dialogs documentation

Squashed the following commits:

* Implement CheckboxList out of Checkbox
* Add styling reference sheet
* Document radiolist_dialog & checkboxlist_dialog
* Add standalone styled-checkboxlist example
* Add example on how to use the style sheet
* Fix typo: frame-label instead of frame.label, resulting in the style not beeing applied
* Prompt toolkit 3.0: update pages/dialogs.rst
* Apply suggestions

Author: gpotter2

docs/pages/dialogs.rst

@@ -19,7 +19,7 @@ simple message box. For instance:
 
     message_dialog(
         title='Example dialog window',
-        text='Do you want to continue?\nPress ENTER to quit.')
+        text='Do you want to continue?\nPress ENTER to quit.').run()
 
 .. image:: ../images/dialogs/messagebox.png
 
@@ -36,7 +36,7 @@ input box. It will return the user input as a string.
 
     text = input_dialog(
         title='Input dialog example',
-        text='Please type your name:')
+        text='Please type your name:').run()
 
 .. image:: ../images/dialogs/inputbox.png
 
@@ -58,13 +58,13 @@ confirmation dialog. It will return a boolean according to the selection.
 
     result = yes_no_dialog(
         title='Yes/No dialog example',
-        text='Do you want to confirm?')
+        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,
@@ -82,11 +82,54 @@ each providing the label (first) and return value if clicked (second).
             ('No', False),
             ('Maybe...', None)
         ],
-    )
+    ).run()
 
 .. image:: ../images/dialogs/button.png
 
 
+Radio list dialog
+-----------------
+
+The :func:`~prompt_toolkit.shortcuts.radiolist_dialog` functiom 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
 ------------------
 
@@ -103,7 +146,7 @@ dialogs to override the default style. Also, text can be styled by passing an
 
     example_style = Style.from_dict({
         'dialog':             'bg:#88ff88',
-        'dialog frame-label': 'bg:#ffffff #000000',
+        'dialog frame.label': 'bg:#ffffff #000000',
         'dialog.body':        'bg:#000000 #00ff00',
         'dialog shadow':      'bg:#00aa00',
     })
@@ -112,7 +155,116 @@ dialogs to override the default style. Also, text can be styled by passing an
         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)
+        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 explicitely 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``.
+Threfore 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()

examples/dialogs/checkbox_dialog.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+"""
+Example of a checkbox-list-based dialog.
+"""
+from __future__ import unicode_literals
+
+from prompt_toolkit.shortcuts import checkboxlist_dialog, message_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()
+if results:
+    message_dialog(
+        title="Room service",
+        text="You selected: %s\nGreat choice sir !" % ",".join(results)
+    ).run()
+else:
+    message_dialog("*starves*").run()

prompt_toolkit/shortcuts/__init__.py

@@ -1,5 +1,6 @@
 from .dialogs import (
     button_dialog,
+    checkboxlist_dialog,
     input_dialog,
     message_dialog,
     progress_dialog,
@@ -27,6 +28,7 @@
     'input_dialog',
     'message_dialog',
     'progress_dialog',
+    'checkboxlist_dialog',
     'radiolist_dialog',
     'yes_no_dialog',
     'button_dialog',

prompt_toolkit/shortcuts/dialogs.py

@@ -25,6 +25,7 @@
 from prompt_toolkit.widgets import (
     Box,
     Button,
+    CheckboxList,
     Dialog,
     Label,
     ProgressBar,
@@ -38,6 +39,7 @@
     'input_dialog',
     'message_dialog',
     'radiolist_dialog',
+    'checkboxlist_dialog',
     'progress_dialog',
 ]
 
@@ -189,6 +191,42 @@ def ok_handler() -> None:
     return _create_app(dialog, style)
 
 
+def checkboxlist_dialog(
+        title: AnyFormattedText = '',
+        text: AnyFormattedText = '',
+        ok_text: str = 'Ok',
+        cancel_text: str = 'Cancel',
+        values: Optional[List[Tuple[_T, AnyFormattedText]]] = None,
+        style: Optional[BaseStyle] = None) -> Application[_T]:
+    """
+    Display a simple list of element the user can choose multiple values amongst.
+
+    Several elements can be selected at a time using Arrow keys and Enter.
+    The focus can be moved between the list and the Ok/Cancel button with tab.
+    """
+    if values is None:
+        values = []
+
+    def ok_handler() -> None:
+        get_app().exit(result=cb_list.current_values)
+
+    cb_list = CheckboxList(values)
+
+    dialog = Dialog(
+        title=title,
+        body=HSplit([
+            Label(text=text, dont_extend_height=True),
+            cb_list,
+        ], padding=1),
+        buttons=[
+            Button(text=ok_text, handler=ok_handler),
+            Button(text=cancel_text, handler=_return_none),
+        ],
+        with_background=True)
+
+    return _create_app(dialog, style)
+
+
 def progress_dialog(
         title: AnyFormattedText = '',
         text: AnyFormattedText = '',

prompt_toolkit/widgets/__init__.py

@@ -10,6 +10,7 @@
     Box,
     Button,
     Checkbox,
+    CheckboxList,
     Frame,
     HorizontalLine,
     Label,
@@ -40,6 +41,7 @@
     'Box',
     'VerticalLine',
     'HorizontalLine',
+    'CheckboxList',
     'RadioList',
     'Checkbox',
     'ProgressBar',