Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorRules Namespace Reference

Namespaces

namespace  ActionParam
namespace  ParamKind
namespace  OverlayStyleToken
 Wire tokens for OverrideOverlayStyle's value param — the closed vocabulary the descriptor's validator + enumWireValues, the daemon consumer (LayoutRegistry::resolveContextOverlay), and the settings label layers (enumOptionLabel + the rule-list summary) all read from this single source, so a future rename can never desync the consumers.
namespace  InsertPositionToken
 Wire tokens for SetInsertPosition's value param — the closed vocabulary the descriptor validator, the daemon consumer (LayoutRegistry::resolveContextTilingParams maps token → the AutotileInsertPosition int), and the settings label layers all read from this single source.
namespace  OverflowBehaviorToken
 Wire tokens for SetOverflowBehavior's value param.
namespace  DragBehaviorToken
 Wire tokens for SetDragBehavior's value param.
namespace  CenterFocusedColumnToken
 Wire tokens for SetCenterFocusedColumn's value param — the closed vocabulary the descriptor validator, the daemon consumer (LayoutRegistry::resolveContextScrollingParams maps token → int), and the settings label layers all read from this single source.
namespace  ColumnDisplayToken
 Wire tokens for SetScrollDefaultColumnDisplay's value param — how a column lays its windows out.
namespace  TabIndicatorStyleToken
 Wire tokens for SetTabIndicatorStyle's value param.
namespace  TabIndicatorPositionToken
 Wire tokens for SetTabIndicatorPosition's value param — which column edge the indicator runs along.
namespace  ColumnPlacementToken
 Wire tokens for OpenColumnPlacement's value param — whether an opening window starts its own column or joins the focused one.
namespace  ScrollInsertPositionToken
 Wire tokens for SetScrollInsertPosition's value param — where a fresh column enters the strip.
namespace  StickyWindowHandlingToken
 Wire tokens for SetScrollStickyWindowHandling's value param — how the strip treats a window shown on all desktops.
namespace  StripAxisToken
 Wire tokens for SetScrollStripAxis's value param — which way the matched context's strip runs.
namespace  WindowLayerToken
 Wire tokens for SetWindowLayer's value param — the closed vocabulary the descriptor validator, the KWin-effect consumer (resolveWindowLayer), and the settings label layers all read from this single source.
namespace  BorderColorToken
 Sentinel value a SetBorderColorActive / SetBorderColorInactive value param may carry instead of a hex string, meaning "track the live system accent colour".
namespace  ActionSlot
namespace  ActionType
namespace  ContextRuleBridge
namespace  ExclusionRules
namespace  Detail
namespace  ModeToken
 The closed wire vocabulary of Field::Mode — the placement mode a window is in, or that a context resolves to.
namespace  Tag

Classes

class  MatchExpression
 A composable predicate tree evaluated against a WindowQuery. More...
struct  AspectRatioToken
 One entry of the Field::ScreenAspectRatio vocabulary: the token a rule compares against and the width-over-height ratio it stands for. More...
struct  FieldDescriptor
 Compile-time descriptor for one Field. More...
struct  ValidationIssue
 One semantic compatibility issue between a rule's match and an action. More...
struct  Rule
 One rule — { id, name, enabled, priority, match, actions, managed }. More...
struct  RuleAction
 One action carried by a Rule. More...
struct  ParamSchema
 Structural schema for one action param. More...
struct  ActionDescriptor
 Static metadata describing one registered action type. More...
class  ActionRegistry
 Process-wide registry of action descriptors. More...
class  ResolvedActions
 The output of a resolution — the first action filling each slot. More...
class  RuleEvaluator
 The single evaluation model — resolves a WindowQuery against a RuleSet. More...
class  RuleSet
 An ordered collection of Rules — the persistent rule store. More...
class  RuleStore
 Persistent store for the unified Rule set. More...
class  RuleStoreWatcher
 Opt-in cross-process auto-reload for a RuleStore. More...
struct  WindowQuery
 The evaluation input — an attribute bag matched against a MatchExpression. More...

Enumerations

enum class  Field : int {
  AppId = 0 , WindowClass = 1 , DesktopFile = 2 , WindowRole = 3 ,
  Pid = 4 , Title = 5 , WindowType = 6 , IsSticky = 7 ,
  IsFullscreen = 8 , IsMinimized = 9 , ScreenId = 10 , VirtualDesktop = 11 ,
  Activity = 12 , IsMaximized = 13 , IsFocused = 14 , IsTransient = 15 ,
  IsNotification = 16 , Width = 17 , Height = 18 , KeepAbove = 19 ,
  KeepBelow = 20 , SkipTaskbar = 21 , SkipPager = 22 , SkipSwitcher = 23 ,
  IsModal = 24 , HasDecoration = 25 , IsResizable = 26 , PositionX = 27 ,
  PositionY = 28 , CaptionNormal = 29 , IsFloating = 30 , IsSnapped = 31 ,
  Zone = 32 , IsTiled = 33 , Mode = 34 , TiledWindowCount = 35 ,
  IsMovable = 36 , IsMaximizable = 37 , ScreenOrientation = 38 , ActiveLayout = 39 ,
  ColorScheme = 40 , ScreenWidth = 41 , ScreenHeight = 42 , ScreenAspectRatio = 43
}
 Match fields. More...
