feat: dedicated instruction area (tips). #7

InquirerPy/base/complex.py

@@ -58,6 +58,7 @@ def __init__(
         qmark: str = "?",
         amark: str = "?",
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         validate: Union[Callable[[Any], bool], Validator] = None,
@@ -91,11 +92,14 @@ def __init__(
         self._application: Application
         self._spinner_enable = spinner_enable
         self._set_exception_handler = set_exception_handler
+        self._tips = tips
+        self._display_tips = True if tips else False
 
         self._is_vim_edit = Condition(lambda: self._editing_mode == EditingMode.VI)
         self._is_invalid = Condition(lambda: self._invalid)
         self._is_loading = Condition(lambda: self.loading)
         self._is_spinner_enable = Condition(lambda: self._spinner_enable)
+        self._is_displaying_tips = Condition(lambda: self._display_tips)
 
         self._spinner = SpinnerWindow(
             loading=self._is_loading & self._is_spinner_enable,

InquirerPy/base/list.py

@@ -33,6 +33,7 @@ def __init__(
         qmark: str = "?",
         amark: str = "?",
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         validate: Union[Callable[[Any], bool], Validator] = None,
@@ -59,6 +60,7 @@ def __init__(
             invalid_message=invalid_message,
             validate=validate,
             instruction=instruction,
+            tips=tips,
             wrap_lines=wrap_lines,
             spinner_enable=spinner_enable,
             spinner_pattern=spinner_pattern,
@@ -87,6 +89,7 @@ def __init__(
                 {"key": "c-p", "filter": ~self._is_vim_edit},
                 {"key": "k", "filter": self._is_vim_edit},
             ],
+            "toggle-tips": [{"key": "alt-t"}],
             "toggle": [
                 {"key": "space", "filter": self._is_multiselect},
             ],
@@ -109,6 +112,7 @@ def __init__(
         self.kb_func_lookup = {
             "down": [{"func": self._handle_down}],
             "up": [{"func": self._handle_up}],
+            "toggle-tips": [{"func": self._toggle_tips}],
             "toggle": [{"func": self._toggle_choice}],
             "toggle-down": [{"func": self._toggle_choice}, {"func": self._handle_down}],
             "toggle-up": [{"func": self._toggle_choice}, {"func": self._handle_up}],
@@ -239,6 +243,11 @@ def _handle_up(self) -> bool:
                 return True
             return False
 
+    def _toggle_tips(self) -> None:
+        """Toggle tips display."""
+        if self._tips:
+            self._display_tips = not self._display_tips
+
     @abstractmethod
     def _toggle_choice(self) -> None:
         """Handle event when user attempting to toggle the state of the chocie."""

InquirerPy/containers/tips.py

@@ -0,0 +1,36 @@
+"""Module contains :class:`.TipsWindow` which can be used to display additional tips/instructions."""
+
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.layout.containers import ConditionalContainer, Window
+from prompt_toolkit.layout.controls import FormattedTextControl
+
+if TYPE_CHECKING:
+    from prompt_toolkit.filters.base import FilterOrBool
+    from prompt_toolkit.formatted_text.base import AnyFormattedText
+
+
+class TipsWindow(ConditionalContainer):
+    """Conditional `prompt_toolkit` :class:`~prompt_toolkit.layout.Window` that displays tips/instructions.
+
+    Args:
+        message: Tips to display.
+        filter: Condition to display the tips window.
+    """
+
+    def __init__(self, message: str, filter: "FilterOrBool") -> None:
+        self._message = message
+        super().__init__(
+            Window(
+                FormattedTextControl(text=self._get_message), dont_extend_height=True
+            ),
+            filter=filter,
+        )
+
+    def _get_message(self) -> "AnyFormattedText":
+        """Get tips to display.
+
+        Returns:
+            FormattedText in list of tuple format.
+        """
+        return [("class:instruction", self._message)]

InquirerPy/prompts/checkbox.py

@@ -99,6 +99,7 @@ class CheckboxPrompt(ListPrompt):
         enabled_symbol: Custom symbol which indicate the checkbox is ticked.
         disabled_symbol: Custom symbol which indicate the checkbox is not ticked.
         instruction: Short instruction to display next to the `message`.
+        tips: Long instructions or tips to display in a floating window at the bottom.
         validate: Validation callable or class to validate user input.
         invalid_message: Error message to display when input is invalid.
         transformer: A callable to transform the result that gets printed in the terminal.
@@ -137,6 +138,7 @@ def __init__(
         enabled_symbol: str = "%s " % INQUIRERPY_FILL_HEX_SEQUENCE,
         disabled_symbol: str = "%s " % INQUIRERPY_EMPTY_HEX_SEQUENCE,
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         height: Union[int, str] = None,
@@ -170,6 +172,7 @@ def __init__(
             qmark=qmark,
             amark=amark,
             instruction=instruction,
+            tips=tips,
             transformer=transformer,
             filter=filter,
             height=height,

InquirerPy/prompts/expand.py

@@ -167,6 +167,7 @@ class ExpandPrompt(ListPrompt):
         amark: Custom symbol that will be displayed infront of the question after its answered.
         pointer: Custom symbol that will be used to indicate the current choice selection.
         instruction: Short instruction to display next to the `message`.
+        tips: Long instructions or tips to display in a floating window at the bottom.
         validate: Validation callable or class to validate user input.
         invalid_message: Error message to display when input is invalid.
         transformer: A callable to transform the result that gets printed in the terminal.
@@ -208,6 +209,7 @@ def __init__(
         help_msg: str = "Help, list all choices",
         expand_pointer: str = "%s " % INQUIRERPY_POINTER_SEQUENCE,
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         height: Union[int, str] = None,
@@ -248,6 +250,7 @@ def __init__(
             qmark=qmark,
             amark=amark,
             instruction=instruction,
+            tips=tips,
             transformer=transformer,
             filter=filter,
             height=height,

InquirerPy/prompts/fuzzy.py

@@ -26,6 +26,7 @@
 from InquirerPy.base import FakeDocument, InquirerPyUIListControl
 from InquirerPy.base.list import BaseListPrompt
 from InquirerPy.containers.message import MessageWindow
+from InquirerPy.containers.tips import TipsWindow
 from InquirerPy.containers.validation import ValidationWindow
 from InquirerPy.enum import INQUIRERPY_POINTER_SEQUENCE
 from InquirerPy.exceptions import InvalidArgument
@@ -254,6 +255,7 @@ class FuzzyPrompt(BaseListPrompt):
         amark: Custom symbol that will be displayed infront of the question after its answered.
         pointer: Custom symbol that will be used to indicate the current choice selection.
         instruction: Short instruction to display next to the `message`.
+        tips: Long instructions or tips to display in a floating window at the bottom.
         validate: Validation callable or class to validate user input.
         invalid_message: Error message to display when input is invalid.
         transformer: A callable to transform the result that gets printed in the terminal.
@@ -296,6 +298,7 @@ def __init__(
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         instruction: str = "",
+        tips: str = "",
         multiselect: bool = False,
         prompt: str = INQUIRERPY_POINTER_SEQUENCE,
         marker: str = INQUIRERPY_POINTER_SEQUENCE,
@@ -341,6 +344,7 @@ def __init__(
             invalid_message=invalid_message,
             multiselect=multiselect,
             instruction=instruction,
+            tips=tips,
             keybindings=keybindings,
             cycle=cycle,
             wrap_lines=wrap_lines,
@@ -415,14 +419,22 @@ def __init__(
                     ]
                 ),
                 floats=[
+                    Float(
+                        content=TipsWindow(
+                            message=self._tips,
+                            filter=self._is_displaying_tips & ~IsDone(),
+                        ),
+                        left=0,
+                        bottom=0,
+                    ),
                     Float(
                         content=ValidationWindow(
                             invalid_message=self._get_error_message,
                             filter=self._is_invalid & ~IsDone(),
                         ),
                         left=0,
                         bottom=0,
-                    )
+                    ),
                 ],
             )
         )

InquirerPy/prompts/list.py

@@ -19,6 +19,7 @@
 from InquirerPy.base.complex import FakeDocument
 from InquirerPy.base.list import BaseListPrompt
 from InquirerPy.containers.message import MessageWindow
+from InquirerPy.containers.tips import TipsWindow
 from InquirerPy.containers.validation import ValidationWindow
 from InquirerPy.enum import INQUIRERPY_POINTER_SEQUENCE
 from InquirerPy.separator import Separator
@@ -102,6 +103,7 @@ class ListPrompt(BaseListPrompt):
         amark: Custom symbol that will be displayed infront of the question after its answered.
         pointer: Custom symbol that will be used to indicate the current choice selection.
         instruction: Short instruction to display next to the `message`.
+        tips: Long instructions or tips to display in a floating window at the bottom.
         validate: Validation callable or class to validate user input.
         invalid_message: Error message to display when input is invalid.
         transformer: A callable to transform the result that gets printed in the terminal.
@@ -140,6 +142,7 @@ def __init__(
         amark: str = "?",
         pointer: str = INQUIRERPY_POINTER_SEQUENCE,
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         height: Union[int, str] = None,
@@ -177,6 +180,7 @@ def __init__(
             qmark=qmark,
             amark=amark,
             instruction=instruction,
+            tips=tips,
             transformer=transformer,
             filter=filter,
             validate=validate,
@@ -225,14 +229,22 @@ def __init__(
                 ]
             ),
             floats=[
+                Float(
+                    content=TipsWindow(
+                        message=self._tips,
+                        filter=self._is_displaying_tips & ~IsDone(),
+                    ),
+                    left=0,
+                    bottom=0,
+                ),
                 Float(
                     content=ValidationWindow(
                         invalid_message=self._get_error_message,
                         filter=self._is_invalid & ~IsDone(),
                     ),
                     left=0,
                     bottom=0,
-                )
+                ),
             ],
         )
 

InquirerPy/prompts/rawlist.py

@@ -121,6 +121,7 @@ class RawlistPrompt(ListPrompt):
         amark: Custom symbol that will be displayed infront of the question after its answered.
         pointer: Custom symbol that will be used to indicate the current choice selection.
         instruction: Short instruction to display next to the `message`.
+        tips: Long instructions or tips to display in a floating window at the bottom.
         validate: Validation callable or class to validate user input.
         invalid_message: Error message to display when input is invalid.
         transformer: A callable to transform the result that gets printed in the terminal.
@@ -160,6 +161,7 @@ def __init__(
         amark: str = "?",
         pointer: str = " ",
         instruction: str = "",
+        tips: str = "",
         transformer: Callable[[Any], Any] = None,
         filter: Callable[[Any], Any] = None,
         height: Union[int, str] = None,
@@ -198,6 +200,7 @@ def __init__(
             qmark=qmark,
             amark=amark,
             instruction=instruction,
+            tips=tips,
             transformer=transformer,
             filter=filter,
             height=height,

InquirerPy/utils.py

@@ -101,7 +101,7 @@ def get_style(
             "input": os.getenv("INQUIRERPY_STYLE_INPUT", "#98c379"),
             "question": os.getenv("INQUIRERPY_STYLE_QUESTION", ""),
             "answered_question": os.getenv("INQUIRERPY_STYLE_ANSWERED_QUESTION", ""),
-            "instruction": os.getenv("INQUIRERPY_STYLE_INSTRUCTION", ""),
+            "instruction": os.getenv("INQUIRERPY_STYLE_INSTRUCTION", "#abb2bf"),
             "pointer": os.getenv("INQUIRERPY_STYLE_POINTER", "#61afef"),
             "checkbox": os.getenv("INQUIRERPY_STYLE_CHECKBOX", "#98c379"),
             "separator": os.getenv("INQUIRERPY_STYLE_SEPARATOR", ""),