出自 Arch Linux 中文维基

Qt 是一個跨平台的應用程式和圖形組件工具包,它使用標準C++,但同時對C++作出了功能拓展,通過使用特別的代碼生成器(稱為 Meta Object Compiler ,元對象編譯器,簡稱 moc )以及數個宏來擴展語言的功能。它還包括以下幾個更重要的特性:

  • 支持各種主流桌面平台和部分手機平台。
  • 完善的國際化支持。
  • 提供 SQL 數據訪問、XML 解析、線程管理、網絡支持和統一的跨平台的文件處理API。

Qt 框架是 KDE 軟體社區和其它一些重要開源和閉源應用的基石,例如 VLCVirtualBoxMathematica 等等。

安裝

可以從官方倉庫安裝 Qt 6.x 和 5.x 。舊版本的Qt (4.x 和 3.x)可以從 AUR 安裝。具體通過如下的軟體包安裝

默認 Qt 庫

安裝 qtchooserAUR 可以改變 /usr/bin Qt二進位文件(例如, qmake )的指向(它們默認指向Qt5版本的程序,例如 qmake-qt5 ),讓它們指向舊版本的程序(例如,qmake-qt4 或者 qmake-qt3 )。

注意: 現在 qtchooserAURqt5-base 相衝突,可以自行編譯並安裝到/usr/local。Arch 官方不支持這種方式FS#51308

修改環境變量

可以通過 QT_SELECT 環境變量 設置默認的 QT. 例如要使用 Qt4,可以設置 export QT_SELECT=4

使用配置文件

創建 ~/.config/qtchooser/default.conf 軟連結,連結到/etc/xdg/qtchooser/目錄中需要的 .conf 文件上。例如要使用 Qt4,將 /etc/xdg/qtchooser/4.conf 軟連結到 ~/.config/qtchooser/default.conf

$ ln -s /etc/xdg/qtchooser/4.conf ~/.config/qtchooser/default.conf

配置

Qt5 樣式

Qt5基於當前使用的桌面環境來決定所使用的樣式:

  • 在 KDE Plasma 桌面環境中,呈現實際選擇的Qt風格。可以在 KDE System Settingssystemsettings )中更改,這項設置的具體位置是 外觀 > 應用程式風格
  • 在 Cinnamon、GNOME、MATE、LXDE、Xfce 等桌面環境中,呈現GTK風格 (QGtkStyle)。
  • 在其他桌面環境中,呈現 Fusion 風格。

如果要強制指定一種樣式,你可以設置 QT_STYLE_OVERRIDE 環境變量。特別的,如果你想要使用GTK主題,把它設置成gtk2(注意:你將需要安裝在下文中提到的Qt樣式插件來獲取GTK樣式)。Qt5應用同時也支持-style標誌,你可以用它來使用指定的樣式運行一個Qt5應用程式。

Qt5中自帶兩種樣式: FusionWindows。其他的可以通過官方倉庫安裝:

  • Breeze — 來自Plasma桌面的Breeze視覺樣式,包括了繪畫、樣式和素材。
https://invent.kde.org/plasma/breeze || breeze
  • Oxygen — KDE 的 Oxygen 輕氧風格。
https://invent.kde.org/plasma/oxygen || oxygen
  • Lightly — Lightly是breeze主題的fork,它致力於現代風和極簡風格。
https://github.com/Luwx/Lightly || lightly-gitAUR
  • QtCurve — 為KDE和Gtk編寫的可配置的小部件樣式。
https://invent.kde.org/system/qtcurve || qtcurve-qt5
  • Adwaita-Qt — 讓Qt應用程式看上去有GNOME風格。
https://github.com/MartinBriza/adwaita-qt || adwaita-qt5
  • Qt style plugins — Qt 5的附加樣式,包含了 GTKCleanlooksMotifPlastique
https://code.qt.io/cgit/qt/qtstyleplugins.git || qt5-stylepluginsAUR
  • Kvantum — 可定製的基於 SVG 的主題引擎,具有多種內置樣式,包括對一些流行的 GTK 主題的模仿,例如 AdaptaArcAmbiance
https://github.com/tsujan/Kvantum/tree/master/Kvantum || kvantum

Qt4 樣式

