diff --git a/Makefile b/Makefile index 26df57b9..5eac21c1 100644 --- a/Makefile +++ b/Makefile @@ -2,17 +2,23 @@ .venv: python3 -m venv .venv - . .venv/bin/activate - pip3 install --upgrade pdoc3 - pip3 install --upgrade GitPython - pip3 install --upgrade build - pip3 install --upgrade twine - pip3 install --upgrade pytest flake8 + . .venv/bin/activate ; \ + pip install -r docs/requirements.txt + # Regen requirements; + # pip freeze > docs/requirements.txt + doc: .venv - . .venv/bin/activate - rm -rf docs/html - pdoc --html TermTk -o docs/html + # old doc gen, using pdoc3 ; \ + # . .venv/bin/activate ; \ + # rm -rf docs/html ; \ + # pdoc --html TermTk -o docs/html ; \ + . .venv/bin/activate ; \ + rm -rf docs/html ; \ + rm -rf docs/source/autogen.* ; \ + # sphinx-apidoc -o docs/source/TermTk/ -e TermTk/ ; \ + make -C docs/ clean ; \ + make -C docs/ html ; runGittk: .venv . .venv/bin/activate diff --git a/TermTk/TTkCore/canvas.py b/TermTk/TTkCore/canvas.py index 343c7685..f44a97c8 100644 --- a/TermTk/TTkCore/canvas.py +++ b/TermTk/TTkCore/canvas.py @@ -32,21 +32,10 @@ from TermTk.TTkCore.color import TTkColor from TermTk.TTkCore.helper import TTkHelper class TTkCanvas: - ''' - TTkCanvas - canvas window primitives - ... - Attributes - ---------- - Methods - ------- - __init__({}) - input obj{ width, height} - - resize(w, h) - - resize the canvas keeping or cutting the current one - in w = the width of the new canvas - in h = the height of the new canvas + ''' Init the Canvas object + + :param width: the width of the Canvas + :param height: the height of the Canvas ''' __slots__ = ( '_widget', @@ -56,6 +45,7 @@ class TTkCanvas: '_bufferedData', '_bufferedColors', '_visible', '_doubleBuffer') def __init__(self, *args, **kwargs): + self._widget = kwargs.get('widget', None) self._visible = True self._doubleBuffer = False @@ -95,6 +85,11 @@ class TTkCanvas: self._width = w def resize(self, w, h): + ''' resize the canvas keeping or cutting the current one + + :param w: the width of the new canvas + :param h: the height of the new canvas + ''' self._newWidth = w self._newHeight = h diff --git a/TermTk/TTkCore/constant.py b/TermTk/TTkCore/constant.py index 2a60bf40..893d1bab 100644 --- a/TermTk/TTkCore/constant.py +++ b/TermTk/TTkCore/constant.py @@ -23,6 +23,10 @@ # SOFTWARE. class TTkConstant: + '''Class container of all the constants used in :mod:`~TermTk`''' + + NONE = 0x0000 + # Color Depth DEP_2: int = 0x02 DEP_4: int = 0x04 @@ -125,15 +129,45 @@ class TTkConstant: Input_Password = 0x04 # Alignment - NONE = 0x0000 - LEFT_ALIGN = 0x0001 - RIGHT_ALIGN = 0x0002 - CENTER_ALIGN = 0x0003 - JUSTIFY = 0x0004 + class Alignment: + ''' This class type is used to describe alignment. + + .. autosummary:: + NONE + LEFT_ALIGN + RIGHT_ALIGN + CENTER_ALIGN + JUSTIFY + pippo + ''' + NONE = 0x0000 + ''' No Alignment''' + LEFT_ALIGN = 0x0001 + ''' Aligns with the left edge.''' + RIGHT_ALIGN = 0x0002 + ''' Aligns with the right edge.''' + CENTER_ALIGN = 0x0004 + ''' Centers horizontally in the available space.''' + JUSTIFY = 0x0008 + ''' Justifies the text in the available space.''' + + LEFT_ALIGN = Alignment.LEFT_ALIGN + RIGHT_ALIGN = Alignment.RIGHT_ALIGN + CENTER_ALIGN = Alignment.CENTER_ALIGN + JUSTIFY = Alignment.JUSTIFY + # LayoutItem Types - LayoutItem = 0x01 - WidgetItem = 0x02 + class LayoutItemTypes: + '''Types used internally in :mod:`~TermTk.TTkLayouts`''' + LayoutItem = 0x01 + '''Item Type Layout''' + WidgetItem = 0x02 + '''Item Type Widget''' + + + LayoutItem = LayoutItemTypes.LayoutItem + WidgetItem = LayoutItemTypes.WidgetItem Character = 0x0001 SpecialKey = 0x0002 diff --git a/TermTk/TTkGui/theme.py b/TermTk/TTkGui/theme.py index adf5fc48..7960182b 100644 --- a/TermTk/TTkGui/theme.py +++ b/TermTk/TTkGui/theme.py @@ -26,7 +26,8 @@ from TermTk.TTkCore.color import TTkColor class TTkTheme(): - ''' from: https://en.wikipedia.org/wiki/Box-drawing_character + ''' from: https://en.wikipedia.org/wiki/Box-drawing_character + :: ┌─┬┐ ╔═╦╗ ╓─╥╖ ╒═╤╕ │ ││ ║ ║║ ║ ║║ │ ││ ├─┼┤ ╠═╬╣ ╟─╫╢ ╞═╪╡ @@ -47,28 +48,8 @@ class TTkTheme(): box = ( '═','║', '╔','╗', '╚','╝') - ''' - grid0 grid1 grid2 grid3 - ┌─┬┐ ╔═╦╗ ╔═╤╗ ┌─╥┐ - │ ││ ║ ║║ ║ │║ │ ║│ - ├─┼┤ ╠═╬╣ ╟─┼╢ ╞═╬╡ - └─┴┘ ╚═╩╝ ╚═╧╝ └─╨┘ - grid4 grid5 grid6 grid7 grid8 grid9 - ╓─╥╖ ╒═╤╕ ╓─┬┐ ┌─┬╖ ┌─┬┐ ╒═╤╕ - ║ ║║ │ ││ ║ ││ │ │║ │ ││ │ ││ - ╟─╫╢ ╞═╪╡ ╟─┼┤ ├─┼╢ ├─┼┤ ├─┼┤ - ╙─╨╜ ╘═╧╛ ╚═╧╛ ╘═╧╝ ╘═╧╛ └─┴┘ - ids (hex): - 0 1 2 3 - ┌ ─ ┬ ┐ - 4 5 6 7 - │ │ │ - 8 9 A B - ├ ─ ┼ ┤ - C D E F - └ ─ ┴ ┘ - ''' + grid = ( ( # Grid 0 '┌','─','┬','┐', @@ -102,13 +83,32 @@ class TTkTheme(): '└','─','┴','┘'), (), # TODO: Grid 10 ) + ''' Grid Types + :: + grid0 grid1 grid2 grid3 + ┌─┬┐ ╔═╦╗ ╔═╤╗ ┌─╥┐ + │ ││ ║ ║║ ║ │║ │ ║│ + ├─┼┤ ╠═╬╣ ╟─┼╢ ╞═╬╡ + └─┴┘ ╚═╩╝ ╚═╧╝ └─╨┘ + grid4 grid5 grid6 grid7 grid8 grid9 + ╓─╥╖ ╒═╤╕ ╓─┬┐ ┌─┬╖ ┌─┬┐ ╒═╤╕ + ║ ║║ │ ││ ║ ││ │ │║ │ ││ │ ││ + ╟─╫╢ ╞═╪╡ ╟─┼┤ ├─┼╢ ├─┼┤ ├─┼┤ + ╙─╨╜ ╘═╧╛ ╚═╧╛ ╘═╧╝ ╘═╧╛ └─┴┘ + ids (hex): + 0 1 2 3 + ┌ ─ ┬ ┐ + 4 5 6 7 + │ │ │ + 8 9 A B + ├ ─ ┼ ┤ + C D E F + └ ─ ┴ ┘ ''' - box0 box1 - ┌─┐ ┌─┐ - │ │ │ │ - └─┘ ╘═╛ - ''' + + + buttonBox = ( ('┌','─','┐', '│',' ','│', @@ -116,6 +116,12 @@ class TTkTheme(): ('┌','─','┐', '│',' ','│', '╘','═','╛')) + ''' + box0 box1 + ┌─┐ ┌─┐ + │ │ │ │ + └─┘ ╘═╛ + ''' hscroll = ('◀','┄','▓','▶') vscroll = ('▲','┊','▓','▼') @@ -123,21 +129,7 @@ class TTkTheme(): # 0 1 2 3 4 5 menuBar = ('├','─','┤','┄','┄','▶') - ''' - ┌──────╔══════╗──────┬──────┐ ┌─┌──────╔══════╗──────┬──────┐─┐ - │Label1║Label2║Label3│Label4│ │◀│Label1║Label2║Label3│Label4│▶│ - ╞═╧══════╩══════╩══════╧══════╧════╡ ╞═╧══════╩══════╩══════╧══════╧═╡ - ┌──────╔══════╗──────┬──────┐ ╭─┌──────╔══════╗──────┬──────┐─╮ - │Label1║Label2║Label3│Label4│ │◀│Label1║Label2║Label3│Label4│▶│ - ╞════════╩══════╩══════════════════╡ ╞════════╩══════╩═══════════════╡ - # Menu Prototype: - ╭──┌──────╔══════╗──────┬──────┐ ╭──┬─┌──────╔══════╗──────┬──────┐─╮ - │⣿⣿│Label1║Label2║Label3│Label4│ │⣿⣿│◀│Label1║Label2║Label3│Label4│▶│ - ╞═════════╩══════╩═══════════════╡ ╞══╧════════╩══════╩═══════════════╡ - ┌──────┲━━━━━━┱──────┬──────┐ - │Label1┃Label2┃Label3│Label4│ - ┝━┷━━━━━━┻━━━━━━┻━━━━━━┷━━━━━━┷━━━━┥ - ''' + tab = ( #0 1 2 3 4 5 6 7 8 '┌','─','┬','┐','╔','═','╗','╭','╮', @@ -150,15 +142,32 @@ class TTkTheme(): #31 32 '◀','▶' ) + ''' Tab Examples + :: + ┌──────╔══════╗──────┬──────┐ ┌─┌──────╔══════╗──────┬──────┐─┐ + │Label1║Label2║Label3│Label4│ │◀│Label1║Label2║Label3│Label4│▶│ + ╞═╧══════╩══════╩══════╧══════╧════╡ ╞═╧══════╩══════╩══════╧══════╧═╡ + ┌──────╔══════╗──────┬──────┐ ╭─┌──────╔══════╗──────┬──────┐─╮ + │Label1║Label2║Label3│Label4│ │◀│Label1║Label2║Label3│Label4│▶│ + ╞════════╩══════╩══════════════════╡ ╞════════╩══════╩═══════════════╡ + # Menu Prototype: + ╭──┌──────╔══════╗──────┬──────┐ ╭──┬─┌──────╔══════╗──────┬──────┐─╮ + │⣿⣿│Label1║Label2║Label3│Label4│ │⣿⣿│◀│Label1║Label2║Label3│Label4│▶│ + ╞═════════╩══════╩═══════════════╡ ╞══╧════════╩══════╩═══════════════╡ + ┌──────┲━━━━━━┱──────┬──────┐ + │Label1┃Label2┃Label3│Label4│ + ┝━┷━━━━━━┻━━━━━━┻━━━━━━┷━━━━━━┷━━━━┥ ''' - bpytop style graph: - ⢠⢠ ⡇ ⣆⡇ ⢠ ⣰ ⢠ - ⢸⣀⣀⣠⣸⣸⡄ ⡄⣼ ⣀⡀ ⢠⣷⡀ ⣀⣰⣀⣿⣇⡀⢀⣸⡀⣆⣿⣆⣄⣼⣀⣀⣸ - ⣾⣿⣿⣿⣿⣿⣧⣧⣧⣤⣦⣦⣿⣿⣤⣿⣧⣧⣿⣿⣿⣷⣷⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧ - ⢿⣿⣿⣿⣿⣿⡟⠟⠟⠋⠟⠏⡿⣿⠋⣿⡟⡟⢿⣿⡿⠿⡿⣿⣿⣿⣿⣿⡿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢿⡏ - ⢸⠉⠉⠉⢸⢹⠁ ⠃⠹ ⠁ ⠈⡿⠁ ⠈⠸⠉⣿⡏ ⠈⢹⠁⠏⣿⠏⠃⢻⠉ ⠸⠈⠁ - ⠈⠈ ⠇ ⠋⠇ ⠈ ⠘ ⠈ - ''' + + # ''' bpytop style graph: + # :: + # ⢠⢠ ⡇ ⣆⡇ ⢠ ⣰ ⢠ + # ⢸⣀⣀⣠⣸⣸⡄ ⡄⣼ ⣀⡀ ⢠⣷⡀ ⣀⣰⣀⣿⣇⡀⢀⣸⡀⣆⣿⣆⣄⣼⣀⣀⣸ + # ⣾⣿⣿⣿⣿⣿⣧⣧⣧⣤⣦⣦⣿⣿⣤⣿⣧⣧⣿⣿⣿⣷⣷⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧ + # ⢿⣿⣿⣿⣿⣿⡟⠟⠟⠋⠟⠏⡿⣿⠋⣿⡟⡟⢿⣿⡿⠿⡿⣿⣿⣿⣿⣿⡿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⢿⡏ + # ⢸⠉⠉⠉⢸⢹⠁ ⠃⠹ ⠁ ⠈⡿⠁ ⠈⠸⠉⣿⡏ ⠈⢹⠁⠏⣿⠏⠃⢻⠉ ⠸⠈⠁ + # ⠈⠈ ⠇ ⠋⠇ ⠈ ⠘ ⠈ + # ''' # graph_up = ( # (' ','⢀','⢠','⢰','⢸'), # ('⡀','⣀','⣠','⣰','⣸'), diff --git a/TermTk/TTkLayouts/boxlayout.py b/TermTk/TTkLayouts/boxlayout.py index 778beeba..1efd8d4e 100644 --- a/TermTk/TTkLayouts/boxlayout.py +++ b/TermTk/TTkLayouts/boxlayout.py @@ -23,17 +23,43 @@ # SOFTWARE. ''' -### Box Layout -[Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) +### Box Layout - [Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) ''' from TermTk.TTkCore.log import TTkLog from TermTk.TTkLayouts.gridlayout import TTkGridLayout class TTkHBoxLayout(TTkGridLayout): + ''' The TTkHBoxLayout class lines up widgets horizontally + ```text + TTkHBoxLayout + ╔═════════╤═════════╤═════════╗ + ║ Widget1 │ Widget2 │ Widget3 ║ + ║ │ │ ║ + ║ │ │ ║ + ║ │ │ ║ + ║ │ │ ║ + ║ │ │ ║ + ╚═════════╧═════════╧═════════╝ + ``` + ''' pass class TTkVBoxLayout(TTkGridLayout): + ''' The TTkVBoxLayout class lines up widgets vertically + ```text + TTkVBoxLayout + ╔═════════════════════════════╗ + ║ Widget 1 ║ + ╟─────────────────────────────╢ + ║ Widget 2 ║ + ╟─────────────────────────────╢ + ║ Widget 3 ║ + ╟─────────────────────────────╢ + ║ Widget 4 ║ + ╚═════════════════════════════╝ + ``` + ''' def addItem(self, item): TTkGridLayout.addItem(self, item, self.count(), 0) def addWidget(self, widget): diff --git a/TermTk/TTkLayouts/gridlayout.py b/TermTk/TTkLayouts/gridlayout.py index 30dd28cd..84e0e610 100644 --- a/TermTk/TTkLayouts/gridlayout.py +++ b/TermTk/TTkLayouts/gridlayout.py @@ -23,24 +23,7 @@ # SOFTWARE. ''' -### Grid Layout -[Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) - -The grid layout allows an automatic place all the widgets in a grid -the empty rows/cols are resized to the "columnMinHeight,columnMinWidth" parameters - - TTkGridLayout ┌┐ columnMinWidth - ╔═════════╤═════════╤╤═════════╗ - ║ Widget1 │ Widget2 ││ Widget3 ║ - ║ (0,0) │ (0,1) ││ (0,3) ║ - ╟─────────┼─────────┼┼─────────╢ ┐ columnMinHeight - ╟─────────┼─────────┼┼─────────╢ ┘ - ║ Widget4 │ ││ ║ - ║ (2,0) │ ││ ║ - ╟─────────┼─────────┼┼─────────╢ - ║ │ ││ Widget5 ║ - ║ │ ││ (3,3) ║ - ╚═════════╧═════════╧╧═════════╝ +### Grid Layout - [Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) ''' from TermTk.TTkCore.constant import TTkK @@ -48,15 +31,30 @@ from TermTk.TTkCore.log import TTkLog from TermTk.TTkLayouts.layout import TTkLayout, TTkWidgetItem class TTkGridLayout(TTkLayout): + ''' + The grid layout allows an automatic place all the widgets in a grid,
+ the empty rows/cols are resized to the "columnMinHeight,columnMinWidth" parameters + + ``` + TTkGridLayout ┌┐ columnMinWidth + ╔═════════╤═════════╤╤═════════╗ + ║ Widget1 │ Widget2 ││ Widget3 ║ + ║ (0,0) │ (0,1) ││ (0,3) ║ + ╟─────────┼─────────┼┼─────────╢ ┐ columnMinHeight + ╟─────────┼─────────┼┼─────────╢ ┘ + ║ Widget4 │ ││ ║ + ║ (2,0) │ ││ ║ + ╟─────────┼─────────┼┼─────────╢ + ║ │ ││ Widget5 ║ + ║ │ ││ (3,3) ║ + ╚═════════╧═════════╧╧═════════╝ + ``` + :param int columnMinWidth: the minimum width of the column, optional, defaults to 0 + :param int columnMinHeight: the minimum height of the column, optional, defaults to 0 + ''' + __slots__ = ('_gridItems','_columnMinWidth','_columnMinHeight', '_rows', '_cols') def __init__(self, *args, **kwargs): - ''' - TTkGridLayout constructor - - Args: - columnMinWidth (int, optional, default=0): the minimum width of the column - columnMinHeight (int, optional, default=0): the minimum height of the column - ''' self._rows = 0 self._cols = 0 TTkLayout.__init__(self, *args, **kwargs) @@ -97,6 +95,15 @@ class TTkGridLayout(TTkLayout): # addWidget(self, widget, row, col) def addWidget(self, widget, row=None, col=None, rowspan=1, colspan=1): + '''Add the widget to this :class:`TTkGridLayout`, this function uses :meth:`~addItem` + + :param widget: the widget to be added + :type widget: :class:`~TermTk.TTkWidgets.widget.TTkWidget` + :param int row: the row of the grid, optional, defaults to None + :param int col: the col of the grid, optional, defaults to None + :param int rowspan: the rows used by the widget, optional, defaults to 1 + :param int colspan: the cols used by the widget, optional, defaults to 1 + ''' self.removeWidget(widget) item = TTkWidgetItem(widget=widget) TTkGridLayout.addItem(self, item, row, col, rowspan, colspan) @@ -105,6 +112,16 @@ class TTkGridLayout(TTkLayout): def replaceItem(self, item, index): pass def addItem(self, item, row=None, col=None, rowspan=1, colspan=1): + '''Add the item to this :class:`TTkGridLayout` + + :param item: the item to be added + :type item: :class:`~TermTk.TTkLayouts.layout.TTkLayoutItem` + :param int row: the row of the grid, optional, defaults to None + :param int col: the col of the grid, optional, defaults to None + :param int rowspan: the rows used by the item, optional, defaults to 1 + :param int colspan: the cols used by the item, optional, defaults to 1 + + ''' self.removeItem(item) if row is None and col is None: # Append The widget at the end diff --git a/TermTk/TTkLayouts/layout.py b/TermTk/TTkLayouts/layout.py index 2ab95dbc..53c41a4f 100644 --- a/TermTk/TTkLayouts/layout.py +++ b/TermTk/TTkLayouts/layout.py @@ -23,14 +23,24 @@ # SOFTWARE. ''' -### Layout -[Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) +### Layout - [Tutorial](https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/002-layout.md) ''' from TermTk.TTkCore.log import TTkLog from TermTk.TTkCore.constant import TTkK class TTkLayoutItem: + ''' :class:`~TTkLayoutItem` is the base class of layout Items inherited by :class:`~TTkLayout`, :class:`~TTkWidgetItem`, and all the derived layout managers. + + :param int row: (used only in the :class:`~TermTk.TTkLayouts.gridlayout.TTkGridLayout`), the row of the grid, optional, defaults to None + :param int col: (used only in the :class:`~TermTk.TTkLayouts.gridlayout.TTkGridLayout`), the col of the grid, optional, defaults to None + :param int rowspan: (used only in the :class:`~TermTk.TTkLayouts.gridlayout.TTkGridLayout`), the rows used by this, optional, defaults to 1 + :param int colspan: (used only in the :class:`~TermTk.TTkLayouts.gridlayout.TTkGridLayout`), the cols used by this, optional, defaults to 1 + :param layoutItemType: The Type of this class, optional, defaults to TTkK.NONE + :type layoutItemType: :class:`~TermTk.TTkCore.constant.TTkConstant.LayoutItemTypes` + :param alignment: The alignment of this item in the layout (not yet used) + :type alignment: :class:`~TermTk.TTkCore.constant.TTkConstant.Alignment` + ''' __slots__ = ( '_x', '_y', '_z', '_w', '_h', '_row','_col', @@ -57,16 +67,12 @@ class TTkLayoutItem: def minDimension(self,o)-> int: return 0 def minimumHeight(self) -> int: return 0 def minimumWidth(self) -> int: return 0 - def minimumHeightSpan(self,pos) -> int: return 0 - def minimumWidthSpan(self,pos) -> int: return 0 def maximumSize(self): return self.maximumWidth(), self.maximumHeight() def maxDimension(self,o)-> int: return 0x1000 def maximumHeight(self) -> int: return 0x10000 def maximumWidth(self) -> int: return 0x10000 - def maximumHeightSpan(self,pos) -> int: return 0x10000 - def maximumWidthSpan(self,pos) -> int: return 0x10000 @staticmethod def _calcSpanValue(value, pos, curpos, span): @@ -106,6 +112,22 @@ class TTkLayoutItem: class TTkLayout(TTkLayoutItem): + ''' The :class:`TTkLayout` class is the base class of geometry managers.
+ It allows free placement of the widgets in the layout area.
+ Used mainly to have free range moving :class:`~TermTk.TTkWidgets.window.TTkWindow` because the widgets are not automatically rearranged after a layout event + ``` + ╔════════════════════════════╗ + ║ pos(4,2) ║ + ║ ┌───────┐ pos(16,4) ║ + ║ │Widget1│ ┌─────────┐ ║ + ║ │ │ │ Widget2 │ ║ + ║ │ │ └─────────┘ ║ + ║ │ │ ║ + ║ └───────┘ ║ + ║ ║ + ╚════════════════════════════╝ + ``` + ''' __slots__ = ('_items', '_zSortedItems', '_parent') def __init__(self, *args, **kwargs): TTkLayoutItem.__init__(self, args, kwargs) diff --git a/TermTk/TTkTemplates/keyevents.py b/TermTk/TTkTemplates/keyevents.py index 68f23b63..53c62ee2 100644 --- a/TermTk/TTkTemplates/keyevents.py +++ b/TermTk/TTkTemplates/keyevents.py @@ -26,7 +26,9 @@ class TKeyEvents(): def keyPressEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive key press events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -36,7 +38,9 @@ class TKeyEvents(): def keyReleaseEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive key release events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -47,7 +51,9 @@ class TKeyEvents(): def keyEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive key events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: diff --git a/TermTk/TTkTemplates/mouseevents.py b/TermTk/TTkTemplates/mouseevents.py index 2e501058..93a46d24 100644 --- a/TermTk/TTkTemplates/mouseevents.py +++ b/TermTk/TTkTemplates/mouseevents.py @@ -26,7 +26,9 @@ class TMouseEvents(): def mouseDoubleClickEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse click events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -37,7 +39,9 @@ class TMouseEvents(): def mouseMoveEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse move events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -48,7 +52,9 @@ class TMouseEvents(): def mouseDragEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse drag events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -59,7 +65,9 @@ class TMouseEvents(): def mousePressEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse press events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -70,7 +78,9 @@ class TMouseEvents(): def mouseReleaseEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse release events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -81,7 +91,9 @@ class TMouseEvents(): def wheelEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse wheel events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -92,7 +104,9 @@ class TMouseEvents(): def enterEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse enter events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: @@ -103,7 +117,9 @@ class TMouseEvents(): def leaveEvent(self, evt) -> bool : ''' This event handler, can be reimplemented in a subclass to receive mouse leave events for the widget. + .. note:: Reimplement this function to handle this event + Args: evt ([TermTk.libbpytop.input.MouseEvent]): the mouse event Returns: diff --git a/TermTk/TTkWidgets/widget.py b/TermTk/TTkWidgets/widget.py index d9a68fa3..c0f69604 100644 --- a/TermTk/TTkWidgets/widget.py +++ b/TermTk/TTkWidgets/widget.py @@ -35,20 +35,51 @@ import TermTk.libbpytop as lbt class TTkWidget(TMouseEvents,TKeyEvents): - ''' - ### Widget Layout sizes: - Terminal window + ''' Widget Layout sizes: + :: + Terminal area (i.e. XTerm) ┌─────────────────────────────────────────┐ │ │ │ TTkWidget width │ │ (x,y)┌─────────────────────────┐ │ - │ │ padt │ │ + │ │ padt (Top Padding) │ │ │ │ ┌───────────────┐ │ height │ │ │padl│ Layout/childs │padr│ │ │ │ └───────────────┘ │ │ - │ │ padl │ │ + │ │ padb (Bottom Pad.) │ │ │ └─────────────────────────┘ │ └─────────────────────────────────────────┘ + + The TTkWidget class is the base class of all user interface objects + + :param str name: the name of the widget, defaults to "" + :type name: str, optional + :param parent: the parent widget, defaults to None + :type parent: :class:`TTkWidget`, optional + + :param int x: the x position, defaults to 0 + :param int y: the y position, defaults to 0 + :param [int,int] pos: the [x,y] position (override the previously defined x, y), optional, default=[0,0] + + :param int width: the width of the widget, defaults to 0 + :param int height: the height of the widget, defaults to 0 + :param [int,int] size: the size [width, height] of the widget (override the previously defined sizes), optional, default=[0,0] + + :param int padding: the padding (top, bottom, left, right) of the widget, defaults to 0 + :param int paddingTop: the Top padding, override Top padding if already defined, optional, default=padding + :param int paddingBottom: the Bottom padding, override Bottom padding if already defined, optional, default=padding + :param int paddingLeft: the Left padding, override Left padding if already defined, optional, default=padding + :param int paddingRight: the Right padding, override Right padding if already defined, optional, default=padding + :param int maxWidth: the maxWidth of the widget, optional, defaults to 0x10000 + :param int maxHeight: the maxHeight of the widget, optional, defaults to 0x10000 + :param [int,int] maxSize: the max [width,height] of the widget, optional + :param int minWidth: the minWidth of the widget, defaults to 0 + :param int minHeight: the minHeight of the widget, defaults to 0 + :param [int,int] minSize: the minSize [width,height] of the widget, optional + + :param bool,optional visible: the visibility, optional, defaults to True + :param layout: the layout of this widget, optional, defaults to :class:`~TermTk.TTkLayouts.layout.TTkLayout` + :type layout: :mod:`TermTk.TTkLayouts` ''' __slots__ = ( '_name', '_parent', @@ -60,36 +91,7 @@ class TTkWidget(TMouseEvents,TKeyEvents): '_pendingMouseRelease') def __init__(self, *args, **kwargs): - ''' - TTkWidget constructor - - Args: - name (str, optional): the name of the widget - parent ([TermTk.TTkWidgets.widget.TTkWidget], optional): the parent widget - - x (int, optional, default=0): the x position - y (int, optional, default=0): the y position - pos ([int,int], optional, default=[0,0]): the [x,y] position (override the previously defined x, y) - - width (int, optional, default=0): the width of the widget - height (int, optional, default=0): the height of the widget - size ([int,int], optional, default=[0,0]): the size [width, height] of the widget (override the previously defined sizes) - - padding (int, optional, default=0): the padding (top, bottom, left, right) of the widget - paddingTop (int, optional, default=padding): the Top padding, override Top padding if already defined - paddingBottom (int, optional, default=padding): the Bottom padding, override Bottom padding if already defined - paddingLeft (int, optional, default=padding): the Left padding, override Left padding if already defined - paddingRight (int, optional, default=padding): the Right padding, override Right padding if already defined - maxWidth (int, optional, default=0x10000): the maxWidth of the widget - maxHeight (int, optional, default=0x10000): the maxHeight of the widget - maxSize ([int,int], optional): the max [width,height] of the widget - minWidth (int, optional, default=0): the minWidth of the widget - minHeight (int, optional, default=0): the minHeight of the widget - minSize ([int,int], optional): the minSize [width,height] of the widget - - visible (bool, optional, default=True): the visibility - layout ([TermTk.TTkLayouts], optional, default=[TermTk.TTkLayouts.layout.TTkLayout]): the layout of this widget - ''' + self._name = kwargs.get('name', 'TTkWidget' ) self._parent = kwargs.get('parent', None ) @@ -143,11 +145,10 @@ class TTkWidget(TMouseEvents,TKeyEvents): self._parent = None def addWidget(self, widget): - ''' - Add a child widget to the layout + ''' Add a child widget to the layout - Args: - widget ([TermTk.TTkWidgets.widget.TTkWidget]): the widget to be added + :param widget: the widget to be added + :type widget: :class:`~TermTk.TTkWidgets.widget.TTkWidget` ''' widget._parent = self if self.layout() is not None: @@ -156,11 +157,9 @@ class TTkWidget(TMouseEvents,TKeyEvents): # widget.show() def removeWidget(self, widget): - ''' - Remove the child widget from the layout + ''' Remove the child widget from the layout - Args: - widget ([TermTk.TTkWidgets.widget.TTkWidget]): the widget to be removed + :param widget: (:class:`~TermTk.TTkWidgets.widget.TTkWidget`): the widget to be removed ''' if self.layout() is not None: self.layout().removeWidget(widget) @@ -209,11 +208,10 @@ class TTkWidget(TMouseEvents,TKeyEvents): pass def move(self, x: int, y: int): - ''' - Move the widget - Args: - x (int): x position - y (int): y position + ''' Move the widget + + :param int x: x position + :param int y: y position ''' if x==self._x and y==self._y: return self._x = x @@ -222,11 +220,10 @@ class TTkWidget(TMouseEvents,TKeyEvents): self.moveEvent(x,y) def resize(self, w: int, h: int): - ''' - Resize the widget - Args: - w (int): the new width - h (int): the new height + ''' Resize the widget + + :param int w: the new width + :param int h: the new height ''' # TTkLog.debug(f"resize: {w,h} {self._name}") if w!=self._width or h!=self._height: @@ -237,33 +234,30 @@ class TTkWidget(TMouseEvents,TKeyEvents): self.resizeEvent(w,h) def setGeometry(self, x: int, y: int, w: int, h: int): - ''' - Resize and move the widget - Args: - x (int): x position - y (int): y position - w (int): the new width - h (int): the new height + ''' Resize and move the widget + + :param int x: x position + :param int y: y position + :param int w: the new width + :param int h: the new height ''' self.resize(w, h) self.move(x, y) def getPadding(self) -> (int, int, int, int): - ''' - Retrieve the widget padding sizes - Returns: - List[top, bottom, left, right]: the 4 padding sizes + ''' Retrieve the widget padding sizes + + :return: list[top, bottom, left, right]: the 4 padding sizes ''' return self._padt, self._padb, self._padl, self._padr def setPadding(self, top, bottom, left, right): - ''' - set the padding of the widget - Args: - top (int): top padding - bottom (int): bottom padding - left (int): left padding - right (int): right padding + ''' Set the padding of the widget + + :param int top: top padding + :param int bottom: bottom padding + :param int left: left padding + :param int right: right padding ''' if self._padt == top and self._padb == bottom and \ self._padl == left and self._padr == right: return diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..2f0295b7 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,61 @@ +alabaster==0.7.12 +attrs==20.3.0 +Babel==2.9.0 +bleach==3.3.0 +build==0.3.1.post1 +certifi==2020.12.5 +cffi==1.14.5 +chardet==4.0.0 +colorama==0.4.4 +cryptography==3.4.7 +docutils==0.17 +flake8==3.9.0 +gitdb==4.0.7 +GitPython==3.1.14 +idna==2.10 +imagesize==1.2.0 +importlib-metadata==3.10.0 +iniconfig==1.1.1 +jeepney==0.6.0 +Jinja2==2.11.3 +keyring==23.0.1 +m2r==0.2.1 +MarkupSafe==1.1.1 +mccabe==0.6.1 +mistune==0.8.4 +packaging==20.9 +pep517==0.10.0 +pkginfo==1.7.0 +pluggy==0.13.1 +py==1.10.0 +pycodestyle==2.7.0 +pycparser==2.20 +pyflakes==2.3.1 +Pygments==2.8.1 +pyparsing==2.4.7 +pytest==6.2.3 +pytz==2021.1 +readme-renderer==29.0 +requests==2.25.1 +requests-toolbelt==0.9.1 +rfc3986==1.4.0 +SecretStorage==3.3.1 +six==1.15.0 +smmap==4.0.0 +snowballstemmer==2.1.0 +Sphinx==3.5.3 +sphinx-autodocgen==1.2 +sphinx-epytext==0.0.4 +sphinx-rtd-theme==0.5.1 +sphinxcontrib-applehelp==1.0.2 +sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-htmlhelp==1.0.3 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-serializinghtml==1.1.4 +toml==0.10.2 +tqdm==4.59.0 +twine==3.4.1 +urllib3==1.26.4 +webencodings==0.5.1 +zipp==3.4.1 diff --git a/docs/source/.gitignore b/docs/source/.gitignore new file mode 100644 index 00000000..f7a70aec --- /dev/null +++ b/docs/source/.gitignore @@ -0,0 +1 @@ +autogen.* \ No newline at end of file diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 00000000..bb3d4b94 --- /dev/null +++ b/docs/source/_static/theme_overrides.css @@ -0,0 +1,22 @@ +/* In a bid to be "mobile-friendly" by default about 1/3 of the horizontal space is wasted; + this CSS removes the wasted space. */ +.wy-nav-content { + max-width: none; +} + + +/* Temporary workaround for RTD 0.4.3 bug https://github.com/readthedocs/sphinx_rtd_theme/issues/117 which will hopefully be fixed soon +*/ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..71732b16 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,133 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('../..')) + + +# -- Project information ----------------------------------------------------- + +project = 'pyTermTk' +copyright = '2021, Eugenio Parodi' +author = 'Eugenio Parodi' + +# The full version, including alpha/beta/rc tags +release = '0.2.0a' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx.ext.githubpages', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.autosectionlabel', + 'sphinx_epytext', + 'sphinxcontrib_autodocgen', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' # read-the-docs theme looks better than the default "classic" one but has bugs e.g. no table wrapping + +html_theme_options = { + 'display_version': True, + #'prev_next_buttons_location': 'bottom', + #'style_external_links': False, + #'vcs_pageview_mode': '', + #'style_nav_header_background': 'white', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + #'navigation_depth': 4, + 'includehidden': False, + #'titles_only': False +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +html_context = {'css_files': [ + # Workaround for RTD 0.4.3 bug https://github.com/readthedocs/sphinx_rtd_theme/issues/117 + '_static/theme_overrides.css', # override wide tables in RTD theme +]} + +# html_theme = 'groundwork' + +#html_theme_options = { +# "sidebar_width": '240px', +# "stickysidebar": True, +# "stickysidebarscrollable": True, +# "contribute": True, +# "github_fork": "useblocks/groundwork", +# "github_user": "useblocks", +#} + + +import m2r + +def docstring(app, what, name, obj, options, lines): + md = '\n'.join(lines) + rst = m2r.convert(md) + lines.clear() + lines += rst.splitlines() + +def setup(app): + app.connect('autodoc-process-docstring', docstring) + +import TermTk + +add_module_names = False +autosummary_generate = True +autosummary_generate_overwrite = False + +autodocgen_config = { + 'modules':[TermTk], + 'generated_source_dir': os.path.abspath('.')+'/autogen.TermTk/', + #'add_module_names': False, + + # if module matches this then it and any of its submodules will be skipped + # 'skip_module_regex': '(.*[.]__|myskippedmodule)', + 'skip_module_regex': '(.*[.]__|myskippedmodule)', + + # produce a text file containing a list of everything documented. you can use this in a test to notice when you've + # intentionally added/removed/changed a documented API + 'write_documented_items_output_file': 'autodocgen_documented_items.txt', + + # customize autodoc on a per-module basis + 'autodoc_options_decider': { + 'TermTk.TTkWidgets': { 'inherited-members':True }, + }, + + # choose a different title for specific modules, e.g. the toplevel one + 'module_title_decider': lambda modulename: 'API Reference' if modulename=='TermTk' else modulename, +} \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..8387328c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,25 @@ +.. pyTermTk documentation master file, created by + sphinx-quickstart on Fri Apr 2 12:13:00 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to pyTermTk's documentation! +==================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + autogen.TermTk/TermTk.rst + +TermTk main +=================== +.. autoclass:: TermTk.TTkButton +.. autodecorator:: TermTk.pyTTkSlot + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/tutorial/002-layout.md b/tutorial/002-layout.md index edc45d12..a1073521 100644 --- a/tutorial/002-layout.md +++ b/tutorial/002-layout.md @@ -303,7 +303,8 @@ root.setLayout(gridLayout) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button1"), 0,0, 1,2) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button2"), 0,2, 2,1) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button3"), 1,0, 2,1) -gridLayout.addWidget(ttk.TTkButton(border=True, text="Button4"), 2,1, 1,2) +# It is possible to expand the names +gridLayout.addWidget(ttk.TTkButton(border=True, text="Button4"), row=2, col=1, rowspan=1, colspan=2) root.mainloop() ``` diff --git a/tutorial/layout/example6.grid.span.py b/tutorial/layout/example6.grid.span.py index ff33dd96..30553e36 100755 --- a/tutorial/layout/example6.grid.span.py +++ b/tutorial/layout/example6.grid.span.py @@ -46,6 +46,7 @@ root.setLayout(gridLayout) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button1"), 0,0, 1,2) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button2"), 0,2, 2,1) gridLayout.addWidget(ttk.TTkButton(border=True, text="Button3"), 1,0, 2,1) -gridLayout.addWidget(ttk.TTkButton(border=True, text="Button4"), 2,1, 1,2) +# It is possible to expand the names +gridLayout.addWidget(ttk.TTkButton(border=True, text="Button4"), row=2, col=1, rowspan=1, colspan=2) root.mainloop() \ No newline at end of file