| 1 |
# Overview |
| 2 |
|
| 3 |
`app-model` is a declarative, backend-agnostic schema for a GUI-based application. |
| 4 |
|
| 5 |
The primary goal of this library is to provide a set of types that enable |
| 6 |
an application developer to declare the commands, keybindings, macros, etc. |
| 7 |
that make up their application. |
| 8 |
|
| 9 |
## Installation |
| 10 |
|
| 11 |
Install from pip |
| 12 |
|
| 13 |
```bash |
| 14 |
pip install app-model |
| 15 |
``` |
| 16 |
|
| 17 |
Or from conda-forge |
| 18 |
|
| 19 |
```bash |
| 20 |
conda install -c conda-forge app-model |
| 21 |
``` |
| 22 |
|
| 23 |
## Usage |
| 24 |
|
| 25 |
See the [Getting Started](getting_started.md) guide for a quick introduction to |
| 26 |
`app-model`. See the [API Reference](reference/index.md) for a complete |
| 27 |
reference of the types and functions provided by `app-model`. |
| 28 |
|
| 29 |
## Motivation |
| 30 |
|
| 31 |
Why bother with a declarative application model? |
| 32 |
|
| 33 |
1. **It's easier to query the application's state** |
| 34 |
|
| 35 |
If you want to ask "what commands are available in this application?", or |
| 36 |
"what items are currently in a given menu", you can directly query the |
| 37 |
application registries. For example, you don't need to find a specific |
| 38 |
`QMenu` instance and iterate its `actions()` to know whether a given item is |
| 39 |
present. |
| 40 |
|
| 41 |
1. **It's easier to modify the application's state** |
| 42 |
|
| 43 |
For applications that need to be dynamic (e.g. adding and removing menu |
| 44 |
items and actions as plugins are loaded and unloaded), it is convenient to |
| 45 |
have an application model that emits events when modified, with the "view" |
| 46 |
(the actual GUI framework) responding to those events to update the actual |
| 47 |
presentation. |
| 48 |
|
| 49 |
1. **It decouples the structure of the application from the GUI framework** |
| 50 |
|
| 51 |
This makes it easier to change the GUI framework without having to change the |
| 52 |
application. (Obviously, as an application grows with a particular framework, |
| 53 |
it does become harder to extract, but having a loosely coupled model is a step |
| 54 |
in the right direction) |
| 55 |
|
| 56 |
1. **It's easier to test** |
| 57 |
|
| 58 |
`app-model` itself is comprehensively tested. By avoiding a number of |
| 59 |
one-off procedurally created menus, we can test reusable *patterns* of |
| 60 |
command/menu/keybinding creation and registration. |
| 61 |
|
| 62 |
## GUI Frameworks |
| 63 |
|
| 64 |
`app-model` is framework-agnostic, and can be used with any GUI toolkit, but |
| 65 |
[Qt](https://www.qt.io) is currently the primary target, and a |
| 66 |
[Qt adapter][app_model.backends.qt] comes with this library. |
| 67 |
|
| 68 |
See some details in the [qt section](getting_started.md#qt) of the getting |
| 69 |
started guide. |
| 70 |
|
| 71 |
## Example Application |
| 72 |
|
| 73 |
For a working example of a QApplication built with and without `app-model`, |
| 74 |
compare |
| 75 |
[`demo/model_app.py`](https://github.com/pyapp-kit/app-model/blob/main/demo/model_app.py) |
| 76 |
to |
| 77 |
[`demo/qapplication.py`](https://github.com/pyapp-kit/app-model/blob/main/demo/qapplication.py) |
| 78 |
in the `demo` directory of the `app-model` repository. |