In Part 1 we covered the basic history of animating in Xojo using pre-calculated chunks to modify the width of our component. In Part 2 we went a bit further by using linear interpolation (lerp) to calculate our current width at each step of the animation process, and setup for concurrent animation.
In this part we’ll be covering a few different things, chiefly concurrent animations. But that’s not all, as I’ve added a lerpColor function to show you how to animate color changes.
Concurrent Animations
Using self-contained concurrent animations in a UI class is an interesting exercise. You need to have the basic setup for an animation controller complete with a method of adding animation operations to a queue and removing completed animations. Typically, however, if you were building out animations on an application scale, you’d build a class that acted as the animation controller and may raise events for updating the elements as the animation progresses. In this example we’ll just build them straight in to our component because we want this to be entirely independent of the rest of the application architecture.
As this part focuses on concurrent animations, we’re not implementing a keyframe methodology for queuing. We’re using the queue purely to have multiple animations running together.
Defining The Queue
In Part 2 we added the following property to AnimatedCanvas:
animQueue As Dictionary
For this part, we’re going to make a slight modification to that property definition so that it will support multiple animation operations. We’re just going to turn it into an array:
animQueue() As Dictionary
Dictionary Changes
If you remember from last time we used the following definition for our Dictionary objects:
- Start Time
- Start Width
- End Width
In this part we’re going to further leverage Dictionary’s use of Variant to expand our functionality. While we previously used the following Dictionary structure for our operations:
Dictionary("s" : <StartTimeInMicroseconds>, "sw" :<StartWidth> , "ew" : <EndWidth>)
We’re now defining our animOp Dictionaries as:
Dictionary("op" : <OperationToAnimate>, "l" : <AnimationLength>, "t" : <StartTimeInMicroseconds>, "s" <StartValue>: , "e" : <EndValue>, "o" : <OptionalOlderAnimationOp>)
This allows us to create an animation operation for practically anything we can think of as long as we properly code for it in our animation Timer’s Action event handler method, and give it any length we desire rather than a common time for all operations.
Adding to the Queue
We’re going to add a new method to our AnimatedCanvas class called animQueue_Add that takes animOp As Dictionary for its sole parameter. This method will act as a basic out-of-the-loop controller when an animation is to be triggered and determine if this is a new animation operation or one that is already currently in the queue.
In this example I’ve setup for both a Cancel/Start type animation operation (which completely cancels the previous animation and begins a new one with the full animation time), and Continue type animation operation that preserves the original animation time within the new animation time, which is explained in more depth later.
Private Sub animQueue_Add(animOp as Dictionary)
'// This method is part of our animation controller.
' It appends to or modifies our animation queue,
' which runs concurrent rather than consecutive
' operations.
' We first check to make sure that the new animation
' operation dictionary isn't nil.
if IsNull(animOp) then Return
'// We need to find out if we already have an operation
' in the queue for this, so we're going to store our
' index in a variable, which we'll get from our new
' anim_IndexOf method.
dim foundIndex as Integer = animQueue_IndexOf(animOp.Value("op"))
'// If the operation exists, overwrite it. Otherwise,
' append it to our queue so that the timer will
' pick it up on its next Action.
if foundIndex >= 0 then
'// We're also going to implement what I call Time
' Preservation. I'm sure there another name that
' this is more commonly referred to as, but I
' just don't know it. When PreserveTimes = True
' then the animation operation overwrite will
' only use the remaining time of the oldest
' overriden animation operation.
if mPreserveTimes then
'// Grab the oldest op in our override chain so
' we can perform the math necessary to calculate
' an appropriate time remainder.
dim oldOp as Dictionary = animQueue_OldestOp(animQueue(foundIndex))
if not IsNull( oldOp ) then
'// Set our animation length to the remaining value.
' We're getting the assigned length of the animation
' and subtracted the difference between our two
' operation start times.
animOp.Value("l") = animOp.Value("l") - ((animOp.Value("t").DoubleValue - oldOp.Value("t").DoubleValue) / 1000)
'// Set oldOp to our "o" key in case of future overrides.
animOp.Value("o") = oldOp
end if
end if
'// Overwrite the operation.
animQueue(foundIndex) = animOp
else
'// Add the operation to the queue.
animQueue.Append(animOp)
end if
'// Make sure that our animation timer is enabled.
animTimer.Mode = 2
End Sub
As you can see, it’s not an incredibly complex method. We’re just checking our animQueue property to see an animation currently exists for this operation. If we find it, we replace it. If we don’t, we just add it to the tail-end of the queue. The final line, as in the previous version, kicks off our animation timer.
Checking Our Queue
The next new method we’re going to add is our method to check if the animation operation already exists in our queue. It’s a straightforward method where we compare the “op” value of items in the queue to a specified “op” value. If an operation exists for that action, we return the index within the queue, otherwise return -1.
Private Function animQueue_IndexOf(op as String) as Integer
'// This method will check our queue for the
' operation specified in the "op" parameter.
' If it exists, we'll return the index. Otherwise
' we return -1 to denote that this is a new op.
'// We're creating our variable before hand so
' we're not doing it in each iteration of the
' loop, which could slow things down a bit.
dim currDict as Dictionary
'// Likewise, we're creating a variable to store
' the maximum index of our animQueue array. If
' we did this, instead, in the For statement,
' the value would be recalculated each time
' unless something changed that I don't know about.
dim intMax as Integer = animQueue.Ubound
'// We're starting from the end, just in case
' the contents of the queue change in the middle,
' we're less likely to hit an exception.
for intCycle as Integer = intMax DownTo 0
'// We're still going to add exception handling
' just in case.
Try
currDict = animQueue(intCycle)
Catch e as OutOfBoundsException
Continue
End Try
'// If our current dictionary's "op" value
' matches the "op" value we're searching for
' then we'll return the index. if currDict.Value("op") = op then
Return intCycle
end if
next
'// No matching operation found, so we return -1.
Return -1
End Function
Time Preservation
One new feature we’re implementing is what I call animation time preservation. This shortens subsequent animations of the same operation to honor the original time until one of them is able to complete.
PreserveTimes property
For our animation time preservation, we’re adding a property to the class so we can turn this on and off at will. We’ll make it public and computed so we can add it to the inspector.
Private Property mPreserveTimes as Boolean = True
Public Property PreserveTimes as Boolean
Get
Return mPreserveTimes
End Get
Set
mPreserveTimes = value
End Set
End Property
Getting the Oldest Op
This all really relies on one method, animQueue_OldestOp which checks the “o” key of the specified animation operation to see if an older operation already exists. If it does, we’ll return it, otherwise return the operation passed in to the method. If you take a look at the changes to animQueue_Add above, you’ll see how we use this.
'// In this method we're just checking to see if
' there was a pre-existing operation when this
' one was created so that we can use its start
' time to shorten our new animation time.
if IsNull(animOp) then Return Nil
if animOp.HasKey("o") then
dim oldOp as Dictionary = animOp.Value("o")
Return oldOp
end if
Return animOp
Expanding the Height
For this example, to highlight multiple concurrent animations, I’ve also added the ability to animate the height in addition to the width. We’re basically just duplicating the existing properties for our width animation, but applying the values to height. This could be modified to use a Point or Rect to achieve the same effect, but this implementation is better for showing how the modifications we’ll be making to the animation Timer’s action actually work by breaking it down independently.
Properties
As with our Width animation, we need to track what our target expanded Height should be as well as the current state of that dimension. For Width we have an expandedWidth property, so we’ll add an expandedHeight property to match.
Private Property expandedHeight as Integer
In this version, we’re also renaming our old expanded property to isExpandedWidth:
Private Property isExpandedWidth as Boolean = True
And adding a new corresponding property for Height:
Private Property isExpandedHeight as Boolean = True
Finally, we need a property that keeps track of whether we’re currently animating our dimensions so that our subsequent clicks during a color-only animation properly toggle our isExpanded* properties. We could do this by searching the animOp array, but just storing it is probably a bit quicker.
Private Property isAnimatingDimensions as Boolean
There are better ways to implement tacking of these states, but for this example I want the verbosity.
MouseUp Changes
Since we’re now animating both Width and Height and implementing our rudimentary animation controller, we need to make some changes to our MouseUp event handler. Primarily we’re duplicating what we already do for Width to account for our new Height animation, and applying the changes to the properties we’ve already discussed. We check to see if we’re currently animating Width or Height before toggling their values to avoid issues in the animation timer’s Action handler.
Sub MouseUp(X As Integer, Y As Integer) Handles MouseUp
'// Just in case we hit some strange scenario where
' the timer is disposed of. Should, theoretically,
' never happen in this case, but better safe than sorry.
if IsNull(animTimer) then Return
'// Now we're going to check for a currently running
' animation. If an animation operation of this type is
' already underway, all we need to do
' is switch the direction the animation is running.
' In a full animation controller, this would be handled
' internally by chaining or cancelling, most likely,
' but this works for our purposes.
if animQueue_IndexOf("width") >= 0 then
isExpandedWidth = not isExpandedWidth
end if
if animQueue_IndexOf("height") >= 0 then
isExpandedHeight = not isExpandedHeight
end if
'// Here we create our dictionary objects containing
' everything our Timer's action event needs to do
' the work. The current time in Microseconds, which
' will be our start time, the start value, and the
' expected result value. This "10" is hard-coded
' just so that we can actually click on the canvas
' again to reverse the animation if it is fully
' collapsed. In most scenarios you wouldn't have
' a hard-coded value like this and you may even be
' triggering the animation from a different element
' altogether, so this value is purely for demonstration
' purposes in this project.
' animQueue_Add is a new method in this part of the
' series, and acts as an animation controller.
animQueue_Add(new Dictionary("op" : "width", "l" : manimTime, "t" : Microseconds, "s" : Width, "e" : If(isExpandedWidth, 10, expandedWidth)))
animQueue_Add(new Dictionary("op" : "height", "l" : manimTime, "t" : Microseconds, "s" : Height, "e" : If(isExpandedHeight, 10, expandedHeight)))
'// Finally, enable the timer to perform the animation.
animTimer.Mode = 2
'// We've added this event, just in case there's
' something you want to trigger at the start of the
' animation.
RaiseEvent BeforeAnimate
End Sub
The New lerpColor
For Part 3, I wanted to add a little something extra before we roll in to Part 4, just to show how we can use linear interpolation for animating any number of different properties of our AnimatedCanvas class. That means we’re going to animate the background color of our class as well!
New Properties
To support our color animation in this specific example, we need a couple of new properties. These properties give us our start and end points for our color animation, and we’re going to add them to the inspector so that they can be changed when editing a Window or ContainerControl view.
- BackgroundColor represents our default background color, which I’ve set to default as red.
- BackgroundColorHover represents the color we want to see when the mouse is over the control, which defaults to blue.
- currentBackgroundColor represents the background color we want to actually apply, and is changed during the animation process.
Public Property BackgroundColor as Color
Get
Return mBackgroundColor
End Get
Set
mBackgroundColor = value
End Set
End Property
Public Property BackgroundColorHover as Color
Get
Return mBackgroundColorHover
End Get
Set
mBackgroundColorHover = value
End Set
End Property
Private Property mBackgroundColor as Color = &cff0000
Private Property mBackgroundColorHover as Color = &c0000ff
Private Property currentBackgroundColor as Color = &cff0000
The Paint Event
Our Paint event only needs one small modification to account for the changes we’re making. We previously used a static red color &cff0000 but we need to switch to using the currentBackgroundColor property to support the animation.
Sub Paint(g As Graphics, areas() As REALbasic.Rect) Handles Paint '// Fill the canvas with our current color. g.ForeColor = currentBackgroundColor g.FillRect(0, 0, g.Width, g.Height) End Sub
The MouseEnter Event
Our first step in animating the color for this example is to implement the MouseEnter event within our class. We’re simply creating a new Dictionary for the animation operation, populating that with our values to be used in the animation timer, then calling animQueue_Add.
Sub MouseEnter() Handles MouseEnter
'// In this version, we're going to animate color change
' based on whether the mouse is over the control.
' So in MouseEnter we start animating from our
' currentBackgroundColor to our BackgroundColorHover.
if me.Enabled then
animQueue_Add(new Dictionary("op" : "color", "l" : 250, "t" : Microseconds, "s" : currentBackgroundColor, "e" : mBackgroundColorHover))
end if
End Sub
You’ll notice that, without the comments, this entire event handler is very short. Part of the goal as I build this functionality is always to make it as easy to implement as possible as I’ll likely use it in a number of different ways for each UI component. Sometimes I have the Dictionary values as parameters of the animQueue_Add method, but I want to show this in this way for this example.
If I’m implementing animation on an application-wide scale, I’ll typically use a custom class called AnimationOperation, with the values for the operation stored as properties and passed via the Constructormethod, then a call to add the resulting class instance to the queue for the AnimationController.
We also assign a static 250ms to color change animations, just to test our dynamic animation times, but you may typically want color change animations to be quicker than other animations in your application just so they stand out less.
The MouseExit Event
MouseExit, like MouseEnter, just creates and adds an animation operation dictionary with the values we want to use. In this case, we want to revert the color back to the default background color.
Sub MouseExit() Handles MouseExit
'// In this version, we're going to animate color change
' based on whether the mouse is over the control.
' So in MouseExit we start animating from our
' currentBackgroundColor to our default BackgroundColor.
if me.Enabled then
animQueue_Add(new Dictionary("op" : "color", "l" : 250, "t" : Microseconds, "s" : currentBackgroundColor, "e" : mBackgroundColor))
end if
End Sub
The lerpColor Method
Now that we have our class setup out of the way, we can create our lerpColor method. In this example I’m simply applying linear interpolation to the Red, Green, and Blue values of the passed colors, but you could use any other subset of color properties that you want for your desired effect.
Private Function lerpColor(startColor as Color, endColor as Color, alphaValue as Double) as Color '// This method takes starting and ending color values ' and applies the lerp method for linear interpolation to ' the constituent Red, Green and Blue values to generate ' the new color value based on the animation's elapsed ' time. ' This could be switched from RGB for different effects, ' or you could just use Color.Alpha for making objects ' fade in or out. dim animStepR as Double = Lerp(startColor.Red, endColor.Red, alphaValue) dim animStepG as Double = Lerp(startColor.Green, endColor.Green, alphaValue) dim animStepB as Double = Lerp(startColor.Blue, endColor.Blue, alphaValue) Return RGB(animStepR, animStepG, animStepB) End Function
The Timer Action Handler
This is where we’re making the most changes in a single method. Not only are we implementing the animation controller methodology, but we’re also adding two new animation operations — height and color, in addition to the original width — so a lot of this will look different from Parts 1 & 2 in this series.
Private Sub animTimer_Action(sender as Timer) '// We're going to declare all of our variables outside of the ' loop so that we're not using precious time and resources ' in every iteration of the loop doing it. dim animOp as Dictionary dim animOpType as String dim animStepDouble as Double dim animStepColor as Color dim animStartTime, timePercent, animLength as Double dim animStartDouble, animEndDouble as Double dim animStartColor, animEndColor, newColor as Color '// Declare our loop maximum variable. Historically each ' iteration of the loop was known to traverse the array ' to get the maximum value if this wasn't stored in advance. ' I haven't tested this myself recently. dim intMax as Integer = animQueue.Ubound '// We start at Ubound and traverse the array in reverse because ' we'll be removing animations from the queue as they complete, ' and this is the best way to avoid OutOfBoundsExceptions. for intCycle as Integer = animQueue.Ubound DownTo 0'// Get our current operation dictionary from the queue.animOp = animQueue(intCycle)'// Our first step is to make sure we actually have an animation' to perform.if IsNull(animOp) then'// For whatever reason, this entry has been cleared. We'll' just remove it and continue with the next operation.animQueue.Remove(intCycle)Continueend if'// Now we'll get our operation values from the dictionary object.' it is possible to run into KeyNotFoundExceptions here, since' we're not checking first, but if you do, then you've likely' made an error when modifying the code. No animQueue Dictionary' should be created without the same set of values since we're' making use of variant for the values dependiong on the "op"' kay's value.animOpType = animOp.Value("op").StringValueanimStartTime = animOp.Value("t").DoubleValueanimLength = animOp.Value("l").DoubleValue'// timePercent is used in the lerp function and gives us a basis' for dividing up the distance we need to cover in to constituent' pieces for animating. We also use this for cutting out of the' animation at the appropriate time. This value ranges from' 0 to 1.0. We subtract our start time from the current time in' microseconds, then divide by one thousand to convert that in to' milliseconds. We then divide the result of that by our AnimationTime' as that's already expressed in milliseconds.timePercent = (((Microseconds - animStartTime) / 1000) / animLength)'// In this part of the series, I show how to animate color changes' as well as dimensions. This method uses RGB, but you could' alter lerpColor to use any other method you wish.if animOpType = "color" then'// Get our animation start and end values.animStartColor = animOp.Value("s").ColorValueanimEndColor = animOp.Value("e").ColorValue'// Now we're going to pass the necessary parameters in to' our new lerpColor function to get the current expected' color at this stage of the animation.animStepColor = lerpColor(animStartColor, animEndColor, timePercent)'// Check to see if this animation operation is complete.' If so, we remove the operation from the queue and' move on.if animStepColor = animEndColor or timePercent >= 1 thencurrentBackgroundColor = animEndColoranimQueue.Remove(intCycle)Continueend if'// Assign our lerped color value to the currentBackgroundColor property.currentBackgroundColor = animStepColor'// Since we've now moved our color animation to a place where it' can be animated without changing the dimensions of the control' we need to tell the control to update when we set a new color value.Invalidate(False)else'// Get our animation start and end values.animStartDouble = animOp.Value("s").DoubleValueanimEndDouble = animOp.Value("e").DoubleValue'// Here we pass our start value, end value, and the percentage' of time passed to our lerp function parameters to' calculate what the current width should be at this point' in the total animation time. Note that, in our previous' version, we used a step value and modified our current width' but in this version our step value is the entire calculated' current width.animStepDouble = Lerp(animStartDouble, animEndDouble, timePercent)'// If we've reached our ending width or our alotted time has' passed then we bail and set the values we expect at the' end of the animation.select case animOpTypecase "width"'// Check to see if this animation operation is complete.' If so, we remove the operation from the queue and' move on.if animStepDouble = animEndDouble or timePercent >= 1 thenme.Width = animEndDouble ' Set our width to the end result.isExpandedWidth = not isExpandedWidth ' Toggle the state boolean.animQueue.Remove(intCycle)Continueend if'// Apply our new width value.me.Width = animStepDoublecase "height"'// Check to see if this animation operation is complete.' If so, we remove the operation from the queue and' move on.if animStepDouble = animEndDouble or timePercent >= 1 thenme.Height = animEndDoubleisExpandedHeight = not isExpandedHeightanimQueue.Remove(animQueue.IndexOf(animOp))Continueend if'// Apply our new height value.me.Height = animStepDoubleend selectend ifnext '// At this stage, we want to see if there are any animation operations ' that have yet to complete. If everything is done, then we disable ' our timer. if animQueue.Ubound < 0 then sender.Mode = 0 end if End Sub
You can see from the code that we’ve moved all of our variable declarations to the top of the method. We do this so that we’re not slowing things down inside the loop by disposing of and redeclaring variables that may be used multiple times. In Part 4 we’ll be adding Pragmas all over the place to make sure our code is even more speedy.
Inside the loop we fill our animOp property with the current animation operation and verify that it isn’t Nil. If animOp is Nil, then we need to go ahead and remove it from the queue.
Next we populate our animOpType, animStartTime, and animLength variables with their corresponding values, and calculate our current timePercent for our lerp functions.
The next block is where all of the magic happens. You can see that we’ve just used the same basic methodology from Part 2, but extended it to support animating color and height in addition to width.
One important thing to note is that we’re calling Invalidate(False) at the end of our conditional if the current operation is a color operation. Without this, our color property’s value would be animated, but the UI would not update to reflect that if this were the only operation currently underway as changes to both Width and Height automatically invalidate the control.
We also do a bit of work on our queue when an animation is complete by removing the current operation when it is complete, and instead of checking the animQueue property for Nil at the end of the method as we did in Part 2, we now check if there are any remaining operations and halt the timer if the queue is empty.
Final Thoughts
While this method may not be best for every situation or every coding style, I’ve found it to be versatile and dependable. This minimal animation controller is surprisingly robust.
As I mentioned earlier, this animation controller does not make use of keyframes for chaining animations. This could be implemented fairly easily, and while I have done it for a number of projects in the past, I won’t be covering that in this series as you should have some idea of how to incorporate that if you so desire.
In the next part I plan to cover easing to some degree which, like lerp, controls the speed and change in our animation and can add a massive amount of appeal to your user interface.
You can download the example project for Part 3 here.
Anthony G. Cyphers is the Lead Developer and Sole Proprietor of GraffitiSuite Solutions, and has been providing custom Xojo components and contract development since 2003. He runs the Xojo User’s Discord server, and is an administrator in the Xojo User’s Facebook user group.
