– Docs

Docs: Configuració amb el C++

Mon, 01 Jan 0001 00:00:00 +0000

Instal·lació del Kirigami

Abans de començar, haurem d'instal·lar el Kirigami a la nostra màquina. Hi ha tres maneres de fer-ho:

Instal·lar el Kirigami a partir dels repositoris de la vostra distribució Linux
Utilitzar el «kde-builder»
Instal·lar el Kirigami amb el Craft

Si feu servir una distribució prou actualitzada com la Debian Testing, l'última Ubuntu no LTS Ubuntu, Fedora, openSUSE Tumbleweed o Arch, podreu instal·lar el Kirigami a partir de la distribució.

Si feu servir una distribució no tan al dia com la Debian Stable o la Ubuntu LTS, hauríeu d'utilitzar el kde-builder per a aquesta guia d'aprenentatge. Hauria d'utilitzar com a màxim 2 GB d'emmagatzematge.

Instal·lar el Kirigami a partir dels repositoris de la vostra distribució Linux

Necessitem un compilador de C++, els paquets de desenvolupament de les Qt i el Kirigami. Obriu una aplicació de terminal i executeu un dels següents, depenent de quina distribució Linux utilitzeu:

Kubuntu KDE Neon	sudo apt install build-essential cmake extra-cmake-modules libkirigami-dev libkf6i18n-dev libkf6coreaddons-dev libkf6iconthemes-dev qt6-base-dev qt6-declarative-dev libkf6qqc2desktopstyle-dev
Manjaro Arch	sudo pacman -S base-devel extra-cmake-modules cmake kirigami ki18n kcoreaddons breeze kiconthemes qt6-base qt6-declarative qqc2-desktop-style
OpenSUSE	sudo zypper install cmake kf6-extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-base-devel qt6-declarative-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style
Fedora	sudo dnf install @development-tools @development-libs cmake extra-cmake-modules kf6-kirigami-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kiconthemes-devel qt6-qtbase-devel qt6-qtdeclarative-devel kf6-qqc2-desktop-style

Trobareu més informació sobre les altres distribucions a Instal·lació de dependències de construcció.

Utilitzar el «kde-builder»

Configureu l'entorn de desenvolupament amb el «kde-builder». Això us proporcionarà les eines de desenvolupament necessàries i les biblioteques subjacents i construirà els Frameworks de KDE des de zero.

Creeu una carpeta ~/kde/src/kirigami-tutorial. En aquesta carpeta situareu els fitxers de codi font d'aquesta guia d'aprenentatge.

Afegiu el següent al final del vostre ~/.config/kde-builder.yaml:

project kirigami-tutorial:
 no-src: true

⏳ Amb el «kdesrc-build»...

Feu clic aquí per a conèixer com s'ha fet amb el «kdesrc-build»

Aquest pas es feia escrivint a ~/.config/kdesrc-buildrc amb una sintaxi diferent:

# after include ${module-definitions-dir}/kf6-qt6.ksb
module kirigami-tutorial
no-src
end module

Instal·lar el Kirigami amb el Craft

KDE té una eina personalitzada per a instal·lar fàcilment la majoria de les seves biblioteques i programes: Craft. Es pot utilitzar per a instal·lar el Kirigami al Windows, l'Android i el macOS.

Tot i que Craft també està disponible per al Linux i FreeBSD, el seu ús previst és només per a les AppImages i empaquetament.

Cal seguir les instruccions de configuració per al Craft. Cap al final de la configuració, hauríeu d'executar un fitxer de configuració d'entorn (craftenv.ps1 al Windows o craftenv.sh a totes les altres plataformes), que us proporcionarà un intèrpret d'ordres de terminal a on compilareu la vostra aplicació Kirigami.

Després d'això, podeu executar el següent en un terminal:

craft kirigami kcoreaddons ki18n breeze kiconthemes qqc2-desktop-style

Això trigarà una estona a acabar en la primera execució. Si tanqueu el terminal, podeu tornar a executar el fitxer de configuració d'entorn per a tornar a preparar el terminal.

Estructura del projecte

Si bé existeixen eines que poden configurar amb facilitat els nostres fitxers, els crearem manualment. Això ens permetrà comprendre millor les peces que compondran la nostra nova aplicació.

Primer crearem la nostra carpeta de projecte (podeu utilitzar les ordres de sota). L'anomenarem kirigami-tutorial/.

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

Dins d'aquesta carpeta crearem una carpeta src/ i un CMakeLists.txt. En general, es considera una bona pràctica posar tots els nostres principals fitxers de codi C++ en una carpeta src/. També hi posarem el fitxer Main.qml ja que s'executarà junt amb l'executable.

Consell

Podeu crear ràpidament aquesta estructura de fitxers amb:

mkdir -p kirigami-tutorial/src
touch kirigami-tutorial/{CMakeLists.txt,org.kde.tutorial.desktop}
touch kirigami-tutorial/src/{CMakeLists.txt,main.cpp,Main.qml}

Nota

En cas que vulgueu construir automàticament el projecte amb el kde-builder, el nom del mòdul personalitzat hauria de ser el mateix que la carpeta arrel del projecte (en el nostre cas serà «kirigami-tutorial»), en cas contrari hauríeu de personalitzar el source-dir o dest-dir per al mòdul. Assumirem que el camí cap al main.cpp serà ~/kde/src/kirigami-tutorial/src/main.cpp.

Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

Aquí és on manejarem el frontal de la nostra aplicació.

Si coneixeu alguna cosa de JavaScript, gran part de QML us resultarà familiar (encara que té les seves pròpies peculiaritats). Si teniu ganes de provar alguna cosa pel vostre compte, la documentació de les Qt té una gran quantitat de material sobre aquest llenguatge. Al llarg d'aquestes guies d'aprenentatge, centrarem gran part de la nostra atenció en el codi en QML, on podrem emprar el Kirigami per a aprofitar-lo al màxim.

Per ara, centrem-nos en Main.qml. Primer importarem diversos mòduls importants:

QtQuick, la biblioteca estàndard utilitzada en les aplicacions QML.
QtQuick Controls, que proporciona una sèrie de controls estàndard que podem utilitzar perquè les nostres aplicacions siguin interactives.
QtQuick Layouts, que proporciona eines per a col·locar els components dins de la finestra de l'aplicació.
El Kirigami, que proporciona una sèrie de components adequats per a crear aplicacions que funcionen en dispositius de formes i mides diferents.

Nota

Posar els QtQuick Controls i les importacions del Kirigami en espais de noms separats utilitzant la paraula clau as és una millor pràctica que assegura que cap component amb el mateix nom pugui entrar en conflicte. Podreu trobar diferents noms per als controls QtQuick en els textos, com ara «QQC» o «QQC2». Utilitzarem "Controls" en aquesta guia d'aprenentatge per a més claredat.

Després arribem al nostre element base, la Kirigami.ApplicationWindow, que proporciona algunes característiques bàsiques necessàries per a totes les aplicacions escrites amb el Kirigami. Aquesta és la finestra que contindrà cadascuna de les nostres pàgines, les seccions principals de la nostra interfície d'usuari.

Després, establim la propietat id de la finestra a "root". Els ID són útils perquè ens permeten fer referència de forma única a un component, fins i tot si en tenim diversos del mateix tipus.

També establirem la propietat title de la finestra a "Hello World". Us adonareu que hem embolcallat la nostra cadena "Hello World" amb una funció amb la crida i18nc(), on detallem el context de la cadena, així com la cadena en si.

Nota

