Rename argument stdscr to win, add CursesWindow, fix bug occured during instantiation of DialogBox, improve documentation.

Author: Tim-ats-d

doc/source/faq.rst

@@ -16,3 +16,9 @@ You can also pass arguments to this callback via ``cargs`` parameter.
 
 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? 
+-----------------------------------------------------------------------
+
+You can create your own derived class by inheriting from ``BaseTextBox``.
+Additionally, you can override the methods of ``DialogBox``.

doc/source/utils.rst

@@ -16,5 +16,5 @@ Utils
     visualdialog.function(args)
 
 
-.. autoclass:: visualdialog.utils.TextAttributes
+.. automodule:: visualdialog.utils
     :members:

doc/source/visualdialog.rst

@@ -13,14 +13,10 @@ TextBox
 .. autoclass:: visualdialog.box.BaseTextBox
     :members:
     :undoc-members:
-    :private-members:
 
 DialogBox
 ---------
 
 .. autoclass:: visualdialog.dialog.DialogBox
-    :special-members:
     :undoc-members:
     :members:
-    :private-members:
-

visualdialog/box.py

@@ -29,6 +29,7 @@
                     CursesKeyConstants,
                     CursesTextAttributesConstant,
                     CursesTextAttributesConstants,
+                    CursesWindow,
                     Numeric,
                     TextAttributes)
 
@@ -38,7 +39,6 @@ class PanicError(Exception):
     pressed.
 
     :param key: Key pressed that caused the exception to be thrown.
-    :type key: CursesKeyConstants
     """
     def __init__(self,
                  key: CursesKeyConstant):
@@ -52,54 +52,45 @@ class BaseTextBox:
     """This class provides attributs and methods to manage a text box.
 
     .. NOTE::
-        This class provides a general API for text boxes, it does not
-        need to be instantiated.
+        This class provides a general API for text boxes, it is not
+         intended to be instantiated.
 
     :param pos_x: x position of the dialog box in ``curses`` window
         object on which methods will have effects.
-    :type pos_x: int
 
     :param pos_y: y position of the dialog box in ``curses`` window
         object on which methods will have effects.
-    :type pos_y: int
 
     :param length: Length of the dialog box in ``curses`` window object
         on which methods will have effects.
-    :type length: int
 
     :param width: Width of the dialog box in ``curses`` window object on
         which methods will have effects.
-    :type width: int
 
     :param title: String that will be displayed in the upper left corner
         of dialog box.
         If title is an empty string, the title will not be displayed.
         This defaults an empty string.
-    :type title: str
 
     :param title_colors_pair_nb:
         Number of the curses color pair that will be used to color the
         title. Zero corresponding to the pair of white color on black
         background initialized by ``curses``). This defaults to ``0``.
-    :type title_colors_pair_nb: int
 
     :param title_text_attr:
         Dialog box title text attributes. It should be a single curses
         text attribute or a tuple of curses text attribute. This
         defaults to ``curses.A_BOLD``.
-    :type title_text_attr: Union[CursesTextAttributesConstant,CursesTextAttributesConstants]
 
     :param downtime_chars:
         List of characters that will trigger a ``downtime_chars_delay``
         time second between the writing of each character.
         This defaults to ``(",", ".", ":", ";", "!", "?")``.
-    :type downtime_chars: Union[tuple[str],list[str]]
 
     :param downtime_chars_delay:
         Waiting time in seconds after writing a character contained in
         ``downtime_chars``.
         This defaults to ``0.6``.
-    :type downtime_chars_delay: Numeric
     """
 
     def __init__(
@@ -111,9 +102,9 @@ def __init__(
         title: str = "",
         title_colors_pair_nb: int = 0,
         title_text_attr: Union[CursesTextAttributesConstant,
-                               CursesTextAttributesConstants] = curses.A_BOLD,
+                            CursesTextAttributesConstants] = curses.A_BOLD,
         downtime_chars: Union[Tuple[str],
-                              List[str]] = (",", ".", ":", ";", "!", "?"),
+                            List[str]] = (",", ".", ":", ";", "!", "?"),
         downtime_chars_delay: Numeric = .6):
         self.pos_x, self.pos_y = pos_x, pos_y
         self.length, self.width = length, width
@@ -142,16 +133,15 @@ def __init__(
         self.downtime_chars_delay = downtime_chars_delay
 
         #: List of accepted key codes to skip dialog. ``curses`` constants are supported. This defaults to an empty tuple.
-        self.confirm_dialog_key: List[CursesKeyConstants] = []
+        self.confirm_dialog_key: List[CursesKeyConstant] = []
         #: List of accepted key codes to raise PanicError. ``curses`` constants are supported. This defaults to an empty tuple.
-        self.panic_key: List[CursesKeyConstants] = []
+        self.panic_key: List[CursesKeyConstant] = []
 
     @property
     def position(self) -> Tuple[int]:
         """Returns a tuple contains x;y position of ``TextBox``.
 
         :returns: x;y position of ``TextBox``.
-        :rtype: tuple[int]
         """
         return self.text_pos_x - 2, self.text_pos_y - 3
 
@@ -160,16 +150,15 @@ def dimensions(self) -> Tuple[int]:
         """Returns a tuple contains dimensions of ``TextBox``.
 
         :returns: Length and width of ``TextBox``.
-        :rtype: tuple[int]
         """
         return self.length, self.width
 
-    def framing_box(self, stdscr):
+    def framing_box(self, win: CursesWindow):
         """Displays dialog box borders and his title.
 
         If attribute ``self.title`` is empty doesn't display the title.
 
-        :param stdscr: ``curses`` window object on which the method will
+        :param win: ``curses`` window object on which the method will
             have effect.
         """
         title_length = len(self.title) + 4
@@ -179,30 +168,30 @@ def framing_box(self, stdscr):
         if self.title:
             attr = (self.title_colors, *self.title_text_attr)
 
-            curses.textpad.rectangle(stdscr,
+            curses.textpad.rectangle(win,
                                      self.pos_y,
                                      self.pos_x + 1,
                                      self.pos_y + title_width,
                                      self.pos_x + title_length)
 
-            with TextAttributes(stdscr, *attr):
-                stdscr.addstr(self.pos_y + 1,
-                              self.pos_x + 3,
-                              self.title)
+            with TextAttributes(win, *attr):
+                win.addstr(self.pos_y + 1,
+                           self.pos_x + 3,
+                           self.title)
 
         # Displays the borders of the dialog box.
-        curses.textpad.rectangle(stdscr,
+        curses.textpad.rectangle(win,
                                  self.pos_y + self.title_offsetting_y,
                                  self.pos_x,
                                  self.pos_y + self.title_offsetting_y + self.width,
                                  self.pos_x + self.length)
 
-    def getkey(self, stdscr):
+    def getkey(self, win: CursesWindow):
         """Blocks execution as long as a key contained in
         ``self.confirm_dialog_key`` is not detected.
 
 
-        :param stdscr: ``curses`` window object on which the method will
+        :param win: ``curses`` window object on which the method will
             have effect.
         :raises PanicError: If a key contained in ``self.panic_key`` is
             pressed.
@@ -217,7 +206,7 @@ def getkey(self, stdscr):
               for more informations.
         """
         while 1:
-            key = stdscr.getch()
+            key = win.getch()
 
             if key in self.confirm_dialog_key:
                 break