cf::ui::components::material::CFMaterialAnimationFactory

Material Design 3 Animation Factory. More...

#include <cfmaterial_animation_factory.h>

Inherits from cf::ui::components::ICFAnimationManagerFactory, QObject

Public Signals

	Name
void	animationCreated(constQString & token) Signal emitted when an animation is created.
void	animationEnabledChanged(bool enabled) Signal emitted when global enabled state changes.

Public Functions

	Name
	CFMaterialAnimationFactory(constcore::ICFTheme & theme, std::unique_ptr< AnimationStrategy > strategy =nullptr, QObject * parent =nullptr) Constructor with theme reference.
	~CFMaterialAnimationFactory() override Destructor.
	CFMaterialAnimationFactory(constCFMaterialAnimationFactory & ) =delete
CFMaterialAnimationFactory &	operator=(constCFMaterialAnimationFactory & ) =delete
	CFMaterialAnimationFactory(CFMaterialAnimationFactory && ) =delete
CFMaterialAnimationFactory &	operator=(CFMaterialAnimationFactory && ) =delete
virtual cf::WeakPtr< ICFAnimationManagerFactory >	GetWeakPtr() override
virtual ICFAnimationManagerFactory::RegisteredResult	registerOneAnimation(constQString & name, constQString & type) override Register an animation type by name.
virtual ICFAnimationManagerFactory::RegisteredResult	registerAnimationCreator(constQString & name, AnimationCreator creator) override Register an animation with a creator function.
virtual cf::WeakPtr< ICFAbstractAnimation >	getAnimation(constchar * animationToken) override Get or create an animation by token name.
cf::WeakPtr< ICFAbstractAnimation >	createAnimation(constAnimationDescriptor & descriptor, QWidget * targetWidget =nullptr, QObject * owner =nullptr) Create an animation from a descriptor.
cf::WeakPtr< ICFAbstractAnimation >	createPropertyAnimation(float * value, float from, float to, int durationMs, cf::ui::base::Easing::Type easing =cf::ui::base::Easing::Type::EmphasizedDecelerate, QWidget * targetWidget =nullptr, QObject * owner =nullptr) Create a property animation for a float value.
void	setStrategy(std::unique_ptr< AnimationStrategy > strategy) Set the animation strategy for this factory.
AnimationStrategy *	strategy() const Get the current animation strategy.
virtual void	setEnabledAll(bool enabled) override Set the global enabled state for all animations.
virtual bool	isAllEnabled() override Check if animations are globally enabled.
void	setTargetFps(constfloat fps) Set the target FPS for animations.
constcore::ICFTheme &	theme() const Get the associated theme.
size_t	animationCount() const Get the number of animations managed by this factory.
float	getTargetFps() const Get the target FPS for animations.

Additional inherited members

Public Types inherited from cf::ui::components::ICFAnimationManagerFactory

	Name
enum class	RegisteredResult { OK, DUP_NAME, UNSUPPORT_TYPE} Registration result enumeration.

Public Signals inherited from cf::ui::components::ICFAnimationManagerFactory

	Name
void	animationRegistered(constQString & name) Signal emitted when an animation is registered.

Public Functions inherited from cf::ui::components::ICFAnimationManagerFactory

	Name
	ICFAnimationManagerFactory(QObject * parent) Constructor with parent.
	~ICFAnimationManagerFactory() override =default Virtual destructor.
void	setTargetEnabled(constQString & which, constbool enabled) Set enabled state for a specific animation.
bool	targetEnabled(constQString & which) Check if a specific animation is enabled.

Detailed Description

class cf::ui::components::material::CFMaterialAnimationFactory;

Material Design 3 Animation Factory.

Exceptions:

• None (all errors return invalid WeakPtr)

Since: 0.1

Note: Thread-safe for concurrent reads.

Warning: Animations are owned by the factory; WeakPtr may become invalid if the factory is destroyed.

Creates and manages animations following Material Design 3 motion specifications. The factory maintains exclusive ownership of created animations (via unique_ptr) and provides WeakPtr access to users.

Animation lifecycle:

1. User calls getAnimation("md.animation.fadeIn")
2. Factory resolves token to AnimationDescriptor via token mapping
3. Strategy adjusts descriptor (if set)
4. Factory creates animation instance
5. Factory stores animation (owns it)
6. Factory returns WeakPtr to user

Token resolution:

• "md.animation.fadeIn" → Fade animation, shortEnter timing
• "md.animation.slideUp" → Slide animation, mediumEnter timing
• "md.animation.scaleUp" → Scale animation, shortEnter timing

// Initialization (usually done once per application)
using namespace cf::ui::components::material;
using namespace cf::ui::core;

MaterialFactory themeFactory;
auto theme = themeFactory.fromName("theme.material.light");
auto factory = std::make_unique<CFMaterialAnimationFactory>(*theme);
factory->setStrategy(std::make_unique<ButtonAnimationStrategy>());

// Basic usage - get animation by token
auto fadeIn = factory->getAnimation("md.animation.fadeIn");
if (fadeIn) {
    fadeIn->setTargetWidget(myWidget);
    fadeIn->start();
}