Qt4 應用程式會嘗試模仿所運行的桌面環境的行為,除非碰到了某些問題或者進行了強制配置。

  • 在 KDE Plasma 桌面環境中,呈現實際選擇的Qt風格。可以在 KDE System Settingssystemsettings )中更改,這項設置的具體位置是 外觀 > 應用程式風格
  • 在 Cinnamon、GNOME、Xfce 等桌面環境中,呈現GTK風格 (QGtkStyle)。
  • 在其他桌面環境中,呈現 Windows 風格。

要修改 Qt4 程序的外觀,可以使用 qt4AUR 提供的 Qt 配置工具qtconfig-qt4。這個程序可以配置 Qt4 程序的樣式、顏色、字體等。

注意: 如果使用 GTK 樣式,將忽略顏色和字體設置,直接使用 GTK2 的值。

Qt將所有的配置信息保存在/etc/xdg/Trolltech.conf (系統級別) 或者 ~/.config/Trolltech.conf (只適用於特定用戶)。這個文件很難瀏覽,因為它還包含許多與外觀無關的信息,但是要更改它,您只需添加到文件末尾並覆蓋任何以前的值(注意要把修改添加在[Qt]標題下)。

例如要將主題更改為 QtCurve,請添加:

~/.config/Trolltech.conf
...
[Qt]
style=QtCurve

Qt4 已經包含數種樣式,例如 GTK 樣式、Windows 樣式、CDE 樣式等,其它的主題(大多數為 KDE Plasma 桌面編寫)可以從官方源或者 AUR 中安裝:

Qt4 自帶這些樣式: CDECleanlooksGTKMotifPlastiqueWindows。其它的主題(大多數為 KDE Plasma 桌面編寫)可以單獨安裝:

  • Breeze — 來自Plasma桌面的Breeze視覺樣式,包括了繪畫、樣式和素材。
https://invent.kde.org/plasma/breeze || breeze-kde4AUR
  • Adwaita-Qt — 讓Qt應用程式看上去有GNOME風格。
https://github.com/MartinBriza/adwaita-qt || adwaita-qt4AUR

Qt 樣式表

定製Qt程序的外觀有一個有趣的方式,那就是通過Qt樣式表,它們只是簡單的CSS文件而已。通過樣式表,你可以修改程序中所有組件的外觀。

想要用不同的風格運行程序,只需要執行:

$ qt_application -stylesheet style.qss

要了解關於Qt樣式表的更多信息,請瀏覽 官方文檔 或者其他的 教程。Qt樣式表的示例:修改Dolphin的外觀

GTK+ 和 Qt

如果你有 GTK 和 Qt 應用程式,它們的外觀可能無法融合到一起。如果你希望使 GTK 風格與 Qt 風格匹配,請閱讀 統一 GTK 和 Qt 應用程式外觀.

在KDE Plasma以外的環境下配置Qt5應用程式

不像Qt4,Qt5並沒有提供一個qtconfig實用程序來配置字體、圖標或者風格。相應的,它會嘗試使用桌面環境提供的配置。在KDE Plasma和GNOME下這個功能運行的很好,但對於其他的比較小眾的桌面環境或者窗口管理器而言,這可能導致Qt5程序缺少圖標。解決方案之一是通過設置變量 XDG_CURRENT_DESKTOP=KDEGNOME來假裝當前運行著的桌面環境,然後再使用相應的配置程序來配置想要的圖標。

另一個解決方案是安裝 qt5ct,它提供了一個獨立於桌面環境的 Qt5 QPA 和一個配置實用程序。安裝完成後,運行 qt5ct 以設置圖標主題,然後修改 環境變量 QT_QPA_PLATFORMTHEME=qt5ct,這樣做出的配置才會被Qt程序讀取。或者不修改環境變量,使用 --platformtheme qt5ct 作為Qt5程序的參數也可以達到目的。

qt5ct-kdeAUR 提供了一個修改過的 qt5ct,它更好的整合了KDE程序,包括KDE QML 程序。

如果遇到了下列錯誤,並且一些圖標依然不在一些應用程式中出現,安裝oxygenoxygen-icons

Icon theme "oxygen" not found.
Icon theme "oxygen" not found.
Error: standard icon theme "oxygen" not found!

開發

支持的平台

Qt支持如今的絕大多數平台,甚至包括一些十分冷門的平台,而且每隔一段時間就會出現更多的移植。更加完整的平台列表請查閱 維基百科上的Qt

Android

注意: Qt Creator 4.12或更高版本可以自動設置SDK工具、NDK和必要的軟體包。有關更多信息,請參閱Qt Creator:指定Android設備設置

