Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorLayer::ISurfaceAnimator Class Referenceabstract

Hook point for show/hide transitions on Surfaces. More...

#include <PhosphorLayer/ISurfaceAnimator.h>

Inheritance diagram for PhosphorLayer::ISurfaceAnimator:
[legend]

Public Types

using CompletionCallback = std::function<void()>
 Invoked when a show/hide animation completes.

Public Member Functions

 ISurfaceAnimator ()=default
virtual ~ISurfaceAnimator ()=default
virtual void beginShow (Surface *surface, QQuickItem *rootItem, CompletionCallback onComplete)=0
 Begin a show transition for surface.
virtual void beginHide (Surface *surface, QQuickItem *rootItem, CompletionCallback onComplete)=0
 Begin a hide transition for surface.
virtual void cancel (Surface *surface)=0
 Interrupt every in-flight animation for surface, on any item, not only the root.

Detailed Description

Hook point for show/hide transitions on Surfaces.

Primary animation authoring happens in the consumer's QML — Behavior on opacity { NumberAnimation { duration: 150 } } is almost always the right answer for fade-in/out. This interface exists for cases the QML side cannot cover:

  • Pre-show measurement (e.g. a panel that needs its content sized before the compositor places it).
  • Post-hide cleanup that must wait for an animation to finish before the library tears down the transport handle.
  • Orchestrated transitions across multiple surfaces (fade out modal as primary fades in).

Most consumers pass nullptr and animate entirely within QML. The default implementation (NoOpSurfaceAnimator) does exactly that — it exists so code paths can always call through the interface without null-checking.

Threading

All hooks are called on the GUI thread.

Contract

Implementations must call onComplete exactly once per hook invocation. The library passes a no-op completion today and makes its own state transitions synchronously, so nothing in it waits on the call yet; a future version may.

Member Typedef Documentation

◆ CompletionCallback

Invoked when a show/hide animation completes.

The animator must call this exactly once per beginShow/beginHide call. Safe to invoke synchronously for no-op animators.

Constructor & Destructor Documentation

◆ ISurfaceAnimator()

PhosphorLayer::ISurfaceAnimator::ISurfaceAnimator ( )
default

◆ ~ISurfaceAnimator()

virtual PhosphorLayer::ISurfaceAnimator::~ISurfaceAnimator ( )
virtualdefault

Member Function Documentation

◆ beginHide()

virtual void PhosphorLayer::ISurfaceAnimator::beginHide ( Surface * surface,
QQuickItem * rootItem,
CompletionCallback onComplete )
pure virtual

Begin a hide transition for surface.

The Surface is transitioning Shown → Hidden. The animator should fade/slide the content, then invoke onComplete. The library does not delay window->hide() waiting for this — the current contract is "animate for visual polish, but the surface is considered hidden the moment hide() is called".

Not dispatched for a surface whose SurfaceConfig::animateRoot is false.

Implemented in PhosphorAnimationLayer::SurfaceAnimator, and PhosphorLayer::NoOpSurfaceAnimator.

◆ beginShow()

virtual void PhosphorLayer::ISurfaceAnimator::beginShow ( Surface * surface,
QQuickItem * rootItem,
CompletionCallback onComplete )
pure virtual

Begin a show transition for surface.

The Surface has just become visible (Hidden → Shown), or is being re-shown while already Shown, which replays the transition. The animator can mutate rootItem (opacity, scale, y-offset) and drive an animation. Invoke onComplete when the transition finishes; the library uses this as a no-op today but a future version may defer compositor sync until the completion signal arrives.

Not dispatched for a surface whose SurfaceConfig::animateRoot is false. cancel() still is, except on a re-show of a Shown surface.

Implemented in PhosphorAnimationLayer::SurfaceAnimator, and PhosphorLayer::NoOpSurfaceAnimator.

◆ cancel()

virtual void PhosphorLayer::ISurfaceAnimator::cancel ( Surface * surface)
pure virtual

Interrupt every in-flight animation for surface, on any item, not only the root.

Called when the Surface is destroyed, on every Shown → Hidden hide, and on every show() before its beginShow. Under SurfaceConfig::animateRoot=false a re-show of a Shown surface skips it, since there is no root leg to supersede.

Implemented in PhosphorAnimationLayer::SurfaceAnimator, and PhosphorLayer::NoOpSurfaceAnimator.


The documentation for this class was generated from the following file: