Animation – Xojo Programming Blog

Xojo + XAML + Goto = 🔥

William Yu — Thu, 22 Jan 2026 20:50:59 +0000

For decades, Goto has been treated as a programming faux pas—something to avoid at all costs. Like most rules though, there are exceptions. The Goto I’m talking about here is one of them… and it can quite literally light your app on fire—programmatically speaking.

One of the hidden gems in Xojo 2025r3 is support for XAML transitions, which makes it possible to add lightweight animations to your UI without writing any custom animation code in Xojo. Instead, you define visual states in XAML and let the XAML engine handle the animation for you.

At a high level, the workflow looks like this:

Define one or more VisualStates in XAML.
Attach transitions to those states (for example, moving or fading an element).
From Xojo code, switch between states using Invoke("GotoState", ...).

Pro Tip
DesktopXAMLContainer subscribes to Operator_Lookup, so you don’t have to call Invoke directly. Instead of writing XAMLContainer1.Invoke("GotoState", "WhichState"), you can simply call XAMLContainer1.GotoState("WhichState").

Visual States in XAML

A VisualState represents a named configuration of UI properties. When you transition from one state to another, XAML can automatically animate the change.

Below is a simple example that animates a fire emoji moving upward, similar to a candle flame flickering or burning upward.

Example XAML

This example uses a TextBlock to display the fire emoji and animates its vertical position with a TranslateTransform. Note that visual states must be defined on a control, so we attach them to a UserControl, allowing it to participate in GotoState transitions.


  
    
      

        
          
                          Storyboard.TargetName="FlameTransform"
              Storyboard.TargetProperty="Y"
              To="40"
              Duration="0:0:1" />
          
        

        
          
                          Storyboard.TargetName="FlameTransform"
              Storyboard.TargetProperty="Y"
              To="-100"
              Duration="0:0:1" />
          
        

      
    

          Text=""
      FontSize="32"
      HorizontalAlignment="Center"
      VerticalAlignment="Bottom">

In this XAML:

The VisualStateGroup named FlameStates contains two states:
- Bottom – moves the emoji downward.
- Top – moves the emoji upward.
The DoubleAnimation targets the Y property of a TranslateTransform.
The transition duration is handled entirely by XAML.

Triggering the Transition from Xojo

Once the visual states are defined, switching between them from Xojo is straightforward. Assuming this XAML is hosted in a XAMLContainer named XAMLContainer1, you can trigger the animation like this:

XAMLContainer1.GotoState("Top")

And to move it back down:

XAMLContainer1.GotoState("Bottom")

Why This Is Powerful

What makes this feature especially useful is that:

The animation logic stays in XAML, where it naturally belongs.
Xojo code remains clean and declarative—just tell the UI which state to go to.
More complex effects (opacity, scaling, rotation, easing functions) can be added without changing any Xojo code.

Here’s a more interesting variation, where the flames drift upward rather than moving in a straight line:

To light up the flames we’ll simply invoke the “On” state:

XAMLContainer1.GotoState("On")

For subtle UI polish—like animated indicators, highlights, or playful effects such as this candle flame—XAML transitions provide a surprisingly powerful new tool in Xojo.

William Yu grew up in Canada learning to program BASIC on a Vic-20. He is Xojo’s resident Windows and Linux engineer, among his many other skills. Some may say he has joined the dark side here in the USA, but he will always be a Canadian at heart.

Beyond Static UI: Create Dynamic Loading Animations with Xojo Graphics

Gabriel Ludosanu — Tue, 05 Nov 2024 15:10:24 +0000

Ever wondered how to create those sleek, professional-looking loading animations you see in modern apps?

In this blog post, we’re going to unlock the power of Xojo’s DesktopCanvas and its Graphics capabilities to recreate one of the popular SpinKit loading animations originally created by Tobias Ahlin. We’ll be implementing the “Three Bounce” animation, transforming this beloved CSS animation into native Xojo code!

Not only will you learn how to create this specific animation, but you’ll also gain valuable insights into animation principles in Xojo that you can use to create your own custom animations. By the end of this tutorial, you’ll understand how to:

Harness the power of DesktopCanvas for custom graphics
Create smooth animations using Timers
Implement phase-based animations
Use Graphics methods to draw dynamic shapes
Manage animation lifecycles properly

Why This Matters

Loading animations are more than just eye candy – they’re essential UI elements that keep users engaged while your app processes data. Instead of using static images or third-party libraries, creating your own animations gives you complete control over the look and feel of your application while keeping your dependencies minimal.

What We’re Building

We’ll create a smooth, professional-looking three-dot loading animation where dots gracefully scale up and down in sequence. The result is a lightweight, customizable loading indicator that you can drop into any Xojo project. Here’s what makes this implementation special:

Pure Xojo code – no external dependencies
Smooth, fluid animation
Easily customizable colors and timing
Efficient resource usage
Clean, object-oriented design

Ok, let’s start building our awesome animation class.

Step 1: Setting Up the Base Class

First, create a new class (Insert > Class) that inherits from DesktopCanvas:

Protected Class SpinKitClass Inherits DesktopCanvas

Step 2: Defining Core Properties

Add these essential properties to control the animation:

Private animationPhases() As Double      // Stores phase offsets for each dot
Private animationSpeed As Integer = 60   // Animation refresh rate in milliseconds
Private animationTimer As Timer         // Timer to drive the animation
Private currentPhase As Double = 0.0    // Current animation phase
Private dotSize As Integer = 20         // Size of each dot
Private dotSpacing As Integer = 20      // Space between dots

Step 3: Setting Up Constants

Define the constants that control the animation behavior:

Private Const kDefaultColor As Color = &c333333    // Dot color
Private Const kPhaseIncrement As Double = 0.05    // Animation speed

Step 4: Implementing Animation Control Methods

Add methods to start and stop the animation:

Public Sub StartAnimation()
  /// Initializes and starts the animation
  /// Sets up initial phase offsets for the dots
  /// Creates and configures the animation timer
  
  If animationTimer = Nil Then
    animationPhases = Array(0.0, 0.16, 0.32)
    
    animationTimer = New Timer
    AddHandler animationTimer.Action, AddressOf UpdateAnimation
    animationTimer.Period = animationSpeed
    animationTimer.RunMode = Timer.RunModes.Multiple
  End If
End Sub

Public Sub StopAnimation()
  /// Stops the running animation
  /// Removes the timer handler and cleans up
  /// Refreshes the canvas to clear the animation
  
  If animationTimer <> Nil Then
    RemoveHandler animationTimer.Action, AddressOf UpdateAnimation
    animationTimer = Nil
    Refresh
  End If
End Sub

Step 5: Creating the Animation Update Logic

Implement the timer callback that drives the animation:

Private Sub updateAnimation(sender As Timer)
  /// Timer callback that updates the animation state
  /// Increments the phase and triggers a redraw
  /// @param sender The Timer that triggered this callback
  
  #Pragma Unused sender
  
  // Increment the current phase (spin08)
  currentPhase = currentPhase + kPhaseIncrement
  // Reset currentPhase if it exceeds 1.0
  If currentPhase > 1.0 Then currentPhase = 0
  
  // Invalidate the canvas to trigger a repaint
  Refresh()
End Sub

Step 6: Implementing the Drawing Logic

Add the core animation rendering code:

Private Sub animation08(g As Graphics)
  /// Renders a single frame of the three-dot loading animation
  /// Draws 3 dots that scale up and down in sequence
  /// @param g The graphics context to draw into
  
  Var centerX As Integer = Me.Width / 2
  Var centerY As Integer = Me.Height / 2
  
  For i As Integer = 0 To 2
    Var phase As Double = currentPhase + animationPhases(i)
    
    // Ensure phase is within 0 to 1
    If phase > 1.0 Then phase = phase - 1.0
    
    Var scale As Double
    If phase < 0.4 Then
      scale = phase / 0.4
    Else
      scale = (1.0 - phase) / 0.6
    End If
    
    Var size As Integer = dotSize * scale
    Var x As Integer = centerX + (i - 1) * dotSpacing - size / 2
    Var y As Integer = centerY - size / 2
    
    g.DrawingColor = kDefaultColor
    g.FillOval(x, y, size, size)
  Next
End Sub

Step 7: Handling the Paint Event

Implement the Paint event to trigger the animation rendering:

