Skip to main content
Gå till innehåll
Redigera sidan See source code Skapa dokumentationsfelrapport Formatting guidelines Style guidelines

Inställning för Windows

Förbereda C++ programmet för Windows

Inledning

Qt har utmärkt Windows-stöd, så program som använder Qt och KDE:s extra-cmake-modules kräver inte många modifieringar för att fungera korrekt på Windows.

Tre saker behövs:

En Craft-plan behövs för att paketera alla beroenden tillsammans med programmet för att generera en körbar fil.

Preprocessordirektivet #ifdef Q_OS_WIN kan användas för att skriva kod som bara gäller när programmet är byggd på Windows. Det behövs minst en gång för att tvinga programmet att använda Breeze-stilen så att det ser bra ut på Windows, men beroende på programmet kan det kräva mer.

Att samla de nödvändiga ikonerna för att programmet ska fungera på Windows är det mest komplexa steget, men både KDE:s extra-cmake-moduler (ECM) och Qt tillhandahåller sätt att göra det här jobbet enklare.

Craft-plan

För att komma igång måste du först följa Building KDE software on Windows with Craft så att du får en fungerande Craft-plan och åtminstone kan bygga programmet på Windows.

När du väl har kunnat bygga projektet får du kompilerings- och körfel som hjälper dig att åtgärda eventuella kompatibilitetsproblem med Windows.

Breeze-stil

Kirigami-handledningen borde redan vara i stort sett kompatibel med Windows, men stegen som behövs för att uppnå det behöver tydliggöras.

De två modifieringar som bör göras för att säkerställa att Breeze-stilen används är att ställa in QStyle till breeze och att ställa in Qt Quick Controls-stilen till org.kde.desktop.

En QStyle är det som styr majoriteten av utseendet på en för ett program med QtWidgets. Det behövs i vårt QtQuick-program eftersom vi initierar programmet med QApplication (traditionellt använt med QtWidgets).

En Qt Quick kontrollstil styr å andra sidan majoriteten av utseendet på ett QtQuick-program. Det påverkar hur QML-kontrollerna kommer att se ut. KDE:s stil org.kde.desktop(även känd som qqc2-desktop-style) är speciell och försöker ta bort dubbelarbete genom att härleda stilelement från programmets QStyle (vilket är orsaken att QApplication används). På så sätt kan QtWidgets och QtQuick-program i stort sett se likadana ut och återanvända stilkomponenter.

QtQuick/Kirigami-program behöver ange båda i C++ kod. För att ange QStyle måste den läggas till på två ställen.

I Craft:

def setDependencies(self):
    self.runtimeDependencies["kde/plasma/breeze"] = None

Och i C++:

QApplication::setStyle("breeze");

Det är vad som används i Kirigami-handledningen. Du kan annars bara ladda Breeze-stilen i Windows där det är mest relevant med hjälp av en ifdef:

#ifdef Q_OS_WIN
    QApplication::setStyle("breeze");
#endif

Qt Quick kontrollstilen behöver läggas till på tre ställen.

I Craft:

def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/qqc2-desktop-style"] = None

I C++, där den måste vara villkorligt:

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

Och valfritt i CMake, på ett av två sätt:

find_package(KF6 REQUIRED COMPONENTS QQC2DesktopStyle)
# or
ecm_find_qmlmodule(org.kde.desktop REQUIRED)

Eftersom det är ett körtidsberoende behöver det inte anges i CMake, som används vid kompilering. Det kan dock signalera till dig själv och andra om miljön är korrekt och att den resulterande programmet kan köras, vilket gör att du lättare kan hitta saknade paket eller felaktiga konfigurationer.

Kommandot find_package() söker specifikt efter CMake-konfigurationsfiler för qqc2-desktop-style, medan ecm_find_qmlmodule() är mindre strikt och söker bara efter QML-modulen. Den senare kräver att du inkluderar ECMFindQmlModule:

include(ECMFindQmlModule)

Leverera ikoner

Det första som behövs för att programmet ska använda Breeze-ikoner är att inkludera KIconThemes i projektet.

Efter det behövs några CMake-kommandon för att paketera programikonen med programmet.

KIconThemes

Det kan göras med följande tre steg:

  • Lägga till det som ett beroende i Craft:
def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None
  • Lägga till det som ett beroende i CMake:
find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
    PRIVATE
    # ...
    KF6::IconThemes
)
  • Använda det i C++ kod, i filen main.cpp:
#include <KIconTheme>

// ...
int main(int argc, char* argv[])
{
    KIconTheme::initTheme();
    QApplication app(argc, argv);
    // ...
}

Observera att även om projektnamnet och anropet till CMake använder pluralis (KIconThemes, KF6IconThemes), använder anropet till C++ singularis (KIconTheme).

KIconThemes måste initialiseras före programmet.

Programikon

Om programmet har en ikon måste den läggas till i projektet både som en QML-resurs och som en del av ikoninstallationen.

Vanligtvis kan programikonen på Linux enkelt installeras i rätt katalog, och ikonen hämtas av programmet när den behövs. Vanligtvis består programikonen av en primär SVG-ikon, parad med flera PNG-ikonstorlekar.

Installation av SVG-ikonen görs så här i CMake:

install(FILES ${PROJECT_SOURCE_DIR}/icons/org.kde.myapp.svg DESTINATION ${KDE_INSTALL_FULL_ICONDIR}/hicolor/scalable/apps)

Och installation av PNG-ikonerna görs så här:

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)

När programikonen är installerad på Linux, placeras en PNG-ikon såsom 48-apps-myapp.png i ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png, och en SVG-ikon placeras i ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, där ${INSTALL_PREFIX} oftast står för /usr, /usr/local eller ~/.local. Observera hur ikonnamnet i PNG-fallet översätts till den sökväg den har i filsystemet.

Du kan läsa mer om att installera filer i Bygga KDE-programvara manuellt: Installationssteget.

När ikonen är installerad på det sättet, kan den enkelt anropas med myapp eller org.kde.myapp i QML-kod, precis som den skulle anropas från QIcon::fromTheme(). Det kan användas med vilken QML-kontroll som helst som har egenskapen icon.name.

Windows har ingen sådan standardkatalog, och installation av ikonen har ingen effekt. Den måste paketeras med programmet. För att göra det kan PNG-filen skickas till en egen installationskatalog med hjälp av ecm_add_app_icon() och en PNG- eller SVG-fil kan inbäddas i programmet som en Qt-resursfil i ecm_add_qml_module() eller ecm_target_qml_sources().

PNG-programikonen installeras med:

ecm_add_app_icon(myapp ICONS ${PROJECT_SOURCE_DIR}/icons/256-apps-myapp.png)

Och huvudprogrammets ikon är paketerad som en Qt-resurs med:

ecm_add_qml_module(myapp URI org.kde.myapp)
ecm_target_qml_sources(myapp SOURCES Main.qml RESOURCES ../icons/org.kde.myapp.svg)

Det gör programikonen tillgänglig som en Qt-resurs under qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Det kan användas med vilken QML-kontroll som helst som har egenskapen icon.source.

The RESOURCES path depends on the place where the icons are located. Traditionally, an icons/ folder is created at the root of the project for storing all icons, as they don't really count as source files.

After the icons are installed (for Linux) and bundled (for Windows and Android), you can set it in code. In QML code, for compatibility with both Windows and Android, you should use the bundled icon; in C++ code, notably when setting the window icon, you can use the theme icon by default and the bundled icon as a fallback with QIcon::fromTheme() in the call to QGuiApplication::setWindowIcon():

QGuiApplication::setWindowIcon(QIcon::fromTheme("org.kde.myapp", QIcon(":/qt/qml/org/kde/myapp/org.kde.myapp.svg")));

Kirigami-ikoner

While Windows does not have a standard directory where to install icons from an icon theme, it is possible to bundle the necessary Breeze icons together with your Windows application.

This is performed by Craft automatically when KIconThemes is correctly set up for the project and Breeze icons are included as a dependency in your project.

To set up KIconThemes, see the above section KIconThemes.

För att lägga till Breeze-ikoner som ett beroende i projektet, lägg till det i Craft-planen:

def setDependencies(self):
    # ...
    self.runtimeDependencies["kde/frameworks/tier1/breeze-icons"] = None

This way, you won't need to manually bundle any Breeze icons into your application as a resource: you can just use a QIcon::fromTheme() name, such as kde or application-exit-symbolic.

Bygga

To build your application on Windows, follow Building KDE software on Windows with Craft: Building your own projects on Windows.

Qt-byggen

If the project has been properly configured to build on Windows and is using KDE infrastructure for its code hosting (KDE Invent), it is possible to configure Windows CI/CD jobs.

To do this, you will need to add the relevant CI templates for Windows with a .gitlab-ci.yaml file and list your dependencies in a .kde-ci.yaml file as mentioned in Continuous Integration System.

Felsökning

If you have problems adapting your application to Windows, you can visit the following rooms on Matrix:

Previous
Formulärdelegater på inställningssidorna