Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
AssignmentEntry.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3
4#pragma once
5
7
8#include <QColor>
9#include <QHash>
10#include <QList>
11#include <QString>
12#include <QUuid>
13#include <QVariantMap>
14#include <QtGlobal>
15
16#include <optional>
17
18namespace PhosphorZones {
19
33{
34 QString screenId; // Stable EDID-based identifier (or connector name fallback)
35 int virtualDesktop = 0; // 0 = all desktops
36 QString activity; // Empty = all activities
37
38 bool operator==(const LayoutAssignmentKey& other) const
39 {
40 return screenId == other.screenId && virtualDesktop == other.virtualDesktop && activity == other.activity;
41 }
42
56 static LayoutAssignmentKey fromGroupName(const QString& groupName, const QString& prefix)
57 {
59 if (!groupName.startsWith(prefix))
60 return result;
61 QString remainder = groupName.mid(prefix.size());
62 if (remainder.isEmpty())
63 return result;
64
65 constexpr QLatin1String kActivityTag(":Activity:");
66 constexpr QLatin1String kDesktopTag(":Desktop:");
67 int actIdx = remainder.indexOf(kActivityTag);
68 if (actIdx >= 0) {
69 const QString activity = remainder.mid(actIdx + kActivityTag.size());
70 if (!activity.isEmpty())
71 result.activity = activity;
72 remainder = remainder.left(actIdx);
73 }
74 int deskIdx = remainder.indexOf(kDesktopTag);
75 if (deskIdx >= 0) {
76 bool ok = false;
77 int desktop = remainder.mid(deskIdx + kDesktopTag.size()).toInt(&ok);
78 if (ok && desktop > 0)
79 result.virtualDesktop = desktop;
80 remainder = remainder.left(deskIdx);
81 }
82 result.screenId = remainder;
83 return result;
84 }
85};
86
87inline size_t qHash(const LayoutAssignmentKey& key, size_t seed = 0)
88{
89 seed = ::qHash(key.screenId, seed);
90 seed = ::qHash(key.virtualDesktop, seed);
91 seed = ::qHash(key.activity, seed);
92 return seed;
93}
94
132inline constexpr QLatin1String NoScrollingTemplate{"none"};
133
173inline constexpr QLatin1String NoSnappingLayout{"none"};
174
191inline constexpr QLatin1String NoTilingAlgorithm{"none"};
192
203{
213 enum Mode {
227 };
229 QString snappingLayout; // UUID string of manual layout
230 QString tilingAlgorithm; // e.g. "dwindle", "wide", "tall"
254
255 QString activeLayoutId() const
256 {
257 // Scrolling has no layout entity, so the id is the bare sentinel
258 // "scrolling:". This is LOAD-BEARING: the assignment cascade's
259 // visitors reject entries with an empty activeLayoutId(), and a
260 // fresh mode-only Scrolling entry (empty preserved snappingLayout)
261 // would otherwise silently fail to assign. The gap / lock /
262 // overlay / tiling-param / scrolling-param resolvers stamp this
263 // sentinel into query.activeLayout, so `ActiveLayout Equals
264 // "scrolling:"` matches THERE (the assignment and context-default
265 // resolvers deliberately leave activeLayout unstamped — recursion).
266 // There is no per-layout identity to distinguish beyond the mode.
267 if (mode == Scrolling) {
269 }
270 if (mode == Autotile) {
271 // Autotile mode always produces a non-empty id so the cascade
272 // visitors in LayoutRegistry accept it (they reject on
273 // activeLayoutId().isEmpty()). For a mode-only entry (empty
274 // tilingAlgorithm — what the KCM writes for "autotile, use
275 // default algorithm"), makeAutotileId returns the bare
276 // prefix @c "autotile:"; downstream callers use
277 // @ref PhosphorLayout::LayoutId::isAutotile to detect mode
278 // and @ref PhosphorLayout::LayoutId::extractAlgorithmId to
279 // get the algorithm (empty = engine default).
281 }
282 return snappingLayout;
283 }
284
294 bool isValid() const
295 {
296 return !snappingLayout.isEmpty() || !tilingAlgorithm.isEmpty();
297 }
298 bool operator==(const AssignmentEntry& other) const
299 {
300 return mode == other.mode && snappingLayout == other.snappingLayout && tilingAlgorithm == other.tilingAlgorithm
302 }
303
309 static AssignmentEntry fromLayoutId(const QString& layoutId, const AssignmentEntry& existing)
310 {
311 AssignmentEntry entry = existing;
313 entry.mode = Autotile;
315 } else if (PhosphorLayout::LayoutId::isScrolling(layoutId)) {
316 // The "scrolling:" sentinel carries no layout entity — flip the
317 // mode and preserve all three layout fields (the lossless-toggle
318 // contract), so a get→set round-trip cannot degrade a Scrolling
319 // assignment into Snapping-pointing-at-a-bogus-id.
320 entry.mode = Scrolling;
321 } else {
322 entry.mode = Snapping;
323 // Normalize a UUID-shaped id to its canonical braced spelling at
324 // this ONE classification choke point, so every caller (the D-Bus
325 // setAssignmentEntry and the four setAll*Assignments verbs, the
326 // batch rebuilds, the controllers) stores one spelling. A braceless
327 // or upper-case bus-supplied uuid stored verbatim defeats the
328 // exact-string compare that purgeLayoutIdFromAssignments does on
329 // layout delete, and the byte-wise action compare in
330 // upsertAssignmentRule's no-op guard. Anything that is not a UUID
331 // passes through untouched — the snapping slot is not required to
332 // hold one, and @ref NoSnappingLayout DEPENDS on this arm staying
333 // verbatim: parsing the reserved word yields a null QUuid, and
334 // storing that null's toString would silently turn "explicitly
335 // none" into a dangling id.
336 const QUuid parsed = QUuid::fromString(layoutId);
337 entry.snappingLayout = parsed.isNull() ? layoutId : parsed.toString();
338 }
339 return entry;
340 }
341
345 static AssignmentEntry fromLayoutId(const QString& layoutId)
346 {
347 return fromLayoutId(layoutId, AssignmentEntry{});
348 }
349};
350
363{
364 std::optional<int> innerGap;
365 std::optional<int> outerGap;
366 std::optional<bool> usePerSideOuterGap;
367 std::optional<int> outerGapTop;
368 std::optional<int> outerGapBottom;
369 std::optional<int> outerGapLeft;
370 std::optional<int> outerGapRight;
371
372 bool isEmpty() const
373 {
375 && !outerGapRight;
376 }
377};
378
401{
402 std::optional<QString> shaderId;
403 QVariantMap shaderParams;
409 std::optional<int> style;
410 std::optional<QColor> highlightColor;
411 std::optional<QColor> inactiveColor;
412 std::optional<QColor> borderColor;
413 std::optional<double> activeOpacity;
414 std::optional<double> inactiveOpacity;
415 std::optional<int> borderWidth;
416 std::optional<int> borderRadius;
417 std::optional<bool> showZoneNumbers;
418
419 bool isEmpty() const
420 {
421 // shaderParams is only ever populated alongside shaderId, but check it too so
422 // isEmpty() stays honest if a future writer sets the map without the gate.
423 return !shaderId && shaderParams.isEmpty() && shaderPresetId.isEmpty() && !style && !highlightColor
425 && !showZoneNumbers;
426 }
427};
428
441{
442 std::optional<int> maxWindows;
443 std::optional<double> splitRatio;
444 std::optional<int> masterCount;
448 std::optional<int> insertPosition;
450 std::optional<int> overflowBehavior;
453 std::optional<int> dragBehavior;
459 QVariantMap algorithmParams;
460
461 bool isEmpty() const
462 {
463 // algorithmParams is only ever populated alongside algorithmParamTarget, but
464 // check it too so isEmpty() stays honest if a future writer sets it without the
465 // target.
467 && algorithmParamTarget.isEmpty() && algorithmParams.isEmpty();
468 }
469};
470
488{
491 std::optional<double> defaultColumnWidth;
495 std::optional<int> centerFocusedColumn;
497 std::optional<int> defaultColumnDisplay;
500 std::optional<int> insertPosition;
503 std::optional<double> defaultWindowHeight;
504
512 std::optional<bool> alwaysCenterSingleColumn;
513 std::optional<bool> centerShortColumns;
514 std::optional<bool> respectMinimumSize;
515 std::optional<bool> cropStraddlers;
516 std::optional<bool> focusNewWindows;
517 std::optional<bool> smartGaps;
521 std::optional<bool> focusFollowsMouse;
527 std::optional<double> focusFollowsMouseMaxScroll;
531 std::optional<int> stickyWindowHandling;
539 std::optional<int> stripAxis;
540
549 std::optional<bool> tabIndicatorEnabled;
550 std::optional<bool> tabIndicatorHideWhenSingleTab;
551 std::optional<bool> tabIndicatorPlaceWithinColumn;
552 std::optional<int> tabIndicatorGap;
553 std::optional<int> tabIndicatorWidth;
554 std::optional<double> tabIndicatorLength;
555 std::optional<int> tabIndicatorPosition;
556 std::optional<int> tabIndicatorStyle;
557 std::optional<int> tabIndicatorGapsBetweenTabs;
558 std::optional<int> tabIndicatorCornerRadius;
559 std::optional<QString> tabIndicatorActiveColor;
560 std::optional<QString> tabIndicatorInactiveColor;
561 std::optional<QString> tabIndicatorUrgentColor;
567 std::optional<QString> tabIndicatorFontFamily;
568 std::optional<int> tabIndicatorFontWeight;
569 std::optional<bool> tabIndicatorFontItalic;
570 std::optional<bool> tabIndicatorFontUnderline;
571 std::optional<bool> tabIndicatorFontStrikeout;
572
578 std::optional<bool> dropIndicatorEnabled;
579 std::optional<QString> dropIndicatorColor;
580 std::optional<QString> dropIndicatorBorderColor;
581 std::optional<double> dropIndicatorOpacity;
582 std::optional<int> dropIndicatorBorderWidth;
583 std::optional<int> dropIndicatorBorderRadius;
584
585 // The three block-level aggregates below exist for isEmpty() — their
586 // ONLY caller. Earlier docs claimed the daemon consulted them to skip
587 // whole override blocks; it never did (it tests each optional it
588 // consumes directly), so do not add such a gate on the strength of a
589 // predicate existing here.
590
597
607
616
623};
624
636{
637 switch (mode) {
639 return QStringLiteral("snapping");
641 return QStringLiteral("autotile");
643 return QStringLiteral("scrolling");
644 }
645 // Switch is exhaustive over `Mode`. A `static_cast<Mode>(99)` reaching
646 // this line means either (a) a future Mode enum value was added without
647 // a case here — the real guard against that is Qt's -Wswitch diagnostic
648 // at the missing-case site (NOTE: this project's CMake does NOT
649 // promote it to -Werror, so it's a warning at build time, not an
650 // error), or (b) callers fabricated an out-of-range value via cast.
651 // `Q_UNREACHABLE_RETURN` expands to `[[unreachable]] + return`
652 // on modern compilers, so the sentinel below carries through release
653 // builds even when the optimizer assumes the function never reaches
654 // here.
655 //
656 // The sentinel `"invalid"` is rejected by the `DisableEngine`
657 // descriptor's closed-vocabulary validator
658 // (`engineModeOptions().contains(...)`), so a malformed disable rule
659 // fails load loudly. NOTE: `SetEngineMode`'s validator only checks
660 // `hasNonEmptyString` (open-vocabulary by design — see its descriptor
661 // validator in `libs/phosphor-rules/src/ruleaction_builtins_engine.cpp`), so a
662 // malformed assignment rule survives load but is silently coerced
663 // back to Snapping at consumption via
664 // `entryFromRuleMatchActions → modeFromWireString → nullopt`. The
665 // sentinel makes the corruption visible to operators inspecting
666 // rules.json by eye, but is not a load-time gate for the
667 // assignment path.
668 Q_UNREACHABLE_RETURN(QStringLiteral("invalid"));
669}
670
679inline std::optional<AssignmentEntry::Mode> modeFromWireString(const QString& wire)
680{
681 if (wire == QLatin1String("snapping")) {
683 }
684 if (wire == QLatin1String("autotile")) {
686 }
687 if (wire == QLatin1String("scrolling")) {
689 }
690 return std::nullopt;
691}
692
703inline QList<AssignmentEntry::Mode> allModes()
704{
706}
707
708} // namespace PhosphorZones
constexpr QLatin1String ScrollingId
Scrolling has no layout entity, so its whole id is the bare sentinel — it exists so a mode-only Scrol...
Definition LayoutId.h:37
QString makeAutotileId(const QString &algorithmId)
Definition LayoutId.h:76
bool isScrolling(const QString &id)
Definition LayoutId.h:44
bool isAutotile(const QString &id)
Definition LayoutId.h:39
QString extractAlgorithmId(const QString &id)
Extract the algorithm id portion from an autotile preview id.
Definition LayoutId.h:64
Definition IWindowTrackingService.h:24
size_t qHash(const LayoutAssignmentKey &key, size_t seed=0)
Definition AssignmentEntry.h:87
constexpr QLatin1String NoTilingAlgorithm
Reserved value of AssignmentEntry::tilingAlgorithm meaning "thiscontext explicitly uses NO tiling alg...
Definition AssignmentEntry.h:191
std::optional< AssignmentEntry::Mode > modeFromWireString(const QString &wire)
Inverse of modeToWireString.
Definition AssignmentEntry.h:679
QString modeToWireString(AssignmentEntry::Mode mode)
Canonical wire-string for an AssignmentEntry::Mode.
Definition AssignmentEntry.h:635
constexpr QLatin1String NoScrollingTemplate
Reserved value of AssignmentEntry::scrollingTemplateLayout meaning "this context explicitly uses NO s...
Definition AssignmentEntry.h:132
constexpr QLatin1String NoSnappingLayout
Reserved value of AssignmentEntry::snappingLayout meaning "thiscontext explicitly uses NO snapping la...
Definition AssignmentEntry.h:173
QList< AssignmentEntry::Mode > allModes()
Iteration order for every AssignmentEntry::Mode value.
Definition AssignmentEntry.h:703
Explicit per-context assignment entry storing every mode's payload.
Definition AssignmentEntry.h:203
QString snappingLayout
Definition AssignmentEntry.h:229
static AssignmentEntry fromLayoutId(const QString &layoutId)
Create a fresh AssignmentEntry from a layoutId string.
Definition AssignmentEntry.h:345
static AssignmentEntry fromLayoutId(const QString &layoutId, const AssignmentEntry &existing)
Update an existing AssignmentEntry from a layoutId, preserving the "other" field.
Definition AssignmentEntry.h:309
QString activeLayoutId() const
Definition AssignmentEntry.h:255
Mode
Per-context engine selection.
Definition AssignmentEntry.h:213
@ Scrolling
The niri-style scrolling engine (PhosphorScrollEngine): windows form columns on an endless strip per ...
Definition AssignmentEntry.h:226
@ Snapping
Definition AssignmentEntry.h:214
@ Autotile
Definition AssignmentEntry.h:215
QString scrollingTemplateLayout
Id of the native scrolling template (ScrollingTemplate) a Scrolling context uses for its seed bluepri...
Definition AssignmentEntry.h:253
bool operator==(const AssignmentEntry &other) const
Definition AssignmentEntry.h:298
bool isValid() const
True when the entry carries a layout/algorithm PAYLOAD — including the reserved opt-out word,...
Definition AssignmentEntry.h:294
QString tilingAlgorithm
Definition AssignmentEntry.h:230
Mode mode
Definition AssignmentEntry.h:228
Per-context gap override resolved from rules.
Definition AssignmentEntry.h:363
std::optional< int > outerGapLeft
Definition AssignmentEntry.h:369
std::optional< int > outerGapBottom
Definition AssignmentEntry.h:368
std::optional< int > outerGapTop
Definition AssignmentEntry.h:367
bool isEmpty() const
Definition AssignmentEntry.h:372
std::optional< bool > usePerSideOuterGap
Definition AssignmentEntry.h:366
std::optional< int > outerGap
Definition AssignmentEntry.h:365
std::optional< int > innerGap
Definition AssignmentEntry.h:364
std::optional< int > outerGapRight
Definition AssignmentEntry.h:370
Per-context overlay-property overrides resolved from window-rule actions.
Definition AssignmentEntry.h:401
std::optional< int > style
Definition AssignmentEntry.h:409
std::optional< QColor > inactiveColor
Definition AssignmentEntry.h:411
std::optional< int > borderRadius
Definition AssignmentEntry.h:416
std::optional< int > borderWidth
Definition AssignmentEntry.h:415
QVariantMap shaderParams
Definition AssignmentEntry.h:403
std::optional< double > inactiveOpacity
Definition AssignmentEntry.h:414
std::optional< QString > shaderId
Definition AssignmentEntry.h:402
QString shaderPresetId
The named preset shaderParams are deltas against, resolved against shaderId.
Definition AssignmentEntry.h:408
bool isEmpty() const
Definition AssignmentEntry.h:419
std::optional< QColor > highlightColor
Definition AssignmentEntry.h:410
std::optional< QColor > borderColor
Definition AssignmentEntry.h:412
std::optional< double > activeOpacity
Definition AssignmentEntry.h:413
std::optional< bool > showZoneNumbers
Definition AssignmentEntry.h:417
Per-context scrolling parameter overrides resolved from context rules.
Definition AssignmentEntry.h:488
std::optional< bool > tabIndicatorFontUnderline
Definition AssignmentEntry.h:570
std::optional< QString > tabIndicatorInactiveColor
Definition AssignmentEntry.h:560
std::optional< bool > dropIndicatorEnabled
The drop indicator's overrides.
Definition AssignmentEntry.h:578
std::optional< bool > smartGaps
Definition AssignmentEntry.h:517
std::optional< bool > tabIndicatorPlaceWithinColumn
Definition AssignmentEntry.h:551
std::optional< int > centerFocusedColumn
When the viewport re-centres on the focused column (0 = never, 1 = always, 2 = on overflow); the reso...
Definition AssignmentEntry.h:495
std::optional< bool > centerShortColumns
Definition AssignmentEntry.h:513
std::optional< QString > tabIndicatorActiveColor
Definition AssignmentEntry.h:559
std::optional< int > dropIndicatorBorderRadius
px; 0 is square, no sentinel
Definition AssignmentEntry.h:583
std::optional< QString > tabIndicatorFontFamily
The label font, all PAINT.
Definition AssignmentEntry.h:567
std::optional< QString > dropIndicatorBorderColor
Definition AssignmentEntry.h:580
std::optional< int > tabIndicatorPosition
TabIndicatorPosition ints, left 0 … bottom 3.
Definition AssignmentEntry.h:555
bool hasTabIndicatorOverrides() const
True when at least one of the eighteen tab-indicator slots resolved.
Definition AssignmentEntry.h:599
std::optional< int > tabIndicatorFontWeight
CSS scale, 100..900; 400 regular, 700 bold.
Definition AssignmentEntry.h:568
std::optional< int > tabIndicatorStyle
0 = title chips, 1 = segment bar
Definition AssignmentEntry.h:556
std::optional< bool > focusNewWindows
Definition AssignmentEntry.h:516
std::optional< int > tabIndicatorGap
px; NEGATIVE draws the indicator over the window
Definition AssignmentEntry.h:552
std::optional< double > defaultColumnWidth
Width a newly-opened column takes, as a fraction of the work area (0.05-1.0).
Definition AssignmentEntry.h:491
std::optional< int > dropIndicatorBorderWidth
px; 0 is a fill with no edge
Definition AssignmentEntry.h:582
std::optional< int > insertPosition
Where a fresh-opened window's column enters the strip (ScrollInsertPosition ints, right-of-active 0 …...
Definition AssignmentEntry.h:500
std::optional< bool > tabIndicatorHideWhenSingleTab
Definition AssignmentEntry.h:550
std::optional< bool > tabIndicatorEnabled
The tab indicator's overrides, niri's tab-indicator layout block.
Definition AssignmentEntry.h:549
std::optional< int > tabIndicatorGapsBetweenTabs
px
Definition AssignmentEntry.h:557
std::optional< bool > focusFollowsMouse
EFFECT-consumed, unlike its neighbours: the daemon collects the resolved per-screen verdict into a se...
Definition AssignmentEntry.h:521
std::optional< bool > tabIndicatorFontStrikeout
Definition AssignmentEntry.h:571
std::optional< QString > tabIndicatorUrgentColor
Definition AssignmentEntry.h:561
std::optional< bool > respectMinimumSize
Definition AssignmentEntry.h:514
std::optional< int > stickyWindowHandling
StickyWindowHandling ints (treatAsNormal 0 / restoreOnly 1 / ignoreAll 2); the resolver maps the wire...
Definition AssignmentEntry.h:531
std::optional< bool > tabIndicatorFontItalic
Definition AssignmentEntry.h:569
bool hasDropIndicatorOverrides() const
True when at least one drop-indicator slot resolved.
Definition AssignmentEntry.h:592
std::optional< int > defaultColumnDisplay
How a newly-opened column lays its windows out (0 = normal, 1 = tabbed).
Definition AssignmentEntry.h:497
std::optional< int > tabIndicatorCornerRadius
px; -1 is the "fully rounded" sentinel
Definition AssignmentEntry.h:558
std::optional< double > focusFollowsMouseMaxScroll
The cap on the toggle above, as a FRACTION of the viewport's extent along the strip (niri's max-scrol...
Definition AssignmentEntry.h:527
bool isEmpty() const
Definition AssignmentEntry.h:617
std::optional< bool > alwaysCenterSingleColumn
The scrolling BEHAVIOUR toggles, filled by the SetScroll* actions of the same names.
Definition AssignmentEntry.h:512
std::optional< double > tabIndicatorLength
fraction of the column extent
Definition AssignmentEntry.h:554
std::optional< int > stripAxis
Which way the strip runs, in the Scrolling.StripAxis config INTENT space (auto 0 / horizontal 1 / ver...
Definition AssignmentEntry.h:539
std::optional< double > defaultWindowHeight
Height a newly-opened window takes, as a fraction of the work-area height (0.05-1....
Definition AssignmentEntry.h:503
std::optional< double > dropIndicatorOpacity
fill only; the border is always opaque
Definition AssignmentEntry.h:581
std::optional< int > tabIndicatorWidth
px thickness
Definition AssignmentEntry.h:553
std::optional< bool > cropStraddlers
Definition AssignmentEntry.h:515
std::optional< QString > dropIndicatorColor
Definition AssignmentEntry.h:579
bool hasBehaviourOverrides() const
True when at least one of the eight behaviour toggles resolved, or the scroll cap did.
Definition AssignmentEntry.h:611
Per-context autotile parameter overrides resolved from context rules.
Definition AssignmentEntry.h:441
std::optional< int > insertPosition
The AutotileInsertPosition int (0 = End, 1 = AfterFocused, 2 = AsMaster); the resolver maps the wire ...
Definition AssignmentEntry.h:448
std::optional< int > dragBehavior
The AutotileDragBehavior int (0 = Float, 1 = Reorder).
Definition AssignmentEntry.h:453
std::optional< int > masterCount
Definition AssignmentEntry.h:444
std::optional< int > overflowBehavior
The AutotileOverflowBehavior int (0 = Float, 1 = Unlimited).
Definition AssignmentEntry.h:450
QString algorithmParamTarget
A SetAlgorithmParam override: the target algorithm id and the custom-param values to layer over that ...
Definition AssignmentEntry.h:458
std::optional< int > maxWindows
Definition AssignmentEntry.h:442
QVariantMap algorithmParams
Definition AssignmentEntry.h:459
std::optional< double > splitRatio
Definition AssignmentEntry.h:443
bool isEmpty() const
Definition AssignmentEntry.h:461
Key for layout assignment (screen + desktop + activity).
Definition AssignmentEntry.h:33
static LayoutAssignmentKey fromGroupName(const QString &groupName, const QString &prefix)
Parse a "<prefix><screenId>[:Desktop:N][:Activity:uuid]" group name.
Definition AssignmentEntry.h:56
bool operator==(const LayoutAssignmentKey &other) const
Definition AssignmentEntry.h:38
QString screenId
Definition AssignmentEntry.h:34
int virtualDesktop
Definition AssignmentEntry.h:35
QString activity
Definition AssignmentEntry.h:36