Improved UiLoader Documentation, Tutorial

TermTk/TTkUiTools/uiloader.py

@@ -32,15 +32,42 @@ from TermTk.TTkTestWidgets import *
 from TermTk.TTkUiTools.uiproperties import TTkUiProperties
 
 class TTkUiLoader():
+    '''TTkUiLoader
+
+    .. _ttkDesigner: https://github.com/ceccopierangiolieugenio/pyTermTk/tree/main/ttkDesigner
+
+
+    `ttkdesigner Tutorial <https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/ttkDesigner/textEdit>`_
+
+    '''
+
     @staticmethod
-    def loadFile(filePath, baseWidget:TTkWidget=None):
+    def loadFile(filePath, baseWidget:TTkWidget=None) -> TTkWidget:
+        '''load the file generated by ttkDesigner_
+
+        :param filePath: the file path
+        :type filePath: str
+        :param baseWidget: the custom widget that will be extended with this ui definition, if not defined a new :class:`~TermTk.TTkWidgets.widget.TTkWidget` will be returned,defaults to **None**
+        :type baseWidget: :class:`~TermTk.TTkWidgets.widget.TTkWidget`, optional
+
+        :return: :class:`~TermTk.TTkWidgets.widget.TTkWidget`
+        '''
         with open(filePath) as f:
-            return TTkUiLoader.loadJson(f.read(), TTkWidget)
+            return TTkUiLoader.loadJson(f.read(), baseWidget)
         return None
 
     @staticmethod
-    def loadJson(text, baseWidget:TTkWidget=None):
-        return TTkUiLoader.loadDict(json.loads(text), TTkWidget)
+    def loadJson(text, baseWidget:TTkWidget=None) -> TTkWidget:
+        '''load the json representing the ui definition of the widget
+
+        :param text: the representation of the widget in Json format
+        :type text: json generated by ttkDesigner_
+        :param baseWidget: the custom widget that will be extended with this ui definition, if not defined a new :class:`~TermTk.TTkWidgets.widget.TTkWidget` will be returned,defaults to **None**
+        :type baseWidget: :class:`~TermTk.TTkWidgets.widget.TTkWidget`, optional
+
+        :return: :class:`~TermTk.TTkWidgets.widget.TTkWidget`
+        '''
+        return TTkUiLoader.loadDict(json.loads(text), baseWidget)
 
     @staticmethod
     def _loadDict_1_0_0(ui, baseWidget:TTkWidget=None):
@@ -193,7 +220,16 @@ class TTkUiLoader():
         return widget
 
     @staticmethod
-    def loadDict(ui, baseWidget:TTkWidget=None):
+    def loadDict(ui, baseWidget:TTkWidget=None) -> TTkWidget:
+        '''load the dictionary representing the ui definition of the widget
+
+        :param ui: the representation of the widget
+        :type ui: dictionary generated by ttkDesigner_
+        :param baseWidget: the custom widget that will be extended with this ui definition, if not defined a new :class:`~TermTk.TTkWidgets.widget.TTkWidget` will be returned,defaults to **None**
+        :type baseWidget: :class:`~TermTk.TTkWidgets.widget.TTkWidget`, optional
+
+        :return: :class:`~TermTk.TTkWidgets.widget.TTkWidget`
+        '''
         cb = {'1.0.0' : TTkUiLoader._loadDict_1_0_0
               }.get(ui['version'], None)
         if cb:

tutorial/ttkDesigner/textEdit/README.rst

@@ -16,6 +16,11 @@
 .. _grid:           https://ceccopierangiolieugenio.github.io/pyTermTk/autogen.TermTk/TermTk.TTkLayouts.gridlayout.html#ttkgridlayout
 .. _TTkGridLayout:  https://ceccopierangiolieugenio.github.io/pyTermTk/autogen.TermTk/TermTk.TTkLayouts.gridlayout.html#ttkgridlayout
 
+.. _TTkUILoader:    https://ceccopierangiolieugenio.github.io/pyTermTk/autogen.TermTk/TermTk.TTkUiTools.uiloader.html#TermTk.TTkUiTools.uiloader.TTkUiLoader
+
+.. contents::
+
+
 ===================
 ttkDesigner_ - Your first TextEditor
 ===================
@@ -169,8 +174,15 @@ Exported: `texteditor.01.py <https://github.com/ceccopierangiolieugenio/pyTermTk
     PYTHONPATH=`pwd`  python3  tutorial/ttkDesigner/textEdit/texteditor.01.py
 
 
-Imclude the Open/Save routine
--------------------------------
+Import this widget in your project
+==================================
+
+The TTkUiLoader_ provide different methods to use the content generated by ttkDesigner_
+
+Each method is capable of (1) returning a new Widget_ or (2) extending a custom defined widget
+
+Option 1) Include the Open/Save routine and link them to the widget
+-------------------------------------------------------------------
 
 Once (quick)exported the code, we need to define the appropriate routines and link them to the file(open/save) pickers `signals <https://ceccopierangiolieugenio.github.io/pyTermTk/autogen.TermTk/TermTk.TTkWidgets.TTkPickers.filepicker.html#TermTk.TTkWidgets.TTkPickers.filepicker.TTkFileButtonPicker.filePicked>`__
 
@@ -211,3 +223,47 @@ Once (quick)exported the code, we need to define the appropriate routines and li
 
     # Connect the save routine to the (save)"filePicked" event
     btnSave.filePicked.connect(saveRoutine)
+
+Option 2) Extend a custom widget including the open/save methods
+----------------------------------------------------------------
+
+`texteditor.03.py <https://github.com/ceccopierangiolieugenio/pyTermTk/blob/main/tutorial/ttkDesigner/textEdit/texteditor.03.py>`_
+(`Try Online <https://ceccopierangiolieugenio.github.io/pyTermTk/sandbox/sandbox.html?fileUri=https://raw.githubusercontent.com/ceccopierangiolieugenio/pyTermTk/main/tutorial/ttkDesigner/textEdit/texteditor.03.py>`__)
+
+.. code:: bash
+
+    # If you want to try without installation, run from the pyTermTk root folder
+    PYTHONPATH=`pwd`  python3  tutorial/ttkDesigner/textEdit/texteditor.03.py
+
+
+.. code:: python
+
+    class MyTextEditor(TTkWindow):
+        def __init__(self):
+            # The "TTkUiLoader" is responsible to init this custom object
+            # and extend it to the "textEditWindow" created in this tutorial
+            # NOTE: no "super().__init__()" is required
+            TTkUiLoader.loadDict(TTkUtil.base64_deflate_2_obj(
+                #  <Copy here the Compressed string representing the object>
+                ), self)
+
+            # Connect the open routine to the (open)"filePicked" event
+            self.getWidgetByName("BtnOpen").filePicked.connect(self.openRoutine)
+            # Connect the save routine to the (save)"filePicked" event
+            self.getWidgetByName("BtnSave").filePicked.connect(self.saveRoutine)
+
+        # This is a generic routine to open/read a file
+        # and push the content to the "TextEdit" widget
+        pyTTkSlot(str)
+        def openRoutine(self, fileName):
+            textEdit = self.getWidgetByName("TextEdit")
+            with open(fileName) as fp:
+                textEdit.setText(fp.read())
+
+        # This is a generic routine to save the content of
+        # the "TextEdit" widget to the chosen file
+        pyTTkSlot(str)
+        def saveRoutine(self, fileName):
+            textEdit = self.getWidgetByName("TextEdit")
+            with open(fileName, 'w') as fp:
+                fp.write(textEdit.toPlainText())

tutorial/ttkDesigner/textEdit/texteditor.03.py

@@ -0,0 +1,48 @@
+from TermTk import TTkUtil, TTkUiLoader, TTk, TTkWindow
+from TermTk import pyTTkSlot
+
+
+class MyTextEditor(TTkWindow):
+    def __init__(self):
+        # The "TTkUiLoader" is responsible to init this custom object
+        # and extend it to the "textEditWindow" created in this tutorial
+        # NOTE: no "super().__init__()" is required
+        TTkUiLoader.loadDict(TTkUtil.base64_deflate_2_obj(
+            "eJytVltvG0UUXtvrXV96yYVSICBWFVIdJCwHoRLUvCSmMXTr1koMFarysNkd+Yy63rV2Z0ODVKniyalGPMCg8FYBggd+AU/8pv4Ezsyur0lQEuGV5T3znTnzfd/c/EL/" +
+            "+ZuKpj7PRY2bBySKaRgIXlyrN+oNwQssoUJCRdd34ljwcrf79DENvPBbwY2BEzn9WOH6Q6dPBL+KWJc8Y/c8ysJI8FInjCmTJfdEzdbtPOH6Lv2OqPBL+wbh5TYNrMfU" +
+            "YyDsPK/I6AtCe8CErSPoPMvAdn4BUQwztK0vcLPjeB4Neqpawc7Jh3DjgXMYJgzJINdWRL1RbH5NY7rvEzHk5r3AwTdPvnbD0O/SgeD6ypNGH2VthZFHIoSKXcownVsS" +
+            "kN92ZEl1FlHyLOv1q19+SDtdSU2xtn2nF4v72gutlHDDT0dGg6AIb4L5HB1pkbBPWHSIlDV8WvYiEzEvuUB9LyLKKJWvrN5KGEPzZM8alLm5xYKvcBwBVSl5ydYIXJVv" +
+            "FbtA4LptwIJdgMX7mpbTYAlfl/eyYTSZekPVzOyAm0N46wjehne4LkUJvjCSKYdQsmBlyMtNIO5T6ZY44qYK0LejBN5PZX0kycGtdBjkgWrggz2R8EKEi8TWeMENfWEX" +
+            "uIlxPHACYee4iW3Ze5KWuT2tcYeMNb471lg9TWP6MycTOY3FQX2iS5Yd6YLGEaydoaI6UQF3bA0+tXVYt3Pw2Um2BrJtSjcV2dvzE1I8N9lhRvb6iCxWPQ/XygmuxbO4" +
+            "Smeb4eAwI7t2eWeH887Kspdz1jiLbQnZdpyYkYzuxjxd88J0F0d0Vd3L8TVn+fJl3FHb1CfpTu1Q3B3RzH59NMBNnUrQxhKMVIKeSkATLmb361c/fT9Ln+sdB09Jnqvj" +
+            "Odd0BurM5VXJzPqcOn7Yw3aMGJ7weDJu+r4lsdiqfbiKeZuuSwbMaocekVu2rPqlUe50Z4wTzmhzM9mbdmHXORhNpPH/ufDjP7MuQAAhDGZlQzQvFxjyTGztvMJyc1P+" +
+            "Bk55M/TD6NQ5L6ldhmgm98q83PyF5OJ3PMfFtC6/tvLkk/W7H99t4HNnvS/OKyQ/J6SKQka39YT/pCVbtIWMf8u+JvlryF/7z303ps+rD2hArIdJf19dqOUd4njWo8A/" +
+            "xLuk0k58Ri2ZIYaSYm5qEZUSkiS86oZBQFy5mOPsYuRGTAJ5PcMxL0XEJfRABqvYTnuB4wu+nOD1tXngUF9eWrV9vN5xieuxH8o7LiYsu/szRHnxKxzDb7ABv/PliJzs" +
+            "DX/An1neKuYdY17Z9eW8ezWJckOOWRsX20iT4C8JyYITqDUFFd2ETZCd6U4uHqgTaG8KMgfy8KrNEH+JhN5zkwj/PzC1RprgBD0kN1qpiuQSalfRVHNW5GWm6qYrm3eJ" +
+            "j6ZfvDv8jWkVTNsO3SSWFElS/xfnLV9T"), self)
+
+        # Connect the open routine to the (open)"filePicked" event
+        self.getWidgetByName("BtnOpen").filePicked.connect(self.openRoutine)
+        # Connect the save routine to the (save)"filePicked" event
+        self.getWidgetByName("BtnSave").filePicked.connect(self.saveRoutine)
+
+    # This is a generic routine to open/read a file
+    # and push the content to the "TextEdit" widget
+    pyTTkSlot(str)
+    def openRoutine(self, fileName):
+        textEdit = self.getWidgetByName("TextEdit")
+        with open(fileName) as fp:
+            textEdit.setText(fp.read())
+
+    # This is a generic routine to save the content of
+    # the "TextEdit" widget to the chosen file
+    pyTTkSlot(str)
+    def saveRoutine(self, fileName):
+        textEdit = self.getWidgetByName("TextEdit")
+        with open(fileName, 'w') as fp:
+            fp.write(textEdit.toPlainText())
+
+# Initialize TTK, add the window widget, and start the main loop
+root=TTk()
+root.layout().addWidget(MyTextEditor())
+root.mainloop()