Les funcions i18n() fan que la vostra aplicació sigui traduïble amb més facilitat, ja que retornen una versió de la cadena proporcionada en l'idioma de l'usuari (sempre que l'aplicació estigui localitzada per a aquest idioma). Mentre que un usuari anglès pot veure el títol de la finestra com «Hello World», un usuari català veurà «Hola món».

i18nc() construeix la funció i18n() que permet als desenvolupadors proporcionar un context als equips de traducció que treballen en l'aplicació. És per això que hem inclòs la cadena "@title:window" abans de "Hello World". Vegeu la Guia del programador Ki18n per a més detalls.

Després establirem la primera pàgina de la nostra pila de pàgines. La majoria de les aplicacions escrites amb el Kirigami estan organitzades com una pila de pàgines, cada pàgina conté els components relacionats adequats per a una tasca específica. Per ara, el mantenim senzill i ens cenyim a una sola pàgina. pageStack és una pila inicialment buida de pàgines proporcionades per Kirigami.ApplicationWindow, i amb pageStack.initialPage: Kirigami.Page {...} establim la primera pàgina presentada en carregar l'aplicació a una Kirigami.Page. Aquesta pàgina contindrà tot el nostre contingut.

Finalment, incloem en la nostra pàgina un Controls.Label que ens permetrà inserir text a la nostra pàgina. Utilitzarem anchors.centerIn: parent per a centrar la nostra etiqueta horitzontalment i verticalment dins de l'element pare. En aquest cas, el component principal de la nostra etiqueta és Kirigami.Page. L'últim que hem de fer és configurar el text: text: i18n("Hello World!").

org.kde.tutorial.desktop

El propòsit principal dels fitxers Desktop Entry és mostrar la vostra aplicació al llançador d'aplicacions en el Linux. Una altra raó per a tenir-los és tenir icones de finestra al Wayland, ja que es requereixen per a dir al compositor «aquesta finestra va amb aquesta icona».

Ha de seguir un esquema de noms DNS invers seguit de l'extensió .desktop com ara org.kde.tutorial.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


[Desktop Entry]
Name=Kirigami Tutorial
Name[ar]=درس كيريغامي
Name[ca]=Guia d'aprenentatge del Kirigami
Name[cs]=Tutoriál Kirigami
Name[eo]=Lernilo pri Kirigami
Name[es]=Tutorial de Kirigami
Name[fr]=Tutoriel pour Kirigami
Name[it]=Esercitazione di Kirigami
Name[nl]=Kirigami handleiding
Name[pt_BR]=Tutorial do Kirigami
Name[ro]=Îndrumar Kirigami
Name[ru]=Учебное руководство по Kirigami
Name[sk]=Tutoriál Kirigami
Name[sl]=Učbenik Kirigami
Name[sv]=Kirigami-handledning
Name[tr]=Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami
Name[zh_TW]=Kirigami 教學
Exec=kirigami-hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Nota

Les icones de les finestres i de la barra de tasques només funcionaran en una sessió del Wayland si els fitxers «desktop» de les aplicacions es col·loquen a ~/.local/share/applications o /usr/share/applications. Per a aconseguir icones que funcionin en aquesta guia d'aprenentatge, copieu el fitxer «desktop» de l'aplicació o canvieu a una sessió de desenvolupament com s'indica en la guia d'aprenentatge del «kde-builder». Algunes aplicacions de KDE podrien tenir icones funcionant si ja estaven instal·lades al sistema.

CMakeLists.txt

Els fitxers CMakeLists.txt són necessaris per a utilitzar el sistema de compilació triat pel KDE, CMake. El fitxer kirigami-tutorial/CMakeLists.txt especifica algunes característiques de la nostra aplicació. També inclou algunes de les dependències que necessitem per a compilar el projecte.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

El CMakeLists.txt defineix com construir els vostres projectes. La major part del seu contingut només és per a arrencar el vostre projecte. Aquí podeu llegir una explicació detallada línia a línia del que fa aquest fitxer CMakeLists.

El més important a tenir en compte és que les dependències de construcció C++ de les Qt i dels Frameworks de KDE es gestionen amb find_ package() i les dependències en temps d'execució del QML es gestionen amb ecm_find_qml_module(). Haureu de modificar aquestes línies i incloure qualsevol component addicional que decidiu utilitzar durant el desenvolupament de la vostra aplicació.

La línia amb add_subdirectory(src) apunta el CMake al directori kirigami-tutorial/src/ on es troba el nostre codi font.

La línia amb install() indica al CMake on instal·lar el fitxer «desktop».

Aprofundim en el fitxer kirigami-tutorial/src/CMakeLists.txt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Aquest fitxer consta de cinc passos:

crea un executable
canvia l'executable a un mòdul QML que accepta fitxers QML
afegeix fitxers C++ i QML a l'executable
enllaça les biblioteques necessàries perquè s'executi l'executable
instal·la l'executable al lloc correcte

La pròxima vegada haureu d'afegir més fitxers en QML, afegir-los a la crida existent ecm_target_qml_sources(). Els fitxers C++ que utilitzen la paraula clau QML_ELEMENT que veurem més endavant a la guia d'aprenentatge es poden afegir utilitzant target_sources().

Ara que ens hem revisat el CMake, vegem els fitxers als quals dedicarem la major part del nostre temps de treball.

main.cpp

El fitxer kirigami-tutorial/src/main.cpp gestiona la «lògica empresarial» de la nostra aplicació. El C++ és útil perquè és flexible i ràpid, encara que és més complicat que altres llenguatges de programació.

També funciona com el punt d'entrada a la nostra aplicació. Les dues parts del nostre projecte, el dorsal i la interfície d'usuari, ambdós es configuren i s'inicien aquí.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

Per ara, no necessitem entrar en massa detalls sobre el que fa el nostre codi de main.cpp, però la seva funció serà significativament més important una vegada en el futur decidim afegir una funcionalitat més complexa a l'aplicació.

Temes al Windows

Feu clic aquí per a llegir-ne més

L'aplicació ha d'establir el seu estil de tema d'icones, QStyle i QtQuick Controls a Brisa per tal de mostrar-se al Windows. Per a saber-ne més, vegeu Descobrir el main.cpp.

Si voleu avançar, podeu llegir més sobre com funciona aquest main.cpp a Descobrir el main.cpp.

Si voleu veure algunes maneres de millorar el codi C++, com ara utilitzar el KAboutData per a les metadades d'aplicació traduïbles, reviseu la Guia d'aprenentatge del KXmlGui.

De moment, la part que ens interessa és aquesta línia:

engine.loadFromModule("org.kde.tutorial", "Main");

El primer argument és l'URI establert a kirigami-tutorial/src/CMakeLists.txt, i el segon argument és el nom del mòdul QML que volem utilitzar (Main), que prové del nom del nostre fitxer Main.qml, el qual ha de començar amb una lletra en majúscula).

El mètode antic

Podeu trobar aquesta manera alternativa de carregar fitxers QML en codi real!

El mètode antic de càrrega de fitxers QML tenia alguns inconvenients i després de les Qt6 es va tornar excessivament detallat a la sortida:

engine.load(QUrl(QStringLiteral("qrc:/qt/qml/org/kde/tutorial/qml/Main.qml")));

Aquest UR del recurs Qt segueix el patró <resource_prefix><import_URI><optional_QML_dir><file>. En aquest cas:

resource prefix = predeterminat / a Qt5, /qt/qml a Qt6
import URI = /org/kde/tutorial, que coincideix amb l'URI org.kde.tutorial
optional QML dir = /qml, necessari si els fitxers QML s'emmagatzemen en un directori anomenat qml/
file = el fitxer QML

Compilar i instal·lar l'aplicació

Estem gairebé a la línia de meta. L'últim que hem de fer és construir i compilar la nostra aplicació. Fer això dependrà de la plataforma en la qual estem.

Linux o FreeBSD

Compilar amb el «kde-builder»

Assegureu-vos que heu seguit les instruccions d'Utilitzar el «kde-builder».

Compileu les dependències de construcció necessàries amb el «kde-builder», després compileu kirigami-tutorial executant les ordres següents en un terminal:

kde-builder kirigami ki18n kcoreaddons breeze kiconthemes qqc2-desktop-style
kde-builder kirigami-tutorial

Compilar manualment

Canvieu els directoris a la carpeta arrel del projecte i executeu l'ordre següent en un terminal:

cmake -B build/ --install-prefix ~/.local
cmake --build build/
cmake --install build/

El programa s'instal·larà a ~/.local/bin i la seva entrada «desktop» a ~/.local/share/applications.

Windows

Si esteu compilant el projecte al Windows després d'haver configurat Craft, el CMake hauria de detectar automàticament el compilador correcte:

cmake -B build/
cmake --build build/
cmake --install build/

En funció de com heu instal·lat el compilador, potser caldrà especificar un generador de CMake per al primer pas, depenent de si esteu utilitzant el Visual Studio (msvc) o el MinGW (make) per a compilar els projectes.

Si és Visual Studio, depenent del compilador que trieu instal·lar, podria ser:

cmake -B build/ -G "Visual Studio 16 2019"

cmake -B build/ -G "Visual Studio 17 2022"

Si és MinGW:

cmake -B build/ -G "MinGW Makefiles"
cmake --build build/
cmake --install build/

En els dos casos, el programa s'instal·larà a C:\CraftRoot\bin.

Si alguna vegada dubteu sobre el nom del compilador que s'ha d'utilitzar en la crida del cmake, executeu:

cmake -G

Llistarà tots els generadors disponibles.

Executar l'aplicació

Llavors podeu executar el programa kirigami-hello amb:

kirigami-hello # Al Linux, manualment
kde-builder --run kirigami-hello # Amb el «kde-builder»
kdesrc-build --run --exec kirigami-hello kirigami-tutorial # Amb el «kdesrc-build»
kirigami-hello.exe # Al Windows

Heus aquí! Ara veureu aparèixer la vostra primera aplicació escrita amb el Kirigami.

Per a executar la nova aplicació QML en mode de mòbil, podeu utilitzar QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami-hello

Si heu compilat el projecte manualment amb el CMake i per algun motiu voleu desinstal·lar el projecte, podeu executar:

cmake --build build/ --target uninstall

Nota

La pròxima vegada que vulgueu crear els fitxers i carpetes necessaris, podreu fer servir KAppTemplate o el KDevelop per a generar automàticament un projecte adequat per a començar. Estan disponibles en els repositoris de cada distribució. Aquestes aplicacions també generaran els fitxers que contenen les metadades d'AppStream i un fitxer .desktop que conté la informació sobre com s'ha de mostrar l'aplicació en un llançador d'aplicacions del Linux.

Gràcies a la màgia de CMakeLists, també podreu utilitzar un IDE com el KDevelop o el QtCreator per a desenvolupar aquesta aplicació dins d'un entorn còmode, amb un esforç mínim.

Docs: Configuració amb el Python

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisits

Abans de començar, haurem d'instal·lar el Kirigami i el PySide a la nostra màquina.

Manjaro Arch

sudo pacman -S python-pipx python-pyqt6 pyside6 kirigami flatpak-builder qqc2-desktop-style appstream

OpenSUSE

sudo zypper install python3-pipx python3-qt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style AppStream-compose

Fedora

sudo dnf install pipx python3-pyqt6 python3-pyside6 kf6-kirigami-devel flatpak-builder kf6-qqc2-desktop-style appstream-compose

Si teniu en una distribució amb paquets antics de PySide6 o PyQt6, aquesta guia d'aprenentatge funciona amb Construir programari amb distrobox.

Estructura del projecte

Primer crearem la nostra carpeta de projecte (podeu utilitzar les ordres de sota). L'anomenarem kirigami_python/.

kirigami_python/
├── README.md
├── LICENSE.txt
├── MANIFEST.in # Per a afegir els nostres fitxers QML
├── pyproject.toml # El fitxer principal per a gestionar el projecte
├── org.kde.kirigami_python.desktop
└── src/
├── __init__.py # Per a importar el directori src/ com a paquet
├── __main__.py # Per a assenyalar l'aplicació com a punt d'entrada
├── app.py
└── qml/
└── Main.qml

El nom del paquet serà kirigami_python, l'«executable» (script de consola) s'anomenarà kirigami_hello i el punt d'entrada serà app.

Consell

Per a generar ràpidament aquesta estructura de carpetes, simplement executeu: mkdir -p kirigami_python/src/qml/.

Per a un projecte més complet que entri en més detalls sobre aquesta estructura de fitxers, vegeu Projecte complet en Python + Kirigami.

pyproject.toml

Les aplicacions Python modernes només necessiten un sol fitxer TOML per a especificar totes les metadades, la informació del paquet i les dependències a partir del PEP 621. El següent serveix com un bon iniciador per a una aplicació i es pot ampliar més tard.

La major part del contingut d'aquest fitxer és estàndard, i es pot veure una versió més completa d'ell a Python amb el Kirigami: Estructura general.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "kirigami_python"
version = "0.1"
authors = [
 {name = "Konqi", email = "konqi@example.com"}
]
classifiers = [
 "Development Status :: 5 - Production/Stable",
 "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
 "Intended Audience :: End Users/Desktop",
 "Topic :: Utilities",
 "Programming Language :: Python",
 "Operating System :: POSIX :: Linux",
]

[project.scripts]
kirigami_hello = "kirigami_python.app:main"

[tool.setuptools]
packages = ["kirigami_python"]
package-dir = {kirigami_python = "src"}
include-package-data = true

[tool.setuptools.data-files]
"share/applications" = ["org.kde.kirigami_python.desktop"]

Tingueu en compte les línies ressaltades. Com s'esmenta a estructura del projecte, el nom del paquet és kirigami_python, el nom de l'executable és kirigami_hello, i el nom del punt d'entrada és app. En particular, cal destacar el següent:

L'script del projecte consisteix en un script de punt d'entrada que serà generat per «setuptools» de l'aplicació a executar, en aquest cas kirigami_hello.
L'script de projecte generat kirigami_hello executa la funció main() a l'script app.py al paquet kirigami_python.
El package-dir predeterminat dels projectes Python és normalment el directori arrel. En aquest cas, això se substitueix pel subdirectori src/, de manera que actua com si fos el directori arrel del paquet.
El package-dir és perquè l'script generat del projecte fa kirigami_python → app en lloc de kirigami_python → src → app.
El package-dir també és perquè la crida importlib.resources.files() a app.py fa kirigami_python → qml → Main.qml en lloc de kirigami_python → src → qml → Main.qml.

Vegeu els detalls a Executar directament, com a mòdul i com a script de consola.

org.kde.kirigami_python.desktop

Ha de seguir un esquema de noms DNS invers seguit de l'extensió .desktop com ara org.kde.kirigami_python.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[Desktop Entry]
Name=Kirigami Tutorial in Python
Name[ar]=درس كيريغامي ببايثون
Name[ca]=Guia d'aprenentatge del Kirigami en Python
Name[eo]=Lernilo pri Kirigami en Python
Name[es]=Tutorial de Kirigami en Python
Name[fr]=Tutoriel pour Kirigami en Python
Name[it]=Esercitazione di Kirigami in Python
Name[nl]=Kirigami handleiding in Python
Name[pt_BR]=Tutorial do Kirigami em Python
Name[ro]=Îndrumar Kirigami în Python
Name[ru]=Учебное руководство по Kirigami на Python
Name[sk]=Tutoriál Kirigami v Pythone
Name[sl]=Učbenik Kirigami v Pythonu
Name[sv]=Kirigami-handledning i Python
Name[tr]=Python ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Python
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

Nota

MANIFEST.in

Aquest fitxer és senzillament una declaració de fitxers de codi font addicionals que haurien d'estar presents en el paquet quan s'executi l'aplicació. El Python no inclou fitxers QML als paquets de manera predeterminada, i han d'estar disponibles perquè l'aplicació s'executi.

1

include src/qml/*.qml

src/app.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


#!/usr/bin/env python3

import os
import sys
import signal
from importlib.resources import files

from PySide6.QtGui import QGuiApplication
from PySide6.QtCore import QUrl
from PySide6.QtQml import QQmlApplicationEngine

def main():
 app = QGuiApplication(sys.argv)
 engine = QQmlApplicationEngine()

 """Needed to close the app with Ctrl+C"""
 signal.signal(signal.SIGINT, signal.SIG_DFL)

 """Needed to get proper KDE style outside of Plasma"""
 if not os.environ.get("QT_QUICK_CONTROLS_STYLE"):
 os.environ["QT_QUICK_CONTROLS_STYLE"] = "org.kde.desktop"

 base_path = files('kirigami_python').joinpath('qml', 'Main.qml')
 url = QUrl(f"{base_path}")
 engine.load(url)

 app.exec()

if __name__ == "__main__":
 main()

Com que aquesta és una aplicació IGU, volem que la funció principal només s'executi quan s'executa l'script, no quan s'importa, de manera que necessitem la condició if __name__ == "__main__" al final del fitxer. Vegeu els detalls a Executar directament, com a mòdul i com a script de consola.

Creem una QGuiApplication i iniciem el motor QML, i amb QGuiApplication.exec() l'aplicació seguirà funcionant fins que es tanqui. Llavors importlib.resources.files() agafa el camí cap a un fitxer que està present en el paquet, és a dir, al nostre Main.qml. Amb aquest camí, carreguem el fitxer QML al motor QML com a punt d'entrada principal per a la interfície de l'aplicació.

src/init.py

Creeu un fitxer kirigami_python/src/__init__.py buit. Aquest fitxer només ha d'estar present per importar un directori com a paquet.

touch __init__.py

src/main.py

Creeu un kirigami_python/src/__main__.py amb el contingut següent:

1
2
3


from . import app

app.main()

Això simplement afegeix el contingut del directori actual (src/) i l'importa com un mòdul anomenat app, després immediatament executa la funció main() de l'aplicació.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

Aquí és on manejarem el frontal de la nostra aplicació.

Per ara, centrem-nos en Main.qml. Primer importarem diversos mòduls importants:

QtQuick, la biblioteca estàndard utilitzada en les aplicacions QML.
QtQuick Controls, que proporciona una sèrie de controls estàndard que podem utilitzar perquè les nostres aplicacions siguin interactives.
QtQuick Layouts, que proporciona eines per a col·locar els components dins de la finestra de l'aplicació.
El Kirigami, que proporciona una sèrie de components adequats per a crear aplicacions que funcionen en dispositius de formes i mides diferents.

Nota

Després, establim la propietat id de la finestra a "root". Els ID són útils perquè ens permeten fer referència de forma única a un component, fins i tot si en tenim diversos del mateix tipus.

També establim la propietat title de la finestra a "Hola món".

Executar l'aplicació

Podeu executar l'script de consola kirigami_hello sense necessitat d'instal·lar-lo abans:

pipx run --system-site-packages --spec . kirigami_hello

Es necessita l'indicador --system-site-packages per a fer que el Python tingui accés als paquets Python de la vostra distribució. Això és necessari perquè el Kirigami i el PySide han d'haver estat construïts amb la mateixa versió de les Qt per a funcionar, que és el cas quan tots dos provenen de la distribució.

L'indicador --spec determina el camí al codi font o paquet «wheel» que té el programa, i kirigami_hello és l'script executable que s'ha d'executar.

Per a construir i instal·lar el paquet Python, executeu:

pipx install --force --system-site-packages .

El paquet s'instal·larà a ~/.local/share/pipx/venvs/kirigami-python, i s'instal·larà un script executable a ~/.local/bin/kirigami_hello.

Ús de «pipx» versus «pip»

A diferència del Python amb el Kirigami: creació d'un paquet Python, aquesta guia d'aprenentatge ha utilitzat pipx per a fer el projecte més fàcil d'executar i instal·lar. Els mateixos passos es poden fer manualment amb venv, build i pip com en el tutorial més complet.

El pipx és útil i recomanat segons el PEP 668 per a executar aplicacions Python, mentre que el pip és multiús i també es pot utilitzar per a mòduls Python importables.

Després d'això, l'aplicació es pot llançar executant:

kirigami_hello

Per a executar la nova aplicació QML en mode de mòbil, podeu utilitzar QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Heus aquí! Ara veureu aparèixer la vostra primera aplicació escrita amb el Kirigami.

Docs: Configuració amb el Rust

Mon, 01 Jan 0001 00:00:00 +0000

Instal·lació del Kirigami

Abans de començar, haurem d'instal·lar el Kirigami i el Rust a la nostra màquina.

Manjaro Arch

sudo pacman -S cargo cmake extra-cmake-modules kirigami breeze qqc2-desktop-style

OpenSUSE

sudo zypper install cargo cmake kf6-extra-cmake-modules kf6-kirigami-devel qt6-quickcontrols2-devel kf6-qqc2-desktop-style-devel

Fedora

sudo dnf install cargo cmake extra-cmake-modules kf6-kirigami-devel kf6-qqc2-desktop-style

Trobareu més informació sobre les altres distribucions a Instal·lació de dependències de construcció.

Estructura del projecte

Primer crearem la nostra carpeta de projecte (podeu utilitzar les ordres de sota). L'anomenarem kirigami_rust/. Aquesta serà l'estructura del projecte:

kirigami_rust/
├── CMakeLists.txt
├── Cargo.toml
├── build.rs
├── org.kde.kirigami_rust.desktop
└── src/
├── main.rs
└── qml/
└── Main.qml

Aquest projecte utilitzarà el CMake per cridar el Cargo, que al seu torn construirà el projecte.

Sobre el CMake i el Cargo

Aquesta és no la forma tradicional de construir un projecte Rust: tècnicament, només es necessita el Cargo per construir-lo, normalment amb cargo build i cargo run.

Per a aplicacions d'escriptori, però, el CMake (o un equivalent com el Meson utilitzat pel GNOME o el Just utilitzat pel COSMIC) és necessari per instal·lar perquè el Cargo no té les característiques necessàries per a instal·lar aplicacions IGU d'escriptori.

El projecte s'anomenarà kirigami_rust i generarà un executable anomenat kirigami_hello.

💡 Consell

Podeu generar ràpidament aquesta estructura de fitxers amb: mkdir -p kirigami_rust/src/qml/.

org.kde.kirigami_rust.desktop

Ha de seguir un esquema de noms DNS invers seguit de l'extensió .desktop com ara org.kde.kirigami_rust.desktop:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


[Desktop Entry]
Name=Kirigami Tutorial in Rust
Name[ar]=درس كيريغامي برست
Name[ca]=Guia d'aprenentatge del Kirigami en Rust
Name[es]=Tutorial de Kirigami en Rust
Name[fr]=Tutoriel pour Kirigami en Rust
Name[it]=Esercitazione di Kirigami in Rust
Name[nl]=Kirigami handleiding in Rust
Name[pt_BR]=Tutorial do Kirigami em Rust
Name[ro]=Îndrumar Kirigami în Rust
Name[ru]=Учебное руководство по Kirigami на Rust
Name[sk]=Tutoriál Kirigami v Ruste
Name[sl]=Učbenik Kirigami v Rustu
Name[sv]=Kirigami-handledning i Rust
Name[tr]=Rust ile Kirigami Öğreticisi
Name[uk]=Підручник з Kirigami для Rust
Exec=kirigami_hello
Icon=kde
Type=Application
Terminal=false
Categories=Utility

CMakeLists.txt

El fitxer CMakeLists.txt s'utilitzarà per a executar el Cargo i instal·lar els fitxers necessaris juntament amb la nostra aplicació. També proporciona certes característiques de qualitat de vida, com assegurar-se que el Kirigami s'instal·la durant la compilació i senyalitzar distribucions de Linux per a instal·lar les dependències necessàries amb l'aplicació.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cmake_minimum_required(VERSION 3.28)

project(kirigami_rust)

find_package(ECM 6.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
include(KDEInstallDirs)
include(ECMUninstallTarget)

include(ECMFindQmlModule)
ecm_find_qmlmodule(org.kde.kirigami REQUIRED)
find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)

add_custom_target(kirigami_rust
 ALL
 COMMAND cargo build --target-dir ${CMAKE_CURRENT_BINARY_DIR}
)

install(
 PROGRAMS ${CMAKE_CURRENT_BINARY_DIR}/debug/kirigami_hello
 DESTINATION ${KDE_INSTALL_BINDIR}
)

install(FILES org.kde.kirigami_rust.desktop DESTINATION ${KDE_INSTALL_APPDIR})

El primer que fem és afegir els Mòduls extres del CMake (ECM) de KDE al nostre projecte perquè puguem utilitzar el ecm_find_qml_module per a comprovar que el Kirigami està instal·lat quan s'intenta construir l'aplicació, i si no ho està, falla immediatament. Una altra característica útil de l'ECM és ECMUninstallTarget, que permet desinstal·lar fàcilment l'aplicació amb el CMake si es desitja.

També utilitzem el find_package() del CMake per assegurar-nos que tenim l'estil qqc2-desktop-style, l'estil QML de KDE per a l'escriptori. Aquesta és una de les dues raons per les quals utilitzem el CMake en aquesta guia d'aprenentatge.

Normalment, els projectes Rust es construeixen amb el Cargo, i aquí no serà diferent. Creem un objectiu que simplement executarà el Cargo quan s'executi, i el marcarà amb ALL perquè es construeixi de manera predeterminada. El Cargo construirà l'executable dins del directori binari del CMake (normalment build/).

Per a més informació sobre el CMake, els objectius i el directori binari, vegeu Construir manualment el programari KDE.

Després d'això, simplement instal·lem l'executable kirigami_rust generat pel Cargo al directori binari i l'instal·lem al BINDIR, que sol ser /usr/bin, /usr/local/bin o ~/.local/bin. També instal·lem el fitxer d'escriptori necessari a APPDIR, que sol ser /usr/share/applications o ~/.local/share/applications. Aquesta és la segona raó per la qual utilitzem el CMake en aquesta guia d'aprenentatge.

Per a més informació sobre on s'instal·la el programari de KDE, vegeu Construir manualment el programari de KDE: El pas d'instal·lació.

Ara que ens hem revisat el CMake, vegem els fitxers als quals dedicarem la major part del nostre temps de treball.

Cargo.toml

A continuació tenim un Cargo.toml molt senzill:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


[package]
name = "kirigami_hello"
version = "0.1.0"
authors = [ "Konqi the Konqueror <konqi@kde.org>" ]
edition = "2024"
license = "GPLv3"

[dependencies]
cxx = "1.0.194" # Check the latest available version at https://crates.io/crates/cxx

# Check the latest available version of all related cxx-qt crates at https://crates.io/crates/cxx-qt
cxx-qt = "0.8.1"
cxx-qt-lib = { version="0.8.1", features = ["qt_full"] }
cxx-qt-lib-extras = "0.8.1"

[build-dependencies]
# The link_qt_object_files feature is required for statically linking Qt 6.
cxx-qt-build = { version = "0.8.1", features = [ "link_qt_object_files" ] }

Consisteix en metadades del projecte i una llista de dependències que el Cargo extraurà automàticament, és a dir, cxx i cxx-qt, que són necessàries per a executar aplicacions Qt escrites en Rust.

build.rs

On al C++ normalment registrareu elements QML amb QML_ELEMENT i el ecm_add_qml_module utilitzant el registre declaratiu, amb el Rust haureu de declarar-ho en un fitxer build script build.rs:

1
2
3
4
5
6
7
8
9


use cxx_qt_build::{CxxQtBuilder, QmlModule};

fn main() {
 CxxQtBuilder::new_qml_module(
 QmlModule::new("org.kde.tutorial")
 .qml_files(&["src/qml/Main.qml"])
 )
 .build();
}

Això és necessari per a fer que el fitxer QML estigui disponible en el punt d'entrada de la nostra aplicació, main.rs.

src/main.rs

El fitxer kirigami_rust/src/main.rs inicialitza el projecte i després carrega el fitxer QML, que consistirà en la interfície d'usuari per a l'aplicació.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


use cxx_qt_lib::{QGuiApplication, QQmlApplicationEngine, QQuickStyle};
use cxx_qt_lib_extras::QApplication;
use std::env;

fn main() {
 let mut app = QApplication::new();
 let mut engine = QQmlApplicationEngine::new();

 // To associate the executable to the installed desktop file
 QGuiApplication::set_desktop_file_name(&"org.kde.kirigami_rust".into());
 // To ensure the style is set correctly
 let style = env::var("QT_QUICK_CONTROLS_STYLE");
 if style.is_err() {
 QQuickStyle::set_style(&"org.kde.desktop".into());
 }

 if let Some(engine) = engine.as_mut() {
 engine.load(&"qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml".into());
 }

 if let Some(app) = app.as_mut() {
 app.exec();
 }
}

La primera part que està marcada amb la macro del Rust #[cxx_qt::bridge] només crea un QObject fictici a partir d'una estructura Rust fictícia. Això és necessari només per a completar l'ús del QmlModule a l'script de construcció anterior build.rs. Això jugarà un paper més important en una guia d'aprenentatge futura ensenyant com exposar el codi Rust al QML, però per ara el podeu ignorar.

Després d'això comença la part important:

Les línies 12-13 importen les biblioteques Qt necessàries exposades a través de cxx-qt.

Primer creem una instància nova d'una QApplication i després realitzem algunes integracions en les línies 20-26.

Després ve la part que realment crea la finestra de l'aplicació:

L'URL llarg qrc:/qt/qml/org/kde/tutorial/src/qml/Main.qml correspon al fitxer Main.qml d'acord amb el Sistema de recursos Qt, i segueix aquest esquema: <resource_prefix><import_URI><QML_dir><file>.

En altres paraules: el prefix de recurs predeterminat qrc:/qt/qml/ + l'URI d'importació org/kde/tutorial (establert a build.rs, separat per barres en lloc de punts) + el directori QML src/qml/ + el fitxer QML Main.qml.

src/qml/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 title: "Hello World"

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: "Hello World!"
 }
 }
}

Aquí és on manejarem el frontal de la nostra aplicació.

Per ara, centrem-nos en Main.qml. Primer importarem diversos mòduls importants:

QtQuick, la biblioteca estàndard utilitzada en les aplicacions QML.
QtQuick Controls, que proporciona una sèrie de controls estàndard que podem utilitzar perquè les nostres aplicacions siguin interactives.
QtQuick Layouts, que proporciona eines per a col·locar els components dins de la finestra de l'aplicació.
El Kirigami, que proporciona una sèrie de components adequats per a crear aplicacions que funcionen en dispositius de formes i mides diferents.

Nota

Després, establim la propietat id de la finestra a "root". Els ID són útils perquè ens permeten fer referència de forma única a un component, fins i tot si en tenim diversos del mateix tipus.

També establim la propietat title de la finestra a "Hola món".

Després establirem la primera pàgina de la nostra pila de pàgines. La majoria de les aplicacions escrites amb el Kirigami estan organitzades com una pila de pàgines, cada pàgina conté els components relacionats adequats per a una tasca específica. Per ara, el mantenim senzill i ens cenyim a una sola pàgina. pageStack és una pila inicialment buida de pàgines proporcionades per Kirigami.ApplicationWindow, i amb pageStack.initialPage: Kirigami.Page{...} establim la primera pàgina presentada en carregar l'aplicació a una Kirigami.Page. Aquesta pàgina contindrà tot el nostre contingut.

Compilar i instal·lar l'aplicació

Hauríeu de trobar l'executable generat kirigami_hello a build/debug/kirigami_hello i podeu executar-lo directament o amb cargo run, però no tindrà una icona de finestra. Per a solucionar-ho, primer instal·larem l'aplicació.

Executeu el següent:

cmake -B build --install-prefix ~/.local
cmake --build build/
cmake --install build/

Amb la primera ordre, el CMake cercarà el Kirigami i el qqc2-desktop-style.

Amb la segona ordre, el CMake construirà l'objectiu kirigami_rust, que només crida cargo build --target-dir build/. Aquest pas trigarà una estona a completar-se, però la pròxima vegada que repetiu la segona ordre del CMake serà més ràpida o no caldrà compilar res.

En el tercer pas, el CMake instal·larà l'executable kirigami_hello a ~/.local/bin/kirigami_hello i el fitxer d'escriptori a ~/.local/share/applications, i apareixerà una entrada nova al menú anomenada «Guia d'aprenentatge del Kirigami en Rust».

Obriu l'entrada de menu i heus aquí! Ara veureu aparèixer la vostra primera aplicació escrita amb el Kirigami.

Per a executar la nova aplicació QML en mode de mòbil, podeu utilitzar QT_QUICK_CONTROLS_MOBILE=1:

QT_QUICK_CONTROLS_MOBILE=1 kirigami_hello

Si heu compilat el projecte manualment amb el CMake i per algun motiu voleu desinstal·lar el projecte, podeu executar:

cmake --build build/ --target uninstall

Docs: Explicar les pàgines

Mon, 01 Jan 0001 00:00:00 +0000

La nostra aplicació

A la guia d'aprenentatge anterior, hem aconseguit configurar, construir i compilar la nostra primera aplicació escrita amb el Kirigami. Amb els conceptes bàsics en el seu lloc, podem començar el nostre viatge cap a la creació d'una aplicació amb totes les característiques.

Aquestes guies d'aprenentatge se centraran a crear una aplicació que permeti a l'usuari veure quants dies queden fins a un esdeveniment de la seva elecció.

També us recomanem que consulteu la Kirigami Gallery, que proporciona una sèrie d'exemples útils d'interfície d'usuari.

En aquesta secció ens centrarem en les pàgines, un dels elements estructurals clau de qualsevol aplicació escrita amb el Kirigami.

Pàgines

Les aplicacions escrites amb el Kirigami solen estar organitzades en Kirigami.Page. Les pàgines són les «pantalles» diferents d'una aplicació. Voldreu tenir una pàgina dedicada a aspectes específics de la interacció amb la vostra aplicació, i per a facilitar les coses podreu crear fitxers QML diferents, un per a cada pàgina.

Les pàgines estan organitzades en una pila de pàgines on es podran empènyer i fer aparèixer. En un telèfon només es mostrarà la pàgina superior, mentre que en una pantalla més gran (escriptori o tauleta), si es desitja, es podran mostrar diverses pàgines una al costat de l'altra.

Una pàgina única al telèfon

Dues pàgines una al costat de l'altra a l'escriptori

Nota

Una Kirigami.Page hereta d'un Controls.Page, i com a tal, també podeu utilitzar les propietats d'aquest últim.

Quan cerqueu a la documentació de l'API del QML, assegureu-vos també de cercar les funcions i propietats heretades per l'API que esteu cercant.

Tornem al fitxer Main.qml que hem creat en la nostra guia d'aprenentatge anterior:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


// Includes relevant modules used by the QML
import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// Provides basic features needed for all kirigami applications
Kirigami.ApplicationWindow {
 // Unique identifier to reference this object
 id: root

 width: 400
 height: 300

 // Window title
 // i18nc() makes a string translatable
 // and provides additional context for the translators
 title: i18nc("@title:window", "Hello World")

 // Set the first page that will be loaded when the app opens
 // This can also be set to an id of a Kirigami.Page
 pageStack.initialPage: Kirigami.Page {
 Controls.Label {
 // Center label horizontally and vertically within parent object
 anchors.centerIn: parent
 text: i18n("Hello World!")
 }
 }
}

Fem que la nostra aplicació comenci a la nostra Kirigami.Page. Tot el que hi hem inclòs és una etiqueta que conté «Hello World», però arreglarem una mica les coses.

La idea darrere de la nostra aplicació és que podrem mostrar a l'usuari un munt de comptes enrere. El problema amb una Kirigami.Page normal és que té una mida vertical fixa, així que en el seu lloc farem servir una Kirigami.ScrollablePage, que ja ve amb la seva pròpia barra de desplaçament integrada.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")
 }
}

Les pàgines escrites amb el Kirigami també compten amb títols niuats col·locats dins de la barra d'eines, indicant ràpidament a l'usuari en quina pàgina es troba. Tot el que necessitem fer per a establir un títol de pàgina és emprar la propietat title de la Kirigami.ScrollablePage. En aquest cas, per a aquesta finalitat utilitzarem una de les funcions i18nc() que hem explorat en la nostra guia d'aprenentatge anterior.

Nota

També podeu optar per definir la vostra pàgina dins del seu propi document QML. Per a fer-ho, cal crear el fitxer QML nou, per exemple kirigami-tutorial/src/qml/StartPage.qml, i afegir-lo al fitxer kirigami-tutorial/src/CMakeLists.txt i establir la finestra de la primera pàgina per a carregar-lo, com així:

pageStack.initialPage: Qt.resolvedUrl("StartPage.qml")

pageStack.initialPage estableix la pàgina inicial de la pila de pàgines de l'aplicació, i Qt.resolvedUrl converteix l'URL relatiu del fitxer QML en un d'absolut.

Hi ha més informació sobre estructures de pàgina alternatives dins la documentació del Kirigami.

Docs: Disposicions (Layout), vistes de llista (ListView) i targetes (Card)

Mon, 01 Jan 0001 00:00:00 +0000

Dissenyar el contingut

Ara que entenem com funcionen les pàgines, és hora d'afegir-hi coses. Repassarem una sèrie de components i elements de disposició importants que seran útils en dissenyar la nostra aplicació.

Al final d'aquesta secció tindreu una aplicació d'aspecte polit.

Vistes de llista (ListView)

Si heu emprat alguna vegada el Discover, el NeoChat o l'Arranjament del sistema del Plasma, us haureu trobat amb una ListView. En poques paraules, les vistes de llista permeten mostrar les dades en una llista.

pageStack.initialPage: Kirigami.ScrollablePage {
 // ...
 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
}

Això sembla críptic, però no us preocupeu. Comencem des del principi.

Ara afegirem aquest component dins del nostre Kirigami.ScrollablePage de la darrera guia d'aprenentatge.

Estem emprant la Kirigami.CardsListView, que és una ListView que ens permet mostrar targetes en una llista amb facilitat. No obstant això, les ListViews estan fetes per a mostrar les dades preses a partir d'un model, per a emplenar-se automàticament a partir d'un conjunt de dades a les quals apuntem. Aquí és on entra la propietat model: en aquest exemple, apunta a kountdownModel.

Model

Kirigami.ApplicationWindow {
 // ...
 ListModel {
 id: kountdownModel
 // Cada ListElement és un element en la llista que conté informació
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }
 // ...
}

Afegirem el kountdownModel dins de la Kirigami.ApplicationWindow de la darrera guia d'aprenentatge.

Un model defineix la manera en què s'estructura una entrada de dades. Per ara, el nostre kountdownModel només consistirà d'un element. Si mirem el nostre ListElement anterior, veurem com s'estructuren els elements del kountdownModel: conté un nom, una descripció i una data. Això no és immutable, i podeu tenir diversos tipus de dades en el vostre model. Els dos primers són cadenes i el tercer és un número que utilitzem com a marcador de posició.

Nota

Com que el QML està construït sobre el JavaScript, moltes de les característiques d'aquest llenguatge estan disponibles per al seu ús en fitxers QML. No obstant això, les variables QML s'han de prefixar amb property, a menys que estigui dins d'un bloc de codi JS. Podeu llegir-ne més en aquesta pàgina.

Els models també són útils perquè es poden modificar mitjançant l'ús de diversos mètodes. Alguns importants són:

ListModel.append(yourobject: jsobject) afegeix un objecte de JavaScript (JSObject) yourobject al ListModel, i el col·loca després de l'últim element del model. Perquè això succeeixi correctament, cal proporcionar un objecte JSObject amb les propietats correctes i els tipus de dades corresponents.
ListModel.get(index: int) retorna el JSObject en la ubicació de l'índex que heu proporcionat.
ListModel.remove(index: int, count: int) elimina el JSObject en la ubicació proporcionada index, i tantes com vulgueu després d'aquesta ubicació de l'índex com indiqueu a count (1 només inclou el JSObject a l'índex proporcionat).
ListModel.set(index: int, yourobject: jsobject) canvia l'element en la ubicació proporcionada de index amb els valors proporcionats a yourobject. Les mateixes regles que amb .append().

Delegats

Mentre que kountdownModel conté les dades que es mostraran, el nostre kountdownDelegate gestionarà com es mostraran les dades a la ListView. Per això farem servir una Kirigami.CardsListView dissenyada per a mostrar delegats del tipus targetes i aquests delegats es representaran visualment per mitjà d'una Kirigami.AbstractCard.

Els delegats reben automàticament les propietats de les instàncies ListElement que hem especificat en el nostre model. Per tant, només podem fer referència a les seves propietats name, description i date com si fossin variables convencionals dins del nostre delegat.

Construir la targeta de delegat

El Component que representarà el nostre delegat es pot afegir dins del nostre Kirigami.ApplicationWindow. Després comprovarem que fa cada part del nostre component delegat.

Kirigami.ApplicationWindow {
 // ...
 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 // implicitWidth/Height defineix l'amplada/altura natural d'un element si no se
 // n'especifica cap. La configuració següent defineix la mida preferida d'un
 // component en funció del seu contingut.
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 // onClicked: s'ha de fer... aviat!
 }
 }
 }
 }
 }
 // ...
}

implicitWidth i implicitHeight

A la primera part donarem un cop d'ull a com gestionar l'amplada i l'altura del nostre component:

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 // ...
 }
 }
}

Mirant la nostra Kirigami.AbstractCard, les primeres propietats que establim són implicitWidth i implicitHeight. Les hem establert a la delegateLayout.implicitWidth i delegateLayout.implicitHeight, és a dir, les implicitWidth i implicitHeight de l'element GridLayout.

Les amplades i alçades implícites són propietats disponibles en qualsevol Item que funcionen com a consells i s'estableixen com a valor predeterminat, o com a reserva, si no hi ha una amplada o altura explícita establerta per a aquests components. Aquests valors són predeterminats a 0x0, per tant, és molt important que els definiu en components Item en brut tal com s'ha fet anteriorment.

Aquí haurem establert la implicitWidth i implicitHeight de la nostra Kirigami.AbstractCard a la de la GridLayout següent per a assegurar-nos que no desbordi la targeta. D'aquesta manera, la targeta pren tant espai com sigui necessari per al seu contingut.

Disposicions

La GridLayout es troba dins del component Item que hem proporcionat per a la propietat contentItem. Aquest és l'Item que conté el que es mostrarà a la targeta.

També haurem de triar una disposició «layout» per als nostres components, de manera que no s'apilin un damunt de l'altre. Hi ha tres tipus principals entre les quals podem triar:

ColumnLayout distribueix els components verticalment, en una sola columna
RowLayout distribueix els components horitzontalment, en una sola fila
GridLayout distribueix els components en una quadrícula amb una composició de la vostra elecció

Amb ColumnLayout i RowLayout, tot el que hem de fer és escriure els nostres components dins del component «Layout». Com podeu veure, hem optat per una GridLayout, la qual implica una mica més de treball manual.

GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2
 // ...
}

El primer que veieu és anchors. El sistema d'ancoratge de QtQuick proporciona una forma útil d'assegurar-vos que els components estiguin col·locats en certes parts d'un component pare. Hem ancorat la nostra GridLayout a l'esquerra, a dalt i a la dreta de la targeta principal, assegurant que el nostre contingut s'estengui per tota la targeta.

A continuació, especificarem l'espai entre les files i les columnes dins la nostra quadrícula, de manera que els nostres components no s'amunteguin. El Kirigami proporciona una sèrie d'útils unitats predefinides per a utilitzar amb aquest propòsit:

Unitat de Kirigami	Píxels
smallSpacing	4px
largeSpacing	8px
gridUnit	18px

Nota

El Grup de Disseny Visual de KDE (VDG) té molta més informació sobre les diferents unitats definides en el Plasma i el Kirigami a les Directrius d'interfície humana.

Com recordareu, root és l'identificador de la nostra Kirigami.ApplicationWindow. Proporciona la propietat wideScreen, utilitzada per a determinar si la pantalla del dispositiu actual és una pantalla ampla (és a dir, un monitor d'ordinador o un telèfon apaïsat). Aquí utilitzem un condicional ternari per a variar el nombre de columnes a la nostra quadrícula depenent de la pantalla que utilitzem: si és una pantalla ampla, la quadrícula tindrà 4 columnes, en cas contrari en tindrà 2.

Components interns

Podríem crear tres etiquetes dins del nostre component delegat i cridar-les un dia. Però això no es veuria particularment bonic. Farem ús d'alguns components més adequats:

GridLayout {
 // ...
 Kirigami.Heading {
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }

 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }

 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }

 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 }
}

Com es veu la targeta personalitzada

A l'esquerra, Kirigami.Heading: utilitza la date d'un ListElement com una capçalera de nivell 1.
Al mig, ColumnLayout: té una Kirigami.Heading que mostra el nom de la tasca; un Kirigami.Separator, el qual proporciona la línia en horitzontal; i un Controls.Label, que mostra una descripció opcional de la tasca. Els dos últims components tenen una propietat visible, la qual comprova si la descripció està buida o no, i mostra els components segons el resultat de description.length > 0.
A la dreta, Controls.Button: un botó que farà alguna cosa... aviat!

La nostra aplicació fins ara

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // ListModel needed for ListView, contains elements to be displayed
 ListModel {
 id: kountdownModel
 // Each ListElement is an element on the list, containing information
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 // Level determines the size of the heading
 level: 1
 text: date
 }

 // Layout for positioning elements vertically
 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 // Horizontal rule
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 // Labels contain text
 Controls.Label {
 Layout.fillWidth: true
 // Word wrap makes text stay within box and shift with size
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 // Column spanning within grid layout (vertically in this case)
 Layout.columnSpan: 2
 text: i18nc("@action:button","Edit")
 //onClicked: to be done...
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // List view for card elements
 Kirigami.CardsListView {
 id: cardsView
 // Model contains info to be displayed
 model: kountdownModel
 // Delegate is how the information will be presented in the ListView
 delegate: kountdownDelegate
 }
 }
}

Així que aquí està la nostra targeta bàsica!

Amb aquests passos, hem establert les bases bàsiques per a afegir tota la funcionalitat a la nostra aplicació.

Docs: Afegir accions

Mon, 01 Jan 0001 00:00:00 +0000

Recapitulació

Fins ara, hem construït una aplicació senzilla que pot mostrar targetes. No obstant això, encara no hi ha cap manera que l'usuari afegeixi targetes noves a la vista de targetes.

En aquesta guia d'aprenentatge, veurem les accions de Kirigami. Aquestes ens ajudaran a afegir interactivitat a la nostra aplicació d'una manera coherent, ràpida i accessible.

Accions

Una Kirigami.Action encapsula una acció de la interfície d'usuari. Podem utilitzar-les per a proporcionar a les nostres aplicacions accions de fàcil accés que són essencials per a la seva funcionalitat.

Si heu emprat abans les aplicacions escrites en Kirigami, certament heu interactuat amb les accions del Kirigami. En aquesta imatge, podem veure les accions a la dreta del títol de la pàgina amb diverses icones. Les accions del Kirigami es poden mostrar de diverses maneres i poden realitzar una àmplia varietat de coses.

Afegir comptes enrere

Una aplicació de compte enrere és força inútil sense la capacitat d'afegir-ne. Crearem una acció que ens permeti fer-ho.

pageStack.initialPage: Kirigami.ScrollablePage {
 // Altres propietats de la pàgina...
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]
 // ...
}

Estem col·locant la nostra Kirigami.Action dins de la nostra pàgina principal a partir de les guies d'aprenentatge anteriors. Si volguéssim, podríem afegir més accions a la nostra pàgina (i fins i tot niar accions dins d'accions!).

Els claudàtors [], que s'han utilitzat anteriorment són similars a les matrius de JavaScript, el qual vol dir que podeu passar-hi una o més coses, separades per comes:

// Matriu general de components JavaScript:
variable: [ component1, component2 ]
// Passar una matriu d'accions del Kirigami al QML:
actions: [ Kirigami.Action {}, Kirigami.Action {} ]

Les propietats id i text haurien de ser familiars de guies d'aprenentatge anteriors. No obstant això, la propietat nova heretada Action.icon hauria de ser interessant: és un objecte amb diverses propietats que permet mostrar certes icones per a les vostres accions. Afortunadament, per a utilitzar les icones del KDE, tot el que hem de fer és proporcionar el nom de la propietat per a la propietat d'icona, icon.name.

Visualització de les icones disponibles

Feu clic aquí per a veure com comprovar les icones disponibles al sistema

L'Explorador d'icones és una aplicació KDE que permet veure totes les icones que podreu utilitzar per a la vostra aplicació. Ofereix una sèrie de característiques útils: com vistes prèvies de la seva aparença en els diferents temes instal·lats, vistes prèvies en mides diferents i més. Potser us resultarà una eina útil a l'hora de decidir quines icones emprar en la vostra aplicació.

Moltes de les icones del KDE segueixen l'especificació d'anomenat d'icones de FreeDesktop. Per tant, també pot resultar útil consultar el lloc web del projecte FreeDesktop, el qual llista tots els noms d'icones compatibles amb tots els escriptoris.

El controlador de senyals onTriggered és el més important. És el que farà la nostra acció quan s'utilitzi. Notareu que en el nostre exemple fem servir el mètode kountdownModel.append del kountdownModel que hem creat en la nostra guia d'aprenentatge anterior. Aquest mètode ens permet afegir un element nou al nostre model de llista. Proporcionem un objecte (indicat per les claus {}) que té les propietats rellevants per als nostres comptes enrere (name, description i una date de marcador de posició).

Cada vegada que fem clic sobre el nostre botó «Add kountdown» que hi ha a la part superior dreta, s'afegirà el nostre compte enrere personalitzat.

Versió mòbil

Calaix global

El component següent és un Kirigami.GlobalDrawer. Es mostra com un menú d'hamburguesa. De manera predeterminada obre una barra lateral, que és especialment útil en el mòbil, ja que l'usuari pot lliscar en un costat de la pantalla per a obrir-la. Els calaixos globals són útils per a la navegació i les accions globals. Crearem un calaix global senzill que inclou un botó «quit».

Kirigami.ApplicationWindow {
 id: root
 // Altres propietats de les finestres...
 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
 // ...
}

Aquí, col·locarem el nostre calaix global dins de la finestra de la nostra aplicació. La propietat principal a la qual hem de parar atenció és GlobalDrawer.actions, que pren la forma d'una matriu de components Kirigami.Action. Aquesta acció té una icona adequada i executa la funció Qt.quit() quan s'activa, tancant l'aplicació.

Atès que, per ara, mantenim senzill el nostre calaix global, establim la propietat GlobalDrawer.isMenu a true. Això mostrarà el nostre calaix global com un menú normal d'aplicació, ocupant menys espai que la subfinestra predeterminada del calaix global.

Calaix global

Calaix global com a menú

Consell

La pàgina components basats en Actions d'aquesta documentació, proporciona més detalls sobre les accions del Kirigami i com es poden utilitzar.

Les accions són contextuals

Els components del Kirigami estan dissenyats de tal manera que el lloc on poseu les accions del Kirigami és rellevant. Com s'ha vist anteriorment, si afegiu accions a una Kirigami.Page, Kirigami.ScrollablePage o qualsevol altre component derivat de pàgina, es mostraran a la part dreta de la capçalera en el mode d'escriptori i a la part inferior en el mode de mòbil.

De manera similar, si les accions del Kirigami s'afegeixen a un Kirigami.GlobalDrawer, es mostraran al calaix o menú resultant.

Altres exemples d'accions del Kirigami que es mostren de manera diferent depenent del seu component pare són:

Entre altres components del Kirigami.

La nostra aplicació fins ara

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 400
 height: 300

 title: i18nc("@title:window", "Day Kountdown")

 // Global drawer element with app-wide actions
 globalDrawer: Kirigami.GlobalDrawer {
 // Makes drawer a small menu rather than sliding pane
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 ListElement {
 name: "Dog birthday!!"
 description: "Big doggo birthday blowout."
 date: 100
 }
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 Layout.fillHeight: true
 level: 1
 text: date
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: kountdownModel.append({
 name: "Kirigami Action added card!",
 description: "Congratulations, your Kirigami Action works!",
 date: 1000
 })
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: Afegir un diàleg

Mon, 01 Jan 0001 00:00:00 +0000

Fer que la nostra aplicació sigui útil

Tenim una finestra, tenim targetes i tenim accions. No obstant això, encara necessitem trobar alguna forma d'introduir un nom, una descripció i una data de la nostra elecció.

Una manera en què podríem fer això és creant una pàgina nova on col·loquem els elements d'introducció requerits. No obstant això, una pàgina sencera dedicada a proporcionar un nom, una descripció i una data sembla una mica excessiu.

En el seu lloc, utilitzarem un diàleg.

Obrir el diàleg

pageStack.initialPage: Kirigami.ScrollablePage {
 // ...
 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]
}

Primer editarem l'acció de la guia d'aprenentatge anterior: només una Kirigami.Action que activi la funció open() del diàleg.

Diàlegs que afegeixen un compte enrere

El component nou que afegim és un Kirigami.Dialog. Els diàlegs apareixen al centre de la finestra i es poden utilitzar per a proporcionar informació addicional rellevant per al contingut actual. No es poden moure, però adapten la seva mida a la finestra.

Kirigami.ApplicationWindow {
 // ...
 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Les disposicions de formulari ajuden a alinear i estructurar una disposició amb diverses
 // entrades
 Kirigami.FormLayout {
 // Els camps de text permeten introduir text en un quadre de text fi
 Controls.TextField {
 id: nameField
 // Proporciona una etiqueta adjuntada al camp de text
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // Què s'ha de fer després d'acceptar l'entrada (p. ex. es prem Retorn) En aquest
 // cas, mou el focus al camp següent
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // De nou, mou el focus al camp següent
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D significa un nombre necessari entre 1-9, 9 significa un nombre necessari entre
 // 0-9
 inputMask: "D999-99-99"
 // Aquí confirmem l'operació igual que fer clic al botó D'acord
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // La lògica del diàleg va aquí
 }
 // ...
}

De manera predeterminada, els diàlegs tenen una header (capçalera) i un footer (peu), tots dos heretats de Controls.Dialog.

La capçalera per defecte inclou un title (títol) i un botó de tancament que es pot desactivar amb showCloseButton. El peu predeterminat no inclou cap botó. Això es pot anul·lar amb standardButtons.

Primer, l'establim per a mostrar un botó «Ok» i un botó «Cancel·la», afegir algun farciment i afegir una preferredWidth raonable. L'amplada preferida és la mida esperada predeterminada del diàleg, que pot augmentar si cal. Podem utilitzar Kirigami.Units que tornarem a revisar més endavant.

Després arribem a un Kirigami.FormLayout. A diferència del ColumnLayout, la disposició dels seus components fills és automàtica i centrada, amb etiquetes opcionals. Com el nom indica, s'utilitza per a crear formularis d'entrada.

Aquestes disposicions de formulari estan dissenyades per a funcionar amb diversos tipus d'entrada diferents, encara que ens cenyim a entrades senzilles Controls.Textfield que ens brinden quadres de text senzills per a escriure-hi.

Hem creat elements Textfield que actuen com:

Entrada per al nom del nostre compte enrere
Entrada per a la descripció del nostre compte enrere
Entrada per a la data cap a la qual estem comptant cap enrere, la qual s'ha de proporcionar en el format YYYY-MM-DD

Dins de cadascun d'aquests elements Controls.TextField, estem establint una propietat Kirigami.FormData.label que permet definir etiquetes per a ells. El formulari presentarà les etiquetes correctes a l'esquerra de cadascun d'aquests camps d'entrada de text.

Finalment, també estem establint la propietat onAccepted per a activar el mètode forceActiveFocus() del camp següent; això canviarà el camp actiu una vegada que l'usuari prem la tecla Retorn, millorant la usabilitat del formulari.

També hem establert una propietat anomenada inputMask en el camp de text per a la nostra data. Establint això a D999-99-9 evitarà que els usuaris introdueixin alguna cosa que pugui trencar la funcionalitat de l'aplicació (com ara text), restringint-lo a només la introducció de dígits, després podrem intentar analitzar-ho en un objecte de data.

Un cop feta la interfície d'usuari del diàleg, hem de canviar com es comporta. Per a això necessitem tres coses:

Mostrar el botó Ok només quan s'omplin els camps requerits
Afegir la informació d'entrada al model
Netejar el formulari d'entrada

Kirigami.Dialog {
 // ...Un cop el Kirigami.Dialog està inicialitzat, volem crear una vinculació personalitzada per
 // a només fer visible el botó Ok si s'omplen els camps de text requerits. Per a això utilitzem
 // el Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => és una funció de fletxa del JavaScript
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // Es crea el vincle, però encara cal fer-lo no clicable a menys que s'omplin els camps
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
}

El primer que s'ha de fer és crear una vinculació entre la propietat activada del botó OK i una comprovació de si els camps s'omplen, que en aquest cas s'ha de fer amb Qt.binding() en JavaScript. En efecte, la línia:

button.enabled = Qt.binding( () => requiredFieldsFilled() );

és similar a les vinculacions en QML que hem vist fins ara, com en el pseudocodi següent:

enabled: requiredFieldsFilled()

El gestor de senyal que activa el botó Ok és onAccepted. Es manté buit i sense fer res si s'omplen els camps requerits; en cas contrari, afegirà l'entrada al model i netejarà el diàleg per a la pròxima vegada que s'obri.

Kirigami.Dialog {
 // ...Comprovem que el «nameField» no estigui buit i que el «dateField» (que té una «inputMask»)
 // estigui completament omplert
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

Per al nostre camp de nom requerit, tot el que hem de fer és comprovar si el text del camp és una cadena buida. Per al camp de data, com que té una màscara d'entrada, cal utilitzar acceptableInput en el seu lloc, el qual només serà cert una vegada que tot el camp s'ompli i només contingui caràcters acceptables.

Llavors, el mètode append() del nostre model de llista kountdownModel afegeix un objecte JavaScript incloent-hi les propietats que hem proporcionat.

Per a acabar, ens assegurem, de netejar els camps de text definint les propietats del seu text a una cadena buida, després fem un close().

Un cop desem els fitxers i construïm el programa, podrem afegir els nostres propis comptes enrere personalitzats! Podem fer un últim toc per a millorar la interfície, és a dir, eliminar el compte enrere fictici que teníem a les lliçons anteriors:

26
27
28


 ListModel {
 id: kountdownModel
 }

En segon lloc, ara que tenim una data real amb la qual jugar, podem calcular el temps fins a aquesta data:

47
48
49
50


 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

I en tercer lloc, augmentar la mida de la finestra perquè tinguem més espai per a les targetes noves:

 9
10


 width: 600
 height: 400

Molt millor.

La nostra aplicació fins ara

Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

Docs: Utilitzar fitxers separats en un projecte C++

Mon, 01 Jan 0001 00:00:00 +0000

Per què i com

Per primera vegada, separarem alguns dels nostres components en els seus propis fitxers en QML. Si seguim afegint coses a Main.qml, ràpidament serà difícil saber què fa què, i correm el risc d'enterbolir el nostre codi.

En aquesta guia d'aprenentatge, dividirem el codi de Main.qml en Main.qml, AddDialog.qml i KountdownDelegate.qml.

A més, fins i tot quan es dispersa el codi entre diversos fitxers QML, la quantitat de fitxers en projectes reals pot anar-se'n de les mans. Una solució habitual a aquest problema és separar lògicament fitxers en carpetes diferents. Farem una breu aproximació a tres enfocaments comuns vistos en projectes reals, i implementarem un d'ells:

emmagatzematge de fitxers QML juntament amb fitxers C++
emmagatzematge de fitxers en QML en un directori diferent dins del mateix mòdul
emmagatzematge de fitxers QML en un directori diferent dins d'un mòdul diferent

Després de la divisió, tindrem separació de preocupacions entre cada fitxer, i els detalls d'implementació s'abstrauran, fent el codi més llegible.

Emmagatzematge de fitxers QML juntament amb fitxers C++

Consisteix a mantenir els fitxers QML del projecte juntament amb els fitxers C++ a src/. Aquesta mena d'estructura es veuria així:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

Això és el que vam fer anteriorment. En el cas anterior, només hauríeu de continuar afegint fitxers QML al kirigami-tutorial/src/CMakeLists.txt existent. No hi ha cap separació lògica, i una vegada que el projecte obté més d'un parell de fitxers QML (i fitxers C++ que creen tipus que es faran servir en el QML), la carpeta es pot omplir ràpidament.

Emmagatzematge de fitxers en QML en un directori diferent dins del mateix mòdul

Consisteix a mantenir tots els fitxers QML en una carpeta separada, normalment src/qml/. Aquesta mena d'estructura es veuria així:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
└── qml/
├── Main.qml
├── AddDialog.qml
└── KountdownDelegate.qml

Aquesta estructura és molt habitual en els projectes KDE, principalment per a evitar tenir un fitxer CMakeLists.txt extra per al directori src/qml/ i crear un mòdul separat. Aquest mètode manté els fitxers en una carpeta separada, però també hauríeu d'afegir-los a kirigami-tutorial/src/CMakeLists.txt. Tots els fitxers QML creats pertanyen al mateix mòdul QML que Main.qml.

A la pràctica, una vegada que el projecte té més d'una dotzena de fitxers QML, tot i que no s'omplirà el directori src/, s'atapeirà el fitxer src/CMakeLists.txt. Es farà difícil diferenciar entre fitxers C++ tradicionals i fitxers C++ que tenen tipus exposats al QML.

També trencarà el concepte de localitat (localització de detalls de dependència), on mantindríeu la descripció de les dependències en el mateix lloc que les mateixes dependències.

Emmagatzematge de fitxers QML en un directori diferent dins d'un mòdul diferent

Això consisteix a mantenir tots els fitxers QML en una carpeta separada amb el seu propi CMakeLists.txt i un mòdul QML propi separat. Aquesta mena d'estructura es veuria així:

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml
└── components/
├── CMakeLists.txt
├── AddDialog.qml
└── KountdownDelegate.qml

Aquesta estructura no és tan habitual en els projectes KDE i requereix escriure un CMakeLists.txt addicional, però és la més flexible. En el nostre cas, donem nom a la nostra carpeta «components» ja que estem creant dos components QML nous a partir del fitxer Main.qml anterior, i mantenim la informació sobre ells a kirigami-tutorial/src/components/CMakeLists.txt. El fitxer Main.qml es manté a src/ de manera que s'utilitza automàticament quan s'executa l'executable, com abans.

Més tard, seria possible crear més carpetes amb diversos fitxers QML, tots agrupats per funcions, com ara «models» i «configuració», i els fitxers C++ que tenen tipus exposats al QML (com els models) es podrien mantenir juntament amb altres fitxers QML on tingui sentit.

Utilitzarem aquesta estructura en aquesta guia d'aprenentatge.

Preparar el CMake per als fitxers nous

Primer, creeu el fitxer kirigami-tutorial/src/components/CMakeLists.txt amb el contingut següent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Creem un objectiu nou anomenat kirigami-hello-components i després el convertim en un mòdul QML utilitzant ecm_add_qml_module() amb el nom d'importació org.kde.tutorial.components i afegim els fitxers QML pertinents.

Com que l'objectiu és diferent de l'executable, funcionarà com un mòdul QML diferent, en aquest cas el necessitarem fer dues coses: fer que generi el codi perquè funcioni com a un connector Qt amb GENERATE_PLUGIN_SOURCE, i finalitzar-lo amb ecm_finalize_qml_module(). Després l'instal·lem exactament igual que en les lliçons anteriors.

Necessitàvem utilitzar add_library() perquè puguem enllaçar kirigami-hello-components amb l'executable a la crida target_link_libraries() a kirigami-tutorial/src/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

També necessitem utilitzar add_subdirectory() perquè el CMake trobi el directori kirigami-tutorial/src/components/.

En les lliçons anteriors, no calia afegir la importació org.kde.tutorial al nostre Main.qml perquè no era necessari: sent el punt d'entrada de l'aplicació, l'executable executaria el fitxer immediatament de totes maneres. Com que els nostres components es troben en un mòdul QML separat, és necessària una importació nova a kirigami-tutorial/src/Main.qml, la mateixa definida anteriorment, org.kde.tutorial.components:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

// La resta del codi...

I ja estem preparats per a continuar.

Divisió de Main.qml

Tornem a fer un cop d'ull a l'original Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 Component {
 id: kountdownDelegate
 Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
 }
 }

 Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 // Form layouts help align and structure a layout with several inputs
 Kirigami.FormLayout {
 // Textfields let you input text in a thin textbox
 Controls.TextField {
 id: nameField
 // Provides a label attached to the textfield
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 // What to do after input is accepted (i.e. pressed Enter)
 // In this case, it moves the focus to the next field
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 placeholderText: i18n("Optional")
 // Again, it moves the focus to the next field
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 // D means a required number between 1-9,
 // 9 means a required number between 0-9
 inputMask: "D999-99-99"
 // Here we confirm the operation just like
 // clicking the OK button
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 // Once the Kirigami.Dialog is initialized,
 // we want to create a custom binding to only
 // make the Ok button visible if the required
 // text fields are filled.
 // For this we use Kirigami.Dialog.standardButton(button):
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 // () => is a JavaScript arrow function
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 // The binding is created, but we still need to make it
 // unclickable unless the fields are filled
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 // We check that the nameField is not empty and that the
 // dateField (which has an inputMask) is completely filled
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 // Kirigami.Action encapsulates a UI action. Inherits from Controls.Action
 actions: [
 Kirigami.Action {
 id: addAction
 // Name of icon associated with the action
 icon.name: "list-add-symbolic"
 // Action text, i18n function returns translated string
 text: i18nc("@action:button", "Add kountdown")
 // What to do when triggering the action
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: kountdownDelegate
 }
 }
}

El delegat personalitzat amb id: kountdownDelegate es pot dividir completament perquè ja està embolcallat en un tipus de component QML. Utilitzem un component per a poder definir-lo sense necessitat d'instanciar-lo; els fitxers QML separats funcionen de la mateixa manera.

Si movem el codi a fitxers separats, llavors no té sentit deixar-lo embolcallat en un component: podem dividir només la Kirigami.AbstractCard en el fitxer separat. Aquest és el KountdownDelegate.qml resultant:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

El nostre diàleg amb id: addDialog no està embolcallat en un component, i no és un component que sigui visible de manera predeterminada, així que el codi es pot copiar tal com està en el AddDialog.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

Amb la divisió del codi, Main.qml es fa molt més curt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

Ara tenim dos fitxers QML addicionals, AddDialog.qml i KountdownDelegate, i necessitem trobar alguna manera d'utilitzar-los a Main.qml. La manera d'afegir el contingut dels fitxers nous a Main.qml és instanciant-los.

AddDialog.qml esdevé AddEditDialog {}:

31
32
33


 AddDialog {
 id: addDialog
 }

KountdownDelegate.qml esdevé KountdownDelegate {}:

47
48
49
50
51


 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }

La majoria dels casos que heu vist d'un component començat per majúscules i seguit de parèntesis eren instàncies d'un component QML. Per això els fitxers QML nous han de començar per una lletra en majúscula.

Compileu el projecte i executeu-lo, i hauríeu de tenir una finestra funcional que es comporti exactament igual que abans, però amb el codi dividit en parts separades, fent les coses molt més manejables.

Docs: Passos següents

Mon, 01 Jan 0001 00:00:00 +0000

El que hem construït

En les últimes guies d'aprenentatge, heu creat una aplicació bàsica però funcional amb el Kirigami, que permet afegir, editar i eliminar comptes enrere de dates. En fer-ho, hem après sobre els components de Kirigami i QtQuick, quelcom del funcionament del QML, disposicions bàsiques d'aplicació i més. No està malament!

Ara compreneu els conceptes bàsics que formen moltes de les aplicacions més populars del KDE. Potser us esteu preguntant: I ara, què?

Bé, no us preocupeu: ens hem pres el temps per a donar-vos algunes indicacions sobre on podeu anar a partir d'aquí.

Col·laborar amb els projectes del KDE

Una de les millors formes de millorar les vostres habilitats de desenvolupament és posant-les en pràctica. La comunitat KDE és acollidora i sempre busca més desenvolupadors apassionats!

Tenim diversos documents que poden ajudar-vos a fer que us convertiu en col·laborador. Us recomanem que vegeu les altres pàgines de desenvolupament, la qual pot ajudar-vos a obtenir més informació sobre el flux de treball de desenvolupament de la comunitat KDE. També recomanem que doneu un cop d'ull a la nostra documentació sobre la instància de GitLab de KDE, anomenada Invent, ja que probablement necessitareu interactuar amb ella durant el procés de desenvolupament. La comunitat KDE interactua principalment a través de Matrix, i també tenim una pàgina al wiki de la comunitat que us guiarà per a configurar el vostre propi compte.

Nota

Mentre interactueu amb els altres a la Comunitat KDE, assegureu-vos de complir amb el Codi de conducta.

Amb les vostres noves habilitats, esteu en una bona posició per a començar a contribuir amb els projectes escrits amb el Kirigami. Afortunadament, moltes de les aplicacions i components més populars del KDE es creen amb aquest marc de treball. Aquí hi ha una llista dels projectes en els quals podreu ajudar.

Projectes escrits amb el Kirigami per a novells

Projecte	Què és això	Enllaços
Calindori	Una aplicació de calendari tàctil dissenyada per a dispositius mòbils.	Pàgina de KDE Apps Pàgina de KDE Invent
Koko	Un visualitzador d'imatges dissenyat per a l'escriptori i dispositius tàctils.	Pàgina de KDE Apps Pàgina de KDE Invent
Kontrast	És un comprovador del contrast del color i indica si les vostres combinacions de color són accessibles per a persones amb deficiències de visió del color.	Pàgina de KDE Apps Pàgina de KDE Invent
Licentia	Una aplicació per a ajudar-vos a triar la llicència que s'adigui al vostre projecte.	Pàgina de KDE Apps Pàgina de KDE Invent
Plasma Welcome	Una aplicació de benvinguda per a l'escriptori Plasma que permet crear pàgines noves amb el QML.	Pàgina de KDE Invent

Projectes més complexos escrits amb el Kirigami

Projecte	Què és això	Enllaços
Discover	Una aplicació que ajuda a trobar i instal·lar les aplicacions, jocs i eines.	Pàgina de KDE Apps Pàgina de KDE Invent
Elisa	Un reproductor de música que s'esforça a ser senzill i agradable d'emprar.	Pàgina inicial Pàgina de KDE Apps Pàgina wiki de la comunitat KDE Pàgina de KDE Invent
KDE Connect	Una aplicació multiplataforma que permet que els dispositius es comuniquin (p. ex., el telèfon i l'ordinador).	Pàgina inicial Pàgina wiki de la comunitat KDE Pàgina de KDE Invent
Kongress	Una aplicació auxiliar per als assistents a congressos.	Pàgina de KDE Invent
NeoChat	Un client per al Matrix, el protocol de comunicacions descentralitzat per a missatgeria instantània.	Pàgina de KDE Apps Pàgina de KDE Invent

Aprendre més

Encara no us sentiu preparat? Això també està bé.

Molts dels projectes llistats anteriorment són recursos d'aprenentatge de valor inestimable. Podeu consultar el codi i veure com els desenvolupadors experimentats han creat aplicacions amb totes les característiques i utilitzar vós mateix aquestes tècniques.

Si creieu que us cal un enfocament més suau, també hem recopilat alguns recursos que creiem que poden resultar-vos útils.

El dorsal i C++

Si bé hem après molt sobre QML, no hem parlat gaire sobre com gestionar el codi del dorsal. No obstant això, aquesta és una faceta essencial del desenvolupament de les aplicacions KDE.

C++/Qt amb el Kirigami

A la secció avançada d'aquesta documentació de Kirigami, tenim algunes pàgines que poden ajudar-vos a començar:

Pàgina	Tema
Entendre les CMakeLists	Aprendre-ho tot sobre CMake i com compilar les vostres aplicacions.
Descobrir el main.cpp	Comprendre el fitxer en C++ central que gestiona la inicialització de la vostra aplicació.
Connectar la lògica amb la vostra interfície d'usuari en QML	Afegir una funcionalitat avançada a la vostra aplicació en Kirigami i connecteu-la amb la IU.
Pàgina «Quant al»	Afegeix una «Pàgina quant al» a la interfície d'usuari.

Recursos de C++ per a novells

Si sou completament nou en C++, al web existeixen nombrosos recursos disponibles. A continuació, es mostren alguns que poden resultar d'utilitat.

Recurs	Tema
LearnCpp	Guies d'aprenentatge per a familiaritzar-se amb C++
cppreference	Un lloc de referència per a C++
C++ a Wikibooks	Un llibre wiki complet amb lliçons i exercicis de C++
C++ a W3Schools	Un conjunt de guies d'aprenentatge de C++ i altres recursos adreçats a principiants

També proporcionem una llista recursos actualitzats contínuament per a aprendre C++ en Aprendre'n més.

Crear aplicacions KDE clàssiques mitjançant QtWidgets

Si us agradaria treballar en les aplicacions KDE com el Dolphin, el Kontact o el Kate, us caldrà aprendre més sobre com utilitzar QtWidgets, els quals usen una forma completament diferent de desenvolupar les interfícies d'usuari amb les Qt. Les aplicacions KDE més complexes o antigues que segueixen un disseny tradicional tendeixen a construir-se amb QtWidgets.

És una mica més complicat treballar amb QtWidgets que amb el QML (i molt més intensiu en C++!). Afortunadament, tenim un conjunt de guies d'aprenentatge en el KDE Docs que us ajudaran a familiaritzar-vos amb ells.

Més QML i QtQuick

El projecte Qt és extens, com també QML i QtQuick. Hi ha moltes funcionalitats que no hem cobert, però hi ha molta documentació de la qual podem extreure per a obtenir més informació.

Si voleu cercar què fa algun component específic, no cerqueu més enllà de la documentació QML oficial de les Qt.
Si esteu cercant un enfocament d'aprenentatge més guiat, el QMLBook és un espai ideal per a començar.

Més Kirigami

Aquesta documentació inclou molt més sobre el Kirigami. Podeu fullejar algunes de les pàgines de Components per a obtenir més informació sobre alguns dels components QML que proporciona el Kirigami perquè els utilitzeu.

Us recomanem que també vegeu la Galeria del Kirigami, una aplicació dissenyada per desenvolupadors del KDE per a mostrar les eines i capacitats del Kirigami. Proporciona tant exemples interactius dels components del Kirigami, així com enllaços amb el codi font d'aquests exemples perquè pugueu veure com s'han creat.

El cel és el límit!

No us deixeu intimidar per tot aquest material! Ningú comença sent capaç de crear des de zero quelcom com el Plasma. Però KDE no és una empresa de mil milions amb una gran barrera a l'entrada (no tenim entrevistes de codificació de cinc tandes!). I mentre sigueu us porteu bé, sereu benvingut.

Bona sort!

Docs: Colors i temes creats amb el Kirigami

Mon, 01 Jan 0001 00:00:00 +0000

El Kirigami té una paleta de colors que segueix els colors del sistema, per a integrar-se millor amb la plataforma en la qual s'executa (és a dir, Escriptori Plasma, Plasma Mobile, GNOME, Android, etc.).

Tots els components QML del Kirigami i tots els components QML de Qt Quick Controls ja seguiran de manera predeterminada aquesta paleta, de manera que normalment no es necessitaran colors personalitzats per a cap d'aquests controls.

Els components primitius com Rectangle sempre s'han d'acolorir amb la paleta de colors proporcionada pel Kirigami a través de la propietat adjunta Kirigami.Theme.

En general, s'han d'evitar els colors codificats en el QML, com #32b2fa o red. Si realment és necessari tenir elements amb colors personalitzats, haurà de ser una àrea on només s'utilitzin colors personalitzats (generalment a l'àrea de contingut de l'aplicació, i mai en les àrees de cromat com les barres d'eines o els diàlegs), per exemple, un primer pla black codificat no es pot utilitzar sobre un fons Kirigami.Theme.backgroundColor, perquè si la plataforma empra un esquema de color fosc, el resultat tindrà un contrast pobre del negre sobre gairebé negre. Això és un problema d'accessibilitat i s'hauria d'evitar.

Nota

Si realment necessiteu utilitzar colors personalitzats, reviseu el Kontrast per a assegurar-vos que els colors que trieu tenen un bon contrast i que són compatibles amb el WCAG.

Tema

Kirigami.Theme és una propietat adjunta, per tant, està disponible per a utilitzar-la en qualsevol element QML. Les seves propietats inclouen tots els colors disponibles a la paleta, i quina paleta emprar, així com la propietat colorSet.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 height: 300
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Rectangle {
 anchors.centerIn: parent
 implicitHeight: 100
 implicitWidth: 200
 color: Kirigami.Theme.highlightColor
 }
 }
}

La Galeria del Kirigami proporciona un exemple de codi que mostra tots els colors disponibles per al Kirigami a través del Kirigami.Theme. Això inclou tots els seus estats: si feu clic fora de la finestra, els colors canviaran al seu estat inactiu, i si canvieu el sistema a un tema fosc, les variants fosques dels colors es mostraran en temps real.

El component Colors en la Galeria del Kirigami

Conjunt de colors

Depenent d'on s'ubiqui un control, haureu d'utilitzar un conjunt de colors diferent: per exemple, quan el tema de color Brisa clara es fa servir a les Views, el fons normal és gairebé blanc, mentre que en altres regions, com les barres d'eines o diàlegs, el color de fons normal és gris.

Si establiu un conjunt de colors per a un element, tots els seus elements fills l'heretaran de manera recursiva automàticament (llevat que la propietat inherit s'hagi establert explícitament a false, el qual sempre s'ha de fer quan el desenvolupador vol forçar un conjunt de colors específic), de manera que és fàcil canviar els colors de tots una jerarquia d'elements sense tocar cap dels elements en si.

Kirigami.Theme admet 5 conjunts diferents de colors:

View: conjunt de colors per a les vistes d'elements, generalment el més clar de tots (en els temes de colors clars)
Window: conjunt de colors per a les finestres i les àrees «cromades» (aquest és també el conjunt de colors predeterminat)
Button: conjunt de colors utilitzat pels botons
Selection: conjunt de colors utilitzat per les àrees seleccionades
Tooltip: conjunt de colors utilitzat per als consells d'eina
Complementary: conjunt de colors destinat a ser complementari a Window: generalment és fosc fins i tot en els temes clars. Pot emprar-se per a emfatitzar en les àrees petites de l'aplicació

Aquest és un exemple que mostra com s'hereten els conjunts de colors i es poden utilitzar per a distingir components diferents. S'ha afegit una vora gran als colors de contrast.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

// The comments assume the system uses the Breeze color theme

Kirigami.ApplicationWindow {
 height: 500
 width: 800

 Rectangle {
 anchors.fill: parent
 border.width: 5

 // A gray color will be used, as the default color set is Window
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the Window color set for light themes
 text: "Rectangle that uses default background color\nfrom the Window color set"
 padding: 100
 }
 Rectangle {
 anchors.bottom: parent.bottom
 border.width: 5
 width: parent.width
 height: Math.round(parent.height / 2)

 // Use the color set used for Views
 Kirigami.Theme.colorSet: Kirigami.Theme.View
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be a near-white color in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 text: "Rectangle that does not inherit the default background color\nand uses the Theme.View color set"
 padding: 50

 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.left: parent.left
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // This will be a near-white color too, as the color set
 // is inherited from the parent and will be View
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-black, as defined in the View color set for light themes
 text: "Rectangle that inherits the Theme.View color set"
 anchors.centerIn: parent
 }
 }

 Rectangle {
 anchors.bottom: parent.bottom
 anchors.right: parent.right
 border.width: 5
 width: Math.round(parent.width / 2)
 height: Math.round(parent.height / 2)

 // Use the Complementary set
 Kirigami.Theme.colorSet: Kirigami.Theme.Complementary
 // Do not inherit from the parent
 Kirigami.Theme.inherit: false
 // This will be near-black as the background color
 // of the Complementary color set is dark in light themes
 color: Kirigami.Theme.backgroundColor

 Controls.Label {
 // The text will be near-white, as defined in the Complementary color set for light themes
 text: "Rectangle that does not inherit the Theme.View\nand uses Theme.Complementary instead"
 anchors.centerIn: parent
 }
 }
 }
 }
}

Com els conjunts de colors difereixen en el Brisa

Com els conjunts de colors difereixen en el Brisa fosc

Utilitzar colors personalitzats

Tot i que es desaconsella utilitzar colors codificats, el Kirigami ofereix una forma més fàcil de mantenir per a assignar una paleta codificada personalitzada a un element i a tots els seus fills, el qual permetrà definir aquests colors personalitzats en un lloc i només en un:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Custom colors"
 height: 300
 width: 300

 Rectangle {
 anchors.fill: parent
 Kirigami.Theme.inherit: false
 // NOTA: Independentment del conjunt de colors utilitzat, es recomana substituir tots els
 // colors disponibles al tema, per a evitar un contrast dolent dels colors

 Kirigami.Theme.colorSet: Kirigami.Theme.Window
 Kirigami.Theme.backgroundColor: "#b9d795"
 Kirigami.Theme.textColor: "#465c2b"
 Kirigami.Theme.highlightColor: "#89e51c"
 // Redefiniu tots els altres colors que vulguis

 // Aquest serà «#b9d795»
 color: Kirigami.Theme.backgroundColor

 Rectangle {
 // Aquest serà «#465c2b»
 anchors.centerIn: parent
 height: Math.round(parent.height / 2)
 width: Math.round(parent.width / 2)
 color: Kirigami.Theme.textColor
 }
 }
}

Exemple amb colors personalitzats

Docs: Tipografia

Mon, 01 Jan 0001 00:00:00 +0000

Per motius demostratius, aquesta guia d'aprenentatge utilitza una AbstractCard per a fer més clars els exemples de text. Una manera millor d'aconseguir els mateixos resultats seria utilitzar un Kirigami Addons FormCard.

Capçaleres

El Kirigami proporciona un Heading que es pot utilitzar per a títols de pàgines o de seccions.

import QtQuick
import QtQuick.Layouts
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Kirigami Heading"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 anchors.fill: parent
 Kirigami.Heading {
 text: "Heading level 1"
 level: 1
 }
 Kirigami.Heading {
 text: "Heading level 2"
 level: 2
 }
 Kirigami.Heading {
 text: "Heading level 3"
 level: 3
 }
 Kirigami.Heading {
 text: "Heading level 4"
 level: 4
 }
 Kirigami.Heading {
 text: "Heading level 5"
 level: 5
 }
 }
 }
 }
}

Etiquetes

Els elements de text hauran d'emprar l'element Label de QtQuick Controls 2.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "My text"
 }
 }
 }
}

Alineació del text

Podeu alinear els elements de text utilitzant les propietats horizontalAlignment i verticalAlignment.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Horizontal Center"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignHCenter
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Horizontal Align Right"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Welcome to my application"
 wrapMode: Text.Wrap
 }
 Controls.Label {
 Layout.fillWidth: true
 horizontalAlignment: Text.AlignRight
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.Wrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Bottom and Top"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Top and Bottom"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignTop
 text: "Welcome to my application"
 wrapMode: Text.WordWrap
 }
 Controls.Label {
 Layout.fillWidth: true
 Layout.fillHeight: true
 verticalAlignment: Text.AlignBottom
 text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante."
 wrapMode: Text.WordWrap
 }
 }
 }
 }
}

Text enriquit

El QML permet mostrar (i editar) el text enriquit. El comportament es pot controlar mitjançant la propietat textFormat.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls Label with rich text"
 height: 400
 width: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.AbstractCard {
 anchors.fill: parent
 contentItem: Controls.Label {
 text: "<p><strong>List of fruits to purchase</strong></p>
 <ul>
 <li>Apple</li>
 <li>Cherry</li>
 <li>Orange</li>
 <li><del>Banana</del></li>
 </ul>
 <p>Kris already got some bananas yesterday.</p>"
 }
 }
 }
}

Tema

La mida de la lletra del Kirigami.Theme està disponible en la vostra aplicació com una Kirigami.Theme.defaultFont.pointSize.

Docs: Accions basades en els components

Mon, 01 Jan 0001 00:00:00 +0000

Accions

Una Kirigami.Action consisteix d'una acció que s'hi pot fer clic i la seva aparença depèn d'on s'ha afegit. Normalment és un botó amb una icona i text.

Podem utilitzar-les per a proporcionar a les nostres aplicacions accions d'accés fàcil que són essencials per a la seva funcionalitat.

Nota

Les accions del Kirigami hereten a partir de QtQuick.Controls.Action i es poden assignar a dreceres.

Igual que QtQuick Controls Actions, es poden assignar a elements de menú i botons de la barra d'eines, però també a molts altres components de Kirigami.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 id: copyAction
 text: i18n("Copy")
 icon.name: "edit-copy"
 shortcut: StandardKey.Copy
 onTriggered: {
 // ...
 }
}

Nota

La propietat `icon.name pren els noms per a les icones de tot el sistema seguint l'especificació de FreeDesktop. Aquestes icones i noms d'icones es poden veure amb l'aplicació CuttleFish del KDE que venen amb plasma-sdk, o visitant l'especificació per a l'anomenat de les icones de FreeDesktop.

Una característica que ofereixen les Kirigami Actions a més de les QtQuick Actions és la possibilitat d'imbricar les accions.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "action 1"
 }
 Kirigami.Action {
 text: "action 2"
 }
 Kirigami.Action {
 text: "action 3"
 }
}

Una altra característica de les Kirigami Actions és proporcionar diversos consells als elements que fan servir accions sobre com mostraran l'acció. Aquests són gestionats principalment per les propietats displayHint i displayComponent.

Si és possible, aquestes propietats seran respectades per l'element. Per exemple, l'acció següent es mostrarà com un TextField amb l'element fent tot el possible per a mantenir-se visible el temps més gran possible.

import org.kde.kirigami as Kirigami

Kirigami.Action {
 text: "Search"
 icon.name: "search"

 displayComponent: TextField { }

 displayHint: Kirigami.DisplayHints.KeepVisible
}

Utilitzar accions en altres components

Com s'ha esmentat en la guia d'aprenentatge d'introducció a les accions, les accions del Kirigami són contextuals, el qual vol dir que es mostren en llocs diferents depenent d'on les poseu. A més, també tenen representacions diferents per a escriptori o mòbil.

Pàgina

Una Kirigami.Page mostra les accions a la dreta de la capçalera superior en el mode d'escriptori i en un peu en el mode de mòbil.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 600
 height: 600

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: Kirigami.Page {
 title: "Demo"

 actions: [
 Kirigami.Action {
 icon.name: "go-home"
 onTriggered: showPassiveNotification("Main action triggered")
 },
 Kirigami.Action {
 icon.name: "go-previous"
 onTriggered: showPassiveNotification("Left action triggered")
 },
 Kirigami.Action {
 icon.name: "go-next"
 onTriggered: showPassiveNotification("Right action triggered")
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "bookmarks"
 onTriggered: showPassiveNotification("Contextual action 1 clicked")
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "folder"
 enabled: false
 }
 ]
 }
}

Accions de la pàgina a l'escriptori

Accions de la pàgina en un dispositiu mòbil

Calaix global

El Kirigami.GlobalDrawer és una barra lateral que sembla un menú que proporciona a l'aplicació una navegació basada en accions. Aquest és el lloc on les accions imbricades són útils perquè permeten crear una navegació imbricada:

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 globalDrawer: Kirigami.GlobalDrawer {
 title: "Demo"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "View"
 icon.name: "view-list-icons"
 Kirigami.Action {
 text: "View Action 1"
 onTriggered: showPassiveNotification("View Action 1 clicked")
 }
 Kirigami.Action {
 text: "View Action 2"
 onTriggered: showPassiveNotification("View Action 2 clicked")
 }
 },
 Kirigami.Action {
 text: "Action 1"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Action 2"
 onTriggered: showPassiveNotification("Action 2 clicked")
 }
 ]
 }
 //...
}

Accions del calaix global a l'escriptori

Podeu llegir més sobre els calaixos globals a la pàgina de documentació per als calaixos.

Calaix contextual

Un Kirigami.ContextDrawer consisteix en un conjunt addicional d'accions que s'oculten darrere d'un menú de tres punts a la part superior dreta en el mode d'escriptori o a la part inferior dreta en el mode de mòbil si no hi ha espai. S'utilitza per a mostrar accions que només són rellevants en una pàgina específica. Podeu llegir-ne més a la nostra guia d'aprenentatge Kirigami Drawers.

ActionTextField

S'utilitza un Kirigami.ActionTextField per a afegir algunes accions contextuals a un camp de text, per exemple, per a netejar el text o per a fer-ne la cerca.

Kirigami.ActionTextField {
 id: searchField
 rightActions: [
 Kirigami.Action {
 icon.name: "edit-clear"
 visible: searchField.text !== ""
 onTriggered: {
 searchField.text = ""
 searchField.accepted()
 }
 }
 ]
}

En aquest exemple, estem creant un botó de «neteja» per a un camp de cerca que només serà visible quan s'hi introdueix text.

Nota

Rarament hauríeu d'utilitzar un ActionTextField directament. El SearchField i el PasswordField hereten de l'ActionTextField i és probable que cobreixin el vostre cas d'ús desitjat.

SwipeListItem

Un Kirigami.SwipeListItem és un delegat destinat a permetre accions extres. Quan s'empra un ratolí, sempre es mostrarà. En un dispositiu tàctil, es podrà mostrar arrossegant l'element amb la nansa. A les imatges següents, aquests són les icones de la dreta.

ListView {
 model: myModel
 delegate: SwipeListItem {
 Controls.Label {
 text: model.text
 }
 actions: [
 Action {
 icon.name: "document-decrypt"
 onTriggered: print("Action 1 clicked")
 },
 Action {
 icon.name: model.action2Icon
 onTriggered: //fa alguna cosa
 }
 ]
 }
}

SwipeListItem en un ordinador

SwipeListItem en un dispositiu mòbil

ActionToolBar

Una Kirigami.ActionToolBar és una barra d'eines construïda a partir d'una llista d'accions. De manera predeterminada, cada acció que càpiga a la barra d'eines estarà representada per un ToolButton, i les que no càpiguen es mouran a un menú al final de la barra d'eines.

Igual que ActionTextField, és possible que no necessiteu utilitzar ActionToolBar directament, ja que l'utilitzen les capçaleres i les targetes de pàgina per a mostrar la seva acció.

import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Actions Demo"
 width: 350
 height: 350
 header: Kirigami.ActionToolBar {
 actions: [
 Kirigami.Action {
 text: i18n("View Action 1")
 onTriggered: showPassiveNotification(i18n("View Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("View Action 2")
 onTriggered: showPassiveNotification(i18n("View Action 2 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 1")
 onTriggered: showPassiveNotification(i18n("Action 1 clicked"))
 },
 Kirigami.Action {
 text: i18n("Action 2")
 onTriggered: showPassiveNotification(i18n("Action 2 clicked"))
 }
 ]
 }
}

Una barra d'eines horitzontal que es mostra a la part superior de l'aplicació

Podeu llegir més sobre els components ActionToolBar a la seva pàgina de documentació dedicada.

Targetes (Card)

Un Kirigami.Card s'utilitza per a mostrar una col·lecció d'informació o accions junts. Aquestes accions es poden afegir al grup actions, de manera similar als components anteriors.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // ...
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

Per a més informació consulteu la pàgina de components per a targetes.

Docs: Files de pàgines i piles de pàgines

Mon, 01 Jan 0001 00:00:00 +0000

Una fila de pàgines

Fins ara hem vist que un dels components principals d'una finestra del Kirigami és un Kirigami.Page. Una sola pàgina pot envoltar tota la pantalla de l'aplicació, o es pot mostrar juntament amb altres pàgines al mateix temps, si hi ha espai.

Quan s'afegeix una pàgina, o s'empeny, apareix a la dreta de les pàgines existents, formant una fila. Aquesta fila de pàgines es pot gestionar amb el que s'anomena correctament Kirigami.PageRow.

Una fila de pàgines mínima amb una pàgina única hauria de ser així:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Single Page"
 width: 500
 height: 200

 Kirigami.PageRow {
 anchors.fill: parent

 Kirigami.Page {
 id: mainPage
 anchors.fill: parent
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

Una sola pàgina amb color blau clar per a mostrar les dimensions de la pàgina

Aquí es poden fer dues millores. El primer és que, amb initialPage, podem establir que mainPage sigui la primera pàgina que aparegui a la fila de la pàgina, i que les seves dimensions siguin gestionades per la fila de la pàgina en lloc de fer-ho a través d'ancoratges, posicionadors o disposicions manuals. El segon és tenir una barra d'eines, que es pot establir definint un estil d'eines amb globalToolBar.style. Hi ha alguns estils que podem triar, però continuarem amb el Kirigami.ApplicationHeaderStyle.Auto per ara.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "With globalToolBar and initialPage"
 width: 500
 height: 200
 Kirigami.PageRow {
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 }
 }
 }
}

Una sola pàgina amb barra d'eines i color blau clar per a mostrar les dimensions de la pàgina

Només hi ha dues maneres d'afegir pàgines a una fila de pàgines: establint la seva initialPage (que opcionalment pot prendre una matriu de pàgines) o utilitzant push(). Per a suprimir una pàgina de la fila de pàgines, haureu d'utilitzar pop(), mentre que goBack() o goForward() es pot utilitzar per a navegar entre les pàgines.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Multiple pages in a row"
 width: 700
 height: 300
 Kirigami.PageRow {
 id: mainRow
 anchors.fill: parent
 globalToolBar.style: Kirigami.ApplicationHeaderStyle.Auto
 initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: mainRow.push(secondPage)
 }
 }
 }

 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: mainRow.pop()
 }
 }
 }
 }
 }
}

Pàgina inicial amb un color blau clar

En fer clic a "Push!", apareix una segona pàgina de color verd clar

La pila de pàgines de l'aplicació

Si un Kirigami.PageRow amb una barra d'eines us sembla familiar, és perquè l'heu vist abans. Una ApplicationWindow.pageStack no és més que una fila de pàgines global molt útil. Cada funció disponible per a una PageRow també està disponible per a pageStack.

L'exemple anterior es pot reduir significativament amb una pageStack, amb la bonificació afegida de les accions de navegació:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Using the pageStack"
 width: 500
 height: 200
 pageStack.initialPage: Kirigami.Page {
 id: firstPage
 Rectangle {
 anchors.fill: parent
 color: "lightblue"
 Controls.Button {
 anchors.centerIn: parent
 text: "Push!"
 onClicked: pageStack.push(secondPage)
 }
 }
 }
 Component {
 id: secondPage
 Kirigami.Page {
 Rectangle {
 anchors.fill: parent
 color: "lightgreen"
 Controls.Button {
 anchors.centerIn: parent
 text: "Pop!"
 onClicked: pageStack.pop()
 }
 }
 }
 }
}

En general, voldreu utilitzar una pageStack en lloc d'implementar la vostra PageRow, especialment quan la vostra aplicació es fa més gran i necessiteu els vostres components residint en fitxers separats. Si creeu la finestra al vostre Main.qml utilitzant un Kirigami.ApplicationWindow, un component que resideix en un altre fitxer encara pot invocar directament la pageStack global mitjançant una crida a la applicationWindow():

// "Main.qml"
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Pushing a Page from a different QML file"
 width: 700
 height: 400
 pageStack.initialPage: BasicPage {}
}

// "BasicPage.qml"
import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {
 Controls.Button {
 anchors.centerIn: parent
 text: "This pushes page1 from BasicPage\ninto the pageStack from Main.qml!"
 onClicked: {
 applicationWindow().pageStack.push(page1)
 }
 Component {
 id: page1
 Kirigami.Page {
 Controls.Label {
 anchors.centerIn: parent
 text: "page1 was pushed!"
 }
 }
 }
 }
}

En fer clic al botó s'empeny una pàgina nova amb l'ajuda d'«applicationWindow»

Docs: Pàgines desplaçables i vistes de llista

Mon, 01 Jan 0001 00:00:00 +0000

Kirigami.ScrollablePage

Una Kirigami.ScrollablePage és una pàgina que conté contingut desplaçable, com ara una vista de llista ListView. El desplaçament i els indicadors de desplaçament es gestionen automàticament.

Kirigami.ScrollablePage {
 id: root
 //El rectangle es podrà desplaçar automàticament
 Rectangle {
 width: root.width
 height: 99999
 }
}

En gairebé tots els altres aspectes, una pàgina desplaçable és el mateix que una pàgina normal.

Avís

No poseu una ScrollView dins d'una [Kirigami.ScrollablePage](docs:kirigami;org.kde.kirigami. ScrollablePage). Els fills d'una Kirigami.ScrollablePage ja estan dins d'una ScrollView.

Vista de llista en una pàgina desplaçable

Quan els fills directes d'una Kirigami.ScrollablePage s'estenen verticalment més enllà de la mida de la pàgina en si, apareixerà una barra de desplaçament a la vora dreta de la pàgina i la pàgina es podrà desplaçar.

Dues pàgines desplaçables, ambdues amb una ListView amb contingut personalitzat (captura de pantalla del NeoChat).

Sovint tindreu més d'un fill a la vostra Kirigami.ScrollablePage, i col·locar-hi els elements pot ser complicat, especialment en combinació amb una ListView.

Per als components no visuals, tenir-los dins del component ListView no canviarà la visualització de la pàgina. Llavors podem moure'ls dins de l'àmbit de la vista de llista. El mateix per als elements ancorats al centre de la pàgina, com els missatges amb marcador de posició per a les vistes de llistes buides.
Per als altres elements, podria tenir sentit moure'ls a la capçalera o al peu de pàgina de la Kirigami.ScrollablePage. Sovint, aquest és el cas de les barres de cerca.

PlaceholderMessage

És possible afegir un Kirigami.PlaceholderMessage amb algunes instruccions en cas que la vista de llista estigui buida.

Kirigami.ScrollablePage {
 ListView {
 id: listView
 Kirigami.PlaceholderMessage {
 anchors.centerIn: parent
 width: parent.width - (Kirigami.Units.largeSpacing * 4)
 visible: listView.count === 0
 text: i18n("No data found")
 helpfulAction: Kirigami.Action {
 text: i18n("Load data")
 // Més codi...
 }
 }
 model: // Codi de model...
 }
}

Cercar a la vista de llista

Sovint s'afegeix un camp de cerca a una Kirigami.ScrollablePage per a filtrar la ListView. Això es pot fer canviant el titleDelegate predeterminat per a utilitzar en el seu lloc un Kirigami.SearchField.

Kirigami.ScrollablePage {
 titleDelegate: Kirigami.SearchField {
 Layout.topMargin: Kirigami.Units.smallSpacing
 Layout.bottomMargin: Kirigami.Units.smallSpacing
 Layout.fillHeight: true
 Layout.fillWidth: true
 onTextChanged: mySortFilterModel.filterText = text
 KeyNavigation.tab: listView
 }

 ListView {
 id: listView
 // Resta del codi de la «listview»...
 }
}

Consell

Podeu utilitzar un KSortFilterProxyModel des del KItemModel per a afegir amb facilitat la capacitat de filtratge directament en el QML sense necessitat de codi en C++.

Estirar per a actualitzar

Una altra funció proporcionada per aquest component és una acció d'«estira per a actualitzar». Per a utilitzar això, activeu-lo de la manera següent:

Kirigami.ScrollablePage {
 id: view
 supportsRefreshing: true
 onRefreshingChanged: {
 if (refreshing) {
 myModel.refresh();
 }
 }
 ListView {
 // NOTA: MyModel no prové dels components, senzillament és un exemple de com es pot emprar
 // juntament amb alguna lògica de l'aplicació que quan està feta pot actualitzar el model de
 // llista i els senyals.
 model: MyModel {
 onRefreshDone: view.refreshing = false;
 }
 delegate: BasicListItem {}
 }
}

En estirar cap avall, també podreu activar un mode especial amb un marge superior més gran que facilita l'ús de l'aplicació amb una sola mà.

Docs: Targetes (Card)

Mon, 01 Jan 0001 00:00:00 +0000

Els tipus AbstractCard i Card de Kirigami s'utilitzen per a implementar el popular component de targeta utilitzat en moltes plataformes mòbils i web. Les targetes es poden utilitzar per a mostrar una col·lecció amb informació o accions d'una manera atractiva i distintiva.

El Kirigami també ofereix 3 tipus de vistes i posicionadors per a ajudar-vos a presentar les vostres targetes amb disposicions belles i sensibles.

AbstractCard

Una Kirigami.AbstractCard és el tipus de targeta més senzilla. Només és un rectangle amb una ombra, el qual podrà contenir qualsevol Item. També podrà tenir Items assignats a les seves propietats header o footer. En aquest cas, una Kirigami.Heading és la seva header i una Controls.Label és el contentItem.

Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: qsTr("AbstractCard")
 level: 2
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "..."
 }
}

Targeta (Card)

Una Kirigami.Card hereta des de AbstractCard i proporciona més característiques a punt d'emprar. Les targetes hereten la mateixa header i footer des d'una Abstract Card, però en el seu lloc us encoratgem a fer servir un banner i un conjunt de Kirigami.Action en el grup actions.

Kirigami.Card {
 actions: [
 Kirigami.Action {
 text: qsTr("Action1")
 icon.name: "add-placemark"
 },
 Kirigami.Action {
 text: qsTr("Action2")
 icon.name: "address-book-new-symbolic"
 },
 // ...
 ]
 banner {
 source: "../banner.jpg"
 title: "Title Alignment"
 // El títol es pot col·locar en el bàner
 titleAlignment: Qt.AlignLeft | Qt.AlignBottom
 }
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
}

CardsLayout

Una Kirigami.CardsLayout és més útil quan les targetes que es presenten no són instanciades per un model o són instanciades per un model que sempre té molt pocs elements. Es presentaran com una quadrícula de dues columnes que romandran centrades si l'aplicació és realment ampla, o es convertiran en una sola columna si no hi ha prou espai per a dues columnes, com en la pantalla d'un telèfon mòbil.

Nota

CardsListView és més adequat per als models més grans.

Important

Una CardsLayout sempre hauria d'estar inclosa dins d'una ColumnLayout.

De manera opcional, una targeta es pot orientar horitzontalment. En aquest cas, serà més ampla que alta i és més adequada per a col·locar-se en una ColumnLayout. Si heu de posar-la en una CardsLayout, de manera predeterminada tindrà un maximumColumns de 2.

ColumnLayout {
 Kirigami.CardsLayout {
 Kirigami.Card {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 Kirigami.AbstractCard {
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text"
 }
 }
 Kirigami.Card {
 headerOrientation: Qt.Horizontal
 contentItem: Controls.Label {
 wrapMode: Text.WordWrap
 text: "My Text2"
 }
 }
 }
}

CardsListView

Una Kirigami.CardsListView és una vista de llista que es pot utilitzar amb els components d'AbstractCard.

Una CardsListView estendrà les targetes filles a la seva pròpia amplada. Per tant, aquest component només s'ha d'utilitzar amb les targetes que es vegin bé en qualsevol mida horitzontal. Es desaconsella l'ús del component Card, llevat que tingueu Qt.Horizontal](docs:qtcore;Qt::Orientation) com la seva propietat headerOrientation.

Kirigami.CardsListView {
 id: view
 model: 100

 delegate: Kirigami.AbstractCard {
 //NOTA: No poseu mai una disposició com a contentItem, ja que provocarà bucles de vincle
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 //IMPORTANT: no posar mai el marge inferior
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: width > Kirigami.Units.gridUnit * 20 ? 4 : 2
 Kirigami.Icon {
 source: "applications-graphics"
 Layout.fillHeight: true
 Layout.maximumHeight: Kirigami.Units.iconSizes.huge
 Layout.preferredWidth: height
 }
 Kirigami.Heading {
 level: 2
 text: qsTr("Product ")+ modelData
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: qsTr("Install")
 }
 }
 }
 }
}

Docs: Calaixos (drawers)

Mon, 01 Jan 0001 00:00:00 +0000

Els calaixos són subfinestres que llisquen pels costats de la finestra de l'aplicació. Es poden completar amb elements interactius com les Kirigami Actions: botons, text i més.

Els calaixos venen en diferents tipus, formes i formularis. En aquesta pàgina repassarem cada tipus i proporcionarem un resum de les seves característiques.

Calaix global

El calaix global és una característica estàndard en les aplicacions de mòbil del KDE i, de vegades, també es pot trobar en les seves encarnacions per a l'escriptori. Conté el menú principal d'una aplicació: aquí s'inclouen totes les funcions que no són específiques de la pàgina actual, però que encara són importants per a la navegació general o la interacció dins de l'aplicació.

Es pot activar tocant el menú d'hamburguesa o lliscant des de la vora esquerra al centre de la pantalla en el mode d'esquerra a dreta o des de la vora dreta en el mode de dreta a esquerra.

Els components d'un Kirigami.GlobalDrawer són els que utilitzem per a crear aquests calaixos. S'estableixen a la propietat globalDrawer de la Kirigami.ApplicationWindow que forma la base de la nostra aplicació escrita amb el Kirigami.

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer"
 titleIcon: "applications-graphics"
 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

Nota

La propietat titleIcon pren els noms per a les icones de tot el sistema segons l'especificació de FreeDesktop. Aquestes icones i noms d'icones es poden veure amb l'aplicació CuttleFish del KDE que es distribueix amb el plasma-sdk, o visitant l'especificació per a l'anomenat de les icones de FreeDesktop.

Capçalera

Les capçaleres es poden utilitzar per a col·locar components adhesius a la part superior del vostre calaix global. Els components de la capçalera romandran en el seu lloc, fins i tot si el vostre calaix global conté accions de Kirigami imbricades que substitueixen la capa actual en el calaix global.

El component de capçalera que trieu es pot configurar amb la propietat header del calaix global, i substituirà el títol del calaix global. Això és útil per afegir un Kirigami.SearchField, per exemple:

import QtQuick
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page { /* Page code here... */ }

 globalDrawer: Kirigami.GlobalDrawer {
 title: "Global Drawer with searchfield (not visible)"

 header: Kirigami.SearchField {
 id: searchField
 }

 actions: [
 Kirigami.Action {
 text: "Kirigami Action 1"
 icon.name: "user-home-symbolic"
 onTriggered: showPassiveNotification("Action 1 clicked")
 },
 Kirigami.Action {
 text: "Kirigami Action 2"
 icon.name: "settings-configure-symbolic"
 onTriggered: showPassiveNotification("Action 2 clicked")
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }
}

El nostre calaix global ara mostra el component de la barra de cerca que hem establert com a capçalera

Adaptar-la per a l'escriptori

Si bé els calaixos globals d'estil subfinestra poden ser útils en entorns mòbils, és possible que siguin massa grans a l'escriptori, especialment quan les aplicacions tenen poques accions.

Afortunadament, els calaixos globals de Kirigami proporcionen una propietat isMenu. Quan es configura com a true, els nostres calaixos globals esdevindran menús més tradicionals només a l'escriptori.

Nota

En aquest mode de menú, les capçaleres i els bàners no seran visibles.

globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true

 actions: [
 // Aquí les accions del Kirigami...
 ]
}