Sub Paint(g As Graphics, areas() As Rect) Handles Paint
  /// Paint event handler that renders the animation
  /// Called automatically when the canvas needs to be redrawn
  /// If animation is running, calls animation08, otherwise clears the canvas
  
  If animationTimer <> Nil Then
    animation08(g)
  Else
    g.ClearRectangle(0, 0, Width, Height)
  End If
End Sub

How It Works

The animation uses a phase-based system where each dot is offset in its animation cycle.
The dots scale up and down based on their current phase.
A timer drives the animation by incrementing the phase and triggering redraws.
The dots are positioned horizontally with equal spacing around the center.
Each dot’s size is calculated based on its current phase in the animation.

Using the Animation

To use this animation in your project, all you have to do is simply drag and drop the class on a DesktopWindow and then start or stop the animation when needed.

// Start the animation
SpinKit1.StartAnimation()

// Stop the animation when done
SpinKit1.StopAnimation()

Customization

You can customize the animation by adjusting:

dotSize for larger or smaller dots
dotSpacing to change the spread of the dots
animationSpeed to make it faster or slower
kDefaultColor to change the dot color
kPhaseIncrement to adjust the animation speed

Taking It Further

The “Three Bounce” animation we’ve created is just one of many amazing animations in the SpinKit collection. Now that you understand the fundamentals, why not try recreating other SpinKit animations? Here are some exciting challenges to tackle:

Modify the current animation to use different shapes (squares, rectangles).
Experiment with different timing functions for varied animation effects.
Try implementing the “Rotating Plane” or “Chasing Dots” animations from SpinKit.
Create your own unique variations by combining what you’ve learned.
Optimize the class further.

Share Your Creations!

Have you created an awesome variation or implemented another SpinKit animation in Xojo? Share it with the community! The Xojo Forums and social media are great places to showcase your work and inspire others.

Resources for Further Exploration

Original SpinKit animations by Tobias Ahlin: https://tobiasahlin.com/spinkit/
Xojo Graphics documentation: https://documentation.xojo.com/api/graphics/graphics.html
Xojo DesktopCanvas documentation: https://documentation.xojo.com/api/user_interface/desktop/desktopcanvas.html

Remember: Every great application deserves great animations and now you have the tools to create them! Keep experimenting, keep creating, and most importantly, keep animating!

Gabriel is a digital marketing enthusiast who loves coding with Xojo to create cool software tools for any platform. He is always eager to learn and share new ideas!

Building a Vertical Navigation for your Web Application

Ricardo Cruz — Wed, 29 Mar 2023 12:41:00 +0000

Composing new controls using primitives is something you definitely want to explore. Let’s build a reusable vertical navigation, with animations, for your Xojo Web projects.

Brief introduction to the Atomic Design Methodology

If you haven’t heard about Atomic Design before, I really recommend that you dig a bit into this topic. With this way of methodology in mind, we will start building the smallest controls we can. Then, we will compose more complex controls reusing the smallest.

Keep in mind you don’t really need to blindly follow the Atoms, Molecules and Organisms proposed categories, and don’t overthink where to categorize them. As long as you can compose controls with other controls, that’s perfect. Adapt it to your own personal way of building software.

The idea resonates perfectly with Xojo and, while we will create a few web controls in this example, you can apply it to other targets like Desktop or Mobile.

Here is a video from Brad Frost, the person behind Atomic Design Methodology.

Containers to the rescue!

In this case, we won’t need to use any Web SDK control, CSS or JavaScript. We will be using just plain Xojo Web Containers for creating our Atoms and Molecules.

This is how Twitter’s navigation sidebar looks like:

Twitter Vertical Navigation

We will create something similar. Using Atomic Design, let’s break it down it into a few new reusable controls:

Individual Controls

Each Atom, Molecule and Organism will be a Container. In the above image, we have identified each of them.

There is a “Navigation Link Icon”, an Atom, which will show one of the available Bootstrap Icons. As you notice in the Twitter example, if the link is active, the icon will be filled.
For the label Atom, we can just use the WebLabel built-in control. There is no need to wrap it in a Container, in this case.
The navigation link will be a Molecule, combining the icon and the label.
The Active Link Indicator will move to the active link, using an animation.
Finally, the Vertical Navigation Control will be the Organism, combining everything into one.

Navigation Link Icon

This Control is basically a Container, with an ImageViewer inside. Technically, this could be just an ImageViewer subclass, but using a WebContainer we can also specify its default width and height.

It will have two computed properties:

Active As Boolean
IconName As String

There will also be a private ShowIcon method. Whenever you change either the Active property or IconName, the computed property will call ShowIcon.

The magic is inside ShowIcon:

Var iconColor As Color = If(mActive, Color.Black, Color.LightGray)
Var icon As String = If(mActive, mIconName + "-fill", mIconName)
IconImageViewer.Picture = WebPicture.BootstrapIcon(icon, iconColor)

NavigationLinkIcon in the IDE

The icon color will be either LightGray or Black, depending if it’s active or not. There are also a lot of Bootstrap Icons with the “-fill” suffix so we’ll use them. This will force us to only use icons which have that suffix, but we will have to live with that.

The final trick is to use the Inspector Behavior and expose our Active and IconName computed properties. Right click on NavigationLinkIcon, then click on Inspector Behavior:

How to open the Inspector Behavior

From there you can enable the checkboxes and define their default value:

Enabling properties in the Inspector Behavior

Now that we have the Control ready, let’s see how it works on its own:

NavigationLinkIcon demo

Neat! You can reuse this Atom everywhere, including other projects.

Navigation Link Control

Combining our fresh NavigationLinkIcon, a built-in WebLabel and exposing an API, we’ll create our NavigationLink Molecule.

Create a new Container and place the items inside. Then add some computed properties:

Active
Caption
IconName

Whenever the property changes, just update the underlying control.

One trick, to make the control clickable, is to add a WebCanvas on top of the other controls. Implement its Pressed event and forward it as a new “Pressed” Event Definition.

If you want to show a pointer cursor when the user moves the mouse over your control, add this line of code into the container’s Opening event:

Me.Style.Cursor = WebStyle.Cursors.Pointer

This is how it looks like in the IDE:

NavigationLink in the IDE

Let’s quickly test it:

NavigationLink demo

We are getting there.

Active Link Indicator

We have most of the Atoms and Molecules created already. The Navigation Link Indicator is so simple and so tied to the Sidebar, that I don’t think creating an individual Atom for it is worth the effort.

Using a WebRectangle, with a line of two of code in its Opening event, will be enough. This is completely up to you!

Vertical Navigation Control

Now it’s time to glue the Atoms and Molecules together to make our first Organism. Create a new Container called VerticalNavigation.

Drop a WebRectangle on it. Set its Left and Top to 0, and implement its Opening event with these lines of code:

Me.Style.BorderThickness = 0
Me.Style.AddTransition("top", 0.2)

That will remove the border that comes by default with this control. It will also tell the browser to animate the rectangle whenever we change the Top position.

The rectangle background color will be a light gray, but this is again up to you.

For the API we want to expose, add these Methods:

AddLink(caption As String, icon As String, active As Boolean = False)
HandleLinkPressed(sender As NavigationLink)
SetActiveLink(index As Integer)

AddLink and SetActiveLink can be left Public, HandleLinkPressed will be a Private Method.

AddLink code:

// We will create a new NavigationLink instance
// and set the properties we're receiving.
Var link As New NavigationLink
link.Caption = caption
link.IconName = icon

// For its pressed event, we will handle it
// internally in the HandleLinkPressed method.
AddHandler link.Pressed, WeakAddressOf HandleLinkPressed

// We will place it programatically in  the container.
Const padding = 10
Var linkTop As Integer = mLinks.Count * (link.Height + padding)
link.EmbedWithin(Self, padding, linkTop, Self.Width - padding, link.Height)

// A reference for this NavigationLink will be
// needed later, so we will store it internally.
mLinks.Add(link)

// Finally, if the item is active, we will
// handle it just like if it's been pressed
// by the user.
If active Then
  SetActiveLink(mLinks.LastIndex)
End If

HandleLinkPressed code:

SetActiveLink(mLinks.IndexOf(sender))
RaiseEvent Pressed(sender)

And, finally, SetActiveLink:

// Here we will loop through the NavigationLink
// references we have and enable or disable the
// Active property, depending on the index
// comparison.
For i As Integer = 0 To mLinks.LastIndex
  mLinks(i).Active = i = index
