So, what is UI Compatibility Mode? It’s Apple’s way of ensuring that your app’s UI appears in macOS 26 and iOS 26 just as it did on previous OS versions. No Liquid Glass effects, no unexpected changes in control sizes or behavior, everything stays as you designed it. This means your pixel-perfect layouts from older OS versions, like Sequoia or iOS 18, will continue to look exactly as intended.

More technically, when UI Compatibility Mode is enabled, your app behaves as if it were compiled with an earlier SDK.

The caveat: Apple only guarantees this behavior while macOS 26 and iOS 26 are current. With the next major OS releases, this mode may no longer be available, so it’s a temporary solution.

The upside: At the time of writing, Apple is still refining these OS versions with point releases. If you need your app to run on macOS 26 or iOS 26 with full compatibility, you can enable UI Compatibility Mode in the Inspector Panel under Build Settings > macOS and Build Settings > iOS.

When enabled, both your debugged apps and the built versions (including those submitted to Apple via Publish) will look and behave on macOS 26 and iOS 26 as if they were compiled with the previous SDK. In fact, the behavior is even more consistent than if they had been compiled using the prior Xojo release.

Below, you can see how the same app appears when running on macOS 26 and iOS 26 with UI Compatibility Mode turned off (showing Liquid Glass and all the new UI effects), compared to how it looks when the switch is turned on:

The Last Word

All in all, macOS 26 and iOS 26 introduce a major UI overhaul, which can change the appearance of existing layouts. To help developers, Apple has added UI Compatibility Mode, which lets your apps appear on these new OS versions just as they did on previous releases—no Liquid Glass effects or layout changes. Technically, enabling this mode makes your app behave as if it were compiled with an earlier SDK. While Apple only guarantees this behavior for macOS 26 and iOS 26, it ensures consistency for both debugged and built apps, including those submitted via Publish.

UI Compatibility Mode gives you a choice: enable it to preserve your exact layouts across all OS versions, or leave it off to adopt the new macOS 26 and iOS 26 look and feel, which may require adjusting your UI for some quirks.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

macOS 26 and iOS 26

Over time, Apple has brought the user experiences of macOS and iOS closer together. macOS 26 and iOS 26, now aligned in version numbers, also share more similarities than ever in their user experience. These updates represent the most significant user experience changes from Apple since iOS was introduced in 2007 and Aqua for macOS seven years earlier. With such a big update, especially when designing elements to work on both large computers displays as well as small smartphone screens, it’s no surprise there’s some tweaking requiring after release. Clearly, Apple is still refining its platforms.

We continue to update Xojo as Apple defines its preferred user experience, ensuring that you can deliver the best possible experience to your users.

WinUI

We are also hard at work upgrading our Windows framework to WinUI, providing a modern user experience for Windows apps. You can see our progress in each release by enabling the Use WinUI (Experimental) option on the Advanced tab in Windows build settings. The “Experimental” label is a reminder that the feature is still evolving, and it will be removed once WinUI is fully ready. Our goal has always been to keep Xojo on a steady path, prepared for whatever challenges lie ahead.

Conclusion

On behalf of the entire Xojo team, I can say that we love what we do and we appreciate your support in allowing us to do it. We are Xojo users ourselves (after all, we make Xojo with Xojo) and we enjoy seeing what you make with it. With that in mind, feel free to tell us about your creations. Send your screenshots, descriptions and your story to hello@xojo.com.

The goal wasn’t to add new features but to explore how applying thoughtful UI design principles can significantly enhance the look and feel of an application, making it more visually appealing and cohesive.

Here are some of the key aspects of the UI revamp:

• Design System Foundation: I started by establishing a basic design system. This involved defining core visual elements to ensure consistency across the entire application interface.
• Typography Definition: Specific styles were defined for how titles and standard text should appear. This helps create a clear visual hierarchy and improves readability.
• Consistent Color Palette: A specific set of colors (Light & Dark mode) was chosen and implemented throughout the project, contributing to a unified and more polished look.
• Refined ListBox Appearance: The standard DesktopListBox control received some visual tweaks to better align with the overall updated aesthetic.

The aim was to demonstrate how focusing on UI details can elevate even a simple example application.

Here’s a glimpse of the revamped ToDo app:

You can find the complete source code for this UI-enhanced ToDo app project on GitHub.

Stay tuned for more exciting projects as we continue our Year of Code 2025 journey!

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!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Year of Code Project

• Year of Code: Kickoff
• January Project: Desktop Apps | Forum Discussion
• February Project: Database Apps | Forum Discussion
• March Project: Web Apps | Forum Discussion
• April Project: User Interface | Forum Discussion
• May Project: Mobile Apps | Forum Discussion
• June Project: Code Sharing | Forum Discussion
• July Project: Charting | Forum Discussion
• August Project: Console Apps | Forum Discussion
• September Project: Games | Forum Discussion
• October Project: Multi-Platform | Forum Discussion
• November Project: PDF | Forum Discussion

How to Play:

Each month we’ll announce a new theme and share an example project of our own. Share your projects to the Xojo Forum thread for that month via GitHub (all the links you need are posted above ↑ ). Learn how to use Xojo and GitHub.

The Prizes:

Monthly winners get $100 at the Xojo store. Every month you submit a project is another chance to win the grand prize. The grand prize is $250 cash plus a Xojo Pro license and a year of GraffitiSuite and will be announce in December. Learn more about the prizes.

This control is available in the Xojo Library panel and works similarly to iOSMobileUserControl: drag it onto a layout and implement the CreateView event.

Declare Function Button Lib "Kotlin" Alias "android.widget.Button(context as android.content.Context)" (context As Ptr) As Ptr

Var bp As Ptr = Button(App.AndroidContextHandle)

Return bp

The above code uses a Declare to create a native Button and returns it so that it can be displayed in a layout.

By using AndroidMobileUserControl and Declares to access the Android UI library, you can create your own UI controls. I look forward to seeing what the community creates!

Paul learned to program in BASIC at age 13 and has programmed in more languages than he remembers, with Xojo being an obvious favorite. When not working on Xojo, you can find him talking about retrocomputing at Goto 10 and on Mastodon @lefebvre@hachyderm.io.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

And what do we mean by the transitory character of Popover windows? Well, and here comes one of the first differences from Modal windows. When a Popover is visible and the user clicks or taps on any other element of the graphical interface not contained in the Popover itself it will close, hence transitory. So, you don’t have to include the typical “Close window” button in a Popover (though you can), since it will close when the user clicks outside of it, i.e. when the Popover loses focus.

Where are the Popover Window Contents?

Where do you define the content displayed in a Popover window? While in your Web app, you can do it on any Container control added to the project. In the case of Desktop and iOS apps, you can do it on either the designs of a Container Control or any Window or Screen added to the project.

For example, here you can see that the content shown as a Popover in the previous screenshot is actually that of a Window (Window2) added to the project:

This introduces additional flexibility allowing your app’s logic to decide when to display a Window or Container instance as you have been doing until now, or display it as a Popover.

Showing a Popover

Displaying a Popover is very straightforward, whether it is created from a Container or a Window, the method is the same:

DesktopContainer.ShowPopover(parentControl As DesktopUIControl, facing As DesktopWindow.DisplaySides = DesktopWindow.DisplaySides.Bottom, detachable As Boolean = True)

The explanation of the expected parameters is as follows:

• ParentControl: The control that will act as the parent, or on which the Popover will be pointing to.
• Facing: The direction in which the Popover will point on the parent control; by default it will appear under the parent control, but you can use any of the values available in the DesktopWindow.DisplaySides enumerator (or the iOS equivalent).
• Detachable: This value only applies to macOS Popovers, since said operating system has the ability for the user to “detach” the Popover from the parent control as long as this value is defined as True. To detach, drag the Popover with the mouse cursor.

Let’s say we have a window called Window2 and a button called MyButton. In the Pressed event of MyButton we can use the following lines of code to display Window2 as a Popover:

Var w As New Window2
w.ShowPopover(me)

And that’s all!

Platform Differences

In the previous section we already pointed out the first: macOS is the only operating system that acts on the value indicated in the Detachable parameter. But there are some other considerations to keep in mind so you don’t get caught off guard:

• Beyond the limits. Although in Windows and macOS Popovers can exceed the limits of the window on which the parent control is located, the position of the popover in Linux is restricted to the limits of the window that contains the parent control. This is the same for iOS and for Web pages.
• iPhone and iPad. When a Popover is displayed on an iPhone, it will look like a modal window; while if the same application is run on an iPad, the appearance will be the typical one expected from Popovers: the window pointing to the parent control in the indicated direction.
• On the Web. The contents of a Popover are those defined in a Container control, while on the rest of the platforms you can use both Container controls and Windows / Screens.

Why the Popover doesn’t “point” in the configured direction?

By default it will try to do so according to the value that has been set in the “facing” parameter, but if it does not find enough space on the margins of the screen, then it will be displayed on the next side of the parent control in which there is available space for display the Popover in its full width and height; This is true on macOS, Linux, Web and iOS.

Can I reuse a Popover?

No, You can not. Whether you use a Container control or a window as the source of the UI design to be displayed by the Popover, do not lose sight of the fact that the Popover is just another type of window; and therefore behaves as such. That is, once it is closed either because it has lost focus or because you have closed it explicitly through code invoking the Close method, all the displayed controls and the rest of the internal structures will be closed / invalidated, so that although the instance If a Popover is not Nil (because, for example, you keep a reference to the window or container instance used as the UI source), you will not be able to invoke the ShowPopover method again on said instance but you will have to create a new instance of the Container/ Window used as the source of the UI to be displayed by the Popover.

How can I communicate with the UI elements contained in the Popover?

You would do so just as you would do with any other type of window that you have been using so far in your Xojo projects.

Conclusion

Without a doubt, Popovers are a new way to improve the design of your apps’ user interfaces, providing a more direct relationship between the user interface elements displayed in the Popover and the “parent” control in charge of displaying it. Furthermore, since you can use any window or container you want as the source of the UI to be displayed by the Popover, you will have greater flexibility about when you want to display them in a Popover or display them using any other of the available window types or, in the case of Containers, embedding them as part of other UI elements at runtime.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

