diff --git a/README.md b/README.md index cefea4bd..57061fdf 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Powered by [Pyodide](https://pyodide.org/) and [xterm.js](https://xtermjs.org/) --- -## [the Tutorials](tutorial) and [the Examples](tutorial/000-examples.rst) +## [the Tutorials](https://github.com/ceccopierangiolieugenio/pyTermTk/tree/main/tutorial) and [the Examples](https://github.com/ceccopierangiolieugenio/pyTermTk/tree/main/tutorial/000-examples.rst) Be inspired by [the Tutorials](https://github.com/ceccopierangiolieugenio/pyTermTk/tree/main/tutorial) and [the Examples](https://github.com/ceccopierangiolieugenio/pyTermTk/tree/main/tutorial/000-examples.rst) ## [Api Definitions](https://ceccopierangiolieugenio.github.io/pyTermTk/) diff --git a/demo/showcase/animation.01.py b/demo/showcase/animation.01.py index 373bd52e..b4df1505 100755 --- a/demo/showcase/animation.01.py +++ b/demo/showcase/animation.01.py @@ -188,9 +188,10 @@ def demoTextEditRO(root=None): te.setText(ttk.TTkString("Text Edit DEMO\n",ttk.TTkColor.UNDERLINE+ttk.TTkColor.BOLD+ttk.TTkColor.ITALIC)) # Load ANSI input - te.append(ttk.TTkString("ANSI Input Test\n",ttk.TTkColor.UNDERLINE+ttk.TTkColor.BOLD)) - with open(os.path.join(os.path.dirname(os.path.abspath(__file__)),'textedit.ANSI.txt')) as f: - te.append(f.read()) + if os.path.exists(os.path.join(os.path.dirname(os.path.abspath(__file__)),'textedit.ANSI.txt')): + te.append(ttk.TTkString("ANSI Input Test\n",ttk.TTkColor.UNDERLINE+ttk.TTkColor.BOLD)) + with open(os.path.join(os.path.dirname(os.path.abspath(__file__)),'textedit.ANSI.txt')) as f: + te.append(f.read()) # Test Variable sized chars te.append(ttk.TTkString("Test Variable sized chars\n",ttk.TTkColor.UNDERLINE+ttk.TTkColor.BOLD)) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9417c08c..ebc38a66 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,56 +3,89 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +Welcome to pyTermTk_'s documentation! +===================================== + +Intro +----- + +| pyTermTk_ is a Text-based user interface library (TUI_) +| Evolved from the discontinued project pyCuT_ and inspired by +| a mix of Qt5_, GTK_, and tkinter_ api definition with a touch of personal interpretation + .. _pyTermTk: https://github.com/ceccopierangiolieugenio/pyTermTk .. _TermTk: https://github.com/ceccopierangiolieugenio/pyTermTk + .. _TUI: https://en.wikipedia.org/wiki/Text-based_user_interface .. _pyCuT: https://github.com/ceccopierangiolieugenio/pyCuT .. _Qt5: https://www.riverbankcomputing.com/static/Docs/PyQt5/ .. _GTK: https://pygobject.readthedocs.io/en/latest/ .. _tkinter: https://docs.python.org/3/library/tkinter.html -Welcome to pyTermTk_'s documentation! -===================================== +:doc:`info/features/index` + Main features of this library -Intro ------ +:ref:`features-alpha` + New Features available but being reviewed and prone of future changes that may break the compatibility with the previous releases -| pyTermTk_ is a Text-based user interface library (TUI_) -| Evolved from the discontinued project pyCuT_ and inspired by -| a mix of Qt5_, GTK_, and tkinter_ api definition with a touch of personal interpretation +:doc:`info/installing` + How to install,Quickstart,Use,Deliver pyTermTk_ + +**Web Exporter** + TBD (sorry😭) + +:doc:`info/debug` + Notes on how to Debug/Profile +.. :ref:`supported-dependencies` + Supported project dependencies, like Python and Sphinx. .. toctree:: :maxdepth: 1 :caption: Tutorials - tutorial/000-examples.rst + tutorial/000-examples - tutorial/001-helloworld.rst - tutorial/002-layout.rst - tutorial/003-signalslots.rst - tutorial/004-logging.rst - tutorial/005-calculator.rst + tutorial/001-helloworld + tutorial/002-layout + tutorial/003-signalslots + tutorial/004-logging + tutorial/005-calculator - tutorial/ttkDesigner/textEdit/README.rst + tutorial/ttkDesigner/textEdit/README + +.. Hidden TOCs .. toctree:: + :caption: Stuff :maxdepth: 1 + :hidden: + + info/features/index + + info/installing + info/debug + + info/features/crosscompatible + +.. toctree:: :caption: API Reference + :maxdepth: 1 + :hidden: - autogen.TermTk/TermTk.TTkAbstract.rst - autogen.TermTk/TermTk.TTkCore.rst - autogen.TermTk/TermTk.TTkCore.TTkTerm.rst - autogen.TermTk/TermTk.TTkGui.rst - autogen.TermTk/TermTk.TTkLayouts.rst - autogen.TermTk/TermTk.TTkTemplates.rst - autogen.TermTk/TermTk.TTkTestWidgets.rst - autogen.TermTk/TermTk.TTkTheme.rst - autogen.TermTk/TermTk.TTkTypes.rst - autogen.TermTk/TermTk.TTkUiTools.rst - autogen.TermTk/TermTk.TTkWidgets.rst - autogen.TermTk/TermTk.TTkWidgets.TTkModelView.rst - autogen.TermTk/TermTk.TTkWidgets.TTkPickers.rst + autogen.TermTk/TermTk.TTkAbstract + autogen.TermTk/TermTk.TTkCore + autogen.TermTk/TermTk.TTkCore.TTkTerm + autogen.TermTk/TermTk.TTkGui + autogen.TermTk/TermTk.TTkLayouts + autogen.TermTk/TermTk.TTkTemplates + autogen.TermTk/TermTk.TTkTestWidgets + autogen.TermTk/TermTk.TTkTheme + autogen.TermTk/TermTk.TTkTypes + autogen.TermTk/TermTk.TTkUiTools + autogen.TermTk/TermTk.TTkWidgets + autogen.TermTk/TermTk.TTkWidgets.TTkModelView + autogen.TermTk/TermTk.TTkWidgets.TTkPickers Indices and tables ================== @@ -60,3 +93,7 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + + + + diff --git a/docs/source/info/debug.rst b/docs/source/info/debug.rst new file mode 100644 index 00000000..9d6f4054 --- /dev/null +++ b/docs/source/info/debug.rst @@ -0,0 +1,82 @@ +===== +Debug +===== + +Env Variables +============= + +There are few ENV Variables that can be used to force some debugging features; + +**TERMTK_FILE_LOG** - Log to a file +--------------------------------- + +To force logging to a file (i.e. "**session.log**") + +.. code:: bash + + TERMTK_FILE_LOG=session.log python3 demo/demo.py + + +**TERMTK_STACKTRACE** - Force stacktrace generation with CTRL+C +-------------------------------------------------------------- + +Use this env variable to force a stacktrace generation to the file defined (i.e. "**stacktrace.txt**") + +.. code:: bash + + TERMTK_STACKTRACE=stacktrace.txt python3 demo/demo.py + + +Profiling +========= + +`VizTracer `_ +-------------------------------------------------- + +this tool is able to generate a tracker file that can be viewed using `Perfetto `_ (`UI `_) + +.. code:: bash + + # install cprofilev: + # pip3 install viztracer + viztracer --tracer_entries 10000010 tests/paint.py + + # View the results + # loading the "result.json" in https://ui.perfetto.dev + # or running + vizviewer result.json + + +`cProfile `_, `cProfilev `_ +------------------------------------------------------------------------------------------------------------------ + + +.. code:: bash + + python3 -m cProfile -o profiler.bin tests/test.ui.004.py + + # install cprofilev: + # pip3 install cprofilev + cprofilev -f profiler.bin + # open http://127.0.0.1:4000 + +`py-spy `_ +--------------------------------------------- + +.. code:: bash + + # install + pip install py-spy + + # run the application + python3 demo/demo.py + + # on another terminal run the py-spy + sudo env "PATH=$PATH" \ + py-spy top \ + --pid $(ps -A -o pid,cmd | grep demo.py | grep -v grep | sed 's,python.*,,') + +pyroscope +--------- + +`pyroscope `_` can be used as well for profiling \ No newline at end of file diff --git a/docs/source/info/features/crosscompatible.rst b/docs/source/info/features/crosscompatible.rst new file mode 100644 index 00000000..133c6600 --- /dev/null +++ b/docs/source/info/features/crosscompatible.rst @@ -0,0 +1,3 @@ +=================== +Cross Compatibility +=================== \ No newline at end of file diff --git a/docs/source/info/features/index.rst b/docs/source/info/features/index.rst new file mode 100644 index 00000000..6900d3f7 --- /dev/null +++ b/docs/source/info/features/index.rst @@ -0,0 +1,50 @@ +======== +Features +======== + +Main features +------------- + +.. From the README.md + - Self Contained (no external lib required) + - Cross compatible: [Linux](https://en.wikipedia.org/wiki/Linux)🐧, [MacOS](https://en.wikipedia.org/wiki/MacOS)🍎, [MS Windows](https://en.wikipedia.org/wiki/Microsoft_Windows)πŸͺŸ, [HTML5](https://en.wikipedia.org/wiki/HTML5)🌍([Try](https://ceccopierangiolieugenio.github.io/pyTermTk/sandbox/sandbox.html)) + - Basic widgets for [TUI](https://en.wikipedia.org/wiki/Text-based_user_interface) development (Button, Label, checkbox, ...) + - Specialized widgets to improve the usability (Windows, Frames, Tables, ...) + - QT Like Layout system to help arrange the widgets in the terminal + - True color support + - Ful/Half/Zero sized Unicode characters 😎 + - I am pretty sure there is something else... + +Self Contained +~~~~~~~~~~~~~~ + | pyTermTk_ does not require external libraries (i.e. curses) + | It can be installed through PyPi or simply copy the TermTk folder inside the root path of any project + +Wide variety of built in base widgets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Specialised widgets +~~~~~~~~~~~~~~~~~~~ + +Cross Compatibility/Exporters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _features-alpha: + +Alpha Features +-------------- + Those are the feature/poc that are not being extensively tested and can be prone to unexpected behaviour. + Their APIs may change before the final release to address bugs or improving the overall design implementation. + +Text Editor +~~~~~~~~~~~ + +Terminal Emulator +~~~~~~~~~~~~~~~~~ + +Terminal Multiplexer +~~~~~~~~~~~~~~~~~~~~ + +ttkDesigner +~~~~~~~~~~~ + diff --git a/docs/source/info/installing.rst b/docs/source/info/installing.rst new file mode 100644 index 00000000..c0f584e1 --- /dev/null +++ b/docs/source/info/installing.rst @@ -0,0 +1,150 @@ +.. _pyTermTk: https://github.com/ceccopierangiolieugenio/pyTermTk +.. _TermTk: https://github.com/ceccopierangiolieugenio/pyTermTk + +.. _install-installation: + +============ +Installation +============ + +pyTermTk_ is a self contained library, +it does not require extra libraries to be used +and can be installed through :ref:`install-pypi` +or just :ref:`copying the TermTk Folder` in the root folder of your project. + + + +.. _install-pypi: + +PyPi +---- + +It is possible to install pyTermTk with PyPi also inside a venv environment + +User Install +~~~~~~~~~~~~ + +.. code:: bash + + # User/Global Install + pip3 install --upgrade pyTermTk + +`Venv `_ Install +~~~~~~~~~~~~ + +.. code:: bash + + # Create a venv environment in the ".venv" folder + python3 -m venv .venv + . .venv/bin/activate + + # Install inside the venv environment + pip3 install --upgrade pyTermTk + + # ... Do you Stuff + + # Clear/Erase/GetRidOf the venv + rm -rf .venv + + +.. _install-copy: + +Copy TermTk folder +------------------ + +.. code:: bash + + git clone https://github.com/ceccopierangiolieugenio/pyTermTk.git + cp -a pyTermTk/TermTk + + +.. _install-quickstart: + +========== +Quickstart +========== + +There are a number of demo apps and examples that can be executed in the repository + +Demos +----- + +Inside the `demo `_ +and `demo/showcase `_ +folders there are a number of examples that can be executed out of the box. + +Prerequisites +~~~~~~~~~~~~~ + +Clone or `Download `_ the pyTermTk_ repo: + +.. code:: bash + + # Clone and enter the folder + git clone https://github.com/ceccopierangiolieugenio/pyTermTk.git + cd pyTermTk + + +Demos +~~~~~ + +* Main demo `demo.py `_ (`tryItOnline `_) +* paint demo `paint.py `_ (`tryItOnline `_) +* ttkode prototype `ttkode.py `_ (`tryItOnline `_) + +.. code:: bash + + # Run the main demo + python3 demo/demo.py + + # Run the paint demo + python3 demo/paint.py + + # Run the ttkode demo + python3 demo/ttkode.py + + +Showcase +~~~~~~~~ + +**Highlight:** + +* Text Editor `textedit.py `_ (`tryItOnline `_) +* Animation `animation.01.py `_ (`tryItOnline `_) +* color picker `colorpicker.py `_ (`tryItOnline `_) +* file picker `filepicker.py `_ (`tryItOnline `_) +* drag & drop `dragndrop.py `_ (`tryItOnline `_) +* d&d with tabs `dndtabs.py `_ (`tryItOnline `_) +* d&d with list `list.py `_ (`tryItOnline `_) +* base widgets `formwidgets02.py `_ (`tryItOnline `_) +* messagebox `messagebox.py `_ (`tryItOnline `_) +* splitter `splitter.py `_ (`tryItOnline `_) +* Windows `windowsflags.py `_ (`tryItOnline `_) +* Tooltip `test.ui.026.toolTip.py `_ (`tryItOnline `_) + +.. code:: bash + + # Demo - Text Editor + python3 demo/showcase/textedit.py + # Demo - Animation + python3 demo/showcase/animation.01.py + # Demo - color picker + python3 demo/showcase/colorpicker.py + # Demo - file picker + python3 demo/showcase/filepicker.py + # Demo - drag & drop + python3 demo/showcase/dragndrop.py + # Demo - d&d with tabs + python3 demo/showcase/dndtabs.py + # Demo - d&d with list + python3 demo/showcase/list.py + # Demo - base widgets + python3 demo/showcase/formwidgets02.py + # Demo - messagebox + python3 demo/showcase/messagebox.py + # Demo - splitter + python3 demo/showcase/splitter.py + # Demo - Windows + python3 demo/showcase/windowsflags.py + # Demo - Tooltip + python3 tests/test.ui.026.toolTip.py \ No newline at end of file