Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
RuleAction.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
6#include <QLatin1StringView>
7#include <QHash>
8#include <QJsonObject>
9#include <QString>
10#include <QStringList>
11
12#include <functional>
13#include <optional>
14
15#include "phosphorrules_export.h"
16
17// The action VOCABULARY — type ids, param keys with their shared validation
18// bounds and token sets, and slot ids — lives in three companion headers,
19// split off purely for file size. They are included here rather than left to
20// the consumer: this header is the one every consumer already includes, and
21// the machinery below is unusable without the vocabulary, so the split must
22// not become an include-ordering puzzle at 40-odd call sites.
23#include "ActionParams.h"
24#include "ActionSlots.h"
25#include "ActionTypes.h"
26
27namespace PhosphorRules {
28
46enum class ActionDomain : int {
47 Context = 0,
48 Window = 1,
49};
50
64struct PHOSPHORRULES_EXPORT RuleAction
65{
66 QString type;
72 QJsonObject params;
73
74 bool operator==(const RuleAction& other) const
75 {
76 return type == other.type && params == other.params;
77 }
78 bool operator!=(const RuleAction& other) const
79 {
80 return !(*this == other);
81 }
82
83 QJsonObject toJson() const;
84
87 static std::optional<RuleAction> fromJson(const QJsonObject& obj);
88};
89
126struct PHOSPHORRULES_EXPORT ParamSchema
127{
128 QString key{};
129 QString kind{};
130 std::optional<double> min{};
131 std::optional<double> max{};
132 std::optional<double> scale{};
139 std::optional<double> defaultDisplay{};
140 QStringList enumWireValues{};
141};
142
143// ── Action tags — structural metadata for consumer-side filtering ──────────
144// Tags classify actions into overlapping behavioural groups. Consumers use
145// `ActionRegistry::hasTag()` / `typesWithTag()` instead of maintaining
146// parallel type-list helpers. Adding a tag to a new action is one descriptor
147// field edit; no consumer call-site changes. Tags compose via intersection:
148// e.g. the animation-override actions (the 3 Override* actions, NOT
149// ExcludeAnimations) are exactly Tag::Animation ∩ Tag::Effect.
150//
151// RETAINED PUBLIC API: Tag::Border, Tag::Gap, Tag::LayoutEngine and
152// Tag::Overlay currently have no in-tree reader, and `typesWithTag()` has no
153// in-tree call site (tests included) — every consumer that could use them
154// happens to filter by slot instead. They stay for the same reason
155// PhosphorZones::LayoutAssignmentKey does (AssignmentEntry.h): this is an
156// installed LGPL library header whose point is third-party linkage, the tag
157// vocabulary is the documented classification of the action set, and removing
158// an exported constant or query is a source break for consumers we do not
159// control. Deliberately kept, not overlooked.
160namespace Tag {
171inline constexpr QLatin1StringView Effect{"effect"};
184inline constexpr QLatin1StringView EffectVerdict{"effectVerdict"};
185inline constexpr QLatin1StringView Border{"border"};
186inline constexpr QLatin1StringView Animation{"animation"};
187inline constexpr QLatin1StringView LayoutEngine{"layoutEngine"};
188inline constexpr QLatin1StringView Gap{"gap"};
193inline constexpr QLatin1StringView Overlay{"overlay"};
194} // namespace Tag
195
215struct PHOSPHORRULES_EXPORT ActionDescriptor
216{
221 using SlotResolver = std::function<QString(const QJsonObject& params)>;
222 using Validator = std::function<bool(const QJsonObject& params)>;
223
224 QString type;
234 bool terminal = false;
240 QStringList allowedKeys{};
249 QList<ParamSchema> params{};
255 bool userAuthorable = true;
258 QString category{};
266 QStringList tags{};
267};
268
277class PHOSPHORRULES_EXPORT ActionRegistry
278{
279public:
281 static ActionRegistry& instance();
282
286
293 bool unregisterAction(const QString& type);
294
296 bool isRegistered(const QString& type) const;
297
299 std::optional<ActionDescriptor> descriptor(const QString& type) const;
300
303 QString slotFor(const RuleAction& action) const;
304
306 bool isTerminal(const RuleAction& action) const;
307
309 bool validate(const RuleAction& action) const;
310
316 ActionDomain domainFor(const RuleAction& action) const;
317
319 QStringList registeredTypes() const;
320
322 bool hasTag(const QString& type, QLatin1StringView tag) const;
323
325 QStringList typesWithTag(QLatin1StringView tag) const;
326
338 QString paramKeyOfKind(const QString& type, QLatin1StringView kind) const;
339
340private:
341 ActionRegistry();
342 void registerBuiltins();
343 // registerBuiltins() is split across three TUs for file-size; these register
344 // the descriptor-table thirds in order (engine/window-management/
345 // animation/overlay, then per-window appearance/gap/autotile-param/
346 // scrolling-param, then the tab- and drop-indicator families). Defined in
347 // ruleaction_builtins_engine.cpp / ruleaction_builtins_appearance.cpp /
348 // ruleaction_builtins_indicators.cpp.
349 void registerBuiltinsEngine();
350 void registerBuiltinsAppearance();
351 void registerBuiltinsIndicators();
352
353 QHash<QString, ActionDescriptor> m_descriptors;
354};
355
378PHOSPHORRULES_EXPORT bool ruleHasLiveEffectAction(const QList<RuleAction>& actions,
379 const std::function<bool(const QString& event)>& eventIsLive);
380
381} // namespace PhosphorRules
static ActionRegistry & instance()
The shared process-wide registry, pre-populated with the built-ins.
bool hasTag(const QString &type, QLatin1StringView tag) const
True if the descriptor for type carries tag.
QString paramKeyOfKind(const QString &type, QLatin1StringView kind) const
The wire param key whose schema kind is kind for type, or an empty string when type declares no such ...
bool isRegistered(const QString &type) const
True if type names a registered action.
QStringList registeredTypes() const
All registered type ids — for UI enumeration / tests.
bool validate(const RuleAction &action) const
True if action passes its descriptor's validation.
std::optional< ActionDescriptor > descriptor(const QString &type) const
The descriptor for type, or nullopt if unregistered.
bool unregisterAction(const QString &type)
Remove a previously-registered descriptor.
QString slotFor(const RuleAction &action) const
The slot a concrete action resolves to, or an empty string if the type is unregistered or its descrip...
ActionDomain domainFor(const RuleAction &action) const
The evaluation domain action contributes to, or ActionDomain::Window for an unregistered type (the co...
QStringList typesWithTag(QLatin1StringView tag) const
All registered type ids whose descriptor carries tag.
void registerAction(const ActionDescriptor &descriptor)
Register (or replace) a descriptor.
bool isTerminal(const RuleAction &action) const
True if action is a terminal action (one of the Exclude family).
Definition RuleAction.h:160
constexpr QLatin1StringView Animation
Definition RuleAction.h:186
constexpr QLatin1StringView Effect
Actions consumed by the KWin effect's rule set (shader manager + border appearance + window stacking ...
Definition RuleAction.h:171
constexpr QLatin1StringView Border
Definition RuleAction.h:185
constexpr QLatin1StringView Gap
Definition RuleAction.h:188
constexpr QLatin1StringView Overlay
Context-domain overlay-property overrides (overlay shader / style).
Definition RuleAction.h:193
constexpr QLatin1StringView LayoutEngine
Definition RuleAction.h:187
constexpr QLatin1StringView EffectVerdict
Effect-consumed one-shot verdicts that are NOT appearance overrides and must not be cancelled by Excl...
Definition RuleAction.h:184
Definition ActionParams.h:25
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,...
@ Context
resolvable during a windowless context query (screen / desktop / activity / mode / screen orientation...
Definition MatchTypes.h:201
@ Window
absent during windowless context queries
Definition MatchTypes.h:200
ActionDomain
Which evaluation pass an action contributes to.
Definition RuleAction.h:46
@ Window
fills slots consumed by per-window evaluation
Definition RuleAction.h:48
Static metadata describing one registered action type.
Definition RuleAction.h:216
QStringList allowedKeys
The complete set of param keys this action type accepts.
Definition RuleAction.h:240
SlotResolver slotFor
Resolves the slot for a concrete action's params.
Definition RuleAction.h:227
Validator validate
Returns true if params is a well-formed payload for this type.
Definition RuleAction.h:229
int displayOrder
Intended sort key within a category (lower = earlier).
Definition RuleAction.h:262
QList< ParamSchema > params
Structural per-param schema consumed by the editor UI.
Definition RuleAction.h:249
QString type
the action type id
Definition RuleAction.h:224
std::function< bool(const QJsonObject &params)> Validator
Definition RuleAction.h:222
bool terminal
Terminal actions (the Exclude family: Exclude / ExcludePlacement / ExcludeAnimations / ExcludeDecorat...
Definition RuleAction.h:234
QStringList tags
Behavioural tags for consumer-side filtering.
Definition RuleAction.h:266
ActionDomain domain
Which evaluation pass the action contributes to — see ActionDomain.
Definition RuleAction.h:245
QString category
UI grouping category for the action-type picker.
Definition RuleAction.h:258
bool userAuthorable
True when the action should appear in the editor's "add rule" type picker.
Definition RuleAction.h:255
std::function< QString(const QJsonObject &params)> SlotResolver
Function shape that resolves the slot for a concrete action's params.
Definition RuleAction.h:221
Structural schema for one action param.
Definition RuleAction.h:127
std::optional< double > max
inclusive upper bound, in display units
Definition RuleAction.h:131
QStringList enumWireValues
wire values for kind == "enum"; empty otherwise
Definition RuleAction.h:140
QString key
wire param key in RuleAction::params
Definition RuleAction.h:128
std::optional< double > min
inclusive lower bound, in display units
Definition RuleAction.h:130
QString kind
UI kind hint — see struct doc.
Definition RuleAction.h:129
std::optional< double > defaultDisplay
Initial display-unit value for the editor when a fresh rule is created.
Definition RuleAction.h:139
std::optional< double > scale
stored = display * scale; nullopt for unscaled kinds
Definition RuleAction.h:132
One action carried by a Rule.
Definition RuleAction.h:65
QJsonObject toJson() const
bool operator==(const RuleAction &other) const
Definition RuleAction.h:74
static std::optional< RuleAction > fromJson(const QJsonObject &obj)
Strict loader — validates against the ActionRegistry; returns nullopt for an unregistered type or par...
bool operator!=(const RuleAction &other) const
Definition RuleAction.h:78
QJsonObject params
Action-specific payload.
Definition RuleAction.h:72
QString type
registered action type id (e.g.
Definition RuleAction.h:66