enum class  FieldType : int { String , Bool , Int , Enum }
 Value-kind of a field's payload in a WindowQuery. More...
enum class  FieldSource : int { Window , Context }
 Whether a field is a window property or a context attribute. More...
enum class  Operator : int {
  Equals = 0 , Contains = 1 , StartsWith = 2 , EndsWith = 3 ,
  Regex = 4 , AppIdMatches = 5 , GreaterThan = 6 , LessThan = 7
}
 Match operators. More...
enum class  ActionDomain : int { Context = 0 , Window = 1 }
 Which evaluation pass an action contributes to. More...

Functions

QString aspectRatioTokenFor (int width, int height)
 The Field::ScreenAspectRatio token for a width x height screen: the vocabulary entry whose ratio is nearest, measured on a log scale so a portrait screen and its landscape twin sit the same distance from their tokens.
QString orientationTokenFor (int width, int height)
 The Field::ScreenOrientation token for a width x height screen: "portrait" when it is taller than wide and "landscape" otherwise, so a square screen is landscape.
const QSet< Field > & windowSourcedFields ()
 Every Window-sourced field, derived from the table so a new field can never silently miss it.
consteval bool verifyFieldTableOrder ()
QString fieldToString (Field field)
 Canonical lowercase wire string for a Field.
std::optional< Field > fieldFromString (QStringView s)
 Strict parse: an unknown token returns nullopt so the loader can drop the malformed predicate rather than silently coercing typos to a default.
bool fieldIsString (Field field)
 True if field carries a string value (the four string operators and Regex apply to these; numeric/bool fields do not).
bool fieldIsNumeric (Field field)
 True if field carries a numeric value.
bool fieldIsBool (Field field)
 True if field carries a boolean value (window-state flags).
bool fieldIsContext (Field field)
 True if field describes the context a window appears in (screen / virtual desktop / activity / placement mode / tiled-window count / screen orientation / active layout / colour scheme / screen width, height and aspect ratio) rather than a property of the window itself.
QString operatorToString (Operator op)
 Canonical lowercase wire string for an Operator.
std::optional< Operator > operatorFromString (QStringView s)
 Strict parse: an unknown token returns nullopt.
PHOSPHORRULES_EXPORT bool ruleHasLiveEffectAction (const QList< RuleAction > &actions, const std::function< bool(const QString &event)> &eventIsLive)
 True when actions carry at least one Tag::Effect action that can actually take effect, delegating the event verdict to eventIsLive.
PHOSPHORRULES_EXPORT Q_DECLARE_LOGGING_CATEGORY (lcRule)
PHOSPHORRULES_EXPORT Q_DECLARE_LOGGING_CATEGORY (lcRuleEval)

Variables

constexpr int MaxZoneOrdinal = 64
 Upper bound for a SnapToZone zone ordinal (each ActionParam::Zones entry).
constexpr int MaxZoneNameLength = 128
 Upper bound on a SnapToZone zone-name entry (each ActionParam::ZoneNames string), in characters, measured on the TRIMMED name.
constexpr int MaxWorkspaceNameLength = 128
 Upper bound on a RouteToWorkspace target name (ActionParam::TargetWorkspaceName), in characters, measured on the TRIMMED name.
constexpr int MaxWorkspaceIdLength = 128
 Upper bound on a RouteToWorkspace target id (ActionParam::TargetWorkspaceId), in characters, measured on the TRIMMED value, the same grossly-malformed-payload posture as the name bound above.
constexpr int MaxScreenIdLength = 128
 Upper bound on a RouteToScreen target id (ActionParam::TargetScreenId), in characters, measured on the TRIMMED value.
constexpr int MaxFontFamilyLength = 128
 Upper bound on a tab label font FAMILY (SetTabIndicatorFontFamily), in characters, measured on the TRIMMED value.