• The control should show previews of images and PDF documents.
• The documents to be displayed can be dragged and dropped onto the control, or opened from the standard file selection dialog.
• In the case of images, they can also be added to the control using Copy and Paste.
• In any of the above cases, the path of the file in question must be received so that future actions can be carried out.

As an additional point, since we are using Xojo, the control will be cross-platform and functional on macOS, Windows and Linux.

Download the Example Project.

Preparation

Taking into account these requirements, as well as considering that the same problem may have more than one solution, this tutorial will show you how to create a control using the Composition technique. Using this technique, several graphical interface controls will be used internally and their use will be transparent to users who use it globally, either when creating their own applications or when using the control on any desktop platform.

When it comes to creating a control using the Composition technique, the DesktopContainerControl is the best candidate. A new ContainerControl-based class would internally use the following core controls:

1. The DesktopImageWell control which is ideal for displaying images.
2. The DesktopHTMLViewer control which is ideal for displaying the preview of PDF documents.

Now, while DesktopImageWell supports displaying images directly using Drag and Drop, this is not the case with the DesktopHTMLViewer control; so if the user of the control tried to drag and drop a PDF document or image when the HTMLViewer is displaying the control, it wouldn’t work.

To solve this situation it is common to add a third control. We’ll use a DesktopCanvas that will be, at all times, the top layer regardless of which underlying control (either the ImageWell or the HTMLViewer) is displayed. Thus, the DesktopCanvas would capture the event corresponding to the user dragging a file onto the global control (the class based on ContainerControl). Since it is transparent, it will not prevent the preview of the image or PDF file to be seen in the bottom layer control, at least on macOS.

But the Canvas is not transparent on Windows, in this case we need to use conditional compilation at various points in the class to modify the user interface of the main ContainerControl so that it adds a special area located under the controls preview (ImageViewer or HTMLViewer), and which will be used by the user of the control to drag and drop the corresponding files. For this we will use an additional DesktopCanvas.

Of course, we will also have to add a button to our control that will be responsible for opening the standard file selection dialog box so that the user can choose the file to preview.

To deal with another small difference between macOS and Windows, we will add a DesktopRectangle to be used as the base layer of the control (Z axis), so that it displays the typical Focus ring when the control is active and selected.

Designing the Control

With all that in mind, start a new Desktop project in Xojo. Drag a DesktopContainer from the Library onto the Navigator. It will look like this:

With the new Desktop Container1 instance selected in the Navigator, use the Inspector Panel to change the following values:

• Name: ImagePDFContainer
• Size > Width: 220
• Size > Height: 200

Next, add the Drag and Drop area which, remember, will be shown only when the control is executed on Windows. To do this, drag a DesktopCanvas from the Library and drop it in the area of the Layout Editor corresponding to the Design Editor, placing it right under the container for our own convenience.

With Canvas1 selected, use the Inspector Panel to change the following values:

• Name: DropArea
• Position > Left: 1
• Position > Top: 221
• Position > Width: 216
• Position > Height: 100

The design should look like this:

Now, add the background layer. This is the layer that will be in charge of displaying the focus ring for the control in Windows. To do this, drag a DesktopRectangle from the Library and drop it on the ContainerControl in the Layout Editor. The ContainerControl should show a red box indicating that the dragged control will be contained as a child control in the Container itself. Next, with DesktopRectangle1 still selected in the Layout Editor, use the Inspector Panel to modify the following values:

• Name: BacktroundRect
• Position > Left: 0
• Position > Top: 0
• Position > Width: 220
• Position > Height: 200
• Locking: Lock all four padlocks.

Next, add the button responsible for displaying the standard dialog box for selecting the file to preview. Drag a DesktopPushButton from the Library and drop it onto the bottom of the Container in the Layout Editor. The Container should display a red box to indicate that the button will be added as a child control in the Container itself.

Then, with Button1 still selected in the Layout Editor, use the associated Inspector Panel to change the following values:

• Name: OpenFileButton
• Position > Left: 0
• Position > Top: 0
• Position > Width: 178
• Position > Height: 22
• Locking: Closes the left, right and bottom locks. Open the lock on the top edge.
• Mac Button Style: Recessed
• Caption: Open File…

At this point, the control layout should look something like this:

Now, add the instance of the DesktopImageViewer control responsible for previewing the images. As in previous steps, drag the DesktopImageViewer control from the Library and drop it on the Layout Editor, in the upper right part of the Container; then, with ImageViewer1 still selected, use the associated Inspector Panel to change the following values:

• Name: ImagePreviewer
• Position > Left: 238
• Position > Top: -219
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

Drag a DesktopHTMLViewer from the Library onto the free area of the Layout Editor, just below the ImageViewer added in the previous step; Then, with HTMLViewer1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: HTMLPDF
• Position > Left: 238
• Position > Top: 0
• Position > Width: 218
• Position > Height: 198
• Locking: Lock all four padlocks.

At this point, the control layout should look something like this:

Finally, add the overlay to be used only when the control is executed on macOS and that is responsible for capturing the action of “Drag and Drop” files by the user. Drag a new DesktopCanvas over the Container in the Layout Editor. The Container should display a red box to indicate that the new control is being added as a child of the Container itself. With Canvas1 still selected in the Layout Editor, use the associated Inspector Panel to modify the following values:

• Name: CanvasOverlay
• Position > Left: 1
• Position > Top: 1
• Position > Width: 218
• Position > Height: 179
• Locking: Lock all four padlocks.

To make sure that all the “layers” (order of the controls on the Z axis) are as we expect, click on the “Show Tab Order” button in the Layout Editor toolbar. If they do not match the order shown in the image below, drag and drop each element to the correct position in the list:

Add Functionality

With the design of the control now complete, it is time to add its functionality. To do this, select ImagePDFContainer in the Navigator and add the following properties along with the values indicated in the Inspector Panel:

The first will be in charge of containing the message to be displayed in the “Drag and Drop” area:

• Name: DropFileMessage
• Type: String
• Scope: Public

The second will be the property in charge of storing the reference to the file (FolderItem instance) whose image/PDF is being previewed:

• Name: FileDropped
• Type: FolderItem
• Scope: Private

The last property will be responsible for containing the color to be used as the focus ring:

• Name: FocusColor
• Type: Color
• Scope: Public

Next, add the events that the control needs to consume for its operation. With ImagePDFContainer still selected in the Navigator, add the following Event Handlers along with the associated code:

Opening:

HTMLPDF.Visible = False
ImagePreviewer.Visible = False

#If TargetWindows Then
  DropArea.Top = Me.Height - 50
  DropArea.Height = 50
  DropArea.Width = BackgroundRect.Width
  DropArea.Left = BackgroundRect.Left
  BackgroundRect.Height = BackgroundRect.Height - 50
  
  HTMLPDF.Height = BackgroundRect.Height - 2
  ImagePreviewer.Height = BackgroundRect.Height - 2
#EndIf

RaiseEvent Opening

MouseDown:

Me.SetFocus
Return True

FocusReceived:

#If TargetWindows Then
  FocusColor = Color.Blue
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

FocusLost:

#If TargetWindows Then
  FocusColor = Color.Black
  BackgroundRect.BorderColor = FocusColor
  DropArea.Refresh
#EndIf

Since the Opening event is used by our ImagePDFContainer subclass, add an event definition with the same name so that instances created from it can also add their own Opening event handler and include any additional code to execute as desired.

Then, add an additional event definition (FileDropped) that will be the one sent by the ImagePDFContainer subclass to the instances created from it, and that implement it, to pass them as a parameter the FolderItem corresponding to the file opened / dragged and dropped / or , in the case of images, that have been pasted on the control.

• Name: FileDropped
• Parameters: file As FolderItem

Since we want to support pasting images onto the control, we also need to add a MenuHandler to the ImagePDFContainer subclass. To do this, with ImagePDFContainer still selected in the Navigator, select the option Add to “ImagePDFContainer” > Menu Handler…

Use the following values in the associated Inspector Panel:

• MenuItem Name: EditPaste

And add the following code in the Code Editor associated with the Menu Handler:

Var pb As New Clipboard
If pb.PictureAvailable Then
  Var f As FolderItem = SpecialFolder.Temporary.Child("temp-pict.png")
  If f.Exists Then f.Remove
  If f <> Nil Then
    pb.Picture.Save(f, Picture.Formats.PNG)
    FileDropped = f
    PreviewFile(FileDropped)
  End If
  Return True
End If

Return False

To complete this section, add a new method to ImagePDFContainer and use the following values in the associated Inspector Panel:

• Method Name: PreviewFile
• Parameters: f As FolderItem

Add the following code in the associated Code Editor:

FileDropped = f

If f <> Nil Then
  
  If FileDropped.Name.EndsWith(".pdf") Then
    ImagePreviewer.Visible = False
    HTMLPDF.Visible = True
    
    HTMLPDF.Top = BackgroundRect.Top + 1
    HTMLPDF.Left = BackgroundRect.Left + 1
    
    #If TargetWindows Then
      HTMLPDF.Height = BackgroundRect.Height - OpenFileButton.Height
    #Else
      HTMLPDF.Height = Self.Height - OpenFileButton.Height
    #EndIf
    
    HTMLPDF.LoadPage(FileDropped)
    
  Else
    
    Var p As Picture = Picture.Open(FileDropped)
    
    If p <> Nil Then
      ImagePreviewer.Top = BackgroundRect.Top + 1
      ImagePreviewer.Left = BackgroundRect.Left + 1
      
      #If TargetWindows Then
        ImagePreviewer.Height = BackgroundRect.Height - OpenFileButton.Height
      #Else
        ImagePreviewer.Height = Self.Height - OpenFileButton.Height
      #EndIf
      
      ImagePreviewer.Image = p
      HTMLPDF.Visible = False
      ImagePreviewer.Visible = True
      
    End If
    
  End If
  
  RaiseEvent FileDropped(FileDropped)
  