Calaix global en el mode de menú, sense capçalera ni bàner

Calaixos contextuals

Mentre un Kirigami.GlobalDrawer mostra les accions globals disponibles a tota la vostra aplicació, un Kirigami.ContextDrawer s'ha d'utilitzar per a mostrar accions que només són rellevants en determinats contextos. Normalment s'utilitza en pàgines separades.

Un calaix contextual es comportarà de manera diferent depenent de si s'està utilitzant en una plataforma mòbil o en un escriptori.

En un escriptori, quan una finestra té prou espai, les accions contextuals es mostren com a part del grup actions a la barra d'eines superior. Quan l'espai és limitat, com en un dispositiu mòbil o en una finestra estreta, les accions contextuals s'oculten darrere d'un menú d'hamburguesa al costat dret. Això és diferent d'altres accions en el grup actions, concretament actions.main, actions.left i actions.right; aquestes no s'ocultaran en les finestres restringides per espais, i en el seu lloc es reduiran en les seves icones respectives.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 height: 600
 width: 1200
 minimumWidth: 500

 globalDrawer: Kirigami.GlobalDrawer {}
 contextDrawer: Kirigami.ContextDrawer {}

 pageStack.initialPage: [ emptyPage, contextDrawerPage ]

 Kirigami.Page {
 title: "Empty page"
 id: emptyPage
 }

 Kirigami.Page {
 id: contextDrawerPage
 title: "Context Drawer page"

 actions: [
 Kirigami.Action {
 icon.name: "media-record"
 },
 Kirigami.Action {
 icon.name: "arrow-left"
 },
 Kirigami.Action {
 icon.name: "arrow-right"
 },
 Kirigami.Action {
 text: "Contextual Action 1"
 icon.name: "media-playback-start"
 },
 Kirigami.Action {
 text: "Contextual Action 2"
 icon.name: "media-playback-stop"
 }
 ]
 }
}

