ProfilePaths.h

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 fuddlesworth
// SPDX-License-Identifier: LGPL-2.1-or-later
 
#pragma once
 
#include <PhosphorAnimation/phosphoranimation_export.h>
 
#include <QString>
#include <QStringList>
 
namespace PhosphorAnimation {
 
namespace ProfilePaths {
 
// Root
PHOSPHORANIMATION_EXPORT extern const QString Global;
 
// window.* — runtime window-lifecycle animations driven by the
// kwin-effect's OffscreenEffect via tryBeginShaderForEvent. The
// snap/layout-switch leaves are window events triggered by zone
// interaction (the WINDOW animates when it snaps into/out of a zone
// or when a layout switch repositions it).
PHOSPHORANIMATION_EXPORT extern const QString Window;
// window.appearance.* — a window surface materialising / dissolving (the
// appearance shader contract). WindowAppearance is the cascade parent.
PHOSPHORANIMATION_EXPORT extern const QString WindowAppearance;
PHOSPHORANIMATION_EXPORT extern const QString WindowOpen;
PHOSPHORANIMATION_EXPORT extern const QString WindowClose;
PHOSPHORANIMATION_EXPORT extern const QString WindowMinimize;
PHOSPHORANIMATION_EXPORT extern const QString WindowFocus;
// window.movement.* — a window changing geometry, old-rect → new-rect (the
// geometry-morph shader contract). WindowMovement is the cascade parent.
// WindowMove is the exception: the held interactive drag, its own opt-in
// `move` class (see EventClassMove below). There are NO resize legs — the
// interactive edge-drag resize and the never-routed snapResize were dropped
// (see the rationale note in profilepaths.cpp); discrete resizes are
// covered by snapIn / layoutSwitch / maximize.
PHOSPHORANIMATION_EXPORT extern const QString WindowMovement;
PHOSPHORANIMATION_EXPORT extern const QString WindowMaximize;
PHOSPHORANIMATION_EXPORT extern const QString WindowMove;
PHOSPHORANIMATION_EXPORT extern const QString WindowSnapIn;
PHOSPHORANIMATION_EXPORT extern const QString WindowSnapOut;
PHOSPHORANIMATION_EXPORT extern const QString WindowLayoutSwitch;
 
// desktop.* — full-screen two-texture transitions driven by the kwin-effect's
// screen-level paint pass. Unlike the per-window window.* events, these blend
// two full-screen scene captures, so they use the desktop event class and its
// own two-texture shader contract rather than the single-surface pipeline.
// `switch` blends the OUTGOING desktop against the INCOMING desktop; `peek`
// (show desktop) blends the windows scene against the bare desktop, and its
// show-back leg reuses the same node, running the same blend with time
// reversed so an asymmetric pack retraces its own motion.
PHOSPHORANIMATION_EXPORT extern const QString Desktop;
PHOSPHORANIMATION_EXPORT extern const QString DesktopSwitch;
PHOSPHORANIMATION_EXPORT extern const QString DesktopPeek;
 
// editor.* — Layout-editor-only zone manipulation animations
// (fill-preview, drag-resize-preview). NOT triggered by runtime
// window snapping — window-snap animations are KWin's
// compositor-level domain. These paths only fire inside the
// Phosphor layout editor.
//
// snapIn and snapOut are the two DIRECTIONS of one animator
// (ZoneFillAnimation.qml), picked by whether the zone is taking space or
// giving it up: snapIn on the fill preview and on a neighbour absorbing a
// deleted zone, snapOut on the original half when a zone is split. They are
// not two animators, so a caller that changes geometry gets the right leg by
// direction rather than by naming one.
PHOSPHORANIMATION_EXPORT extern const QString Editor;
PHOSPHORANIMATION_EXPORT extern const QString EditorSnapIn;
PHOSPHORANIMATION_EXPORT extern const QString EditorSnapOut;
PHOSPHORANIMATION_EXPORT extern const QString EditorSnapResize;
 
// scrolling.* — the scrolling strip's VIEW. `scrolling.view` is one leg for
// the whole strip: the compositor springs it once per output and every column
// rides that offset, rather than each column springing itself. It is its own
// root rather than a window.movement.* leaf because its subject is the view
// and not any window.
// `scrolling.tabSwitch` shares the root for grouping only: its subject IS a
// window (the tab arriving in the rect the outgoing one vacated), so it
// carries its own opt-in `tab` class (see EventClassTab below), not the strip
// class its siblings do.
PHOSPHORANIMATION_EXPORT extern const QString Scrolling;
PHOSPHORANIMATION_EXPORT extern const QString ScrollingView;
PHOSPHORANIMATION_EXPORT extern const QString ScrollingTabSwitch;
 
// shell.* — surfaces owned by the desktop shell rather than by an
// application: today the Plasma applet popups (the launcher, the system tray
// flyouts, any widget's expanded view). Appearance legs like the window ones,
// driven by the same kwin-effect lifecycle hooks, but on their OWN root for
// the reason the decoration tree gives them one: a foreign surface must not
// inherit what the user chose for their windows. That is enforced in the
// shader tree, where the whole subtree resolves inside itself
// (shaderPathIsolationRoot) — engaging a pack HERE is the entire opt-in, and
// an unconfigured shell surface animates exactly as it did before the root
// existed. Show / hide rather than open / close: these are ephemeral
// surfaces, the same family the osd and popup roots name that way.
//
// The isolation is the SHADER tree's alone. ProfileTree has no isolation arm, so
// these legs take their duration and curve from the ordinary walk, `global`
// included — deliberately, since the timing is inert until a pack is engaged and a
// user who sets one duration for everything means it. Anything describing this
// subtree to a user must scope the claim to the shader, or it is wrong about
// timing.
PHOSPHORANIMATION_EXPORT extern const QString Shell;
PHOSPHORANIMATION_EXPORT extern const QString ShellAppletPopup;
PHOSPHORANIMATION_EXPORT extern const QString ShellAppletPopupShow;
PHOSPHORANIMATION_EXPORT extern const QString ShellAppletPopupHide;
 
// osd.*
PHOSPHORANIMATION_EXPORT extern const QString Osd;
PHOSPHORANIMATION_EXPORT extern const QString OsdShow;
PHOSPHORANIMATION_EXPORT extern const QString OsdPop;
PHOSPHORANIMATION_EXPORT extern const QString OsdHide;
 
// popup.* — transient overlays invoked by user action.
// Per-leg .show/.hide leaves let show/hide shader effects diverge.
PHOSPHORANIMATION_EXPORT extern const QString Popup;
PHOSPHORANIMATION_EXPORT extern const QString PopupZoneSelector;
PHOSPHORANIMATION_EXPORT extern const QString PopupZoneSelectorShow;
PHOSPHORANIMATION_EXPORT extern const QString PopupZoneSelectorHide;
PHOSPHORANIMATION_EXPORT extern const QString PopupLayoutPicker;
PHOSPHORANIMATION_EXPORT extern const QString PopupLayoutPickerShow;
PHOSPHORANIMATION_EXPORT extern const QString PopupLayoutPickerHide;
PHOSPHORANIMATION_EXPORT extern const QString PopupSnapAssist;
PHOSPHORANIMATION_EXPORT extern const QString PopupSnapAssistShow;
PHOSPHORANIMATION_EXPORT extern const QString PopupSnapAssistHide;
PHOSPHORANIMATION_EXPORT extern const QString PopupCheatsheet;
PHOSPHORANIMATION_EXPORT extern const QString PopupCheatsheetShow;
PHOSPHORANIMATION_EXPORT extern const QString PopupCheatsheetHide;
 
// panel.* — persistent in-app side surfaces (settings nav rail, editor
// property panel). Absorbs the former sidebar.* root — sidebars are panels.
PHOSPHORANIMATION_EXPORT extern const QString Panel;
PHOSPHORANIMATION_EXPORT extern const QString PanelSlideIn;
PHOSPHORANIMATION_EXPORT extern const QString PanelSlideOut;
PHOSPHORANIMATION_EXPORT extern const QString PanelFadeIn;
PHOSPHORANIMATION_EXPORT extern const QString PanelFadeOut;
 
// cursor.*
PHOSPHORANIMATION_EXPORT extern const QString Cursor;
PHOSPHORANIMATION_EXPORT extern const QString CursorHover;
PHOSPHORANIMATION_EXPORT extern const QString CursorClick;
 
// widget.* — per-archetype paths so library defaults preserve original motion.
PHOSPHORANIMATION_EXPORT extern const QString Widget;
PHOSPHORANIMATION_EXPORT extern const QString WidgetHover; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetPress; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetDim; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetTint; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetTintFast; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetToggleOn; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetToggleOff; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetBadgeShow; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetBadgeHide; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetBadgePulse; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetAccordionExpand; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetAccordionCollapse; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetFadeIn; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetFadeOut; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetReorder; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetProgress; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetPulse; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetPulseFast; 
PHOSPHORANIMATION_EXPORT extern const QString WidgetPulseSlow; 
// Zone-rect widget (used by ZoneItem.qml,
// ZonePreview.qml — i.e. the reusable QML zone-rectangle that gets
// embedded in the runtime overlay, settings dialogs, layout
// thumbnails, etc.). The animation lives with the widget; the
// surface it's hosted on is incidental.
PHOSPHORANIMATION_EXPORT extern const QString WidgetZoneHighlight;
PHOSPHORANIMATION_EXPORT extern const QString WidgetZoneHighlightPop;
PHOSPHORANIMATION_EXPORT extern const QString WidgetZoneHighlightBorder;
// One-shot flash on the main zone-overlay surface when the active
// layout changes mid-drag (ZoneOverlayContent.qml). A widget-level
// content effect on the overlay, not a per-zone animation.
PHOSPHORANIMATION_EXPORT extern const QString WidgetZoneOverlayFlash;
 
// ── Event classes ───────────────────────────────────────────────────────
// A coarse capability axis layered over the path taxonomy. Two of the six
// classes are the general ones: an animation either reshapes a window's
// GEOMETRY (it has a before-rect and an after-rect) or it changes a
// surface's APPEARANCE (a single surface fading / scaling / glitching in or
// out). A geometry-only shader such as window-morph cross-fades
// `iFromRect → iToRect` and is a silent no-op on an appearance event, so a
// shader declares which classes it supports (AnimationShaderEffect::appliesTo)
// and the settings UI filters the rows it can't drive. The other four —
// DESKTOP, MOVE, STRIP and TAB — each name a distinct uniform contract a
// pack must opt into explicitly, and a universal (empty `appliesTo`) pack
// never reaches them. These string tokens are the SSOT for that vocabulary —
// matched verbatim against `appliesTo` entries and `eventClassForPath`.
//
// Adding a class token? It is not enough to declare it here. Every one of
// these must be updated too, and the last three have each already shipped a
// bug from being missed:
//   1. `allEventClassTokens()` below — the exported vocabulary. `fromJson`
//      (animationshadereffect.cpp) validates `appliesTo` against it and the
//      pack validator's lint lists it in the diagnostic, so both follow for
//      free once it is here.
//   2. `shaderEffectAppliesToEventPath` (AnimationShaderEffect.h) — an
//      opt-in class needs its own branch plus an exclusion in the
//      ambiguous-row fallback, or it silently behaves as universal.
//   3. `shaderEffectIsCompositorOnly` (AnimationShaderEffect.h) hardcodes
//      "appearance is the only class that reaches a daemon surface" — a new
//      daemon-driven class must be added there, or its packs are silently
//      classified compositor-only and skipped by the daemon.
//   4. `_typeCatalog` in ShaderBrowserPage.qml — the browser's type axis.
//      A missing entry ships an untranslated badge sorted last.
//   5. `shaderPathResolvesInIsolation` (shaderprofiletree.cpp) — decide
//      whether the new class's leaves may inherit a shader from their
//      ancestors. A leaf whose ONLY ancestors carry other classes must join
//      the predicate, or it inherits packs the applicability gate then
//      refuses at install: the leaf animates nothing while settings shows an
//      inherited "current shader" that never runs (the tab class shipped
//      with exactly this hazard).
//   6. `shaderConsumedLeafEventPaths` (animationshadersupportedpaths.h) —
//      the new class's consumed leaves must be registered, or the picker
//      hides the shader row and the prune drops stored overrides.
// (The coverage chips in AnimationsMotionSetsPage.qml / DecorationSetsPage.qml
// key on the path ROOT segment, not on class tokens — a new class needs a
// case there only if it also introduces a new path root.)
//
// Adding a path ROOT? A different list, and longer than it looks. The `shell`
// root needed every one of these:
//   1. `allBuiltInPaths()` below — the taxonomy every UI and validity check
//      reads. It is NOT a persistence filter: the motion tree stores and
//      loads whatever path it is given (ProfileTree::setOverride/fromJson
//      reject only an empty one), so a path missing here is not dropped, it
//      just becomes unreachable from the UI and inert at resolve time. The
//      writer-side reject lives in AnimationsPageController::isValidEventPath.
//   2. `eventClassForPath` — an unclassified root reads as the ambiguous-row
//      fallback in the pack pickers.
//   3. `shaderConsumedLeafEventPaths` (animationshadersupportedpaths.h) — the
//      shader tree's admission list, per the note at the top of this file.
//   4. An isolation decision: ordinary inheritance, a leaf in
//      `shaderPathResolvesInIsolation`, or a subtree in
//      `shaderPathIsolationRoot`. Deciding nothing means ordinary, which for a
//      foreign surface is usually wrong.
//   5. `segmentLabel` (animationspagecontroller_paths.cpp) — every segment of the
//      built-in taxonomy is translated there; a miss ships untranslated English
//      through the mechanical humanizeSegment fallback.
//   6. The coverage-chip `case` in BOTH AnimationsMotionSetsPage.qml and
//      DecorationSetsPage.qml, per the parenthetical above.
//   7. A settings page plus its registration, topology, page scope and search
//      catalogue entries.
//   8. `animationPageScope` — without an entry the page falls through to the
//      whole-tree branch and its Reset wipes every animation override there is.
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassGeometry;
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassAppearance;
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassDesktop;
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassMove;
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassStrip;
 
PHOSPHORANIMATION_EXPORT extern const QString EventClassTab;
 
PHOSPHORANIMATION_EXPORT QStringList allEventClassTokens();
 
PHOSPHORANIMATION_EXPORT QString eventClassForPath(const QString& path);
 
PHOSPHORANIMATION_EXPORT bool eventPathResolvesPerWindow(const QString& path);
 
PHOSPHORANIMATION_EXPORT QStringList allBuiltInPaths();
 
PHOSPHORANIMATION_EXPORT QString parentPath(const QString& path);
 
PHOSPHORANIMATION_EXPORT QString defaultShaderEffectIdForPath(const QString& path);
 
} // namespace ProfilePaths
 
} // namespace PhosphorAnimation