Else
  HTMLPDF.Visible = False
  ImagePreviewer.Visible = False
End If

Add Functionality to Controls

Now it’s time to add functionality to the controls. Select the CanvasOverlay item in the Navigator and add the following Event Handlers along with the code given below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetWindows Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Now select the DropArea item in the Navigator and add the following Event Handlers along with the code indicated below:

Opening:

Me.AcceptFileDrop("application/pdf")
Me.AcceptFileDrop("image/png")
Me.AcceptFileDrop("image/jpg")

#If TargetMacOS Then
  Me.Visible = False
#EndIf

DropObject:

#Pragma Unused action

If obj.FolderItemAvailable Then
  PreviewFile(obj.FolderItem)
End If

Paint:

#Pragma Unused areas

g.DrawingColor = FocusColor
g.PenSize = 2.0
g.DrawRectangle(0, 0, g.Width, g.Height)
g.PenSize = 1.0

If DropFileMessage <> "" Then
  
  g.DrawingColor = Color.Black
  
  Var textLength As Double = g.TextWidth(DropFileMessage)
  Var x, y As Double
  
  x = Me.Width / 2 - textLength / 2
  y = Me.Height / 2 + g.TextHeight / 2
  
  g.DrawText(DropFileMessage, x, y)
  
End If

Now select the HTMLPDF item in the Navigator and add the Event Handlers along with the code indicated below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Next, select the ImagePreviewer item in the Navigator and add the following Event Handlers along with the code below:

MouseDown:

#Pragma Unused x
#Pragma Unused y

Self.SetFocus

Finally, select the OpenFileButton item in the Navigator and add the following Event Handlers along with the code indicated below:

Pressed:

Var f As FolderItem = FolderItem.ShowOpenFileDialog("")

If f <> Nil Then
  Self.PreviewFile(f)
End If

Testing the ImagePDFContainer Control

We have completed the design and added the required functionality to our control, now it is time to add an instance to the project window so we can test its operation.

Select Window1 in the Navigator so that the associated Layout Editor is displayed. Next drag ImagePDFContainer from the Navigator and drop it onto the Layout Editor, using the following values in the associated Inspector Panel:

• Size > Width: 220
• Size > Height: 200
• Locking: Lock all four padlocks
• Appearance > Allow Focus Ring: Enabled
• Behavior > Allow Focus: Enabled.
• Behavior > Allow Tabs: Enabled.

With ImagePDFContainer1 selected in the Navigator, add the following Event Handlers along with the code below:

Opening:

Me.DropFileMessage = "Drop Files Here"

FileDropped:

LastFolderItemNameLabel.Text = file.NativePath

As you can see, this is referring to the LastFolderItemNameLabel control that we have not yet added to the window layout yet; So, let’s do that.

Select Window1 in the Navigator to access the associated Layout Editor. Drag a Label control from the Library and drop it onto the bottom of the window in the Layout Editor, then use the following values in the associated Inspector Panel:

• Name: Label1
• Position > Left: 28
• Position > Top: 360
• Position > Width: 150
• Position > Height: 20
• Locking: Lock the left and bottom padlock. Unlock the top and right locks.
• Text: Last FolderItem Path:

Add a second Label from the Library to the right of the previous one, using the following values in the associated Inspector Panel:

• Name: LastFolderItemNameLabel
• Position > Left: 190
• Position > Top: 360
• Position > Width: 390
• Position > Height: 20
• Locking: Locks the left, bottom and right padlocks. Unlock the top lock.
• Text: (empty)

Run the Application

Ready! Run the application and try dragging and dropping image files (JPEG or PNG), as well as PDF files on the control. You should see the change on the fly, showing the most appropriate viewer for each type of file. It will also display the path of the file at the bottom of the window.

You can also click on the button to select the file to display or try copying images and pasting them directly on the control. If you do this, a temporary file will be created so that one of the initial requirements is satisfied: being able to continue working with the file corresponding to the image or PDF document.

As I mentioned at the beginning, this is just one of the possible implementations. I hope you have learned a few things along the way in, for example:

• Redefine Events consumed by a base class.
• Create your own Class Events and how to launch them to “pass” information to the instances created from said class.
• Capture and work with Menu Handlers.
• Use of Conditional Compilation so that certain sections of code run only on one platform or another.
• And, of course, how to make several UI controls cooperate and present themselves as a single control to the developer and end user who are going to use them.

I hope you found it interesting. You are welcome to modify and expand the project to better suit your purposes!

Have fun and keep coding with Xojo!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

At first glance you might think that simply looking for the option key in a KeyDown event will do the trick. The problem is KeyDown/KeyUp does not get called for modifier keys. The solution is to use a Timer to detect the Option/Alt key, though it could be adapted to read any of the modifier keys.

First of all, we need to decide whether to create a Timer embedded on a Window, or to create a subclass. Either technique will work, but the subclass creates reusable code, something I always recommend. Also, the subclass will allow you to call events which can come in handy.

Start by creating a new class called “OptionTimer” whose super is “Timer”. Next, add a property “Pressed As Boolean”, an event definition “KeyDown”, and a second event definition “KeyUp” to OptionTimer. Lastly add the Action event handler with the following code:

If Keyboard.AsyncAltKey = True And Pressed = False Then
  Pressed = True
  RaiseEvent KeyDown
ElseIf KeyBoard.AsyncAltKey = False And Pressed = True Then
  Pressed = False
  RaiseEvent KeyUp
End If

That’s it for code. Now go to your Window, place a Timer on it and set the super to “OptionTimer” and you can insert code into the events for that timer. You’ll also want to adjust the period of the timer to something small such as 200 to make sure the events are responsive.

To test this, add a Label to the Window which will be used to display different text when the Option key is held down. In the Timer subclass, put this code in the KeyDown event:

Label1.Value = "You are pressing Option."

And in the KeyUp event put this code:

Label1.Value = "Normal Text"

Run the project and watch the text change when you hold and release the Option/Alt key.

*Updated from an original post written by Thom McGrath.

With Xojo 2019R2, everything related to updating the UI is much simpler thanks to the new UserInterfaceUpdate event in the Thread class. This provides, as an Array of Dictionaries, all the values we need to pass along from the Run event of the running Thread.

In order to add new values to these dictionaries, we only need to call the AddUserInterfaceUpdate method, providing as parameter a Pair.

The first (left) value of this pair will be the one acting as the Key for the Dictionary, while the second value of the pair (right) will be the value itself we want to forward to the main thread in order to update our user interface.

In addition, the overloaded AddUserInterfaceUpdate method also accepts a Dictionary as a parameter.

The two ways we can use the new thread class are the same available in previous releases:

• Draging and dropping an object from the Library panel to the Tray in the Window Layout, so the IDE creates a new instance that we can use to implement the Run and, now, also the UserInterfaceUpdate events. The Run event is the one intended to run the code usually associated with a long task, so it doesn’t freeze the responsiveness of the rest of the app (mainly the user interaction or user interface refreshes). The UserInterfaceUpdate event is the new Event whose parameter will provide all the data we are interested in previously added from the Run event calling the AddUserInterfaceUpdate method. That is: every time we call the AddUserInterfaceUpdate method, the Thread will fire its UserInterfaceUpdate event. Think about this as a bridge between our Thread and the main app thread.
• The second approach is the one we use when creating the Thread instances from code. In this case, the solution is simple and is the one we usually use to delegate the code to execute in the Action event of the Timer class. AddHandler sets the method we want to execute in substitution of the UserInterfaceUpdate event handler of a Thread instance. As usual, make sure that the delegated method has the right signature: receiving a Thread object as its first parameter and the data we are interested in as the second parameter.

The example project available here, shows the implementation of both cases, how the Threads sends the data to update the user interface and how such data is received and accessed in the corresponding Thread Event Handler or delegated Method.

As you can see in the example, the user interface is responsive to the user interaction while the two threads do their work.

Easier and faster!

Javier Rodri­guez 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, GuancheID, AXControlGrid, AXImageCanvas, Markdown Parser for Xojo, and HTMLColorizer for Xojo among others.

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.

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" : <OperationToComplete", "l" : <LengthOfAnimation>, "m" : <EasingFunction>, "t" : <StartTime>, "s" : <StartValue>, "e" : <EndValue>)

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.

In this part we’ll be covering a few different things, chiefly concurrent animations. But that’s not all, as I’ve added a lerpColor function to show you how to animate color changes.

Concurrent Animations

Using self-contained concurrent animations in a UI class is an interesting exercise. You need to have the basic setup for an animation controller complete with a method of adding animation operations to a queue and removing completed animations. Typically, however, if you were building out animations on an application scale, you’d build a class that acted as the animation controller and may raise events for updating the elements as the animation progresses. In this example we’ll just build them straight in to our component because we want this to be entirely independent of the rest of the application architecture.

As this part focuses on concurrent animations, we’re not implementing a keyframe methodology for queuing. We’re using the queue purely to have multiple animations running together.

Defining The Queue

In Part 2 we added the following property to AnimatedCanvas:

animQueue As Dictionary

For this part, we’re going to make a slight modification to that property definition so that it will support multiple animation operations. We’re just going to turn it into an array:

animQueue() As Dictionary

Dictionary Changes

If you remember from last time we used the following definition for our Dictionary objects:

• Start Time
• Start Width
• End Width

In this part we’re going to further leverage Dictionary’s use of Variant to expand our functionality. While we previously used the following Dictionary structure for our operations:

Dictionary("s" : <StartTimeInMicroseconds>, "sw" :<StartWidth> , "ew" : <EndWidth>)

We’re now defining our animOp Dictionaries as:

Dictionary("op" : <OperationToAnimate>, "l" : <AnimationLength>, "t" : <StartTimeInMicroseconds>, "s" <StartValue>: , "e" : <EndValue>, "o" : <OptionalOlderAnimationOp>)

This allows us to create an animation operation for practically anything we can think of as long as we properly code for it in our animation Timer’s Action event handler method, and give it any length we desire rather than a common time for all operations.