Calaix contextual amb accions contextuals ocultes

Calaix contextual que mostra totes les accions contextuals

Al mòbil, el calaix sempre consisteix en accions ocultes darrere d'un menú d'hamburguesa. Es pot activar tocant el menú d'hamburguesa o lliscant des de la vora dreta al centre de la pantalla en el mode d'esquerra a dreta o des de la vora esquerra en el mode de dreta a esquerra.

El mateix exemple anterior, executant-se en mode de mòbil

Calaix contextual obert en mode de mòbil

Calaixos modals i inclosos

El Kirigami ofereix dos tipus addicionals de calaixos: calaixos modals i calaixos inclosos. Són força similars entre si: ambdós abasten la totalitat de l'amplada o altura de l'aplicació, i es poden col·locar a les vores de la finestra de l'aplicació. No obstant això, reaccionen de manera diferent de la interacció de l'usuari.

Els calaixos modals estan ocults de manera predeterminada i enfosqueixen la resta de l'aplicació, i es descarten quan se selecciona sobre una àrea enfosquida.
Els calaixos inclosos es mostren de manera predeterminada i permeten a l'usuari interactuar amb la resta de l'aplicació sense ser descartats i no enfosqueixen les altres àrees.

Aquesta mena de calaix és obert i flexible, però generalment, és possible que vulgueu utilitzar aquest tipus de calaix quan vulgueu que aparegui una llista petita d'opcions en una pulsació llarga o un clic dret.

Aquests dos calaixos són molt similars perquè, de fet, són el mateix component de Kirigami: Kirigami.OverlayDrawer. Propietats importants d'aquest component a tenir en compte:

Popup.modal controla si el calaix serà modal o inclòs depenent d'un valor booleà.
Drawer.edge controla en quina vora de la finestra de l'aplicació apareixerà el calaix. Les opcions per a aquesta propietat són part de l'Edge enum, això és, Qt.TopEdge, Qt.RightEdge, Qt.BottomEdge i Qt.LeftEdge.
Popup.contentItem conté el component que formarà el contingut del calaix.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Drawers App"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 title: "OverlayDrawer at the bottom"
 actions: [
 Kirigami.Action {
 text: "Open bottomDrawer"
 onTriggered: bottomDrawer.open()
 }
 ]
 Kirigami.OverlayDrawer {
 id: bottomDrawer
 edge: Qt.BottomEdge
 // Establiu «modal» a «false» per a fer que aquest calaix estigui inclòs!
 modal: true

 contentItem: RowLayout {
 Controls.Label {
 Layout.fillWidth: true
 text: "Say hello to my little drawer!"
 }
 Controls.Button {
 text: "Close"
 onClicked: bottomDrawer.close()
 }
 }
 }
 }
}

Calaix modal no visible

Calaix modal a la vora inferior de la pantalla

Docs: Chips

Mon, 01 Jan 0001 00:00:00 +0000

Els components Kirigami.Chip són elements petits heretats del AbstractButton utilitzats per a mostrar propietats comunes o filtres d'alguna cosa. Aquests són normalment elements de text, que també es pot interaccionar amb ells i venen amb un botó opcional de supressió.

Inici ràpid

Els chips es poden afegir fàcilment utilitzant el component Kirigami.Chip. En assignar una cadena al seu camp AbstractButton.text heretat, li donem el nom als chips.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Chips"

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Kirigami.Chip {
 text: "Chip 1"
 }
 Kirigami.Chip {
 text: "Chip 2"
 }
 Kirigami.Chip {
 text: "Chip 3"
 }
 }
 }
}

Amb repetidors (recomanat)

Com que els chips s'han d'utilitzar més d'una vegada, és probable que vulgueu utilitzar algun tipus d'estructura de dades de llista i iterar-los per a mostrar els chips. Per a fer-ho, necessitem un component ListModel i un component Repeater.

El ListModel s'utilitza com a emmagatzematge per als chips. Per a poblar el ListModel (i, per tant, els chips), declarem un parell de components de ListElement, que conté un camp conegut com a text. Podem utilitzar aquesta cadena assignada des d'aquí al camp text per a cada xip repetit.

