Docs.

Author: jonathanslenders

docs/index.rst

@@ -69,6 +69,7 @@ Table of contents
    pages/upgrading/index
    pages/printing_text
    pages/asking_for_input
+   pages/choice_prompts
    pages/dialogs
    pages/progress_bars
    pages/full_screen_apps

docs/pages/choice_prompts.rst

@@ -0,0 +1,103 @@
+.. _asking_for_input:
+
+Asking for a choice
+===================
+
+Similar to how the :func:`~prompt_toolkit.shortcuts.prompt` function allows for
+text input, prompt_toolkit has a
+:func:`~prompt_toolkit.shortcuts.prompt_choice` function to ask for a choice
+from a list of options:
+
+.. code:: python
+
+    from prompt_toolkit.shortcuts import prompt_choice
+
+    result = prompt_choice(
+        message="Please choose a dish",
+        options=[
+            ("pizza", "Pizza with mushrooms"),
+            ("salad", "Salad with tomatoes"),
+            ("sushi", "Sushi"),
+        ],
+        default="salad",
+    )
+
+    print(f"You have chosen: {text}")
+
+
+Coloring the options
+--------------------
+
+Similar to text input prompts, it is possible to customize the colors and
+styles. The ``message`` parameter takes any :ref:`formatted text
+<formatted_text>`, and the labels (2nd argument of the options) can also be
+:ref:`formatted text <formatted_text>`. Further, we can pass a
+:class:`~prompt_toolkit.styles.Style` instance using the
+:meth:`~prompt_toolkit.styles.Style.from_dict` function:
+
+.. code:: python
+
+    from __future__ import annotations
+
+    from prompt_toolkit.formatted_text import HTML
+    from prompt_toolkit.shortcuts import prompt_choice
+    from prompt_toolkit.styles import Style
+
+    style = Style.from_dict(
+        {
+            "input-selection": "fg:#ff0000",
+            "number": "fg:#884444 bold",
+            "selected-option": "underline",
+            "frame.border": "#884444",
+        }
+    )
+
+    result = prompt_choice(
+        message=HTML("<u>Please select a dish</u>:"),
+        options=[
+            ("pizza", "Pizza with mushrooms"),
+            (
+                "salad",
+                HTML("<ansigreen>Salad</ansigreen> with <ansired>tomatoes</ansired>"),
+            ),
+            ("sushi", "Sushi"),
+        ],
+        style=style,
+    )
+    print(result)
+
+
+Adding a frame
+--------------
+
+The :func:`~prompt_toolkit.shortcuts.prompt_choice` function takes a
+``show_frame`` argument. When set to ``True``, the options will be shown
+inside a frame. It is also possible to pass a :ref:`filter <filters>`, like
+``~is_done``, so that the frame is only displayed when asking for input, but
+hidden once the input is accepted.
+
+.. code:: python
+
+    from prompt_toolkit.shortcuts import prompt_choice
+    from prompt_toolkit.filters import is_done
+    from prompt_toolkit.styles import Style
+
+    style = Style.from_dict(
+        {
+            "frame.border": "#884444",
+            "selected-option": "bold underline",
+        }
+    )
+    result = prompt_choice(
+        message="Please select a dish:",
+        options=[
+            ("pizza", "Pizza with mushrooms"),
+            ("salad", "Salad with tomatoes"),
+            ("sushi", "Sushi"),
+        ],
+        style=style,
+        show_frame=~is_done,
+    )
+    print(result)
+
+