Skip to main content
Ir para o conteúdo
Editar esta página See source code Criar um bug sobre a documentação Formatting guidelines Style guidelines

Configuração no Windows

Preparando sua aplicação C++ para Windows

Introdução

O Qt tem ótimo suporte para Windows, portanto, os aplicativos que usam Qt e os módulos extras do KDE (extra-cmake-modules) não precisarão de muitas modificações para funcionar corretamente no Windows.

São necessárias três coisas:

O blueprint Craft é necessário para agrupar todas as dependências com o aplicativo para gerar um executável.

A diretiva de pré-processador #ifdef Q_OS_WIN pode ser usada para escrever código que só será aplicado quando o aplicativo for compilado no Windows. Isso é necessário pelo menos uma vez para forçar o estilo Breeze ao aplicativo para que ele tenha uma boa aparência no Windows, mas dependendo do aplicativo, pode ser necessário mais vezes.

Incluir os ícones necessários para o aplicativo funcionar no Windows é a etapa mais complexa, mas tanto os módulos extras do CMake (ECM) do KDE quanto o Qt fornecem meios para facilitar esse trabalho.

Blueprint Craft

Para começar, você deve primeiro seguir Compilando software KDE no Windows com o Craft para obter um blueprint ou modelo funcional do Craft e poder pelo menos compilar seu aplicativo no Windows.

Assim que você conseguir compilar o projeto, você receberá erros de compilação e de tempo de execução que o ajudarão a corrigir quaisquer problemas de compatibilidade com o Windows.

Estilo Breeze

O tutorial de Kirigami já deve ser em grande parte compatível com o Windows, mas os passos necessários para alcançar isso precisam ser explicitados.

As duas modificações que devem ser feitas para garantir que o estilo Breeze seja usado são: definir o QStyle como breeze e definir o estilo do Qt Quick Controls como org.kde.desktop.

Um QStyle é o que controla a maior parte da aparência de um aplicativo QtWidgets. Isso é necessário em nosso aplicativo QtQuick porque inicializamos o aplicativo com QApplication (tradicionalmente usado com QtWidgets).

Um estilo de controles Qt Quick, por outro lado, controla a maior parte da aparência de um aplicativo Qt Quick. Isso afeta a aparência dos controles QML. O estilo org.kde.desktop do KDE (também conhecido como qqc2-desktop-style) é especial e tenta remover a duplicação derivando elementos de estilo do QStyle do aplicativo (por isso um QApplication é usado). Dessa forma, os QtWidgets e os aplicativos Qt Quick podem ter uma aparência muito semelhante e reutilizar componentes de estilo.

Os aplicativos QtQuick / Kirigami precisam ser configurados em código C++. Para definir o QStyle, ele precisa ser adicionado em dois lugares.

No Craft:

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

E no C++:

QApplication::setStyle("breeze");

Este é o estilo usado no tutorial de Kirigami. Você também pode carregar o estilo Breeze apenas no Windows, onde isso é mais relevante, usando um ifdef:

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

O estilo Qt Quick Controls precisa ser adicionado em três locais.

No Craft:

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

Em C++, onde é necessário que seja condicional:

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

E opcionalmente no CMake, de uma das duas maneiras a seguir:

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

Como se trata de uma dependência de tempo de execução, não é necessário configurá-la no CMake, que é usado em tempo de compilação. No entanto, isso pode sinalizar para você e para outros se o ambiente está correto e será capaz de executar o aplicativo resultante, permitindo que você encontre pacotes ausentes ou configurações incorretas com mais facilidade.

O comando find_package() procura especificamente pelos arquivos de configuração do CMake para qqc2-desktop-style, enquanto ecm_find_qmlmodule() é menos restritivo e procura apenas pelo módulo QML. Este último requer que você inclua o ECMFindQmlModule:

include(ECMFindQmlModule)

Empacotando os ícones

A primeira coisa necessária para que o aplicativo use os ícones do Breeze é incluir KIconThemes em seu projeto.

Depois disso, alguns comandos CMake são necessários para incluir o ícone do seu aplicativo no pacote do app.

KIconThemes

Isso pode ser feito seguindo estes três passos:

  • Adicionando-o como uma dependência no Craft:
def setDependencies(self):
    self.runtimeDependencies["kde/frameworks/tier3/kiconthemes"] = None
  • Adicionando-o como uma dependência no CMake:
find_package(KF6 REQUIRED COMPONENTS IconThemes)

# ...

target_link_libraries(myapp
    PRIVATE
    # ...
    KF6::IconThemes
)
  • Utilizando-o em código C++, no arquivo main.cpp:
#include <KIconTheme>

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

Observe que, embora o nome do projeto e a chamada do CMake usem o plural (KIconThemes, KF6IconThemes), a chamada do C++ usa o singular (KIconTheme).

O KIconThemes precisa ser inicializado antes da aplicação.

Ícone do aplicativo

Se o seu aplicativo tiver um ícone, ele precisa ser adicionado ao seu projeto tanto como um recurso QML quanto como parte da instalação do ícone.

Normalmente, no Linux, o ícone do aplicativo pode ser simplesmente instalado no diretório correto e será buscado pelo aplicativo quando necessário. Geralmente, o ícone do aplicativo consiste em um ícone SVG principal, combinado com vários tamanhos de ícones PNG.

A instalação do ícone SVG é feita da seguinte forma no CMake:

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

E a instalação dos ícones PNG é feita da seguinte forma:

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)

Quando o ícone do aplicativo é instalado no Linux, um ícone PNG como 48-apps-myapp.png é instalado em ${INSTALL_PREFIX}/share/icons/hicolor/48x48/apps/myapp.png, e um ícone SVG é instalado em ${INSTALL_PREFIX}/share/icons/hicolor/scalable/apps/org.kde.myapp.svg, onde ${INSTALL_PREFIX} geralmente representa /usr, /usr/local ou ~/.local. Observe como, no caso dos PNGs, o nome do ícone se traduz no caminho que ele terá no sistema de arquivos.

Você pode ler mais sobre a instalação de arquivos em Compilando o software KDE manualmente: A etapa de instalação.

Uma vez que o ícone esteja instalado desta forma, no código QML, ele pode ser chamado simplesmente com myapp ou org.kde.myapp, como seria chamado de QIcon::fromTheme(). Isso pode ser usado com qualquer controle QML que tenha uma propriedade icon.name.

O Windows não possui um diretório padrão como esse, e instalar o ícone não tem efeito; ele precisa ser incluído no aplicativo. Para isso, o PNG pode ser enviado para seu próprio diretório de instalação usando ecm_add_app_icon() e um arquivo PNG ou SVG pode ser incorporado ao aplicativo como um arquivo de recurso Qt em ecm_add_qml_module() ou ecm_target_qml_sources().

O ícone PNG do aplicativo é instalado com:

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

E o ícone principal do aplicativo é incluído como um recurso Qt com:

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

Isso tornará o ícone do aplicativo disponível como um recurso Qt em qrc:/qt/qml/org/kde/myapp/org.kde.myapp.svg. Isso pode ser usado com qualquer controle QML que tenha uma propriedade icon.source.

O caminho RESOURCES depende do local onde os ícones estão armazenados. Tradicionalmente, uma pasta icons/ é criada na raiz do projeto para armazenar todos os ícones, já que eles não são considerados arquivos de fonte.

Após os ícones serem instalados (para Linux) e empacotados (para Windows e Android), você pode defini-los no código. No código QML, para compatibilidade com Windows e Android, você deve usar o ícone empacotado; no código C++, principalmente ao definir o ícone da janela, você pode usar o ícone do tema por padrão e o ícone empacotado como alternativa com QIcon::fromTheme() na chamada para QGuiApplication::setWindowIcon():

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

Ícones do Kirigami

Embora o Windows não tenha um diretório padrão para instalar ícones de um tema de ícones, é possível incluir os ícones Breeze necessários junto com seu aplicativo Windows.

Isso é feito automaticamente pelo Craft quando o KIconThemes está configurado corretamente para o projeto e os ícones do Breeze estão incluídos como uma dependência no seu projeto.

Para configurar os temas KIconThemes, consulte a seção acima KIconThemes.

Para adicionar os ícones do Breeze como uma dependência do seu projeto, adicione isto ao seu blueprint do Craft:

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

Dessa forma, você não precisará incluir manualmente nenhum ícone do Breeze em seu aplicativo como um recurso: você pode simplesmente usar um nome QIcon::fromTheme(), como kde ou application-exit-symbolic.

Compilação

Para criar seu aplicativo no Windows, siga Criando software KDE no Windows com Craft: Criando seus próprios projetos no Windows.

Compilações CI

Se o projeto foi configurado corretamente para compilar no Windows e está usando a infraestrutura do KDE para hospedagem de código (KDE Invent), é possível configurar tarefas de CI/CD para Windows.

Para fazer isso, você precisará adicionar os modelos de CI relevantes para Windows com um arquivo .gitlab-ci.yaml e listar suas dependências em um arquivo .kde-ci.yaml, como mencionado em Sistema de Integração Contínua.

Solução de problemas

Se você tiver problemas para adaptar seu aplicativo ao Windows, pode visitar as seguintes salas no Matrix:

Previous
Formulário delegados em suas páginas de configurações