El repetidor s'utilitza per a mostrar els chips. Primer, hem d'establir el camp model del Repeater al nostre ListModel, o crear el ListModel dins del repetidor. Després, declarem el component Kirigami.Chip dins del Repeater, i assigneu el seu camp text amb les dades de l'element utilitzant la propietat modelData.

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.FormLayout {
 anchors.fill: parent
 Repeater {
 Layout.fillWidth: true
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 }
 }
 }
 }
}

Nota

Podeu afegir i eliminar dinàmicament dades del ListModel, i el Repeater farà automàticament aquests canvis. No obstant això, canviant un element específic del Repeater o del ListModel no afecta l'altre, i requereix el canvi de tots dos, a menys que s'utilitzi alguna cosa com QAbstractListModel. Vegeu Aplicació d'exemple per a més informació.

Aplicació d'exemple

L'aplicació d'exemple següent mostra com es poden utilitzar els chips en programes com llistes de tasques pendents.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root
 title: "Chips"

 ListModel {
 id: chips

 ListElement { text: "Chip 1" }
 ListElement { text: "Chip 2" }
 ListElement { text: "Chip 3" }
 }

 pageStack.initialPage: Kirigami.Page {
 title: "Chips"

 Kirigami.OverlaySheet {
 id: editChipPrompt

 property var chip;
 property var index;

 header: Kirigami.Heading {
 text: "Edit Chip"
 }

 footer: DialogButtonBox {
 standardButtons: DialogButtonBox.Ok | DialogButtonBox.Cancel
 onAccepted: {
 // Both the data from the Repeater and ListModel must be
 // edited in order to update both.
 editChipPrompt.chip.text = editTextField.text;
 chips.setProperty(editChipPrompt.index, "text", editTextField.text);
 editChipPrompt.close();
 }
 onRejected: {
 editChipPrompt.close();
 }
 }

 TextField {
 id: editTextField
 }
 }

 Kirigami.FormLayout {
 anchors.fill: parent
 TextField {
 id: insertTextField
 Kirigami.FormData.label: "Item:"
 onAccepted: chips.append({ text: insertTextField.text })
 }
 // Wrapped in ColumnLayout to prevent binding loops.
 ColumnLayout {
 Layout.alignment: Qt.AlignHCenter
 Repeater {
 model: chips

 Kirigami.Chip {
 id: chip
 text: modelData
 onClicked: {
 editTextField.text = modelData;
 editChipPrompt.chip = chip;
 editChipPrompt.index = index;
 editChipPrompt.open();
 }
 onRemoved: chips.remove(index)
 }
 }
 }
 }
 }
}

Docs: Tipus de diàlegs

Mon, 01 Jan 0001 00:00:00 +0000

Un Kirigami.Dialog és un component individual que es pot utilitzar per a complementar el contingut que es mostra a una pàgina d'aplicació. Poden mostrar contingut no interactiu (només text) i contingut interactiu (formularis, vistes de llistes i botons).

Es poden descartar fent clic o tocant fora de la seva àrea o fent clic al botó de tancar a la capçalera.

Sandboxed environments

Això funciona directament per a tots els diàlegs del Kirigami en entorns d'espai aïllat (com el Flatpak) a través dels XDG Desktop Portals. Quan s'executa en un entorn d'espai aïllat, s'utilitza automàticament el dorsal apropiat del portal, cosa que permet l'accés aprovat per l'usuari sense necessitat de gestió manual del D-Bus.

Diàleg

S'utilitza un Kirigami.Dialog estàndard per a crear diàlegs personalitzats. Són molt fàcils d'ampliar:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Dialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: "Show dialog"
 onTriggered: dialog.open()
 }

 Kirigami.Dialog {
 id: dialog
 title: "A simple dialog"
 padding: Kirigami.Units.largeSpacing
 showCloseButton: false
 standardButtons: Kirigami.Dialog.NoButton
 flatFooterButtons: false
 Controls.Label {
 text: "A generic, easy to make dialog!"
 }
 customFooterActions: Kirigami.Action {
 text: "Copy"
 icon.name: "clipboard"
 }
 }
 }
}

Com es mostra en el guia d'aprenentatge d'introducció sobre els diàlegs, també és possible capturar un standardButton(button) per a assignar-li algun comportament, com una vinculació per a habilitar-lo només sota certes condicions.

Aquest tipus de diàleg és genèric i s'aplica a la majoria dels casos d'ús, i funciona bé amb contingut interactiu complex (especialment vistes):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Scrollable Dialog"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: scrollableDialog.title
 onTriggered: scrollableDialog.open()
 }

 Kirigami.Dialog {
 id: scrollableDialog
 title: i18n("Select Number")

 ListView {
 id: listView
 // consells per a les dimensions del diàleg
 implicitWidth: Kirigami.Units.gridUnit * 16
 implicitHeight: Kirigami.Units.gridUnit * 16

 model: 20
 delegate: Controls.RadioDelegate {
 topPadding: Kirigami.Units.smallSpacing * 2
 bottomPadding: Kirigami.Units.smallSpacing * 2
 implicitWidth: listView.width
 text: modelData
 }
 }
 }

 }
}

Tanmateix, en la majoria dels casos probablement voldreu utilitzar un dels seus tipus de diàleg derivats, Kirigami.PromptDialog o Kirigami.MenuDialog.

PromptDialog

Un Kirigami.PromptDialog és essencialment un diàleg amb una etiqueta integrada i el contentPadding predeterminat que s'utilitza per a demanar a l'usuari alguna informació. Se suposa que aquest tipus de diàleg només s'utilitzarà per a indicadors ssenzills sí/no o sol·licituds breus d'entrada de l'usuari.

La seva propietat principal és Kirigami.Dialog.subtitle, al qual afegireu text. Si s'afegeix qualsevol component QML com a fill del diàleg de l'indicador, aquest component ocuparà el lloc del subtítol.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: promptDialog.title
 onTriggered: promptDialog.open()
 }

 Kirigami.PromptDialog {
 id: promptDialog
 title: i18n("Delete file")
 subtitle: i18n("Are you sure you'd like to delete this file?")

 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: console.info("File deleted")
 }
 }
}

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "PromptDialog with a textfield"
 width: 600
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: textPromptDialog.title
 onTriggered: textPromptDialog.open()
 }

 Kirigami.PromptDialog {
 id: textPromptDialog
 title: "New Folder"

 standardButtons: Kirigami.Dialog.NoButton
 customFooterActions: [
 Kirigami.Action {
 text: "Create Folder"
 icon.name: "dialog-ok"
 onTriggered: {
 showPassiveNotification("Created");
 textPromptDialog.close();
 }
 },
 Kirigami.Action {
 text: "Cancel"
 icon.name: "dialog-cancel"
 onTriggered: {
 textPromptDialog.close();
 }
 }
 ]
 ColumnLayout {
 Controls.TextField {
 Layout.fillWidth: true
 placeholderText: "Folder name…"
 }
 }
 }
 }
}

MenuDialog

El Kirigami.MenuDialog és un diàleg especialitzat que s'utilitza per a llistar una selecció d'opcions clicables per a l'usuari utilitzant la seva propietat actions.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "MenuDialog"
 width: 400
 height: 600
 pageStack.initialPage: Kirigami.Page {
 id: page
 actions: Kirigami.Action {
 icon.name: "list-add"
 text: menuDialog.title
 onTriggered: menuDialog.open()
 }

 Kirigami.MenuDialog {
 id: menuDialog
 title: i18n("Track options")
 showCloseButton: false

 actions: [
 Kirigami.Action {
 icon.name: "media-playback-start"
 text: i18n("Play")
 tooltip: i18n("Start playback of the selected track")
 },
 Kirigami.Action {
 enabled: false
 icon.name: "document-open-folder"
 text: i18n("Show in folder")
 tooltip: i18n("Show the file for this song in the file manager")
 },
 Kirigami.Action {
 icon.name: "documentinfo"
 text: i18n("View details")
 tooltip: i18n("Show track metadata")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Play next")
 tooltip: i18n("Add the track to the queue, right after the current track")
 },
 Kirigami.Action {
 icon.name: "list-add"
 text: i18n("Add to queue")
 tooltip: i18n("Enqueue current track")
 }
 ]
 }
 }
}

Docs: Controls i elements interactius

Mon, 01 Jan 0001 00:00:00 +0000

El Kirigami fa ús d'una àmplia selecció de diferents elements interactius de les Qt que podeu utilitzar en les aplicacions. Cada tipus diferent té estils d'interacció, estils visuals i funcionalitats lleugerament diferents. Emprant el tipus de control correcte a la vostra aplicació ajudareu a fer que la interfície d'usuari sigui més sensible i intuïtiva.

Botons

En les aplicacions Kirigami, utilitzem el Button dels QtQuick Controls. Emprar-los és força senzill: establim la propietat text i qualsevol acció que volem que realitzi s'estableix a la propietat onClicked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Beep!"
 onClicked: showPassiveNotification("Boop!")
 }
 }
 }
}

Botons commutables

El comportament dels botons es pot canviar perquè es puguin commutar: en aquest mode, romandran premuts fins que s'hi faci clic una vegada més. Aquest mode es pot activar establint la propietat checkable a true. També podem establir els botons perquè es commutin de manera predeterminada establint la propietat [checked](https://doc.qt.io/qt-6 /qml-qtquick-controls2-abstractbutton.html#checked-prop) a true.

Podem aprofitar al màxim els botons commutables utilitzant el controlador de la propietat onCheckedChanged que es genera automàticament a partir del senyal checked. Funciona de manera similar a onClicked, excepte que aquí l'acció assignada s'executarà quan es canviï l'estat del botó. És una propietat booleana, el qual pot ser útil per a casos específics d'ús.

En aquest exemple, establim la visibilitat d'un calaix inclòs d'acord amb l'estat d'un botó commutable:

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Button (toggleable version)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Button {
 Layout.alignment: Qt.AlignCenter
 text: "Hide inline drawer"
 checkable: true
 checked: true
 onCheckedChanged: myDrawer.visible = checked
 }

 Kirigami.OverlayDrawer {
 id: myDrawer
 edge: Qt.BottomEdge
 modal: false

 contentItem: Controls.Label {
 text: "Peekaboo!"
 }
 }
 }
 }
}

Nota

Amb el tema Brisa predeterminat en el Plasma del KDE, pot ser difícil saber si un botó està commutat, ja que els botons seran de color blau quan es fa clic a sobre seu. Assegureu-vos de tenir això en compte quan creeu la vostra aplicació: un control diferent podria ser més fàcil d'utilitzar.

Botons de la barra d'eines

Hi ha un tipus de botó específic per al seu ús en les barres d'eines, Controls.ToolButton. La diferència més òbvia entre aquest i un botó Button convencional és l'estil, amb botons d'eina plans (encara que això es pot alterar amb la propietat booleana flat).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.ToolButton"
 width: 600
 height: 600

 header: Controls.ToolBar {
 RowLayout {
 anchors.fill: parent
 Controls.ToolButton {
 icon.name: "application-menu-symbolic"
 onClicked: showPassiveNotification("Kirigami Pages and Actions are better!")
 }
 Controls.Label {
 text: "Global ToolBar"
 horizontalAlignment: Qt.AlignHCenter
 verticalAlignment: Qt.AlignVCenter
 Layout.fillWidth: true
 }
 Controls.ToolButton {
 text: "Beep!"
 onClicked: showPassiveNotification("ToolButton boop!")
 }
 }
 }
}

Controls de la selecció

Els controls de selecció permeten als usuaris escollir o triar una opció. Hi ha tipus diferents que s'adapten millor a diferents situacions.

Caselles de selecció

Un Controls.CheckBox està destinat a opcions en què les opcions no són exclusives i en què cada opció té una alternativa clara.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.CheckBox"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is checked!"
 checked: true
 }
 Controls.CheckBox {
 Layout.alignment: Qt.AlignHCenter
 text: "This checkbox is not checked!"
 checked: false
 }
 }
 }
}

Com podeu veure, són fàcils d'utilitzar. La propietat checked manté un valor booleà que determina si s'ha marcat o no.

Botons d'opció

Un Controls.RadioButton està dissenyat per a situacions en què l'usuari ha de triar una opció d'entre un conjunt d'opcions diverses.

De manera predeterminada, els botons d'opció són exclusius: només en el mateix element pare només se'n pot marcar un.

Igual que les caselles de selecció, es poden establir perquè estiguin marcats o desmarcats de manera predeterminada amb la propietat checked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RadioButton"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {

 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tick!"
 checked: true
 }
 Controls.RadioButton {
 Layout.alignment: Qt.AlignCenter
 text: "Tock!"
 checked: false
 }
 }
 }
}

Commutadors (Switches)

A l'escriptori, canviar les opcions de configuració generalment implica canviar la configuració i després aplicar-la fent clic a un botó «Aplica» o «D'acord». Al mòbil, en el seu lloc podem utilitzar un Controls.Switch.

Els commutadors es poden alternar entre un estat activat i desactivat. Es poden alternar fent-hi clic o tocar-los, o es poden arrossegar cap a la posició activada o desactivada. Un cop més, els commutadors es poden establir perquè estiguin activats o desactivats de manera predeterminada amb la propietat checked.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Switch"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Switchy"
 checked: true
 }
 Controls.Switch {
 Layout.alignment: Qt.AlignCenter
 text: "Swootchy"
 checked: false
 }
 }
 }
}

Controls lliscants

Els controls lliscants permeten als usuaris seleccionar certs valors fent lliscar un control al llarg d'una pista. Hi ha diversos tipus entre els quals podreu triar segons els valors que us agradaria que triessin els usuaris a la vostra aplicació.

Controls lliscants estàndard i amb marques

Un Controls.Slider estàndard proporciona a l'usuari un control molt precís sobre la selecció que voleu realitzar.

En el mode d'esquerra a dreta, els controls lliscants van d'esquerra a dreta per a augmentar en l'orientació horitzontal, mentre que en el mode de dreta a esquerra van en la direcció inversa. En ambdós modes, els controls lliscants en orientació vertical van des de baix cap a dalt.

La coloració proporciona un indicador visual de com és de gran el valor que s'està seleccionant.

Els controls lliscants tenen algunes propietats importants a les quals hem de parar atenció:

value: conté el valor en el qual es col·loca la nansa i també es pot establir manualment per a proporcionar un valor inicial predeterminat
to: defineix l'interval del control lliscant, especificant el valor màxim fins al qual pot anar
orientation: permet que el control lliscant s'estableixi en una orientació vertical amb Qt.Vertical

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: normalSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillHeight: true
 orientation: Qt.Vertical
 value: 60
 to: 100
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: Math.round(normalSlider.value)
 }
 }
 }
}

Una altra propietat útil que podem utilitzar és stepSize. Establir-la en un valor numèric ens permet crear un control lliscant que s'ajusta als valors que són múltiples de la stepSize especificada, amb aquests múltiples indicats per marques d'escala. Per tant, si establim aquesta propietat a 2.0, quan l'usuari arrossega el control lliscant, només podrà seleccionar 0.0, 2.0, 4.0, etc. fins al valor especificat a la propietat to.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.Slider (with steps)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.Slider {
 id: tickmarkedSlider
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 orientation: Qt.Horizontal
 snapMode: Controls.Slider.SnapAlways
 value: 6.0
 to: 10.0
 stepSize: 2.0
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 text: tickmarkedSlider.value
 }
 }
 }
}

Controls lliscants amb intervals

Els QtQuick Controls també proporcionen Controls.RangeSliders. Aquests tenen dues nanses, i això permet definir un interval de nombres entre les dues nanses.

És important tenir en compte dues propietats noves: `first.value i second.value, les quals mantenen els valors de les dues nanses. Igual que la propietat value dels controls lliscants estàndard, aquests es poden preestablir.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Controls.RangeSlider"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.fill: parent
 Controls.RangeSlider {
 id: rangeSlider
 Layout.alignment: Qt.AlignHCenter
 to: 10.0
 first.value: 2.0
 second.value: 8.0
 stepSize: 1.0
 snapMode: Controls.Slider.SnapAlways
 }
 RowLayout {
 Layout.alignment: Qt.AlignHCenter
 Layout.fillWidth: true
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's first value is: " + Math.round(rangeSlider.first.value)
 }
 Controls.Label {
 Layout.fillWidth: true
 text: "The slider's second value is: " + Math.round(rangeSlider.second.value)
 }
 }
 Controls.Label {
 Layout.alignment: Qt.AlignHCenter
 font.bold: true
 text: "Is the selected range between 2 and 8?"
 }
 Controls.Button {
 Layout.alignment: Qt.AlignHCenter
 icon.name: {
 if (rangeSlider.first.value >= 2 && rangeSlider.second.value <= 8)
 return "emblem-checked"
 else
 return "emblem-error"
 }
 }
 }
 }
}

Docs: Disposicions de formulari

Mon, 01 Jan 0001 00:00:00 +0000

Els components de Kirigami.FormLayout faciliten la creació de formularis que s'ajustin a les Directrius d'interfície humana de KDE. Són òptims per als diàlegs de configuració i per a grans grups de controls i camps d'entrada que estan relacionats entre si.

Quan se'ls proporciona prou espai, les disposicions de formulari ocuparan dues columnes. La columna de l'esquerra estarà ocupada per les etiquetes proporcionades pels components fills del formulari, mentre que la dreta estarà ocupada pels components fills mateixos. En les finestres amb un espai més limitat (o en dispositius mòbils), els formularis consistiran en una sola columna vertical amb les etiquetes dels components fills col·locades a sobre dels seus respectius components.

Formulari senzill

Els components de Kirigami.FormLayout són similars en ús als components QtQuick Layout com ColumnLayout o RowLayout. Els components fills s'organitzaran automàticament d'acord amb la mida disponible per a la disposició del formulari.

Els fills d'una Kirigami.FormLayout tenen una propietat anomenada Kirigami.FormData.label. Aquesta propietat permet establir l'etiqueta que es proporcionarà per al component fill en qüestió.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 pageStack.initialPage: Kirigami.Page {

 Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 }
 }
}

Una disposició de formulari senzilla en mode escriptori

Seccions i separadors

Les FormLayout també es poden dividir en seccions. Establir on comença una secció és tan fàcil com establir la Kirigami.FormData.isSection d'un component fill a «true». Això proporcionarà al component un marge addicional a la part superior per a demarcar el començament de la secció nova.

Els components de Kirigami.Separator són els més adequats per a començar seccions noves. Els separadors s'usen per a dibuixar una prima línia horitzontal, delimitant el final d'una secció. Si preferiu no traçar dita línia entre les seccions, podeu utilitzar una propietat Item de QML estàndard. De manera alternativa, podeu utilitzar la propietat Kirigami.FormData.isSection en qualsevol altre component.

Tanmateix, això no està recomanat. Als components on Kirigami.FormData.isSection està establert a true, el text de l'etiqueta proporcionat per la propietat Kirigami.FormData.label d'aquest component es mostrarà com a text de capçalera de la secció.

Avís

Això no s'aplica a cada component, d'aquí la recomanació que utilitzeu els components Kirigami.Separator o Item en llocs on voleu utilitzar un text de capçalera.

Aquest text de capçalera és més gran que el text d'etiqueta normal, i proporciona als usuaris una pista visual agradable de què tracta la secció de disseny de formulari.

Kirigami.FormLayout {
 anchors.fill: parent

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
 Kirigami.Separator {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "New Section!"
 }
 ColumnLayout {
 Kirigami.FormData.label: "Radio buttons"
 Controls.RadioButton {
 text: "Radio 1"
 checked: true
 }
 Controls.RadioButton {
 text: "Radio 2"
 }
 Controls.RadioButton {
 text: "Radio 3"
 }
 }
 Item {
 Kirigami.FormData.isSection: true
 Kirigami.FormData.label: "Another Section! (lineless though)"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 4:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 5:"
 }
}

Una disposició de formulari amb seccions

Forçar una disposició d'escriptori o mòbil

Si preferiu que la disposició del formulari sigui coherent independentment de l'entorn on es trobi la vostra aplicació, podeu emprar la propietat wideMode del component Kirigami.FormLayout:

Quan s'estableix a true, la disposició del formulari s'estructurarà en una disposició de pantalla ampla optimitzada per a l'escriptori (doble columna).
Quan s'estableix a false, la disposició del formulari s'estructurarà en una disposició per a un dispositiu mòbil (una sola columna).

Kirigami.FormLayout {
 anchors.fill: parent
 wideMode: false

 Controls.TextField {
 Kirigami.FormData.label: "TextField 1:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 2:"
 }
 Controls.TextField {
 Kirigami.FormData.label: "TextField 3:"
 }
}

Una disposició de formulari amb la disposició de mòbil forçada

Alineació de les etiquetes

Hi ha instàncies en què voleu assignar una etiqueta als components que tenen més d'una línia o a una llista de components. Això es pot aconseguir posant el Kirigami.FormData.label a la ColumnLayout, tal com es pot veure a Seccions i separadors. Per defecte, l'etiqueta es col·loca al centre vertical de la disposició, la qual cosa no sempre és desitjable. Podem canviar això amb l'ajuda del Kirigami.FormData.labelAlignment.

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: Qt.AlignTop

 Controls.Label {
 text: "This is some rather long text \nthat should elide to multiple lines \nto show how the label gets aligned."
 elide: Text.elideLeft
 }
 }
}

Una disposició de formulari amb una etiqueta alineada a dalt

Establir l'alineació de l'etiqueta és especialment pràctic per a gestionar els components o llistes de components la mida dels quals no coneixeu prèviament. L'Elisa és un bon exemple d'això:

L'etiqueta Comment només està alineada a dalt quan el seu component corresponent té més d'una línia

Podem fer quelcom similar a això amb un operador JavaScript ternari:

Kirigami.FormLayout {
 anchors.fill: parent

 ColumnLayout {
 Kirigami.FormData.label: "This is a label:"
 Kirigami.FormData.labelAlignment: labelText.text.lineCount > 1 ? Qt.AlignTop : Qt.AlignVCenter

 Controls.Label {
 id: labelText
 text: "This is some rather long text \nthat should elide to a new line \nso it appears below the Form Label."
 elide: Text.elideLeft
 }
 }
}

Docs: Missatges inclosos

Mon, 01 Jan 0001 00:00:00 +0000

Els missatges inclosos proporcionen una forma immediata de notificar als usuaris sobre alguna cosa que ha succeït mentre utilitzaven l'aplicació.

Missatge bàsic inclòs

Els components de Kirigami.InlineMessage tenen dues propietats importants a tenir en compte:

visible: de manera predeterminada s'estableix a «false», de manera que el missatge només apareixerà quan ho vulgueu explícitament. Això es pot anul·lar si ho voleu establint-la a «true». Quan un missatge inclòs ocult està establert per a ser visible, s'obtindrà una animació bonica.
text: aquí és on establireu el text del missatge inclòs.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Page {

 ColumnLayout {
 Kirigami.InlineMessage {
 id: inlineMessage
 Layout.fillWidth: true
 text: "Hello! I am a siiiiiiimple lil' inline message!"
 }

 Controls.Button {
 text: "Show inline message!"
 onClicked: inlineMessage.visible = !inlineMessage.visible
 }
 }
}

Tipus diferents

Els missatges inclosos estàndard són com els anteriors: tenen un fons blau i una icona predeterminada. Podem canviar-ho amb la propietat type, la qual ens permet establir el nostre missatge inclòs a un tipus diferent. Hi ha quatre tipus entre els quals podem triar:

Informació (Kirigami.MessageType.Information): el predeterminat. Té un fons blau, una icona i i s'utilitza per a anunciar un resultat o dir-li a l'usuari alguna cosa general. No cal establir-lo manualment.
Positiu (Kirigami.MessageType.Positive): té un fons verd, icona de marca i indica que alguna cosa ha sortit bé.
Avís (Kirigami.MessageType.Warning): té un fons taronja, una icona de signe d'exclamació i es pot utilitzar per a avisar a l'usuari sobre alguna cosa que ha de tenir en compte.
Error (Kirigami.MessageType.Error): té un fons vermell, una icona de creu i es pot utilitzar per a dir-li a l'usuari que alguna cosa ha sortit malament.

ColumnLayout {

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hello! Let me tell you something interesting!"
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hey! Let me tell you something positive!"
 type: Kirigami.MessageType.Positive
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Hmm... You should keep this in mind!"
 type: Kirigami.MessageType.Warning
 visible: true
 }

 Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Argh!!! Something went wrong!!"
 type: Kirigami.MessageType.Error
 visible: true
 }

}

Personalitzar el text i les icones

Els missatges inclosos admeten text enriquit, el qual es pot definir amb un marcatge senzill similar a HTML. Això permet afegir algun format al text del missatge inclòs o fins i tot incloure un enllaç web extern si ho voleu.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 // Cal tenir en compte que, quan utilitzeu cometes en una cadena, les haureu d'escapar.
 text: "Check out <a href=\"https://kde.org\">KDE's website!<a/>"
 onLinkActivated: Qt.openUrlExternally(link)
 visible: true
}

També podreu personalitzar la icona que apareix a la part superior esquerra del missatge, proporcionant un nom d'icona de sistema per a la propietat icon.source. Aquests noms d'icona s'han de correspondre amb les icones que hi ha al vostre sistema. Podeu utilitzar una aplicació com Cuttlefish proporcionada per plasma-sdk per a explorar i cercar les icones disponibles en el sistema, i quins són els seus noms.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Look at me! I look SPECIAL!"
 icon.source: "actor"
 visible: true
}

Utilitzar accions en els missatges inclosos

Si els missatges han de ser interactius, podreu adjuntar accions de Kirigami als missatges inclosos. Igual que amb les pàgines, podreu fer això establint la propietat InlineMessage.actions del missatge inclòs ja sigui en una Kirigami.Action o en una matriu que contingui els components d'una Kirigami.Action.

ColumnLayout {

 Kirigami.InlineMessage {
 id: actionsMessage
 Layout.fillWidth: true
 visible: true

 readonly property string initialText: "Something is hiding around here..."
 text: initialText

 actions: [
 Kirigami.Action {
 enabled: actionsMessage.text == actionsMessage.initialText
 text: qsTr("Add text")
 icon.name: "list-add"
 onTriggered: {
 actionsMessage.text = actionsMessage.initialText + " Peekaboo!";
 }
 },
 Kirigami.Action {
 enabled: actionsMessage.text != actionsMessage.initialText
 text: qsTr("Reset text")
 icon.name: "list-remove"
 onTriggered: actionsMessage.text = actionsMessage.initialText
 }
 ]
 }
}

Botons de tancar

Els missatges inclosos proporcionen un botó de tancament que es pot utilitzar per a descartar-los amb facilitat.

De manera predeterminada, aquest botó de tancament estarà ocult, però ho podeu anul·lar establint la propietat showCloseButton a true.

Kirigami.InlineMessage {
 Layout.fillWidth: true
 text: "Please don't dismiss me..."
 showCloseButton: true
 visible: true
}

Docs: Barres d'eines d'acció

Mon, 01 Jan 0001 00:00:00 +0000

Si bé les pàgines de Kirigami permeten posar amb facilitat un conjunt d'accions a la capçalera de la pàgina, hi ha ocasions en què potser preferireu tenir una mica més de flexibilitat.

El Kirigami proporciona el component Kirigami.ActionToolBar. Mostra una llista d'objectes Kirigami.Action i en mostrarà tants com sigui possible, proporcionant un menú desbordat per als que no encaixin. L'ActionToolBar és dinàmica i mourà les accions dins i fora del menú desbordat depenent de l'espai disponible.

Nota

Aquesta pàgina assumeix que esteu familiaritzat amb els objectes Kirigami.Action. Si no ho esteu, podeu aprendre-ho tot a la nostra guia d'aprenentatge inicial o a la pàgina de documentació dedicada a ells.

Crear la nostra primera ActionToolBar

La disposició i la ubicació de la vostra Kirigami.ActionToolBar en realitat dependrà de vosaltres, encara que en nom de la facilitat d'ús, generalment és una bona idea cenyir-se a les convencions de la interfície d'usuari i col·locar la barra d'eines a prop de la part superior o inferior de la pàgina i que s'estengui en amplada.

Com la majoria dels altres components que mantenen accions, la Kirigami.ActionToolBar té una propietat accions. Podem assignar una matriu de components Kirigami.Action a aquesta propietat.

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Kirigami.ActionToolBar {
 anchors.left: parent.left
 anchors.right: parent.right

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 },
 Kirigami.Action {
 text: "Action Menu"
 icon.name: "overflow-menu"

 Kirigami.Action {
 text: "Deet";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DEET!")
 }
 Kirigami.Action {
 text: "Doot";
 icon.name: "notifications"
 onTriggered: showPassiveNotification("DOOT!")
 }
 },
 Kirigami.Action {
 icon.name: "search"
 displayComponent: Kirigami.SearchField { }
 }
 ]
 }
 }
}

ActionToolBar amb prou espai per a tots els fills

ActionToolBar amb el menú desbordat que conté els fills

Alineació

De manera predeterminada, les accions a la Kirigami.ActionToolBar s'alinearan a l'esquerra. Això pot no ser desitjable en totes les situacions. Afortunadament, podem canviar això amb la propietat alignment. Podem establir aquesta propietat en un interval de valors, però els tres més rellevants són Qt.AlignLeft, Qt.AlignCenter i Qt.AlignRight (els quals s'ocupen de l'alineació horitzontal).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 id: root

 title: "ActionToolBar App"
 width: 600
 height: 400

 pageStack.initialPage: Kirigami.Page {
 Controls.GroupBox {
 anchors.left: parent.left
 anchors.right: parent.right

 Kirigami.ActionToolBar {
 anchors.fill: parent

 alignment: Qt.AlignCenter

 actions: [
 Kirigami.Action {
 text: "Beep"
 icon.name: "notifications"
 onTriggered: showPassiveNotification("BEEP!")
 }
 ]
 }
 }
 }
}

Docs: Barres de progrés i indicadors

Mon, 01 Jan 0001 00:00:00 +0000

Sempre que l'aplicació faci alguna cosa que requereixi una quantitat considerable de temps, voldreu utilitzar un element visual que digui a l'usuari que en segon pla està succeint alguna cosa.

Els QtQuick Controls proporcionen dos components útils que podreu utilitzar per a aquesta finalitat.

Barra de progrés

Controls.ProgressBar és un component que permet incloure amb facilitat barres de progrés en la vostra aplicació. Hi ha quatre propietats principals que haureu d'utilitzar:

from: el valor mínim representat pel començament de la barra de progrés
to: el valor màxim representat pel final de la barra de progrés
value: el valor actual de l'acció que està en curs (p. ex., 50% carregat)
indeterminate: si l'acció que està en procés actualment no té un valor de progrés clar, podreu establir aquesta propietat a true per a mostrar a l'usuari que està succeint alguna cosa, però el seu progrés encara no està clar (però que ho estarà aviat).

import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 value: 50
 indeterminate: false
 }
 Controls.ProgressBar {
 Layout.fillWidth: true
 from: 0
 to: 100
 // value: 50
 indeterminate: true
 }
 }
 }
}

A dalt: barra de progrés al 50%. A baix: barra de progrés indeterminat

Indicador d'ocupat

En els casos en què els temps de càrrega són més curts o el mesurament del progrés no és factible, podreu utilitzar el Controls.BusyIndicator. Aquest component proporciona una roda giratòria senzilla que mostra als usuaris que està succeint alguna cosa.

Si voleu que l'indicador deixi d'executar-se, podreu fer-ho establint la propietat running a false.

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Progressbar App"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.Page {
 actions: [
 Kirigami.Action {
 text: "Toggle busy indicator"
 onTriggered: indicator.running ? indicator.running = false : indicator.running = true
 }
 ]
 Controls.BusyIndicator {
 id: indicator
 anchors.centerIn: parent
 }
 }
}

Docs: Vistes de llista

Mon, 01 Jan 0001 00:00:00 +0000

Les List views poden ajudar a mostrar objectes d'un model d'una manera atractiva. Per a utilitzar una vista de llista, haureu de realitzar un seguiment de tres coses:

El model, el qual conté les dades que voleu mostrar a la vista de llista.
El delegat, el qual defineix com es mostrarà cada element en el model.
La vista de llista en si, la qual mostrarà la informació del model segons el delegat.

Per a més aclariments, la documentació de les Qt té una pàgina informativa sobre el tema.

Essencials de models i vistes

Una vista de llista té dues propietats essencials a les quals hem de parar atenció:

model, el qual accepta les dades o l'id de l'objecte que conté les dades
delegate, el qual accepta el component que utilitzarem per a mostrar les dades en el model

El model no és visible, ja que només conté dades. Normalment, el delegat s'embolcallarà en un Component perquè sigui reutilitzable: serveix com a esquema per a conèixer com instanciar cada delegat.

Aquí hi ha un exemple que conté exactament una vista de llista, un model i un delegat, utilitzant un Kirigami.SubtitleDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

I el mateix exemple, en línia:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (inline)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 delegate: Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

Entendre els models

El model conté les dades que s'utilitzaran per a emplenar la vista de llista. Les maneres diferents d'utilitzar els models tenen maneres diferents d'accedir a les dades:

MANERA D'UTILITZAR	COM ACCEDIR-HI	QUAN EMPRAR-HO
Models Qt amb més d'un rol	model.index, model.somerole	En la majoria dels casos
Models Qt amb un rol	model.index, model.somerole, model.modelData	En la majoria dels casos, per a fer prototips
Model de matriu JavaScript	model.index, model.modelData	Per a fer prototips
Model enter	model.index, model.modelData	Per a fer prototips

Podeu llegir sobre altres maneres d'usar els models a la documentació de les Qt.

A la taula anterior, els «models Qt» es refereixen tant a models específics de C++ com QAbstractListModel i a models específics de QML com ListModel. Aquesta pàgina de la guia d'aprenentatge només se centrarà en models específics de QML. Més endavant, proporcionem una guia d'aprenentatge per a Connectar models C++ a QML utilitzant QAbstractListModel.

La propietat model.index es posa a disposició de cada model i conté l'índex (la posició) de cada delegat. Es pot escurçar a index per comoditat.

La propietat model.somerole esmentada anteriorment és només una variable de substitució, no és una propietat específica que prové del QML: somerole pot ser qualsevol rol que estigui definit pel model. En el primer exemple de codi d'aquesta pàgina que es mostra a sobre de la taula, el model plasmaProductsModel té els rols product i target, als quals es pot accedir amb model.product i model.target, respectivament.

De la mateixa manera que model.index es pot escurçar a index, cada propietat model.somerole es pot escurçar a només somerole (com product) per comoditat, però es recomana que es converteixin en propietats requerides:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products (shortened with required properties)"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string product
 required property string target
 required property int index
 text: `${product} is KDE software developed for ${target} stored at index ${index} of this list`
 }
 }
 }
}

A més, si el model conté només un rol o no té cap rol, també es pot accedir a les seves dades amb la propietat model.modelData, que també es pot escurçar a modelData (i com a tal també necessitaria ser una propietat requerida):

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami


Kirigami.ApplicationWindow {
 title: "List of KDE software"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: kdeSoftwareModel
 delegate: listDelegate
 }
 ListModel {
 id: kdeSoftwareModel
 ListElement { software: "Dolphin" }
 ListElement { software: "Discover" }
 ListElement { software: "KHelpCenter" }
 ListElement { software: "KCalc" }
 ListElement { software: "Ark" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData // Aquest coincideix amb model.software
 }
 }
 }
}

Com a comparació, aquí és com es veuria el codi anterior amb una matriu JavaScript, sense rol:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of KDE software (as JS array)"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: ["Dolphin", "Discover", "KHelpCenter", "KCalc", "Ark"]
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: modelData
 }
 }
 }
}

L'ús d'un enter per al model pot ser útil per a casos molt específics, com el prototipatge i les proves:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "Simple list of indexes"
 width: 400
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 anchors.fill: parent
 model: 30
 delegate: listDelegate
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 required property string modelData
 text: `This delegate's index is: ${modelData}`
 }
 }
 }
}

