Visual-dialog 0.9

CONTRIBUTING.md

@@ -49,9 +49,6 @@ This tree does not contain a description of all the files in the repository, onl
 │   ├── source/
 │   │   Contains images used in documentation.
 │   │   │
-│   │   ├── images/
-│   │   │   Contains images used in documentation.
-│   │   │
 │   │   ├── conf.py
 │   │   │   Sphinx's configuration file.
 │   │   │
@@ -79,10 +76,16 @@ This tree does not contain a description of all the files in the repository, onl
 │   ├── __init__.py
 │   │
 │   ├── box.py
-│   │   Contains the parent class TextBox which serves as a basis for the implementation of the other classes.
+│   │   Contains the parent class BaseTextBox which serves as a basis for the implementation of the other classes.
 │   │
 │   ├── dialog.py
-│   │   Contains the DialogBox class, which is the main class of the library.
+│   │   Contains DialogBox class, which is the main class provides by the library.
+│   │
+│   ├── error.py
+│   │   Contains exceptions raised by the library.
+│   │
+│   ├── type.py
+│   │   Contains custom type hinting used by the library.
 │   │
 │   └── utils.py
 │       Contains the classes and functions used but not related to the libriarie.

README.md

@@ -69,7 +69,7 @@ pip install sphinx sphinx_rtd_theme
 
 ### Hello world with **Visual-dialog**
 
-```python3
+```py3
 import curses
 
 from visualdialog import DialogBox
@@ -84,8 +84,8 @@ def main(win):
     textbox = DialogBox(x, y,
                         height, width,
                         title="Demo")
-    textbox.char_by_char(win,
-                         "Hello world")
+    textbox.char_by_char("Hello world",
+                         win)
 
 
 curses.wrapper(main)
@@ -126,8 +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 **LGPL-3.0 License**. See [license](LICENSE) for more information.
 
 ## Acknowledgements
 

doc/source/api.rst

@@ -5,4 +5,5 @@ API documentation
   :maxdepth: 2
 
   visualdialog.rst
+  error.rst
   utils.rst

doc/source/conf.py

@@ -55,10 +55,6 @@
     "display_version": True
 }
 
-html_logo = "_static/visual-dialog.png"
-
-latex_logo = "_static/visual-dialog.png"
-
 latex_elements = {
     "pointsize": "12pt"
 }

doc/source/error.rst

@@ -0,0 +1,8 @@
+Exceptions
+==========
+
+**Visual-dialog** defined several exceptions raised by library. 
+
+.. autoexception:: visualdialog.error.ValueNotInBound
+
+.. autoexception:: visualdialog.error.PanicError

doc/source/faq.rst

@@ -18,5 +18,5 @@ You can use this behavior to perform multiple tasks while text scrolling.
 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``.
-Additionally, you can override the methods of ``DialogBox``.
+You can create your own derived class by inheriting from :class:`BaseTextBox`.
+Additionally, you can override the methods of :class:`DialogBox`.

doc/source/index.rst

@@ -20,7 +20,7 @@ Welcome to Visual-dialog's documentation
 - Text coloring and formatting.
 - Hackable and configurable.
 
-.. IMPORTANT::
+.. important::
    I recommend that you have some knowledge of Python ``curses`` module in order to use the library to its full potential.
 
    Here several links to learn ``curses``:
@@ -32,7 +32,7 @@ Getting started
 ---------------
 
 - **First steps:**
-- **Examples:** Many examples are available in the `repository <https://github.com/Tim-ats-d/Visual-dialog/issues>`_.
+- **Examples:** Many examples are available in the `repository <https://github.com/Tim-ats-d/Visual-dialog/tree/main/examples>`_.
 
 Getting help
 ------------

doc/source/installation.rst

@@ -6,12 +6,22 @@ Using PIP
 
 Install **Visual-dialog** using ``pip`` (The lib is not yet available on **pypi**):
 
-.. code-block::
+.. code-block:: text
 
   pip install git+git://github.com/Tim-ats-d/Visual-dialog
 
 or update library to the latest version:
 
-.. code-block::
+.. code-block:: text
 
   pip install git+git://github.com/Tim-ats-d/Visual-dialog --upgrade
+
+From source
+-----------
+
+.. code-block:: text
+
+  git clone https://github.com/Tim-ats-d/Visual-dialog.git
+  cd Visual-dialog
+  pip install .
+

doc/source/requirements.rst

@@ -12,9 +12,9 @@ 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**.
 
-To install ``curses`` on **Windows**, you need ``windows-curses`` module:
+To install ``curses`` on **Windows**, you need `windows-curses <https://pypi.org/project/windows-curses/>`_ module:
 
-.. code-block::
+.. code-block:: text
 
   pip install curses-windows
 
@@ -24,6 +24,6 @@ To build the documentation
 - `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::
+.. code-block:: text
 
   pip install sphinx sphinx_rtd_theme

doc/source/utils.rst

@@ -1,7 +1,7 @@
 Utils
 =====
 
-.. NOTE::
+.. note::
   A sub-module of **Visual-dialog** (``visualdialog.utils``) contains
   functions and classes used by the private API. The context manager
   ``TextAttr`` is used by the library to manage in a more
@@ -16,5 +16,10 @@ Utils
     visualdialog.function(args)
 
 
-.. automodule:: visualdialog.utils
-    :members:
+.. autoclass:: visualdialog.utils.TextAttr
+
+  .. automethod:: __init__
+
+  .. automethod:: __enter__
+
+  .. automethod:: __exit__

doc/source/visualdialog.rst

@@ -1,22 +1,43 @@
 Text boxes
 ==========
 
-.. IMPORTANT::
-  **Visual-dialog** contains two **modules**: ``visualdialog.box`` and ``visualdialog.dialog``.
-  These two **modules** are both imported when you import ``visualdialog``.
+.. important::
+  **Visual-dialog** provides two classes but only :class:`DialogBox` is destined to be instantiated.
 
-  Two **classes** are defined in these modules but only ``DialogBox`` is destined to be instantiated.
-
-TextBox
--------
+BaseTextBox
+-----------
 
 .. autoclass:: visualdialog.box.BaseTextBox
-    :members:
-    :undoc-members:
+
+  .. automethod:: __init__
+
+  The following methods are public:
+
+  .. autoproperty:: position
+
+  .. autoproperty:: dimensions
+
+  .. automethod:: framing_box
+
+  .. automethod:: get_input
 
 DialogBox
 ---------
 
 .. autoclass:: visualdialog.dialog.DialogBox
-    :undoc-members:
-    :members:
+
+  .. automethod:: __init__
+
+  The following methods are public:
+
+  .. automethod:: __repr__
+
+  .. automethod:: __enter__
+
+  .. automethod:: __exit__
+
+  .. automethod:: __lt__
+
+  .. automethod:: char_by_char
+
+  .. automethod:: word_by_word

examples/confrontation.py

@@ -2,34 +2,40 @@
 # A concrete example exploiting the possibilities of Visual-dialog.
 
 import curses
+from functools import partial
 
 from visualdialog import DialogBox
 
 
-PASS_KEYS = (" ", "\n")
-HEIGHT, WIDTH = 35, 6
+pass_keys = (" ", "\n")
+height, width = 35, 5
 
 
 # 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
+# complex applications (or an instance factory like here).
+def box_factory(win,
+                x: int,
+                y: int,
+                title: int,
+                title_colors_pair_nb: int,
+                **kwargs) -> DialogBox:
+    box = DialogBox(x, y,
+                    height, width,
+                    title, title_colors_pair_nb,
+                    global_win=win,
+                    # Use a default window to display text.
+                    # Setting this parameter allows to avoid passing `win`
+                    # parameter to `char_by_char` and `word_by_word` methods.
+                    # Useful when dealing with many `DialogBox` methods calls.
+                    **kwargs)
+
+    # Definition of accepted key codes to pass a dialog.
+    box.confirm_keys = pass_keys
+    # Definition of a partial objet to reduce verbosity and accelerate
+    # the time it takes to write the text on the screen.
+    box.char_by_char = partial(box.char_by_char, delay=30)
+
+    return box
 
 
 def main(win):
@@ -44,46 +50,44 @@ def main(win):
     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 = 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 !",
+    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 = box_factory(win,
+                                 left_x, bottom_y,
+                                 "Phoenix",  # Title of dialog box.
+                                 1)  # Color pair used to colored title.
+
+    april_may = box_factory(win,
+                            center_x, bottom_y,
+                            "April",
+                            2)
+
+    miles_edgeworth = box_factory(win,
+                                  right_x, bottom_y,
+                                  "Edgeworth",
+                                  3)
+
+    phoenix_wright.char_by_char("This testimony is a pure invention !",
                                 delay=30)
     # Set delay between writting each characters to 30 milliseconds
 
-    phoenix_wright.char_by_char(win,
-                                "You're lying April May !",
+    phoenix_wright.char_by_char("You're lying April May !",
                                 flash_screen=True,  # A short luminous glow will be displayed before writing the text.
                                 delay=30,
                                 text_attr=curses.A_BOLD)
 
-    april_may.char_by_char(win,
-                           "Arghh !",
+    april_may.char_by_char("Arghh !",
                            delay=30,
                            text_attr=curses.A_ITALIC)
 
-    miles_edgeworth.char_by_char(win,
-                                 "OBJECTION !",
+    miles_edgeworth.char_by_char("OBJECTION !",
                                  flash_screen=True,
                                  delay=30,
                                  text_attr=curses.A_BOLD)
 
-    miles_edgeworth.char_by_char(win,
-                                 "These accusations are irrelevant !",
+    miles_edgeworth.char_by_char("These accusations are irrelevant !",
                                  delay=30)
 
 

examples/context.py

@@ -21,8 +21,7 @@ def main(win):
         with DialogBox(1, 1,
                        30, 6) as db:
             db.confirm_keys.append("\n")  # To match enter key.
-            db.char_by_char(win,
-                            reply)
+            db.char_by_char(reply, win)
 
 
 # Execution of main function.

examples/monologue.py

@@ -34,8 +34,8 @@ def main(win):
     # Iterate on each sentence contained in replys.
     for reply in replys:
         textbox.char_by_char(
-            win,
             reply,
+            win,
             2,  # Display text colored with color pair 2.
             delay=40)  # Set delay between writting each characters to 40 milliseconds.