如何開發 KWin 插件#

KWin 是 KDE Plasma 桌面環境內建的視窗合成器與視窗管理員，支援在 X11 與 Wayland 兩種顯示協定下運作。KWin 提供了相當彈性的插件架構，讓開發者能在不修改核心程式碼的情況下擴充功能，例如特效（Effects）、腳本（Scripts）、視窗裝飾（Window Decorations）等。本文將介紹兩種主要的開發方式：KWin Scripts（QML/JavaScript） 與 KWin C++ 原生插件（Effects/Plugins）。

一、開發方式概覽#

KWin 的擴充機制大致分為三類：

KWin Scripts：使用 JavaScript 撰寫，透過 KWin 提供的腳本 API 操作視窗、工作區、輸出裝置等，開發門檻低，適合快速原型與簡易自動化邏輯。
KWin Effects（特效插件）：使用 C++ 撰寫，可直接存取合成器的渲染管線，適合實作視覺特效（如模糊、縮放動畫、轉場效果）。
視窗裝飾（Decoration）插件：使用 C++ 與 QML 撰寫，用來自訂視窗標題列、按鈕樣式等外觀。

以下分別說明前兩種最常見的開發方式。

二. 撰寫 metadata.json#

metadata.json 定義插件的基本資訊，KWin 會依此辨識並載入腳本：

1
{
2
    "KPlugin": {
3
        "Id": "my-kwin-script",
4
        "Name": "My KWin Script",
5
        "Description": "示範用的 KWin 腳本插件",
6
        "Authors":  "你的名字",
7
        "Version": "1.0",
8
        "License": "GPL-3.0-or-later"
9
    }
10
}

三、開發 KWin Effect（C++ 原生特效插件）#

1. 環境需求#

KDE Frameworks（KF6）與 Qt6 開發套件
KWin 原始碼與標頭檔（建議使用發行版提供的 kwin-devel 或自行編譯 KWin）
CMake、extra-cmake-modules

2. 基本 CMakeLists.txt 範例#

1
cmake_minimum_required(VERSION 3.19)
2
project({your_project_name} VERSION 6.0.0 LANGUAGES CXX)
3

4
set(CMAKE_CXX_STANDARD 20)
5
set(CMAKE_CXX_STANDARD_REQUIRED ON)
6
find_package(ECM 6.0.0 REQUIRED NO_MODULE)
7
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})
8

9
include(KDEInstallDirs)
10
include(KDECMakeSettings)
11
include(KDECompilerSettings NO_POLICY_SCOPE)
12

13
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
14
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
15
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
16

17
set(QT_NO_CREATE_VERSIONLESS_FUNCTIONS TRUE)
18
find_package(Qt6 REQUIRED COMPONENTS Core Gui Network Widgets)
19
find_package(KF6 REQUIRED COMPONENTS CoreAddons)
20
find_package(KWin REQUIRED)
21

22
set(project_SRCS
23
    main.cpp
24
)
25

26
kcoreaddons_add_plugin({your_project_name}
27
    SOURCES ${project_SRCS}
28
    INSTALL_NAMESPACE "kwin/effects/plugins"
29
)
30

31
target_link_libraries({your_project_name}
32
    Qt::Core
33
    Qt::Gui
34
    Qt::Network
35
    KF6::CoreAddons
36
    KWin::kwin
37
)

3. 示範#

1
#pragma once
2

3
#include <effect/effect.h>
4
#include <effect/effecthandler.h>
5
#include <QLocalSocket>
6
#include <QPointer>
7
#include <QObject>
8
#include <QPointF>
9
#include <kwin/virtualdesktops.h>
10

11
namespace kde {
12

13
struct DesktopTransition {
14
    int desktop;
15
    float x;
16
    float y;
17
};
18

19
class WorkspaceTrackerEffect : public KWin::Effect
20
{
21
    Q_OBJECT
22
public:
23
    WorkspaceTrackerEffect();
24
    ~WorkspaceTrackerEffect() override;
25

26
private Q_SLOTS:
27
    void onDesktopChanging(KWin::VirtualDesktop* desktop, QPointF offset);
28
    void onDesktopChangingCancelled();
29
    void onDesktopChanged(KWin::VirtualDesktop* oldDesktop, KWin::VirtualDesktop* newDesktop);
30
    void connectSocket();
31

32
private:
33
    void sendPayload(int desktop, float x, float y);
34

35
    QLocalSocket* m_socket;
36
};
37

38
} // namespace caelestia

1
#include "workspace_tracker.hpp"
2
#include <QTimer>
3
#include <KPluginFactory>
4
#include <QStandardPaths>
5
#include <QDir>
6
#include <QDebug>
7
#include <QStandardPaths>
8
#include <QDir>
9