Entendre les vistes i els delegats

Tornem a l'exemple original:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target} stored at index ${model.index} of this list`
 }
 }
 }
}

A diferència del model (que només conté dades) i d'un delegat Component (que només apareixen quan s'instancien), la vista és un component visual instanciat immediatament i, per tant, necessita tenir les seves dimensions establertes o utilitzar ancoratges o disposicions.

Com que les vistes són normalment llistes de contingut per les quals l'usuari es desplaçarà, quan s'afegeixen a un Kirigami.ScrollablePage, les vistes es converteixen en el contingut principal amb poc farciment al voltant d'elles, i no hi ha cap necessitat de fer que ompli la pàgina. Quan la vista s'afegeix a una única Kirigami.Page, necessitarà establir les seves dimensions correctament abans que aparegui. En altres paraules: a la pàgina desplaçable de dalt, no es requereix anchors.fill: parent; si s'utilitzés una única pàgina, seria necessària.

Hi ha diverses API de vistes que es poden utilitzar, algunes de les Qt i altres de Kirigami. A continuació us detallem les més utilitzades:

ListView de les Qt
GridView de les Qt
TableView de les Qt
TreeView de les Qt
CardsListView del Kirigami
ColumnView del Kirigami

D'altra banda, el delegat sempre ha de tenir les seves dimensions establertes. Generalment, les seves dimensions s'estableixen per a utilitzar només l'amplada completa de la vista.

Errors habituals

L'anterior significa que els delegats no haurien de tenir àncores inferiors, ja que el delegat no necessita tenir la mateixa altura que la vista. En altres paraules, probablement mai voldreu utilitzar anchors.fill: parent.

A més, encara que és possible establir les seves dimensions utilitzant el pare i les àncores, que normalment és el «contentItem» de la vista, així:

Controls.ItemDelegate {
 anchors.left: parent.left
 anchors.right: parent.right
 text: // ...
}

No està garantit que el pare del delegat sigui una vista, per tant, això ha d'evitar-se. En lloc d'això, utilitzeu la propietat adjunta ListView.view per a apuntar a la vista pare del delegat:

Controls.ItemDelegate {
 width: ListView.view.width
 text: // ...
}

L'ús més comú d'un delegat es troba dins d'un Component, que no instancia el delegat immediatament. Quan es construeix una vista, el delegat s'utilitza com a esquema per a fer cada element a la vista.

Tot i que podeu crear els vostres propis components personalitzats per a ser utilitzats com a delegats sense les API de les Qt específiques de delegats (per exemple, una disposició que conté alguns elements), els QtQuick Controls proporcionen les API de delegats que són més senzilles d'utilitzar:

ItemDelegate (delegats amb només text)
CheckDelegate (delegats amb una casella de selecció)
RadioDelegate (delegats amb una opció)
SwitchDelegate (delegats amb un commutador)
SwipeDelegate (delegats que es poden lliscar)

Hauríeu de preferir utilitzar els delegats originals de les Qt quan sigui possible.

A sobre d'aquests delegats de les Qt, el Kirigami proporciona els seus propis equivalents, amb la funcionalitat afegida de subtítols i icones:

L'API que acaba amb «Delegate» es pot definir com un delegat directe de la vista, igual que els exemples anteriors que utilitzaven Controls.ItemDelegate:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 KD.CheckSubtitleDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
}

Tant TitleSubtitle com IconTitleSubtitle s'espera que s'utilitzin per a substituir el «contentItem» d'un delegat de les Qt, per exemple:

import QtQuick
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.kirigami.delegates as KD

Kirigami.ApplicationWindow {
 title: "List of Plasma products"
 width: 600
 height: 400
 pageStack.initialPage: Kirigami.ScrollablePage {
 ListView {
 // anchors.fill: parent
 model: plasmaProductsModel
 delegate: listDelegate
 }
 ListModel {
 id: plasmaProductsModel
 ListElement { product: "Plasma Desktop"; target: "desktop" }
 ListElement { product: "Plasma Mobile"; target: "mobile" }
 ListElement { product: "Plasma Bigscreen"; target: "TVs" }
 }
 Component {
 id: listDelegate
 Controls.ItemDelegate {
 width: ListView.view.width
 text: `${model.product} is KDE software developed for ${model.target}.`
 contentItem: KD.IconTitleSubtitle {
 title: parent.text
 subtitle: `This delegate is stored at index ${model.index} of this list`
 icon.name: "kde"
 }
 }
 }
 }
}

Es pot veure un exemple pràctic d'ús dels delegats del Kirigami al fitxer ListItemTest al repositori del Kirigami.

Docs: Entendre les CMakeLists

Mon, 01 Jan 0001 00:00:00 +0000

CMake

En la nostra guia d'aprenentatge introductòria, emprem el CMake com el sistema de compilació per a la nostra aplicació, però només parem molta atenció a un dels nostres fitxers CMakeLists.txt. Aquí, repassarem com funcionen amb una mica més de detall.

El CMake és útil perquè ens permet automatitzar gran part de les coses que s'han de fer abans de la compilació.

El CMakeLists.txt arrel

És possible que recordeu aquest fitxer CMakeLists.txt de la primera guia d'aprenentatge:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

La primera línia, cmake_minimum_required() estableix la versió del CMake que es cridarà.

Després d'això, project(kirigami-tutorial) defineix el nom del projecte.

Després arribem a una secció on incloem una sèrie de paràmetres necessaris de CMake i del KDE fent servir extra-cmake-modules. Proporcionen un conjunt d'utilitats:

KDEInstallDirs proporciona variables d'utilitat com ara ${KDE_INSTALL_TARGETS_DEFAULT_ARGS}, ${KDE_INSTALL_QMLDIR}, ${KDE_INSTALL_BINDIR} i ${KDE_INSTALL_LIBDIR}.
KDECMakeSettings proporciona coses com CMAKE_AUTORCC ON, un objectiu uninstall que es pot fer servir amb cmake --build build/ --target uninstall, i ENABLE_CLAZY.
KDECompilerSettings proporciona un estàndard C++ mínim, indicadors del compilador com -pedantic, i macros de millors pràctiques com -DQT_NO_CAST_FROM_ASCII per a necessitar conversions explícites com QStringLiteral().
ECMFindQmlModule proporciona una manera d'assegurar que la dependència de QML en temps d'execució es troba en temps de compilació.
ECMQmlModule proporciona ordres del CMake com ecm_add_qml_module() i ecm_target_qml_sources().

La secció següent és important, perquè especifica quines dependències portarem en temps de compilació. Vegem el primer:

13
14
15
16
17
18
19
20
21
22
23
24
25
26


find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle

find_package() cerca i carrega la biblioteca externa i els seus components.
REQUIRED fa saber al CMake que surti amb un error si no s'ha pogut trobar el paquet.
COMPONENTS és un paràmetre que precedeix als components específics del marc de treball que incloem.
Cada paraula després de COMPONENTS es refereix a un component específic de la biblioteca.

Nota

Si esteu mirant d'afegir qualsevol component llistat a la documentació de l'API de KDE a la vostra aplicació, podeu comprovar la barra lateral dreta per com afegir el component amb el CMake. Per exemple, per al Kirigami, trobareu quelcom com find_package(KF6Kirigami), el qual amb l'addició de l'ECM es converteix en:

find_package(KF6 COMPONENTS Kirigami)

Pareu molta atenció als components inclosos, ja que l'omissió dels utilitzats en el nostre codi aturarà la compilació de l'aplicació.

La línia d'instal·lació instrueix al CMake que instal·li el fitxer «desktop» a ${KDE_INSTALL_APPDIR}, que al Linux es tradueix com $XDG_DATA_DIRS/applications, normalment /usr/share/applications, i en el Windows es tradueix com C:/Program Files/${PROJECT_NAME}/bin/data/applications:

34

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

La línia final permet que el CMake imprimeixi quins paquets ha trobat, i fa que la compilació falli completament si troba un error:

36

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

I a sobre d'això, add_subdirectory(src) a punta el CMake en el directori src/, a on troba un altre fitxer CMakeLists.txt.

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Mentre que el primer fitxer gestionava metadades i cercava biblioteques, aquest consisteix a gestionar dependències i instal·lar l'aplicació. Té les crides següents del CMake:

add_executable() crea l'objectiu executable que farem servir per a executar el projecte.
ecm_add_qml_module() crea un objectiu de mòdul QML al qual es podrà accedir via la importació «org.kde.tutorial».
target_sources() afegeix fitxers de codi font C++ a l'objectiu executable.
ecm_target_qml_sources() afegeix fitxers QML al mòdul.
target_link_libraries() enllaça les biblioteques C++ utilitzades en el nostre codi amb el nostre executable. El Kirigami no s'inclou aquí perquè només estem utilitzant el seu mòdul QML.
install() instal·la l'executable en el sistema.

La documentació de les dues ordres ECM es pot trobar a l'API dels extra-cmake-modules per a l'ECMQmlModule.

La crida a ecm_add_qml_module() s'ha fet servir aquí per a modificar l'objectiu de l'executable del codi font C++ tradicional i convertir-lo en alguna cosa que pugui acceptar fitxer QML i codi font C++ source que sigui accessible des del QML en el que s'ha cridat usant l'executable com a objectiu de reserva per a un mòdul QML. Això vol dir que els fitxers QML s'executen directament com a part de l'aplicació, que sovint és el cas de les aplicacions.

També podeu crear un mòdul QML separat que no usi l'executable com a objectiu de reserva utilitzant ecm.add.qml.module(). En aquest cas, hauríeu de crear un objectiu de biblioteca utilitzant add.library(), enllaçar-lo a un objectiu executable existent utilitzant target_link_libraries(), i a més d'instal·lar la biblioteca amb install() haureu de finalitzar el mòdul QML amb ecm_finalize_qml_module() perquè pugui generar dos fitxers: qmldir i qmltypes. Aquests fitxers són utilitzats per les aplicacions QtQuick per a trobar mòduls QML separats.

El mètode per a crear un mòdul QML separat s'exemplifica millor a Usar fitxers separats.

Aquests són afegits proporcionats per extra-cmake-modules per a fer que l'ús del registre declaratiu de les Qt faciliti (la substitució als fitxers de recursos de les Qt).

Nota

Aquestes biblioteques han de coincidir amb els components que incloem en el nostre fitxer CMakeLists.txt anterior. En cas contrari, aquests components no s'inclouran i la nostra aplicació no compilarà.

La documentació de les tres ordres ECM es pot trobar a l'API dels extra-cmake-modules per a l'ECMQmlModule.

src/components/CMakeLists.txt

A la guia d'aprenentatge sobre com dividir el codi en fitxers separats, es va introduir un fitxer CMake nou per a permetre mòduls QML separats:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

El requisit perquè aquest fitxer sigui llegit pel CMake és afegir una crida a add_subdirectory() en el src/CMakeLists.txt apuntant-hi.

La crida a add_library() genera un objectiu nou anomenat kirigami-hello-components. Aquest objectiu tindrà el seu conjunt propi de fitxers de codi font, fitxers en QML, enllaçarà les seves pròpies biblioteques i així successivament, però necessitarà estar vinculat a l'executable, però una vegada compilat necessitarà estar vinculat a l'executable creat en el src/CMakeLists.txt. Això es fa afegint el nom de destinació a la llista de biblioteques que s'enllaçaran a l'executable a target_link_libraries().

La crida a ecm_add_qml_module() canvia la biblioteca per a permetre que accepti fitxers QML com abans, però aquesta vegada cal usar GENERATE_PLUGIN_SOURCE. Quan l'executable es fa servir com a objectiu de reserva (com amb kirigami-hello) no cal generar codi del connector ja que està construït dins l'executable; amb mòduls QML separats com kirigami-hello-components és necessari el codi del connector.

El qt_add_qml_module() de les Qt originals generen de manera predeterminada un connector junt amb el mòdul QML, però l'ecm_add_qml_module() de KDE no ho fa per compatibilitat cap enrere.

Una altra cosa que és necessària per als mòduls QML separats és finalitzar l'objectiu. Això significa principalment que el CMake genera dos fitxers, qmldir i qmltypes, que descriuen els mòduls QML que tenim i exporten els seus símbols per al seu ús a la biblioteca. Són importants quan s'instal·la l'aplicació perquè l'executable que s'està executant pugui trobar on són els fitxers QML per a cada mòdul, de manera que s'afegeixen automàticament a l'objectiu.

A continuació, podeu instal·lar l'objectiu com abans.

La pròxima vegada que necessiteu afegir més fitxers QML, recordeu d'incloure'ls en aquest fitxer. Els fitxers C++ que utilitzen la paraula clau QML_ELEMENT que veurem més tard a la guia d'aprenentatge també es poden afegir aquí utilitzant target_sources(). Podeu separar lògicament el codi creant més mòduls QML amb importacions diferents segons calgui.

Aquesta configuració serà útil en desenvolupar la majoria de les aplicacions escrites amb el Kirigami.

Docs: Descobrir el main.cpp

Mon, 01 Jan 0001 00:00:00 +0000

El paper de main.cpp

Si bé el QML s'utilitza per al frontal de les aplicacions escrites amb el Kirigami, el dorsal generalment s'escriu en C++ gràcies a la velocitat i flexibilitat d'aquest llenguatge. Si bé en les pàgines anteriors hem cobert el QML amb molta profunditat, necessitarem comprendre el nostre codi en C++ del dorsal per a crear aplicacions que siguin més útils del que podem aconseguir amb un QML pur.

Aquí, repassarem el fitxer main.cpp que hem creat a la pàgina Com començar perquè puguem comprendre millor el que està succeint en el fitxer central de C++ de la nostra aplicació. Si bé aquest és un main.cpp bàsic, les característiques que repassarem seguiran sent essencials, sense importar la classe d'aplicació que decidiu crear.

Què és el que fa

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

Primer hem d'incloure una sèrie de fitxers de capçalera de les Qt, i això ens permetrà utilitzar les seves funcions. En aquest cas, incloem una sèrie de capçaleres de les Qt que manegen la lògica de l'aplicació i ens permet accedir a fitxers QML.

Després creem una instància QApplication a la que anomenarem app. La crida requereix passar argc i argv al constructor.

També establim algunes metadades relacionades amb l'aplicació. Aquestes inclouen l'organització que va crear l'aplicació, el lloc web de l'organització i el nom de l'aplicació. Configurem aquestes propietats en el QApplication, un objecte que ve de QCoreApplication i proporciona el bucle d'esdeveniments per a les aplicacions, independentment de si tenen una IGU o no (pel que si executem el nostre programa sense la IGU, aquestes metadades encara s'establiran).

Per a fer que la nostra aplicació es vegi bé amb les icones Brisa i l'estil Brisa de KDE en entorns no Plasma com el Windows o el GNOME, hem de fer tres coses:

inicialitzar les funcions de tematització dels KIconThemes a les plataformes on els temes d'icones no formen part del sistema (com el Windows o el MacOS) amb KIconTheme::initTheme()
definir el QStyle amb QApplication::setStyle() per a forçar el Brisa en lloc de l'estil natiu de la plataforma
definir l'estil del QtQuick Controls amb QQuickStyle::setStyle() per a forçar el Brisa amb el qqc2-desktop-style de KDE

La crida a KIconTheme::initTheme() cal fer-la abans de crear la QApplication i permetre que l'aplicació trobi les icones Brisa a usar. Cal establir el QStyle a Brisa perquè usem QApplication per a la nostra aplicació en lloc de QGuiApplication. Els controls reals de la interfície de la finestra com botons i caselles de selecció seguiran el Brisa utilitzant qqc2-desktop-style.

El QQmlApplicationEngine permet carregar una aplicació des d'un fitxer QML, el qual fem en la línia següent. A engine.loadFromModule("org.kde.tutorial", "Main"); carreguem el nostre QML des de l'URI d'importació definit al CMake.

A continuació, comprovem si el nostre motor ha carregat correctament el fitxer QML comprovant que la llista rootObjects() del motor no està buida. Després podem executar la nostra aplicació amb app.exec().

Docs: Pàgina «Quant al»

Mon, 01 Jan 0001 00:00:00 +0000

La Kirigami.AboutPage permet tenir una pàgina que mostra les notes dels drets d'autor de l'aplicació juntament amb la llista dels col·laboradors i certa informació sobre la plataforma en la qual s'està executant.

Primer, editarem el nostre fitxer main.cpp de les guies d'aprenentatge anteriors.

main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argc, char *argv[])
{
 QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

 QApplication app(argc, argv);

 KLocalizedString::setApplicationDomain("helloworld");
 QCoreApplication::setOrganizationName(QStringLiteral("KDE"));
 QCoreApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QCoreApplication::setApplicationName(QStringLiteral("Hello World"));

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 KAboutData aboutData(
 QStringLiteral("helloworld"),
 i18nc("@title", "Hello World"),
 QStringLiteral("1.0"),
 i18n("Hello world application"),
 KAboutLicense::GPL,
 i18n("(c) 2021"));

 aboutData.addAuthor(
 i18nc("@info:credit", "Your name"),
 i18nc("@info:credit", "Author Role"),
 QStringLiteral("your@email.com"),
 QStringLiteral("https://yourwebsite.com"));

 // Set aboutData as information about the app
 KAboutData::setApplicationData(aboutData);

 // Register a singleton that will be accessible from QML.
 qmlRegisterSingletonType(
 "org.kde.example", // How the import statement should look like
 1, 0, // Major and minor versions of the import
 "About", // The name of the QML object
 [](QQmlEngine* engine, QJSEngine *) -> QJSValue {
 // Here we retrieve our aboutData and give it to the QML engine
 // to turn it into a QML type
 return engine->toScriptValue(KAboutData::applicationData());
 }
 );

 // Load an application from a QML file
 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

En el fitxer main.cpp incloem KAboutData, un component central dels Frameworks de KDE que permet emmagatzemar la informació sobre l'aplicació. Aquesta informació després pot ser reutilitzada per molts altres components dels Frameworks del KDE. Instanciem un objecte aboutData nou amb el seu constructor predeterminat força complet i afegim la informació de l'autor.

Una vegada s'ha establert tota la informació requerida, cridem a KAboutData::setApplicationData() per a inicialitzar les propietats de l'objecte QApplication .

Després creem un qmlRegisterSingletonType(). Això s'utilitza per a permetre importar el codi C++ com un mòdul en el nostre main.qml amb import org.kde.example 1.0.

El seu primer argument és l'URI que s'utilitzarà per a la importació, el segon i el tercer són les versions majors i menors respectivament, el quart és el nom del tipus, el nom que cridarem quan accedim al nostre tipus About, i l'últim és una referència a l'objecte C++ que està exposat al QML. En el cas d'aquest últim, utilitzem una lambda per a instanciar l'aboutData de la nostra aplicació en el seu lloc.

main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

import org.kde.example 1.0

Kirigami.ApplicationWindow {
 id: root

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "gtk-quit"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 },

 Kirigami.Action { // <==== Action to open About page
 text: i18n("About")
 icon.name: "help-about"
 onTriggered: pageStack.layers.push(aboutPage)
 }
 ]
 }

 Component { // <==== Component that instantiates the Kirigami.AboutPage
 id: aboutPage

 Kirigami.AboutPage {
 aboutData: About
 }
 }

 ListModel {
 id: kountdownModel
 }

 AddEditSheet {
 id: addEditSheet
 onAdded: kountdownModel.append({
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onEdited: kountdownModel.set(index, {
 "name": name,
 "description": description,
 "date": Date.parse(kdate)
 });
 onRemoved: kountdownModel.remove(index, 1)
 }

 function openPopulatedSheet(mode, index = -1, listName = "", listDesc = "", listDate = "") {
 addEditSheet.mode = mode
 addEditSheet.index = index;
 addEditSheet.name = listName
 addEditSheet.description = listDesc
 addEditSheet.kdate = listDate

 addEditSheet.open()
 }


 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: openPopulatedSheet("add")
 }
 ]

 Kirigami.CardsListView {
 id: layout
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

Primer, utilitzarem la importació que hem definit al fitxer main.cpp, és a dir org.kde.example. Després s'afegeix Kirigami.Action al nostre calaix global que ens enviarà a la pàgina «Quant al», i crearà un component amb un Kirigami.AboutPage en ell, que espera un objecte KAboutData::applicationData(). Hem exposat precisament això en el nostre main.cpp i l'hem anomenat About, de manera que el podem passar aquí.

CMakeLists

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


cmake_minimum_required(VERSION 3.16)
project(helloworld)

find_package(ECM REQUIRED NO_MODULE)

set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)

find_package(Qt6 REQUIRED NO_MODULE COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami2
 I18n
 CoreAddons
)

add_subdirectory(src)

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

Al fitxer CMakeLists.txt de la nostra carpeta de nivell superior, assegureu-vos de tenir CoreAddons a la crida find_package(). És necessari per a KAboutData.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


add_executable(helloworld)

target_sources(helloworld PRIVATE
 main.cpp
 resources.qrc
)

target_link_libraries(helloworld
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::Kirigami2
 KF6::I18n
 KF6::CoreAddons
)

En el fitxer CMakeLists.txt en el directori src/, no es necessita res, ja que hem instanciat aboutData al lloc.

Executar l'aplicació

Ara, si executeu la vostra aplicació i activeu l'acció «About» en el calaix global, s'hauria de mostrar la nostra pàgina.

Docs: Connectar la lògica amb la vostra interfície d'usuari en QML

Mon, 01 Jan 0001 00:00:00 +0000

Per a integrar la lògica dins de l'aplicació, necessitem que les classes del dorsal estiguin en C++ perquè puguin fer els càlculs importants. Es desaconsella escriure la lògica en els fitxers QML, així que intenteu moure tant com sigui possible cap al dorsal, de manera que el QML s'empri exclusivament per a mostrar la interfície d'usuari.

Farem servir el codi de la guia d'aprenentatge [Usar fitxers separats en un projecte C++](/content/docs/getting-started/kirigami/introduction- separatefiles) com a base.

Estructura del projecte

kirigami-tutorial/
├── CMakeLists.txt
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml ------------- # New
├── backend.h ------------------ # New
└── backend.cpp ---------------- # New

Canvis en el codi existent

src/components/backend.h

Primer, creeu el fitxer de capçalera que tindrà el codi exposat al QML, és a dir, el tipus Backend:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON

public:
 explicit Backend(QObject *parent = nullptr);
};

Hi ha dues coses necessàries per a exposar el codi C++ al QML, i una d'elles és simplement utilitzar la macro QML_ELEMENT, disponible a la capçalera <QtQml/qqmlregistration.h>.

El dorsal es crearà com a «singleton», el que significa que només es crearà una vegada i existirà durant tota la durada de l'aplicació. Per això, fem servir la macro QML_SINGLETON.

src/components/backend.cpp

Podem afegir el nostre codi inicial per al constructor a backend.cpp:

1
2
3
4
5


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

src/components/ExposePage.qml

A partir d'ara, el dorsal serà conegut pel QML com el tipus QML Backend. Està contingut en un mòdul anomenat org.kde.tutorial.components.

Això significa que només afegint la importació en un fitxer QML, és possible utilitzar el codi exposat des de C++:

import org.kde.tutorial.components

Per a començar des de zero utilitzant el codi d'aplicació existent, creeu un component QML nou que contingui una pàgina buida:

1
2
3
4
5
6
7


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 // ...
}

src/Main.qml

Per a mostrar realment la pàgina nova, crearem una opció de menú que enviï la pàgina nova a l'aplicació, només perquè puguem provar el model amb més facilitat.

Per a això, podem utilitzar una Kirigami.Action juntament amb Qt.createComponent() per a generar la pàgina sobre la marxa:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

src/components/CMakeLists.txt

Finalment, afegim els backend.h, backend.cpp i ExposePage.qml creats nous al CMake:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Afegir els fitxers a un mòdul QML existent en el CMake és la segona part per a exposar el codi al QML.

Tingueu en compte que el mòdul QML hauria d'haver estat creat amb ecm_add_qml_module() o qt_add_qml_module(), ja que es requereixen per al registre declaratiu.

Ara hauríeu de poder compilar i instal·lar el projecte amb els mateixos passos que abans.

Fer-ho funcional

src/components/backend.h

