CompositionScopedBatch Class

Reference

Definition

Namespace:: Windows.UI.Composition

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

An explicitly created group of active animations or effects.

public ref class CompositionScopedBatch sealed : CompositionObject

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 131072)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class CompositionScopedBatch final : CompositionObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 131072)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class CompositionScopedBatch : CompositionObject

Public NotInheritable Class CompositionScopedBatch
Inherits CompositionObject

Inheritance: Object Platform::Object IInspectable CompositionObject CompositionScopedBatch

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10586.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v2.0)

Examples

Scoped Batch

// The Green Square's completion events for the Offset and Opacity animations are aggregated
// The Rotation animation completion event is not aggregated
// When the aggregated events are completed OnBatchCompleted method is executed
public void BatchAnimations()
{
    // Create a Scoped batch to capture animation completion events
    _batch = _compositor.CreateScopedBatch(CompositionBatchTypes.Animation);

    // Executing the Offset animation and aggregating completion event
    ApplyOffsetAnimation(_greenSquare);

    // Suspending to exclude the following Rotation animation from the batch
    _batch.Suspend();

    // Executing the Rotation animation 
    ApplyRotationAnimation(_greenSquare);

    // Resuming the batch to collect additional animations
    _batch.Resume();

    // Executing the Opacity animation and aggregating completion event
    ApplyOpacityAnimation(_greenSquare);

    // Batch is ended and no objects can be added
    _batch.End();

    // Method triggered when batch completion event fires
    _batch.Completed += OnBatchCompleted;
}

Remarks

Represents a group of active animations or effects, and triggers a callback when all members of the group have completed. A CompositionScopedBatch is explicitly created and is used to designate specific objects to be included in a single scoped batch.

Multiple CompositionScopedBatch instances can be created and objects can be aggregated in multiple batches at the same time.

Create

To aggregate a specific group of animations or target a single animation’s completion event, you create a scoped batch. A scoped batch is explicitly created using Compositor.CreateScopedBatch and is used to designate specific objects to be included in a single batch. A scoped batch can be created on any thread and is not tied to the composition thread. Scoped batches will only aggregate objects within the thread it is created.

CompositionScopedBatch myScopedBatch = _compositor.CreateScopedBatch(CompositionBatchTypes.Animation);

Suspend and resume

After creating a scoped batch, all started animations aggregate until the batch is explicitly suspended or ended using the Suspend or End function.

CompositionScopedBatch may be explicitly paused with Suspend in order to exclude objects from that batch. When a batch is suspended it can be reopened by calling Resume. Calling the Suspend function stops aggregating animation end states until Resume is called. This allows you to explicitly exclude content from a given batch.

In the example below, the animation targeting the Offset property of VisualA will not be included in the batch:

myScopedBatch.Suspend();
VisualA.StartAnimation("Offset", myAnimation);
myScopeBatch.Resume();

End

A CompositionScopedBatch must be explicitly closed using End. Once it has been closed it cannot be suspended or resumed again. In order to complete your batch you must call End(). Without an End call, the batch will remain open forever-collecting objects.

The following code snippet and diagram shows an example of how the batch will aggregate animations to track end states.

Note that in this example, Animations 1, 3, and 4 will have end states tracked by this Batch, but Animation 2 will not.

myScopedBatch.End();
CompositionScopedBatch myScopedBatch = 	_compositor.CreateScopedBatch(CompositionBatchTypes.Animation);
// Start Animation1
[…]
myScopedBatch.Suspend();
// Start Animation2 
[…]
myScopedBatch.Resume();
// Start Animation3
[…]
// Start Animation4
[…]
myScopedBatch.End();

The scoped batch contains animation one, animation three, and animation four while animation two is excluded from the scoped batch

Batching a single animation's completion event

If you want to know when a single animation ends, you need to create a scoped batch that will include just the animation you are targeting.

For example:

CompositionScopedBatch myScopedBatch = 	_compositor.CreateScopedBatch(CompositionBatchTypes.Animation);
Visual.StartAnimation("Opacity", myAnimation);
myScopedBatch.End();

Retrieving a batch's completion event

When batching an animation or multiple animations, you will retrieve the batch’s completion event the same way. You register the event-handling method for the Completed event of the targeted batch.

myScopedBatch.Completed += OnBatchCompleted;

Batch states

There are two properties you can use to determine the state of an existing batch; IsActive and IsEnded.

The IsActive property returns true if a targeted batch is open to aggregating animations. IsActive will return false when a batch is suspended or ended.

The IsEnded property returns true when you cannot add an animation to that specific batch. A batch will be ended when you call explicitly call End for a specific batch.

Properties

Comment	A string to associate with the CompositionObject. (Inherited from CompositionObject)
Compositor	The Compositor used to create this CompositionObject. (Inherited from CompositionObject)
Dispatcher	The dispatcher for the CompositionObject. (Inherited from CompositionObject)
DispatcherQueue	Gets the DispatcherQueue for the CompostionObject. (Inherited from CompositionObject)
ImplicitAnimations	The collection of implicit animations attached to this object. (Inherited from CompositionObject)
IsActive	Indicates whether the CompositionScopedBatch is currently opened for objects to be aggregated.
IsEnded	Indicates whether the CompositionScopedBatch has been closed and can no longer accept changes.
Properties	The collection of properties associated with the CompositionObject. (Inherited from CompositionObject)

Methods

Close()	Closes the CompositionObject and releases system resources. (Inherited from CompositionObject)
ConnectAnimation(String, CompositionAnimation)	Connects and animation. (Inherited from CompositionObject)
DisconnectAnimation(String)	Disconnects an animation. (Inherited from CompositionObject)
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from CompositionObject)
End()	Closes the CompositionScopedBatch. Once the CompositionScopedBatch has been closed it cannot be suspended or resumed again.
PopulatePropertyInfo(String, AnimationPropertyInfo)	Defines a property that can be animated. (Inherited from CompositionObject)
Resume()	Resumes aggregating objects in the CompositionScopedBatch.
StartAnimation(String, CompositionAnimation)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimation(String, CompositionAnimation, AnimationController)	Connects an animation with the specified property of the object and starts the animation. (Inherited from CompositionObject)
StartAnimationGroup(ICompositionAnimationBase)	Starts an animation group. The StartAnimationGroup method on CompositionObject lets you start CompositionAnimationGroup. All the animations in the group will be started at the same time on the object. (Inherited from CompositionObject)
StopAnimation(String)	Disconnects an animation from the specified property and stops the animation. (Inherited from CompositionObject)
StopAnimationGroup(ICompositionAnimationBase)	Stops an animation group. (Inherited from CompositionObject)
Suspend()	Suspends aggregating objects in the CompositionScopedBatch.
TryGetAnimationController(String)	Returns an AnimationController for the animation running on the specified property. (Inherited from CompositionObject)

Events

Completed

Event triggered once all animations and effects in the CompositionScopedBatch have completed.

Applies to