Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IPlacementEngine.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 "phosphorengine_export.h"
7
12
13#include <QPoint>
14#include <QRect>
15#include <QSize>
16#include <QSet>
17#include <QString>
18#include <QStringList>
19#include <QVariantMap>
20
21#include <functional>
22#include <optional>
23
24class QObject;
25
26namespace PhosphorEngine {
27
28class DesktopRemap;
30
43class PHOSPHORENGINE_EXPORT IPlacementEngine
44{
45protected:
46 IPlacementEngine() = default;
47
48public:
49 virtual ~IPlacementEngine() = default;
50 // Polymorphic base: never copied or moved (every concrete engine is a
51 // QObject anyway; this makes slicing a compile error at the interface).
54
55 // ═══════════════════════════════════════════════════════════════════════════
56 // Screen ownership
57 // ═══════════════════════════════════════════════════════════════════════════
58
60 virtual bool isActiveOnScreen(const QString& screenId) const = 0;
61
62 // ═══════════════════════════════════════════════════════════════════════════
63 // Window lifecycle
64 // ═══════════════════════════════════════════════════════════════════════════
65
67 virtual void windowOpened(const QString& windowId, const QString& screenId, int minWidth = 0,
68 int minHeight = 0) = 0;
69
82 void windowOpened(const QString& windowId, const QString& screenId)
83 {
84 windowOpened(windowId, screenId, 0, 0);
85 }
86
101 virtual bool claimCrossScreenReopen(const QString& windowId, const QString& openingScreenId, int minWidth = 0,
102 int minHeight = 0)
103 {
104 Q_UNUSED(windowId)
105 Q_UNUSED(openingScreenId)
106 Q_UNUSED(minWidth)
107 Q_UNUSED(minHeight)
108 return false;
109 }
110
113 virtual void noteCrossScreenClaimsExhausted(const QString& windowId, bool exhausted)
114 {
115 Q_UNUSED(windowId)
116 Q_UNUSED(exhausted)
117 }
118
139 virtual QString heldScreenForWindow(const QString& windowId) const
140 {
141 Q_UNUSED(windowId)
142 return {};
143 }
144
166 virtual std::optional<PlacementStateKey> heldKeyForWindow(const QString& windowId) const
167 {
168 Q_UNUSED(windowId)
169 return std::nullopt;
170 }
171
183 virtual void beginArrivalBurst()
184 {
185 }
186 virtual void endArrivalBurst()
187 {
188 }
189
197 virtual void windowClosed(const QString& windowId) = 0;
198
202 virtual void windowFocused(const QString& windowId, const QString& screenId) = 0;
203
204 // ═══════════════════════════════════════════════════════════════════════════
205 // Float management (explicit window ID)
206 //
207 // These take a concrete window ID — used by the D-Bus adaptor and
208 // engine-internal paths that already know which window to act on.
209 // toggleFocusedFloat() in the Navigation section is the user-intent
210 // entry point that resolves the focused window from NavigationContext.
211 // ═══════════════════════════════════════════════════════════════════════════
212
214 virtual void toggleWindowFloat(const QString& windowId, const QString& screenId) = 0;
215
229 virtual void setWindowFloat(const QString& windowId, bool shouldFloat, const QString& screenId = QString()) = 0;
230
231 // ═══════════════════════════════════════════════════════════════════════════
232 // Navigation (user intents)
233 // ═══════════════════════════════════════════════════════════════════════════
234
236 virtual void focusInDirection(const QString& direction, const NavigationContext& ctx) = 0;
237
239 virtual void moveFocusedInDirection(const QString& direction, const NavigationContext& ctx) = 0;
240
248 virtual void spanFocusedInDirection(const QString& direction, const NavigationContext& ctx)
249 {
250 Q_UNUSED(direction)
251 Q_UNUSED(ctx)
252 }
253
266 virtual void switchFocusBetweenFloatingAndTiling(const QString& screenId)
267 {
268 Q_UNUSED(screenId)
269 }
270
272 virtual void swapFocusedInDirection(const QString& direction, const NavigationContext& ctx) = 0;
273
275 virtual void moveFocusedToPosition(int position, const NavigationContext& ctx) = 0;
276
278 virtual void rotateWindows(bool clockwise, const NavigationContext& ctx) = 0;
279
281 virtual void reapplyLayout(const NavigationContext& ctx) = 0;
282
287 virtual void snapAllWindows(const NavigationContext& ctx) = 0;
288
290 virtual void cycleFocus(bool forward, const NavigationContext& ctx) = 0;
291
297 virtual void pushToEmptyZone(const NavigationContext& ctx) = 0;
298
300 virtual void restoreFocusedWindow(const NavigationContext& ctx) = 0;
301
303 virtual void toggleFocusedFloat(const NavigationContext& ctx) = 0;
304
305 // ═══════════════════════════════════════════════════════════════════════════
306 // OPTIONAL: Screen management (override if engine tracks multi-screen state)
307 // ═══════════════════════════════════════════════════════════════════════════
308
309 virtual QSet<QString> activeScreens() const
310 {
311 return {};
312 }
313 virtual void setActiveScreens(const QSet<QString>& screens)
314 {
315 Q_UNUSED(screens)
316 }
317
318 // ═══════════════════════════════════════════════════════════════════════════
319 // OPTIONAL: Window-appearance re-application (compositor reconnect)
320 // ═══════════════════════════════════════════════════════════════════════════
321
334 {
335 }
336
337 // ═══════════════════════════════════════════════════════════════════════════
338 // OPTIONAL: Unified placement capture/restore (engine-agnostic restore model)
339 //
340 // The single seam for the unified WindowPlacement restore model. An engine
341 // implements exactly these two methods to participate in save+restore; a new
342 // engine (e.g. the scrolling engine) needs no core/schema change — it keys
343 // its own EngineSlot (state token + slot reference) under its engineId() in the
344 // single per-window record and reads/writes the shared freeGeometryByScreen.
345 // ═══════════════════════════════════════════════════════════════════════════
346
357 virtual std::optional<WindowPlacement> capturePlacement(const QString& windowId) const
358 {
359 Q_UNUSED(windowId)
360 return std::nullopt;
361 }
362
378 virtual bool restorePlacement(const WindowPlacement& placement, const QString& screenId)
379 {
380 Q_UNUSED(placement)
381 Q_UNUSED(screenId)
382 return false;
383 }
384
385 // ═══════════════════════════════════════════════════════════════════════════
386 // OPTIONAL: Window ordering and focus (mode-transition capture and seed)
387 // ═══════════════════════════════════════════════════════════════════════════
388
389 virtual QStringList managedWindowOrder(const QString& screenId) const
390 {
391 Q_UNUSED(screenId)
392 return {};
393 }
394 virtual void setInitialWindowOrder(const QString& screenId, const QStringList& windowIds)
395 {
396 Q_UNUSED(screenId)
397 Q_UNUSED(windowIds)
398 }
399
407 virtual QString managedFocusedWindow(const QString& screenId) const
408 {
409 Q_UNUSED(screenId)
410 return {};
411 }
412
431 virtual int stickyPinnedDesktopForScreen(const QString& screenId) const
432 {
433 Q_UNUSED(screenId)
434 return 0;
435 }
436
452 virtual void setInitialFocusedWindow(const QString& screenId, const QString& windowId)
453 {
454 Q_UNUSED(screenId)
455 Q_UNUSED(windowId)
456 }
457
458 // ═══════════════════════════════════════════════════════════════════════════
459 // OPTIONAL: Per-screen config (override if engine supports per-screen overrides)
460 //
461 // SCOPE IS THE IMPLEMENTATION'S CHOICE, and the two in-tree engines differ.
462 // AutotileEngine stores one map per SCREEN. ScrollEngine stores one per
463 // (screen, desktop, activity) and answers for the screen's CURRENT context,
464 // because its templates are resolved per context and keying by screen let
465 // one desktop's template overwrite another's. A caller holding this
466 // interface must therefore not assume a map it pushed survives a desktop or
467 // activity switch, nor that the accessor replays what it last wrote.
468 // clearPerScreenConfig is the whole-SCREEN door in both: it drops every
469 // context's entry, so an engine keyed per context needs an empty
470 // applyPerScreenConfig push, not a clear, to say "this context has none".
471 // ═══════════════════════════════════════════════════════════════════════════
472
473 virtual void applyPerScreenConfig(const QString& screenId, const QVariantMap& overrides)
474 {
475 Q_UNUSED(screenId)
476 Q_UNUSED(overrides)
477 }
478 virtual void clearPerScreenConfig(const QString& screenId)
479 {
480 Q_UNUSED(screenId)
481 }
482 virtual QVariantMap perScreenOverrides(const QString& screenId) const
483 {
484 Q_UNUSED(screenId)
485 return {};
486 }
487
488 // ═══════════════════════════════════════════════════════════════════════════
489 // OPTIONAL: Mode-specific float MARKER (runtime discriminator, NOT persistence)
490 //
491 // Distinguishes a USER float in this engine's mode from an incidental float
492 // (e.g. autotile overflow). It is live runtime state the capture funnel reads
493 // to decide whether a float should persist into the record — there is no
494 // parallel "saved floats" store; the WindowPlacement record is the single
495 // source of truth for cross-mode float state. All three verbs live here,
496 // in one section (mark / query / clear).
497 // ═══════════════════════════════════════════════════════════════════════════
498
499 virtual void markModeSpecificFloated(const QString& windowId)
500 {
501 Q_UNUSED(windowId)
502 }
503 virtual bool isModeSpecificFloated(const QString& windowId) const
504 {
505 Q_UNUSED(windowId)
506 return false;
507 }
508 virtual void clearModeSpecificFloatMarker(const QString& windowId)
509 {
510 Q_UNUSED(windowId)
511 }
512
513 // ═══════════════════════════════════════════════════════════════════════════
514 // OPTIONAL: Drag insert preview (override if engine supports drag-to-insert)
515 // ═══════════════════════════════════════════════════════════════════════════
516
538 {
539 int primary = -1;
540 int secondary = -1;
541 bool newSlot = false;
542 bool leadingEdge = false;
543
544 bool isValid() const
545 {
546 return primary >= 0;
547 }
548 bool operator==(const DragInsertTarget& other) const = default;
549 };
550
551 // Contract shared by the preview verbs, which the two implementations
552 // honour with OPPOSITE internal shapes:
553 // - begin MAY mutate managed state, and MAY adopt the window from
554 // another screen, from a floating set, or from untracked entirely
555 // (both engines do all three).
556 // - an engine may or may not keep the window MANAGED while its preview
557 // is live — autotile keeps it a tile and restructures per update;
558 // scrolling DETACHES it until commit. Cross-engine callers must not
559 // use isWindowTiled/isWindowManaged as a drag-state probe.
560 // - begin on an engine already holding a preview cancels the old one
561 // first; commit/cancel are no-ops with no preview live; and
562 // dragInsertPreviewScreenId is empty with no preview live.
563 // - after a successful begin the caller may hand over the size the
564 // client chose for the window, through setDragInsertClientSize
565 // (declared last in this class for ABI), and hand it again on later
566 // ticks. A begin starts without one, and the call is a no-op with no
567 // preview live.
568
569 virtual bool hasDragInsertPreview() const
570 {
571 return false;
572 }
573 virtual bool beginDragInsertPreview(const QString& windowId, const QString& screenId)
574 {
575 Q_UNUSED(windowId)
576 Q_UNUSED(screenId)
577 return false;
578 }
580 {
581 }
582
590 virtual void cancelDragInsertPreview(bool dragStillActive = false)
591 {
592 Q_UNUSED(dragStillActive)
593 }
594 virtual QString dragInsertPreviewScreenId() const
595 {
596 return {};
597 }
598
607 virtual QString dragInsertPreviewPriorScreenId() const
608 {
609 return {};
610 }
611
614 virtual DragInsertTarget computeDragInsertTargetAtPoint(const QString& screenId, const QPoint& cursorPos) const
615 {
616 Q_UNUSED(screenId)
617 Q_UNUSED(cursorPos)
618 return {};
619 }
620
625 virtual void updateDragInsertPreview(const DragInsertTarget& target)
626 {
627 Q_UNUSED(target)
628 }
629
655 virtual bool dragAutoScrollTick(const QString& screenId, const QPoint& cursorPos, qreal dtSeconds)
656 {
657 Q_UNUSED(screenId)
658 Q_UNUSED(cursorPos)
659 Q_UNUSED(dtSeconds)
660 return false;
661 }
662
678 virtual bool dragAutoScrollActive() const
679 {
680 return false;
681 }
682
692 virtual void cancelDragAutoScroll()
693 {
694 }
695
711 virtual QRect dragInsertIndicatorRect(const QString& screenId) const
712 {
713 Q_UNUSED(screenId)
714 return {};
715 }
716
731 virtual void setInteractiveDragWindow(const QString& windowId)
732 {
733 Q_UNUSED(windowId)
734 }
735
736 // ═══════════════════════════════════════════════════════════════════════════
737 // OPTIONAL: Per-window tracking state
738 //
739 // What the daemon asks an engine about ONE window: does it track it, does
740 // it manage/tile it, which screen does it think the window is on, what min
741 // size does it model — plus the two per-window updates that follow from
742 // those answers (a late min-size discovery, an interactive resize). The
743 // drag-preview verbs above are a separate group; these have nothing to do
744 // with a drag.
745 // ═══════════════════════════════════════════════════════════════════════════
746
747 virtual bool isWindowTracked(const QString& windowId) const
748 {
749 Q_UNUSED(windowId)
750 return false;
751 }
752
761 virtual bool isWindowManaged(const QString& windowId) const
762 {
763 Q_UNUSED(windowId)
764 return false;
765 }
766
769 virtual bool isWindowTiled(const QString& windowId) const
770 {
771 Q_UNUSED(windowId)
772 return false;
773 }
774
780 virtual QString screenForTrackedWindow(const QString& windowId) const
781 {
782 Q_UNUSED(windowId)
783 return {};
784 }
785
796 virtual QSize windowMinimumSize(const QString& windowId) const
797 {
798 Q_UNUSED(windowId)
799 return {};
800 }
801
807 virtual void windowMinSizeUpdated(const QString& windowId, int minWidth, int minHeight)
808 {
809 Q_UNUSED(windowId)
810 Q_UNUSED(minWidth)
811 Q_UNUSED(minHeight)
812 }
813
823 virtual void onWindowResized(const QString& windowId, const QRect& oldFrame, const QRect& newFrame,
824 const QString& screenId)
825 {
826 Q_UNUSED(windowId)
827 Q_UNUSED(oldFrame)
828 Q_UNUSED(newFrame)
829 Q_UNUSED(screenId)
830 }
831
832 // ═══════════════════════════════════════════════════════════════════════════
833 // Cross-engine handoff
834 //
835 // When a window crosses screens whose owning engines differ (e.g. a snap
836 // screen → an autotile screen, via drag drop), ownership has to transfer
837 // between two engines. Without an explicit contract, each engine makes
838 // local guesses (autotile's "is this a floating window I should adopt?"
839 // branch, snap's "do I know this window?" early-return) and the daemon
840 // misroutes user intents during the transition window.
841 //
842 // The handoff is a two-step transaction the daemon orchestrates:
843 // 1. fromEngine->handoffRelease(windowId)
844 // 2. toEngine->handoffReceive(ctx)
845 //
846 // Each engine's release is a tracking-only clear (no geometry mutation —
847 // the receiving engine places the window). Each engine's receive applies
848 // its own placement policy (autotile picks an insert slot or floats;
849 // snap picks the nearest zone or floats) using the context fields.
850 //
851 // Engines that don't currently distinguish ownership across screens can
852 // leave both as no-ops; the defaults are safe.
853 //
854 // The verbs are prefixed `handoff*` to keep them distinct from an engine
855 // dropping a window entirely (the window is no longer engine-managed at all
856 // — a different concept from "transferring ownership to another engine").
857 // ═══════════════════════════════════════════════════════════════════════════
858
863 {
864 QString windowId;
865 QString fromEngineId;
866 QString toScreenId;
867 int toDesktop = 0;
872 QPoint dropPos;
874 QSize minSize;
883 QStringList sourceZoneIds;
884 bool wasFloating = false;
885 bool heldFocus = false;
892 int insertIndex = -1;
900 };
901
916 virtual void handoffReceive(const HandoffContext& ctx)
917 {
918 Q_UNUSED(ctx)
919 }
920
933 virtual void handoffRelease(const QString& windowId)
934 {
935 Q_UNUSED(windowId)
936 }
937
941 virtual QString engineId() const
942 {
943 return {};
944 }
945
946 // ═══════════════════════════════════════════════════════════════════════════
947 // OPTIONAL: Layout capability (UI-facing; distinct from algorithm identity)
948 // ═══════════════════════════════════════════════════════════════════════════
949
955 enum class LayoutSupport {
959 None,
962 Placement,
972 Templates
973 };
974
977 {
978 return LayoutSupport::None;
979 }
980
991 virtual bool providesDragInsertSelector() const
992 {
993 return false;
994 }
995
996 // ═══════════════════════════════════════════════════════════════════════════
997 // OPTIONAL: Algorithm / mode identity (override if engine has switchable algorithms)
998 // ═══════════════════════════════════════════════════════════════════════════
999
1000 virtual QString algorithmId() const
1001 {
1002 return {};
1003 }
1004 virtual void setAlgorithm(const QString& algorithmId)
1005 {
1006 Q_UNUSED(algorithmId)
1007 }
1008 virtual bool isEnabled() const noexcept
1009 {
1010 return false;
1011 }
1012 virtual QString activeScreen() const
1013 {
1014 return {};
1015 }
1016 virtual void setActiveScreenHint(const QString& screenId)
1017 {
1018 Q_UNUSED(screenId)
1019 }
1020
1021 // ═══════════════════════════════════════════════════════════════════════════
1022 // OPTIONAL: Desktop/activity context (override if engine is desktop-aware)
1023 // ═══════════════════════════════════════════════════════════════════════════
1024
1025 virtual void setCurrentDesktop(int desktop)
1026 {
1027 Q_UNUSED(desktop)
1028 }
1029
1035 virtual void setCurrentDesktopForScreen(const QString& screenId, int desktop)
1036 {
1037 Q_UNUSED(screenId)
1038 Q_UNUSED(desktop)
1039 }
1040
1041 virtual void clearCurrentDesktopForScreen(const QString& screenId)
1042 {
1043 Q_UNUSED(screenId)
1044 }
1045 virtual void setCurrentActivity(const QString& activity)
1046 {
1047 Q_UNUSED(activity)
1048 }
1049
1055 {
1056 Q_UNUSED(resolver)
1057 }
1058
1061 virtual void updateStickyScreenPins(const StickyPredicate& isSticky, StickyPinPhase phase)
1062 {
1063 Q_UNUSED(isSticky)
1064 Q_UNUSED(phase)
1065 }
1066
1074 const DesktopSpanQuery& spanOf)
1075 {
1076 Q_UNUSED(screenId)
1077 Q_UNUSED(spanOf)
1078 return {};
1079 }
1080
1086 const DesktopSpanQuery& spanOf)
1087 {
1088 Q_UNUSED(windowId)
1089 Q_UNUSED(spanOf)
1090 return {};
1091 }
1092 virtual QSet<int> desktopsWithActiveState() const
1093 {
1094 return {};
1095 }
1096 virtual void pruneStatesForDesktop(int removedDesktop)
1097 {
1098 Q_UNUSED(removedDesktop)
1099 }
1100
1109 virtual void renumberDesktopsAfterRemoval(int removedDesktop)
1110 {
1111 Q_UNUSED(removedDesktop)
1112 }
1113 virtual void pruneStatesForActivities(const QStringList& validActivities)
1114 {
1115 Q_UNUSED(validActivities)
1116 }
1117
1128 virtual void pruneStatesForRemovedScreen(const QString& physicalScreenId)
1129 {
1130 Q_UNUSED(physicalScreenId)
1131 }
1132
1133 // ═══════════════════════════════════════════════════════════════════════════
1134 // OPTIONAL: Settings synchronization (override if engine caches config)
1135 // ═══════════════════════════════════════════════════════════════════════════
1136
1143 {
1144 }
1145
1147 static constexpr qreal kDefaultSplitRatioStep = 0.05;
1148 virtual qreal effectiveSplitRatioStep(const QString& screenId) const
1149 {
1150 Q_UNUSED(screenId)
1152 }
1153
1156 virtual int runtimeMaxWindows() const
1157 {
1158 return -1;
1159 }
1160
1167 virtual std::optional<int> savedMaxWindowsForAlgorithm(const QString& algorithmId) const
1168 {
1169 Q_UNUSED(algorithmId)
1170 return std::nullopt;
1171 }
1172
1173 // ═══════════════════════════════════════════════════════════════════════════
1174 // OPTIONAL: Retile / refresh (override if engine supports on-demand retile)
1175 // ═══════════════════════════════════════════════════════════════════════════
1176
1177 virtual void retile(const QString& screenId = QString())
1178 {
1179 Q_UNUSED(screenId)
1180 }
1181 virtual void scheduleRetileForScreen(const QString& screenId)
1182 {
1183 Q_UNUSED(screenId)
1184 }
1185
1186 // Per-window restore persistence is unified: engines implement
1187 // capturePlacement()/restorePlacement() (above) and the common
1188 // WindowPlacementStore handles capture timing, serialization, and the single
1189 // WindowPlacements config key. No engine-specific serialize/deserialize hooks.
1190
1191 // ═══════════════════════════════════════════════════════════════════════════
1192 // OPTIONAL: Init hooks (override to receive shared services)
1193 // ═══════════════════════════════════════════════════════════════════════════
1194
1198 virtual void setWindowRegistry(QObject* registry)
1199 {
1200 Q_UNUSED(registry)
1201 }
1202 // ═══════════════════════════════════════════════════════════════════════════
1203 // OPTIONAL: Master operations (autotile-specific, no-op on snap engine)
1204 // ═══════════════════════════════════════════════════════════════════════════
1205
1207 {
1208 Q_UNUSED(delta)
1209 }
1211 {
1212 Q_UNUSED(delta)
1213 }
1214 virtual void increaseMasterCount()
1215 {
1216 }
1217 virtual void decreaseMasterCount()
1218 {
1219 }
1220 virtual void focusMaster()
1221 {
1222 }
1224 {
1225 }
1226
1227 // ═══════════════════════════════════════════════════════════════════════════
1228 // Persistence
1229 // ═══════════════════════════════════════════════════════════════════════════
1230
1231 virtual void saveState() = 0;
1232 virtual void loadState() = 0;
1233
1234 // ═══════════════════════════════════════════════════════════════════════════
1235 // State access
1236 // ═══════════════════════════════════════════════════════════════════════════
1237
1243 virtual IPlacementState* stateForScreen(const QString& screenId) = 0;
1244 virtual const IPlacementState* stateForScreen(const QString& screenId) const = 0;
1245
1249 virtual void setOpenFocusEligible(bool eligible)
1250 {
1251 Q_UNUSED(eligible)
1252 }
1253
1258 virtual void releaseWindowOffScreen(const QString& windowId, const QString& keepScreenId)
1259 {
1260 Q_UNUSED(windowId)
1261 Q_UNUSED(keepScreenId)
1262 }
1263
1264 // ── Evacuee park (OPTIONAL, appended for ABI) ──────────────────────────
1265 // When KWin evacuates an output that disconnected, the daemon parks each engine's memory of the windows there
1266 // and re-seats an untouched window when KWin returns it. Session-scoped: a daemon restart loses the park.
1267
1270 virtual QStringList parkOutput(const QString& physicalScreenId)
1271 {
1272 Q_UNUSED(physicalScreenId)
1273 return {};
1274 }
1275
1280 virtual bool readoptParked(const QString& windowId, const QString& parkedPhysicalId,
1281 const QString& returnedPhysicalId)
1282 {
1283 Q_UNUSED(windowId)
1284 Q_UNUSED(parkedPhysicalId)
1285 Q_UNUSED(returnedPhysicalId)
1286 return false;
1287 }
1288
1290 virtual void dropParked(const QString& windowId, const QString& physicalScreenId, int desktop,
1291 const QString& activity)
1292 {
1293 Q_UNUSED(windowId)
1294 Q_UNUSED(physicalScreenId)
1295 Q_UNUSED(desktop)
1296 Q_UNUSED(activity)
1297 }
1298
1300 virtual bool hasParked(const QString& windowId, const QString& physicalScreenId) const
1301 {
1302 Q_UNUSED(windowId)
1303 Q_UNUSED(physicalScreenId)
1304 return false;
1305 }
1306
1312 virtual void remapDesktops(const DesktopRemap& remap);
1313
1331 virtual void setDragInsertClientSize(const QSize& size)
1332 {
1333 Q_UNUSED(size)
1334 }
1335};
1336
1337} // namespace PhosphorEngine
How KWin's desktop positions moved in one change of its desktop list: for each 1-based position in th...
Definition DesktopRemap.h:29
Resolves the neighbouring surface — output or virtual desktop — in a direction, for cross-surface win...
Definition ICrossSurfaceResolver.h:21
virtual QString activeScreen() const
Definition IPlacementEngine.h:1012
virtual void noteCrossScreenClaimsExhausted(const QString &windowId, bool exhausted)
INERT, kept for ABI: fed the removed cross-screen defer gates.
Definition IPlacementEngine.h:113
virtual QString dragInsertPreviewScreenId() const
Definition IPlacementEngine.h:594
virtual void applyPerScreenConfig(const QString &screenId, const QVariantMap &overrides)
Definition IPlacementEngine.h:473
virtual LayoutSupport layoutSupport() const
Default None: an engine must opt in to being a layout consumer.
Definition IPlacementEngine.h:976
virtual void increaseMasterCount()
Definition IPlacementEngine.h:1214
virtual QString engineId() const
Stable engine identity for HandoffContext.fromEngineId.
Definition IPlacementEngine.h:941
virtual void setAlgorithm(const QString &algorithmId)
Definition IPlacementEngine.h:1004
virtual void dropParked(const QString &windowId, const QString &physicalScreenId, int desktop, const QString &activity)
Forget windowId's parked contexts; an empty physicalScreenId, a desktop of 0 or an empty activity mat...
Definition IPlacementEngine.h:1290
virtual void setWindowFloat(const QString &windowId, bool shouldFloat, const QString &screenId=QString())=0
Set floating state explicitly (directional, not toggle).
void windowOpened(const QString &windowId, const QString &screenId)
Convenience overload — equivalent to windowOpened(id, screen, 0, 0).
Definition IPlacementEngine.h:82
virtual void setCurrentActivity(const QString &activity)
Definition IPlacementEngine.h:1045
virtual QString heldScreenForWindow(const QString &windowId) const
OPTIONAL: the screen this engine genuinely HOLDS the window on IN THE SCREEN'S CURRENT CONTEXT — a ME...
Definition IPlacementEngine.h:139
virtual int runtimeMaxWindows() const
Runtime max-windows limit.
Definition IPlacementEngine.h:1156
virtual void setActiveScreenHint(const QString &screenId)
Definition IPlacementEngine.h:1016
virtual std::optional< int > savedMaxWindowsForAlgorithm(const QString &algorithmId) const
The user's saved per-algorithm max-windows tuning for algorithmId, or std::nullopt when the engine ke...
Definition IPlacementEngine.h:1167
virtual void windowMinSizeUpdated(const QString &windowId, int minWidth, int minHeight)
Update a window's minimum size after the initial windowOpened.
Definition IPlacementEngine.h:807
virtual void setWindowRegistry(QObject *registry)
Attach a window-class registry (QObject carrying WindowRegistry).
Definition IPlacementEngine.h:1198
virtual void onWindowResized(const QString &windowId, const QRect &oldFrame, const QRect &newFrame, const QString &screenId)
Notify the engine that a tracked window finished an interactive resize.
Definition IPlacementEngine.h:823
virtual void setCurrentDesktopForScreen(const QString &screenId, int desktop)
Set a single screen's current virtual desktop (Plasma 6.7 "switch desktopsindependently for each scre...
Definition IPlacementEngine.h:1035
virtual void setActiveScreens(const QSet< QString > &screens)
Definition IPlacementEngine.h:313
virtual bool readoptParked(const QString &windowId, const QString &parkedPhysicalId, const QString &returnedPhysicalId)
Re-seat windowId's contexts parked under parkedPhysicalId on returnedPhysicalId as a re-statement (no...
Definition IPlacementEngine.h:1280
virtual void windowFocused(const QString &windowId, const QString &screenId)=0
A window gained focus (called when the compositor reports activation).
virtual QStringList parkOutput(const QString &physicalScreenId)
Copy every context of physicalScreenId (each of its virtual screens) into the park,...
Definition IPlacementEngine.h:1270
virtual QString screenForTrackedWindow(const QString &windowId) const
Return the screen this engine considers the window to be on (any context), or empty if the window isn...
Definition IPlacementEngine.h:780
virtual bool isWindowTracked(const QString &windowId) const
Definition IPlacementEngine.h:747
virtual void commitDragInsertPreview()
Definition IPlacementEngine.h:579
virtual void spanFocusedInDirection(const QString &direction, const NavigationContext &ctx)
Grow or shrink the focused window's zone span toward the direction: extend into the adjacent zone(s) ...
Definition IPlacementEngine.h:248
virtual bool dragAutoScrollActive() const
Whether edge auto-scroll currently owns the drop target.
Definition IPlacementEngine.h:678
virtual void moveFocusedInDirection(const QString &direction, const NavigationContext &ctx)=0
Move the focused window to the adjacent slot.
virtual void scheduleRetileForScreen(const QString &screenId)
Definition IPlacementEngine.h:1181
virtual void swapFocusedWithMaster()
Definition IPlacementEngine.h:1223
virtual void cancelDragAutoScroll()
Give the drop target back and forget any armed band, WITHOUT moving the view or re-aiming.
Definition IPlacementEngine.h:692
virtual void handoffRelease(const QString &windowId)
Release ownership of a window WITHOUT modifying its geometry.
Definition IPlacementEngine.h:933
virtual bool isWindowTiled(const QString &windowId) const
Whether the window is actively tiled (engine-owned, non-floating).
Definition IPlacementEngine.h:769
virtual ~IPlacementEngine()=default
virtual void setCrossSurfaceResolver(ICrossSurfaceResolver *resolver)
Inject the cross-surface resolver used to find a neighbouring output / desktop when directional navig...
Definition IPlacementEngine.h:1054
virtual void setInitialWindowOrder(const QString &screenId, const QStringList &windowIds)
Definition IPlacementEngine.h:394
virtual void restoreFocusedWindow(const NavigationContext &ctx)=0
Restore the focused window out of its managed state.
virtual void clearCurrentDesktopForScreen(const QString &screenId)
Drop a screen's per-output desktop, reverting it to the global current.
Definition IPlacementEngine.h:1041
virtual IPlacementState * stateForScreen(const QString &screenId)=0
Per-screen state object for the given screen.
virtual void handoffReceive(const HandoffContext &ctx)
Receive ownership of a window from another engine.
Definition IPlacementEngine.h:916
virtual QSize windowMinimumSize(const QString &windowId) const
The window's client-reported minimum size as last known by this engine, or an UNKNOWN answer when it ...
Definition IPlacementEngine.h:796
virtual void focusMaster()
Definition IPlacementEngine.h:1220
virtual QString algorithmId() const
Definition IPlacementEngine.h:1000
static constexpr qreal kDefaultSplitRatioStep
One home for the master/split ratio step so the default return below and the two default arguments ca...
Definition IPlacementEngine.h:1147
virtual bool dragAutoScrollTick(const QString &screenId, const QPoint &cursorPos, qreal dtSeconds)
Advance edge auto-scroll for a live drag-insert preview (niri's dnd-edge-view-scroll): an engine whos...
Definition IPlacementEngine.h:655
virtual MembershipReconcileResult reconcileWindowMemberships(const QString &windowId, const DesktopSpanQuery &spanOf)
The same pass for ONE window, on the screen it is held on.
Definition IPlacementEngine.h:1085
virtual void setOpenFocusEligible(bool eligible)
OPTIONAL: whether the opens dispatched next may take focus ("Focus newwindows"): true for a genuine o...
Definition IPlacementEngine.h:1249
virtual void cancelDragInsertPreview(bool dragStillActive=false)
dragStillActive: the previewed window is still under an interactive move when the cancel runs (mid-dr...
Definition IPlacementEngine.h:590
virtual bool hasDragInsertPreview() const
Definition IPlacementEngine.h:569
virtual void decreaseMasterRatio(qreal delta=kDefaultSplitRatioStep)
Definition IPlacementEngine.h:1210
virtual void focusInDirection(const QString &direction, const NavigationContext &ctx)=0
Move keyboard focus to the adjacent window.
virtual void windowOpened(const QString &windowId, const QString &screenId, int minWidth=0, int minHeight=0)=0
A new window appeared on this engine's screen.
virtual void beginArrivalBurst()
Bracket a BURST of windowOpened calls delivered together (the adaptor's three dispatch loops: windows...
Definition IPlacementEngine.h:183
virtual void clearModeSpecificFloatMarker(const QString &windowId)
Definition IPlacementEngine.h:508
virtual void moveFocusedToPosition(int position, const NavigationContext &ctx)=0
Move the focused window to the Nth position.
virtual bool providesDragInsertSelector() const
Whether the daemon's edge-triggered drag popup (the zone selector surface) should render this engine'...
Definition IPlacementEngine.h:991
virtual void setDragInsertClientSize(const QSize &size)
OPTIONAL: the size the client chose for the window under the live drag-insert preview,...
Definition IPlacementEngine.h:1331
virtual void refreshConfigFromSettings()
Re-read all tuning values from the engine's settings interface.
Definition IPlacementEngine.h:1142
virtual void pruneStatesForRemovedScreen(const QString &physicalScreenId)
Prune per-(screen, desktop, activity) state for a PHYSICALLY REMOVED output (monitor hot-unplug),...
Definition IPlacementEngine.h:1128
virtual QSet< QString > activeScreens() const
Definition IPlacementEngine.h:309
virtual bool isWindowManaged(const QString &windowId) const
Whether the engine considers the window "managed" (eligible for layout operations).
Definition IPlacementEngine.h:761
virtual void retile(const QString &screenId=QString())
Definition IPlacementEngine.h:1177
virtual const IPlacementState * stateForScreen(const QString &screenId) const =0
virtual QString dragInsertPreviewPriorScreenId() const
The screen the previewed window was on BEFORE begin adopted it, or empty when it had no prior state (...
Definition IPlacementEngine.h:607
LayoutSupport
How this engine relates to user-selectable layouts — the entries the layout picker,...
Definition IPlacementEngine.h:955
@ None
No layout concept at all: the daemon suppresses the picker/popup and answers the layout shortcuts wit...
Definition IPlacementEngine.h:959
virtual bool restorePlacement(const WindowPlacement &placement, const QString &screenId)
Apply placement to a (re)opening window on screenId.
Definition IPlacementEngine.h:378
virtual bool isEnabled() const noexcept
Definition IPlacementEngine.h:1008
virtual qreal effectiveSplitRatioStep(const QString &screenId) const
Definition IPlacementEngine.h:1148
virtual void updateStickyScreenPins(const StickyPredicate &isSticky, StickyPinPhase phase)
Run one phase of the sticky-screen pin pass; see StickyPinPhase for why the two phases bracket a cont...
Definition IPlacementEngine.h:1061
virtual bool isActiveOnScreen(const QString &screenId) const =0
Whether this engine is active on the given screen.
virtual void toggleWindowFloat(const QString &windowId, const QString &screenId)=0
Toggle between managed and floating.
virtual void swapFocusedInDirection(const QString &direction, const NavigationContext &ctx)=0
Swap the focused window with the adjacent window.
virtual void increaseMasterRatio(qreal delta=kDefaultSplitRatioStep)
Definition IPlacementEngine.h:1206
virtual bool isModeSpecificFloated(const QString &windowId) const
Definition IPlacementEngine.h:503
virtual void rotateWindows(bool clockwise, const NavigationContext &ctx)=0
Rotate all managed windows on the screen.
virtual MembershipReconcileResult reconcileDesktopMemberships(const QString &screenId, const DesktopSpanQuery &spanOf)
Give every window whose span covers screenId's current context a place in it, and take back the place...
Definition IPlacementEngine.h:1073
virtual bool beginDragInsertPreview(const QString &windowId, const QString &screenId)
Definition IPlacementEngine.h:573
virtual void snapAllWindows(const NavigationContext &ctx)=0
Bring every unmanaged window on the screen back under this engine's placement (zones for snap,...
virtual void cycleFocus(bool forward, const NavigationContext &ctx)=0
Cycle keyboard focus through managed windows.
virtual void toggleFocusedFloat(const NavigationContext &ctx)=0
Toggle the focused window between managed and floating.
virtual void windowClosed(const QString &windowId)=0
A window was closed.
virtual void clearPerScreenConfig(const QString &screenId)
Definition IPlacementEngine.h:478
virtual void renumberDesktopsAfterRemoval(int removedDesktop)
Shift every per-(screen, desktop, activity) state ABOVE removedDesktop down by one,...
Definition IPlacementEngine.h:1109
IPlacementEngine(const IPlacementEngine &)=delete
virtual void reapplyLayout(const NavigationContext &ctx)=0
Re-apply the current layout to all managed windows.
virtual void reapplyManagedWindowAppearance()
Re-drive the compositor's per-window appearance (border, hidden title bar) for every window this engi...
Definition IPlacementEngine.h:333
virtual void setCurrentDesktop(int desktop)
Definition IPlacementEngine.h:1025
virtual bool hasParked(const QString &windowId, const QString &physicalScreenId) const
Whether windowId has a context parked under physicalScreenId (any output when it is empty).
Definition IPlacementEngine.h:1300
virtual std::optional< PlacementStateKey > heldKeyForWindow(const QString &windowId) const
The (screen, desktop, activity) key of the state that genuinely holds windowId, tiled or floating,...
Definition IPlacementEngine.h:166
virtual void pruneStatesForDesktop(int removedDesktop)
Definition IPlacementEngine.h:1096
virtual void pushToEmptyZone(const NavigationContext &ctx)=0
Move the focused window to the first empty slot.
virtual void releaseWindowOffScreen(const QString &windowId, const QString &keepScreenId)
OPTIONAL: another engine just placed windowId on keepScreenId, so a hold this engine keeps on any oth...
Definition IPlacementEngine.h:1258
virtual void remapDesktops(const DesktopRemap &remap)
OPTIONAL: KWin's desktop list changed (a removal, an insert or a reorder).
virtual void markModeSpecificFloated(const QString &windowId)
Definition IPlacementEngine.h:499
virtual void decreaseMasterCount()
Definition IPlacementEngine.h:1217
virtual void setInteractiveDragWindow(const QString &windowId)
The window currently under a compositor interactive move (the whole drag, preview or not).
Definition IPlacementEngine.h:731
virtual void endArrivalBurst()
Definition IPlacementEngine.h:186
virtual bool claimCrossScreenReopen(const QString &windowId, const QString &openingScreenId, int minWidth=0, int minHeight=0)
OPTIONAL: the reopen claim, under the reopen contract (restores happen where a window opens).
Definition IPlacementEngine.h:101
virtual QSet< int > desktopsWithActiveState() const
Definition IPlacementEngine.h:1092
IPlacementEngine & operator=(const IPlacementEngine &)=delete
virtual QRect dragInsertIndicatorRect(const QString &screenId) const
The rect the dragged window would occupy if the live preview were dropped now, in absolute px on scre...
Definition IPlacementEngine.h:711
virtual DragInsertTarget computeDragInsertTargetAtPoint(const QString &screenId, const QPoint &cursorPos) const
Compute the drop target for a cursor position on a managed screen.
Definition IPlacementEngine.h:614
virtual void updateDragInsertPreview(const DragInsertTarget &target)
Update the drop target for an active drag-insert preview.
Definition IPlacementEngine.h:625
virtual QStringList managedWindowOrder(const QString &screenId) const
Definition IPlacementEngine.h:389
virtual int stickyPinnedDesktopForScreen(const QString &screenId) const
The desktop this engine has PINNED screenId to, or 0 when it has not pinned it (which is the normal c...
Definition IPlacementEngine.h:431
virtual QVariantMap perScreenOverrides(const QString &screenId) const
Definition IPlacementEngine.h:482
virtual QString managedFocusedWindow(const QString &screenId) const
The window this engine considers focused on screenId, or empty.
Definition IPlacementEngine.h:407
virtual void setInitialFocusedWindow(const QString &screenId, const QString &windowId)
Hand the incoming engine the focus captured from the outgoing one.
Definition IPlacementEngine.h:452
virtual void pruneStatesForActivities(const QStringList &validActivities)
Definition IPlacementEngine.h:1113
virtual std::optional< WindowPlacement > capturePlacement(const QString &windowId) const
Report windowId's CURRENT placement for persistence, or nullopt if this engine does not manage it.
Definition IPlacementEngine.h:357
virtual void switchFocusBetweenFloatingAndTiling(const QString &screenId)
Jump focus between the float layer and the engine's placement layer (niri's switch-focus-between-floa...
Definition IPlacementEngine.h:266
Per-screen placement state contract.
Definition IPlacementState.h:28
Definition DesktopRemap.h:12
StickyPinPhase
Which half of the sticky-screen pin pass to run.
Definition EngineTypes.h:323
std::function< bool(const QString &)> StickyPredicate
Answers whether a window is on all desktops.
Definition EngineTypes.h:247
std::function< DesktopSpan(const QString &)> DesktopSpanQuery
Answers a window's DesktopSpan.
Definition EngineTypes.h:292
Where a drag-insert preview should place the dragged window, in the TARGET ENGINE's slot vocabulary.
Definition IPlacementEngine.h:538
bool newSlot
Definition IPlacementEngine.h:541
int secondary
Definition IPlacementEngine.h:540
bool isValid() const
Definition IPlacementEngine.h:544
int primary
Definition IPlacementEngine.h:539
bool leadingEdge
Definition IPlacementEngine.h:542
bool operator==(const DragInsertTarget &other) const =default
Context for a cross-engine window handoff.
Definition IPlacementEngine.h:863
QString fromEngineId
source engine identity ("snap" / "autotile" / "scrolling" / "")
Definition IPlacementEngine.h:865
bool wasFloating
window was floating in source engine
Definition IPlacementEngine.h:884
QSize minSize
minimum size as the SOURCE engine models it (0x0 when unknown) — autotile stores it screen-capped,...
Definition IPlacementEngine.h:874
int toDesktop
destination virtual desktop (1-based); 0 = current desktop (drag-drop / same-desktop monitor crossing...
Definition IPlacementEngine.h:867
QRect sourceGeometry
window's frame at handoff time (for size preservation)
Definition IPlacementEngine.h:873
QPoint dropPos
cursor position at drop, or invalid for non-drag handoffs
Definition IPlacementEngine.h:872
QString toScreenId
destination screen (must be owned by to engine)
Definition IPlacementEngine.h:866
int insertIndex
PER-TARGET unit.
Definition IPlacementEngine.h:892
bool heldFocus
the window held compositor focus at handoff time, per the daemon's windowActivated tracking.
Definition IPlacementEngine.h:885
QStringList sourceZoneIds
zones the window held at source (empty if not snapped)
Definition IPlacementEngine.h:883
QString windowId
Definition IPlacementEngine.h:864
What a membership pass did, so the caller can drive the bookkeeping the engines cannot reach: the pla...
Definition EngineTypes.h:299
Target window + screen for a navigation or lifecycle operation.
Definition NavigationContext.h:18
One window's single, authoritative placement record — the unit of the unified, engine-agnostic restor...
Definition WindowPlacement.h:96