Adding to the Queue

We’re going to add a new method to our AnimatedCanvas class called animQueue_Add that takes animOp As Dictionary for its sole parameter. This method will act as a basic out-of-the-loop controller when an animation is to be triggered and determine if this is a new animation operation or one that is already currently in the queue.

In this example I’ve setup for both a Cancel/Start type animation operation (which completely cancels the previous animation and begins a new one with the full animation time), and Continue type animation operation that preserves the original animation time within the new animation time, which is explained in more depth later.

Private Sub animQueue_Add(animOp as Dictionary)
   '// This method is part of our animation controller.
   '   It appends to or modifies our animation queue,
   '   which runs concurrent rather than consecutive
   '   operations.
   '   We first check to make sure that the new animation
   '   operation dictionary isn't nil.
   if IsNull(animOp) then Return

 '// We need to find out if we already have an operation
   '   in the queue for this, so we're going to store our
   '   index in a variable, which we'll get from our new
   '   anim_IndexOf method.
   dim foundIndex as Integer = animQueue_IndexOf(animOp.Value("op"))

 '// If the operation exists, overwrite it. Otherwise,
   '   append it to our queue so that the timer will
   '   pick it up on its next Action.
   if foundIndex >= 0 then

 '// We're also going to implement what I call Time 
 '   Preservation. I'm sure there another name that
 '   this is more commonly referred to as, but I
 '   just don't know it. When PreserveTimes = True
 '   then the animation operation overwrite will
 '   only use the remaining time of the oldest
 '   overriden animation operation. 
 if mPreserveTimes then

   '// Grab the oldest op in our override chain so
   '   we can perform the math necessary to calculate
   '   an appropriate time remainder.
   dim oldOp as Dictionary = animQueue_OldestOp(animQueue(foundIndex))

   if not IsNull( oldOp ) then
     '// Set our animation length to the remaining value.
     '   We're getting the assigned length of the animation
     '   and subtracted the difference between our two
     '   operation start times.
     animOp.Value("l") = animOp.Value("l") - ((animOp.Value("t").DoubleValue - oldOp.Value("t").DoubleValue) / 1000)

     '// Set oldOp to our "o" key in case of future overrides.
     animOp.Value("o") = oldOp
   end if
 end if 

'// Overwrite the operation.
 animQueue(foundIndex) = animOp
 else

 '// Add the operation to the queue.
 animQueue.Append(animOp)
 end if

 '// Make sure that our animation timer is enabled.
   animTimer.Mode = 2
 End Sub

As you can see, it’s not an incredibly complex method. We’re just checking our animQueue property to see an animation currently exists for this operation. If we find it, we replace it. If we don’t, we just add it to the tail-end of the queue. The final line, as in the previous version, kicks off our animation timer.

Checking Our Queue

The next new method we’re going to add is our method to check if the animation operation already exists in our queue. It’s a straightforward method where we compare the “op” value of items in the queue to a specified “op” value. If an operation exists for that action, we return the index within the queue, otherwise return -1.

Private Function animQueue_IndexOf(op as String) as Integer
   '// This method will check our queue for the
   '   operation specified in the "op" parameter.
   '   If it exists, we'll return the index. Otherwise
   '   we return -1 to denote that this is a new op.

 '// We're creating our variable before hand so
   '   we're not doing it in each iteration of the
   '   loop, which could slow things down a bit.
   dim currDict as Dictionary

 '// Likewise, we're creating a variable to store
   '   the maximum index of our animQueue array. If
   '   we did this, instead, in the For statement,
   '   the value would be recalculated each time
   '   unless something changed that I don't know about.
   dim intMax as Integer = animQueue.Ubound

 '// We're starting from the end, just in case
   '   the contents of the queue change in the middle,
   '   we're less likely to hit an exception.
   for intCycle as Integer = intMax DownTo 0
     '// We're still going to add exception handling
     '   just in case.
     Try
       currDict = animQueue(intCycle)
     Catch e as OutOfBoundsException
       Continue
     End Try

 '// If our current dictionary's "op" value
 '   matches the "op" value we're searching for
 '   then we'll return the index. if currDict.Value("op") = op then
   Return intCycle
 end if
 next

 '// No matching operation found, so we return -1.
   Return -1
 End Function

Time Preservation

One new feature we’re implementing is what I call animation time preservation. This shortens subsequent animations of the same operation to honor the original time until one of them is able to complete.

PreserveTimes property

For our animation time preservation, we’re adding a property to the class so we can turn this on and off at will. We’ll make it public and computed so we can add it to the inspector.

Private Property mPreserveTimes as Boolean = True

 Public Property PreserveTimes as Boolean
   Get
     Return mPreserveTimes
   End Get
   Set
     mPreserveTimes = value
   End Set
 End Property

Getting the Oldest Op

This all really relies on one method, animQueue_OldestOp which checks the “o” key of the specified animation operation to see if an older operation already exists. If it does, we’ll return it, otherwise return the operation passed in to the method. If you take a look at the changes to animQueue_Add above, you’ll see how we use this.

'// In this method we're just checking to see if
 '   there was a pre-existing operation when this
 '   one was created so that we can use its start
 '   time to shorten our new animation time.

 if IsNull(animOp) then Return Nil

 if animOp.HasKey("o") then
   dim oldOp as Dictionary = animOp.Value("o")
   Return oldOp
 end if

 Return animOp

Expanding the Height

For this example, to highlight multiple concurrent animations, I’ve also added the ability to animate the height in addition to the width. We’re basically just duplicating the existing properties for our width animation, but applying the values to height. This could be modified to use a Point or Rect to achieve the same effect, but this implementation is better for showing how the modifications we’ll be making to the animation Timer’s action actually work by breaking it down independently.

Properties

As with our Width animation, we need to track what our target expanded Height should be as well as the current state of that dimension. For Width we have an expandedWidth property, so we’ll add an expandedHeight property to match.

Private Property expandedHeight as Integer

In this version, we’re also renaming our old expanded property to isExpandedWidth:

Private Property isExpandedWidth as Boolean = True

And adding a new corresponding property for Height:

Private Property isExpandedHeight as Boolean = True

Finally, we need a property that keeps track of whether we’re currently animating our dimensions so that our subsequent clicks during a color-only animation properly toggle our isExpanded* properties. We could do this by searching the animOp array, but just storing it is probably a bit quicker.

Private Property isAnimatingDimensions as Boolean

There are better ways to implement tacking of these states, but for this example I want the verbosity.

MouseUp Changes

Since we’re now animating both Width and Height and implementing our rudimentary animation controller, we need to make some changes to our MouseUp event handler. Primarily we’re duplicating what we already do for Width to account for our new Height animation, and applying the changes to the properties we’ve already discussed. We check to see if we’re currently animating Width or Height before toggling their values to avoid issues in the animation timer’s Action handler.

Sub MouseUp(X As Integer, Y As Integer) Handles MouseUp
   '// Just in case we hit some strange scenario where
   '   the timer is disposed of. Should, theoretically,
   '   never happen in this case, but better safe than sorry.
   if IsNull(animTimer) then Return

 '// Now we're going to check for a currently running
   '   animation. If an animation operation of this type is
   '   already underway, all we need to do
   '   is switch the direction the animation is running.
   '   In a full animation controller, this would be handled
   '   internally by chaining or cancelling, most likely,
   '   but this works for our purposes.
   if animQueue_IndexOf("width") >= 0 then
     isExpandedWidth = not isExpandedWidth
   end if
   if animQueue_IndexOf("height") >= 0 then
     isExpandedHeight = not isExpandedHeight
   end if

 '// Here we create our dictionary objects containing
   '   everything our Timer's action event needs to do
   '   the work. The current time in Microseconds, which
   '   will be our start time, the start value, and the
   '   expected result value. This "10" is hard-coded
   '   just so that we can actually click on the canvas
   '   again to reverse the animation if it is fully
   '   collapsed. In most scenarios you wouldn't have
   '   a hard-coded value like this and you may even be
   '   triggering the animation from a different element
   '   altogether, so this value is purely for demonstration
   '   purposes in this project.
   '   animQueue_Add is a new method in this part of the
   '   series, and acts as an animation controller.
   animQueue_Add(new Dictionary("op" : "width", "l" : manimTime, "t" : Microseconds, "s" : Width, "e" : If(isExpandedWidth, 10, expandedWidth)))
   animQueue_Add(new Dictionary("op" : "height", "l" : manimTime, "t" : Microseconds, "s" : Height, "e" : If(isExpandedHeight, 10, expandedHeight)))
 
'// Finally, enable the timer to perform the animation.
   animTimer.Mode = 2
 
'// We've added this event, just in case there's
   '   something you want to trigger at the start of the
   '   animation.
   RaiseEvent BeforeAnimate
 End Sub

The New lerpColor

For Part 3, I wanted to add a little something extra before we roll in to Part 4, just to show how we can use linear interpolation for animating any number of different properties of our AnimatedCanvas class. That means we’re going to animate the background color of our class as well!

New Properties

To support our color animation in this specific example, we need a couple of new properties. These properties give us our start and end points for our color animation, and we’re going to add them to the inspector so that they can be changed when editing a Window or ContainerControl view.

• BackgroundColor represents our default background color, which I’ve set to default as red.
• BackgroundColorHover represents the color we want to see when the mouse is over the control, which defaults to blue.
• currentBackgroundColor represents the background color we want to actually apply, and is changed during the animation process.

Public Property BackgroundColor as Color
   Get
     Return mBackgroundColor
   End Get
   Set
     mBackgroundColor = value
   End Set
 End Property
 Public Property BackgroundColorHover as Color
   Get
     Return mBackgroundColorHover
   End Get
   Set
     mBackgroundColorHover = value
   End Set
 End Property

 Private Property mBackgroundColor as Color = &cff0000
 Private Property mBackgroundColorHover as Color = &c0000ff
 Private Property currentBackgroundColor as Color = &cff0000

The Paint Event