Next

// Move the visual active indicator to the
// NavigationLink position.
ActiveLinkIndicator.Top = mLinks(index).Top

VerticalNavigation in the IDE

Final Result

Everything is ready, drop your VerticalNavigation somewhere in your WebPage and add a few links inside its Opening event:

// Setting the third parameter to "True" will set that link as Active.
Me.AddLink("Home", "house")
Me.AddLink("Explore", "binoculars", True)
Me.AddLink("Notifications", "bell")

You should see something similar to this:

Final result!

Congratulations! You’ve built a vertical navigation, with nice transitions, using some Atomic Design principles.

Code repository: https://github.com/piradoiv/vertical-navigation-example
Download the project: vertical-navigation-example

Ricardo has always been curious about how things work. Growing up surrounded by computers he became interested in web technologies in the dial-up connections era. Xojo has been his secret weapon and language of preference since 2018. When he’s not online, chances are he will be scuba diving … or crocheting amigurumis. Find Ricardo on Twitter @piradoiv.

Cross-Platform Mobile Bounce Animation

Paul Lefebvre — Wed, 17 Mar 2021 18:04:06 +0000

Here’s a fun little project you can try to get a feel for simple animation in your iOS apps. As you can see, this project moves a small “ball” around the screen and it bounces off the edges.

Create a new iOS project and on Screen1 add a couple Buttons and a Canvas, the buttons at the top and the Canvas using up the rest of the space. Also add a Timer.

Add some properties to track the ball’s position and direction:

Public Property XDirection as Integer = 10
Public Property XPosition as Integer = 10
Public Property YDirection as Integer = 10
Public Property YPosition as Integer = 10

In the Opening event for Screen1, initialize the Timer (which I’ve named MoveTimer):

MoveTimer.Period = 50
MoveTimer.RunMode = Timer.RunModes.Multiple
MoveTimer.Enabled = False

Speaking of the Timer, in its Run event put this code to move the ball:

XPosition = XPosition + XDirection
YPosition = YPosition + YDirection
BounceCanvas.Refresh

Add the Paint and PointerDown events to the Canvas. In the Paint event draw the ball with this code:

Var size As Integer = 25
g.DrawingColor = Color.RGB(255, 0, 0)
g.DrawRectangle(0, 0, g.Width, g.Height)
g.FillOval(XPosition, YPosition, size, size)
If (XPosition + size) > g.Width Then
  XDirection = -XDirection
End If
If ( YPosition + size) > g.Height Then
  YDirection = -YDirection
End If
If XPosition < 0 Then
  XDirection = -XDirection
End If
If YPosition < 0 Then
  YDirection = -YDirection
End If

And in the PointerDown event, reset the ball’s position to the touch:

XPosition = position.X
YPosition = position.Y
XDirection = -XDirection
YDirection = -YDirection

Lastly you can add the Pressed event to the Start button and tell it to start the Timer:

MoveTimer.Enabled = True

Similarly add the Pressed event to the Stop button and tell it to stop the Timer:

MoveTimer.Enabled = False

That’s it. Run the project, click start to watch the ball bounce. Tap on the screen to change its position and direction. You could probably use this as the start of a Pong game!

Oh, and I forgot to mention that the code above was actually copied from the Android project where I first created this. The exact code copied over to iOS and worked as is with no changes. For a little teaser, here’s Bounce running on Android:

Programming your own Solar System with Xojo + MBS SceneKit

Stefanie Juchmes — Mon, 17 Feb 2020 10:00:00 +0000

In this post I will show you how to create you own solar system in Xojo with the help of the Monkeybread Software plugin component SceneKit. SceneKit is an Apple framework that supplies functions for graphic and animation designs.

Please run a current Xojo version with MBS Xojo Mac64bit Plugin installed. Due to our dependencies list, please add Main, MacCloud, MacBase, MacCocoa, MacControls, MacCG and MacCF plugins too. Start with a new project. To the window we add a SCNControlMBS control from the library and rename it MyControl. Drag it across the entire window size and lock all edges. It is very useful because we want fullscreen mode later.

Then we need two properties MyScene and MyView. MyScene has the type SCNSceneMBS and MyView has the type SCNViewMBS. Afterwards, add the open event of the SceneKit control.

We start with the setting of MyView and MyScene like this:

MyView = Me.View 
MyScene = New SCNSceneMBS
MyView.scene = MyScene

Then we enable the default light and the camera control, because we want to see a 3D effect and want to move the camera using the mouse. We set black as the background color.

myView.autoenablesDefaultLighting = True  
MyView.allowsCameraControl = True   
myView.backgroundColor = NSColorMBS.blackColor

Next we add our first node to the scene. The center of the scene is the Sun. In basic structure the Sun is a lit up sphere. So we add a sphere geometry with a given size. In this project we can’t work with the original conditions, because Mercury would be so small that it is impossible to see. Plus, we would have same problem for the distance between the Sun and the planets. Because that, our Sun has a radius of 13. Then we add a node and give it geometric information about the Sun. The position of the node is the origin with the coordinates 0,0,0. Finally, we add the node to our scene.

Dim SunGeometry As New SCNSphereMBS(13)  
Dim Sun As New SCNNodeMBS(SunGeometry)  
Sun.Position = New SCNVector3MBS(0, 0, 0)   
MyScene.rootNode.addChildNode(Sun)

Then we start our program.

We see a white sphere on the screen. The Sun looks a bit edged because of the segment count. Our Sun sphere is very big and needs more segments then the default segment count. Set the segment count property ahead of adding the node to the scene command.

	SunGeometry.segmentCount=100

Then we set each planet in a similar way. Because the planets look different, we want to change their colors as appropriate or even put a picture as a graphic over each sphere. For the color of an object we have the firstMaterial.diffuse.contents Property. This is how you would set a gray color for Mercury.

 MercuryGeometry.firstMaterial.diffuse.contents = NSColorMBS.grayColor

If we want to map a picture on a geometry, for example for Earth, we add this picture to our project and set it to the geometry. It’s a bit like covering it with a blanket with a high percentage of elongation. We can imagine that by covering a sphere, we stretch the blanket on the equator more than on the polar caps. Because that, if you look on a map, the longitudes and latitudes are not parallel, but rather bent. In reality the longitude and latitude are parallel. You can see that on a globe. Fortunately for us a world map is already a perfect UV map for a sphere. Thanks to the website www.ginkgomaps.com which supplies world maps to everyone. I used one of these maps in my example. You can customize the map with a graphic program. Then add it to the project and set it in the property.

Dim EarthGeometry As New SCNSphereMBS(1.47)  
EarthGeometry.segmentCount=100  
Dim Earth As New SCNNodeMBS(EarthGeometry)  
EarthGeometry.firstMaterial.diffuse.contents = EarthPic  
Earth.Position = New SCNVector3MBS(25, 0, 0)   
MyScene.rootNode.addChildNode(Earth)

All other textures I draw myself in a graphic program.

For the position of the Planets, we must pay attention to the fact that the origin of the single planets are in the center of the sphere and we set in the constructor of the geometry as the radius and not the diameter. The distance between two planets are: radius of planet 1+radius of planet two+ space between them.

Following this same pattern we add the other planets. Saturn has a planetary ring. The ring is a tube with an inner radius that is bigger than the planet and a small hight. I use the same structure on the ring as on the planet. The tube is a bit rotated. We rotate the ring a bit by x and y. The specification of a rotation looks like this:

saturnRing.orientation = New SCNVector4MBS(-0.4, -0.5, 0, 1)

Let’s Move the Solar System

Now we want to move the Scene. We assume that the planets’ orbits are all parallel to the xz plane and that they are exactly circular. To roate around a certain point, we create a geometry for each rotation. It lies in the point and is a parent node of the geometry. If a parent node moves, a child node moves too. The inverse does not apply. In that way, if we rotate the helping node in the origin, the child node moves around the origin too. We cannot use the Sun as the parent node for all planets because the planets are supposed to move at different speeds.

The creation of the geometry looks similar for each planet:

Dim UranusRotationGeometry As New SCNSphereMBS(1)  
Dim UranusRotation As New SCNNodeMBS(UranusRotationGeometry) 
UranusRotation.Position = New SCNVector3MBS(0, 0, 0)  
MyScene.rootNode.addChildNode(UranusRotation)

