# Gaphas
[](https://github.com/gaphor/gaphas/actions)
[](https://codeclimate.com/github/gaphor/gaphas/maintainability)
[](https://codeclimate.com/github/gaphor/gaphas/test_coverage)
[](https://github.com/RichardLitt/standard-readme)
[](https://matrix.to/#/#gaphor_Lobby:gitter.im)
[](#contributors)
> Gaphas is the diagramming widget library for Python.
Gaphas is a library that provides the user interface component (widget) for drawing diagrams. Diagrams can be drawn to screen and then easily exported to a variety of formats, including SVG and PDF. Want to build an app with chart-like diagrams? Then Gaphas is for you! Use this library to build a tree, network, flowchart, or other diagrams.
This library is currently being used by [Gaphor](https://github.com/gaphor/gaphor) for UML drawing,
[RAFCON](https://github.com/DLR-RM/RAFCON) for state-machine based robot control, and [ASCEND](http://ascend4.org/) for solving mathematical models.
## 📑 Table of Contents
- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
## 📜 Background
Gaphas was built to provide the foundational diagramming portions of [Gaphor](https://github.com/gaphor/gaphor). Since Gaphor is built on GTK and Cairo, [PyGObject](https://pygobject.readthedocs.io/) provides access to the GUI toolkit and [PyCairo](https://pycairo.readthedocs.io/) to the 2D graphics library. However, there wasn't a project that abstracted these technologies to easily create a diagramming tool. Hence, Gaphas was created as a library to allow others to create a diagramming tool using GTK and Cairo.
Here is how it works:
- Items (Canvas items) can be added to a Canvas.
- The Canvas maintains the tree structure (parent-child relationships between items).
- A constraint solver is used to maintain item constraints and inter-item constraints.
- The item (and user) should not be bothered with things like bounding-box calculations.
- Very modular--e.g., handle support could be swapped in and swapped out.
- Rendering using Cairo.
The main portions of the library include:
- canvas - The main canvas class (container for Items).
- items - Objects placed on a Canvas.
- solver - A constraint solver to define the layout and connection of items.
- gtkview - A view to be used in GTK applications that interacts with users with tools.
- painters - The workers used to paint items.
- tools - Tools are used to handle user events (such as mouse movement and button presses).
- aspects - Provides an intermediate step between tools and items.
Gaphas contains default implementations for `Canvas` and `Item`s. There are protocols in place
to allow you to make your own canvas.
## 💾 Install
To install Gaphas, simply use pip:
```bash
$ pip install gaphas
```
Use of a
[virtual environment](https://virtualenv.pypa.io/en/latest/) is highly recommended.
### Development
To setup a development environment with Linux:
```bash
$ sudo apt-get install -y python3-dev python3-gi python3-gi-cairo
gir1.2-gtk-3.0 libgirepository1.0-dev libcairo2-dev
$ pip install poetry
$ poetry install
```
## 🔦 Usage
API docs and tutorials can be found on [Read the Docs](https://gaphas.readthedocs.io).
## ♥ Contributing
Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore -->
<table><tr><td align="center"><a href="https://github.com/amolenaar"><img src="https://avatars0.githubusercontent.com/u/96249?v=4" width="100px;" alt="Arjan Molenaar"/><br /><sub><b>Arjan Molenaar</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=amolenaar" title="Code">💻</a> <a href="https://github.com/gaphor/gaphas/issues?q=author%3Aamolenaar" title="Bug reports">🐛</a> <a href="https://github.com/gaphor/gaphas/commits?author=amolenaar" title="Documentation">📖</a> <a href="#review-amolenaar" title="Reviewed Pull Requests">👀</a> <a href="#question-amolenaar" title="Answering Questions">💬</a> <a href="#plugin-amolenaar" title="Plugin/utility libraries">🔌</a></td><td align="center"><a href="https://ghuser.io/danyeaw"><img src="https://avatars1.githubusercontent.com/u/10014976?v=4" width="100px;" alt="Dan Yeaw"/><br /><sub><b>Dan Yeaw</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=danyeaw" title="Code">💻</a> <a href="https://github.com/gaphor/gaphas/commits?author=danyeaw" title="Tests">⚠️</a> <a href="#review-danyeaw" title="Reviewed Pull Requests">👀</a> <a href="https://github.com/gaphor/gaphas/issues?q=author%3Adanyeaw" title="Bug reports">🐛</a> <a href="#question-danyeaw" title="Answering Questions">💬</a> <a href="#infra-danyeaw" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a> <a href="https://github.com/gaphor/gaphas/commits?author=danyeaw" title="Documentation">📖</a></td><td align="center"><a href="https://github.com/wrobell"><img src="https://avatars2.githubusercontent.com/u/105664?v=4" width="100px;" alt="wrobell"/><br /><sub><b>wrobell</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=wrobell" title="Code">💻</a> <a href="https://github.com/gaphor/gaphas/commits?author=wrobell" title="Tests">⚠️</a> <a href="#review-wrobell" title="Reviewed Pull Requests">👀</a></td><td align="center"><a href="https://github.com/jlstevens"><img src="https://avatars3.githubusercontent.com/u/890576?v=4" width="100px;" alt="Jean-Luc Stevens"/><br /><sub><b>Jean-Luc Stevens</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=jlstevens" title="Code">💻</a> <a href="https://github.com/gaphor/gaphas/issues?q=author%3Ajlstevens" title="Bug reports">🐛</a> <a href="https://github.com/gaphor/gaphas/commits?author=jlstevens" title="Documentation">📖</a></td><td align="center"><a href="http://www.franework.de"><img src="https://avatars1.githubusercontent.com/u/1144966?v=4" width="100px;" alt="Franz Steinmetz"/><br /><sub><b>Franz Steinmetz</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=franzlst" title="Code">💻</a> <a href="https://github.com/gaphor/gaphas/issues?q=author%3Afranzlst" title="Bug reports">🐛</a></td><td align="center"><a href="https://github.com/adrianboguszewski"><img src="https://avatars3.githubusercontent.com/u/4547501?v=4" width="100px;" alt="Adrian Boguszewski"/><br /><sub><b>Adrian Boguszewski</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=adrianboguszewski" title="Code">💻</a></td><td align="center"><a href="https://github.com/Rbelder"><img src="https://avatars3.githubusercontent.com/u/15119522?v=4" width="100px;" alt="Rico Belder"/><br /><sub><b>Rico Belder</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/issues?q=author%3ARbelder" title="Bug reports">🐛</a> <a href="#review-Rbelder" title="Reviewed Pull Requests">👀</a></td></tr><tr><td align="center"><a href="http://www.boduch.ca"><img src="https://avatars2.githubusercontent.com/u/114619?v=4" width="100px;" alt="Adam Boduch"/><br /><sub><b>Adam Boduch</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/issues?q=author%3Aadamboduch" title="Bug reports">🐛</a></td><td align="center"><a href="https://github.com/janettech"><img src="https://avatars3.githubusercontent.com/u/13398384?v=4" width="100px;" alt="Janet Jose"/><br /><sub><b>Janet Jose</b></sub></a><br /><a href="https://github.com/gaphor/gaphas/commits?author=janettech" title="Documentation">📖</a></td></tr></table>
<!-- ALL-CONTRIBUTORS-LIST:END -->
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind are welcome!
1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
There is a [first-timers-only](https://github.com/gaphor/gaphas/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Afirst-timers-only) tag for issues that should be ideal for people who are not very familiar with the codebase yet.
2. Fork [the repository](https://github.com/gaphor/gaphas) on GitHub to start making your changes to the **main** branch (or branch off of it).
3. Write a test which shows that the bug was fixed or that the feature
works as expected.
4. Send a pull request and bug the maintainers until it gets merged and
published. :smile:
See [the contributing file](CONTRIBUTING.md)!
## © License
Copyright © Arjan Molenaar and Dan Yeaw
Licensed under the [Apache License 2.0](LICENSE).
Summary: You can do what you like with Gaphas, as long as you include the required notices. This permissive license contains a patent license from the contributors of the code.
Raw data
{
"_id": null,
"home_page": "https://gaphas.readthedocs.io/",
"name": "gaphas",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4",
"maintainer_email": "",
"keywords": "gtk,diagram,gaphas",
"author": "Arjan J. Molenaar",
"author_email": "gaphor@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/85/ba/4a20056c4c66cfd921ad69fb9449978c65c322d809f0ff2a6c39476dc911/gaphas-4.0.0.tar.gz",
"platform": null,
"description": "# Gaphas\n[](https://github.com/gaphor/gaphas/actions)\n[](https://codeclimate.com/github/gaphor/gaphas/maintainability)\n[](https://codeclimate.com/github/gaphor/gaphas/test_coverage)\n\n[](https://github.com/RichardLitt/standard-readme)\n[](https://matrix.to/#/#gaphor_Lobby:gitter.im)\n[](#contributors)\n\n> Gaphas is the diagramming widget library for Python.\n\n\n\nGaphas is a library that provides the user interface component (widget) for drawing diagrams. Diagrams can be drawn to screen and then easily exported to a variety of formats, including SVG and PDF. Want to build an app with chart-like diagrams? Then Gaphas is for you! Use this library to build a tree, network, flowchart, or other diagrams.\n\nThis library is currently being used by [Gaphor](https://github.com/gaphor/gaphor) for UML drawing,\n[RAFCON](https://github.com/DLR-RM/RAFCON) for state-machine based robot control, and [ASCEND](http://ascend4.org/) for solving mathematical models.\n\n## \ud83d\udcd1 Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## \ud83d\udcdc Background\n\nGaphas was built to provide the foundational diagramming portions of [Gaphor](https://github.com/gaphor/gaphor). Since Gaphor is built on GTK and Cairo, [PyGObject](https://pygobject.readthedocs.io/) provides access to the GUI toolkit and [PyCairo](https://pycairo.readthedocs.io/) to the 2D graphics library. However, there wasn't a project that abstracted these technologies to easily create a diagramming tool. Hence, Gaphas was created as a library to allow others to create a diagramming tool using GTK and Cairo.\n\nHere is how it works:\n\n- Items (Canvas items) can be added to a Canvas.\n- The Canvas maintains the tree structure (parent-child relationships between items).\n- A constraint solver is used to maintain item constraints and inter-item constraints.\n- The item (and user) should not be bothered with things like bounding-box calculations.\n- Very modular--e.g., handle support could be swapped in and swapped out.\n- Rendering using Cairo.\n\nThe main portions of the library include:\n\n- canvas - The main canvas class (container for Items).\n- items - Objects placed on a Canvas.\n- solver - A constraint solver to define the layout and connection of items.\n- gtkview - A view to be used in GTK applications that interacts with users with tools.\n- painters - The workers used to paint items.\n- tools - Tools are used to handle user events (such as mouse movement and button presses).\n- aspects - Provides an intermediate step between tools and items.\n\nGaphas contains default implementations for `Canvas` and `Item`s. There are protocols in place\nto allow you to make your own canvas.\n\n## \ud83d\udcbe Install\n\nTo install Gaphas, simply use pip:\n\n```bash\n$ pip install gaphas\n```\n\nUse of a\n[virtual environment](https://virtualenv.pypa.io/en/latest/) is highly recommended.\n\n### Development\n\nTo setup a development environment with Linux:\n\n```bash\n$ sudo apt-get install -y python3-dev python3-gi python3-gi-cairo\n gir1.2-gtk-3.0 libgirepository1.0-dev libcairo2-dev\n$ pip install poetry\n$ poetry install\n```\n\n## \ud83d\udd26 Usage\n\nAPI docs and tutorials can be found on [Read the Docs](https://gaphas.readthedocs.io).\n\n## \u2665 Contributing\n\nThanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):\n\n<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->\n<!-- prettier-ignore -->\n<table><tr><td align=\"center\"><a href=\"https://github.com/amolenaar\"><img src=\"https://avatars0.githubusercontent.com/u/96249?v=4\" width=\"100px;\" alt=\"Arjan Molenaar\"/><br /><sub><b>Arjan Molenaar</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=amolenaar\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/gaphor/gaphas/issues?q=author%3Aamolenaar\" title=\"Bug reports\">\ud83d\udc1b</a> <a href=\"https://github.com/gaphor/gaphas/commits?author=amolenaar\" title=\"Documentation\">\ud83d\udcd6</a> <a href=\"#review-amolenaar\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"#question-amolenaar\" title=\"Answering Questions\">\ud83d\udcac</a> <a href=\"#plugin-amolenaar\" title=\"Plugin/utility libraries\">\ud83d\udd0c</a></td><td align=\"center\"><a href=\"https://ghuser.io/danyeaw\"><img src=\"https://avatars1.githubusercontent.com/u/10014976?v=4\" width=\"100px;\" alt=\"Dan Yeaw\"/><br /><sub><b>Dan Yeaw</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=danyeaw\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/gaphor/gaphas/commits?author=danyeaw\" title=\"Tests\">\u26a0\ufe0f</a> <a href=\"#review-danyeaw\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a> <a href=\"https://github.com/gaphor/gaphas/issues?q=author%3Adanyeaw\" title=\"Bug reports\">\ud83d\udc1b</a> <a href=\"#question-danyeaw\" title=\"Answering Questions\">\ud83d\udcac</a> <a href=\"#infra-danyeaw\" title=\"Infrastructure (Hosting, Build-Tools, etc)\">\ud83d\ude87</a> <a href=\"https://github.com/gaphor/gaphas/commits?author=danyeaw\" title=\"Documentation\">\ud83d\udcd6</a></td><td align=\"center\"><a href=\"https://github.com/wrobell\"><img src=\"https://avatars2.githubusercontent.com/u/105664?v=4\" width=\"100px;\" alt=\"wrobell\"/><br /><sub><b>wrobell</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=wrobell\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/gaphor/gaphas/commits?author=wrobell\" title=\"Tests\">\u26a0\ufe0f</a> <a href=\"#review-wrobell\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a></td><td align=\"center\"><a href=\"https://github.com/jlstevens\"><img src=\"https://avatars3.githubusercontent.com/u/890576?v=4\" width=\"100px;\" alt=\"Jean-Luc Stevens\"/><br /><sub><b>Jean-Luc Stevens</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=jlstevens\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/gaphor/gaphas/issues?q=author%3Ajlstevens\" title=\"Bug reports\">\ud83d\udc1b</a> <a href=\"https://github.com/gaphor/gaphas/commits?author=jlstevens\" title=\"Documentation\">\ud83d\udcd6</a></td><td align=\"center\"><a href=\"http://www.franework.de\"><img src=\"https://avatars1.githubusercontent.com/u/1144966?v=4\" width=\"100px;\" alt=\"Franz Steinmetz\"/><br /><sub><b>Franz Steinmetz</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=franzlst\" title=\"Code\">\ud83d\udcbb</a> <a href=\"https://github.com/gaphor/gaphas/issues?q=author%3Afranzlst\" title=\"Bug reports\">\ud83d\udc1b</a></td><td align=\"center\"><a href=\"https://github.com/adrianboguszewski\"><img src=\"https://avatars3.githubusercontent.com/u/4547501?v=4\" width=\"100px;\" alt=\"Adrian Boguszewski\"/><br /><sub><b>Adrian Boguszewski</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=adrianboguszewski\" title=\"Code\">\ud83d\udcbb</a></td><td align=\"center\"><a href=\"https://github.com/Rbelder\"><img src=\"https://avatars3.githubusercontent.com/u/15119522?v=4\" width=\"100px;\" alt=\"Rico Belder\"/><br /><sub><b>Rico Belder</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/issues?q=author%3ARbelder\" title=\"Bug reports\">\ud83d\udc1b</a> <a href=\"#review-Rbelder\" title=\"Reviewed Pull Requests\">\ud83d\udc40</a></td></tr><tr><td align=\"center\"><a href=\"http://www.boduch.ca\"><img src=\"https://avatars2.githubusercontent.com/u/114619?v=4\" width=\"100px;\" alt=\"Adam Boduch\"/><br /><sub><b>Adam Boduch</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/issues?q=author%3Aadamboduch\" title=\"Bug reports\">\ud83d\udc1b</a></td><td align=\"center\"><a href=\"https://github.com/janettech\"><img src=\"https://avatars3.githubusercontent.com/u/13398384?v=4\" width=\"100px;\" alt=\"Janet Jose\"/><br /><sub><b>Janet Jose</b></sub></a><br /><a href=\"https://github.com/gaphor/gaphas/commits?author=janettech\" title=\"Documentation\">\ud83d\udcd6</a></td></tr></table>\n\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nThis project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind are welcome!\n\n1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.\n There is a [first-timers-only](https://github.com/gaphor/gaphas/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Afirst-timers-only) tag for issues that should be ideal for people who are not very familiar with the codebase yet.\n2. Fork [the repository](https://github.com/gaphor/gaphas) on GitHub to start making your changes to the **main** branch (or branch off of it).\n3. Write a test which shows that the bug was fixed or that the feature\n works as expected.\n4. Send a pull request and bug the maintainers until it gets merged and\n published. :smile:\n\nSee [the contributing file](CONTRIBUTING.md)!\n\n## \u00a9 License\n\nCopyright \u00a9 Arjan Molenaar and Dan Yeaw\n\nLicensed under the [Apache License 2.0](LICENSE).\n\nSummary: You can do what you like with Gaphas, as long as you include the required notices. This permissive license contains a patent license from the contributors of the code.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Gaphas is a GTK diagramming widget",
"version": "4.0.0",
"project_urls": {
"Documentation": "https://gaphas.readthedocs.io/",
"Homepage": "https://gaphas.readthedocs.io/",
"Repository": "https://github.com/gaphor/gaphas"
},
"split_keywords": [
"gtk",
"diagram",
"gaphas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ba8cb06f27ad23e5de05c9235ad9616466b06ecdd21cd288071b692d6eabb6d",
"md5": "1f401ba5632bc2851dbb094ae9bf455c",
"sha256": "ef68df99c75943172c8ebf80840a60fb6ff2f7ae73330d4cd8f90da086380d15"
},
"downloads": -1,
"filename": "gaphas-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f401ba5632bc2851dbb094ae9bf455c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4",
"size": 76080,
"upload_time": "2023-12-29T21:46:03",
"upload_time_iso_8601": "2023-12-29T21:46:03.672757Z",
"url": "https://files.pythonhosted.org/packages/5b/a8/cb06f27ad23e5de05c9235ad9616466b06ecdd21cd288071b692d6eabb6d/gaphas-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85ba4a20056c4c66cfd921ad69fb9449978c65c322d809f0ff2a6c39476dc911",
"md5": "1a91e98fe771cf632fe4bfed13f381ce",
"sha256": "c780956368bf4828eafdcd577f1de0771ee34e29acd5a29dd39ce23780dd1358"
},
"downloads": -1,
"filename": "gaphas-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "1a91e98fe771cf632fe4bfed13f381ce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4",
"size": 63875,
"upload_time": "2023-12-29T21:46:05",
"upload_time_iso_8601": "2023-12-29T21:46:05.659577Z",
"url": "https://files.pythonhosted.org/packages/85/ba/4a20056c4c66cfd921ad69fb9449978c65c322d809f0ff2a6c39476dc911/gaphas-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-29 21:46:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gaphor",
"github_project": "gaphas",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gaphas"
}
JSON