constexpr int MaxTabGroupNameLength = 64
 Length cap on an OpenTabGroup group name, on the same terms as the font family above (checked on the trimmed value; the descriptor validator and the rule editor's text field both read it).
constexpr int MaxDecorationChainEntries = 64
 Caps on an OverrideDecorationChain payload, mirroring the config path's kMaxChainPacks / kMaxShaderStringChars.
constexpr int MaxChainPackIdLength = 1024
constexpr int MaxShaderPresetIdLength = 1024
 Length cap on a shader preset id carried by a rule action.
constexpr double MaxBorderWidth = 20.0
 Upper bounds for the per-window border appearance overrides (SetBorderWidth / SetBorderRadius), in logical px, mirroring the PhosphorCompositor::DecorationDefaults BorderWidthMax / BorderRadiusMax slider ceilings.
constexpr double MaxBorderRadius = 50.0
constexpr double MinAnimationDurationMs = 50.0
 Bounds for the per-event animation duration override (OverrideAnimationTiming's optional durationMs), in ms.
constexpr double MaxAnimationDurationMs = 2000.0
constexpr double MaxGap = 200.0
 Upper bound for the context-domain gap actions (SetInnerGap, SetOuterGap, and the four per-side variants), in logical px.
constexpr double MinColumnWidthRatio = 0.05
 Bounds for a scrolling-engine work-area FRACTION, width or height.
constexpr double MaxColumnWidthRatio = 1.0
constexpr double MinFocusFollowsMouseMaxScrollRatio = 0.0
 Bounds for the focus-follows-mouse scroll cap, niri's max-scroll-amount, as a FRACTION of the viewport's extent along the strip.
constexpr double MaxFocusFollowsMouseMaxScrollRatio = 1.0
constexpr double MinTabIndicatorGap = -64.0
 Bounds for the tab-indicator numeric slots.
constexpr double MaxTabIndicatorGap = 64.0
constexpr double MinTabIndicatorWidth = 1.0
constexpr double MaxTabIndicatorWidth = 64.0
constexpr double TabIndicatorCornerRadiusPill = -1.0
constexpr double MaxTabIndicatorCornerRadius = 64.0
constexpr double MinTabIndicatorLengthRatio = 0.05
constexpr double MaxTabIndicatorLengthRatio = 1.0
constexpr double MinTabIndicatorFontWeight = 100.0
 Bounds for the tab label's font WEIGHT, the CSS/QFont::Weight scale where 400 is regular and 700 is bold.
constexpr double MaxTabIndicatorFontWeight = 900.0
constexpr double MinDropIndicatorOpacity = 0.0
 Drop-indicator numeric bounds, mirroring the config layer's (ConfigDefaults::scrollingDropIndicator*Min/Max) so a rule cannot author a value the settings page would refuse.
constexpr double MaxDropIndicatorOpacity = 1.0
constexpr double MinDropIndicatorBorderWidth = 0.0
constexpr double MaxDropIndicatorBorderWidth = 10.0
constexpr double MinDropIndicatorBorderRadius = 0.0
constexpr double MaxDropIndicatorBorderRadius = 50.0
constexpr double MinScrollFactor = 0.05
 Bounds for the ScrollFactor multiplier.
constexpr double MaxScrollFactor = 10.0
constexpr int MaxVirtualDesktopOrdinal = 1024
 Upper bound for a RouteToDesktop 1-based virtual-desktop number.
constexpr int FieldCount = static_cast<int>(Field::ScreenAspectRatio) + 1
 The number of distinct Field enumerators.
constexpr QLatin1StringView kModeTokens []
 The complete Field::Mode vocabulary, for callers that validate or enumerate it (a settings picker, a boundary check on a hand-edited value).
constexpr AspectRatioToken kAspectRatioTokens []
 The complete Field::ScreenAspectRatio vocabulary, landscape first and then the portrait forms a rotated monitor reports.
constexpr FieldDescriptor kFieldTable []
 The master field table — indexed by static_cast<int>(field).
constexpr int OperatorCount = static_cast<int>(Operator::LessThan) + 1
 The number of distinct Operator enumerators.

Enumeration Type Documentation

◆ ActionDomain

enum class PhosphorRules::ActionDomain : int
strong

Which evaluation pass an action contributes to.

The evaluator runs two distinct query shapes against the rule set:

  • Context queries (windowless) — issued by the screen/desktop/activity resolution paths to ask "what engine mode / layout does this context use?". They carry only ScreenId / VirtualDesktop / Activity; every window-property predicate evaluates false against them.
  • Window queries — issued per window to ask "what per-window behaviour applies?". They carry both window properties and the window's context.

An action's domain selects which query shape can fill its slot. Authoring a Context action with a match that pins window properties produces a rule that silently never fires (the window predicate fails during context resolution); the validator (Rule::validationIssues()) flags exactly this case so the picker UI and the JSON loader can surface it.

Enumerator
Context 

fills slots consumed by context (screen/desktop/activity) resolution

Window 

fills slots consumed by per-window evaluation

◆ Field

enum class PhosphorRules::Field : int
strong

Match fields.

Each names one attribute of a WindowQuery — either a window property (absent during a windowless context query) or a context attribute (present during context resolution, except the optional tiledWindowCount, screenWidth and screenHeight, each absent when unknown). A predicate over an absent field evaluates false, which is what makes window-property rules naturally inert during context resolution without special-casing.

Enumerator
AppId 
WindowClass 
DesktopFile 
WindowRole 
Pid 
Title 
WindowType 
IsSticky 
IsFullscreen 
IsMinimized 
ScreenId 

context — always present

VirtualDesktop 

context — always present

Activity 

context — always present

IsMaximized 
IsFocused 
IsTransient 
IsNotification 
Width 
Height 
KeepAbove 
KeepBelow 
SkipTaskbar 
SkipPager 
SkipSwitcher 
IsModal 
HasDecoration 
IsResizable 
PositionX 
PositionY 
CaptionNormal 
IsFloating 

floated out of tiling (any placement engine)

IsSnapped 

occupies a snap zone

Zone 

the snap zone's UUID the window occupies

IsTiled 

managed by a tiling-family engine — autotile or scrolling (distinct from IsSnapped)

Mode 

context — current placement mode (snapping / tiling / scrolling)

TiledWindowCount 

context — tiled windows on this screen + desktop

IsMovable 

window can be moved

IsMaximizable 

window can be maximized

ScreenOrientation 

context — "portrait" / "landscape" of the resolving screen

ActiveLayout 

context — the layout id currently resolved for the screen (snap UUID, "autotile:<algo>", or "scrolling:")

ColorScheme 

context — "light" / "dark" system colour scheme, session-wide

ScreenWidth 

context — the resolving screen's width in device pixels

ScreenHeight 

context — the resolving screen's height in device pixels

ScreenAspectRatio 

context — the resolving screen's nearest common aspect ratio ("16:9", "32:9", …)

◆ FieldSource

enum class PhosphorRules::FieldSource : int
strong

Whether a field is a window property or a context attribute.

Enumerator
Window 

absent during windowless context queries

Context 

resolvable during a windowless context query (screen / desktop / activity / mode / screen orientation / active layout / colour scheme / aspect ratio are always set; tiledWindowCount and the screen width and height are optional and absent when unknown)

◆ FieldType

enum class PhosphorRules::FieldType : int
strong

Value-kind of a field's payload in a WindowQuery.

Enumerator
String 

QString-valued (operators: Equals/Contains/StartsWith/EndsWith/Regex).

Bool 

bool-valued (operator: Equals)

Int 

int-valued (operators: Equals/GreaterThan/LessThan)

Enum 

enum-as-int (WindowType) — Equals only

◆ Operator

enum class PhosphorRules::Operator : int
strong

Match operators.

Not every operator is valid against every field — validity is enforced by Predicate::isValid(), not the parser.

Enumerator
Equals 

case-insensitive for strings, numeric for ints, bool for flags

Contains 

substring, case-insensitive (strings)

StartsWith 

prefix, case-insensitive (strings)

EndsWith 

suffix, case-insensitive (strings)

Regex 

QRegularExpression, precompiled & cached per predicate.

AppIdMatches 

segment-aware reverse-DNS match (AppId only)

GreaterThan 

numeric compare (every FieldType::Int field)

LessThan 

numeric compare (every FieldType::Int field)

Function Documentation

◆ aspectRatioTokenFor()

QString PhosphorRules::aspectRatioTokenFor ( int width,
int height )
inline

The Field::ScreenAspectRatio token for a width x height screen: the vocabulary entry whose ratio is nearest, measured on a log scale so a portrait screen and its landscape twin sit the same distance from their tokens.

Empty for a non-positive size, which no token describes. The one derivation every producer (daemon, effect, tests) calls.

◆ fieldFromString()

std::optional< Field > PhosphorRules::fieldFromString ( QStringView s)
inline

Strict parse: an unknown token returns nullopt so the loader can drop the malformed predicate rather than silently coercing typos to a default.

◆ fieldIsBool()

bool PhosphorRules::fieldIsBool ( Field field)
inline

True if field carries a boolean value (window-state flags).

◆ fieldIsContext()

bool PhosphorRules::fieldIsContext ( Field field)
inline

True if field describes the context a window appears in (screen / virtual desktop / activity / placement mode / tiled-window count / screen orientation / active layout / colour scheme / screen width, height and aspect ratio) rather than a property of the window itself.

◆ fieldIsNumeric()

bool PhosphorRules::fieldIsNumeric ( Field field)
inline

True if field carries a numeric value.

◆ fieldIsString()

bool PhosphorRules::fieldIsString ( Field field)
inline

True if field carries a string value (the four string operators and Regex apply to these; numeric/bool fields do not).

◆ fieldToString()

QString PhosphorRules::fieldToString ( Field field)
inline

Canonical lowercase wire string for a Field.

◆ operatorFromString()

std::optional< Operator > PhosphorRules::operatorFromString ( QStringView s)
inline

Strict parse: an unknown token returns nullopt.

◆ operatorToString()

QString PhosphorRules::operatorToString ( Operator op)
inline

Canonical lowercase wire string for an Operator.

◆ orientationTokenFor()

QString PhosphorRules::orientationTokenFor ( int width,
int height )
inline

The Field::ScreenOrientation token for a width x height screen: "portrait" when it is taller than wide and "landscape" otherwise, so a square screen is landscape.

Empty for a non-positive size, like aspectRatioTokenFor. The one derivation every producer (daemon, effect, settings) calls.

◆ Q_DECLARE_LOGGING_CATEGORY() [1/2]

PHOSPHORRULES_EXPORT PhosphorRules::Q_DECLARE_LOGGING_CATEGORY ( lcRule )

◆ Q_DECLARE_LOGGING_CATEGORY() [2/2]

PHOSPHORRULES_EXPORT PhosphorRules::Q_DECLARE_LOGGING_CATEGORY ( lcRuleEval )

◆ ruleHasLiveEffectAction()

PHOSPHORRULES_EXPORT bool PhosphorRules::ruleHasLiveEffectAction ( const QList< RuleAction > & actions,
const std::function< bool(const QString &event)> & eventIsLive )

True when actions carry at least one Tag::Effect action that can actually take effect, delegating the event verdict to eventIsLive.

Splits one question in two so each half sits in the layer that can answer it. The action walk is rule semantics and lives here: which actions are appearance actions, which of those are scoped to an animation event, and which param carries it — all read from the descriptor rather than from a list of type ids that would drift the day a fourth event-scoped action is registered. Whether a given event path can be driven per window is animation taxonomy, which this library does not know, so the caller supplies it.

An action declaring no animationEvent param is not event-scoped at all (a border, an opacity, a layer) and is live without consulting eventIsLive. A null eventIsLive treats every event-scoped action as live, which is the pre-narrowing behaviour.

The KWin window filter uses this to stop force-animating a window past the user's own size and exclusion settings on behalf of a rule that could not have changed anything. Takes the action list rather than a Rule: this header defines RuleAction and is included BY Rule.h, so the higher-level type is not visible here, and the walk needs nothing else from a rule anyway.

◆ verifyFieldTableOrder()

bool PhosphorRules::verifyFieldTableOrder ( )
consteval

◆ windowSourcedFields()

const QSet< Field > & PhosphorRules::windowSourcedFields ( )
inline

Every Window-sourced field, derived from the table so a new field can never silently miss it.

This is the exclusion set the windowless context resolvers pass to MatchExpression::negatesAnyField — an absent window field makes a positive leaf inert (false, by design) but makes a NEGATED leaf match unconditionally, so a context resolver must refuse rules that negate any of these.

Variable Documentation

◆ FieldCount

int PhosphorRules::FieldCount = static_cast<int>(Field::ScreenAspectRatio) + 1
inlineconstexpr

The number of distinct Field enumerators.

Field is a contiguous range [0, FieldCount); bump this whenever an enumerator is added — round-trip tests iterate the range using it as the upper bound.

◆ kAspectRatioTokens

AspectRatioToken PhosphorRules::kAspectRatioTokens[]
inlineconstexpr
Initial value:
= {
{QLatin1StringView("1:1"), 1.0}, {QLatin1StringView("5:4"), 5.0 / 4.0},
{QLatin1StringView("4:3"), 4.0 / 3.0}, {QLatin1StringView("3:2"), 3.0 / 2.0},
{QLatin1StringView("16:10"), 16.0 / 10.0}, {QLatin1StringView("16:9"), 16.0 / 9.0},
{QLatin1StringView("21:9"), 21.0 / 9.0}, {QLatin1StringView("32:10"), 32.0 / 10.0},
{QLatin1StringView("32:9"), 32.0 / 9.0}, {QLatin1StringView("4:5"), 4.0 / 5.0},
{QLatin1StringView("3:4"), 3.0 / 4.0}, {QLatin1StringView("2:3"), 2.0 / 3.0},
{QLatin1StringView("10:16"), 10.0 / 16.0}, {QLatin1StringView("9:16"), 9.0 / 16.0},
{QLatin1StringView("9:21"), 9.0 / 21.0}, {QLatin1StringView("10:32"), 10.0 / 32.0},
{QLatin1StringView("9:32"), 9.0 / 32.0},
}

The complete Field::ScreenAspectRatio vocabulary, landscape first and then the portrait forms a rotated monitor reports.

The names are the ones monitors are sold under, so "21:9" stands for the whole ultrawide family (2560x1080, 3440x1440, 3840x1600) rather than for exactly 2.333.

◆ kFieldTable

FieldDescriptor PhosphorRules::kFieldTable[]
inlineconstexpr

The master field table — indexed by static_cast<int>(field).

◆ kModeTokens

QLatin1StringView PhosphorRules::kModeTokens[]
inlineconstexpr
Initial value:
= {
}
constexpr QLatin1StringView Snapping
Definition MatchTypes.h:109
constexpr QLatin1StringView Tiling
autotile OR scrolling-engine tiling
Definition MatchTypes.h:110
constexpr QLatin1StringView Scrolling
Definition MatchTypes.h:111

The complete Field::Mode vocabulary, for callers that validate or enumerate it (a settings picker, a boundary check on a hand-edited value).

An empty mode is NOT in this set and is not a token: it means the window has no placement mode (it is floating), which no leaf here can express.

◆ MaxAnimationDurationMs

double PhosphorRules::MaxAnimationDurationMs = 2000.0
inlineconstexpr

◆ MaxBorderRadius

double PhosphorRules::MaxBorderRadius = 50.0
inlineconstexpr

◆ MaxBorderWidth

double PhosphorRules::MaxBorderWidth = 20.0
inlineconstexpr

Upper bounds for the per-window border appearance overrides (SetBorderWidth / SetBorderRadius), in logical px, mirroring the PhosphorCompositor::DecorationDefaults BorderWidthMax / BorderRadiusMax slider ceilings.

Hand-mirrored, because phosphor-rules does not link phosphor-compositor; the pair is pinned by static_asserts in the KWin effect's shader_resolve.cpp, which is the one translation unit that sees both headers. Shared so the load-time descriptor validators (ruleaction_builtins_appearance.cpp) and that consumer re-validation stay in lockstep — a programmatically-built or hand-edited payload out of this range is rejected at both boundaries rather than drawn.

The zone-overlay actions keep their own kMaxOverlayBorderWidth / kMaxOverlayBorderRadius (ruleaction_builtins_p.h) rather than reusing this pair. The overlay WIDTH bound is narrower (10 against 20); the radius bounds happen to coincide at 50 today, and stay separate symbols so retuning the window decoration cannot silently move the overlay.

◆ MaxChainPackIdLength

int PhosphorRules::MaxChainPackIdLength = 1024
inlineconstexpr

◆ MaxColumnWidthRatio

double PhosphorRules::MaxColumnWidthRatio = 1.0
inlineconstexpr

◆ MaxDecorationChainEntries

int PhosphorRules::MaxDecorationChainEntries = 64
inlineconstexpr

Caps on an OverrideDecorationChain payload, mirroring the config path's kMaxChainPacks / kMaxShaderStringChars.

Hand-mirrored for the same reason as the border bounds below: phosphor-rules does not link the settings layer.

These matter more than the config twins they mirror. A rule chain REPLACES the config chain wholesale, AFTER every config-side bound has run, and lands in the compositor's per-entry fold where each entry costs a draw and a buffer slot every frame — so this validator is the only thing standing between a hand-edited rules.json and an unbounded per-frame cost on every matched window.

◆ MaxDropIndicatorBorderRadius

double PhosphorRules::MaxDropIndicatorBorderRadius = 50.0
inlineconstexpr

◆ MaxDropIndicatorBorderWidth

double PhosphorRules::MaxDropIndicatorBorderWidth = 10.0
inlineconstexpr

◆ MaxDropIndicatorOpacity

double PhosphorRules::MaxDropIndicatorOpacity = 1.0
inlineconstexpr

◆ MaxFocusFollowsMouseMaxScrollRatio

double PhosphorRules::MaxFocusFollowsMouseMaxScrollRatio = 1.0
inlineconstexpr

◆ MaxFontFamilyLength

int PhosphorRules::MaxFontFamilyLength = 128
inlineconstexpr

Upper bound on a tab label font FAMILY (SetTabIndicatorFontFamily), in characters, measured on the TRIMMED value.

Same posture and same number as MaxZoneNameLength: a grossly-malformed-payload guard, not a real limit — installed family names run well under it, and the value normally arrives from a QFontDatabase enumeration rather than being typed. It exists because this is the one free-form string in the tab-indicator family, so without it a hand-edited rules file could carry an unbounded one through the resolver and onto the wire. EMPTY stays legal and is NOT a length failure: it is the documented "use the system font" value. Consumers: the descriptor validator (ruleaction_builtins_indicators.cpp), the settings-layer config validator for both family keys (settingsschema_scrolling.cpp and settingsschema.cpp), and the value ParamSchema max, which the rule editor's text field reads so it cannot author a value the validator would then drop.

◆ MaxGap

double PhosphorRules::MaxGap = 200.0
inlineconstexpr

Upper bound for the context-domain gap actions (SetInnerGap, SetOuterGap, and the four per-side variants), in logical px.

Equal to PlasmaZones::Defaults::MaxGap / PhosphorEngine::GeometryDefaults::MaxGap (pinned by a static_assert in plasmazones/src/daemon/daemon.cpp). This is the range the rule editor OFFERS: it is published as the parameter's schema max, which is the spin box's ceiling, and every placement arm clamps a resolved gap to it, so a larger value could never be drawn anyway.

It is deliberately NOT the LOAD bound. That stays looser (kMaxGap, ruleaction_builtins_p.h) so a rule authored when the editor offered a wider range still loads: a rejected action is dropped, taking its whole rule with it when it was the only one. The visible consequence of the asymmetry is that such a stored value displays clamped to this ceiling in the editor, and collapses to it if the user nudges that spin box.

◆ MaxScreenIdLength

int PhosphorRules::MaxScreenIdLength = 128
inlineconstexpr

Upper bound on a RouteToScreen target id (ActionParam::TargetScreenId), in characters, measured on the TRIMMED value.

Same grossly-malformed-payload posture as the name bounds above: a real canonical id (Manuf:Model:Serial, optionally /CONNECTOR-suffixed, or a virtual screen id) runs well under it.

The ONE screen-id length bound. Besides the descriptor validator, the app's other screen-id boundaries (the named-workspace output pin, the per-screen settings D-Bus setters) and any reader that has to judge a payload the way the loader does (the settings rule summary, for one) measure against it, so an id one boundary accepts is an id a rule can name. Not published as a ParamSchema max: the editor picks the id from the live monitor list rather than typing it.

◆ MaxScrollFactor

double PhosphorRules::MaxScrollFactor = 10.0
inlineconstexpr

◆ MaxShaderPresetIdLength

int PhosphorRules::MaxShaderPresetIdLength = 1024
inlineconstexpr

Length cap on a shader preset id carried by a rule action.

Every other free-form string in this vocabulary is bounded; an over-long id is inert (it resolves to no preset) but the asymmetry is the kind that drifts.

◆ MaxTabGroupNameLength

int PhosphorRules::MaxTabGroupNameLength = 64
inlineconstexpr

Length cap on an OpenTabGroup group name, on the same terms as the font family above (checked on the trimmed value; the descriptor validator and the rule editor's text field both read it).

Empty is NOT legal here: a group with no name names nothing, so the validator rejects it rather than letting an unnamed group silently gather every matched window.

◆ MaxTabIndicatorCornerRadius

double PhosphorRules::MaxTabIndicatorCornerRadius = 64.0
inlineconstexpr

◆ MaxTabIndicatorFontWeight

double PhosphorRules::MaxTabIndicatorFontWeight = 900.0
inlineconstexpr

◆ MaxTabIndicatorGap

double PhosphorRules::MaxTabIndicatorGap = 64.0
inlineconstexpr

◆ MaxTabIndicatorLengthRatio

double PhosphorRules::MaxTabIndicatorLengthRatio = 1.0
inlineconstexpr

◆ MaxTabIndicatorWidth

double PhosphorRules::MaxTabIndicatorWidth = 64.0
inlineconstexpr

◆ MaxVirtualDesktopOrdinal

int PhosphorRules::MaxVirtualDesktopOrdinal = 1024
inlineconstexpr

Upper bound for a RouteToDesktop 1-based virtual-desktop number.

KWin tops out far below this in practice; the cap exists only to reject a grossly malformed hand-edited payload and to keep the validator's integrality check from narrowing an out-of-range double to int (UB). The descriptor validator (ruleaction_builtins_engine.cpp) enforces the bound once, at load; downstream consumers re-check the 1-based lower bound (and the label layer re-checks this ceiling defensively), trusting the load-time clamp for the rest.

◆ MaxWorkspaceIdLength

int PhosphorRules::MaxWorkspaceIdLength = 128
inlineconstexpr

Upper bound on a RouteToWorkspace target id (ActionParam::TargetWorkspaceId), in characters, measured on the TRIMMED value, the same grossly-malformed-payload posture as the name bound above.

The id is machine-written when the declaration is created, so a real one runs well under it.

◆ MaxWorkspaceNameLength

int PhosphorRules::MaxWorkspaceNameLength = 128
inlineconstexpr

Upper bound on a RouteToWorkspace target name (ActionParam::TargetWorkspaceName), in characters, measured on the TRIMMED name.

Same posture as MaxZoneNameLength above: a grossly-malformed-payload guard, not a real limit. A hand-edited rules file may carry anything, so the bound only stops an unbounded string riding through the loader.

It must stay at or above the app's cap on a DECLARED workspace name (ConfigDefaults::WorkspaceNameMaxLength), or a rule naming a workspace the user could declare would fail to load and be dropped. This library cannot see that constant, so the app pins the ordering with a static_assert where both are visible.

The descriptor validator trims before measuring, so it and the daemon's trimmed-name resolution measure the same string. It is published as the workspaceName ParamSchema max, which the rule editor reads, and any other reader that has to judge a payload the way the loader does (the settings rule summary, for one) measures against this constant.

◆ MaxZoneNameLength

int PhosphorRules::MaxZoneNameLength = 128
inlineconstexpr

Upper bound on a SnapToZone zone-name entry (each ActionParam::ZoneNames string), in characters, measured on the TRIMMED name.

This is deliberately permissive: the layout editor caps zone names at 40 (MaxLayoutNameLength in the app's constants.h, which this LGPL lib cannot include), but a hand-edited or legacy layout may carry a longer one, so the bound here is only a grossly-malformed-payload guard in the spirit of MaxZoneOrdinal, not the editor's limit. Consumers: the descriptor validator, the daemon's placement reader, and the settings authoring layer (parseZoneNameList and the rule-list summary apply it in C++; it is also published as the zoneNames ParamSchema max so the editor can read it from the schema).

◆ MaxZoneOrdinal

int PhosphorRules::MaxZoneOrdinal = 64
inlineconstexpr

Upper bound for a SnapToZone zone ordinal (each ActionParam::Zones entry).

No real layout has anywhere near this many zones (the snapToZone1..9 shortcuts only reach 9); the cap exists purely to reject a grossly malformed hand-edited payload AND to keep the load-time validator's integrality check from narrowing an out-of-range double to int (which is UB). Shared by the descriptor validator (ruleaction_builtins_engine.cpp), the daemon's placement reader (windowtrackingadaptor/rules_placement.cpp placementTargetsOf), the v3→v4 migration, and the settings editor (published to QML as the zoneOrdinals ParamSchema max) so all of them stay in lockstep.

◆ MinAnimationDurationMs

double PhosphorRules::MinAnimationDurationMs = 50.0
inlineconstexpr

Bounds for the per-event animation duration override (OverrideAnimationTiming's optional durationMs), in ms.

Hand-mirrored from PhosphorAnimation::Limits::Min/MaxAnimationDurationMs, which phosphor-rules does not link; pinned by static_asserts in the KWin effect's shader_resolve.cpp, the one translation unit that sees both. These are the numbers the consumer actually honours, since it qBounds an incoming duration to them. Only the MAX is published as the descriptor's schema ceiling, so the editor cannot offer a duration the effect would quietly cut; the schema FLOOR stays 0, because 0 is the disengaged sentinel. Min exists to pin the consumer's clamp, not to bound the editor, so a duration of 1 to 49 is authorable and rounds up at the consumer.

◆ MinColumnWidthRatio

double PhosphorRules::MinColumnWidthRatio = 0.05
inlineconstexpr

Bounds for a scrolling-engine work-area FRACTION, width or height.

The pair is named for the column-width action it was introduced with, but it now bounds four actions across both axes: SetScrollDefaultColumnWidth and OpenColumnWidth against the work-area WIDTH, SetScrollDefaultWindowHeight and OpenWindowHeight against its HEIGHT. One pair, because the axes share the same "at least a sliver, at most the whole work area" policy. Shared for the same lockstep reason as the border bounds above: the load-time descriptor validators (via the private percent pair in ruleaction_builtins_p.h), the zones-layer context resolver (layoutregistry_contextparams.cpp), and the per-window open-params consumer (windowtrackingadaptor/rules.cpp) all validate against these — a private copy in any of them would drift by hand-mirroring. A column or window may legitimately take the whole work area, so the upper bound is 1.0.

◆ MinDropIndicatorBorderRadius

double PhosphorRules::MinDropIndicatorBorderRadius = 0.0
inlineconstexpr

◆ MinDropIndicatorBorderWidth

double PhosphorRules::MinDropIndicatorBorderWidth = 0.0
inlineconstexpr

◆ MinDropIndicatorOpacity

double PhosphorRules::MinDropIndicatorOpacity = 0.0
inlineconstexpr

Drop-indicator numeric bounds, mirroring the config layer's (ConfigDefaults::scrollingDropIndicator*Min/Max) so a rule cannot author a value the settings page would refuse.

Both floors are 0 and neither is a sentinel: a zero border width is a fill with no edge, and a zero radius is a square corner. Deliberately NOT shared with the tab-indicator constants above, whose ranges are wider (radius 64 against 50, width 64 against 10): the two families are tuned independently, so tying them would make retuning one silently move the other.

◆ MinFocusFollowsMouseMaxScrollRatio

double PhosphorRules::MinFocusFollowsMouseMaxScrollRatio = 0.0
inlineconstexpr

Bounds for the focus-follows-mouse scroll cap, niri's max-scroll-amount, as a FRACTION of the viewport's extent along the strip.

Installed here for the same lockstep reason as the pair above, though the readers differ: the zones-layer context resolver checks the pair, while the descriptor validator checks only the CEILING, because hasNumberInRange carries its own zero floor and the minimum here simply restates it. The rules-model label renderer reads the pair too.

The ceiling is 1.0 and it means "no cap" as a SENTINEL rather than as a measured limit — see ScrollEngine::windowsBeyondFocusScrollLimit, where a recentring step can genuinely cost more than one viewport. The floor is a real setting rather than a disabled one, meaning focus only follows the pointer onto windows already fully in view.

◆ MinScrollFactor

double PhosphorRules::MinScrollFactor = 0.05
inlineconstexpr

Bounds for the ScrollFactor multiplier.

Shared by the load-time descriptor validator (ruleaction_builtins_appearance.cpp) and the KWin-effect consumer re-validation (shader_resolve.cpp's resolveScrollFactor) so the two stay in lockstep — the usual reject-at-both-boundaries stance. The floor mirrors niri's practical range (a factor below 1/20th makes scrolling read as broken); the ceiling keeps a hand-edited payload from turning one wheel notch into a page-length jump.

◆ MinTabIndicatorFontWeight

double PhosphorRules::MinTabIndicatorFontWeight = 100.0
inlineconstexpr

Bounds for the tab label's font WEIGHT, the CSS/QFont::Weight scale where 400 is regular and 700 is bold.

Kept beside the other tab-indicator bounds and shared by the same two consumers, so the descriptor validator and the context resolver check one number rather than two hand-mirrored ones.

Inside this library it is one pair; outside it the SAME 100..900 band is mirrored at three more sites, so widening it means editing four places. The config layer owns the canonical pair (ConfigDefaults::scrollingTabIndicatorFontWeight{Min,Max}() in plasmazones/src/config/configdefaults_scrolling.h). The KWin effect mirrors it twice: kFontWeightMin / kFontWeightMax in plasmazones/kwin-effect/tilinghandler/scrolltabs.cpp name it, and the global loader in plasmazones/kwin-effect/plasmazoneseffect/daemon_settings_scrolltabs.cpp spells it as bare literals.

The floor is 100, not 0 — a zero weight is not a lighter font, it is an out-of-scale value the font stack rounds to whatever it likes. So this pair takes the EXPLICIT-FLOOR validator helper, like the signed bounds above, even though both ends are positive.

The family beside it has no bounds constant because it is a free string, and the three style FLAGS have none because they are booleans. There is no font-SIZE pair at all: the painter fits the label to the pill thickness.

◆ MinTabIndicatorGap

double PhosphorRules::MinTabIndicatorGap = -64.0
inlineconstexpr

Bounds for the tab-indicator numeric slots.

Installed here, next to the column-width pair and for the same reason: the descriptor validators (ruleaction_builtins_indicators.cpp) and the per-context consumer (layoutregistry_contextparams.cpp) both check against these, so a private copy in either would drift by hand-mirroring.

Two floors are NEGATIVE and neither is a mistake. A negative GAP draws the indicator on top of the window, which is niri's documented behaviour. The corner-radius floor is the config layer's "fully rounded" SENTINEL, not a real negative radius; the validators admit the whole [-1, max] range rather than carving out (-1, 0), because every consumer rounds to an int and both -1 and 0 are meaningful there.

MaxTabIndicatorGap bounds TWO slots: the indicator-to-window gap and the between-tabs gap (which floors at 0 rather than at the negative). Moving it moves both.

◆ MinTabIndicatorLengthRatio

double PhosphorRules::MinTabIndicatorLengthRatio = 0.05
inlineconstexpr

◆ MinTabIndicatorWidth

double PhosphorRules::MinTabIndicatorWidth = 1.0
inlineconstexpr

◆ OperatorCount

int PhosphorRules::OperatorCount = static_cast<int>(Operator::LessThan) + 1
inlineconstexpr

The number of distinct Operator enumerators.

Operator is a contiguous range [0, OperatorCount); bump this whenever an enumerator is added.

◆ TabIndicatorCornerRadiusPill

double PhosphorRules::TabIndicatorCornerRadiusPill = -1.0
inlineconstexpr