UranusRotation.addChildNode(Uranus)

These geometries are covered by the Sun.

Then we add the movements. We defined a rotation of the helping node and set the information about the rotation. We want to rotate around the y axis in each cycle about 360°. The information is given in the unit rad. Because of this we must convert 360° to 6.283 rad. The last parameter is about the speed of the operation. In this section we can set the proportion of the speed of the planets. The speed of Earth is the basic value. Everything is based on this value. The assumption is: an Earth year lasts 365 days. For each planet we use the number of Earth days a planet takes to rotate once around the Sun. We divide this value by the days of an Earth year. For Neptune we get a value that is approximate to 164.79 rad. That we can multiply with a variable. The variable can be set by the customer to regulate the speed of the solar system. We want to repeat this movement again and again. In this way we set it. In the last step we set this rotation to the scene.

Dim moveNeptune As SCNActionMBS = SCNActionMBS.rotateBy(0, 6.283, 0, 164.79 * speed)
Dim Neptunerepeat As SCNActionMBS = SCNActionMBS.repeatActionForever(moveNeptune)
NeptuneRotation.runAction(Neptunerepeat)

Finally, we want to talk about lighting. The Sun is the light source. It is a light that comes from a point and shines in all directions. That type of light source is called an omni light. We define a light as a property from a node. Since our Sun is a node in the scene, we add the light property directly. All nodes that spray light don’t get any light and they are normally black. With the emission property we can make the sphere look like it is glowing. We choose yellow as color.

Dim SunGeometry As New SCNSphereMBS(13) 
Dim Sun As New SCNNodeMBS(SunGeometry) 
sun.Light = New SCNLightMBS 
sun.Light.Type = SCNLightMBS.SCNLightTypeOmni 
sun.Light.Intensity = 2000
sun.light.Color = NSColorMBS.whiteColor sun.Light.Intensity = 2000 SunGeometry.firstMaterial.emission.contents = NSColorMBS.yellowColor SunGeometry.segmentCount = 100 
Sun.Position = New SCNVector3MBS(0, 0, 0)  
MyScene.rootNode.addChildNode(Sun)

The scene seems very dark if the Sun is our only light source, so add weak ambient light that lights up all elements in the same way. The unit of the light intensity is lumen. Now you can run the project and admire your own programmed solar system. Have a lot of fun with that. Link to project.

If you have questions about SceneKit don’t hesitate to contact me. And please join my session about SceneKit at the XOJO.CONNECT conference in Nashville.

Download the project.

Stefanie Juchmes studies computer science at the University of Bonn. She came in touch with Xojo due to the work of her brother-in-law and got a junior developer position in early 2019 at Monkeybread Software. You may have also read her articles in Xojo Developer Magazine.

Guest Post: Animating Xojo, Part 4

Anthony Cyphers — Wed, 21 Aug 2019 10:00:20 +0000

In Part 1 we covered the history of animating UI effects in Xojo. In Part 2 we dug in to linear interpolation. In Part 3 saw the addition of support for concurrent animations and color changes. In Part 4 we’ll cover easing, which can make the most drab User Interface interactions beautiful.

Easing

What is Easing?

To quote Paul Lewis:

Nothing in nature moves linearly from one point to another. In reality, things tend to accelerate or decelerate as they move. Our brains are wired to expect this kind of motion, so when animating, you should use this to your advantage. Natural motion makes your users feel more comfortable with your apps, which in turn leads to a better overall experience.
https://developers.google.com/web/fundamentals/design-and-ux/animations/the-basics-of-easing

Based on that, we can define easing as a more natural-appearing change in value between a start and end point which is designed to make a user feel more comfortable with changes in the user interface.

Types of Easing Functions

Easing functions can be broken down in to three basic types:

In — An animation that starts slowly and increases in speed over time
Out — An animation that starts quickly and decreases in speed over time
InOut — A combination of InOut that begins and ends quickly with a slow transition in the middle.

What Does Easing Look Like?

There are a number of currently standard UI easing functions (as seen in CSS, various JavaScript frameworks, and even OS-provided implementations), but one of the more interesting sets is called Elastic. Elastic easing functions simulate the motion you might observe if you stretched out a piece of elastic then released it. You get a dramatic change as the elastic fibers quickly contract, then a slower series of changes as the momentum dissipates. To visualize that in a diagram:

This can be used to provide some really enthralling UI transitions that’ll make both you and your users much happier as it just feels more natural than making Element A of your UI disappear and Element B appear, or using a linear animation to swap the two elements.

What Does an Easing Function Look Like

Easing functions can be incredibly simple, as you saw in our lerp method in Part 2, or as complex as you can imagine. Our example of Elastic easing, while not the most complex, is pretty interesting mathematically (if you’re terrible at math like I am).

Private Function easeInElastic(startValue as Double, endValue as Double, alphaValue as Double) as Double
   Return ((endValue - startValue) * (0.04 * alphaValue / (alphaValue - 1) * Sin( 25 * (alphaValue - 1) ))) + startValue
 End Function

Basically what this method is doing, and my grasp of the math is admittedly pretty thin, is it’s taking the start and end value and creating a diminishing sine wave to simulate the change over time. I normally would say that this should be broken down in to multiple lines to make it easier to read, possibly by using no fewer than three variables, but we really want it to be quick.

If we did break it down, it would look more like this:

Private Function easeInElastic(startValue as Double, endValue as Double, alphaValue as Double) as Double
   dim changeValue as Double = endValue - startValue
   dim differenceValue as Double = (0.04 * alphaValue / (alphaValue - 1) * Sin( 25 * (alphaValue - 1) ))
   Return (changeValue * differenceValue) + startValue
 End Function

Which may be easier to read for some of us, but those variable declarations have a cost.

Many of the easing functions you’ll see in this part of the series are adapted for Xojo (with some heavy modification in most places) from Robert Penner’s Easing Functions (BSD License). There’s a note on the Animated Canvas project item if you wish to explore the sources.

What Types of Easing Functions Should I Use?

UI animations are, typically, something you want to happen fairly quickly. Given that, you likely won’t use InOut easing functions very often as they can feel slower to your end user.

In functions can be off putting to users as the natural expectation of seeing the most movement at the end of an animation is antithetical to In functions and may feel slow or confusing for some users.

Based on those theories, you’ll typically employ Out functions in your UI animations, as they’re both quick and easier for our brains to understand in a UI setting. That said, there will be times when other types of easing functions are more suited to an individual task and you must use your best judgement and listen to your QA/users if they complain about it. Animation type and length are a delicate balance.

Easing Lengths

As I alluded to earlier, the timing of your chosen easing function is incredibly important. The following table should be a good starting point for appropriate animation lengths for different types of operations.

Color (In)	100-250ms
Color (Out)	100-250ms
Color (InOut)	500-1000ms
Dimensions/Position (In)	800-1200ms
Dimensions/Position (Out)	800-1200ms
Dimensions/Position(InOut)	1500-2500ms

These are the values I typically start with, and alter them based on the responsiveness of the UI and the desired effect. Your mileage may vary.

Code Changes

While I won’t cover the addition of each of the example easing functions that I’ve provided in the example project, I will cover the functional changes to our existing codebase and the addition of the Elastic easing functions.

AnimationEasing Property

Our first step is to create a new property on our AnimatedCanvas class called AnimationEasing. In our demo window we’ll set this value based on selection in a PopupMenu to make it easy to switch between different easing functions and view their output. It’s going to public and computed so we can show it in the Inspector.

Private Property mAnimationEasing as Easings

 Public Property AnimationEasing as Easings
 Get
   Return mAnimationEasing
 End Get

 Set
   mAnimationEasing = value
 End Set

 End Property

Easings Enumeration

Next we to create an enum for our various easing functions. It’s pretty straight-forward, and we’ll use it to tell our animation controller code what to do in the animation operations we define in our Dictionary objects.

Public Enum Easings
 Linear
 InQuad
 OutQuad
 InOutQuad
 InCubic
 OutCubic
 InOutCubic
 InElastic
 OutElastic
 InOutElastic
 End Enum

Dictionary Definition

We are, again, modifying our Dictionary object definition. This time we’re passing along the desired easing effect. Our new definition looks like this:

new Dictionary("op" : , "m" : , "t" : , "s" : , "e" : )