首先從 AUR 或使用 Android Studio 安裝一個 Android SDK 和 NDK。

SDK 也需要 OpenJDK,版本要求也有不同,請查閱 這裡

接下來你需要安裝Qt 5 for Android。你可以按下面描述的包從 AUR 安裝,也可以自行構建。構建需要用到的命令可以從 Qt wiki 找到。

如果遇到了問題,你可以需要查閱 已知問題

或者你也可以使用 官方 Qt 安裝程序進行安裝。

工具

以下是官方的Qt工具:

  • Qt Creator — 專為Qt設計的跨平台IDE,支持Qt所有的特性。
https://doc.qt.io/qtcreator/ || qtcreator
  • Qt Linguist — Qt程序的多語言支持工具集。
https://doc.qt.io/qt-5/qtlinguist-index.html || Qt 5: qt5-tools, Qt 4: qt4AUR
  • Qt Assistant — 可配置、可再分發的Qt qch 文件閱讀器。
https://doc.qt.io/qt-5/qtassistant-index.html || Qt 5: qt5-tools, Qt 4: qt4AUR
  • Qt Designer — 為Qt Widget程序編寫的跨平台GUI設計、窗體構建工具。
https://doc.qt.io/qt-5/qtdesigner-manual.html || Qt 5: qt5-tools, Qt 4: qt4AUR
  • Qt Quick Designer — QML文件的可視化編輯器,支持WYSIWYG(所見即所得)。它能讓你從零開始快速構建一個Qt Quick程序。
https://doc.qt.io/qtcreator/creator-using-qt-quick-designer.html[失效連結 2022-09-22 ⓘ] || qtcreator
  • qmlscene — 可以用來加載QML文檔的工具。這讓開發和調試QML程序變得很快。
https://doc.qt.io/qt-5/qtquick-qmlscene.html || Qt 5: qt5-declarative, Qt 4 QML Viewer: qt4AUR
  • qmake — 用來簡化跨平台程序的構建過程的工具,與 cmake 相似,但提供的選項更少,同時是為Qt程序定製的。
https://doc.qt.io/qt-5/qmake-manual.html || Qt 5: qt5-base, Qt 4: qt4AUR
  • uic — 讀取 *.ui XML文件並且生成相應的C++文件的工具。
https://doc.qt.io/qt-5/uic.html || Qt 5: qt5-base, Qt 4: qt4AUR
  • rcc — 用於在構建過程中將資源(例如圖片)嵌入到Qt應用程式中的工具。它生成包含在 Qt 資源 (.qrc) 文件中指定的數據的 C++ 源文件。
https://doc.qt.io/qt-5/rcc.html || Qt 5: qt5-base, Qt 4: qt4AUR
  • moc — 用來處理Qt的C++語言功能拓展的工具(例如信號槽技術、運行時類型信息、動態屬性系統等等)。
https://doc.qt.io/qt-5/moc.html || Qt 5: qt5-base, Qt 4: qt4AUR

語言支持

Qt支持許多流行的程式語言,查閱 https://wiki.qt.io/Language_Bindings 以獲取完整列表。

下面的例子會在一個窗口中顯示 'Hello world!'。

C++

hello.cpp
#include <QApplication>
#include <QLabel>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);
    QLabel hello("Hello world!");

    hello.show();
    return app.exec();
}

QML

hello.qml
import QtQuick 2.3

Rectangle {
    id: page
    width: 400; height: 100
    color: "lightgray"

    Text {
        id: helloText
        text: "Hello world!"
        anchors.horizontalCenter: page.horizontalCenter
        anchors.verticalCenter: page.verticalCenter
        font.pointSize: 24; font.bold: true
    }
}

Python (PyQt)

hello-pyqt.py
import sys
from PyQt5 import QtWidgets

app = QtWidgets.QApplication(sys.argv)
label = QtWidgets.QLabel("Hello world!")

label.show()
sys.exit(app.exec_())

Python (PySide2)

hello-pyside2.py
import sys
from PySide2.QtWidgets import QApplication, QLabel

app = QApplication(sys.argv)
label = QLabel("Hello world!")

label.show()
sys.exit(app.exec_())

C#

查看 QtSharp

解決問題

禁用/更改 Qt 日誌行為

當使用 KDE 和/或者任何其他Qt 桌面環境 時,調試信息可能會頻繁的輸出到 systemd日誌 中。