Our Paint event only needs one small modification to account for the changes we’re making. We previously used a static red color &cff0000 but we need to switch to using the currentBackgroundColor property to support the animation.

Sub Paint(g As Graphics, areas() As REALbasic.Rect) Handles Paint
   '// Fill the canvas with our current color.
   g.ForeColor = currentBackgroundColor
   g.FillRect(0, 0, g.Width, g.Height)
 End Sub

The MouseEnter Event

Our first step in animating the color for this example is to implement the MouseEnter event within our class. We’re simply creating a new Dictionary for the animation operation, populating that with our values to be used in the animation timer, then calling animQueue_Add.

Sub MouseEnter() Handles MouseEnter
   '// In this version, we're going to animate color change
   '   based on whether the mouse is over the control.
   '   So in MouseEnter we start animating from our
   '   currentBackgroundColor to our BackgroundColorHover.
   if me.Enabled then
     animQueue_Add(new Dictionary("op" : "color", "l" : 250, "t" : Microseconds, "s" : currentBackgroundColor, "e" : mBackgroundColorHover))
   end if
 End Sub

You’ll notice that, without the comments, this entire event handler is very short. Part of the goal as I build this functionality is always to make it as easy to implement as possible as I’ll likely use it in a number of different ways for each UI component. Sometimes I have the Dictionary values as parameters of the animQueue_Add method, but I want to show this in this way for this example.

If I’m implementing animation on an application-wide scale, I’ll typically use a custom class called AnimationOperation, with the values for the operation stored as properties and passed via the Constructormethod, then a call to add the resulting class instance to the queue for the AnimationController.

We also assign a static 250ms to color change animations, just to test our dynamic animation times, but you may typically want color change animations to be quicker than other animations in your application just so they stand out less.

The MouseExit Event

MouseExit, like MouseEnter, just creates and adds an animation operation dictionary with the values we want to use. In this case, we want to revert the color back to the default background color.

Sub MouseExit() Handles MouseExit
   '// In this version, we're going to animate color change
   '   based on whether the mouse is over the control.
   '   So in MouseExit we start animating from our
   '   currentBackgroundColor to our default BackgroundColor.
   if me.Enabled then
     animQueue_Add(new Dictionary("op" : "color", "l" : 250, "t" : Microseconds, "s" : currentBackgroundColor, "e" : mBackgroundColor))
   end if
 End Sub

The lerpColor Method

Now that we have our class setup out of the way, we can create our lerpColor method. In this example I’m simply applying linear interpolation to the Red, Green, and Blue values of the passed colors, but you could use any other subset of color properties that you want for your desired effect.

Private Function lerpColor(startColor as Color, endColor as Color, alphaValue as Double) as Color
   '// This method takes starting and ending color values
   '   and applies the lerp method for linear interpolation to
   '   the constituent Red, Green and Blue values to generate
   '   the new color value based on the animation's elapsed
   '   time.
   '   This could be switched from RGB for different effects,
   '   or you could just use Color.Alpha for making objects
   '   fade in or out.
   dim animStepR as Double = Lerp(startColor.Red, endColor.Red, alphaValue)
   dim animStepG as Double = Lerp(startColor.Green, endColor.Green, alphaValue)
   dim animStepB as Double = Lerp(startColor.Blue, endColor.Blue, alphaValue)

   Return RGB(animStepR, animStepG, animStepB)
 End Function

The Timer Action Handler

This is where we’re making the most changes in a single method. Not only are we implementing the animation controller methodology, but we’re also adding two new animation operations — height and color, in addition to the original width — so a lot of this will look different from Parts 1 & 2 in this series.

Private Sub animTimer_Action(sender as Timer)
   '// We're going to declare all of our variables outside of the
   '   loop so that we're not using precious time and resources
   '   in every iteration of the loop doing it.
   dim animOp as Dictionary
   dim animOpType as String
   dim animStepDouble as Double
   dim animStepColor as Color
   dim animStartTime, timePercent, animLength as Double
   dim animStartDouble, animEndDouble as Double
   dim animStartColor, animEndColor, newColor as Color

 '// Declare our loop maximum variable. Historically each
 '   iteration of the loop was known to traverse the array
 '   to get the maximum value if this wasn't stored in advance.
 '   I haven't tested this myself recently.
 dim intMax as Integer = animQueue.Ubound

 '// We start at Ubound and traverse the array in reverse because
 '   we'll be removing animations from the queue as they complete,
 '   and this is the best way to avoid OutOfBoundsExceptions.
 for intCycle as Integer = animQueue.Ubound DownTo 0

 '// Get our current operation dictionary from the queue. 
 animOp = animQueue(intCycle) 

'// Our first step is to make sure we actually have an animation 
'   to perform. 
if IsNull(animOp) then   
  '// For whatever reason, this entry has been cleared. We'll   
  '   just remove it and continue with the next operation.  
  animQueue.Remove(intCycle)   
  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.

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.

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.

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.

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.

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.

Sometimes, subclassing the available controls is the answer to add specific behaviors you need. But what happen when none of the controls offer what you need, whether visually or functionally? The answer is the Canvas class (for Desktop projects), WebCanvas class (for Web projects) and iOSCanvas class for iPhone and iPad devices. But how do you create your own UI controls from scratch? Read on to learn…

Before starting with this basic tutorial about customized UI controls, there is much more to take into consideration about providing the same behavior on your designed controls for multiplatform deployments. For example, in the case of desktop projects, we should add to the mix some things like HiDPI / Retina detection and adaptation on the fly (specially in the case of Windows deployment, with multiple dpi / Windows OS version combinations), and Dark Mode support for macOS. A well as other performance hints and differences when it’s about doing desktop multiplatform layouts; for example, when to set the Transparent or DoubleBuffer properties to True or not.

As the name implies, the Canvas control acts like a painting canvas and you can set its look for all the supported states based on the available events. This is done through the Paint Event and all the Graphic classes availables in the Framework. In fact, the Paint event provides as a parameter the graphical context (canvas height and width) you can paint on. In addition, you can combine these graphic classes (or completely substitute them) with any prepared Picture of your choice as the customize control background (ImageSet recommended, so it supports all the needed resolutions based on display dpi). In addition, and as you can do with the drawing via the Graphic class and functions, you can choose to use a different Picture as the control background based on several events, for example, when the mouse pointer is entering or exiting the control limits in a Desktop or Web app, or as response to the user clicking on it.

Canvas: A matter of Events

The Canvas class provides all the needed Events you probably would want to implement in order to react to the user interaction. These are listed and described in the available documentation online and as part of the Xojo IDE interactive Help.

While you can drag and drop a Canvas instance directly to your project layout window or view, implementing and writing the code associated with  any of the available Events, the recommended way to go is to create your own subclass taking as its parent the Canvas class. This way, you can implement and fine-tune every aspect that makes you control unique and, most importantly, re-use your customized UI controls as many times you want both in current and future projects (or even offer them to the Xojo community or sell them to other developers!).

As you probably already know, in an OOP programming language, subclassing is the method to get a specialized behavior from an existing Class: We get for free all the available properties, methods and events from the parent (and all its parent hierarchy), including also the code executed in the Paint event to truly paint or provide its look on screen; so we just need to implement the specific behavior and/or control drawing/painting we need over these.

This is also the way to go when you are in the inital stages of designing your own customized UI control: will you need to create even more specialized behaviors based on a “parent” or base customized control? Maybe variations on the behavior? In cases like these, you should define your UI control base class at the bare-minimum set of painting, behavior (events and methods) and properties that will be shared from all the future UI Controls inherited from your base/parent UI Control class. (i.e: more specialized or with behavior variations).

Creating a subclass in Xojo is truly simple: just drag and drop the Canvas icon from the Library to the Navigator (the leftmost column in the Xojo IDE), or choose Insert > Class from the Insert menu.

Points vs Pixels: HiDPI and Retina

Once you have added the new Class to your project, select it, go to the Inspector and set the name you want to use for your new Class (using a “company” or personal prefix it’s always a good idea to avoid collision with other existing or future classes in the Xojo Framework, or when using third party classes). Then, in the Super field of the Inspector Panel, type Canvas and confirm the entry. You’ll see how your class icon changes to the one that uniquely identifies Canvas based classes and instances. The most important thing: your new subclass will have all the properties, events and methods you may expect from a Canvas.

This will be the base class in our short tutorial for creating a customized button that will change its associated image (picture) when the mouse pointer is inside the button area, outside the button bounds or when the user click on the control. In the last case, the button will change both the image and its internal state represented by a property as a Boolean value (named Status).

As our customized UI control will not draw itself via the Paint event, we will need to design the images so these precisely fit in the size we want to use for our button. In this example a size of 32 x 32 points.

In general, when designing images to use in our Xojo projects we need to change our mindset from thinking in pixels to points. That’s because Xojo apps do support HiDPI on Windows/Linux and Retina on macOS; that is: hi-def graphics. Thus, it’s important to use a design tool that simplifies the process. Personally, I use the vectorial app Sktech on macOS because it automates the 2x creation of the final images. (Remember that HiDPI/Retina is enabled by default in the Building Settings on every new Desktop project.)

How do you support HiDPI/Retina if you want to draw the control look on the fly? Avoid the use of pixels in your calculations or when setting the values of the existing Graphic class properties, and use Points instead. If you really need to access the Pixels values underneath, then you can resort to the RGBSurface class (if available) and make use of the ScaleFactorChanged event available on the Canvas class. This way, your class will be notified on every change between displays with or withour Retina/HiDPI support.

Good rule of thumb: do all your control drawing inside the Paint event! And, when you need to update or redraw it (maybe as consequence of some change in the app behavior, or from the change made in other UI control), invoke the method Invalidate instead of Refresh. In general, this will speed up the drawing and, thus, the main app performance.

If you use an existing Event… Define the Event again

As our customized class makes use of the Open, MouseEnter, MouseExit and MouseDown Events, we need to make sure we define these events again to the class, so they are also available for the developer using our canvas-based UI subclass. After all, it’s very probable he needs or wants to add extra code on top of ours! This is something we can do choosing Add to "class_name" > Event definition when our subclass icon is selected in the Navigation Browser.

