Animatable::BeginAnimation Method (DependencyProperty^, AnimationTimeline^, HandoffBehavior)
Applies an animation to the specified DependencyProperty. The animation is started when the next frame is rendered. If the specified property is already animated, the specified HandoffBehavior is used.
Assembly: PresentationCore (in PresentationCore.dll)
public: virtual void BeginAnimation( DependencyProperty^ dp, AnimationTimeline^ animation, HandoffBehavior handoffBehavior ) sealed
Parameters
- dp
-
Type:
System.Windows::DependencyProperty^
The property to animate.
- animation
-
Type:
System.Windows.Media.Animation::AnimationTimeline^
The animation used to animate the specified property.
If handoffBehavior is SnapshotAndReplace and the animation's BeginTime is null, any current animations will be removed and the current value of the property will be held.
If handoffBehavior is SnapshotAndReplace and animation is a null reference, all animations will be removed from the property and the property value will revert back to its base value.
If handoffBehavior is Compose, this method will have no effect if the animation or its BeginTime is null.
- handoffBehavior
-
Type:
System.Windows.Media.Animation::HandoffBehavior
A value that specifies how the new animation should interact with any current animations already affecting the property value.
If the animation has a BeginTime that is greater than zero, the animation begins after that amount of time has elapsed from the time the next frame is rendered.
When you apply a Storyboard, AnimationTimeline, or AnimationClock to a property using the Compose HandoffBehavior, any Clock objects previously associated with that property continue to consume system resources; the timing system will not remove these clocks automatically.
To avoid performance issues when you apply a large number of clocks using Compose, you should remove composing clocks from the animated property after they complete. There are several ways to remove a clock.
To remove all clocks from a property, use the ApplyAnimationClock(DependencyProperty^, AnimationClock^) or BeginAnimation(DependencyProperty^, AnimationTimeline^) method of the animated object. Specify the property being animated as the first parameter, and null as the second. This will remove all animation clocks from the property.
To remove a specific AnimationClock from a list of clocks, use the Controller property of the AnimationClock to retrieve a ClockController, then call the Remove method of the ClockController. This is typically done in the Completed event handler for a clock. Note that only root clocks can be controlled by a ClockController; the Controller property of a child clock will return null. Note also that the Completed event will not be called if the effective duration of the clock is forever. In that case, the user will need to determine when to call Remove.
This is primarily an issue for animations on objects that have a long lifetime. When an object is garbage collected, its clocks will also be disconnected and garbage collected.
For more information about clock objects, see the Animation and Timing System Overview.
The following example shows how to apply animations using different HandoffBehavior settings.
/* This sample animates the position of an ellipse when the user clicks within the main border. If the user left-clicks, the SnapshotAndReplace HandoffBehavior is used when applying the animations. If the user right-clicks, the Compose HandoffBehavior is used instead. */ using namespace System; using namespace System::Windows; using namespace System::Windows::Navigation; using namespace System::Windows::Media; using namespace System::Windows::Media::Animation; using namespace System::Windows::Shapes; using namespace System::Windows::Controls; using namespace System::Windows::Input; namespace Microsoft { namespace Samples { namespace Animation { namespace LocalAnimations { public ref class InteractiveAnimationExample : Page { private: TranslateTransform^ interactiveTranslateTransform; Border^ containerBorder; Ellipse^ interactiveEllipse; public: InteractiveAnimationExample () { WindowTitle = "Interactive Animation Example"; DockPanel^ myPanel = gcnew DockPanel(); myPanel->Margin = Thickness(20.0); containerBorder = gcnew Border(); containerBorder->Background = Brushes::White; containerBorder->BorderBrush = Brushes::Black; containerBorder->BorderThickness = Thickness(2.0); containerBorder->VerticalAlignment = System::Windows::VerticalAlignment::Stretch; interactiveEllipse = gcnew Ellipse(); interactiveEllipse->Fill = Brushes::Lime; interactiveEllipse->Stroke = Brushes::Black; interactiveEllipse->StrokeThickness = 2.0; interactiveEllipse->Width = 25; interactiveEllipse->Height = 25; interactiveEllipse->HorizontalAlignment = System::Windows::HorizontalAlignment::Left; interactiveEllipse->VerticalAlignment = System::Windows::VerticalAlignment::Top; interactiveTranslateTransform = gcnew TranslateTransform(); interactiveEllipse->RenderTransform = interactiveTranslateTransform; containerBorder->MouseLeftButtonDown += gcnew MouseButtonEventHandler(this, &Microsoft::Samples::Animation::LocalAnimations::InteractiveAnimationExample::border_mouseLeftButtonDown); containerBorder->MouseRightButtonDown += gcnew MouseButtonEventHandler(this, &Microsoft::Samples::Animation::LocalAnimations::InteractiveAnimationExample::border_mouseRightButtonDown); containerBorder->Child = interactiveEllipse; myPanel->Children->Add(containerBorder); this->Content = myPanel; }; private: // When the user left-clicks, use the // SnapshotAndReplace HandoffBehavior when applying the animation. void border_mouseLeftButtonDown (System::Object^ sender, System::Windows::Input::MouseButtonEventArgs^ e) { System::Windows::Point clickPoint = Mouse::GetPosition(containerBorder); // Set the target point so the center of the ellipse // ends up at the clicked point. Point targetPoint = Point(); targetPoint.X = clickPoint.X - interactiveEllipse->Width / 2; targetPoint.Y = clickPoint.Y - interactiveEllipse->Height / 2; // Animate to the target point. DoubleAnimation^ xAnimation = gcnew DoubleAnimation(targetPoint.X, Duration(TimeSpan::FromSeconds(4))); interactiveTranslateTransform->BeginAnimation(TranslateTransform::XProperty, xAnimation, HandoffBehavior::SnapshotAndReplace); DoubleAnimation^ yAnimation = gcnew DoubleAnimation(targetPoint.Y, Duration(TimeSpan::FromSeconds(4))); interactiveTranslateTransform->BeginAnimation(TranslateTransform::YProperty, yAnimation, HandoffBehavior::SnapshotAndReplace); // Chage the color of the ellipse. interactiveEllipse->Fill = Brushes::Lime; } private: // When the user right-clicks, use the // Compose HandoffBehavior when applying the animation. void border_mouseRightButtonDown (System::Object^ sender, System::Windows::Input::MouseButtonEventArgs^ e) { // Find the point where the use clicked. Point clickPoint = Mouse::GetPosition(containerBorder); // Set the target point so the center of the ellipse // ends up at the clicked point. Point targetPoint = System::Windows::Point(); targetPoint.X = clickPoint.X - interactiveEllipse->Width / 2; targetPoint.Y = clickPoint.Y - interactiveEllipse->Height / 2; // Animate to the target point. DoubleAnimation^ xAnimation = gcnew DoubleAnimation(targetPoint.X, Duration(TimeSpan::FromSeconds(4))); interactiveTranslateTransform->BeginAnimation(TranslateTransform::XProperty, xAnimation, HandoffBehavior::Compose); DoubleAnimation^ yAnimation = gcnew DoubleAnimation(targetPoint.Y, Duration(TimeSpan::FromSeconds(4))); // Change the color of the ellipse. interactiveTranslateTransform->BeginAnimation(TranslateTransform::YProperty, yAnimation, HandoffBehavior::Compose); interactiveEllipse->Fill = Brushes::Orange; } }; } } } }
Available since 3.0