VIsual-dialog 0.8

Author: Tim-ats-d

CONTRIBUTING.md

@@ -17,7 +17,7 @@ Please push on the `dev` branch, any pull request on the `main` branch will be r
 
 When you make a pull request make sure to:
 
-* Test your code with `Python3.7` to be sure not to break compatability.
+* Test your code with `Python 3.8` to be sure not to break compatability.
 * Format your code according [PEP 8](https://www.python.org/dev/peps/pep-0008/). [PEP8 Check](https://github.com/quentinguidee/actions-pep8) will ensure that your code is correctly formatted .
 * Document your code with [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) if you add new functionality.
 

README.md

@@ -2,23 +2,11 @@
 # Visual-dialog
 
 <p align="center">
-  <a href="#features">Features</a> •
-  <a href="#installation">Installation</a> •
-  <a href="#requirements">Requirements</a> •
-  <a href="#documentation">Documentation</a> •
-  <a href="#quick-start">Quick start</a> •
-  <a href="#contributing">Contributing</a> •
-  <a href="#license">License</a>
-</p>
-
-<p align="center">
-  <img width="400" src="https://user-images.githubusercontent.com/59396366/100594532-188c6900-32fa-11eb-8372-4796f53b122f.png" alt="Visual-dialog">
+  <img width="300" src="https://user-images.githubusercontent.com/59396366/113866239-5f5d0480-97ad-11eb-879f-fa7d4098b689.png" alt="Visual-dialog">
   <br>
-  A library to make easier dialog box in terminal.
+  A library to make easier dialog box in a terminal.
 </p>
 
-This library is still under development. API can change.
-
 ## Features
 
 📃 Automatic text scrolling.
@@ -27,6 +15,8 @@ This library is still under development. API can change.
 
 ⚙️ Hackable and configurable.
 
+⚠️ This library is still under development. API can change.
+
 ## Installation
 
 ### Using pip
@@ -52,17 +42,29 @@ pip install .
 
 ## Requirements
 
+### Python version
+
+* [**Python 3.8**](https://www.python.org/downloads/) or more.
+
 ### Curses
 
 **Visual-dialog** works with `curses` Python module. It is available in the standard **Python** library on **UNIX** but it doesn’t work out-of-the-box on **Windows**.
 
-See [this explanations](https://www.devdungeon.com/content/curses-windows-python) to install `curses` on **Windows** (untested).
+To install `curses` on **Windows**, you need `windows-curses` module:
+
+```sh
+pip install curses-windows
+```
+
+### To build the documentation
 
-### Other requirements
-* [**Python 3.7**](https://www.python.org/downloads/) or more.
 * [**Sphinx**](https://www.sphinx-doc.org/en/master/usage/installation.html) to generate the documentation of library.
 * [**sphinx-rtd-theme**](https://pypi.org/project/sphinx-rtd-theme/) used as documentation theme.
 
+```sh
+pip install sphinx sphinx_rtd_theme
+```
+
 ## Quick-start
 
 ### Hello world with **Visual-dialog**
@@ -73,16 +75,16 @@ import curses
 from visualdialog import DialogBox
 
 
-x, y = (0, 0)
-height, width = (35, 6)
+x, y = 0, 0
+height, width = 35, 6
 
-def main(stdscr):
+def main(win):
     curses.curs_set(False)
 
     textbox = DialogBox(x, y,
                         height, width,
                         title="Demo")
-    textbox.char_by_char(stdscr,
+    textbox.char_by_char(win,
                          "Hello world")
 
 
@@ -124,7 +126,7 @@ You can also help by reporting **bugs**.
 
 ## License
 
-Distributed under the **GPL-2.0 License** . See [license](LICENSE) for more information.
+Distributed under the **GPL-2.0 License**. See [license](LICENSE) for more information.
 
 
 ## Acknowledgements

doc/source/_static/visual-dialog.png

@@ -11,13 +11,11 @@ See the `dedicated example <https://github.com/Tim-ats-d/Visual-dialog/tree/main
 How can I continue to manage screen display while a DialogBox is writing text on the screen?
 --------------------------------------------------------------------------------------------
 
-``char_by_char`` and ``word_by_word`` methods of ``DialogBox`` class accept a callback in parameter.
-You can also pass arguments to this callback via ``cargs`` parameter.
+``char_by_char`` and ``word_by_word`` methods of ``DialogBox`` class accept a ``callbacks`` in parameter.
+It must be a function iterable.
+You can use this behavior to perform multiple tasks while text scrolling.
 
-The past callback is executed after downtime delay between character or word display.
-You can use this behavior to perform multiple tasks while ``DialogBox`` scrolling.
-
-I am not satisfied with the behavior of DialogBox, how can I change it? 
+I am not satisfied with the behavior of DialogBox, how can I change it?
 -----------------------------------------------------------------------
 
 You can create your own derived class by inheriting from ``BaseTextBox``.

doc/source/faq.rst

@@ -11,12 +11,14 @@ Welcome to Visual-dialog's documentation
 
 .. image:: _static/visual-dialog.png
    :align: center
+   :width: 300
+   :alt: Visual-dialog
 
 **Features:**
 
-   - Automatic text scrolling.
-   - Text coloring and formatting.
-   - Hackable and configurable.
+- Automatic text scrolling.
+- Text coloring and formatting.
+- Hackable and configurable.
 
 .. IMPORTANT::
    I recommend that you have some knowledge of Python ``curses`` module in order to use the library to its full potential.

doc/source/index.rst

@@ -4,10 +4,14 @@ Installation
 Using PIP
 ---------
 
-Install **Visual-dialog** using ``pip`` (The lib is not yet available on **pypi**)::
+Install **Visual-dialog** using ``pip`` (The lib is not yet available on **pypi**):
 
-  python3 -m pip install git+git://github.com/Tim-ats-d/Visual-dialog
+.. code-block::
 
-or update library to the latest version::
+  pip install git+git://github.com/Tim-ats-d/Visual-dialog
 
-  python3 -m pip install git+git://github.com/Tim-ats-d/Visual-dialog --upgrade
+or update library to the latest version:
+
+.. code-block::
+
+  pip install git+git://github.com/Tim-ats-d/Visual-dialog --upgrade

doc/source/installation.rst

@@ -1,19 +1,29 @@
 Requirements
 ============
 
+Python version
+--------------
+
+- `Python 3.8 or more <https://www.python.org/downloads/>`_.
+
 Curses
 ------
 
 **Visual-dialog** works with ``curses`` Python module.
 It is available in the standard **Python** library on **UNIX** but it doesn't work out-of-the-box on **Windows**.
 
-See this explanations to install ``curses`` on **Windows** (untested).
+To install ``curses`` on **Windows**, you need ``windows-curses`` module:
+
+.. code-block::
 
-- https://www.devdungeon.com/content/curses-windows-python
+  pip install curses-windows
 
-Other requirements
-------------------
+To build the documentation
+--------------------------
 
-- **Python 3.7** or more.
 - `Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`_ to generate the documentation of library.
 - `sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`_ used as documentation theme.
+
+.. code-block::
+
+  pip install sphinx sphinx_rtd_theme

doc/source/requirements.rst

@@ -4,7 +4,7 @@ Utils
 .. NOTE::
   A sub-module of **Visual-dialog** (``visualdialog.utils``) contains
   functions and classes used by the private API. The context manager
-  ``TextAttributes`` is used by the library to manage in a more
+  ``TextAttr`` is used by the library to manage in a more
   pythonic way the textual ``curses`` attributes curses but you can
   also use it in your programs.
 

doc/source/utils.rst

@@ -3,22 +3,26 @@
 This directory contains several examples of use of **Visual-dialog**.
 They are classified below by order of difficulty (approximately).
 
-## [Monologue](monologue.py)
+## [`Monologue`](monologue.py)
 
 A complete concrete example of how to use **Visual-dialog**.
 
-## [Word](word.py)
+## [`Word`](word.py)
 
 An example of using ``word_by_word`` method from text boxes.
 
-## [Text attributes](text_attributes.py)
+## [`Text attributes`](text_attributes.py)
 
-An example showing the possibilities of text formatting in a text box.
+An example showing the possibilities of **text formatting** in a text box.
 
-## [Context](contex.py)
+## [`Panic`](panic.py)
+
+An example of the use of **panic keys**.
+
+## [`Context`](context.py)
 
 An example of how to use a text box as a **context manager**.
 
-## [Confrontation](confrontation.py)
+## [`Confrontation`](confrontation.py)
 
 A concrete example exploiting the possibilities of library.

examples/README.md

@@ -6,73 +6,85 @@
 from visualdialog import DialogBox
 
 
-# Definition of curses key constants.
-# 10 and 32 correspond to enter and space keys.
-PASS_DIALOG_KEY = (10, 32)
-
-
-def main(stdscr):
-    # Makes the cursor invisible.
+PASS_KEYS = (" ", "\n")
+HEIGHT, WIDTH = 35, 6
+
+
+# It is preferable to create its own class derived from DialogBox for
+# complex applications.
+class CustomDialogBox(DialogBox):
+
+    def __init__(self,
+                 pos_x: int,
+                 pos_y: int,
+                 title: str,
+                 title_colors_pair_nb: int,
+                 **kwargs):
+        super().__init__(pos_x=pos_x,
+                         pos_y=pos_y,
+                         height=HEIGHT,
+                         width=WIDTH,
+                         title=title,
+                         title_colors_pair_nb=title_colors_pair_nb,
+                         **kwargs)
+
+        # Definition of accepted key codes to pass a dialog.
+        self.confirm_keys = PASS_KEYS
+
+
+def main(win):
+    # Make the cursor invisible.
     curses.curs_set(False)
 
     # Definition of several colors pairs.
-    curses.init_pair(1, curses.COLOR_BLUE, curses.COLOR_BLACK)
-    curses.init_pair(2, curses.COLOR_MAGENTA, curses.COLOR_BLACK)
-    curses.init_pair(3, curses.COLOR_RED, curses.COLOR_BLACK)
+    curses.init_pair(1, curses.COLOR_BLUE, 0)
+    curses.init_pair(2, curses.COLOR_MAGENTA, 0)
+    curses.init_pair(3, curses.COLOR_RED, 0)
 
-    width, height  = 6, 35  # Width and height (in character).
-
-    max_y, max_x = stdscr.getmaxyx()
+    max_y, max_x = win.getmaxyx()  # Get height and width of the window.
 
     left_x = 2  # Left alignment.
-    right_x = max_x - height - 4 # Calculation of right alignment.
-    center_x = max_x//2 - height//2  # Calculation of center alignment.
-    bottom_y = max_y - width - 4  # Calculation of bottom alignment.
-
-    phoenix_wright = DialogBox(left_x, bottom_y,
-                               height, width,
-                               title="Phoenix",
-                               title_colors_pair_nb=1)  # Title and color_pair used to colored title.
-
-    april_may = DialogBox(center_x, bottom_y,
-                          height, width,
-                          title="April",
-                          title_colors_pair_nb=2)
-
-    miles_edgeworth = DialogBox(right_x, bottom_y,
-                                height, width,
-                                title="Edgeworth",
-                                title_colors_pair_nb=3)
-
-    # Definition of accepted key codes to pass a dialog.
-    phoenix_wright.confirm_dialog_key = PASS_DIALOG_KEY
-    april_may.confirm_dialog_key = PASS_DIALOG_KEY
-    miles_edgeworth.confirm_dialog_key = PASS_DIALOG_KEY
-
-    phoenix_wright.char_by_char(stdscr,
+    right_x = max_x - HEIGHT - 4  # Calculation of right alignment.
+    center_x = max_x//2 - HEIGHT//2  # Calculation of center alignment.
+    bottom_y = max_y - WIDTH - 4  # Calculation of bottom alignment.
+
+    phoenix_wright = CustomDialogBox(left_x, bottom_y,
+                                     "Phoenix",  # Title of dialog box.
+                                     1)  # Color pair used to colored title.
+
+    april_may = CustomDialogBox(center_x, bottom_y,
+                                "April",
+                                2)
+
+    miles_edgeworth = CustomDialogBox(right_x, bottom_y,
+                                      "Edgeworth",
+                                      3)
+
+    phoenix_wright.char_by_char(win,
                                 "This testimony is a pure invention !",
-                                delay=0.03)  # Set delay between writting each characters to 0.03 seconde.
+                                delay=30)
+    # Set delay between writting each characters to 30 milliseconds
 
-    phoenix_wright.char_by_char(stdscr,
+    phoenix_wright.char_by_char(win,
                                 "You're lying April May !",
                                 flash_screen=True,  # A short luminous glow will be displayed before writing the text.
-                                delay=0.03,
+                                delay=30,
                                 text_attr=curses.A_BOLD)
 
-    april_may.char_by_char(stdscr,
+    april_may.char_by_char(win,
                            "Arghh !",
-                           delay=0.02,
+                           delay=30,
                            text_attr=curses.A_ITALIC)
 
-    miles_edgeworth.char_by_char(stdscr,
+    miles_edgeworth.char_by_char(win,
                                  "OBJECTION !",
                                  flash_screen=True,
-                                 delay=0.03,
+                                 delay=30,
                                  text_attr=curses.A_BOLD)
 
-    miles_edgeworth.char_by_char(stdscr,
+    miles_edgeworth.char_by_char(win,
                                  "These accusations are irrelevant !",
-                                 delay=0.03)
+                                 delay=30)
 
 
 # Execution of main function.