// Create with custom descriptor
AnimationDescriptor desc{"fade", "md.motion.longEnter", "opacity", 0.0f, 1.0f};
auto customFade = factory->createAnimation(desc, myWidget);

// Enable/disable all animations
factory->setEnabledAll(false);  // Disable animations for performance

Public Signals Documentation

signal animationCreated

void animationCreated(
    constQString & token
)

Signal emitted when an animation is created.

Parameters:

• token The animation token that was created.

Since: 0.1

signal animationEnabledChanged

void animationEnabledChanged(
    bool enabled
)

Signal emitted when global enabled state changes.

Parameters:

• enabled The new enabled state.

Since: 0.1

Public Functions Documentation

function CFMaterialAnimationFactory

explicit CFMaterialAnimationFactory(
    constcore::ICFTheme & theme,
    std::unique_ptr< AnimationStrategy > strategy =nullptr,
    QObject * parent =nullptr
)

Constructor with theme reference.

Parameters:

• theme Reference to the Material Design theme.
• strategy Optional strategy for widget-specific behavior. If nullptr, DefaultAnimationStrategy is used.
• parent QObject parent.

Exceptions:

• None

Since: 0.1

Note: If strategy is nullptr, DefaultAnimationStrategy is used.

Warning: The theme must outlive this factory.

The theme reference must remain valid for the lifetime of the factory. It is used to query MotionSpec values (duration, easing) for animations.

CFMaterialAnimationFactory factory(*theme);

function ~CFMaterialAnimationFactory

~CFMaterialAnimationFactory() override

Destructor.

Since: 0.1

All owned animations are destroyed. Any WeakPtr returned by this factory becomes invalid.

function CFMaterialAnimationFactory

CFMaterialAnimationFactory(
    constCFMaterialAnimationFactory & 
) =delete

function operator=

CFMaterialAnimationFactory & operator=(
    constCFMaterialAnimationFactory & 
) =delete

function CFMaterialAnimationFactory

CFMaterialAnimationFactory(
    CFMaterialAnimationFactory && 
) =delete

function operator=

CFMaterialAnimationFactory & operator=(
    CFMaterialAnimationFactory && 
) =delete

function GetWeakPtr

inline virtual cf::WeakPtr< ICFAnimationManagerFactory > GetWeakPtr() override

Reimplements: cf::ui::components::ICFAnimationManagerFactory::GetWeakPtr

function registerOneAnimation

virtual ICFAnimationManagerFactory::RegisteredResult registerOneAnimation(
    constQString & name,
    constQString & type
) override

Register an animation type by name.

Parameters:

• name Unique name for the animation.
• type Animation type identifier.

Exceptions:

• None

Return: Registration result indicating success or failure reason.

Since: 0.1

Note: None

Warning: None

Reimplements: cf::ui::components::ICFAnimationManagerFactory::registerOneAnimation

function registerAnimationCreator

virtual ICFAnimationManagerFactory::RegisteredResult registerAnimationCreator(
    constQString & name,
    AnimationCreator creator
) override

Register an animation with a creator function.

Parameters:

• name Unique name for the animation.
• creator Function that creates the animation instance.

Exceptions:

• None

Return: Registration result indicating success or failure reason.

Since: 0.1

Note: None

Warning: None

Reimplements: cf::ui::components::ICFAnimationManagerFactory::registerAnimationCreator

function getAnimation

virtual cf::WeakPtr< ICFAbstractAnimation > getAnimation(
    constchar * animationToken
) override

Get or create an animation by token name.

Parameters:

• animationToken Token name (e.g., "md.animation.fadeIn").

Exceptions:

• None

Return: WeakPtr to the animation, or invalid WeakPtr if:

• Token is not found in mapping
• Animation type is not supported
• Global enabled is false
• Strategy disables animation

Since: 0.1

Note: If the animation doesn't exist, a new animation is created.

Warning: The returned WeakPtr may become invalid if the factory is destroyed. Always check validity before use.

Reimplements: cf::ui::components::ICFAnimationManagerFactory::getAnimation

This is the primary user API for retrieving animations. Tokens are resolved through the token mapping system:

• "md.animation.fadeIn" → Fade animation, shortEnter timing
• "md.animation.slideUp" → Slide animation, mediumEnter timing
• "md.animation.scaleUp" → Scale animation, shortEnter timing

If an animation with the given token already exists, the existing animation's WeakPtr is returned. Otherwise, a new animation is created and stored.

auto anim = factory->getAnimation("md.animation.fadeIn");
if (anim) {
    anim->setTargetWidget(myWidget);
    anim->start();
}

function createAnimation

cf::WeakPtr< ICFAbstractAnimation > createAnimation(
    constAnimationDescriptor & descriptor,
    QWidget * targetWidget =nullptr,
    QObject * owner =nullptr
)

Create an animation from a descriptor.

Parameters:

• descriptor Animation configuration descriptor.
• targetWidget Optional target widget for the animation. The animation applies to this widget.
• owner Optional owner QObject for memory management.

Exceptions:

• None