10
namespace kde {
11

12
WorkspaceTrackerEffect::WorkspaceTrackerEffect()
13
    : m_socket(new QLocalSocket(this))
14
{
15
    connect(KWin::effects, &KWin::EffectsHandler::desktopChanging,
16
            this, &WorkspaceTrackerEffect::onDesktopChanging);
17
    connect(KWin::effects, &KWin::EffectsHandler::desktopChangingCancelled,
18
            this, &WorkspaceTrackerEffect::onDesktopChangingCancelled);
19
    connect(KWin::effects, &KWin::EffectsHandler::desktopChanged,
20
            this, &WorkspaceTrackerEffect::onDesktopChanged);
21

22
    connect(m_socket, &QLocalSocket::disconnected, this, [this]() {
23
        qDebug() << "WorkspaceTracker: Socket disconnected, retrying...";
24
        QTimer::singleShot(2000, this, &WorkspaceTrackerEffect::connectSocket);
25
    });
26

27
    connect(m_socket, &QLocalSocket::errorOccurred, this, [this](QLocalSocket::LocalSocketError err) {
28
        qDebug() << "WorkspaceTracker: Socket error:" << err << "- retrying in 2s";
29
        QTimer::singleShot(2000, this, &WorkspaceTrackerEffect::connectSocket);
30
    });
31

32
    connect(m_socket, &QLocalSocket::connected, this, [this]() {
33
        qDebug() << "WorkspaceTracker: Socket connected!";
34
    });
35

36
    connectSocket();
37
}
38

39
WorkspaceTrackerEffect::~WorkspaceTrackerEffect()
40
{
41
    if (m_socket->isOpen()) {
42
        m_socket->close();
43
    }
44
}
45

46
void WorkspaceTrackerEffect::connectSocket()
47
{
48
    if (m_socket->state() == QLocalSocket::UnconnectedState) {
49
        QString socketPath = QStandardPaths::writableLocation(QStandardPaths::RuntimeLocation) + QStringLiteral("/caelestia-workspace-tracker");
50
        qDebug() << "WorkspaceTracker: Connecting to socket:" << socketPath;
51
        m_socket->connectToServer(socketPath);
52
    }
53
}
54

55
void WorkspaceTrackerEffect::sendPayload(int desktop, float x, float y)
56
{
57
    if (m_socket->state() == QLocalSocket::ConnectedState) {
58
        DesktopTransition payload{desktop, x, y};
59
        m_socket->write(reinterpret_cast<const char*>(&payload), sizeof(payload));
60
    }
61
}
62

63
void WorkspaceTrackerEffect::onDesktopChanging(KWin::VirtualDesktop* desktop, QPointF offset)
64
{
65
    if (desktop && m_socket->state() == QLocalSocket::ConnectedState) {
66
        qDebug() << "WorkspaceTracker: sending offset" << offset << "for desktop" << desktop->x11DesktopNumber();
67
        sendPayload(desktop->x11DesktopNumber(), static_cast<float>(offset.x()), static_cast<float>(offset.y()));
68
    } else {
69
        qDebug() << "WorkspaceTracker: not connected or desktop is null. Socket state:" << m_socket->state();
70
    }
71
}
72

73
void WorkspaceTrackerEffect::onDesktopChangingCancelled()
74
{
75
    sendPayload(0, 0.0f, 0.0f);
76
}
77

78
void WorkspaceTrackerEffect::onDesktopChanged(KWin::VirtualDesktop* oldDesktop, KWin::VirtualDesktop* newDesktop)
79
{
80
    if (newDesktop && m_socket->state() == QLocalSocket::ConnectedState) {
81
        sendPayload(newDesktop->x11DesktopNumber(), 0.0f, 0.0f);
82
    }
83
}
84

85
} // namespace kde
86

87
KWIN_EFFECT_FACTORY(kde::WorkspaceTrackerEffect, "metadata.json") //要記得有他就好:)
88

89
#include "workspace_tracker.moc"

特效插件可覆寫 paintScreen()、paintWindow() 等函式來介入合成器的繪製流程，實作模糊、透明度漸變、位移動畫等效果。

4. 編譯與安裝#

1
mkdir build && cd build
2
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
3
make
4
sudo make install

安裝完成後，於系統設定的「桌面特效」清單中應可看到新插件並啟用。

四、除錯建議#

使用 journalctl --user -f | grep kwin (若在程式碼用qDebug()的話)來觀察log 與錯誤訊息。
修改 C++ 插件後務必重新編譯並重啟 KWin（或登出重登），避免載入到舊版本的動態函式庫。

五、參考資源#

KDE 官方開發者文件（develop.kde.org）中的 KWin 章節
KWin 原始碼倉庫內的 src/scripting/ 與 src/effects/ 目錄，內含大量官方特效與腳本範例可供參考
KDE Bugzilla 與 invent.kde.org 上的 KWin 專案，可觀察社群提交的合併請求（Merge Request）學習實際開發流程

~~當然你也可以來給我的垃圾專案星星https://github.com/LuYishan-4/Animated_UltralightWeb_Cursor~~

KDE-Wayland插件開發