🖥️ Adding a Desktop Environment

Note

For how desktop integration fits into the overall system, see the Desktop Integration section of the Architecture page.

📐 Interface

class IDesktopIntegration : public QObject {
 Q_OBJECT
public:
 virtual void start() = 0;
 virtual bool available() const = 0;
 virtual QString desktopName() const = 0;
 virtual QStringList detectedCompositors() const = 0;
 virtual void blockGlobalShortcuts(bool block) = 0;
 virtual QVariantList runningApplications() const = 0;
signals:
 void activeWindowChanged(const QString &wmClass, const QString &title);
};

📋 Required Methods

⚡ The Critical Signal

void activeWindowChanged(const QString &wmClass, const QString &title);

Important

This signal drives the entire profile switching system. wmClass must be a stable, unique identifier for the application. On KDE, this is the .desktop file's completeBaseName (e.g., org.kde.dolphin). On other DEs, it might be the X11 WM_CLASS or a Wayland app_id.

🔧 Existing Implementations

🖥️ KDeDesktop

🖥️ GenericDesktop

🏗️ Step-by-Step: Adding GNOME Support

📝 Step 1: Create the class

#pragma once
#include "interfaces/IDesktopIntegration.h"
#include <QDBusInterface>
#include <QTimer>
namespace logitune {
class GnomeDesktop : public IDesktopIntegration {
 Q_OBJECT
public:
 explicit GnomeDesktop(QObject *parent = nullptr);
 void start() override;
 bool available() const override;
 QString desktopName() const override;
 QStringList detectedCompositors() const override;
 void blockGlobalShortcuts(bool block) override;
 QVariantList runningApplications() const override;
private:
 bool m_available = false;
 QString m_lastAppId;
 QTimer *m_pollTimer = nullptr;
 void pollActiveWindow();
 QString resolveAppId(const QString &wmClass) const;
};
} // namespace logitune

💻 Step 2: Implement focus tracking

#include "desktop/GnomeDesktop.h"
#include "logging/LogManager.h"
#include <QDBusConnection>
#include <QDBusMessage>
#include <QDBusReply>
#include <QProcessEnvironment>
#include <QDir>
#include <QFileInfo>
#include <QSettings>
namespace logitune {
GnomeDesktop::GnomeDesktop(QObject *parent)
 : IDesktopIntegration(parent)
{
}
void GnomeDesktop::start()
{
 // Check if GNOME Shell is running
 QDBusInterface shell(
 QStringLiteral("org.gnome.Shell"),
 QStringLiteral("/org/gnome/Shell"),
 QStringLiteral("org.gnome.Shell"),
 QDBusConnection::sessionBus());
 m_available = shell.isValid();
 if (!m_available) return;
 // GNOME Shell Extension approach:
 // Install a GNOME Shell extension that sends D-Bus signals on focus change.
 // Alternatively, use the GNOME Shell Eval API (deprecated) or
 // the org.gnome.Shell.Introspect API for window tracking.
 // For now, use polling via org.gnome.Shell.Introspect
 m_pollTimer = new QTimer(this);
 m_pollTimer->setInterval(500);
 connect(m_pollTimer, &QTimer::timeout, this, &GnomeDesktop::pollActiveWindow);
 m_pollTimer->start();
}
bool GnomeDesktop::available() const
{
 return m_available;
}
QString GnomeDesktop::desktopName() const
{
 return QStringLiteral("GNOME");
}
QStringList GnomeDesktop::detectedCompositors() const
{
 QStringList compositors;
 const QString desktop = QProcessEnvironment::systemEnvironment()
 .value(QStringLiteral("XDG_CURRENT_DESKTOP"));
 if (desktop.contains(QStringLiteral("GNOME"), Qt::CaseInsensitive))
 compositors << QStringLiteral("Mutter");
 return compositors;
}
void GnomeDesktop::pollActiveWindow()
{
 // Option 1: org.gnome.Shell.Introspect.GetWindows
 // Option 2: GNOME Shell extension with D-Bus callback
 // Option 3: wlr-foreign-toplevel-management (wlroots-based compositors)
 // This is the scaffold — the actual implementation depends on
 // which GNOME API is available and stable.
 // Example using Shell.Introspect:
 QDBusMessage msg = QDBusMessage::createMethodCall(
 QStringLiteral("org.gnome.Shell"),
 QStringLiteral("/org/gnome/Shell/Introspect"),
 QStringLiteral("org.gnome.Shell.Introspect"),
 QStringLiteral("GetWindows"));
 QDBusReply<QVariantMap> reply = QDBusConnection::sessionBus().call(msg);
 if (!reply.isValid()) return;
 // Find the focused window and extract its app-id
 // ... parse reply.value() ...
 // QString appId = ...;
 // if (appId != m_lastAppId) {
 // m_lastAppId = appId;
 // emit activeWindowChanged(appId, title);
 // }
}
void GnomeDesktop::blockGlobalShortcuts(bool block)
{
 // GNOME doesn't have a direct D-Bus API for this.
 // Options:
 // 1. Use a GNOME Shell extension
 // 2. Temporarily grab the keyboard via libinput
 // 3. Leave unimplemented (keystroke capture will work but may trigger shortcuts)
 Q_UNUSED(block)
}
QVariantList GnomeDesktop::runningApplications() const
{
 // Same approach as KDeDesktop — scan .desktop files
 // The KDeDesktop implementation is desktop-agnostic for this method
 // Consider extracting it to a shared utility
 QVariantList result;
 // ... scan /usr/share/applications/*.desktop ...
 return result;
}
} // namespace logitune