You can see that all we’ve really done from Part 3 is add a Key/Value pair for the easing. I assigned this to the “m” key to represent “method of change”, but you could use anything you like here.

MouseEnter and MouseExit

We actually don’t need any changes here for our color animation, as this will continue to use the lerpColor function we previously defined. Color change animations should typically be quick and applying anything but a linear easing to them can both look and feel bad if done improperly, so I won’t cover it here. When in doubt, for color animation, stick with linear and keep it around 100-250ms.

MouseUp

MouseUp, likewise isn’t changing much. We’re basically just adding the easing Key/Value to our existing Dictionary objects like so:

animQueue_Add(new Dictionary("op" : "width", "l" : manimTime, "m" : mAnimationEasing, "t" : Microseconds, "s" : Width, "e" : 
If(isExpandedWidth, 10, expandedWidth)))

doEasing Function

We need a function to take our Easings enumeration value and perform the specified easing function. In this example I’m using a Select Case block, but I’ve also implemented a nice jump table using delegates in other projects.

Private Function doEasing(easing as Easings, startValue as Double, endValue as Double, alphaValue as Double) as Double
   select case easing
   case easings.Linear
     Return lerp( startValue, endValue, alphaValue )
   case easings.InQuad
     Return easeInQuad( startValue, endValue, alphaValue )
   case easings.OutQuad
     Return easeOutQuad( startValue, endValue, alphaValue )
   case easings.InOutQuad
     Return easeInOutQuad( startValue, endValue, alphaValue )
   case easings.InCubic
     Return easeInCubic( startValue, endValue, alphaValue )
   case easings.OutCubic
     Return easeInOutCubic( startValue, endValue, alphaValue )
   case easings.InOutCubic
     Return easeInOutCubic( startValue, endValue, alphaValue )
   case easings.InElastic
     Return easeInElastic( startValue, endValue, alphaValue )
   case easings.OutElastic
     Return easeOutElastic( startValue, endValue, alphaValue )
   case easings.InOutElastic
     Return easeInOutElastic( startValue, endValue, alphaValue )
   end select
 End Function

As you can see, it takes the easing parameter representing the desired function, and the values we need to animate, passes all of that along to the requested easing function, and returns the value. A call to this method will replace our previous call to lerp in our Timer’s Action event handler.

Our Easing Functions

As I said earlier, I won’t cover all of the functions in the article, but I will include the Elastic functions here for your perusal. To see all of the easing functions included, be sure to download the example project at the end of the article.

Private Function easeInElastic(startValue as Double, endValue as Double, alphaValue as Double) as Double
   Return ((endValue - startValue) * (0.04 * alphaValue / (alphaValue - 1) * Sin( 25 * (alphaValue - 1) ))) + startValue
 End Function

 Private Function easeOutElastic(startValue as Double, endValue as Double, alphaValue as Double) as Double
   Return ((endValue - startValue) * ((0.04 - 0.04 / alphaValue) * Sin( 25 * alphaValue ) + 1)) + startValue
 End Function

 Private Function easeInOutElastic(startValue as Double, endValue as Double, alphaValue as Double) as Double
   dim opChange as Double = Abs(endValue - startValue)

 if alphaValue <= 0.5 then
     return easeInElastic(startValue, opChange /  2, alphaValue * 2)
   else
     return easeOutElastic(opChange / 2, endValue, Abs(1 - (alphaValue * 2)))
   end if
 End Function

We’ve already discussed purpose and expectation for In/Out, but take a look at easeInOutElastic. We accomplish this effect by splitting the run-time of the animation into two distinct parts and executing the appropriate easing function based on where we are in the animation. In happens at <= 50% of our total animation time, and Outhappens at > 50% of our animation time. This gives us a nice, seamless transition in our InOut animation as the value at 50% should be close — if not identical — in both easing functions.

animTimer_Action

Our changes in animTimer_Action are also pretty minimal. Since we’re not applying one of the more advanced easing functions to our previously discussed color animation, I’ll only cover the changes we’re making to the Width and Height operations.

First, we need to add a new variable declaration to the top of our method. This is where we’ll store the easing type.

Dim animOpEasing As Easings

Then, after our Else at line 87, where we get our values from the current animOp Dictionary, we will assign the current operation’s easing (or “m” key) value to our new variable.

animOpEasing = animOp.Value("m")

Now that we know which easing function we want to apply to the current operation, and we’ve already defined our doEasing function, all we need to do is swap out our line (line 100) that previously used the lerp function to assign the appropriate value to animStepDouble, to use our new doEasing function.

animStepDouble = doEasing(animOpEasing, animStartDouble, animEndDouble, timePercent)

Series Finale

I do hope that, throughout this series, you’ve learned a little something about how and when to implement animation in user interfaces, some decent practices for doing so in an encapsulated way, and maybe picked up a few other pointers.

I had a lot of fun writing this and interacting with readers who reached out with questions and suggestions, and I hope to do more guest posts on the Xojo blog in the future. I’d like to thank Team Xojo not only for their great product and support, but also for allowing me to stand at their podium for a short time and share with you all.

If you would like to see more easing functions, or how I’ve implemented a full animation controller and the delegate jump table, GraffitiAnimator will soon be coming to GraffitiSuite Desktop Edition, and can be acquired directly, via the Xojo Extras store, or for a limited time as part of the Omega Bundle.

Finally, you can download the example project for Part 4 here.

Thank you all for following along with me!

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.

Guest Post: Animating Xojo, Part 3

Anthony Cyphers — Thu, 15 Aug 2019 10:00:56 +0000

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" : , "sw" : , "ew" : )

We’re now defining our animOp Dictionaries as:

Dictionary("op" : , "l" : , "t" : , "s" : , "e" : , "o" : )

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)   
  Continue 
end 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").StringValue 
animStartTime = animOp.Value("t").DoubleValue 
animLength = 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").ColorValue   
   animEndColor = 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 then      
     currentBackgroundColor = animEndColor     
     animQueue.Remove(intCycle)     
     Continue   
    end 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").DoubleValue   
    animEndDouble = 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 animOpType   
    case "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 then       
        me.Width = animEndDouble ' Set our width to the end result.
        isExpandedWidth = not isExpandedWidth ' Toggle the state boolean.     
        animQueue.Remove(intCycle)       
        Continue     
       end if     

      '// Apply our new width value.     
      me.Width = animStepDouble   

 case "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 then       
    me.Height = animEndDouble       
    isExpandedHeight = not isExpandedHeight  
    animQueue.Remove(animQueue.IndexOf(animOp))       
    Continue     
  end if     

   '// Apply our new height value.     
   me.Height = animStepDouble   

   end select 
  end if
 next

 '// 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.

Guest Post: Animating Xojo, Part 2

Anthony Cyphers — Wed, 31 Jul 2019 10:00:16 +0000

Continuing with what we previously learned in Animating Xojo, Part 1, this version introduces the use of linear interpolation to calculate the current stage of the animation at each step, plus switching to a Dictionary object for variable storage to setup for future parts in this series.

Linear Interpolation

Last time we used a static animation step that was calculated in advance to modify the width of our element. That method is fine for many uses, but for more advanced things we want to get a bit more involved with linear interpolation.

The new method will shorten the steps taken if something locks up your application UI so the time you’ve chosen for your animation to take to complete is honored. Previously, if something suspended your application’s main thread, the animation would halt and wait during this period and 250ms could become 100ms before the lockup and 150ms after the lockup. Now, if your selected animation time is 250ms and something suspends UI updates, the animation will complete after the UI updates have resumed as if the UI had never become unresponsive, resulting in a true animation time that roughly matches the specified time (I’ve seen +/- approximately 0.03 seconds using this method with a timer set at the minimum period for the debugging OS).

What is Linear Interpolation

Linear interpolation (or lerp) in animation is used to calculate change based on the total amount of time a process should take, the amount of time passed since the start of the process, and the change in value from start to finish. By using these three values we can determine, at any given point within our animation time-frame, what our current value should be.

You can read more in-depth information about linear interpolation here.

What Does it Look Like?

In code, linear interpolation is a fairly simple algorithm. We provide the following:

Starting value (starting width, in our case)
Ending value (the width after animation)
The amount of time passed (expressed as a double value between 0 and 1, which is typically referred to as alpha)