Thus, once we have created the same events (using the same parameters and returning the same kind of Type values as the original ones), we need to make sure we call them; usually as the last line of code for the already used Event. For example, this is the code for our implementation of the MouseDown event in our Canvas subclass:

me.Backdrop = if(me.Status = false, ShellRunSelected, ShellRun)
me.Status = not me.Status
return RaiseEvent MouseDown(X, Y)

Note how, in this case, our implementation of the MouseDown event returns the value returned by the consumer of our subclass instances, called with the RaiseEvent statement. Just remember that returning the True value from this event means that such events will not be propagated further along the Events Chain.

Putting it all Together

With this information at hand, and the basic concepts explained, this video (in Spanish) shows how you can join all the needed pieces: pictures, events, definition of already consumed events by the subclass; creating a new very basic control from scratch. Obviously, from this point on, you can find in the available documentation all the information needed to create more complex UI controls based on the Canvas class (WebCanvas or iOSCanvas). The possibilities are limitless!

Other useful topics:

• User Guide: Desktop Canvas
• Canvas, Graphics classes
• User Guide: iOS Canvas
• User Guide: Web Canvas

Javier Rodri­guez 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

When I got my first modem I went online with Genie and Delphi and uploaded JumpSTART as freeware. Even though it was freeware, I got a few checks in the mail from people that liked it.

I was reminded of JumpSTART when I saw my dock getting crowed. I thought replicating JumpSTART in Xojo would be a good project for week 8 of #JustCode. Though let’s just call it JumpStart this time around.

This is what JumpSTART looked like on monochrome 640×480 screen:

JumpStart in Xojo is greatly simplified and looks like this:

The Xojo version automatically saves and loads the apps you’ve added so there was no need for separate Load/Save, Re-Read buttons. Technically they don’t have to be apps as even a document file can be launched as well.

You can right-click on an app button after you’ve added it to Rename, Change or Clear it so that also removed the need for some UI controls. And you just click on an empty button to add an app to it. When you click on a button with an app assigned, the app is launched and JumpStart hides itself.

This Xojo app demonstrates the use of a Canvas-based button, ContainerControls added dynamically to a window, and saving/loading JSON. The Canvas-based button will let me tweak the display, colors and maybe display an icon there.

You can download the project or check it out on GitLab.

As an added code treat, I’ve posted the original JumpSTart Pascal code to GitHub. FWIW, the original Pascal source is just over 1300 lines of code. The Xojo version is about 180.

Add your #JustCode project to the week 8 forum conversation.

Download and check out earlier projects:

• Week 7: Pitch Tracker
• Week 6: Bubble Popper
• Week 5: Math Quiz
• Week 4: Mini-Golf ScoreKeeper
• Week 3: Dogs Up!
• Week 2: Password Generator
• Week 1: Color Picker

Along the way, we also will see how the Xojo IDE simplifies making subclass properties available from the Inspector Panel, so when using their instances we can set some attributes as the background color, pen size or border color in a more convenient way.

As usual, the first step to create a new subclass is adding a new class item to the Desktop project (Insert > Class). With the new class item selected, change its name to something descriptive. For this example we will use MyImageWell. The most important thing here is setting Canvas as its Super attribute. That means that the subclass will be based on the Canvas class, inheriting all its properties, Events and Methods so they will also be available for the subclass.

One of these inherited Events is Open, and we will implement it using the Event Handler option (click the + button in the toolbar to access the dropdown menu) in order to inform the class that we want to accept the dropped JPEG files. This is done with the following line of code in the Open Event Handler:

Me.AcceptFileDrop("img/jpeg")

Obviously, we can extend this support to accept other Xojo compatible graphical formats. For that, we would add a new File Type Set to the project, using it as the filter in the previous line of code.

Once we inform the class that we accept this feature, the next step is implementing the DropObject Event Handler that fires once this action is detected inside the limits of the control. The code we need to write for this Event Handler will test that the obj parameter passed along contains a valid FolderItem and, in that case, we will load such file as a new Picture object, assigning it to a property of the same Type. The code for the event is:

If obj.FolderItemAvailable Then
  image = Picture.Open(obj.FolderItem)
  Invalidate
End If

Don’t forget to add the Image computed property to the Class using Insert > Computed Property while the MyImageWell item is still selected, and using these values:

• Name: Image
• Type: Picture
• Scope: Public

As you can see, the amount of code we need to load the file as a Picture object and to assign it to the class property is minimal! Why do we use the Invalidate method call afterwards? Well, this is responsible for informing the operating system to redraw the instance when it has a chance. And when this happens it will fire the third and last Event we need to implement: Paint. Here is where we can instruct any Canvas based control how to draw itself through the graphical context represented by the g parameter passed along the Event.

Painting the control

Once we’ve added the Paint Event to the class and before writing the code responible of painting the dropped image inside its limits, we need to add three additional computed properties. We will use them to set some attributes like the color we want to use to paint the control background, the border color and even the width of the border:

• BackGroundColor As Color = &cdddddd
• BorderColor As Color = &c000000
• PenSize as Integer = 2

Add to the Setter method on every computed property the sentence me.invalidate; so every time we assign a new value to them… the control will be redrawn using the new value (background color, border color, pen size or even a new assigned picture).

The last step is writing the code responsible for drawing the control itself: filling the background with the set color, then drawing proportionally (and centered) the loaded picture pointed by the Image property, and finally drawing the border with the width and color specified. All of this is what we can do using the following snippet of code:

// We fill the control background using the set color
g.DrawingColor = BackgroundColor
g.FillRectangle(0,0,g.Width,g.Height)

// If we have a valid image object, then we draw it centered and scaled (if necessary)
If image <> Nil Then 
  Var Height, Width As Integer
  Var sourcey, sourcex As Integer = 0 
  If image.Height > image.Width Then
    Height = Me.Height
    Width = (Me.Height * image.Width) / image.Height
    sourcey = (Me.Width - Width) / 2
  Else
    Width = Me.Width
    Height = (Me.Width * image.Height) / image.Width
    sourcex = (Me.Height - Height) / 2
  End If

  // This is the line that actually draws a picture inside the graphic context of our instance
  g.DrawPicture(image,sourcey,sourcex,Width,Height,0,0,image.Width,image.Height)
End If

// We draw the control border
g.PenSize = me.PenSize
g.DrawingColor = BorderColor

g.DrawRectangle(0,0,Me.Width,Me.Height)

As you can see, the code needed for this is also very simple!

Make the properties visible from the Inspector Panel

While we are on it, we can use the Inspector Behavior feature to make our specific properties visible through the Inspector Panel. This way, when we add new instances from the subclass to the layout of any window, we will be able to easily set their values directly from the Inspector Panel. With the MyImageWell item still selected in the Project Browser, use the contextual menu to select the Inspector Behavior option to access the following Window:

Here you will see all the Class properties, those common to all Canvas derived subclasses and also the ones added for us and that are specific to our class. You can find these properties listed under the Behavior section. To make them visible in the Inspector Panel we just need to check their associated checkboxes; and even modify their default values editing the associated cell if we want to.

Now, we just need to drag and drop the MyImageWell item from the Project Browser into any Window Design Layout in order to add new instances! Once we run the example project, we will see how the controls react to displaying any JPEG picture dropped on it.

If you want, you can investigate deeper into the methods provided by the Graphics class in order to make the control more glittery or more sophisticated.

You can watch this video (en español) to see this in action:

Javier Rodri­guez 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

Set Transparent Property for Controls to False

UI controls now have a Transparent property which determines whether the control is transparent on Microsoft Windows. The default is False for new controls added to layouts. For existing projects and controls, this property is set to True for maximum compatibility.
However, controls that have Transparent set to True require more drawing, use more memory and are thus slower. For best results you should set the Transparent property to False for as many controls as possible.

Consider ContainerControl DoubleBuffer Property

Set this property to True to reduce flicker on Microsoft Windows when the ContainerControl is scrolled. Otherwise you can leave this to False.

Avoid Overlapping Controls

The easiest thing you can do to prevent flickering is to not overlap any controls. Overlapped controls result in more requests to redraw the controls which can result in flickering and slower performance.

Use a Canvas

For best results, display any graphics using the Paint event of a Canvas control. Stay away from using the Window Backdrop property, the Window Paint event, the Canvas.Backdrop property or the ImageWell control. Although those techniques work fine in certain situations, they often lead to flickering in more complex window layouts.

On the Canvas, the first thing you want to do is turn off the EraseBackground property. The EraseBackground property prevents the Canvas from being erased (and showing as a white rectangle) before it is redrawn, which is another common source of flicker. (Deprecated in Xojo 2019r2) You should also check your usage of the DoubleBuffer property. In many cases you will find you can leave it set to off (False) for best performance.

With these tweaks, you can do all your drawing in the Paint event using the supplied graphics object parameter: g.

Note: Do not do any drawing directly to the Canvas.Graphics property. This ability was deprecated in 2011 and is strongly discouraged. Drawing in this manner will likely increase flickering and will definitely slow down graphics updates.

You can have separate methods that update the graphics, but they need to be called from the Paint event with the graphics object supplied to the methods as a parameter. Another technique is to have a Picture property that you use to draw you graphics to and then in the Paint event handler you draw the Picture to the Canvas to display it.

When you want the Canvas to update itself, redrawing any changes to your graphics, you call the Invalidate method:

Canvas1.Invalidate(False)

You can also call the Refresh method:

Canvas1.Refresh(False)

The difference is that Invalidate tells the Canvas to update itself when it gets a redraw request from the operating system. The Refresh method tells the Canvas to update itself immediately. Normally you want to use Invalidate as it results in fewer draw requests, improving performance and reducing flicker.

To reduce flicker, both of the above commands pass False for the EraseBackground parameter (which defaults to True) so that the Canvas is not erased before its updated contents are drawn.

Remove or Update Older Code

If you previously had specialized code in your app to help minimize Windows flicker, you should consider removing it as the code may prove to be unnecessary and cause worse performance.