QT_LOGGING_RULES 設為 環境變量 來修改這個行為。例如,完全禁用所有日誌:

/etc/environment
QT_LOGGING_RULES='*=false'

若只想禁用調試信息的日誌,請使用 QT_LOGGING_RULES="*.debug=false"

圖標主題沒有生效

從Qt 5.1開始,SVG支持被移動到了其他的模塊。由於 qt5-base 不依賴於 qt5-svg,可能會出現 qt5-base 安裝上了,但未安裝 qt5-svg 的情況。這會導致欺騙性的圖標行為。由於SVG不受支持,圖標的繪製過程被安靜地跳過了,因此圖標主題可能處於未使用狀態。手動安裝 qt5-svg 可以解決這個問題。

主題對root下運行的程序無效

由於用戶的主題配置文件 ($XDG_CONFIG_HOME/Trolltech.conf) 不被其他的用戶讀取,你選擇的主題不會對 root下運行的X程序生效。以下是幾個可能解決方案:

  • 創建符號連結,例如
    # ln -s /home/[username]/.config/Trolltech.conf /etc/xdg/Trolltech.conf
  • 配置系統級別的主題文件:/etc/xdg/Trolltech.conf
  • 將主題調整為root

Qt 4 風格未被考慮

如果純Qt4程序(非KDE程序)不遵循你所選擇的Qt4風格,那麼你可能需要告訴Qt4如何找到KDE風格(Oxygen等)。只需要設置 環境變量 QT_PLUGIN_PATH即可。例如:

QT_PLUGIN_PATH=$HOME/.kde4/lib/kde4/plugins/:/usr/lib/kde4/plugins/

qtconfig-qt4 應該能夠找到你的kde主題,從而解決這些問題。

或者你也可以將Qt4風格文件夾軟連結到KDE4風格文件夾:

# ln -s /usr/lib/{kde,qt}4/plugins/styles/theme_name

Qt5升級後所有基於Qt5的程序無法啟動

如果你得到大概類似以下的報錯信息:

Qt FATAL: Cannot mix incompatible Qt library (version 0x50900) with this library (version 0x50901)

那麼很可能是因為你正使用著沒有針對最新Qt5重新編譯的Qt5主題或風格插件。它們通常使用Qt私有頭文件,這意味著它們依賴於特定的Qt版本,而不僅僅是匹配的soname。通過檢查 QT_STYLE_OVERRIDEQT_QPA_PLATFORMTHEME 環境變量找出您正在使用的主題/樣式,並重新構建提供它的AUR包。

QXcbConnection: XCB error: 2 (BadValue)

創建含有如下內容的文件 [1]:

/etc/xdg/QtProject/qtlogging.ini
[Rules]
qt.qpa.xcb.xcberror=false

圖形未正確對齊或縮放不正確

查看 HiDPI#Qt 5

死鍵在Qt程序中不工作

如果你進行了正確的鍵盤配置,並且死鍵在GTK應用程式(或其他小部件工具包)中工作,但在KDE或任何Qt應用程式中不起作用,那麼你可能沒有在Xorg中加載正確的文件。

去確認的一種方法:

  1. launch a Qt app with qt.xkb.compose.debug logging rule enabled, eg. launching qtqr: QT_LOGGING_RULES=qt.xkb.compose.debug=true qtqr
  2. then try to write a character using a dead key, eg. <dead_circumflex> <e> for ê (LATIN SMALL LETTER E WITH CIRCUMFLEX)
  3. if you encounter qt.xkb.compose: failed to create compose table then you probably have this issue.

To fix this, first identify your locale. Then, if your locale doesn't have its own folder in /usr/share/X11/locale/, eg. fr_FR.UTF-8, look for it in the compose.dir mapping file to find the corresponding compose file (eg. en_US.UTF-8/Compose):

$ grep fr_FR.UTF-8 /usr/share/X11/locale/compose.dir
en_US.UTF-8/Compose             fr_FR.UTF-8
en_US.UTF-8/Compose:            fr_FR.UTF-8

Now create or edit ~/.XCompose to include this compose file:

~/.XCompose
include "%S/en_US.UTF-8/Compose"

最後,重啟Qt 軟體, dead keys should be working and qt.xkb.compose: failed to create compose table error should have disappeared whenever you debug with QT_LOGGING_RULES=qt.xkb.compose.debug=true.

參閱