# Getting Started ## Creating an Application Typical usage will begin by creating a [`Application`][app_model.Application] object. ```python from app_model import Application my_app = Application('my-app') ``` ## Registering Actions Most applications will have some number of actions that can be invoked by the user. Actions are typically callable objects that perform some operation, such as "open a file", "save a file", "copy", "paste", etc. These actions will usually be exposed in the application's menus and toolbars, and will usually have associated keybindings. Sometimes actions hold state, such as "toggle word wrap" or "toggle line numbers". `app-model` provides a high level [`Action`][app_model.Action] object that comprises a pointer to a callable object, along with placement in menus, keybindings, and additional metadata like title, icons, tooltips, etc... ```python from app_model.types import Action, KeyBindingRule, KeyCode, KeyMod, MenuRule def open_file(): print('open file!') def close_window(): print('close window!') ACTIONS: list[Action] = [ Action( id='open', title="Open", icon="fa6-solid:folder-open", callback=open_file, menus=['File'], keybindings=[KeyBindingRule(primary=KeyMod.CtrlCmd | KeyCode.KeyO)], ), Action( id='close', title="Close", icon="fa-solid:window-close", callback=close_window, menus=['File'], keybindings=[KeyBindingRule(primary=KeyMod.CtrlCmd | KeyCode.KeyW)], ), # ... ] ``` Actions are registered with the application using the [`Application.register_action()`][app_model.Application.register_action] method. ```python for action in ACTIONS: my_app.register_action(action) ``` ## Registries The application maintains three internal registries. 1. `Application.commands` is an instance of [`CommandsRegistry`][app_model.registries.CommandsRegistry]. It maintains all of the commands (the actual callable object) that have been registered with the application. 2. `Application.menus` is an instance of [`MenusRegistry`][app_model.registries.MenusRegistry]. It maintains all of the menus and submenu items that have been registered with the application. 3. `Application.keybindings` is an instance of [`KeyBindingsRegistry`][app_model.registries.KeyBindingsRegistry]. It maintains an association between a [KeyBinding][app_model.types.KeyBinding] and a command id in the `CommandsRegistry`. !!! Note Calling [`Application.register_action`][app_model.Application.register_action] with a single [`Action`][app_model.Action] object is just a convenience around independently registering objects with each of the registries using: - [CommandsRegistry.register_command][app_model.registries.CommandsRegistry.register_command] - [MenusRegistry.append_menu_items][app_model.registries.MenusRegistry.append_menu_items] - [KeyBindingsRegistry.register_keybinding_rule][app_model.registries.KeyBindingsRegistry.register_keybinding_rule] ### Registry events Each of these registries has a signal that is emitted when a new item is added. - `CommandsRegistry.registered` is emitted with the new command id (`str`) whenever [`CommandsRegistry.register_command`][app_model.registries.CommandsRegistry.register_command] is called - `MenusRegistry.menus_changed` is emitted with the new menu ids (`set[str]`) whenever [`MenusRegistry.append_menu_items`][app_model.registries.MenusRegistry.append_menu_items] or if the menu items have been disposed. - `KeyBindingsRegistry.registered` is emitted (no arguments) whenever [`KeyBindingsRegistry.register_keybinding_rule`][app_model.registries.KeyBindingsRegistry.register_keybinding_rule] is called. You can connect callbacks to these events to handle them as needed. ```python @my_app.commands.registered.connect def on_command_registered(command_id: str): print(f'Command {command_id!r} registered!') my_app.commands.register_command('new-id', lambda: None, title='No-op') # Command 'new-id' registered! ``` ## Executing Commands Registered commands may be executed on-demand using [`execute_command`][app_model.registries.CommandsRegistry.execute_command] method on the command registry: ```python my_app.commands.execute_command('open') # prints "open file!" from the `open_file` function registered above. ``` ### Command Arguments and Dependency Injection The `execute_command` function does accept `*args` and `**kwargs` that will be passed to the command. However, very often in a GUI application you may wish to infer some of the arguments from the current state of the application. For example, if you have menu item linked to a "close window", you likely want to close the current window. For this, `app-model` uses a dependency injection pattern, provided by the [`in-n-out`](https://github.com/pyapp-kit/in-n-out) library. The application has a [`injection_store`][app_model.Application.injection_store] attribute that is an instance of an `in_n_out.Store`. A `Store` is a collection of: - **providers**: Functions that can be called to return an instance of a given type. These may be used to provide arguments to commands, based on the type annotations in the command function definition. - **processors**: Functions that accept an instance of a given type and do something with it. These are used to process the return value of the command function at execution time, based on command definition return type annotations. See [`in-n-out` getting started](https://ino.readthedocs.io/en/latest/getting_started/) for more details on the use of providers/processors in the `Store`. Here's a simple example. Let's say an application has a `User` object with a `name()` method: ```python class User: def name(self): return 'John Doe' ``` Assume the application has some way of retrieving the current user: ```python def get_current_user() -> User: # ... get the current user from somewhere return User() ``` We register this provider function with the application's injection store: ```python my_app.injection_store.register_provider(get_current_user) ``` Now commands may be defined that accept a `User` argument, and used for callbacks in actions registered with the application. ```python def print_user_name(user: User) -> None: print(f"Hi {user.name()}!") action = Action( id='greet', title="Greet Current User", callback=print_user_name, ) my_app.register_action(action) my_app.commands.execute_command('greet') # prints "Hi John Doe!" ``` ## Connecting a GUI framework Of course, most of this is useless without some way to connect the application to a GUI framework. The [`app_model.backends`][app_model.backends] module provides functions that map the `app-model` model onto various GUI framework models. !!! note "erm... someday 😂" Well, really it's just Qt for now, but the abstraction is valuable for the ability to swap backends. And we hope to add more backends if the demand is there. ### Qt Currently, we don't have a generic abstraction for the application window, so users are encouraged to directly use the classes in the `app_model.backends.qt` module. One of the main classes is the [`QModelMainWindow`][app_model.backends.qt.QModelMainWindow] object: a subclass of `QMainWindow` that knows how to map an `Application` object onto the Qt model. ```python from app_model.backends.qt import QModelMainWindow from qtpy.QtWidgets import QApplication app = QApplication([]) # create the main window with our app_model.Application main = QModelMainWindow(my_app) # pick menus for main menu bar, # using menu ids from the application's MenusRegistry main.setModelMenuBar(['File']) # add toolbars using menu ids from the application's MenusRegistry # here we re-use the File menu ... but you can have menus # dedicated for toolbars, or just exclude items from the menu main.addModelToolBar('File') main.show() app.exec() ``` You should now have a QMainWindow with a menu bar and toolbar populated with the actions you registered with the application with icons, keybindings, and callbacks all connected. ![QMainWindow with menu bar and toolbar](images/qmainwindow.jpeg) Once objects have been registered with the application, it becomes very easy to create Qt objects (such as [`QMainWindow`](https://doc.qt.io/qt-6/qmainwindow.html), [`QMenu`](https://doc.qt.io/qt-6/qmenu.html), [`QMenuBar`](https://doc.qt.io/qt-6/qmenubar.html), [`QAction`](https://doc.qt.io/qt-6/qaction.html), [`QToolBar`](https://doc.qt.io/qt-6/qtoolbar.html), etc...) with very minimal boilerplate and repetitive procedural code. See all objects in the [Qt backend API docs][app_model.backends.qt]. !!! Tip Application registries are backed by [psygnal](https://github.com/pyapp-kit/psygnal), and emit events when modified. These events are connected to the Qt objects, so `QModel...` objects such as `QModelMenu` and `QCommandAction` will be updated when the application's registry is updated.