A Note About Virtual Machines

Many people run Windows in Virtual Machines. If you do so you’ll want to ensure that you have the best performance possible. Xojo apps use Direct2D for all screen drawing and not all VM software has properly accelerated graphics drivers for this.

In particular, VMware Fusion has rather poor performance when “Accelerate 3D Graphics” is enabled in the Display preferences. For best performance you should make sure that option is turned off.

Alternatively, Parallels Desktop and VirtualBox both seem to have better graphics performance with Direct2D and Xojo apps.

For more information:

• Windows UI Guidelines

*Minor update re: deprecation 3/2021

The first thing that went through my mind was how exactly is such an important function of a state emergency management system triggered so easily that it could be done by accident? Did a radar system show an incoming missile that was later discovered to be a mistake? No. As the Washington Post reported, the user interface for the system has a drop down menu with two items: Test Missile Alert and Missile Alert. The facts that these two options are so similarly named and that there is no confirmation dialogue for such an important command is at a minimum bad user interface design.

If I want do something as relatively innocuous as erasing all the data from my iPhone, I have to first find the feature that does this buried two levels deep in the Settings app where it’s clearly titled, “Erase All Contents and Settings.” Tapping it displays a dialog box asking me if I want to Backup Then Erase or just go ahead and Erase Now. If memory serves from the last time I did this, choosing Erase Now then reconfirms that I truly do want to erase all the contents and settings on my iPhone. That’s a lot of steps to accomplish a task that only affects one person: me. However, considering the magnitude of the result, it makes good sense that the user interface doesn’t make this very easy to do and actual makes sure you are deliberately trying to erase your phone.

Hawaii’s emergency management system does none of this. There apparently are just two menu items, one next to the other and once chosen, the computer immediately completes the task without confirmation. That’s just astonishing. What’s even worse, however, than the poor interface design on the part of whomever designed it, is that at a minimum (a) someone had to accept this poor interface design, (b) others had to use it without complaint that it could potentially cause the very situation it has caused.

The Chairman of the FCC wants an an expensive investigation. Let’s please not spend $1 million or more of the taxpayer’s hard-earned money on a $100 fix. First, these two menu items should be reduced to a single menu item entitled, “Missile Alert…” The ellipsis tells the user that before this item performs its function, a dialog will be displayed to confirm it. The dialog that appears should be on that requires deliberate actions by the user to initiate a true warning to the population of Hawaii:

In the above example dialog box notice that in order to initiate a real warning, the user will not only have to uncheck the “Internal Test Only” checkbox but also have to deliberately click the Proceed button as the Cancel button is the default.

After taking those two deliberate actions, the user is then presented with a second dialog box to confirm that requires again clicking the Proceed button, another deliberate action.

With this simple, 5 minute fix, it would be nearly impossible for someone to accidentally send out a warning when they meant to only perform an internal test.

Not all user interfaces have functions with such wide-reaching results. However, user interface guidelines for many years now have said that an action that cannot be undone should be confirmed. That’s a simple rule that all of us that design user interfaces would do well to remember.

Here are 8 proven tips to help ensure you create a user interface that your users will love.

1. Limit choices.
Don’t provide an overwhelming number of options or preferences for your users. Too many choices can be intimidating and confusing and can make people not enjoy using your app. Your job is to design the software, which means choosing what it should do. Don’t take the easy way out and provide loads of options for your users all at one time.

2. Be familiar.
Sometimes you may need to implement an entirely new user interface metaphor in order to design your app. But typically this is unnecessary. Though it can be fun creating new and snazzy UI layouts, your users will likely not appreciate them much. Why? Because they won’t understand them or won’t know how to use them. A unique UI design isn’t always practical – stick to what people are familiar with.

3. Be consistent.
Your app should be consistent within itself. Don’t use UI controls in different ways on different screens because that is just confusing. For example, don’t use buttons on one screen to indicate actions, but then use link text on another screen to indicate the same action.

4. Put the user in charge.
Let the user feel like they are controlling the software. This means don’t force them down a single path to solve something. Let them try things and make mistakes. Have an undo feature so that they can easily fix their mistakes.

5. People can’t.
Don’t spend time writing long text for the user as they likely won’t read it. Keep the language short and simple. Make it easy for people to enter text because they are not good at it. If the user has to enter lots of text, give them lots of room, enable a spell checker and use a larger font to make it easier for them to read the text.

Make your UI targets easy to find and use because people can’t control the mouse, trackpad or even their finger for touch devices. And lastly, users likely won’t remember how they did something the last time, so make it easy to figure out.

6. Design first.
Have a design process – it doesn’t need to be anything complex. Sketching designs on paper or a whiteboard is a great way to get a feel for things. Software to mockup UI designs (such as Balsamiq) can also be quite useful. You can also use development tools like Xojo to mockup UI designs, but be careful not to make your mockup too functional or the users might think it is nearly complete!

7. Time is relative.
Users perceive time differently than you might expect. For example, they typically hate waiting for tasks to complete. But if you make it seem like they are not waiting, they often don’t notice how long a task takes. For example, if your main window takes 5 seconds to appear, that will irritate your users. If you instead display the window immediately with a loading indicator, users are far less likely to notice the delay. In general, users more easily notice delays when the UI becomes unresponsive so try to minimize that.

Also keep in mind that features you have spent a large amount of time creating may only be used for a very short period of time. Don’t let yourself become comfortable with a difficult design because you use it frequently.

8. Help out.
Your app should provide assistance to your users. Tips and guides are a great way to gently remind users how to use your software. It’s also a great idea to provide default data for the first launch of your app so that users can see how it is actually used in the real world. Another strategy is to prevent the user from making a mistake in the first place. Disable things when they cannot be used and enable them when they can be used.

For more tips like these, I recommend User Interface Design for Programmers by Joel Spolsky.

If you want to try your next app in Xojo, download it free anytime.

A quick glance at the iOS UIApplication doc page shows that there is a property called applicationIconBadgeNumber that is the “number currently set as the badge of the app icon in Springboard.”

So how can this be used with Xojo? Using just five Declare commands, which I’ll cover step-by-step.

At first glance, it seems like it is as simple as using the property to set the badge number. Well, it used to be that simple in iOS 7 and earlier. But starting with iOS 8, you are now required to first get the user’s permission by calling the registerUserNotificationSettings method on UIApplication. Looking at that page, you’ll see that to register for a notification, you have to supply an instance of UIUserNotificationSettings that is configured for badge icon permission. So I’m going to start there.

But before jumping right in, there is a helper function I need in order to get references to iOS classes: NSClassFromString. So this is the first Declare and it looks like this:

Declare Function NSClassFromString Lib "Foundation" (name As CFStringRef) As Ptr

Now I can get a reference to UIUserNotificationSettings by calling this method:

Dim notificationSettings As Ptr = NSClassFromString("UIUserNotificationSettings")

This class has a shared method (settingsForTypes:categories:) that can be called to get an instance configured for use with registerUserNotificationSettings. Its Declare (our second) looks like this:

Declare Function settings Lib "UIKit" Selector "settingsForTypes:categories:" _
  (obj As Ptr, allowedTypes As Integer, actionSettings As Ptr) As Ptr

Looking at that method declaration, note the trailing colon in the name. This is necessary because the method takes parameters. Do not forget to include it or the method will not be found and your app will crash when you run it.

The first parameter (obj As Ptr) is for you to pass in the reference to the UIUserNotificationSettings class. The second parameter (allowedTypes As Integer) is the type of notification you want to use, and the third parameter (actionSettings As Ptr) is for groups of notifications, but I won’t be using that.

You can now call the method by supplying the reference to the class we have stored in notificationSettings. For the allowedTypes, the value “1” indicates a badge icon notification:

Dim settingsObject As Ptr = settings(notificationSettings, 1, Nil)

This gives me an instance of UIUserNotificationSettings that I can then pass to the registerUserNotificationSettings method. In order to call that method I now need a reference to the UIApplication instance for the running app. To get that the third Declare is needed:

Declare Function sharedApplication Lib "UIKit" Selector "sharedApplication" (obj As Ptr) As Ptr

The Declare to call that method looks like this:

Dim sharedApp As Ptr = sharedApplication(NSClassFromString("UIApplication"))

This is the fourth declare to the registerUserNotificationSettings method:

Declare Sub registerUserNotificationSettings Lib "UIKit" Selector "registerUserNotificationSettings:" _
  (obj As Ptr, settings As Ptr)

You call this method by passing in the reference to the shared app and the settings:

registerUserNotificationSettings(sharedApp, settingsObject)

Lastly, we arrive at the fifth and final declare which calls the applicationIconBadgeNumber property that was the first thing I identified. Its Declare looks like this:

Declare Sub applicationIconBadgeNumber Lib "UIKit" Selector "setApplicationIconBadgeNumber:" _
  (id As Ptr, value As Integer)

One thing to note is that because this is a property, the name has to be adjusted a bit. Rather than using “applicationIconBadgeNumber”, you have to use the name of the “setter”, which prefixes “set” and tweaks the casing. So the name instead is “setApplicationIconBadgeNumber:”. Remember the trailing colon since a parameter is passed!

And don’t forget that these Selector names are all case-sensitive!

And finally, you call the method like this to set the number 42 on the badge:

applicationIconBadgeNumber(sharedApp, 42)

You’ll have to press home to get back to Springboard so you can see the app icon with the badge, of course!

You can download the project that adds this as an extension method to iOSApplication so you can call it like this:

App.SetBadge(42)

And you are all set now!

PushTo

The most common way to display new views is to use the PushTo method.

With this method, the new view appears on top of the current view and a “back” button is displayed in the Navigation Bar (if it is enabled) to close this new view so that the original view is displayed.

Download the PushTo example to see how this works.

Refer to Views in the User Guide to learn more about PushTo.

Modal View

A modal view is a view that appears over a view, and is a bit more limited. The user cannot display a new view or go back to the original view until the modal view is closed. To display a modal view in your Xojo iOS apps, you have to use a Declare.

Download the ModalView example to see how it works.

Refer to Views in the User Guide to learn more about Modal View.

Change Current Screen

There are times where you may want to reset the view hierarchy so that the “back” feature is not available. An example of this might be an initial login screen displayed by your app. After the user logs in, you will likely want your true main view to replace the login view, but not allow the use of the “back” feature to go back to the login view.

A feature (iOSApplication.CurrentScreen) added to Xojo in 2016r1 allows you to do that by changing the current screen of the app to point to your new view.

Download the Navigation example to see how it works.

Refer to Views in the User Guide to learn more about this.

Splits on iPad

An iPad can be set up with a split view that allows two views to be displayed on the screen at the same time. The view on the left is the “master” and the view on the right is the “detail”. If you’ve used Mail on iOS then you’re familiar with this type of layout.

When you have a split view set up, you can access the base view for the master and detail areas by using the ParentSplitView property of any of the views. ParentSplitVIew is an iOSSplitView with its own properties (Master and Detail) that give you access to the content of the split area.

Download the SplitVIew example to see how it works.

These tips should help you provide great navigation for your iOS apps. If you have an iOS app in the App Store, be sure to tell everyone in the Xojo-made iOS apps in the App Store conversation of the forum and tweet us the link @xojo!

We’ve got lots of resources to get your iOS app started, check them out or click below to learn about building 64bit iOS apps for the App Store.

My Raspberry Pi 2 sits on my desk next to one of my speakers. It’s not hooked up to any display. I use a combination of SSH, SFTP and VNC when I need to work with it.

To connect to the Pi, I just need its IP address, which currently is 10.0.1.11. I leave the Pi on all the time, but if I reboot it then the IP address could change since I have not set it up with a fixed IP address. To identify the IP address, I run the utility LanScan (free on the Mac App Store) which shows me all the IP addresses of everything on my local network. The Raspberry Pi is clearly identified.

I can then connect to the Pi via ssh:

ssh pi@10.0.1.11

I’m prompted for the password, which I’ve left at the default (“raspberry”).

If I am only going to be running Xojo console apps, then this is all I need. You really only need to set up VNC if you want to access the Desktop so you can run Xojo desktop apps (or use the Pi UI to run other desktop apps).

Personally I do like using the Pi desktop, so I now need to start the VNC server, which I have previously installed. If you need to install it, easy VNC installation steps are at the official Raspberry Pi site.

At the ssh terminal, I start VNC using its defaults with this command:

vncserver

After typing this command, I’m back at the terminal prompt. Use the “exit” command to disconnect from the ssh connection.

Now I can connect to the Pi using a VNC client. I’m going to use the client that is built into OS X since it is always available and reasonably fast. In Finder, select Go->Connect to Server from the menu. In the window, enter the address and port for the VNC server and click Connect:

vnc://10.0.1.11:5901

You’ll again be prompted for your password. This is the password you set up when you installed TightVNC, not the Raspberry Pi password.

When everything connects you’ll get a window displaying the Raspberry Pi desktop, shown here running the XojoNotes example app:

But how do you get apps to the Pi so you can run them? I use SFTP. There are many SFTP tools available. I primarily use ForkLift and ExpanDrive, but other apps have also been recommended on the Xojo forum. Regardless of the tool you use, create a new SFTP connection and enter the same credentials you used to connect via ssh.

You’ll now have access to the file system on the Pi and you can drag files from your computer to the Pi’s file system, which will copy them across your network to the Pi. With ExpanDrive, I get a drive mounted to the Finder that is connected to the Pi, making access to the Pi always available.

With your free Xojo Pi license you can develop and build desktop and console Pi apps. Download today and get the latest release!

As their tagline says, it’s a “messaging app for teams”. It’s also free to use (with a paid version also available) so it is easy for anyone to try.

Slack is pretty slick, making it incredibly easy to text chat with others on your team. I think it is much better than trying to use tools like iMessage, AIM or Skype for text chatting. With slack you can have multiple “channels” to keep converstations focused and attach files/images to a post. Slack has also been utterly reliable for me, unlike issues I’ve run into with iMessage and AIM.

To be fair, Slack doesn’t really offer anything all that new with regards to text chatting, but it integrates it all in a clean UI that is easily accessible by anyone.

Slack also has a web api, which of course works with Xojo. Back in September I did a webinar on a Slack library It shows you how to allow your Xojo apps to post messages to a Slack channel and to get other information about your Slack teams and channels. This library is included in with the Xojo 2015 Release 3.1 examples (Communication/Web Services/Slack).

And now this Slack library is available on GitHub to make it easier to accept community contributions.

https://github.com/xojo/slack

To use the Slack library, you create an AuthToken for a Slack team account at the Slack API site (be sure to log in first).

Then you drag Slack.Connector onto your layout and call the Slack.Connector.SetAuthToken method with your token. The Open event handler is often a good place for this:

SlackConnector.SetAuthToken("AFERE34323FJDK5") ' this is not an actual token

Once authorized, you can call Connector methods to post message or get information about the Slack team and channels, with results returned to event handlers on Connector.

Refer to the ReadMe on the GitHub page for more information.

I hope you find it useful!

In the Beginning

In 1984 when the original Macintosh was introduced, as advanced as its interface was at the time, its graphics capabilities were extremely weak, at least by today’s standards. It could only manage a black and white, 1 bit interface.

Almost 2 years later, Microsoft Windows 1.0 was released and it added color but was laboring under many of the same technological restrictions.

The whole idea behind the GUI was to make the interface use elements that were similar to things the user already understood. For example, pushbuttons already existed in the real world. The idea of a window as a place to view things was an analogy but it connected the user with something they already understood.

Over time, the graphics capabilities of personal computers became stronger. Processors, memory and displays all became better, faster and less expensive. Consider Windows 95 (released in 1995) and Mac OS 8 (released in 1997):

Both took a big leap forward. With better graphics and color, the user interface felt more realistic. I know that may be hard to imagine if you never used these versions of Mac OS or Windows but remember and consider what users had been using up to this point. Over time, user interfaces became more skeuomorphic, though this was certainly true more for OS X than it was for Windows. Apple made the Address Book and Calendar   look somewhat like their real world counterparts.

The Mobile User Experience

When the iPhone came along, it took the mobile interface to an entirely new level. One of the things Apple realized is that when using an interface on a much smaller screen, you have to simplify. The busier the user interface, the harder it is to use. This meant fewer lines and simpler graphics. It also meant being more choosy about the functions apps would perform because of the limited space available in such a small screen (among other things). The simpler user interface allowed the user to focus.

Android has gone through the same transition over the years, from Cupcake yo KitKat.

The Changing Desktop

In some ways, this didn’t start with iPhone and Android. For example, for years many graphics and photo-editing applications have used a dark theme so that the application’s interface fades into the background helping the user focus on their content.

Microsoft Windows 8 offered a radically different user interface. While the change has certainly been contraversial, it’s clearly meant to simplify the desktop user experience. Microsoft’s motivation was to provide a single user experience for desktop and mobile. It’s clear now that this was not a complete success and it seems they are going to make a new attempt with Windows 9.

Now Apple, with the upcoming release of OS X 10.10 Yosemite, is simplifying the user interface as well. You can click to enlarge the picture below.

But in Apple’s case, I believe the motivation is more about simplifying for two reasons:

1) The simpler the visual aspects are, the more the user can focus on their content. Apple is not removing functionality. The change is more about how they render the user interface itself. There are fewer lines and fewer colors.

2) While Apple firmly (and rightly, IMHO) believes that you can’t have the exact same user experience on a mobile device as a desktop, there are visual cues that can be shared which make it easier for the user to switch between devices- icons for sharing, etc. Switching between desktop and mobile devices is a behavior that is very common and only becoming more so.

Coming Full Circle

In some ways we have come full circle. We started with simple user interfaces that were skeuomorphic and became even more so over time. At the time, they had to be because the user needed to relate the user interface to the real world. The Graphical User Interface has been around long enough now that it no longer needs to be skeuomorphic. Today, user interfaces need to make sense to users who already have experience with a graphical user interface. The simplified user interface makes the user experience more friendly and allows the user to stay more focused on what they are trying to accomplish. In subtle ways it increases productivity which, after all, is why we use computing devices in the first place.

The new UI in iOS 7 is the most controversial thing about it by far. I’ll admit that when I first saw it, I thought they were changing it just to change it. I thought they hadn’t put enough thought into the reasons why or they were just bending to the pressure of change for change’s sake. In my role at Xojo, I think at a lot about UI design. Before long, I realized that of course Apple put a lot of thought into it. That’s what Apple does. It’s their culture. So why were they going with this new, simpler, non-skeumorphic design?

Then it hit me. First, skeumorphic makes less and less sense. When I was a kid, phones had handsets like one in the icon for the Phone app. Calenders were something you purchased and hung on your wall. Your camera was something that you used to take pictures and that’s it. It did nothing else. Skeumorphic makes sense when you need to connect a real world object with its digital counterpart. But the younger you are, the less these skeumorphic designs make sense.

My daughter is 12 years old and has an iPhone. We have never had a home phone that she can remember. Her iPhone is of course her phone but it’s also her calendar, her camera, her notepad and her TV. It doesn’t replace these things. It is these things. Over time, fewer and fewer people will recognize the skeumorphic designs because those real world objects are not part of their world. Thus the value of skeumorphic design decreases.

The other day, I showed my daughter and my 10 year old son the new iOS 7 user interface (from Apple’s website linked to earlier in this post). I asked each of them if they preferred the new look, the one they currently had (iOS 6) or thought that one wasn’t better than the other. They both preferred iOS 7. When I asked them why (independently so they would not bias each other), they both said the same thing, “Because it’s cooler.” I have no doubt that I would get a similar response from most iOS users 25 and younger.

There are no doubt many important reasons Apple identified for refreshing the iOS user interface. We will probably never know them all. But “cool” is important. Cool is especially important to young people who buy a lot of iOS devices and their brand loyalty to the Apple ecosystem is therefore important to Apple.