Adding a Desktop Environment

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);

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/<DE>Desktop.h"
#include "logging/LogManager.h"
#include <QDBusConnection>
#include <QDBusConnectionInterface>
#include <QDBusMessage>
#include <QProcessEnvironment>
namespace logitune {
<DE>Desktop::<DE>Desktop(QObject *parent)
 : LinuxDesktopBase(parent)
{
}
void <DE>Desktop::start()
{
 // 1. Sanity-check the session — bail if this DE isn't actually running
 // or if the session type is wrong for your focus API.
 // 2. If you need a Shell extension / KWin script / wlr protocol,
 // install or activate it here.
 // 3. Register your D-Bus callback so the DE-side agent can call
 // back into the app with focus events. focusChanged() is
 // inherited from LinuxDesktopBase and does the desktop-file
 // resolution + duplicate suppression.
 //
 // See GnomeDesktop::start() for a complete worked example.
 m_available = true;
}
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;
}
// focusChanged() is the D-Bus entry point the DE-side agent calls.
// LinuxDesktopBase provides resolveDesktopFile() + duplicate-event
// suppression, so subclasses only implement the DE-specific glue.
void <DE>Desktop::focusChanged(const QString &appId, const QString &title)
{
 QString resolved = appId;
 if (!appId.contains('.'))
 resolved = resolveDesktopFile(appId);
 if (resolved == m_lastAppId) return;
 m_lastAppId = resolved;
 emit activeWindowChanged(resolved, title);
}
// runningApplications() is inherited from LinuxDesktopBase — do not
// reimplement unless your DE has a faster dedicated API.
} // namespace logitune

Step 3: Focus Tracking Strategies

Step 4: Window Identity Resolution

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

Outline: Adding Hyprland Support