Kirigami con Python
Requisitos previos
Antes de empezar, necesitamos instalar Kirigami y PySide nuestra máquina.
sudo pacman -S python-pipx python-pyqt6 pyside6 kirigami flatpak-builder qqc2-desktop-style appstream | |
sudo zypper install python3-pipx python3-qt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style AppStream-compose | |
sudo dnf install pipx python3-pyqt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style appstream-compose |
If you are on a distribution with old PySide6 or PyQt6 packages, this tutorial works with Building software with distrobox.
Estructura del proyecto
First we create our project folder (you can use the commands below). We are going to call ours kirigami_python/
.
kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in # Para añadir nuestros archivos QML
├── pyproject.toml # El archivo principal para la gestión del proyecto
├── org.kde.kirigami_python.desktop
└── src/
├── __init__.py # Para importar el directorio src/ como paquete
├── __main__.py # Para señalar la aplicación como punto de entrada
├── app.py
└── qml/
└── Main.qml
The package name is going to be kirigami_python
, the "executable" (console script) will be called kirigami_hello
, and the entrypoint will be app
.
Consejo
To quickly generate this folder structure, just run:mkdir -p kirigami_python/src/qml/
.For a more comprehensive project that goes into further detail about this file structure, see Full project in Python + Kirigami.
pyproject.toml
Modern Python applications need only a single TOML file to specify all metadata, package information and dependencies as of PEP 621. The following serves as a good starter for an application and can be extended later.
Most of the contents in this file are boilerplate, and a more complete version of it can be seen in Python with Kirigami: General Structure.
|
|
Note the highlighted lines. As mentioned under Project structure, the name of the package is kirigami_python
, the name of the executable is kirigami_hello
, and the name of the entrypoint is app
. In particular, the following should be noted:
- The project script consists of an entrypoint script that will be generated by setuptools for the application to run, in this case
kirigami_hello
. - The generated project script
kirigami_hello
runs themain()
function in theapp.py
script in thekirigami_python
package. - The default
package-dir
for Python projects is usually the root directory. In this case, this is overridden with thesrc/
subdirectory so it acts like it is the root directory of the package. - The
package-dir
is why the generated project script doeskirigami_python → app
instead ofkirigami_python → src → app
. - The
package-dir
is also why theimportlib.resources.files()
call in app.py doeskirigami_python → qml → Main.qml
instead ofkirigami_python → src → qml → Main.qml
.
See Running directly, as a module, and as a console script for details.
org.kde.kirigami_python.desktop
The primary purpose of Desktop Entry files is to show your app on the application launcher on Linux. Another reason to have them is to have window icons on Wayland, as they are required to tell the compositor "this window goes with this icon".
It must follow a reverse-DNS naming scheme followed by the .desktop
extension such as org.kde.kirigami_python.desktop
:
|
|
Nota
Window and taskbar icons will work in a Wayland session only if apps' desktop files are placed in~/.local/share/applications
or /usr/share/applications
. To get icons working in this tutorial, copy the app's desktop file there.MANIFEST.in
This file is simply a declaration of additional source code files that should be present in the package when the application runs. Python by default doesn't include QML files in packages, and they need to be available in order for the application to run.
|
|
src/app.py
|
|
Since this is a GUI application, we want the main function to only run when the script is run, not when it's imported, so we need the if __name__ == "__main__"
condition at the end of the file. See Running directly, as a module, and as a console script for details.
We create a QGuiApplication and initialize the QML engine, and with QGuiApplication.exec()
the application will keep running until closed. Then importlib.resources.files()
grabs the path to a file that is present in the package, namely our Main.qml
. With that path, we load the QML file into the QML engine as the main entrypoint for the application interface.
src/__init__.py
Create an empty kirigami_python/src/__init__.py
file. This file just needs to be present in order to import a directory as a package.
touch __init__.py
src/__main__.py
Create a kirigami_python/src/__main__.py
with the following contents:
|
|
This simply adds the contents of the current directory (src/
) and imports it as a module named app
, then immediately runs the main()
function of the application.
src/qml/Main.qml
|
|
Aquí es donde manejaremos la interfaz de nuestra aplicación.
Si sabe algo de JavaScript, gran parte de QML le será familiar (aunque tiene sus propias peculiaridades). La documentación de Qt dispone de gran cantidad de material sobre este lenguaje si tiene ganas de probar cosas por su cuenta. A lo largo del curso de estos tutoriales nos vamos a centrar en nuestro código QML, donde podemos usar Kirigami para sacar el máximo provecho del mismo.
Por ahora, centrémonos en Main.qml
. Primero [importamos](https:// doc.qt.io/qt-6/qtqml-syntax-imports.html) cierto número de importantes módulos:
- QtQuick, la biblioteca estándar que usan las aplicaciones en QML.
- QtQuick Controls, que proporciona cierto número de controles estándares que podemos usar para hacer que nuestras aplicaciones sean interactivas.
- QtQuick Layouts, que proporciona herramientas para situar componentes dentro de la ventana de la aplicación.
- Kirigami, que proporciona cierto número de componentes adecuados para crear aplicaciones que funcionan en dispositivos de diferentes formas y tamaños.
Nota
Putting the QtQuick Controls and Kirigami imports into separate namespaces using theas
keyword is a best practice that ensures no components with the same name can conflict. You might see different names for QtQuick Controls in the wild, such as "QQC" or "QQC2". We will be using "Controls" in this tutorial for clarity.Luego llegamos a nuestro elemento base, Kirigami.ApplicationWindow, que proporciona algunas funcionalidades básicas que son necesarias para todas las aplicaciones de Kirigami. Esta es la ventana que contendrá todas nuestras páginas, las secciones principales de nuestra interfaz de usuario.
Luego definimos la propiedad id
de la ventana a «root». Los identificadores son útiles porque nos permiten hacer referencia a componentes de una forma única, incluso si tenemos varios del mismo tipo.
We also set the window title
property to "Hello World".
We then set the first page of our page stack. Most Kirigami applications are organised as a stack of pages, each page containing related components suited to a specific task. For now, we are keeping it simple, and sticking to a single page. pageStack is an initially empty stack of pages provided by Kirigami.ApplicationWindow, and with pageStack.initialPage: Kirigami.Page {...}
we set the first page presented upon loading the application to a Kirigami.Page. This page will contain all our content.
Finally, we include in our page a Controls.Label that lets us place text on our page. We use anchors.centerIn: parent
to center our label horizontally and vertically within our parent element. In this case, the parent component of our label is Kirigami.Page. The last thing we need to do is set its text: text: "Hello World!"
.
Ejecución de la aplicación
You can run the kirigami_hello
console script without needing to install it first:
pipx run --system-site-packages --spec . kirigami_hello
The flag --system-site-packages
is needed to make Python have access to the Python packages from your distribution. This is required because Kirigami and PySide need to have been built against the same Qt version to work, which is the case when both of them come from the distribution.
The flag --spec
determines the path to the source code or wheel package that has the program, and kirigami_hello
is the executable script to be run.
To build and install the Python package, run:
pipx install --force --system-site-packages .
The package will be installed to ~/.local/share/pipx/venvs/kirigami-python
, and an executable script will be installed to ~/.local/bin/kirigami_hello
.
Uso de pipx frente a pip
Unlike Python with Kirigami: Creating a Python package, this tutorial used pipx
to make the project easier to run and install. The same steps can be done manually with venv
, build
and pip
as in the more complete tutorial.
pipx
is useful and recommended as per PEP 668 for running Python applications, while pip
is multi-purpose and can also be used for importable Python modules.
After this, the application can be launched by running:
kirigami_hello
Para ejecutar la nueva aplicación QML en modo móvil, puede usar QT_QUICK_CONTROLS_MOBILE=1
:
QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello
¡Ya está! Ahora verá su primera aplicación de Kirigami aparecer ante sus ojos.