Debian Codegraph @

docs/index.md

raw
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.