PhosphorIdentity::WindowId Namespace Reference

Compositor-agnostic window-identity utilities. More...

Functions
QString	buildCompositeId (QStringView appId, QStringView instanceId)
	Build a composite window id from its appId + instance parts.
QString	extractAppId (const QString &windowId)
	Extract app identity from window ID (portion before the '|' separator) Format: "appId|internalUuid" → returns "appId".
QString	extractInstanceId (const QString &windowId)
	Extract the stable KWin instance identifier (UUID) from a full window ID.
QString	normalizeAppId (const QString &desktopFileName, const QString &windowClass)
	Derive a canonical appId from a window's desktop-file name and class.
bool	isValidAppId (const QString &appId)
	Whether appId is a well-formed canonical app identifier.
QString	deriveShortName (const QString &windowClass)
	Derive short name from app ID for icon/app display Reverse-DNS: "org.kde.dolphin" → last dot-segment (e.g., "dolphin") Simple name: "firefox" → as-is.
bool	appIdMatches (const QString &appId, const QString &pattern)
	Segment-aware app ID matching for exclusion lists.

Detailed Description

Compositor-agnostic window-identity utilities.

Operates on the canonical composite window-id format "appId|instanceId". The format is stable across processes — KWin effect, daemon, and every library reading window assignments must spell it the same way. This is the single source of truth for parsing, building, and matching the format.

Function Documentation

appIdMatches()

bool PhosphorIdentity::WindowId::appIdMatches ( const QString &  appId, const QString &  pattern  )

inline

Segment-aware app ID matching for exclusion lists.

Matches reverse-DNS app IDs flexibly:

• Exact match (case-insensitive): "firefox" == "Firefox"
• Trailing dot-segment: "org.mozilla.firefox" matches pattern "firefox"
• Reverse trailing: pattern "org.mozilla.firefox" matches appId "firefox"
• Last-segment prefix (prefix >= 5 chars): "systemsettings" matches "systemsettings5"

The 5-char minimum always applies to the prefix candidate — whichever operand is the shorter one in the prefix/full-segment relationship. This prevents short false positives like appId "fire" matching pattern "org.mozilla.firefox" (the "firefox" last-segment would otherwise start with "fire").

buildCompositeId()

QString PhosphorIdentity::WindowId::buildCompositeId ( QStringView  appId, QStringView  instanceId  )

inline

Build a composite window id from its appId + instance parts.

Symmetric counterpart to extractAppId / extractInstanceId — together these three helpers make this header the single source of truth for the wire format. Callers should prefer this over hand-rolled appId + "|" + instanceId concatenation so the separator choice stays in exactly one place.

Either part may be empty; the result is always formed, with the separator preserved when instanceId is non-empty. An empty instanceId yields a bare appId (no trailing separator), which matches what extractAppId would reconstruct.

deriveShortName()

QString PhosphorIdentity::WindowId::deriveShortName ( const QString &  windowClass )

inline

Derive short name from app ID for icon/app display Reverse-DNS: "org.kde.dolphin" → last dot-segment (e.g., "dolphin") Simple name: "firefox" → as-is.

Warning

Operates on a bare appId, not a composite window id. If you hold a composite appId|instanceId, run it through extractAppId first — passing the composite in directly would make the '|'-separated instance id look like a trailing segment and produce that as the short name.

extractAppId()

QString PhosphorIdentity::WindowId::extractAppId ( const QString &  windowId )

inline

Extract app identity from window ID (portion before the '|' separator) Format: "appId|internalUuid" → returns "appId".

extractInstanceId()

QString PhosphorIdentity::WindowId::extractInstanceId ( const QString &  windowId )

inline

Extract the stable KWin instance identifier (UUID) from a full window ID.

Legacy composite format: "appId|internalId". The instance id is stable for the window's lifetime; the appId is mutable (Electron/CEF apps rebroadcast WM_CLASS mid-session). Per discussion #271, runtime keys use the bare instance id — this helper exists for legacy fixtures and compat paths.

A bare appId with no '|' separator is returned verbatim.

isValidAppId()

bool PhosphorIdentity::WindowId::isValidAppId ( const QString &  appId )

inline

Whether appId is a well-formed canonical app identifier.

A canonical appId is a non-empty, whitespace-free token — a desktop-file name ("org.kde.konsole") or a normalized window-class token. A blank, whitespace-only, or whitespace-bearing string is a corrupt identity (a KWin bare-" " class, or a stale pre-3.0 "resourceName resourceClass" key) and must never be used as a map key. Gate every appId-keyed insert and every persisted-key load on this.

normalizeAppId()

QString PhosphorIdentity::WindowId::normalizeAppId ( const QString &  desktopFileName, const QString &  windowClass  )

inline

Derive a canonical appId from a window's desktop-file name and class.

Prefers desktopFileName (stable across sessions). Falls back to the LAST whitespace-delimited token of windowClass: an X11 window class is "resourceName resourceClass" and the resourceName may itself contain spaces, so the last space is the split point and the resourceClass is the token kept. A Wayland app_id has no space and is taken whole.

The result is trimmed and lower-cased. A blank or whitespace-only input (KWin reports a bare " " class for some unmapped / transient surfaces) yields an EMPTY string, never " " — a space-only appId would otherwise become a live key in every appId-map (most damagingly the snap restore queue, where it lets unrelated blank-class windows consume each other's saved zones). isValidAppId rejects whatever survives.