Private Function lerp(startValue as Double, endValue as Double, alphaValue as Double) as Double
   '// The lerp function evaluates where we should be in the animation
   '   given a starting point, an ending point, and the amount of time
   '   elapsed. Lerp is shorthand for linear interpolation.
   return (startValue * (1 - alphaValue)) + (endValue * alphaValue)
 End Function

We can express that graphically with the two red points below representing our starting and ending values, the blue line representing the current position between those two values over time.

By Berland. Based on png-version Image:Linear_interpolation.png. Newer version by ElectroKid – Own work, Public Domain, Link

Applying Linear Interpolation

Applying this to our previous code requires quite a bit of modification.

First, we need to keep track of when the animation started, the width value when it started, and what we want our width to be at the end. Previously we used properties of the AnimatedCanvas class to track each value we used in our animation. In this version we’re going to use a Dictionary to store values and keep that in a property of the canvas. This gives us a means of throwing away the animated values (setting our Dictionary property to Nil) when we’re not using them, mainly, but also looks a bit cleaner in the Properties listing in our project, and sets up for the future of this project.

Properties

We’re going to add a new property to our AnimatedCanvas class which will hold our calculation values during the animation process:

Private Property animAction as Dictionary

With the addition of this property, we’re going to get rid of our old animStep property.

MouseUp Event

Our MouseUp handler is quite a bit different in this implementation. Instead of calculating the animation steps based on the timer’s interval and the length of time we want our animation to run, we’re now doing the following:

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 we find that the timer is currently
' running, then we know that the user wants to
' animate in the other direction. All we need to do
' is switch the direction the animation is running.
if animTimer.Mode = 2 then
expanded = not expanded
end if
'// Here we create our dictionary object 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 width, and the
' expected resulting width. 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 demonstation
' purposes in this project.
animAction = new Dictionary( "s" : Microseconds, "sw" : Width, "ew" : If( expanded, 10, expandedWidth ) )
'// 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

As you can see from the comments above, we’re constructing the Dictionary object with the current time(s), the current width(w), and the expected width at the end of the animation(ew).

These changes also allow for the user to click again during the animation to reverse it without, theoretically, causing any strangeness such as animation skipping or jumping. The new animation operation just begins when the user clicks, cancelling the old one. Since we’re using linear interpolation, the timer’s Action event handler just keeps trucking along with a calculated width based upon the changes.

Timer Action Handler

Our timer’s action handler method is also quite different. This is where we use the Dictionary we created in the MouseUp event handler and assigned to our animAction property to calculate and apply the new width of our component.

Private Sub animTimer_Action(sender as Timer)
   '// In this version we've moved from having properties to store
   '   the values we use in our animation to a dictionary
   '   because it's both data we don't want to keep around when not 
   '   animating, and it'll be a bit easier to implement multiple
   '   running animations later by looping over an array of these
   '   dictionary objects on each Timer action.
 '// Our first step is to make sure we actually have an animation
   '   to perform.
   if IsNull( animAction ) then
     '// No current animation. The timer shouldn't even be running,
     '   so we'll go ahead and kill it. Theoretically this should
     '   never happen, but it's another case of checking just so
     '   we're not using unnecessary CPU cycles.
     sender.Mode = 0
     Return
   end 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 since we create the
   '   Dictionary with the same set of keys every time and always
   '   overwrite the old object with the new one.
   dim animStart as Double = animAction.Value("s").DoubleValue
   dim animStartWidth as Double = animAction.Value("sw").DoubleValue
   dim animEndWidth as Double = animAction.Value("ew").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.
   dim timePercent as Double = (((Microseconds - animStart) / 1000) / manimTime)
 '// 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.
   dim animStep as Double = Lerp( animStartWidth, animEndWidth, 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.
   if animStep = animEndWidth or timePercent >= 1 then
     me.Width = animEndWidth ' Set our width to the end result.
     expanded = not expanded ' Toggle the state boolean.
     animAction = nil ' Set our dictionary to nil since we don't need it.
     sender.Mode = 0 ' Disable the Timer
     RaiseEvent AfterAnimate ' Notify that the animation is done.
 Return ' Bail out.
 end if
 '// If we get here, then we're still somewhere in the middle
   '   of the animation. Apply the new width value, and we're
   '   good to go.
   me.Width = animStep
 End Sub

New Events

For this version, I’ve also added a couple of new events. These can be used to perform other actions that you may want to carry out when the animation process has started or ended. Here’s our two new event definitions:

Event AfterAnimate()
Event BeforeAnimate()

Other Changes

When you launch the demo project, you’ll notice that there’s a lot more going on with wndAnimate than the previous version. First, I renamed the animTime property to a computed AnimationTime property and added it to the inspector, so there’s a field on the window to change this value.

Second, there’s a new checkbox captioned “Insert Interruption”. This uses the BeforeAnimate event to cause the app’s main thread to sleep for 50% of the animation time beginning at 25% of the animation time, which results in the UI becoming unresponsive and the animation to halt for the duration of the Sleep. Once the call to sleep is complete, you’ll see the animation pick up where it would have been if there had been no call to sleep.

Then, a group of RadioButtons for verifying that modal elements do not interfere with animation on the main thread. The choices are: None, MenuItem, and Modal Window. When Xojo was still using Carbon for macOS, modal elements would interfere with UI updates to the main window until that modal element was dismissed. There’s all sorts of technical-ness as to why, but all we really care about is that with the move to Cocoa this is no longer an issue, and the demo proves it.

Finally, I’ve moved the instance of AnimatedCanvas to the right of the Window. This isn’t purely aesthetic as I plan to use this setup in a future version to show how to run multiple concurrent animations.

You can download the updated demo project here.

Guest Post: Animating Xojo, Part 1

Anthony Cyphers — Wed, 24 Jul 2019 10:00:44 +0000

One of the fun things I get to do regularly is build animations into Xojo desktop components. While incredibly rewarding when you get it right, it can be a long road.

Historical Methods

The Tight Loop

A long time ago, to implement animation in Xojo one had to resort to tight loops if the animation needed to be self-contained (in a custom class, for example). This resulted in code that looked a lot like this:

while me.Height > 0
     me.Height = me.Height - 10
     me.Refresh()
     App.DoEvents(10)
 Wend

Now, however, this is bad for a number of reasons. The most obvious being the use of a tight loop for UI updates. This can result in all kinds of funkiness that’s hard to workaround, and often the code above would’ve been much longer to account for other issues in the UI depending upon your implementation.

Second, the use of Refresh(), Refresh was required because the changes were happening in a tight loop, but it comes with its own set of drawbacks, and there are no shortage of forum posts that detail why to avoid it.

Third, App.DoEvents. Don’t. Use. DoEvents. I can’t stress this enough. Unless building a console app, DoEvents should almost always be avoided. As pointed out in this post, if you think you need DoEvents in a desktop app, you probably actually need a thread.

Threads

Using threads for animation can be a great way to implement it depending on the scenario, but one must remember that threads can no longer access the UI. At one time, however, they could. This gave us the ability to take that tight loop above and shove it in to a thread to avoid locking up the UI and using DoEvents. A typical thread animation Run() event might’ve looked like this:

Sub Run() Handles Run
   while me.Height > 0
     control1.Height = control1.Height - 10
     control1.Refresh()
     me.Sleep(10)
   Wend
 End Sub

While this was an improvement as it moved the tight loop out of the primary event loop, the old implementation of threads that allowed for directly accessing the UI came with its own set of problems and was unsafe.

Today

Nowadays, the best method is to use a timer. If we want a self-contained animation, then this requires a bit of setup. I’m creating a new class called AnimatedCanvas that shrinks or expands its width when clicked. Its superclass is Canvas.

The Properties

Once we have that, we’re going to add some properties to it:

Private Property expandedWidth as Integer
 Private Property animStep as Integer
 Private Property animTimer as Timer
 Private Property expanded as Boolean = True

The expandedWidth property is where we’re going to store the width we want when the control is expanded fully.

animStep is where we’ll store the current animation’s step value, or the amount of change to the width at each stage of the animation.

animTimer is our Timer instance that will be doing the heavy-lifting.

The expanded boolean property helps us determine what operation is currently in progress. We set it to True because we’re going to use the default width of the control as our expandedWidth property later on.

The Event Handlers

The first event handler we want to add is the Open event. In this simple example we’re just setting our expandedWidth property to the width of the component, and setting up our animTimer property for use later.

Sub Open() Handles Open
   '// In this example, I'm just setting the expandedWidth to the initial width.
   '   A real-world case would obviously be different.
   expandedWidth = me.Width
 '// Initialize our animation timer. I'm using a period of 20 here,
   '   but this should be adjusted for best performance and smoothness
   '   based on what you're animating.
   animTimer = new Timer
   animTimer.Period = 20
   animTimer.Mode = 0
   AddHandler animTimer.Action, WeakAddressOf animTimer_Action
 End Sub

Next we’re just going to do something simple in the Paint event so that we can see what’s going on

Sub Paint(g As Graphics, areas() As REALbasic.Rect) Handles Paint
   '// Just fill it red so that we can see it.
   g.ForeColor = &cff0000
   g.FillRect( 0, 0, g.Width, g.Height )
 End Sub

MouseDown is also simple. We want our animation to occur only if the control is enabled, so we can just return the value of Enabled. If Enabled, then MouseUp will fire next to start our animation.

Function MouseDown(X As Integer, Y As Integer) Handles MouseDown as Boolean
   Return me.Enabled
 End Function

MouseUp is a little more complex as we’re doing some simple math for animStep and then starting the timer.

'// 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
 '// Here we setup our animation step to take 1000ms.
 '   We multiple by 20, which is our timer interval.
 '   The minimum built-in timer Interval for macOS
 '   is 10ms and for Windows is 16ms, if I remember
 '   correctly. 20 gets us where want to be, but
 '   could just as easily use a #IF target or the
 '   value of 16.
 animStep = (expandedWidth / 1000) * 20
 '// If our control is currently expanded, then we'll
 '   use a negative value to shrink it.
 if expanded then animStep = -animStep
 '// Finally, enable the timer to perform the animation.
 animTimer.Mode = 2

Timer Action

Now that we have all of that setup, the last thing we need to do is add our timer’s Action handler method. This is going to do the bulk of the work by calculating the new width, checking the new width for validity, then either applying the new value or ending the animation.

Private Sub animTimer_Action(sender as Timer)
 ‘// We want to calculate the new value ahead of time.
 ’   This gives us the opportunity to bail a little
 '   earlier and not have to apply a corrected value later.
 dim newWidth as Integer = me.Width + animStep
 ' If expanded = True then we’re shrinking.
 if expanded then
  ‘// If our newWidth is going to be less than or equal to
  ’   our minimum width, then we’re done with our animation.
  '   I’m using a hardcoded width of 10 here, but you could
  '   create a property for this.
  if newWidth <= 10 then    
   ‘// Make sure the width is correct for the new state,    
   ’   disable the timer, then set our Expanded property.    
   me.Width = 10    
   sender.Mode = 0    
   expanded = False    
   Return  
 end if 
else  
‘// If our newWidth is going to be greater than or equal  
’   to our expandedWidth, we bail.  
if newWidth >= expandedWidth then
    ‘// Make sure the width is correct for the new state,
    ’   disable the timer, then set our Expanded property.
    me.Width = expandedWidth
    sender.Mode = 0
    expanded = True
    Return
  end if
 end if
 '// If we get here, then we're still somewhere in the middle
   '   of the animation. Apply the new width value.
   me.Width = newWidth
 End Sub

Final Notes

As you can see, animating in Xojo is a fairly simple concept at its core. The real fun starts when you want to animate multiple virtual elements inside picture objects with varying types of animation, and we won’t even get in to easing.

Bear in mind that this is an intentionally simplistic example that’s meant to illustrate the basics of timer-based animation. A full implementation that expects multiple different moving parts in tandem or independently would be much more complex, and likely use something along the lines of an Array or Dictionary to keep track of the animation queue and the expected changes at each step in the process.

I’ve built all of this in to an example project, which you can download here.

Web: Create Sliding-Animated Menus

Javier Menendez — Wed, 30 Jan 2019 10:00:32 +0000

Sometime ago a Xojo user asked if it is possible to use Xojo Web to create the kind of animated menus seen in several regular websites. After some investigation (and the invaluable help of Greg O’Lone), the answer is: yes, you can do that! If you are interested in seeing how to achieve this, continue reading!

We’ll start with a WebContainer, responsible for including all the menu elements. For this particular example, a couple of WebLabel controls that when clicked, will display the associated web page; a template web page (WebPage), that will be used to create all the web pages driven by the menu so they can display all the common elements; a couple of Web styles, to set the menu opacity and menu items text color; and a bit of JavaScript to animate the menu itself.

Creating the styles

With Xojo running with a new Web project, we will start adding a couple of styles (WebStyle) to the project from the Library. Select the first of the just added styles in order to access the Styles Editor and change the Name property to MenuStyle in the Inspector. Now, add the Background property using the Style editor and set the background color to the one you want to use. Maybe you want to set the Opacity property so it is not 100% solid when the menu is displayed over the webpages.

Choose the second style in the Navigator and change its Name property to TextWhite (or other name of your election) in the Inspector, setting the Text Color property to the one you want (white in the example). This is the style to be applied on the WebLabel controls of the menu.

Creating the WebContainer-based menu

Add now a WebContainer from the Library to the Navigator. This is the control that will include all the links to the webpages of the web app; and also will contain the button responsible of closing the menu using a sliding animation on the right side of the webpage. Of course, you can easily change these UI controls to other ones that fits better in your app design.

With the WebContainer selected in the Navigator, use the Inspector to set the following properties:

Name: CCMenu
Style: MenuStyle

You don’t need to modify the size of the control; this is something we will set using the control locking options in the Inspector once we add it to our template webpage.

The next control that we add to the WebContainer is the button that will hide the menu, and also the WebLabels that will link to the webpages we want to drive from the menu. Don’t forget to set the property Style to TextWhite (or the name set in the previous step) to the WebLabels using the Inspector.

At this point, the WebContainer CCMenu should be similar to the one displayed in this screenshot:

Adding Behavior to the Menu

The next step is adding the behavior to the WebContainer, so it is hidden or displayed when directed from our web app; so add the a new method to the CCMenu WebContainer using the following signature:

ShowMenu( show as Boolean = True )

And set its Scope to Private. Then, write the following snippet of code in the associated Code Editor:

Dim sa() As String
// We get the unique ID for the WebContainer
sa.Append "var el = document.getElementById('" + Me.ControlID + "');"

// accessing its Style property
sa.Append "var st = el.style;"

// If the 'show' variable is set to True, then
// that means that we want to display the menu
If show Then
  // we set the position and animation properties
  // so the menu is displayed sliding from
  // the right margin of the webpage
  sa.Append "st.transitionProperty = 'right';"
  sa.Append "st.transitionDuration = '1s';"
  sa.Append "st.transitionTimingFunction = 'ease-in-out';"
  sa.Append "st.right = '0px';"
Else
  // If the value is set to False, then
  // we will hide the menu, sliding it outside
  // of the right bound of the webpage
  sa.Append "st.right =  '-" + str(me.width) + "px';"
End If

// we compose the JavaScript sentence to execute
Dim js As String = Join(sa, "")

// executing it on the current webpage
ExecuteJavaScript(js)

While this is the method in charge of doing the real work, we will add a couple of convenient public methods to make more explicit the task of displaying and hiding the menu. Add thus the first of such methods to the WebContainer CCMenu using the following values in the associated Inspector:

Method Name: Show
Scope: Public

And put this line of code in the associated Code Editor:

ShowMenu(True)

That is, it will call the previously created private method passing along the True value, so it will instruct to display the menu.

Add the second method, using these values:

Method Name: Hide
Scope: Public

And put this line of code in the associated Code Editor:

ShowMenu(False)

These are all the methods needed. Now select the button added to the WebContainer and change its name to Close from the Inspector Panel. Next, add the Action Event Handler to it and write the following line of code in the associated Code Editor:

Hide

That is, when the web app user clicks the button it will call the method in charge of hiding the Menu.

Now is time to add the functionality to the labels responsible for showing the associated webpages; that is, the menu option themselves. For this, we are using a really simple approach in order to simplify the example and focus in the main topic of this tutorial. For this, the text displayed by the labels is the name of the webpages to be displayed. Select the first of the labels and set the following property using the Inspector:

Text: WebPage1

Adding next the MouseDown Event Handler and writing the following couple of lines of code in the associated Code Editor:

If Me.Page.Name = Me.Text Then Exit

WebPage1.Show

Now repeat the process for the second label setting the following property from the Inspector:

Text: WebPage2

And this code in the associated Code Editor for the MouseDown Event Handler:

If Me.Page.Name = Me.Text Then Exit

WebPage2.Show

Now we have everything we need for our example menu.

Creating the Template Webpage

Now it is time to add the webpage acting as a template for all the app webpages subclassed from it using the menu.

Add a new WebPage to the project from the Library and change its name to WPBase using the Inspector. Next, add the CCMenu WebContainer to it from the Navigator and a button from the Library, so the result is similar to the one displayed in the following screenshot:

Notice the Locking values for the added WebContainer displayed in the Inspector on the screenshot, so it is locked to the same width and height of the webpage when we run the app.

Select now the button and add the Action Event Handler writing the following line of code in the associated Code Editor:

ccmenu1.Show

As you can see, this simply calls the public show method previously added to the CCMenu WebContainer, so it displays the menu. This is everything we need to do.

Creating the Example WebPages

We have mainly everything we need to run our example. We just need to add a couple of additional webpages to the project from the Library. Change its names to WebPage1 and WebPage2, because this is the property whose value has to match with the text of the labels added to the menu, in order to show the right page from the menu.

The main point here is set the Super property for both webpages to WPBase, so they inherit all the elements from the template webpage created in the previous step. Finally, add any controls you want to each webpage simply so you can distinguish one from other when selected from the menu.

Click the Run button in the Xojo IDE toolbar and test the menu! You can download and play with the project this tutorial is based on from this link.

Javier Rodriguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others.

*Read this post in Spanish

Animating the Web: Fading Images in-out

Javier Menendez — Wed, 19 Dec 2018 10:00:29 +0000

This tutorial will show you how easy it is to create animations on components of Xojo web apps, thanks to the use of the Style Editor and the WebAnimator class. Learn how to do a fade effect between two images that you can expand and adapt to your web apps.

In order to recreate this fade effect we’ll mainly use a couple of styles (WebStyle class) to set the initial status for each one of our images (instances from the WebImageView class). These will be overlaped in the web page, sharing the same position. Then we’ll add a button to the web page so it will fire the animation every time it is clicked.

Let’s see how we can do this, step by step.

Creating Styles

The style creation process is really simple in Xojo Web thanks to the integrated Style Editor. For example, drag two instances of a WebStyle from the Library panel to the Navigator (the leftmost column in the Xojo IDE). Now select the first of these style instances in the Navigator and you will see the Style Editor.

The first thing to do is change the style name using the Name attribute in the Inspector. For example, type ZeroOpacity as the name. As you can guess, this will be the style that applies a 0% of opacity on any control it is attached to. For this, access the properties popup menu and click on the Add Property button in the Editor then select the Opacity option under the Miscellaneous section. The Editor will add the property to the editor, where we only need to set the value to 0%.

Repeat the process for the second style, except that in this case the name will be MaxOpacity, leaving the default value associated with the Opacity property once the style has been added.

As you can see, the Style Editor also allows us to create styles that implements other additional properties like fonts, shadows, color, borders, etc., with several variations for every possible status of a control: Normal, the cursor is over the control, the control has been clicked, or is an already “visited” link, for example. These are the common statuses for any object or control on a web page of a web app.

Applying Styles to Controls

With the webpage added by default to the project selected (WebPage1), add two instances of the WebImageView control from the Library to the web page. Set their sizes so they are the same, and set their positions so they are located in the same place (Left and Top properties). Next, add two images to the web project; it is best if they have the same size as the one set to the WebImageView instances.

The next step is setting each image to each WebImageView instance, at the same time that we set the style created in the previous step to each one of these instances. Both operations are done using the Inspector.

Choose the first of these instances, ImageView1 and in the Inspector choose one of the two added images selecting the popup menu associated with the Picture property under the Behavior section. Next, select the ZeroOpacity style option in the Style popup menu under the Style section.

Repeat this operation for the ImageView2 instance and use the Inspector to select the other image and the style MaxOpacity.

Starting the Animation object

The use of the WebAnimator class is really easy. Just set a control derived from the WebControl class over we want it to work in order to apply any operation of Scale, Movement, Resizing, Rotation… and also animate its opacity value. That is what we want to achieve in this example. Then set the amount of time for the animation (in seconds) and the value of the attribute or attributes we want to modify (for the opacity, only set one property).

Of course the animation can be smoothier (or more detailed) using keyframes references. The best part is that the animations are done in the client side of the web app; that is, the browser. This means that you’ll be away from latency derived problems or communication speed problems because the app doesn’t needs to talk with the server.

For our example the operation is really simple. Once we create the instance from the WebAnimator class (drag it from the Library to the Webpage1, so it is added to the Shelf in the bottom of the Editor), we will animate the image in the upper position (with the Style at 100% opacity) to a 0% opacity. Then, animate the second image, in a lower layer, doing exactly the opposite so its opacity gets a 100% value. Once the animation has finished, we will change the variables in charge of setting the opacity level for each image, so the process is reversed the next time the button is clicked.

Thus, we can add the Action Event Handler to our button (use the Insert > Event Handler menu option for that), and add the following snippet of code to it using the Code Editor:

Static first As Integer = 0 // Variable to set the opacity to a 0%
Static second As Integer = 100 // Variable in charge of setting the opacity to a 100% value

Animator1.Opacity(ImageView1, first, 1) // We set the property we want to animate into the Animation instance
Animator1.Play // And execute it so it efectively animates the opacity property to the passed value
animator1.Opacity(ImageView2,second, 1) // We repeat the process for the second image
Animator1.Play
If first = 0 Then // And we interchange the variables values, so they do the opossite action next time the Event Handler is called
  first = 100
  second = 0
Else
  first = 0
  second = 100
End If

Of course, you can expand it (or adapt the code) so it is more flexible if you decide to include, for example, the ImageView controls into a ContainerControl, or you add an Array to the mix in order to apply this fade effect to more than just two images, even at a specified period of time. Do you dare?

*Watch a video of this Tutorial in Spanish

*Read this post in Spanish

Contrast Illusion Animation

Paul Lefebvre — Wed, 29 Nov 2017 19:41:31 +0000

I was reading Twitter recently and came across this Tweet:

Reality shatter. The two objects are traveling in exactly the same manner. Watch when it turns gray. https://t.co/gkRKyfNnyI pic.twitter.com/HpZsudeXSG

— Cliff Pickover (@pickover) November 26, 2017

So of course, I though that would be cool to try in Xojo. After a few minutes of playing around I quickly had it.

In addition to being a cool illusion (eyes are weird), this project is a good excuse for me to again show how easily you can do animation with Xojo.

Essentially, you just need a Timer that tells a Canvas to update regularly. The Canvas then redraws itself using your objects.

I added a Block class to serve as the blocks that move across the stripe pattern. This class has properties for the X, Y, color and a method to draw itself.

In the Open event of the Canvas, the block objects are initialized:

Block1 = New Block // property on Window
Block1.X = 0
Block1.Y = Canvas1.Height / 3
Block1.BlockColor = &cFFFF00

Block2 = New Block // property on Window
Block2.X = 0
Block2.Y = (Canvas1.Height / 3) * 2
Block2.BlockColor = &c0000ff

A Timer is added to the Window (Period = 10) with code to update the block’s X coordinates:

Block1.X = Block1.X + 1
Block2.X = Block2.X + 1

If Block1.X > Canvas1.Width Then Block1.X = 0
If Block2.X > Canvas1.Width Then Block2.X = 0

Canvas1.Invalidate(False)

The Paint event then draws the stripe pattern (or not if a hide checkbox is selected):

If HideStripeCheck.Value Then
  g.ForeColor = &ccccccc
  g.FillRect(0, 0, g.Width, g.Height)
Else
  g.ForeColor = &c000000
  g.FillRect(0, 0, g.Width, g.Height)
  Dim showStripe As Boolean
  For i As Integer = 0 To g.Width Step 25
    If showStripe Then
      g.ForeColor = &cffffff
      g.FillRect(i, 0, 25, g.Height)
    End If
    showStripe = Not showStripe
  Next
End If

Block1.Draw(g)
Block2.Draw(g)

Download the illusion project and be amazed at how your eyes play tricks on you:

Illusion Project