Ara hem connectat la classe que conté la lògica futura amb l'aplicació, però encara no fa res. Per a canviar això, afegirem una propietat a la classe. Les propietats són molt més que una simple variable. Poden informar a la interfície d'usuari sobre els canvis perquè pugui actualitzar les àrees correctes.

Just a sota de la macro QML_SINGLETON, afegim una [Q_PROPERTY](docs:qtcore; QObject::Q_PROPERTY) nova.

Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)

Això sembla molt codi per a només llegir i escriure codi des del dorsal. Però una mirada més atenta revela que llegir la propietat des de la IU pot executar una lògica, i el mateix quan s'escriu. En aquest cas, informarà automàticament el frontal i el dorsal dels canvis.

La lectura i escriptura es basen en les funcions capturadora i establidora. Continueu i afegiu un atribut privat nou a la vostra classe que contingui les dades, així com les funcions capturadora i establidora rellevants.

Afegim una secció privada nova amb el següent:

private:
 QString m_introductionText = QStringLiteral("Hello World!");

I afegim el següent a la secció pública existent:

public:
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();

La primera funció és la capturadora, la segona l'establidora i la tercera un senyal que s'emet quan es canvia la propietat. Coincideixen amb les parts READ, WRITE i NOTIFY de la Q_PROPERTY d'abans.

El resultat hauria de ser el següent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

El senyal no necessita cap implementació en el fitxer backend.cpp, ja que no fa gaire més que ser emès, però la capturadora i l'establidora s'han d'implementar de manera similar a la següent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

Com podeu veure, quan es crida al configurador, s'emetrà el senyal i informarà la interfície d'usuari i al dorsal del canvi.

src/components/ExposePage.qml

Per a mostrar el text, afegiu una Kirigami.Heading a src/components/ExposePage.qml sota la propietat title del component Kirigami.Page que hem afegit al codi.

El codi resultant en aquesta part del fitxer s'hauria de veure així:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

La nostra aplicació fins ara

Codi existent:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

Codi escrit/modificat en aquesta pàgina:

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

Ara compileu i torneu a iniciar el programa. Veureu que la pàgina nova té un encapçalament centrat dient «Hola món!».

Felicitacions, heu après:

Com registrar els tipus de dorsal en QML
Afegir elements nous al fitxer en QML
Crear subclasses noves de QObject
Com afegir propietats i què fan
Quins són els senyals

Si voleu saber més sobre la integració entre QML i C++, us recomanem llegir la documentació oficial de les Qt.

Docs: Connectar models C++ a la vostra interfície d'usuari en QML

Mon, 01 Jan 0001 00:00:00 +0000

Com es mostra a la guia d'aprenentatge anterior, podeu connectar codi C++ al QML creant una classe que es tractarà com un altre component en QML. No obstant això, és possible que vulgueu representar dades més complicades, com ara les dades que han d'actuar com un ListModel personalitzat o, d'alguna manera, han de ser delegades des d'un Repeater.

Podem crear els nostres propis models des de la banda del C++, i declarar com s'han de representar les dades d'aquest model en el frontal QML.

És molt recomanable que llegiu la guia d'aprenentatge Vistes de llista abans d'aquest.

El codi utilitzat per a aquesta guia d'aprenentatge es basarà en la pàgina anterior, Connectar la lògica amb la vostra interfície d'usuari en QML.

Estructura del projecte

kirigami-tutorial/
├── CMakeLists.txt --------------------- # Modified for didactic purposes
├── org.kde.tutorial.desktop
└── src/
├── CMakeLists.txt
├── main.cpp
├── Main.qml ----------------------- # Modified
└── components/
├── CMakeLists.txt ------------- # Modified
├── AddDialog.qml
├── KountdownDelegate.qml
├── ExposePage.qml
├── ModelsPage.qml ------------- # New
├── model.h -------------------- # New
├── model.cpp ------------------ # New
├── backend.h
└── backend.cpp

Creació d'una pàgina nova per a la guia d'aprenentatge de models

Abans de fer res, afegim una pàgina nova al nostre codi QML.

Primer, a src/Main.qml, afegim l'acció següent al calaix global:

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

Després, creeu un src/components/ModelsPage.qml nou amb el contingut següent:

1
2
3
4
5
6
7
8
9


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 // ...
}

I finalment, afegiu-lo a src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Això servirà com a llenç per a aquesta pàgina de la guia d'aprenentatge.

Ús de cadenes en brut

Per a fer que aquesta guia d'aprenentatge sigui més fàcil d'entendre com s'omple el model, desactivarem una característica que les aplicacions KDE que utilitzen els extra-cmake-modules (ECM) fan servir de manera predeterminada d'optimització del codi de cadenes. Això ens permet evitar haver d'escriure QStringLiteral() cada vegada que s'introdueixi una cadena en el nostre codi C++, el qual serà útil per al codi en el fitxer de capçalera proper.

Al fitxer arrel CMakeLists.txt, afegiu el següent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

🚨 No feu això a producció

La desactivació d'aquest indicador del CMake només es fa amb finalitats didàctiques. El codi de producció ha d'utilitzar QStringLiteral() o l'espai de noms de literals de cadenes de les Qt quan sigui possible.

Preparant la classe

Crearem una classe que conté un QMap, on s'utilitza un QString com a clau i objectes QStringList com a valors. El frontal podrà llegir i mostrar les claus i els valors i serà senzill d'utilitzar com una matriu unidimensional. Hauria de ser semblant a un ListModel en QML.

Per a fer-ho, necessitem crear una classe que hereti de QAbstractListModel. Afegim també algunes dades addicionals al QMap. Aquestes declaracions s'ubicaran a model.h.

Creeu dos fitxers nous, src/components/model.h i src/components/model.cpp.

Afegiu aquests dos fitxers a src/components/CMakeLists.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

Afegiu el següent com a contingut inicial a src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

Per descomptat, no podem simplement mostrar aquesta classe com és. També hem de dir-li al QML com representar aquestes dades a la classe. Podem fer-ho sobreescrivint tres funcions virtuals essencials:

rowCount() - Penseu en aquesta funció com una manera de dir al QML quants elements ha de representar el model.
roleNames() - Podeu pensar en els noms dels rols com a noms de propietats adjunts a les dades en QML. Aquesta funció permet crear aquests rols.
data() - Aquesta funció es crida quan voleu recuperar les dades que corresponen als noms dels rols a partir del model.

Nota

Els noms de rol personalitzats creats per roleNames() només es poden utilitzar quan s'està delegant un model, i no es poden utilitzar fora d'ell. Vegeu Models i vistes.

Nota

Tècnicament, els models en Qt es representen com a taules, amb files i columnes. Per tant, el que fa rowCount() és dir a les Qt quantes files hi ha en un model. Com que només estem tractant amb una matriu unidimensional en aquesta guia d'aprenentatge, només podeu pensar en «files» com a «nombre d'elements».

Sobreescriure i implementar `rowCount()`

Sobreescrivim la funció al fitxer de capçalera src/components/model.h. El rowCount() ve amb el seu paràmetre propi, però no s'utilitzarà en aquest exemple i, per tant, no cal anomenar-lo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

Llavors, declarem quantes files hi ha en aquest model a src/components/model.cpp:

1
2
3
4
5


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

Sobreescriure i implementar `roleNames()`

Abans de substituir roleNames(), necessitem declarar quins són els rols a la banda del C++ utilitzant una enumeració pública. El motiu d'això és perquè aquests valors de la variable d'enumeració es passen a data() cada vegada que el QML accedeix a un rol corresponent, i com a tal podem fer que data() retorni el que volem.

Comencem per crear la variable d'enumeració per als rols a src/components/model.h, a on cada valor és un rol de la banda del C++.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };

 QHash<int, QByteArray> roleNames() const override;
 int rowCount(const QModelIndex &) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
};

Una vegada que hàgim resolt això, finalment podrem crear quins són aquests rols en la banda del QML utilitzant un QHash on les claus són els valors enumerats aparellats amb QByteArrays. Això hauria d'anar a src/components/model.cpp. El text del QByteArray és el que s'utilitza en el codi QML real.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

En el nostre model d'exemple, el rol «espècies» es pot utilitzar per a recuperar la clau del QString «Feline», «Fox», «Goat», cadascuna en un delegat separat. El mateix es pot fer amb els valors de QStringList per a la llista de noms de caràcters.

Sobreescriure i implementar `data()`

Hi ha dos paràmetres que es passen a data(): index i role. L'index és la posició de les dades en el model. Com s'ha indicat anteriorment, el QML utilitza el role per a obtenir dades específiques que es retornen quan s'està accedint a un rol.

A data(), podem utilitzar una declaració de commutació per a retornar les dades i el tipus de dades adequats depenent del rol, el qual és possible ja que data() retorna una QVariant. No obstant això, encara hem d'assegurar-nos d'aconseguir la ubicació adequada de les dades. En aquest exemple a continuació, podeu veure que s'està declarant una variable nova de l'iterador, que s'estableix des del principi de la llista més la fila de l'índex i les dades a les quals apunta l'iterador que és el que s'està retornant.

Però no podem retornar les dades que vulguem. És possible que estiguem intentant vincular dades a una propietat amb un tipus de dades incompatible, com ara una QStringList a una QString. És possible que hàgiu de fer la conversió de dades perquè les dades es mostrin correctament. Per a això, creem una funció estàtica privada nova anomenada formatList().

Això dona com a resultat el codi següent a src/components/model.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

I el codi següent a src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Ús de la classe en el QML

El fitxer QML que s'utilitza només contindrà tres components Kirigami.AbstractCard, on la clau és la capçalera i el valor és el contingut. Aquestes targetes es creen delegant una AbstractCard utilitzant un repetidor, on el model personalitzat que hem creat actua com a model. S'accedeix a les dades utilitzant la paraula model, seguida dels rols que hem declarat a roleNames().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Controls.Label {
 text: model.characters
 }
 }
 }
 }
}

Modificació de dades

Edició de dades utilitzant `dataChanged()` i `setData()`

Podeu trobar-vos amb una situació en la qual vulgueu modificar les dades del model, i tenir els canvis reflectits a la banda del frontal. Cada vegada que canviem dades en el model, hem d'emetre el senyal dataChanged() que aplicarà aquests canvis a la banda del frontal a les cel·les específiques especificades en els seus arguments. En aquesta guia d'aprenentatge, només podem utilitzar l'argument index de setData().

setData() és una funció virtual que podeu sobreescriure de manera que modificar les dades des de la banda del frontal reflecteix automàticament aquests canvis a la banda del dorsal. Requereix tres paràmetres:

index - La ubicació de les dades.
value - El contingut de les dades noves.
role - En aquest context, el rol aquí s'utilitza per a dir a les vistes com haurien de gestionar les dades. El rol aquí hauria de ser Qt::EditRole.

El paràmetre role en aquest cas s'utilitza per a assegurar que setData() es pot editar mitjançant l'entrada de l'usuari (Qt::EditRole). Utilitzant index, podem utilitzar això per a determinar la ubicació d'on s'han d'editar les dades amb el contingut de value.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

Nota

setData() no emet automàticament dataChanged() i això s'ha de fer manualment.

Amb l'addició corresponent a src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Actualitzem el codi QML de manera que puguem obrir un indicador que ens permeti editar el model utilitzant un Controls.Button adjunt a les targetes.

Afegim el Kirigami.PromptDialog següent al src/components/ModelsPage.qml, junt amb el botó nou d'edició:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

Ara, sempre que els valors del model canviïn al frontal, els canvis s'hauran d'actualitzar automàticament al dorsal.

Afegir files

S'ha afegit una manera de modificar les dades a les claus existents del QMap, i al frontal, això es reflecteix com modificar el contingut dins de les AbstractCards. Però, i si necessitem afegir una entrada nova de clau al QMap i tenir això reflectit a la banda del QML? Fem-ho creant un mètode nou que es pot cridar a la banda del QML per a realitzar aquesta tasca.

Per a fer visible el mètode en el QML, cal començar la declaració del mètode amb la macro Q_INVOKABLE. Aquest mètode també inclourà un paràmetre de cadena, que es pretén que sigui la clau nova en el QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Dins d'aquest mètode, hem de dir a les Qt que volem crear més files en el model. Això es fa cridant a beginInsertRows() per a començar la nostra operació d'addició de files, seguida d'inserir el que necessitem, i després utilitzeu endInsertRows() per a acabar l'operació. No obstant això, encara cal emetre dataChanged() al final. Aquesta vegada, actualitzarem totes les files, des de la primera fila fins a l'última, ja que el QMap pot reorganitzar-se alfabèticament, i hem d'agafar-ho a totes les files.

En cridar beginInsertRows(), primer hem de passar en una classe QModelIndex per a especificar la ubicació d'on s'han d'afegir les files noves, seguit de quins seran els números nous de primera i última fila. En aquesta guia d'aprenentatge, el primer argument serà QModelIndex(), ja que no cal utilitzar el paràmetre aquí. Només podem utilitzar la mida de fila actual per al primer i últim número de fila, ja que només afegirem una fila al final del model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Nota

La funció dataChanged() utilitza QModelIndex com a tipus de dades per als seus paràmetres. No obstant això, podem convertir enters en tipus de dades QModelIndex utilitzant la funció index().

Actualitzem el codi en QML, de manera que se'ns dona la possibilitat d'afegir una clau nova al QMap.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 // ...
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }
 Kirigami.PromptDialog {
 id: editPrompt
 // ...
 }
}

Ara, se'ns ha de donar una acció nova a la part superior de l'aplicació que obri un indicador que permeti afegir un element nou al model, amb les nostres pròpies dades personalitzades.

Eliminar files

La manera d'eliminar files és similar a afegir files. Creem un altre mètode que cridarem en el QML. Aquesta vegada, utilitzarem un paràmetre addicional, i és un enter que és el número de fila. El nom de l'espècie s'utilitza per a suprimir la clau del QMap, mentre que el número de fila s'utilitzarà per a suprimir la fila en el frontal.

Afegiu una funció Q_INVOKABLE nova anomenada deleteSpecies() a src/components/model.h:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);

private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

Amb una implementació coincident a src/components/model.cpp:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Ara, actualitzem l'aplicació de manera que apareixerà un botó «Elimina» en un RowLayout al costat del botó d'edició dins la nostra AbstractCard, i enganxeu-lo al nostre mètode d'eliminació.

24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60


 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }

La nostra aplicació fins ara

Codi existent:

src/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


add_executable(kirigami-hello)

ecm_add_qml_module(kirigami-hello
 URI
 org.kde.tutorial
)

target_sources(kirigami-hello
 PRIVATE
 main.cpp
)

ecm_target_qml_sources(kirigami-hello
 SOURCES
 Main.qml
)

target_link_libraries(kirigami-hello
 PRIVATE
 Qt6::Quick
 Qt6::Qml
 Qt6::Gui
 Qt6::QuickControls2
 Qt6::Widgets
 KF6::I18n
 KF6::CoreAddons
 KF6::IconThemes
 kirigami-hello-components
)

install(TARGETS kirigami-hello ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

add_subdirectory(components)

src/main.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <QApplication>
#include <QQmlApplicationEngine>
#include <QtQml>
#include <QUrl>
#include <QQuickStyle>
#include <KLocalizedContext>
#include <KLocalizedString>
#include <KIconTheme>

int main(int argc, char *argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 KLocalizedString::setApplicationDomain("tutorial");
 QApplication::setOrganizationName(QStringLiteral("KDE"));
 QApplication::setOrganizationDomain(QStringLiteral("kde.org"));
 QApplication::setApplicationName(QStringLiteral("Kirigami Tutorial"));
 QApplication::setDesktopFileName(QStringLiteral("org.kde.tutorial"));

 QApplication::setStyle(QStringLiteral("breeze"));
 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }

 QQmlApplicationEngine engine;

 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.tutorial", "Main");

 if (engine.rootObjects().isEmpty()) {
 return -1;
 }

 return app.exec();
}

src/components/KountdownDelegate.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.AbstractCard {
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 GridLayout {
 id: delegateLayout
 anchors {
 left: parent.left
 top: parent.top
 right: parent.right
 }
 rowSpacing: Kirigami.Units.largeSpacing
 columnSpacing: Kirigami.Units.largeSpacing
 columns: root.wideScreen ? 4 : 2

 Kirigami.Heading {
 level: 1
 text: i18n("%1 days", Math.round((date-Date.now())/86400000))
 }

 ColumnLayout {
 Kirigami.Heading {
 Layout.fillWidth: true
 level: 2
 text: name
 }
 Kirigami.Separator {
 Layout.fillWidth: true
 visible: description.length > 0
 }
 Controls.Label {
 Layout.fillWidth: true
 wrapMode: Text.WordWrap
 text: description
 visible: description.length > 0
 }
 }
 Controls.Button {
 Layout.alignment: Qt.AlignRight
 Layout.columnSpan: 2
 text: i18n("Edit")
 }
 }
 }
}

src/components/AddDialog.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami

Kirigami.Dialog {
 id: addDialog
 title: i18nc("@title:window", "Add kountdown")
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 padding: Kirigami.Units.largeSpacing
 preferredWidth: Kirigami.Units.gridUnit * 20

 Kirigami.FormLayout {
 Controls.TextField {
 id: nameField
 Kirigami.FormData.label: i18nc("@label:textbox", "Name*:")
 onAccepted: descriptionField.forceActiveFocus()
 }
 Controls.TextField {
 id: descriptionField
 Kirigami.FormData.label: i18nc("@label:textbox", "Description:")
 onAccepted: dateField.forceActiveFocus()
 }
 Controls.TextField {
 id: dateField
 Kirigami.FormData.label: i18nc("@label:textbox", "ISO Date*:")
 inputMask: "D999-99-99"
 onAccepted: addDialog.accepted()
 }
 Controls.Label {
 text: "* = required fields"
 }
 }
 Component.onCompleted: {
 const button = standardButton(Kirigami.Dialog.Ok);
 button.enabled = Qt.binding( () => requiredFieldsFilled() );
 }
 onAccepted: {
 if (!addDialog.requiredFieldsFilled()) return;
 appendDataToModel();
 clearFieldsAndClose();
 }
 function requiredFieldsFilled() {
 return (nameField.text !== "" && dateField.acceptableInput);
 }
 function appendDataToModel() {
 kountdownModel.append({
 name: nameField.text,
 description: descriptionField.text,
 date: new Date(dateField.text)
 });
 }
 function clearFieldsAndClose() {
 nameField.text = ""
 descriptionField.text = ""
 dateField.text = ""
 addDialog.close();
 }
}

src/components/ExposePage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.Page {
 title: "Exposing to QML Tutorial"
 Kirigami.Heading {
 anchors.centerIn: parent
 text: Backend.introductionText
 }
}

src/components/backend.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#pragma once

#include <QObject>
#include <qqmlintegration.h>

class Backend : public QObject
{
 Q_OBJECT
 QML_ELEMENT
 QML_SINGLETON
 Q_PROPERTY(QString introductionText READ introductionText WRITE setIntroductionText NOTIFY introductionTextChanged)
public:
 explicit Backend(QObject *parent = nullptr);
 QString introductionText() const;
 void setIntroductionText(const QString &introductionText);
 Q_SIGNAL void introductionTextChanged();
private:
 QString m_introductionText = QStringLiteral("Hello World!");
};

src/components/backend.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


#include "backend.h"

Backend::Backend(QObject *parent)
 : QObject(parent)
{}

QString Backend::introductionText() const
{
 return m_introductionText;
}

void Backend::setIntroductionText(const QString &introductionText)
{
 m_introductionText = introductionText;
 Q_EMIT introductionTextChanged();
}

Codi escrit/modificat en aquesta pàgina:

CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


cmake_minimum_required(VERSION 3.20)
project(kirigami-tutorial)

find_package(ECM 6.0.0 REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMFindQmlModule)
include(ECMQmlModule)
remove_definitions(-DQT_NO_CAST_FROM_ASCII)

find_package(Qt6 REQUIRED COMPONENTS
 Core
 Quick
 Test
 Gui
 QuickControls2
 Widgets
)

find_package(KF6 REQUIRED COMPONENTS
 Kirigami
 I18n
 CoreAddons
 QQC2DesktopStyle
 IconThemes
)

ecm_find_qmlmodule(org.kde.kirigami REQUIRED)

add_subdirectory(src)

install(PROGRAMS org.kde.tutorial.desktop DESTINATION ${KDE_INSTALL_APPDIR})

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)

src/Main.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ApplicationWindow {
 id: root

 width: 600
 height: 400

 title: i18nc("@title:window", "Day Kountdown")

 globalDrawer: Kirigami.GlobalDrawer {
 isMenu: true
 actions: [
 Kirigami.Action {
 text: i18n("Exposing to QML Tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ExposePage"))
 },
 Kirigami.Action {
 text: i18n("C++ models in QML tutorial")
 icon.name: "kde"
 onTriggered: pageStack.push(Qt.createComponent("org.kde.tutorial.components", "ModelsPage"))
 },
 Kirigami.Action {
 text: i18n("Quit")
 icon.name: "application-exit-symbolic"
 shortcut: StandardKey.Quit
 onTriggered: Qt.quit()
 }
 ]
 }

 ListModel {
 id: kountdownModel
 }

 AddDialog {
 id: addDialog
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 title: i18nc("@title", "Kountdown")

 actions: [
 Kirigami.Action {
 id: addAction
 icon.name: "list-add-symbolic"
 text: i18nc("@action:button", "Add kountdown")
 onTriggered: addDialog.open()
 }
 ]

 Kirigami.CardsListView {
 id: cardsView
 model: kountdownModel
 delegate: KountdownDelegate {}
 }
 }
}

src/components/CMakeLists.txt

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


add_library(kirigami-hello-components)

ecm_add_qml_module(kirigami-hello-components
 URI "org.kde.tutorial.components"
 GENERATE_PLUGIN_SOURCE
)

ecm_target_qml_sources(kirigami-hello-components
 SOURCES
 AddDialog.qml
 KountdownDelegate.qml
 ExposePage.qml
 ModelsPage.qml
)

target_sources(kirigami-hello-components
 PRIVATE
 backend.cpp backend.h
 model.cpp model.h
)

ecm_finalize_qml_module(kirigami-hello-components)

install(TARGETS kirigami-hello-components ${KDE_INSTALL_TARGETS_DEFAULT_ARGS})

src/components/ModelsPage.qml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94


import QtQuick
import QtQuick.Layouts
import QtQuick.Controls as Controls
import org.kde.kirigami as Kirigami
import org.kde.tutorial.components

Kirigami.ScrollablePage {
 title: "C++ models in QML"
 actions: [
 Kirigami.Action {
 icon.name: "list-add-symbolic"
 text: "Add New Species"
 onTriggered: {
 addPrompt.open();
 }
 }
 ]
 Model {
 id: customModel
 }
 ColumnLayout {
 anchors.left: parent.left
 anchors.right: parent.right
 Repeater {
 model: customModel
 delegate: Kirigami.AbstractCard {
 Layout.fillHeight: true
 header: Kirigami.Heading {
 text: model.species
 level: 2
 }
 contentItem: Item {
 implicitWidth: delegateLayout.implicitWidth
 implicitHeight: delegateLayout.implicitHeight
 ColumnLayout {
 id: delegateLayout
 Controls.Label {
 text: model.characters
 }
 RowLayout {
 Layout.fillWidth: true
 Controls.Button {
 text: "Edit"
 onClicked: {
 editPrompt.text = model.characters;
 editPrompt.model = model;
 editPrompt.open();
 }
 }
 Controls.Button {
 text: "Delete"
 onClicked: {
 customModel.deleteSpecies(model.species, index);
 }
 }
 }
 }
 }
 }
 }
 }
 Kirigami.PromptDialog {
 id: addPrompt
 title: "Add New Species"
 standardButtons: Kirigami.Dialog.Ok
 onAccepted: {
 customModel.addSpecies(addPromptText.text);
 addPromptText.text = ""; // Clear TextField every time it's done
 addPrompt.close();
 }
 Controls.TextField {
 id: addPromptText
 Layout.fillWidth: true
 onAccepted: addPrompt.accept()
 }
 }

 Kirigami.PromptDialog {
 id: editPrompt
 property var model
 property alias text: editPromptText.text
 title: "Edit Characters"
 standardButtons: Kirigami.Dialog.Ok | Kirigami.Dialog.Cancel
 onAccepted: {
 const model = editPrompt.model;
 model.characters = editPromptText.text;
 editPrompt.close();
 }
 Controls.TextField {
 id: editPromptText
 onAccepted: editPrompt.accept()
 }
 }
}

src/components/model.h

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#pragma once

#include <QAbstractListModel>
#include <qqmlintegration.h>

class Model : public QAbstractListModel {
 Q_OBJECT
 QML_ELEMENT
public:
 enum Roles {
 SpeciesRole = Qt::UserRole,
 CharactersRole
 };
 int rowCount(const QModelIndex &) const override;
 QHash<int, QByteArray> roleNames() const override;
 QVariant data(const QModelIndex &index, int role) const override;
 bool setData(const QModelIndex &index, const QVariant &value, int role) override;
 Q_INVOKABLE void addSpecies(const QString &species);
 Q_INVOKABLE void deleteSpecies(const QString &speciesName, const int &rowIndex);
private:
 QMap<QString, QStringList> m_list = {
 {"Feline", {"Tigress", "Waai Fuu"}},
 {"Fox", {"Carmelita", "Diane", "Krystal"}},
 {"Goat", {"Sybil", "Toriel"}}
 };
 static QString formatList(const QStringList& list);
};

src/components/model.cpp

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


#include "model.h"

int Model::rowCount(const QModelIndex &) const {
 return m_list.count();
}

QHash<int, QByteArray> Model::roleNames() const {
 return {
 {SpeciesRole, "species"},
 {CharactersRole, "characters"}
 };
}

QVariant Model::data(const QModelIndex &index, int role) const {
 const auto it = std::next(m_list.begin(), index.row());
 switch (role) {
 case SpeciesRole:
 return it.key();
 case CharactersRole:
 return formatList(it.value());
 default:
 return {};
 }
}

QString Model::formatList(const QStringList& list) {
 QString result;
 for (const QString& character : list) {
 result += character;
 if (list.last() != character) {
 result += ", ";
 }
 }
 return result;
}

bool Model::setData(const QModelIndex &index, const QVariant &value, int role) {
 if (!value.canConvert<QString>() && role != Qt::EditRole) {
 return false;
 }

 auto it = std::next(m_list.begin(), index.row());
 QString charactersUnformatted = value.toString();
 QStringList characters = charactersUnformatted.split(", ");

 m_list[it.key()] = characters;
 Q_EMIT dataChanged(index, index);

 return true;
}

void Model::addSpecies(const QString& species) {
 beginInsertRows(QModelIndex(), m_list.size() - 1, m_list.size() - 1);
 m_list.insert(species, {});
 endInsertRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

void Model::deleteSpecies(const QString &speciesName, const int& rowIndex) {
 beginRemoveRows(QModelIndex(), rowIndex, rowIndex);
 m_list.remove(speciesName);
 endRemoveRows();
 Q_EMIT dataChanged(index(0), index(m_list.size() - 1));
}

Més informació

Per a més informació, vegeu Using C++ Models with Qt Quick Views i Model/View Programming.

Docs: Introducció als complements del Kirigami

Mon, 01 Jan 0001 00:00:00 +0000

Els complements del Kirigami són un conjunt addicional de components visuals que funcionen bé en el mòbil i l'escriptori i es garanteix que són multiplataforma. Utilitzen el Kirigami per sota per a crear els seus components.

Aquí configurareu el vostre projecte nou de complements del Kirigami i es presentaran alguns components útils.

Aquests components fan ús de les ajudes de localització del KDE, de manera que abans de començar a utilitzar-les, haurem d'establir un petit projecte que faci ús del KLocalizedContext.

Configurar el projecte

L'estructura inicial del projecte s'hauria de veure així:

addonsexample/
├── CMakeLists.txt
├── main.cpp
└── Main.qml

Consell

Podeu crear ràpidament aquesta estructura de fitxers amb:

mkdir -p addonsexample/contents/ui
touch addonsexample/{CMakeLists.txt,main.cpp}
touch addonsexample/Main.qml

Comencem utilitzant un CMakeLists.txt molt estàndard:

cmake_minimum_required(VERSION 3.20)

project(FormCardTutorial)

find_package(ECM REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECompilerSettings)
include(KDECMakeSettings)
include(ECMQmlModule)

find_package(Qt6 REQUIRED COMPONENTS
 Widgets # For QApplication
 Quick # For QML
 QuickControls2 # For QQuickStyle
)
find_package(KF6 REQUIRED COMPONENTS
 CoreAddons # For KAboutData
 I18n # For KLocalizedContext
)
qt_policy(SET QTP0001 NEW)

add_executable(addonsexample)

target_sources(addonsexample PRIVATE main.cpp)

ecm_add_qml_module(addonsexample
 GENERATE_PLUGIN_SOURCE
 URI org.kde.addonsexample
)

ecm_target_qml_sources(addonsexample SOURCES
 Main.qml
 SettingsPage.qml
 JsonAboutPage.qml
)

target_link_libraries(addonsexample PRIVATE
 Qt::Widgets
 Qt::Quick
 Qt::QuickControls2
 KF6::CoreAddons
 KF6::I18n
)

install(TARGETS addonsexample DESTINATION ${KDE_INSTALL_BINDIR})

La part interessant serà el main.cpp:

#include <QtQml>
#include <QApplication>
#include <QQmlApplicationEngine>
#include <QIcon>
#include <QQuickStyle>
#include <KAboutData>
#include <KLocalizedContext>
#include <KLocalizedString>

int main(int argCount, char* argVector[])
{
 QApplication app(argCount, argVector);
 KLocalizedString::setApplicationDomain("org.kde.addonsexample");

 KAboutData aboutData(
 QStringLiteral("addonsexample"),
 i18nc("@title:window", "Addons Example"),
 QStringLiteral("1.0"),
 i18nc("@info", "This program shows how to use Kirigami Addons"),
 KAboutLicense::GPL_V3,
 QStringLiteral("(C) 2023"),
 i18nc("@info", "Optional text shown in the About"),
 QStringLiteral("https://kde.org"));

 aboutData.addAuthor(i18nc("@info:credit", "John Doe"),
 i18nc("@info:credit", "Maintainer"));

 KAboutData::setApplicationData(aboutData);

 if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE")) {
 QQuickStyle::setStyle(QStringLiteral("org.kde.desktop"));
 }
 QApplication::setWindowIcon(QIcon::fromTheme(QStringLiteral("kde")));

 QQmlApplicationEngine engine;
 engine.rootContext()->setContextObject(new KLocalizedContext(&engine));
 engine.loadFromModule("org.kde.addonsexample", "Main");
 app.exec();
}

