[
{
"path": ".github/FUNDING.yml",
"content": "# These are supported funding model platforms\n\nbuy_me_a_coffee: andereoo\n"
},
{
"path": ".gitignore",
"content": "build/\ntkinterweb/__pycache__/\ntkinterweb/resources/\ntkinterweb.egg-info\n"
},
{
"path": ".readthedocs.yaml",
"content": "version: \"2\"\n\nbuild:\n os: \"ubuntu-22.04\"\n tools:\n python: \"3.10\"\n\npython:\n install:\n - requirements: docs/requirements.txt\n\nsphinx:\n configuration: docs/source/conf.py"
},
{
"path": "LICENSE.md",
"content": "MIT License\n\nCopyright (c) 2021-2025 Andrew Clarke\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE."
},
{
"path": "MANIFEST.in",
"content": "recursive-include tkinterweb/resources *\r\n"
},
{
"path": "README.md",
"content": "\n \n\n\n\n
\n\n
\n\n**
Fast and lightweight web browser, rich text, and app design widgets for Tkinter.
**\n\n## Overview\n**TkinterWeb adds HTML and CSS rendering capabilities to Tkinter widgets.**\n\nCommon use cases include displaying help files, documentation, and other HTML content, rendering images (including SVG), building rich-text editors, designing apps with HTML templates, and creating more modern-looking interfaces, with advanced styling and even round buttons!\n\nAll [major operating systems](https://tkinterweb.readthedocs.io/en/latest/compatibility.html#a-note-on-tkhtml-binaries) running Python 3.2+ are supported. \n\n## Usage\n\n**TkinterWeb provides:**\n* A [frame widget](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html) to display and edit websites, help files, RSS feeds, and any other styled HTML in Tkinter.\n* A [label widget](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html#tkinterweb.HtmlLabel) that can display styled HTML.\n* A [text widget](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html#tkinterweb.HtmlText) that allows the user to edit styled HTML.\n\n**TkinterWeb can be used in any Tkinter application to display and edit websites, help pages, documentation, and much more! Here is an example:**\n```\nimport tkinter as tk\nfrom tkinterweb import HtmlFrame # import the HtmlFrame widget\n\nroot = tk.Tk() # create the Tkinter window\nframe = HtmlFrame(root, messages_enabled=True) # create the HtmlFrame widget\nframe.load_website(\"https://tkinterweb.readthedocs.io/en/latest/index.html\") # load a website\nframe.pack(fill=\"both\", expand=True) # attach the HtmlFrame widget to the window\nroot.mainloop()\n```\n\n\nSee [Getting Started](https://tkinterweb.readthedocs.io/en/latest/usage.html) for more tips and tricks.\n\n## Installation\nTo install TkinterWeb, simply type `pip install tkinterweb[recommended]` in the command prompt or terminal. That's it!\n\nOr, you can also choose from the following extras: `pip install tkinterweb[html,images,svg,javascript,requests]`. You can also use `pip install tkinterweb[full]` to install all optional dependencies or ``pip install tkinterweb`` to install the bare minimum.\n\n## Dependencies\n\n**TkinterWeb offers bindings and extensions to a modified version of the Tkhtml3 widget from [http://tkhtml.tcl.tk](https://web.archive.org/web/20250219233338/http://tkhtml.tcl.tk/). Tkinter and the [TkinterWeb-Tkhtml](https://pypi.org/project/tkinterweb-tkhtml/) package are required.**\n\nI also **strongly** recommended installing the following:\n* [TkinterWeb-Tkhtml-Extras](https://pypi.org/project/tkinterweb-tkhtml-extras/) (for better HTML/CSS support and bug fixes)\n* [PIL](https://pillow.readthedocs.io/) (for better image support)\n* [PIL.ImageTk](https://pillow.readthedocs.io/en/stable/reference/ImageTk.html)\n\nYou can also choose from the following list for extra functionality:\n* [Brotli](https://github.com/google/brotli) (for faster page loads on some sites)\n* [PythonMonkey](http://pythonmonkey.io/) (for basic JavaScript support)\n* [CairoSVG](https://cairosvg.org/) or [PyGObject](https://pygobject.gnome.org/) (for SVG support)\n\nPip will automatically install dependencies when installing TkinterWeb. PIL.ImageTk should be automatically installed with PIL but might need to installed separately on some systems.\n\n## API Documentation\n\n> [!WARNING]\n> The API changed significantly in version 4.0.0. See [the changelog](https://tkinterweb.readthedocs.io/en/latest/upgrading.html) for details.\n\n**Documentation and additional information on built-in classes can be found in the corresponding API reference pages:**\n* [`tkinterweb.Demo`](https://tkinterweb.readthedocs.io/en/latest/usage.html#installation)\n* [`tkinterweb.HtmlFrame`](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html)\n* [`tkinterweb.HtmlLabel`](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html#tkinterweb.HtmlLabel)\n* [`tkinterweb.HtmlText`](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html#tkinterweb.HtmlText)\n* [`tkinterweb.HtmlParse`](https://tkinterweb.readthedocs.io/en/latest/api/htmlframe.html#tkinterweb.HtmlParse)\n* [`tkinterweb.TkinterWeb`](https://tkinterweb.readthedocs.io/en/latest/api/tkinterweb.html)\n* [`tkinterweb.Notebook`](https://tkinterweb.readthedocs.io/en/latest/api/notebook.html) (a Tkhtml-compatible drop-in replacement for `ttk.Notebook`)\n\n## FAQs\nSee [Frequently Asked Questions](https://tkinterweb.readthedocs.io/en/latest/faq.html).\n\n## Webpage Compatability\n**HTML & CSS:**\n* TkinterWeb supports HTML 4.01 and CSS 2.1. A full list of supported CSS declarations can be found at [http://tkhtml.tcl.tk/support.html](https://web.archive.org/web/20250325123206/http://tkhtml.tcl.tk/support.html).\n* Most CSS pseudo-elements, such as `:hover` and `:active` are also supported. \n* On 64-bit Windows and Linux, if the [TkinterWeb-Tkhtml-Extras](https://pypi.org/project/tkinterweb-tkhtml-extras/) is installed, HTML5 tags and some extra CSS properties (including `border-radius` and `overflow-x`) and cursors are also supported. To use these features on all other platforms, you will simply need to compile Tkhtml yourself. Visit and clone https://github.com/Andereoo/TkinterWeb-Tkhtml. Then run `python compile.py --install`.\n\n**JavaScript:**\n* Javascript only partly supported at the moment.\n * To use JavaScript, PythonMonkey must be installed.\n* It is also possible for the user to connect their own JavaScript interpreter or manipulate the document through Python.\n* See [Using JavaScript](https://tkinterweb.readthedocs.io/en/latest/javascript.html) for more information and [DOM Manipulation with TkinterWeb](https://tkinterweb.readthedocs.io/en/latest/dom.html) for information on manipulating the document through Python.\n\n**Images:**\n* TkinterWeb supports nearly 50 different image types through PIL.\n* In order to load Scalable Vector Graphic images, CairoSVG, both PyCairo and PyGObject, or both PyCairo and Rsvg must also be installed. \n\n## Support & Donations\n**☕ If you’d like to support ongoing development and maintenance, please consider supporting this project by [buying me a coffee](https://buymeacoffee.com/andereoo). Any amount is hugely appreciated!**\n\nThis project is released under the [MIT License](./LICENSE.md) and is free to use, including for commercial purposes.\n\nIf you use this project in a commercial product or derive financial benefit from it, please kindly consider supporting its development with a donation. This helps cover maintenance time and ongoing improvements, which in turn will improve your own software!\n\n## Contributing\n**The best ways to contribute to this project are by submitting a [bug report](https://github.com/Andereoo/TkinterWeb/issues/new) to report bugs or suggest new features, or by submitting a [pull request](https://github.com/Andereoo/TkinterWeb/pulls) to offer fixes. Your help makes TkinterWeb become more stable and full-featured!**\n\nPlease check the [FAQs](https://tkinterweb.readthedocs.io/en/latest/faq.html) and [closed bugs](https://github.com/Andereoo/TkinterWeb/issues?q=is%3Aissue) before submitting a bug report to see if your question as already been answered.\n\n## Credits\n**TkinterWeb is powered by the [Tkhtml project](https://web.archive.org/web/20250219233338/http://tkhtml.tcl.tk/).**\n\nSpecial thanks to [Christopher Chavez](https://github.com/chrstphrchvz), [Zamy846692](https://github.com/Zamy846692), [Jośe Fernando Moyano](https://github.com/jofemodo), [Bumshakalaka](https://github.com/Bumshakalaka), [Trov5](https://github.com/TRVRStash), [Mark Mayo](https://github.com/marksmayo), [Jaedson Silva](https://github.com/jaedsonpys), [Nick Moore](https://github.com/nickzoic), [Leonardo Saurwein](https://github.com/Sau1707), and [Hbregalad](https://github.com/hbregalad) for their code suggestions and pull requests.\n\nSpecial thanks to [Christopher Chavez](https://github.com/chrstphrchvz), Jan Nijtmans, and everyone else in the tcl-core mailing list for the help making border rounding work on Windows and MacOSX, and to [Zamy846692](https://github.com/Zamy846692) for spearheading experimental Tkhtml development.\n\nThanks to the [TkinterHtml package](https://bitbucket.org/aivarannamaa/tkinterhtml) for providing the bindings on which this project is based and the [BRL-CAD project](https://github.com/BRL-CAD/brlcad) for providing modifications for Tkhtml on 64-bit Windows.\n\nA huge thanks to everyone else who supported this project by reporting bugs and providing suggestions!\n"
},
{
"path": "docs/Makefile",
"content": "# Minimal makefile for Sphinx documentation\n#\n\n# You can set these variables from the command line, and also\n# from the environment for the first two.\nSPHINXOPTS ?=\nSPHINXBUILD ?= sphinx-build\nSOURCEDIR = source\nBUILDDIR = build\n\n# Put it first so that \"make\" without argument is like \"make help\".\nhelp:\n\t@$(SPHINXBUILD) -M help \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n\n.PHONY: help Makefile\n\n# Catch-all target: route all unknown targets to Sphinx using the new\n# \"make mode\" option. $(O) is meant as a shortcut for $(SPHINXOPTS).\n%: Makefile\n\t@$(SPHINXBUILD) -M $@ \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n"
},
{
"path": "docs/make.bat",
"content": "@ECHO OFF\r\n\r\npushd %~dp0\r\n\r\nREM Command file for Sphinx documentation\r\n\r\nif \"%SPHINXBUILD%\" == \"\" (\r\n\tset SPHINXBUILD=sphinx-build\r\n)\r\nset SOURCEDIR=source\r\nset BUILDDIR=build\r\n\r\nif \"%1\" == \"\" goto help\r\n\r\n%SPHINXBUILD% >NUL 2>NUL\r\nif errorlevel 9009 (\r\n\techo.\r\n\techo.The 'sphinx-build' command was not found. Make sure you have Sphinx\r\n\techo.installed, then set the SPHINXBUILD environment variable to point\r\n\techo.to the full path of the 'sphinx-build' executable. Alternatively you\r\n\techo.may add the Sphinx directory to PATH.\r\n\techo.\r\n\techo.If you don't have Sphinx installed, grab it from\r\n\techo.http://sphinx-doc.org/\r\n\texit /b 1\r\n)\r\n\r\n%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%\r\ngoto end\r\n\r\n:help\r\n%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%\r\n\r\n:end\r\npopd\r\n"
},
{
"path": "docs/requirements.txt",
"content": "sphinx==7.1.2\nsphinx-rtd-theme==1.3.0rc1\nsphinx_design==0.6.1\ntkinterweb-tkhtml >= 2.0.0\nPillow >= 10.0.0\n"
},
{
"path": "docs/source/_static/custom.css",
"content": "/* This file is used to make tweak the documentation and make it CSS2 compatible.*/\n\n.wy-nav-side {\n overflow: hidden !important;\n}\n\n.wy-side-nav-search > div.version {\n color: #cacaca !important;\n}\n\n.wy-side-nav-search, .wy-nav-top, .note .admonition-title, .wy-menu-vertical a:active {\n background-color: rgb(77, 122, 77) !important;\n}\n\n.wy-nav-content a {\n color: rgb(77, 122, 77);\n}\n\n.wy-nav-content a:hover {\n color: rgb(96, 156, 96);\n}\n\ncode.literal,\nspan.literal {\n color: rgb(94, 94, 94) !important;\n}\n\n.rst-content code.xref,\n.rst-content tt.xref,\na .rst-content code,\na .rst-content tt {\n color: initial !important\n}\n\n.note {\n background-color: rgb(230, 238, 230) !important;\n}\n\n#rtd-search-form input {\n width: 80% !important;\n color: black !important;\n margin-left: auto;\n margin-right: auto;\n}\n\n.wy-breadcrumbs .icon-home:before {\n content: \"Home\" !important;\n font-family: Lato, proxima-nova, Helvetica Neue, Arial, sans-serif !important;\n}\n\n.wy-breadcrumbs .wy-breadcrumbs-aside {\n display: none;\n}\n\n.wy-side-nav-search {\n padding-left: 0 !important;\n padding-right: 0 !important;\n}\n\n.wy-breadcrumbs .breadcrumb-item {\n display: inline !important;\n}\n\n.highlight-python,\n.highlight-console,\n.highlight-default {\n border: 1px solid #e1e4e5 !important;\n margin: 1px 0 24px !important;\n background: #f8f8f8 !important;\n width: 100% !important;\n}\n\n.highlight pre {\n white-space: pre !important;\n margin: 0 !important;\n padding: 12px !important;\n display: block !important;\n}\n\n.highlight {\n border: none !important;\n margin: 0 !important;\n}\n\n.sig-object {\n display: table !important;\n margin: 6px 0 !important;\n margin-top: 6px !important;\n font-size: 90% !important;\n line-height: normal !important;\n background: rgb(230, 238, 230) !important;\n color: rgb(77, 122, 77) !important;\n border-top: 3px solid rgb(101, 145, 101) !important;\n padding: 6px !important;\n position: relative !important;\n}\n\n.sig-object .property,\n.sig-object .sig-param,\n.sig-object .sig-paren {\n font-size: 90% !important;\n line-height: normal !important;\n color: rgb(77, 122, 77) !important;\n}\n\n.sig-object .sig-name,\n.sig-object .sig-prename {\n font-family: SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, Courier New, Courier, monospace !important;\n color: #000 !important;\n}\n\ndd .sig-object {\n margin-bottom: 6px !important;\n border: none !important;\n border-left-width: medium !important;\n border-left-style: none !important;\n border-left-color: currentcolor !important;\n border-left: 3px solid #ccc !important;\n background: #f0f0f0 !important;\n color: #555 !important;\n}\n\ndd .sig-name {\n font-family: SFMono-Regular, Menlo, Monaco, Consolas, Liberation Mono, Courier New, Courier, monospace !important;\n color: #000 !important;\n}\n\ndd .property,\ndd .sig-param,\ndd .sig-paren {\n color: inherit !important\n}\n\n.rst-footer-buttons {\n display: table !important;\n width: 100% !important;\n}\n\n.rst-footer-buttons .float-left {\n display: table-cell !important;\n}\n\n.rst-footer-buttons .float-right {\n display: table-cell !important;\n}\n\n.fa-arrow-circle-right:before {\n content: \" →\" !important;\n}\n\n.fa-arrow-circle-left:before {\n content: \"← \" !important;\n}\n\n.btn {\n border-color: #e1e4e5 !important;\n padding: 6px 12px !important;\n border-bottom: 2px solid #ccc !important;\n box-shadow: none !important;\n transition: none !important;\n}\n\n.btn:active {\n border-top: 2px solid #ccc !important;\n padding: 5px 12px 7px !important;\n border-bottom-width: 1px !important;\n}\n\n.wy-side-nav-search > a {\n padding: 0 !important;\n margin: 0 !important;\n}\n\n.wy-side-nav-search > a:hover {\n background: transparent !important;\n}\n\n.wy-side-nav-search > a img.logo {\n max-width: 250px !important;\n margin: 0 !important;\n}\n\n.sd-card-header {\n display: block;\n}\n\ndetails.sd-dropdown .sd-summary-content p {\n cursor: text;\n}\n\ndetails.sd-dropdown summary.sd-summary-title{\n padding: .5em .6em .5em 1em !important;\n}\n\n.sd-mb-3, .sd-my-3 {\n margin-bottom: 16px !important;\n}\n\n.sd-card-header, .sd-card {\n border-color: #dcdcdc;\n border-radius: 4px;\n}\n\n.sd-card-body {\n padding: 0px 17px !important;\n}\n\n.rst-content .section ul, .rst-content .toctree-wrapper ul, .rst-content section ul, .wy-plain-list-disc, article ul {\n margin: 12px 0px !important;\n}\n\n.sd-card-body > p {\n margin: 12px 0px !important;\n}"
},
{
"path": "docs/source/api/extensions.rst",
"content": "TkinterWeb Extensions\n=====================\n\nThe following objects are extensions to the :class:`~tkinterweb.TkinterWeb` widget and are largely internal. You will likely never need to access them, but they are described here just in case.\n\nThe methods described in this page may change at any time without warning. If you are relying on anything here, please let me know so I know to keep compatibility.\n\n.. autoclass:: tkinterweb.extensions.SelectionManager\n :members:\n\n.. autoclass:: tkinterweb.extensions.CaretManager\n :members:\n\n.. autoclass:: tkinterweb.extensions.EventManager\n :members:\n\n.. autoclass:: tkinterweb.extensions.WidgetManager\n :members:\n\n.. autoclass:: tkinterweb.extensions.SearchManager\n :members:"
},
{
"path": "docs/source/api/htmldocument.rst",
"content": "Document Object Model Documentation\n===================================\n\n.. note::\n The API changed significantly in version 4. See :doc:`the changelog <../upgrading>` for details.\n\nThe methods described in this page make it easy to modify the appearance and content of a loaded document and manage interaction with the document. For the most part, this page mirrors the core JavaScript DOM API.\n\n.. autoclass:: tkinterweb.dom.HTMLDocument\n :members:\n\n.. autoclass:: tkinterweb.dom.HTMLElement\n :members:\n\nThe following JavaScript event properties are also supported: ``onchange``, ``onclick``, ``oncontextmenu``, ``ondblclick``, ``onload``, ``onmousedown``, ``onmouseenter``, ``onmouseleave``, ``onmousemove``, ``onmouseout``, ``onmouseover``, and ``onmouseup``.\n\n.. autoclass:: tkinterweb.dom.HTMLCollection\n :members:\n\n.. autoclass:: tkinterweb.dom.CSSStyleDeclaration\n :members:\n\n.. autoclass:: tkinterweb.dom.DOMRect\n :members:\n\nSpecial thanks to `Zamy846692 `_ for the help making this happen!\n"
},
{
"path": "docs/source/api/htmlframe.rst",
"content": "HTML Widgets Documentation\n==========================\n\n.. note::\n The API changed significantly in version 4. See :doc:`the changelog <../upgrading>` for details.\n\nThe :class:`~tkinterweb.HtmlFrame` widget is a Tkinter frame that provides additional functionality to the :class:`~tkinterweb.TkinterWeb` widget by adding automatic scrollbars, error handling, and many convenience methods into one embeddable and easy to use widget.\n\nThe :class:`~tkinterweb.HtmlFrame` widget is also capable managing other Tkinter widgets, making it easy to combine Tkinter widgets and HTML elements.\n\n\n.. autoclass:: tkinterweb.HtmlFrame\n :members:\n\nThis widget also emits the following Tkinter virtual events that can be bound to:\n\n* ``<>``/:py:attr:`utilities.DOWNLOADING_RESOURCE_EVENT`: Generated whenever a new resource is being downloaded.\n* ``<>``/:py:attr:`utilities.DONE_LOADING_EVENT`: Generated whenever all outstanding resources have been downloaded. This is generally a good indicator as to when the website is done loading, but may be generated multiple times while loading a page.\n* ``<>``/:py:attr:`utilities.DOM_CONTENT_LOADED_EVENT`: Generated once the page content has loaded. The page may not be done loading, but at this point it is possible to interact with the DOM.\n* ``<>``/:py:attr:`utilities.URL_CHANGED_EVENT`: Generated whenever the widget's url changes or redirects. Use :attr:`.HtmlFrame.current_url` to get the url.\n* ``<>``/:py:attr:`utilities.ICON_CHANGED_EVENT`: Generated whenever the icon of a webpage changes. Use :attr:`.HtmlFrame.icon` to get the icon.\n* ``<>``/:py:attr:`utilities.TITLE_CHANGED_EVENT`: Generated whenever the title of a website or file has changed. Use :attr:`.HtmlFrame.title` to get the title.\n* ``<>```/:py:attr:`utilities.FIELD_CHANGED_EVENT`: Generated whenever the content of an interactive element changes.\n\n.. autoclass:: tkinterweb.HtmlLabel\n :members:\n\n.. autoclass:: tkinterweb.HtmlText\n :members:\n\n.. autoclass:: tkinterweb.HtmlParse\n :members:"
},
{
"path": "docs/source/api/jsengine.rst",
"content": "JavaScript Engine Documentation\n===============================\n\n\nThe methods described in this page make it easy to interact with the JavaScript Engine.\n\n.. autoclass:: tkinterweb.js.JSEngine\n :members:\n"
},
{
"path": "docs/source/api/notebook.rst",
"content": "Notebook Documentation\n=======================\n\nThe TkinterWeb :class:`~tkinterweb.Notebook` widget should be used in place of :py:class:`ttk.Notebook`, which is incompatable with Tkhtml on 64-bit Windows and crashes when selecting tabs. See https://docs.python.org/3/library/tkinter.ttk.html#notebook for the full API.\n\n.. autoclass:: tkinterweb.Notebook\n :members:\n\nThis widget also emits the following Tkinter virtual events that can be bound to:\n\n* ``<>``: Generated whenever the selected tab changes.\n"
},
{
"path": "docs/source/api/tkinterweb.rst",
"content": "Internals Documentation\n=======================\n\n.. toctree ::\n :maxdepth: 2\n\n tkinterweb_api\n extensions"
},
{
"path": "docs/source/api/tkinterweb_api.rst",
"content": "Bindings Documentation\n======================\n\n.. note::\n This API has changed significantly recently. See :doc:`the changelog <../upgrading>` for details.\n\n\nThe following objects offer the core bindings to the Tkhtml3 HTML widget and are largely internal. You will likely never need to access them, but they are described here just in case. \n\nRefer to the `Tkhtml Documentation `_ for more details on some of the commands.\n\n.. autoclass:: tkinterweb.TkinterWeb\n :members:\n\n.. autoclass:: tkinterweb.TkHtmlParsedURI\n :members:"
},
{
"path": "docs/source/api.rst",
"content": "API Reference\n==============\n\n.. note::\n The API changed significantly in version 4. See :doc:`the changelog ` for details.\n\n.. toctree::\n :maxdepth: 2\n :caption: Available Classes\n\n api/htmlframe\n api/htmldocument\n api/jsengine\n api/notebook\n\n-------------------\n\n.. toctree::\n :maxdepth: 3\n\n api/tkinterweb"
},
{
"path": "docs/source/caret.rst",
"content": "Making Documents Editable\n=========================\n\n.. note::\n Caret browsing support is new in version 4.8. The :class:`~tkinterweb.HtmlText` widget was made editable in version 4.15. Make sure you are using the latest version of TkinterWeb.\n\nOverview\n--------\n\n**TkinterWeb can be used to create a rich text or HTML editor.**\n\nThe :class:`~tkinterweb.HtmlText` widget provides a simple HTML editor that can be extended to adapt to the needs of your application.\n\nTkinterWeb also provides a useful API for developers to create their own HTML-based what-you-see-is-what-you-get editor.\n\nThese features are new. Please reach out to report a bug, suggest an improvement, or seek support.\n\nSetup\n------\n\nTo enable caret browsing mode, add ``yourhtmlframe.configure(caret_browsing_enabled=True)`` to your script or add the parameter ``caret_browsing_enabled=True`` when creating your :class:`~tkinterweb.HtmlFrame` or :class:`~tkinterweb.HtmlLabel` widget.\n\nWhen enabled, a caret will appear once the user clicks on text in the document. Use the methods described below to handle keypresses, or instead use the :class:`~tkinterweb.HtmlText` widget which handles most cases on its own.\n\nHow-to\n------\n\nSimply create your :class:`~tkinterweb.HtmlText` and start editing!\n\n.. code-block:: python\n\n from tkinterweb import HtmlText\n yourhtmlframe = HtmlText(root, messages_enabled=True)\n\nYou can also load html, files, and websites. For instance, to create an editable page with a heading, an orange block, and a list, you could use the following:\n\n.. code-block:: python\n\n yourhtmlframe = HtmlText(root, messages_enabled=True)\n yourhtmlframe.load_html(\"\"\"
Hello, world!
\n
\n
Tkinter is so cool.
\n
\n
\n
TkinterWeb is also cool
\n
Python is also cool
\n
\"\"\")\n\n.. image:: ./_static/text_widget.png\n\nIt's that easy! \n\nYou can insert and edit hyperlinks, images, and much more. Click on a hyperlink while pressing the Ctrl key to navigate to it. Like the :class:`~tkinterweb.HtmlFrame` widget, the :class:`~tkinterweb.HtmlText` widget is also scrollable out of the box!\n\nYou can also use :meth:`.HtmlText.insert` and :meth:`.HtmlText.delete` to easily modify the document.\n\nCustomization\n-------------\n\nEverything described below applies to all HTML widgets with caret browsing enabled.\n\nUse :meth:`.HtmlFrame.get_caret_position` to get the caret's position. The element returned will always be a text node.\n\n.. tip::\n You can use the methods outlined in the `HTMLElement documentation `_ to get the element's parent if needed. From here you can insert new elements, change the text and much more!\n\nUse :meth:`.HtmlFrame.shift_caret_left` or :meth:`.HtmlFrame.shift_caret_right` to shift the caret left or right.\n\nThe following is a simple example showing how to handle keypresses to insert letters and numbers:\n\n.. code-block:: python\n \n def on_keypress(event):\n # Get the caret's position\n caret_position = yourhtmlframe.get_caret_position()\n if caret_position and event.char:\n element, text, index = caret_position\n \n # Add the key's character to the element's text\n newtext = text[:index] + event.char + text[index:]\n\n # Set the element's text\n element.textContent = newtext\n\n # Shift the caret right\n yourhtmlframe.shift_caret_right()\n\n yourhtmlframe.bind(\"\", on_keypress)\n\nThis works on all HTML widgets.\n\n.. warning::\n If using the :class:`~tkinterweb.HtmlText` widget, binding to ```` will remove all default key bindings. Either bind to individual keys as needed or use ``yourhtmlframe.bind(\"\", on_keypress, add=\"+\")``, but keep in mind then both bindings will fire.\n\n.. note::\n Most HTML elements collapse spaces. To insert a space into the document's text, it is usually best to use a non-breaking space (``\"\\xa0\"`` or ``\" \"``).\n\nUse :meth:`.HtmlFrame.set_caret_position` to set the caret's position if you know the element and index you want to place the caret at.\n\nSome extra logic will be needed to handle other types of keypresses. See the :class:`~tkinterweb.HtmlText` source code for inspiration.\n\n.. tip::\n When handling backspaces at the start of a node or deletions at the end of a node, it is sometimes useful to find the previous or following text nodes, respectively. \n \n You can get the preceeding or following text nodes by using :meth:`.HtmlFrame.shift_caret_left` or :meth:`.HtmlFrame.shift_caret_right` followed by :meth:`.HtmlFrame.get_caret_position`.\n\nUse :meth:`.HtmlFrame.get_selection_position` to get the position of any selected text and :meth:`.HtmlFrame.clear_selection` to clear the selection. \n\nYou may need to set the caret's position after modifying the document.\n\n.. tip::\n :meth:`.HtmlFrame.set_caret_position` will raise an error if the element provided has been removed or is empty. \n \n If you need to remove or empty the elements returned by :meth:`.HtmlFrame.get_selection_position` or :meth:`.HtmlFrame.get_caret_position`, you can also get the selection or caret's position relative to the page text content using :meth:`HtmlFrame.get_selection_position(return_elements=False) <.HtmlFrame.get_selection_position>` and :meth:`HtmlFrame.get_caret_position(return_element=False) <.HtmlFrame.get_caret_position>`, respectively.\n\n You can then set the selection or caret's position as usual, providing only indexes (i.e. ``yourhtmlframe.set_selection_position(start_index=5, end_index=10)``.\n\n\nThe following code can be used as a starting point on handling backspaces when text is selected:\n\n.. code-block:: python\n\n def on_backspace(event):\n # Get the selection's position and deselect all selected text\n selection = yourhtmlframe.get_selection_position()\n\n if selection:\n start, end, middle = selection\n start_element, start_element_text, start_element_index = start\n end_element, end_element_text, end_element_index = end\n\n # Deselect all selected text\n d.clear_selection()\n\n # Cut out the selection\n start_element.textContent = start_element_text[:start_element_index] + start_element_text[end_element_index:]\n\n if start_element != end_element:\n # Delete the end element\n end_element.remove()\n\n # Remove each element that is fully selected, and its parent if it is now empty\n for element in middle:\n parent = element.parentElement\n element.remove()\n if len(parent.children) == 0:\n parent.remove()\n\n # Set the caret's position\n yourhtmlframe.set_caret_position(start_element, start_element_index)\n\n yourhtmlframe.bind(\"\", on_backspace)\n\nYou can use :meth:`.HtmlFrame.set_selection_position` to set the selection if needed.\n\n-------------------\n\nSee the `HtmlFrame documentation `_ for a complete list of supported methods.\n\nPlease report bugs or request new features on the `issues page `_."
},
{
"path": "docs/source/compatibility.rst",
"content": "System and Webpage Compatibility\n================================\n\nSystem compatibility\n--------------------\n\n**TkinterWeb supports all platforms but only ships with precompiled Tkhtml binaries for the most common platforms:**\n\n* x86_64 Windows, Linux, and macOS\n* i686 Windows and Linux\n* ARM64 Macos and Linux\n* ARMv71 Linux\n\nIf your system is unsupported, compile and install Tkhtml by visiting and cloning https://github.com/Andereoo/TkinterWeb-Tkhtml. Then run ``python compile.py --install``.\n\nAlternatively, you can install Tkhtml system-wide (i.e. through your system package manager) and then add the parameter :attr:`use_prebuilt_tkhtml=False` when creating your :class:`~tkinterweb.HtmlFrame`, :class:`~tkinterweb.HtmlLabel`, or :class:`~tkinterweb.HtmlText` widget to use the system's Tkhtml. Keep in mind that some features will no longer work.\n\nIf you are encountering issues, feel free to submit a bug report or feature request.\n\nThe experimental Tkhtml version is not provided as a pre-built binary but can be compiled from the source code at https://github.com/Andereoo/TkinterWeb-Tkhtml/tree/experimental. This version has better cross-platform compatibility, is printable, and introduces support for some new CSS3 properties!\n\nWebpage compatibility\n---------------------\n\n**HTML & CSS:**\n\n* TkinterWeb supports HTML 4.01 and CSS 2.1. A full list of supported CSS declarations can be found at `http://tkhtml.tcl.tk/support.html `_.\n* Most CSS pseudo-elements, such as ``:hover`` and ``:active`` are also supported.\n* On 64-bit Windows and Linux, if the `TkinterWeb-Tkhtml-Extras `_ package is installed, HTML5 tags and some extra CSS properties (including ``border-radius`` and ``overflow-x``) and cursors are also supported. To use these features on all other platforms, you will simply need to compile Tkhtml yourself. Visit and clone https://github.com/Andereoo/TkinterWeb-Tkhtml. Then run ``python compile.py --install``.\n\n**JavaScript:**\n\n* JavaScript partly supported at the moment. See :doc:`javascript` for more information.\n\n * To use JavaScript, `PythonMonkey `_ must be installed.\n\n* It is also possible for the user to connect their own JavaScript interpreter or manipulate the document through Python. See :doc:`javascript` and :doc:`dom` for more information.\n\n**Images:**\n\n* TkinterWeb supports nearly 50 different image types through `PIL `_.\n\n* In order to load Scalable Vector Graphic images, `CairoSVG `_, `PyGObject `_, or both :py:mod:`PyCairo` and :py:mod:`Rsvg` must also be installed. \n\n-------------------\n\nPlease report bugs or request new features on the `issues page `_."
},
{
"path": "docs/source/conf.py",
"content": "# Configuration file for the Sphinx documentation builder.\n\n# -- Project information\n\nimport os\nimport sys\n\nsys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname((os.path.realpath(__file__))))))\n\nfrom tkinterweb import __title__, __copyright__, __author__, __version__\n\nproject = __title__\ncopyright = __copyright__\nauthor = __author__\n\nrelease = \".\".join(__version__.split(\".\")[:2])\nversion = __version__\n\n# -- General configuration\n\nextensions = [\n 'sphinx.ext.duration',\n 'sphinx.ext.doctest',\n 'sphinx.ext.autodoc',\n 'sphinx.ext.autosummary',\n 'sphinx.ext.intersphinx',\n \"sphinx_design\",\n]\n\nintersphinx_mapping = {\n 'python': ('https://docs.python.org/3/', None),\n 'sphinx': ('https://www.sphinx-doc.org/en/master/', None),\n}\n\nhtml_logo = \"_static/logo.png\"\nhtml_theme_options = {\"logo_only\": True}\ntemplates_path = ['_templates']\n\nhtml_static_path = ['_static']\nhtml_css_files = ['custom.css']\n\n# -- Options for HTML output\n\nautodoc_member_order = 'bysource'\n\nhtml_theme = 'sphinx_rtd_theme' # May switch to agogo or alabaster or python_docs_theme\n\n# -- Options for EPUB output\nepub_show_urls = 'footnote'\n\ndef skip_member(app, what, name, obj, skip, options):\n if name == \"destroy\" and what == \"class\":\n return True\n return skip\n\ndef setup(app):\n app.connect(\"autodoc-skip-member\", skip_member)"
},
{
"path": "docs/source/dom.rst",
"content": "Manipulating the Page\n=====================\n\n.. note::\n The API changed significantly in version 4. See :doc:`the changelog ` for details.\n\nOverview\n--------\n\n**TkinterWeb provides a handful of functions that allow for manipulation of the webpage. They are fashioned after common JavaScript functions.**\n\n\nHow-to\n--------\n\nTo manipulate the Document Object Model, use the :attr:`~tkinterweb.HtmlFrame.document` property of your :class:`~tkinterweb.HtmlFrame` or :class:`~tkinterweb.HtmlLabel` widget. For example, to create a heading with blue text inside of an element with the id \"container\", one can use the following:\n\n.. code-block:: python\n\n yourhtmlframe = tkinterweb.HtmlFrame(root, messages_enabled=True)\n yourhtmlframe.load_html(\"
Test
\")\n container = yourhtmlframe.document.getElementById(\"container\")\n new_header = yourhtmlframe.document.createElement(\"h1\")\n new_header.textContent = \"Hello, world!\"\n new_header.style.color = \"blue\"\n container.appendChild(new_header)\n\n\n.. _binding-to-an-element:\n\nBinding to an element\n---------------------\n\nTo manage bindings on HTML elements, simply use :meth:`~tkinterweb.dom.HTMLElement.bind` and :meth:`~tkinterweb.dom.HTMLElement.unbind` (new in version 4.9):\n\n.. code-block:: python\n\n container = yourhtmlframe.document.getElementById(\"container\")\n\n def callback(event):\n print(\"Woah this is cool!\")\n\n container.bind(\"\", callback)\n\n-------------------\n\nSee the :doc:`api/htmldocument` for a complete list of supported commands.\n\nSee :doc:`javascript` for information on manipulating the DOM through JavaScript.\n\nPlease report bugs or request new features on the `issues page `_."
},
{
"path": "docs/source/faq.rst",
"content": "Frequently Asked Questions\n==========================\n\nHow do I load websites or files?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* Use the :meth:`~tkinterweb.HtmlFrame.load_website` or :meth:`~tkinterweb.HtmlFrame.load_file` commands. Alternatively, use the :meth:`~tkinterweb.HtmlFrame.load_url` command to load any generic url, but keep in mind that the url must be properly formatted, because the url scheme will not be automatically applied. As always, check out the :doc:`api/htmlframe` for more information.\n\nHow do I manage clicks and use custom bindings?\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* The :attr:`on_link_click` configuration option can be used to assign a custom function to link clicks. Likewise :attr:`on_form_submit` can be used to handle form submissions. See the :doc:`api/htmlframe` for more information.\n* Like any other Tkinter widget, mouse and keyboard events can be bound to the :class:`~tkinterweb.HtmlFrame` widget and associated HTML elements. See the :doc:`usage` page for more information.\n \nTkinterWeb is crashing\n~~~~~~~~~~~~~~~~~~~~~~\n\n* That is defenitely not normal. Make sure your are using the most up-to-date TkinterWeb version and have crash protection enabled.\n* If you are using a :py:class:`ttk.Notebook` in your app, see the question below.\n* If all else fails, `file a bug report `_. Post your operating system, Python version, and TkinterWeb version, as well as any error codes or instructions for reproducing the crash.\n\nI'm having issues when using shrink or the HtmlLabel widget\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* See :doc:`shrink` for more information.\n\nMy app crashes when I open a tab with an HtmlFrame in it\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* Tkhtml (the underlying HTML engine) and the :py:class:`ttk.Notebook` widget aren't compatable on 64-bit Windows.\n* This is a known issue. Fixing this is beyond the scope of this project, but working around it is easy.\n* Instead of using :py:class:`ttk.Notebook`, use :class:`tkinterweb.Notebook`. This is a wrapper around ttk.Notebook that is designed to be a drop-in replacement for the :py:class:`ttk.Notebook` widget. It should look and behave exactly like a :py:class:`ttk.Notebook` widget, but without the crashes. See `bug #19 `_ for more information.\n* Please note that after adding a widget to the Notebook (eg. ``mynotebook.add(mywidget)``) there is no need to call :py:func:`~tkinterweb.Widget.pack` or :py:func:`~tkinterweb.Widget.grid` the widget. This may raise errors. TkinterWeb's Notebook widget handles all this on its own.\n\nI get a ModuleNotFoundError after compiling my code\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n* When compiling your code, you might get an error popup saying ``ModuleNotFoundError: The files required to run TkinterWeb could not be found``\n* Your app might also fail quietly if TkinterWeb's dependencies are not installed\n* This occurs when your Python script bundler isn't finding all the files nessessary for running TkinterWeb. You need to force it to get all of TkinterWeb's files and dependencies.\n* On PyInstaller: make sure you are using the latest version of PyInstaller by running ``pip install --upgrade pyinstaller pyinstaller-hooks-contrib``. Otherwise, you can also add the flags ``--collect-all tkinterweb --collect-all tkinterweb_tkhtml --collect-all tkinterweb_tkhtml_extras`` when bundling your app.\n* On py2app / py2exe: Add ``'packages': ['tkinterweb', 'tkinterweb_tkhtml', 'tkinterweb_tkhtml_extras']`` to the ``OPTIONS`` variable in your setup file.\n\n-------------------\n\nPlease report bugs or request new features on the `issues page `_.\n"
},
{
"path": "docs/source/geometry.rst",
"content": "Embedding Widgets\n=================\n\n.. note::\n The API changed significantly in version 4. See :doc:`the changelog ` for details.\n\nOverview\n--------\n\nBy default, Tkinter provides three geometry managers: pack, place, and grid. While these geometry managers are very powerful, achieving certain layouts, especially with scrolling, can be very difficult.\n\n**TkinterWeb provides a system for attaching Tkinter widgets onto the window, and handles layouts, images, selection, scrolling, and much more for you.**\n\nHow-to\n------\n\nTo place a Tkinter widget inside an HTML document, add the ``data=[yourwidget]`` attribute to an ``
![\"Buy](\"https://cdn.buymeacoffee.com/buttons/v2/default-violet.png\")
![](\"./docs/source/_static/banner.png\")