kirigami-app-components

We just had a release of a new library, and future framework: kirigami-app-componets, which is a new repository where a certain kind of Kirigami extensions will go.

This repository will contain modules that are intended to be building blocks for applications to integrate within the KDE Frameworks ecosystem.

Why start a new repository when kirigami-addons already exists?

We now had a standalone release of kirigami-app-components with a single module inside for testing purposes, but the target here is to move it to frameworks releases, with all the stability promises and quality constraints of Frameworks.

Kirigami-addons is a bit more experimental of nature and have modules which, while they are a good first approach at solving a particular problem, would definitely need some work and refactoring for us to be comfortable having them in Frameworks, while other kirigami-addons modules will be a more straightforward import into kirigami-app-components.

An example of a module that was very useful but needed some work in its architecture is the StatefulApplication module (import org.kde.kirigamiaddons.statefulapp). It provides a Kirigami ApplicationWindow subclass and a way to map QActions to Kirigami actions.

The central idea is having a series of actions that can have their keyboard shortcuts configured by the user (while also providing a component for such configuration UI).

A problematic aspect of StatefulApp is that it’s based too much on C++: in order to add actions, it is necessary for the app to create a subclass and add them as QActions, then the QML part has to connect the QActions and Kirigami.Action using the proper API.

This is OK for the parts of the app where the logic is completely on the C++ side, but when it is necessary to add a very simple action (closing a page, opening a search dialog, and so on), this brings far too much boilerplate.

org.kde.kirigami.actioncollection

ActionCollection is the module that we introduce with kirigami-app-components. It’s all about collections of actions that are defined declaratively via QML (with the option of creating collections on the C++ side as well) and that have shortcuts configurable by the user via the standard interface.

In order to define a new collection, we would write the following QML:

import org.kde.kirigami.actioncollection as AC
AC.ActionCollectionManager {
id: manager
pageRow: pageStack
AC.ActionCollection {
name: "org.kde.myapp.mainactions"
text: i18n("Main Actions")
AC.ActionData {
name: "hello"
text: i18n("Hello")
icon.name: "document-send"
defaultShortcut: "Ctrl+H"
}
AC.StandardActionData {
standardAction: AC.StandardActionData.Copy
}
...
}
AC.ActionCollection {
name: "org.kde.myapp.photoactions
text: i18n("Photo Actions")
AC.ActionData {
...
}
...
}
}

The ActionCollectionManager will be a single instance for the whole application, and it is what takes care of instantiating the common actions (such as About Application, About KDE, Configure Shortcuts, and so on) and doing the plumbing with the configuration dialogs and so on.

ActionCollection is a set of actions semantically grouped together in the same category (if an application would have, for instance, actions that operate on photos and actions that operate on videos, those could be two different collections).

ActionData is the semantic representation of an action (internally it is a QAction, so it has all its properties) and will be defined only once for the whole application. Instances of Kirigami.Action will be attached to it (even more than one), and those will define the actual buttons and menu entries in the application.

A Kirigami.Action is attached to an ActionData via an attached property:

Kirigami.Action {
// Here shows how important is that each ActionCollection has
// an app-global unique name and each action has a collecion-global
// unique name as well
AC.ActionCollection.name: "org.kde.myapp.mainactions"
AC.ActionCollection.action: "hello"
onTriggered: {
// Logic here
}
}

The Kirigami.Action instance will not have text, shortcut, or icon defined, because everything comes from the attached ActionData. Only the onTriggered logic will be defined there (as well as the logic for when the action is enabled or visible).

When an ActionCollectionManager is created, a collection named org.kde.globalactions will be automatically created as well, which also contains an action called "KeyBindings“. When triggered, this dialog will open:

This is the configuration UI where it is possible to configure all the application shortcuts.

Another action called “FindAction" is also available: when triggered, this other dialog will open instead:

This is the classical Ctrl+Alt+I dialog also present in QWidget applications, where it is possible to search and trigger all the application’s actions.