🔍 Step 3: Focus Tracking Strategies

🪪 Step 4: Window Identity Resolution

Warning

The trickiest part of desktop integration is resolving a window to a stable application ID. Different compositors report different identifiers:

Tip

This logic is currently in KDeDesktop but is DE-agnostic. Consider extracting it to a shared utility if adding multiple DEs.

📋 Step 5: Register in AppController

AppController::AppController(IDesktopIntegration *desktop, IInputInjector *injector, QObject *parent)
 : QObject(parent)
 , m_deviceManager(&m_registry)
 , m_actionExecutor(nullptr)
{
 if (desktop) {
 m_desktop = desktop;
 } else {
 // Detect desktop environment and create appropriate integration
 QString xdgDesktop = QProcessEnvironment::systemEnvironment()
 .value("XDG_CURRENT_DESKTOP");
 if (xdgDesktop.contains("KDE", Qt::CaseInsensitive)) {
 m_ownedDesktop = std::make_unique<KDeDesktop>();
 } else if (xdgDesktop.contains("GNOME", Qt::CaseInsensitive)) {
 m_ownedDesktop = std::make_unique<GnomeDesktop>();
 } else {
 m_ownedDesktop = std::make_unique<GenericDesktop>();
 }
 m_desktop = m_ownedDesktop.get();
 }
 // ... rest unchanged
}

📦 Step 6: Add to CMakeLists.txt

target_sources(logitune-core PRIVATE
 # ... existing files ...
 desktop/KDeDesktop.cpp
 desktop/GenericDesktop.cpp
 desktop/GnomeDesktop.cpp # Add this
)

🧪 Step 7: Testing

TEST(DesktopDetectionTest, GnomeDetected) {
 // Set XDG_CURRENT_DESKTOP to GNOME and verify GnomeDesktop is created
 // (This may require environment variable manipulation)
}

🔧 Extracting Shared Utilities

Tip

If you are adding a second DE implementation, consider extracting these shared utilities:

1. resolveDesktopFile() — .desktop file lookup by resourceClass/StartupWMClass
2. runningApplications() — scanning .desktop files for GUI applications
3. Desktop directory list — /usr/share/applications, Flatpak paths, etc.

These could live in a DesktopUtils static class or be moved to the GenericDesktop base class.

📝 Outline: Adding Hyprland Support

Note

The Hyprland IPC approach would be event-driven (no polling), making it more efficient than the GNOME polling fallback.