Return: WeakPtr to the created animation, or invalid WeakPtr if:

• Animation type is not supported
• Global enabled is false
• Strategy disables animation

Since: 0.1

Note: The factory takes ownership of the created animation.

Warning: None

Creates a new animation instance based on the descriptor. The strategy (if set) is applied before creation.

Unlike getAnimation(), this method always creates a new animation instance, even if one with the same configuration already exists.

AnimationDescriptor desc{"fade", "md.motion.longEnter", "opacity", 0.0f, 1.0f};
auto anim = factory->createAnimation(desc, myWidget);
if (anim) anim->start();

function createPropertyAnimation

cf::WeakPtr< ICFAbstractAnimation > createPropertyAnimation(
    float * value,
    float from,
    float to,
    int durationMs,
    cf::ui::base::Easing::Type easing =cf::ui::base::Easing::Type::EmphasizedDecelerate,
    QWidget * targetWidget =nullptr,
    QObject * owner =nullptr
)

Create a property animation for a float value.

Parameters:

• value Pointer to the float property to animate. Must remain valid for the lifetime of the animation.
• from Start value of the animation.
• to End value of the animation.
• durationMs Duration of the animation in milliseconds.
• easing Easing type for the animation.
• targetWidget Optional target widget for repaint notifications.

Exceptions:

• None

Return: WeakPtr to the created animation, or invalid WeakPtr if:

• Global enabled is false
• Strategy disables animation

Since: 0.1

Note: The factory takes ownership of the created animation.

Warning: The value pointer must remain valid during animation.

Creates a property animation that directly animates a float value from a start value to an end value. This is useful for simple property animations like floating labels, scale, etc.

Unlike createAnimation(), this method always creates a new animation instance and does not use token-based lookup.

float scale = 0.0f;
auto anim = factory->createPropertyAnimation(&scale, 0.0f, 1.0f, 200,
                                            Easing::Type::EmphasizedDecelerate,
                                            this);
if (anim) anim->start();

function setStrategy

void setStrategy(
    std::unique_ptr< AnimationStrategy > strategy
)

Set the animation strategy for this factory.

Parameters:

• strategy Unique pointer to the strategy (takes ownership). Pass nullptr to use DefaultAnimationStrategy.

Exceptions:

• None

Since: 0.1

Note: Pass nullptr to use the default strategy.

Warning: The factory takes ownership of the strategy.

The strategy is applied to all animations created after this call. Existing animations are not affected.

Strategies allow widget-specific customization:

• Buttons: shorter animations
• Dialogs: longer animations
• Lists: staggered animations

factory->setStrategy(std::make_unique<ButtonAnimationStrategy>());

function strategy

inline AnimationStrategy * strategy() const

Get the current animation strategy.

Return: Pointer to the current strategy (may be nullptr).

Since: 0.1

function setEnabledAll

virtual void setEnabledAll(
    bool enabled
) override

Set the global enabled state for all animations.

Parameters:

• enabled true to enable animations, false to disable.

Exceptions:

• None

Since: 0.1

Note: This affects all animation creation methods.

Warning: Existing animations continue to run; only new creations are affected.

Reimplements: cf::ui::components::ICFAnimationManagerFactory::setEnabledAll

When disabled, getAnimation() returns invalid WeakPtr and createAnimation() returns invalid WeakPtr.

This is useful for:

• Performance optimization during heavy processing
• Accessibility (respect "reduce motion" settings)
• User preference (animation toggle)

// Disable animations during heavy processing
factory->setEnabledAll(false);
// ... do heavy work ...
factory->setEnabledAll(true);

function isAllEnabled

inline virtual bool isAllEnabled() override

Check if animations are globally enabled.

Return: true if animations are enabled, false otherwise.

Since: 0.1

Reimplements: cf::ui::components::ICFAnimationManagerFactory::isAllEnabled

function setTargetFps

void setTargetFps(
    constfloat fps
)

Set the target FPS for animations.

Parameters:

• fps Target frames per second (e.g., 60.0f).

Exceptions:

• None

Since: 0.1

Note: Default is 60.0f. Changes take effect immediately.

Warning: None

Sets the desired frame rate for animation updates. This affects the tick interval for all animations created by this factory, including existing animations.

factory->setTargetFps(30.0f);   // 30 FPS (lower CPU usage)
factory->setTargetFps(120.0f);  // 120 FPS (smoother animation)

function theme

inline constcore::ICFTheme & theme() const

Get the associated theme.

Return: Reference to the theme.

Since: 0.1

Warning: The theme must outlive this factory.

function animationCount

inline size_t animationCount() const

Get the number of animations managed by this factory.

Return: Number of owned animations.

Since: 0.1

function getTargetFps

inline float getTargetFps() const

Get the target FPS for animations.

Exceptions:

• None

Return: Target frames per second (default: 60.0f).

Since: 0.1

Note: Use setTargetFps() to change this value.

Warning: None

Returns the current target frame rate for animation updates. This value is used by all animations created by this factory.

float fps = factory->getTargetFps();  // Returns 60.0f by default

---

Updated on 2026-03-09 at 10:14:00 +0000