Si heu llegit la nostra guia d'aprenentatge del KXmlGui o l'última guia d'aprenentatge del Kirigami a la pàgina sobre el Kirigami, gran part d'això us semblarà familiar.

Creem la nostra aplicació i utilitzem el constructor predeterminat del KAboutData per a afegir les metadades de la nostra aplicació, afegir-nos com a autor i després utilitzar setApplicationData() per a acabar el procés. Per a més endavant, també s'ha establert una icona d'aplicació que prové del tema del sistema.

Després utilitzem una lambda en qmlRegisterSingletonType() per a enviar directament les metadades de la nostra aplicació a la part del QML, exposant les seves propietats.

Després, instanciem el nostre motor QML i establim el seu context per a utilitzar el KLocalizedContext de KDE, que s'utilitza per a integrar cadenes traduïdes, passant el motor que s'acaba de crear com a paràmetre.

Simplement carreguem el fitxer QML des del fitxer de recursos, i ara només cal tenir cura del fitxer QML inicial.

FormCard i FormButtonDelegate

La idea de l'aplicació és dissenyar la nostra pròpia galeria de complements del Kirigami, mostrant múltiples components, un per pàgina. La pàgina principal contindrà una llista senzilla de botons en un ColumnLayout, cada un obrint una pàgina separada.

Inicialment, el nostre Main.qml s'hauria de veure així:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 // Our code will go here
 }
 }
}

Utilitzem la nostra útil pageStack per a establir la pàgina inicial a Kirigami.ScrollablePage.

Tot i que podríem utilitzar un FormLayout juntament amb els components de QtQuick Controls per a assolir el nostre objectiu, aquí us presentarem un FormCard.

El propòsit principal d'un FormCard és servir com a contenidor per a altres components mentre segueix un color diferent del fons, de manera similar a un Kirigami.Card, però per a les finestres de configuració. Podeu tenir múltiples FormCards a l'aplicació per a indicar seccions diferents. També s'espera que el FormCard sigui fill directe d'un ColumnLayout.

La importació de org.kde.kirigamiaddons.formcard fa que tots els components de FormCard estiguin disponibles per al fitxer QML.

Només tindrem una secció única a la pàgina principal, per la qual cosa afegirem una FormCard única:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 // Our buttons will go here
 }
 }
 }
}

El millor del FormCard és que fa una maquetació automàtica. En altres paraules, només l'ordre dels seus components és suficient per a indicar la seva posició dins del FormCard, no són necessàries les propietats adjuntes a la disposició i s'espera que no utilitzeu les àncores o els posicionadors.

Simplement podem afegir uns quants botons dins de la FormCard:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 }
 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }
 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

Això és tot! Els botons encara no es poden utilitzar, però ara estem preparats per a jugar amb les nostres pàgines «Quant al»!

Després la construïm i l'executem així:

cmake -B build/ -DCMAKE_INSTALL_PREFIX=~/kde5/usr
cmake --build build/
cmake --install build/
aboutexample

Per a veure altres maneres de construir la vostra aplicació (per exemple, al Windows), vegeu la pàgina Com començar amb el Kirigami.

Docs: Pàgines FormCard «Quant al»

Mon, 01 Jan 0001 00:00:00 +0000

Alguns d'aquests components us permeten acreditar el vostre treball i el treball d'altres col·laboradors en el projecte, així com esmentar els marcs de treball que s'utilitzen a l'aplicació: AboutKDE i AboutPage.

Quant al KDE

Cada botó nou que hem creat en el pas anterior hauria d'obrir una pàgina nova. Podeu afegir pàgines noves instanciant-les com a Components i després utilitzant pageStack.layers.push() per a cada botó per a carregar aquesta pàgina en el Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

Això és realment! Tot el que cal és instanciar FormCard.AboutKDE. Hauríeu de veure una cosa així després de fer clic al botó AboutKDE:

Pàgina «Quant al»

L'AboutPage de l'aplicació és una mica més complexa, però encara és molt senzilla d'utilitzar.

Per a una pàgina «quant al» que faci servir el conjunt de dades de KAboutData::setApplicationData(aboutData); a main.cpp afegiu el següent al vostre Main.qml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 FormCard.AboutPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 }
 }
 }
 }
}

La pàgina «Quant al» de la nostra aplicació s'hauria de veure així:

Ús del JSON en lloc del KAboutData

En lloc de permetre que la pàgina «Quant al» rebi informació de KAboutData, és possible passar directament un objecte JSON. Encara haureu d'utilitzar QApplication::setWindowIcon() en el vostre main.cpp perquè es mostri la icona de l'aplicació.

Creeu una MyAboutPage.qml com aquesta:

import org.kde.kirigamiaddons.formcard as FormCard
import org.kde.about

FormCard.AboutPage {
 title: i18nc("@action:button", "About")
 aboutData: {
 "displayName" : "Addons Example",
 "productName" : "",
 "componentName" : "addonsexample",
 "shortDescription" : "This program shows how to use AboutKDE and AboutPage",
 "homepage" : "https://kde.org",
 "bugAddress" : "",
 "version" : "1.0",
 "otherText" : "Optional text shown in the About",
 "authors" : [
 {
 "name" : "John Doe",
 "task" : "Maintainer",
 "emailAddress" : "",
 "webAddress" : "",
 "ocsUsername" : ""
 }
 ],
 "credits" : [],
 "translators" : [],
 "licenses" : [
 {
 "name" : "GPL v3",
 "text" : "Long license text goes here",
 "spdx" : "GPL-3.0"
 }
 ],
 "copyrightStatement" : "© 2023",
 "desktopFileName" : ""
 }

}

I després ajusteu el Main.qml per a incloure la pàgina nova «quant al»:

L'objecte JSON principal conté les claus displayName, productName, homepage i així successivament. Les claus authors, credits, translators i licenses s'hi poden passar una matriu d'objectes. Els objectes passats a authors, credits i translators comparteixen les mateixes claus perquè es puguin mostrar cadascuna en la seva pròpia secció, mentre que licenses inclou les claus name, text i spdx per a cada llicència afegida, ja que no és estrany que el mateix projecte inclogui diverses llicències.

Aquestes claus són opcionals, però s'espera que una quantitat mínima raonable de claus faci que la vostra aplicació no tingui camps buits: displayName, version, description, homepage, copyrightStatement i authors. No obstant això, se us anima a omplir tantes claus com sigui possible.

Docs: Delegats de formularis a les pàgines de configuració

Mon, 01 Jan 0001 00:00:00 +0000

Heu après a afegir pàgines «Quant al» i «Quant al KDE» a l'aplicació. Ara podreu utilitzar els seus mateixos components interns per a crear les pàgines de configuració.

L'estructura del projecte s'hauria de veure així:

addonsexample
├── CMakeLists.txt
├── main.cpp
├── Main.qml
├── MyAboutPage.qml
└── SettingsPage.qml

Canvis necessaris

Canvieu el Main.qml per a incloure la pàgina nova Settings:

import QtQuick
import QtQuick.Layouts

import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

import org.kde.about 1.0

Kirigami.ApplicationWindow {
 id: root
 width: 600
 height: 700

 Component {
 id: aboutkde
 FormCard.AboutKDE {}
 }

 Component {
 id: aboutpage
 MyAboutPage {}
 }

 Component {
 id: settingspage
 SettingsPage {}
 }

 pageStack.initialPage: Kirigami.ScrollablePage {
 ColumnLayout {
 FormCard.FormCard {
 FormCard.FormButtonDelegate {
 id: aboutKDEButton
 icon.name: "kde"
 text: i18n("About KDE Page")
 onClicked: root.pageStack.layers.push(aboutkde)
 }

 FormCard.FormButtonDelegate {
 id: aboutPageButton
 icon.name: "applications-utilities"
 text: i18n("About Addons Example")
 onClicked: root.pageStack.layers.push(aboutpage)
 }

 FormCard.FormButtonDelegate {
 id: settingsButton
 icon.name: "settings-configure"
 text: i18n("Single Settings Page")
 onClicked: root.pageStack.layers.push(settingspage)
 }
 }
 }
 }
}

Ara podem començar a consultar els components que s'utilitzen per a crear la pàgina de Configuració: la Targeta de Formulari i els seus Delegats.

Delegats de Formularis

FormCard i FormCardPage

[FormCard.FormCard](https://api.kde.org/qml-org-kde-kirigamiaddons-formcard-formcard.html és el component principal que utilitzarem per a agrupar tots els seus components fills, els Delegats.

Hem utilitzat una targeta de formulari en la introducció dels complements del Kirigami abans. El seu propòsit principal és servir com a contenidor per a altres components alhora que segueix un color diferent del fons, de manera similar a un Kirigami.Card.

Crea un fitxer SettingsPage.qml nou:

import QtQuick
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormCard {
 // Aquí és on van tots els nostres delegats!
 }

 FormCard.FormCard {
 // Aquí és on van tots els nostres delegats!
 }
}

Com que estem creant un fitxer QML separat per a la nostra pàgina de Configuració, i com que necessitem preparar el desplaçament potencial a la nostra pàgina, utilitzem un FormCard.FormCardPage, que hereta Kirigami.ScrollablePage.

El més agradable de la pàgina de la targeta de formulari és que ve amb una disposició interna, de manera que no es necessita cap ColumnLayout addicional i els nostres delegats poden afegir-se directament a ella.

Note

És possible utilitzar delegats de FormCard directament amb un Kirigami.ScrollablePage, però en aquest cas haureu d'afegir les vostres pròpies disposicions.

FormHeader

Per a cada FormCard que vulgueu crear, podeu crear un FormHeader just abans. La capçalera utilitza text en negreta i es mostra just a sobre de la targeta de formulari.

import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 // Els nostres delegats van aquí...
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 // Els nostres delegats van aquí...
 }
}

FormTextDelegate i FormSectionText

Comencem de manera senzilla, amb text net.

FormSectionText senzillament afegeix un delegat fi que conté una etiqueta. FormTextDelegate té text i una descripció en gris.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 }
}

Afegim algun text fictici per a la hipotètica detecció del tema. Si volíem tenir una detecció real de l'esquema de color, en el futur es podria fer de manera similar al Neochat (codi aquí), fent ús d'un model de C++ amb el KColorSchemeManager.

A l'apartat Comptes Online, veiem un immoble addicional, leading. Es pot afegir un Item perquè aparegui abans del text. La seva propietat oposada, trailing, podria mostrar un element després del text, però no l'utilitzarem en el programa.

Fem servir un Kirigami.Icon aquí per a la simplicitat, però això també es podria implementar utilitzant un Avatar dels complements del Kirigami que captura la informació d'un model, com es fa al Neochat.

Hauria d'acabar veient-se així:

FormButtonDelegate

El FormButtonDelegate és visualment similar a un FormTextDelegate, però s'hi pot fer clic i mostra una fletxa que apunta cap a la dreta. L'hem utilitzat abans a la introducció dels complements del Kirigami.

Mentre que el FormTextDelegate tenia les propietats leading i trailing per a mostrar un element abans i després del contingut principal, el FormButtonDelegate només té la propietat leading, perquè el costat dret està ocupat per la fletxa.

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 FormCard.FormHeader {
 title: i18n("General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 }

 FormCard.FormHeader {
 title: i18n("Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18n("Online Account Settings")
 }
 FormCard.FormTextDelegate {
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18n("The Maintainer ™️")
 }
 FormCard.FormButtonDelegate {
 icon.name: "list-add"
 text: i18n("Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

Utilitzem la seva propietat icon.name per a establir una icona de més (+) que apareixerà després de l'espai on apareixerà el leading, i abans del contingut principal. Aquest és un patró comú per a indicar que el botó afegirà alguna cosa a una llista.

Com que aquest exemple és per a propòsits il·lustratius senzills, no aprofundim en el que es faria una vegada que es clica el botó: només imprimeix «Clicked!» al terminal. Podríem crear una pàgina nova per a la creació de comptes que afegeixi un altre usuari a un model i després empenyi la pàgina a la vista, de manera similar al que vam fer a Main.qml.

FormRadioDelegate, FormCheckDelegate i FormSwitchDelegate

El RadioButton, el CheckBox i el Switch són components molt utilitzats en qualsevol interfície d'usuari. Els complements del Kirigami els proporcionen com a FormRadioDelegate, FormCheckDelegate i FormSwitchDelegate.

Les seves úniques propietats principals són text i description. Són diferents en ús perquè tots hereten AbstractButton, i per tant s'espera que utilitzin els seus senyals i controladors: «checked» i «onChecked», «toggled» i «onToggled», «clicked» i «onClicked».

Volem crear alguna funcionalitat de desament automàtic a la nostra aplicació, i només volem mostrar la seva configuració si l'usuari ha habilitat aquesta funcionalitat. Creeu una secció nova utilitzant un FormCard i un FormHeader, després afegiu un FormSwitchDelegate i un FormRadioDelegate.

FormCard.FormHeader {
 title: i18n("Autosave")
}

FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18n("Enabled")
 }
 FormCard.FormRadioDelegate {
 text: i18n("After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18n("Every 30 minutes")
 visible: autosave.checked
 }
}

Vinculem la visibilitat de cada botó d'opció a un commutador, de manera que només apareixeran quan el commutador estigui habilitat.

Millors pràctiques

Feu clic aquí per a llegir-ne més

Si teniu algun coneixement de programació en llenguatges imperatius com C++, és possible que tingueu la temptació d'establir la propietat checked del commutador per a activar la visibilitat dels botons d'opció a true amb una assignació de JavaScript com:

checked: {
 radio1.visible = true;
 radio2.visible = true;
 radio3.visible = true;
}

Això no és molt eficient per al llenguatge declaratiu del QML i els seus senyals i ranures. Intenteu utilitzar les vinculacions del QML com en el cas de visible: autosave.checked tant com sigui possible en lloc d'expressions JavaScript.

Vegeu aquesta pàgina per als detalls.

Per a provar la nostra casella de selecció, podem afegir un FormCheckDelegate nou a la nostra secció General.

FormCard.FormHeader {
 title: i18n("General")
}

FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18n("Current Color Scheme")
 description: "Breeze"
 }
 FormCard.FormCheckDelegate {
 text: i18n("Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
}

Aquí utilitzem el manipulador de senyals anomenat onToggled per a mostrar text fictici per a simular una icona de safata que apareix en el sistema. Si realment voleu, podeu implementar fàcilment una icona de la safata utilitzant KStatusNotifierItem de KDE o SystemTrayIcon de les Qt.

Finalment, la nostra aplicació s'hauria de veure així:

FormComboBoxDelegate

El component ComboBox comú es pot crear utilitzant un FormComboBoxDelegate.

Aquest quadre combinat té diverses propietats útils que podem fer servir: editable, displayText i displayMode.

Establir editable: true permet a l'usuari editar el text del quadre combinat, el qual és útil en cas que es necessitin opcions noves del quadre combinat:

Sempre que necessiteu mostrar text addicional abans de cada opció, podeu utilitzar alguna cosa com displayText: "Profile: " + currentText:

I el més interessant, que utilitzarem en el nostre exemple, és displayMode. Pot tenir tres opcions:

FormComboBoxDelegate.ComboBox: el quadre petit estàndard que mostra una llista d'opcions.

FormComboBoxDelegate.Dialog: un diàleg que mostra una llista d'opcions al mig de la finestra, com un Kirigami.OverlaySheet.

FormComboBoxDelegate.Page: una pàgina nova que conté una llista d'opcions mostrades en una finestra separada.

Afegiu el següent entre els delegats de «Current Color Scheme» i «Show Tray Icon» a la targeta del formulari «General».

FormCard.FormComboBoxDelegate {
 text: i18n("Default Profile")
 description: i18n("The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
}

Amb la casella de selecció, la pàgina Configuració s'hauria de veure així:

FormDelegateSeparator

La nostra pàgina de configuració està prenent forma, però cada secció està començant a fer-se llarga. Podem afegir algunes instàncies de FormDelegateSeparators per a fer que la nostra pàgina sigui més ordenada:

import QtQuick
import org.kde.kirigami as Kirigami
import org.kde.kirigamiaddons.formcard as FormCard

FormCard.FormCardPage {
 id: root

 title: i18nc("@title", "Settings")

 FormCard.FormHeader {
 title: i18nc("@title:group", "General")
 }

 FormCard.FormCard {
 FormCard.FormTextDelegate {
 text: i18nc("@info", "Current Color Scheme")
 description: "Breeze"
 }

 FormCard.FormComboBoxDelegate {
 id: combobox
 text: i18nc("@label:listbox", "Default Profile")
 description: i18nc("@info:whatsthis", "The profile to be loaded by default.")
 displayMode: FormCard.FormComboBoxDelegate.ComboBox
 currentIndex: 0
 editable: false
 model: ["Work", "Personal"]
 }

 FormCard.FormDelegateSeparator {
 above: combobox
 below: checkbox
 }

 FormCard.FormCheckDelegate {
 id: checkbox
 text: i18nc("@option:check", "Show Tray Icon")
 onToggled: {
 if (checkState) {
 console.info("A tray icon appears on your system!")
 } else {
 console.info("The tray icon disappears!")
 }
 }
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Autosave")
 }

 FormCard.FormCard {
 FormCard.FormSwitchDelegate {
 id: autosave
 text: i18nc("@option:check", "Enabled")
 }
 FormCard.FormDelegateSeparator {
 above: autosave
 below: firstradio
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 id: firstradio
 text: i18nc("@option:radio", "After every change")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 10 minutes")
 visible: autosave.checked
 }
 FormCard.FormRadioDelegate {
 text: i18nc("@option:radio", "Every 30 minutes")
 visible: autosave.checked
 }
 }

 FormCard.FormHeader {
 title: i18nc("@title:group", "Accounts")
 }

 FormCard.FormCard {
 FormCard.FormSectionText {
 text: i18nc("@info:whatsthis", "Online Account Settings")
 }
 FormCard.FormTextDelegate {
 id: lastaccount
 leading: Kirigami.Icon {source: "user"}
 text: "John Doe"
 description: i18nc("@info:credit", "The Maintainer ™️")
 }
 FormCard.FormDelegateSeparator {
 above: lastaccount
 below: addaccount
 }
 FormCard.FormButtonDelegate {
 id: addaccount
 icon.name: "list-add"
 text: i18nc("@action:button", "Add a new account")
 onClicked: console.info("Clicked!")
 }
 }
}

Generalment, podeu utilitzar separadors sempre que veieu distincions importants entre components, encara que l'elecció d'on col·locar-los és en última instància vostra. Per exemple, a la secció General, la casella de selecció difereix dels seus components anteriors, ja que no comença per text; a la secció Desament automàtic, el separador agrupa els botons d'opció; i a la secció Comptes, afegir un separador entre l'últim compte i el botó proporciona algun focus addicional al botó.

Les propietats above i below són bastant autoexplicatives pel que fa al seu ús: es passa el id dels components per sobre i per sota del separador. Quan s'estableixin, el separador desapareixerà ràpidament cada vegada que es ressalti o es passi per sobre de l'element anterior o inferior. Són més útils, per exemple, quan necessiteu generar components dinàmicament i no podeu assumir automàticament quin element vindrà immediatament abans o després del separador. Aquest seria el cas a la secció de Comptes de la nostra aplicació una vegada que s'hagi implementat realment la lògica d'afegir comptes nous, i en aquest cas sempre podríem agafar l'últim element del model per a fer-ho.

Observeu com el separador que hi ha a sobre de la configuració de la icona de la safata no apareixerà mentre es passa per sobre.

Docs: Configuració al Windows

Mon, 01 Jan 0001 00:00:00 +0000

Introducció

Les Qt tenen un suport gran del Windows, i per tant les aplicacions que fan ús dels extra-cmake-modules de les Qt i KDE no requeriran moltes modificacions per a funcionar correctament al Windows.

Són necessàries 3 coses:

Un esquema de Craft
Configuració de l'estil Brisa
Icones empaquetades amb l'aplicació

L'esquema de Craft és necessari per a empaquetar totes les dependències juntament amb l'aplicació per a generar un executable.

La directiva de preprocessador #ifdef Q_OS_WIN es pot utilitzar per a escriure codi que només s'aplicarà quan l'aplicació estigui construïda en el Windows. Això és necessari almenys una vegada per a forçar l'estil Brisa a l'aplicació de manera que es vegi bé en el Windows, però depenent de l'aplicació pot requerir més.

Empaquetar les icones necessàries perquè l'aplicació funcioni en el Windows és el pas més complex, però tant els extra-cmake-modules (ECM) de KDE com les Qt proporcionen mitjans per a fer més fàcil aquesta feina.

Esquema de Craft

Per a començar, primer heu de seguir Construir el programari KDE al Windows amb Craft perquè obtingueu un esquema de Craft funcional i almenys pugueu construir la vostra aplicació al Windows.

Un cop pugueu construir el projecte, obtindreu errors de compilació i en temps d'execució que us ajudaran a corregir qualsevol problema de compatibilitat amb el Windows.

Estil Brisa

La guia d'aprenentatge del Kirigami ja hauria de ser majoritàriament compatible amb el Windows, però els passos necessaris per aconseguir-ho han de ser explícits.

Les dues modificacions que s'han de fer per assegurar que s'utilitza l'estil Brisa és establir el QStyle a breeze i establir l'estil dels Qt Quick Controls a org.kde.desktop.

Un QStyle és el que controla la majoria de l'aparença d'una aplicació QtWidgets. Això és necessari a la nostra aplicació QtQuick perquè inicialitzem l'aplicació amb QApplication (tradicionalment usada amb QtWidgets).

D'altra banda, un estil dels Qt Quick Controls controla la majoria de l'aparença d'una aplicació QtQuick. Això afecta com es veuran els controls QML. L'estil de KDE org.kde.desktop (altrament conegut com a qqc2-desktop-style) és especial i intenta eliminar la duplicació derivant elements estilístics del QStyle de l'aplicació (per això s'utilitza una QApplication). D'aquesta manera, les aplicacions QtWidgets i QtQuick poden veure's majoritàriament de la mateixa manera i reutilitzar components d'estil.

Les aplicacions QtQuick / Kirigami necessiten establir-ho en el codi C++. Per establir el QStyle, s'ha d'afegir en dos llocs.

En Craft:

def setDependencies(self):
 self.runtimeDependencies["kde/plasma/breeze"] = None

I en C++:

QApplication::setStyle("breeze");

Això és el que s'utilitza a la guia d'aprenentatge del Kirigami. Altrament, podeu carregar l'estil Brisa només al Windows, on això és més rellevant utilitzant un «ifdef»:

#ifdef Q_OS_WIN
 QApplication::setStyle("breeze");
#endif

L'estil Qt Quick Controls s'ha d'afegir en tres llocs.

En Craft:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None

En C++, on cal que sigui condicional:

if (qEnvironmentVariableIsEmpty("QT_QUICK_CONTROLS_STYLE"))
{
 QQuickStyle::setStyle("org.kde.desktop");
}

I opcionalment en el CMake, d'una entre dues maneres:

find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)
# or
ecm_find_qmlmodule(org.kde.desktop REQUIRED)

Com que és una dependència en temps d'execució, no cal establir-la al CMake que s'utilitza en temps de compilació. Tanmateix, això pot indicar a si mateix i als altres si l'entorn és correcte i serà capaç d'executar l'aplicació resultant, cosa que permet trobar amb més facilitat els paquets que falten o les configuracions errònies.

L'ordre find_package() cerca específicament qqc2-desktop-style als fitxers de configuració del CMake, mentre que ecm_find_qmlmodule() és menys estricte i només cerca el mòdul QML. Aquest últim requereix que inclogueu ECMFindQmlModule:

include(ECMFindQmlModule)

Distribució d'icones

El primer que cal per a fer que l'aplicació utilitzi les icones Brisa és incloure KIconThemes en el projecte.

Després d'això, es necessiten algunes ordres del CMake per afegir la icona de l'aplicació a l'aplicació.

KIconThemes

Això es pot fer amb els tres passos següents:

Afegir-la com a dependència al Craft:

def setDependencies(self):
 self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None

Afegir-la com a dependència al CMake:

find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
 PRIVATE
 # ...
 KF6::IconThemes
)

Usant-la al codi C++, en el fitxer main.cpp:

#include <KIconTheme>

// ...
int main(int argc, char* argv[])
{
 KIconTheme::initTheme();
 QApplication app(argc, argv);
 // ...
}

Tingueu en compte que encara que el nom del projecte i la crida al CMake fan servir el plural (KIconThemes, KF6IconThemes), la crida C++ fa servir el singular (KIconTheme).

Cal inicialitzar KIconThemes abans de l'aplicació.

Icona de l'aplicació

Si l'aplicació té una icona, s'ha d'afegir al vostre projecte tant com un recurs QML i com a part de la instal·lació d'icones.

Habitualment al Linux, la icona de l'aplicació es pot instal·lar al directori correcte, i l'aplicació recuperarà la icona quan sigui necessari. Normalment, la icona de l'aplicació consisteix en una icona SVG primària, aparellada amb diverses mides d'icones PNG.

La instal·lació de la icona SVG es fa així en el CMake:

install(FILES ${PROJECT_SOURCE_DIR}/icons/org.kde.myapp.svg DESTINATION ${KDE_INSTALL_FULL_ICONDIR}/hicolor/scalable/apps)

I la instal·lació de les icones PNG es fa així:

ecm_install_icons(ICONS
 16-apps-myapp.png
 24-apps-myapp.png
 32-apps-myapp.png
 48-apps-myapp.png
 64-apps-myapp.png
 128-apps-myapp.png
 256-apps-myapp.png
 512-apps-myapp.png
 DESTINATION share/icons)

Quan s'instal·la la icona de l'aplicació al Linux, una icona PNG com 48-apps-myapp.png goes to ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png, i una icona SVG va a ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, on ${INSTALL_PREFIX} normalment significa /usr, /usr/local o ~/.local. Tingueu en compte com en el cas dels PNG que el nom de la icona es tradueix al camí que tindrà en el sistema de fitxers.

Podeu llegir més sobre la instal·lació de fitxers a Construir manualment el programari de KDE: El pas d'instal·lació.

Una vegada instal·lada la icona d'aquesta manera, en codi QML, es pot cridar simplement amb myapp o org.kde.myapp, com es cridaria des de QIcon::fromTheme(). Això es pot utilitzar amb qualsevol control QML que tingui una propietat icon.name.

El Windows no té aquest directori estàndard, i la instal·lació de la icona no té cap efecte; s'ha d'empaquetar amb l'aplicació. Per a fer-ho, el PNG es pot enviar al seu propi directori d'instal·lació utilitzant ecm_add_app_icon() i un fitxer PNG o SVG es pot incrustar a l'aplicació com un fitxer de recursos Qt a ecm_add_qml_module() o ecm_target_qml_sources().

La icona de l'aplicació PNG s'instal·la amb:

ecm_add_app_icon(myapp ICONS ${PROJECT_SOURCE_DIR}/icons/256-apps-myapp.png)

I la icona principal de l'aplicació s'empaqueta com a recurs Qt amb:

ecm_add_qml_module(myapp URI org.kde.myapp)
ecm_target_qml_sources(myapp SOURCES Main.qml RESOURCES ../icons/org.kde.myapp.svg)

Això farà que la icona de l'aplicació estigui disponible com a recurs Qt a qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Això es pot utilitzar amb qualsevol control QML que tingui una propietat icon.source.

El camí RESOURCES depèn del lloc on es trobin les icones. Tradicionalment, es crea una carpeta icons/ a l'arrel del projecte per a emmagatzemar totes les icones, ja que realment no compten com a fitxers de codi font.

Després d'instal·lar les icones (per al Linux) i empaquetades (per al Windows i l'Android), podeu definir-les al codi. Al codi QML, per a la compatibilitat amb el Windows i l'Android, hauríeu d'utilitzar la icona empaquetada; en el codi C++, especialment quan establiu la icona de la finestra, podeu utilitzar la icona del tema predeterminat i la icona empaquetada com a alternativa amb QIcon::fromTheme() a la crida a QGuiApplication::setWindowIcon():

QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));

Icones del Kirigami

Tot i que el Windows no té un directori estàndard on instal·lar icones des d'un tema d'icones, és possible afegir les icones Brisa necessàries juntament amb la vostra aplicació Windows.

Això ho fa el Craft automàticament quan KIconThemes està configurat correctament per al projecte i les icones Breeze s'inclouen com a dependència en el projecte.

Per a configurar KIconThemes, vegeu la secció anterior KIconThemes.

Per a afegir les icones Brisa com a dependència del vostre projecte, afegiu-ho al vostre esquema de Craft:

def setDependencies(self):
 # ...
 self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = None

D'aquesta manera, no necessitareu empaquetar manualment cap icona del Brisa a la vostra aplicació com a recurs: podeu utilitzar un nom QIcon::fromTheme(), com ara kde o application-exit-symbolic.

Construcció

Per a construir la vostra aplicació al Windows, seguiu Construir el programari KDE al Windows amb Craft: Construcció dels projectes propis al Windows.

Construccions de CI

Si el projecte s'ha configurat correctament per a construir al Windows i està utilitzant la infraestructura KDE per al seu allotjament de codi (KDE Invent), és possible configurar els treballs CI/CD del Windows.

Per a fer-ho, haureu d'afegir les plantilles CI rellevants del Windows amb un fitxer .gitlab-ci.yaml i llistar les vostres dependències en un fitxer .kde-ci.yaml com s'ha esmentat al Sistema d'integració contínua.

Solució de problemes

Si teniu problemes per a adaptar la vostra aplicació al Windows, podeu visitar les sales següents a Matrix: