Add DialogBoxglobal_win instance attribute. Fix doc and examples accordingly.

Author: Tim-ats-d

doc/source/index.rst

@@ -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
 ------------

examples/confrontation.py

@@ -7,26 +7,34 @@
 
 
 PASS_KEYS = (" ", "\n")
-HEIGHT, WIDTH = 37, 7
+HEIGHT, WIDTH = 35, 5
 
 
 # It is preferable to create its own class derived from DialogBox for
 # complex applications.
 class CustomDialogBox(DialogBox):
 
     def __init__(self,
+                 win,
                  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)
+        DialogBox.__init__(self,
+                           pos_x,
+                           pos_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.
         self.confirm_keys = PASS_KEYS
@@ -48,42 +56,40 @@ def main(win):
     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_wright = CustomDialogBox(win,
+                                     left_x, bottom_y,
                                      "Phoenix",  # Title of dialog box.
                                      1)  # Color pair used to colored title.
 
-    april_may = CustomDialogBox(center_x, bottom_y,
+    april_may = CustomDialogBox(win,
+                                center_x, bottom_y,
                                 "April",
                                 2)
 
-    miles_edgeworth = CustomDialogBox(right_x, bottom_y,
+    miles_edgeworth = CustomDialogBox(win,
+                                      right_x, bottom_y,
                                       "Edgeworth",
                                       3)
 
-    phoenix_wright.char_by_char(win,
-                                "This testimony is a pure invention !",
+    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.
 

examples/panic.py

@@ -17,22 +17,20 @@ def main(win):
     box.panic_keys = ("q", )
 
     try:
-        box.char_by_char(win,
-                            "When a key contained in EXIT_KEY has been "
-                            "pressed at end of dialog PanicError "
-                            "exception is raised.")
+        box.char_by_char("When a key contained in EXIT_KEY is pressed "
+                         "at end of dialog PanicError exception is raised.",
+                         win)
     except PanicError:  # Catch PanicError.
-        box.char_by_char(win,
-                         "PanicError exception has been caught. "
+        box.char_by_char("PanicError exception has been caught. "
                          "One of the keys contained in EXIT_CHAR has "
-                         "been pressed.")
+                         "been pressed.",
+                         win)
     else:
-        box.char_by_char(win,
-                         "None of the keys contained in EXIT_CHAR have "
-                         "been pressed.")
+        box.char_by_char("None of the keys contained in EXIT_CHAR have "
+                         "been pressed.",
+                         win)
     finally:  # Code executed in all cases.
-        box.char_by_char(win,
-                         "End of dialog.")
+        box.char_by_char("End of dialog.", win)
 
 
 # Execution of main function.

examples/text_attributes.py

@@ -41,8 +41,8 @@ def main(win):
     textbox.confirm_keys = PASS_KEYS
 
     for text, attributes in sentences.items():
-        textbox.char_by_char(win,
-                             text,
+        textbox.char_by_char(text,
+                             win,
                              2,  # Display text colored with color pair 2.
                              attributes)  # Pass attributes to text.
 

examples/word.py

@@ -27,8 +27,8 @@ def main(win):
 
     # Iterate on each sentence contained in instructions.
     for instruction in instructions:
-        textbox.word_by_word(win,
-                             instruction,
+        textbox.word_by_word(instruction,
+                             win,
                              delay=200)
         # Set delay between writting each words to 200 milliseconds.
 

visualdialog/box.py

@@ -6,7 +6,7 @@
 import curses
 import curses.textpad
 import functools
-from typing import Callable, List, Literal, Optional, Sequence, Tuple, Union
+from typing import Callable, List, Literal, Sequence, Tuple, Union
 
 from .error import PanicError, ValueNotInBound
 from .type import CursesKey, CursesTextAttribute, CursesTextAttributes, CursesWindow
@@ -102,7 +102,7 @@ def __init__(
             pos_y: int,
             height: int,
             width: int,
-            title: Optional[str] = None,
+            title: str = "",
             title_colors_pair_nb: int = 0,
             title_text_attr: Union[CursesTextAttribute,
                                    CursesTextAttributes] = curses.A_BOLD,