This guide walks you through the complete process of signing EXE and DLL files on Windows with Azure Artifact Signing.

Here’s the shape of it, so you know what you’re signing up for:

• One-time setup (Steps 1–9): Azure account, portal clicks, and identity validation. This is the slow part. Budget a day to a week for the identity check to clear.
• Every build (Step 10): one script that signs your exe and DLLs in seconds.

If you’ve already done the setup, skip straight to Step 10.

Why I Picked Azure Artifact Signing

• $9.99/mo for up to 5,000 signatures (Basic tier), with no USB hardware token to manage.
• Fully managed. Microsoft rotates the certificates daily behind the scenes. You never see or store a private key.
• Identity-based publisher reputation. Public Trust signing ties the signature to your validated identity instead of a certificate you manage yourself. SmartScreen warnings can still appear for first-time or low-volume downloads; signing does not guarantee they will disappear immediately.

A note on names: this service was called “Azure Trusted Signing” until recently. Same thing, new name. If you see “Trusted Signing” in older docs or screenshots, it’s the same service.

Prerequisites

1. A Microsoft account (you get one when you sign up with Azure).
2. A paid Azure subscription.  This is the #1 early blocker: Artifact Signing does not work on free/trial/sponsored subscriptions. Upgrade to pay-as-you-go first (Cost Management + Billing → your subscription → upgrade) – https://azure.microsoft.com/en-us/products/artifact-signing.

Step 1 — Register the resource provider

Quick orientation first: an Azure subscription is the billing container for everything you create. Azure charges your services to it, and it also defines where those resources live and who can access them. When you signed up, Azure created one for you automatically (often with a forgettable default name like “Azure subscription 1”).

A separate subscription is optional. If you want clean billing and access boundaries for signing, create or dedicate one; otherwise, use your existing paid subscription and keep the signing resources in a dedicated resource group.

Then:

1. Portal → Subscriptions → the subscription you chose.
2. Left menu → Settings → Resource providers.
3. Find Microsoft.CodeSigning → click the … → Register. Wait for Registered.

Step 2 — Create the Artifact Signing account

Keep the signing resources together in the same subscription and a dedicated resource group.

1. Portal search → Artifact Signing Accounts → Create.
2. Subscription: the paid subscription you chose. Resource group: new, e.g. rg-artifact-signing.
3. Account name: 3–24 alphanumeric, starts with a letter, globally unique (no consecutive hyphens). e.g. xojoappsigning.
4. Region: pick one you’ll remember; it determines your signing endpoint.
5. Pricing: Basic unless you’ll exceed 5,000 signs/month.
6. Create, then note the Account URI on the overview page. It follows the pattern https://<region-code>.codesigning.azure.net/.

Step 3 — Assign the Identity Verifier role

You need this before the identity-validation button becomes clickable.

1. From your Artifact Signing account, left menu → Access control (IAM) → Add role assignment.
2. Role: Artifact Signing Identity Verifier (use the search field) → assign to your own user account.

Step 4 — Identity validation (the real gate)

From your Artifact Signing account (the one you created in Step 2), go to the left menu → Objects → Identity validations → New Identity → Public.

Public is what you want for normal app signing (it’s what SmartScreen cares about).

Fill in your legal business name, website, emails, business identifier (tax ID / DUNS), and address. Two gotchas that bite everyone:

• The secondary email must be on the same domain as the primary.
• Individual developers: the form pulls from your Azure billing account, and its name/address must exactly match your ID.

What happens next: status goes In Progress → Action Required (this is the point when you may have to wait a few hours to days… In my case, it took only an hour). You’ll be routed through a third-party verifier (AU10TIX). You upload a government ID and a selfie from your phone, then add the resulting Verified ID to Microsoft Authenticator and share it back (another hour or so).

Timeline: officially 1–20 business days; in practice often hours to a few days. If it stalls, re-submit with a different identifier (tax ID instead of DUNS) and make sure your company name/address match your documents exactly.

Step 5 — Create the certificate profile

1. From your Artifact Signing account, left menu → Objects → Certificate profiles → Create.
2. Type: Public Trust.
3. Name it (5–100 chars), then pick your completed identity validation under Verified CN and O.
4. Create. You never see or hold the certificate. It’s rotated daily behind the scenes. The public cert is embedded in every file you sign.

Step 6 — Assign the Certificate Profile Signer role

This is the role that lets you actually sign. Because we’re using the Azure CLI, it goes on your user. No app registration is needed (this is a separate/alternative process, but we’re not talking about that in this article).

1. From your Artifact Signing account, left menu → Access control (IAM) → Add role assignment.
2. Role: Artifact Signing Certificate Profile Signer → assign to your own user account.

Give role assignments a few minutes to propagate. If you try signing immediately and hit a 403, wait ~5 minutes and retry.

Step 7 — Install the signing tools

First, the Azure CLI: winget install Microsoft.AzureCLI

You’ll use it in Step 9 to authenticate with Azure.

SignTool comes with the Windows SDK. Install it with: winget install --id Microsoft.WindowsSDK --exact

 Run this to find the newest x64 signtool.exe:
Get-ChildItem "C:\Program Files (x86)\Windows Kits\10\bin" -Recurse -Filter signtool.exe | Where-Object { $_.FullName -match '\\x64\\signtool\.exe$' } | Sort-Object FullName -Descending | Select-Object -First 1 -ExpandProperty FullName

Note the path down.

.NET 8 runtime (x64).

Microsoft Visual C++ Redistributable.

Artifact Signing Client Tools:winget install -e --id Microsoft.Azure.ArtifactSigningClientTools
This installs Azure.CodeSigning.Dlib.dll (the plugin signtool uses to talk to Azure).

 Locate the actual dll path after install:
Get-ChildItem -Path "C:\Program Files","$env:LOCALAPPDATA" -Recurse -Filter Azure.CodeSigning.Dlib.dll -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName

Note the path down.

If signtool gives you “command not found”, that’s normal; it’s not on PATH. Use the full path, or add ...\10\<version>\x64 to your PATH.

Step 8 — Create the metadata file

This is a small JSON with three values. Name it anything you like, e.g. artifact-code-signing.json:

{
	"Endpoint": "https://<region-code>.codesigning.azure.net",
	"CodeSigningAccountName": "xojoappsigning",
	"CertificateProfileName": "...."
}

This JSON file will be used a lot, so save it somewhere safe.

• Endpoint = your account URI (region-specific; must match where the account + profile live, or you get a 403).
• CodeSigningAccountName = the Artifact Signing account name from Step 2.
• CertificateProfileName = the certificate profile name you created in Step 5.

Step 9 — Authenticate with the Azure CLI

az login

This opens your browser; sign in with the Microsoft account tied to your Azure subscription. When signtool runs, the dlib picks up your logged-in Azure CLI session automatically.

If you have multiple Azure subscriptions, point the CLI at the right one, then confirm it took:

az account set --subscription "<your subscription id>"
az account show --query name -o tsv

The second command should print your code-signing subscription’s name. If you also have multiple Microsoft tenants (a personal account and a work account, for example), log straight into the right one:

az login --tenant "<tenant id>"

You may occasionally need to re-run az login after long idle periods.

Step 10 — Sign your Xojo app

Just remember, you need to sign the compiled application after each new build.

What to sign (and skip)

Your Xojo Windows build folder looks roughly like this. Sign the binaries you build or distribute under your publisher identity; leave Xojo, Microsoft, and other vendor-signed dependencies alone.

Windows 64 bit/
└── YourApp/
    ├── YourApp.exe              ← sign
    ├── <your own DLLs>          ← sign
    ├── XojoGUIFramework64.dll   ← skip, Xojo provides signed DLLs
    ├── YourApp Libs/            ← skip, Xojo provides signed DLLs
    ├── msvcp140.dll, vcruntime*.dll …  ← skip (Microsoft runtime)
    └── YourApp.exe.WebView2/    ← skip (WebView2 cache)

The script

Save this as sign.ps1, next to the Xojo project, update the paths at the top, and run it from PowerShell:

$ErrorActionPreference = "Stop"

$Signtool    = "C:\...\signtool.exe"                            # path from Step 7
$Dlib        = "C:\...\Azure.CodeSigning.Dlib.dll"              # path from Step 7
$Metadata    = "C:\...\artifact-code-signing.json"              # from Step 8
$BuildFolder = "F:\...\YourApp"                                 # folder containing YourApp.exe

# Installer (Inno Setup) — optional. Set $EnableInno to $false to skip this part.
$EnableInno  = $true
$InnoSetup   = "C:\Program Files (x86)\Inno Setup 6\ISCC.exe"
$IssScript   = "F:\...\YourAppSetup.iss"                        # your Inno Setup script
$Installer   = "F:\...\YourAppSetup.exe"                        # output from the .iss

# Sign binaries you build or distribute under your publisher identity.
# Leave Xojo, Microsoft, and other vendor-signed dependencies alone.
$FilesToSign = @(
    "$BuildFolder\YourApp.exe"
    "$BuildFolder\MyPlugin.dll"
    # add any other files you own here, one per line
)

function Invoke-SigningCommand {
    param([string[]]$Arguments)

    & $Signtool @Arguments
    if ($LASTEXITCODE -ne 0) {
        throw "SignTool failed with exit code $LASTEXITCODE."
    }
}

foreach ($f in $FilesToSign) {
    Invoke-SigningCommand @(
        "sign", "/v", "/fd", "SHA256",
        "/tr", "http://timestamp.acs.microsoft.com", "/td", "SHA256",
        "/dlib", $Dlib, "/dmdf", $Metadata,
        $f
    )
}

if ($EnableInno) {
    # Build a fresh installer, then sign it.
    & $InnoSetup $IssScript
    if ($LASTEXITCODE -ne 0) {
        throw "Inno Setup failed with exit code $LASTEXITCODE."
    }

    Invoke-SigningCommand @(
        "sign", "/v", "/fd", "SHA256",
        "/tr", "http://timestamp.acs.microsoft.com", "/td", "SHA256",
        "/dlib", $Dlib, "/dmdf", $Metadata,
        $Installer
    )
}

What the flags mean:

• /tr http://timestamp.acs.microsoft.com: the timestamp server. The http:// (not https) is intentional.
• /fd SHA256 and /td SHA256: SHA-256 for the file and the timestamp.
• /dlib: the Azure plugin from Step 7. /dmdf: your metadata JSON from Step 8.

Confirm it worked

Two checks:

1. Signtool:$Signtool verify /v /pa "$BuildFolder\YourApp.exe" You want to see Successfully verified.
2. Or: right-click YourApp.exe → Properties → Digital Signatures → your org name should be listed.

Rules of thumb

• Sign after every build. Each new .exe is a fresh unsigned binary.
• Sign before you zip. Sign the files, then package them. Signing inside a zip does nothing.

Troubleshooting

Recap

One time (Steps 1–9): register the Microsoft.CodeSigning provider → create the account → assign the Identity Verifier role → complete identity validation (slow’ish) → create the certificate profile → assign the Signer role → install tools → write the metadata JSON → az login.

Every build (Step 10): run sign.ps1.

The bottom line

Azure Artifact Signing is a low-cost managed option for signing Windows apps, and Azure CLI authentication means local builds do not need a stored signing private key. The setup has some Azure bureaucracy, and identity validation is the slow part. After that, it is one script per build.

Related discussion

For an alternative approach that automates Xojo application signing and Inno Setup installer creation, see Jürg Otter’s Xojo Forum topic, Windows Code Signing & Installer Creation with Inno Setup. The topic includes Jürg’s open-source code, which supports both Azure Artifact Signing and traditional .pfx certificates.

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

Settings

Let’s start with the Settings window, which now has its own AI panel for adjusting how Jade works.

By default, “Enable AI Features” is checked. However, if you are not onboard the AI train, then you can uncheck that setting to turn off Xojo AI integration. This removes the Jade button from the toolbar and also disables the Help menu option.

With AI Features enabled, you can choose the Service to use. By default, “Anthropic Claude” is selected so that your previous Jade configuration works the same as before, but you now also have all these services to choose from:

• Anthropic Claude
• OpenAI GPT
• OpenRouter (Anthropic)
• OpenRouter (OpenAI)
• Local

More information about each of these is in the next section.

The “Allow access to project context” option lets Jade ask for information about your project, such as the names of project items, their source code and any compile errors.

The “Restore conversation from last time” option indicates if your last Jade conversation will be restored to the chat window when the IDE restarts.

Below this are the text areas where you can enter API keys for the services you are using.

Services

Anthropic Claude

When Anthropic Claud is selected, Xojo uses the most recent version of the Claude Sonnet model, which is currently 4.6. To use this service, you will need to create an Anthropic account, generate an API key and add some credits.

Access to project context is supported with Anthropic Claude.

OpenAI GPT

When choose OpenAI, Xojo uses a recent version of the gpt-mini model, currently gpt-5.4-mini. This particular model is fast, relatively inexpensive and well suited for coding purposes. To use OpenAI, you will need to create an OpenAI account , generate an API key and add some credits. There is also an option to earn some free credits that you can optionally turn on.

Access to project context is supported with OpenAI.

OpenRouter

OpenRouter is a unified API service that gives access to hundreds of LLMs from different providers (OpenAI, Anthropic, Google, Meta, etc.) through a single endpoint and key.” Like the others you will first need to create an account, generate an API key and purchase credits. OpenRouter applies these credits as appropriate when using the models you have configured.

There are two options for OpenRouter, so that you can tell it whether to use the Anthropic or OpenAI API. When you choose Anthropic, OpenRouter will automatically route you to Claude models. When you choose OpenAI, OpenRouter will direct you to the default model specified in your OpenRouter account settings.

Not all models will work with Jade and some models have limitations. Currently, only OpenRouter with OpenAI and an OpenAI GPT model supports project context. If you want to try other models, you will likely need to disable the “Allow access to project context” setting in Xojo.

Local LLM

A local LLM is a model that you are running locally on your computer or server you control. To run a local LLM, we recommend using LM Studio which makes it easy to download and run models on a local server.

When this is selected, you also need to provide the base URL for your server. With LM Studio, it is typically:

http://127.0.0.1:1234

In our testing with Xojo we’ve found that a Qwen model, such as qwen3-coder-30b works OK. Other models may not provide useful responses or even work at all. Even though this model works, it is far less capable than Anthropic Claude or OpenAI GPT.

If you want to use Ollama, you’ll have to specify the model name as part of the base URL like this:

http://127.0.0.1:11434#qwen2.5-coder:14b

A local LLM does not have access to project context and choosing this service option currently ignores that setting.

Which Should You Use?

Based on our internal testing, Anthropic Claude has the most accurate responses. It is also the slowest and most expensive.

OpenAI with GPT is the fastest and is relatively inexpensive for what you get.

OpenRouter is really only recommended for advanced users, but it does provide an easy way to switch to specific models.

A local LLM is free to use and completely private, but it is also much slower and far less accurate. Depending on the model you choose, a local LLM also requires significant computing resources (RAM and GPU).

I hope you find these Jade improvements useful to you!

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

These changes focus on two main areas:

• Expanded button symbol support in DesktopToolbarButton
• New layout and presentation control via toolbar style options

Smarter Icon Handling with Symbols

A key addition is the new Symbol property on DesktopToolbarButton. It lets you provide a single string containing multiple symbol names separated by semicolons. Each platform will then check that list and use the first symbol it recognizes.

The Symbol feature is only supported on Windows when using the WinUI target.

AllowMulticolorSymbol was added for macOS. When enabled, the OS may render toolbar symbols using multicolor variants where available, instead of enforcing monochrome styling.

Example

home.Symbol = "house.fill;home;go-home"
home.AllowMulticolorSymbol = True
back.Symbol = "chevron.left;back;go-previous"
forward.Symbol = "chevron.right;forward;go-forward"
search.Symbol = "magnifyingglass;find;system-search"

How it works

Instead of relying only on a static icon, the toolbar now attempts to resolve a symbol first. If a symbol is found, it is used in preference to any icon.

The lookup order is:

1. First matching symbol in the list
2. If none resolve, fallback to the standard icon (if one is set)

This allows you to provide multiple symbolic names as a fallback chain, improving cross-theme and cross-platform reliability.

Where to find the list of supported symbols

WinUI: https://learn.microsoft.com/en-us/uwp/api/windows.ui.xaml.controls.symbol

Linux: https://specifications.freedesktop.org/icon-naming

macOS: https://developer.apple.com/design/human-interface-guidelines/sf-symbols

Better Control Over Toolbar Layout

The toolbar itself now supports a new Style property. This controls how buttons are visually arranged.

DesktopToolbarStyles options:

• Default
  • Generally icon/symbol on top, caption below
  • On Linux and WinUI: icon/symbol on left, caption on right
• IconCaptionVertical
  • Forces vertical layout (icon/symbol above text)
• IconCaptionHorizontal
  • Forces horizontal layout (icon/symbol beside text)
  • Only supported on Linux and Windows
• IconOnly
  • Displays only the icon/symbol
• CaptionOnly
  • Displays only text labels

In Conclusion

With support for symbols, additional layout styles, and WinUI support on Windows, we’re making it easier to create toolbars that look more modern, feel more native on each operating system, and adapt better to different user environments. Whether you prefer icon-only toolbars, text labels, or platform-specific symbols, the new options give you more ways to fine-tune the experience for your users without adding extra complexity to your projects.

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

1. The UI froze completely until the search finished.
2. If the folder tree was deep enough, you might have hit a StackOverflowException.
3. We haven’t actually built a proper UI for it yet!

Today, we’re fixing all three. We’ll introduce a custom app UI, create a Thread subclass to perform the search in the background, and swap our recursive folder crawl for a flatter, iterative approach to spare our stack memory. We’ll also add a file size limit to avoid choking on massive unreadable files.

Step 1: Designing the UI

First, let’s build the interface so you have a real application to run. On your main Window1 (or whichever Window you are using), we need to add a few controls:

• Path Selection: Add a DesktopTextField (named fieldPath, set to ReadOnly) to display the chosen folder path, and a DesktopButton (named buttonSelectPath, caption ...) next to it to open a SelectFolderDialog.
• Search Input: Add a DesktopSearchField (named fieldSearchTerm) where the user types the text they want to find.
• Action Button: Add a DesktopButton (named buttonSearchThreaded, caption Search Threaded) to start and cancel the search.
• Results List: Add a DesktopListBox (named listResults) and set its Column Count to 3. (Optional: Set the InitialValue of the Column headers to File | Line No. | Context).
• Status labels: Add a DesktopLabel (named labelStatusValue) at the bottom of the window to display the live search progress.

Step 2: Creating the Thread Subclass

Threading lets us run our file search simultaneously with the main application, keeping our UI totally responsive.

Instead of writing standard methods, we need to create a dedicated Class.

1. Add a New Class, in the SearchUtils module and name it FileSearch.
2. In the Inspector, change its Super to Thread.
3. Add the following Properties to your new class:
   • MaximumFileSizeMB As Integer = 1
   • SearchTerm As String
   • TargetFolder As FolderItem
   • startTime As Double (Set Scope to Private)

Defining Custom Events

We need our Thread to broadcast events to the Window that’s holding it. Add these three Event Definitions to your FileSearch class:

• Complete(timeElapsed as Double)
• MatchFound(result as SearchUtils.SearchHit)
• StatusUpdate(currentPath as String)

Step 3: The iterative approach

Recursion is elegant, but crawling a hierarchy thousands of folders deep throws a StackOverflowException. Instead, we flatten the traversal using an array as a queue. We start by adding our root folder’s children to an array. As we iterate through that array, any folders we find get their children appended to the end of the same array.

Here is exactly how it looks in the Thread’s Run event. Add the Run event to your FileSearch class and use this exact code and notice the use of AddUserInterfaceUpdate to safely queue UI updates:

Sub Run() Handles Run
  Var maxFileSize As Double = If( Self.MaximumFileSizeMB < 1, 999999999 * 1024 * 1024, Self.MaximumFileSizeMB * 1024 * 1024 )
  
  Var result As Dictionary
  
  Var lastUpdate As Integer = System.Microseconds
  
  If Not (targetFolder Is Nil) And targetFolder.Exists And Not searchTerm.IsEmpty Then
    
    Var child As FolderItem
    Var toSearch() As FolderItem
    For Each child In targetFolder.Children
      toSearch.Add( child )
    Next
    
    Var ti As TextInputStream
    Var line As String
    Var lineNumber As Integer = -1
    
    For index As Integer = 0 To toSearch.LastIndex
      child = toSearch(index)
      
      If System.Microseconds - lastUpdate > 1000000 Then
        result = New Dictionary
        result.Value( "type" ) = "status"
        result.Value( "current" ) = child.NativePath
        AddUserInterfaceUpdate( result )
        lastUpdate = System.Microseconds
      End If
      
      If child.IsFolder Then
        Try
          
          #Pragma BreakOnExceptions False
          
          For Each innerChild As FolderItem In child.Children
            toSearch.Add( innerChild )
          Next
          
          #Pragma BreakOnExceptions Default
          
        Catch e As IOException
          '// Skip inaccessible folders
        End Try
      Else
        If child.Length < maxFileSize Then
          Try
            ti = TextInputStream.Open( child )
            ti.Encoding = Encodings.UTF8
            
            lineNumber = 0
            
            While Not ti.EndOfFile
              lineNumber = lineNumber + 1
              line = ti.ReadLine
              If line.Contains( searchTerm, ComparisonOptions.CaseInsensitive ) Then
                result = New Dictionary
                result.Value( "type" ) = "match"
                result.Value( "path" ) = child.NativePath
                result.Value( "lineNo" ) = lineNumber
                result.Value( "lineText" ) = line
                AddUserInterfaceUpdate( result )
              End If
            Wend
          Catch ioe As IOException
            '// Skip unreadable files
          End Try
        End If
      End If
    Next
  End If
  
  result = New Dictionary( New Pair( "type", "complete" ) )
  AddUserInterfaceUpdate( result )
End Sub

Step 4: Sending Updates to the UI safely

In a thread, you cannot update UI controls directly. That’s why we used AddUserInterfaceUpdate above passing a Dictionary of data. This triggers the Thread’s UserInterfaceUpdate event on the main UI thread.

Add the UserInterfaceUpdate event to your FileSearch class:

Sub UserInterfaceUpdate(data() As Dictionary) Handles UserInterfaceUpdate
  For Each d As Dictionary In data
    Select Case d.Value( "type" )
    Case "match" 
      Var hit As New SearchHit( d.Value( "path" ), d.Value( "lineNo" ), d.Value( "lineText" ) )
      RaiseEvent MatchFound( hit )
    Case "complete"
      RaiseEvent Complete( (System.Microseconds - startTime) / 1000 )
    Case "status"
      RaiseEvent StatusUpdate( d.Value( "current" ) )
    End Select
  Next
End Sub

And finally, add a public method called Search to the class, making sure it executes Preemptively across CPU cores:

Public Sub Search(path As FolderItem, term As String)
  Self.Type = Thread.Types.Preemptive
  
  startTime = System.Microseconds
  
  Self.TargetFolder = path
  Self.SearchTerm = term
  Self.Start
End Sub

Step 5: Wiring the UI

Now, let’s bring it all together. Select Window1 and simply drag the FileSearch class from your Navigator onto your Window. It will appear in a shelf at the bottom as FileSearch1 (rename it to seeker).

Implement the Event Handlers to your new seeker control:

seeker.Complete:

Sub Complete(timeElapsed As Double) Handles Complete
  buttonSelectPath.Enabled = True
  buttonSearchThreaded.Caption = "Search Threaded"
  fieldSearchTerm.Enabled = True

  Var count As Integer = listResults.LastRowIndex + 1
  Var timeElapsedSeconds As Double = timeElapsed / 1000
  labelStatusValue.Text = "Complete in " + timeElapsedSeconds.ToString( "#0.00" ) + " seconds! " + count.ToString( "#" ) + " results found."
End Sub

seeker.MatchFound:

Sub MatchFound(result As SearchUtils.SearchHit) Handles MatchFound
  listResults.AddRow( result.FilePath, result.LineNumber.ToString( "#" ), result.LineText )
  listResults.RowTagAt( listResults.LastAddedRowIndex ) = result
End Sub

seeker.StatusUpdate:

Sub StatusUpdate(currentPath As String) Handles StatusUpdate
  labelStatusValue.Text = "Searching '" + currentPath + "'"
End Sub

And finally, the code in buttonSearchThreaded to kick off the search (and handle nice cancellation):

Sub Pressed() Handles Pressed
  Select Case Me.Caption
  Case "Search Threaded"
    If fieldSearchTerm.Text.Length >= 3 Then
      If seeker.ThreadState = Thread.ThreadStates.NotRunning Then

        listResults.RemoveAllRows

        fieldSearchTerm.Enabled = False
        buttonSelectPath.Enabled = False
        labelStatusValue.Text = "Searching..."

        Me.Caption = "Cancel"

        seeker.Search( Self.path, fieldSearchTerm.Text )

      End If
    End If
  Case "Cancel"
    seeker.Stop
    labelStatusValue.Text = "Cancelled"
  End Select
End Sub

Summary

By switching from recursion to a linear queue, we bulletproofed the code against StackOverflowExceptions. By moving the heavy lifting to a preemptive Thread, we completely unlocked the UI, making the app feel incredibly fast and responsive even while chewing through thousands of files. And using AddUserInterfaceUpdate, we safely pipe results directly back to the user without locking up the UI!

You can download the project here: SearchUtils.FindInFiles.zip

Special Thanks

A huge shoutout and special thanks to Xojo MVP and forum user Anthony G. Cyphers. Anthony generously provided the solution to evolve the SearchUtils module into this threaded version, along with the demo app UI.

P.S. Got your own spin on this utility? Have ideas for new features or alternative approaches? Jump into the Xojo Code Sharing Forum  and share your improvements with the community!

Happy coding!

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

Part 1: Building JSON

Building JSON from scratch means firing up a new JSONItem and throwing data at it. Don’t build JSON by stitching strings together. It breaks easily, you’ll mess up the escaping, and JSONItem makes it completely unnecessary.

The Basic Payload

When you just need to fire a flat object at a web service:

Var apiPayload As New JSONItem
apiPayload.Value("endpoint") = "/users/create"
apiPayload.Value("timestamp") = 1715423000
apiPayload.Value("forceSync") = True

// Get the string back
Var jsonString As String = apiPayload.ToString
// {"endpoint":"/users/create","timestamp":1715423000,"forceSync":true}

Making Arrays

If you’re making a list of tags or IDs, use the .Add method. The moment you call .Add, Xojo treats that JSONItem as a JSON array under the hood.

Var tags As New JSONItem
tags.Add("xojo")
tags.Add("desktop")
tags.Add("api")

Var jsonString As String = tags.ToString
// ["xojo","desktop","api"]

Nesting Things

Most APIs want nested payloads. You map this out by making separate JSONItem objects and attaching them to each other.

Var payload As New JSONItem
payload.Value("status") = "active"

Var user As New JSONItem
user.Value("id") = 982
user.Value("username") = "johndoe"

Var roles As New JSONItem
roles.Add("admin")
roles.Add("editor")

user.Value("roles") = roles // Attach the array to the user object
payload.Value("data") = user // Attach the user object to the main payload

Var jsonString As String = payload.ToString
// {"status":"active","data":{"id":982,"username":"johndoe","roles":["admin","editor"]}}

Part 2: Parsing JSON

To go the other direction, pass a raw JSON string straight into the constructor.

Reading a Flat Response

When a server hands you back a flat config or auth token, just pull the values right out.

Var rawJSON As String = "{""token"":""abc123xyz"",""expiresIn"":3600,""active"":true}"
Var response As New JSONItem(rawJSON)

Var token As String = response.Value("token")
Var expiresIn As Integer = response.Value("expiresIn")
Var isActive As Boolean = response.Value("active")

Handling Optional Keys with Lookup

If you use .Value("key") and the key isn’t in the JSON, Xojo throws a KeyNotFoundException. Instead of writing boilerplate If response.HasKey("key") Then checks everywhere, use .Lookup(). It lets you define a fallback value in line.

Var rawJSON As String = "{""username"":""johndoe""}"
Var response As New JSONItem(rawJSON)

// Returns "johndoe" because the key is present
Var user As String = response.Lookup("username", "anonymous") 

// Returns False because "forceSync" is missing from the JSON
Var isSyncForced As Boolean = response.Lookup("forceSync", False) 

Looping Over an Array

If an API hands you a list of database records:

Var rawJSON As String = "[{""id"":1, ""name"":""Alice""}, {""id"":2, ""name"":""Bob""}]"
Var userList As New JSONItem(rawJSON)

For i As Integer = 0 To userList.Count - 1
  Var currentUser As JSONItem = userList.ValueAt(i)

  Var id As Integer = currentUser.Value("id")
  Var name As String = currentUser.Value("name")

  System.DebugLog(id.ToString + ": " + name)
Next

Digging out Nested Nodes

This is where .Child() comes in handy. While .Value() returns a generic Variant (which you can’t chain directly), .Child("key") explicitly returns the nested object as a JSONItem. This allows for perfectly clean chaining.

Var rawJSON As String = "{""weather"":{""current"":{""temp"":22, ""condition"":""Sunny""}}}"
Var forecast As New JSONItem(rawJSON)

// Use .Child() to tunnel down into objects, then .Value() to pull the final primitive data 
Var temperature As Double = forecast.Child("weather").Child("current").Value("temp")
Var condition As String = forecast.Child("weather").Child("current").Value("condition")

Part 3: Identifying the Structure

APIs are notoriously inconsistent. Check the .IsArray property to figure out what structure you’re dealing with before parsing it, so your loops don’t crash when passing something unexpected.

Var rawJSON As String = "[""apple"", ""banana"", ""orange""]"
Var parsedData As New JSONItem(rawJSON)

If parsedData.IsArray Then
  System.DebugLog("Looks like an array with " + parsedData.Count.ToString + " items.")

  For i As Integer = 0 To parsedData.Count - 1
    System.DebugLog(parsedData.ValueAt(i).StringValue)
  Next
Else
  System.DebugLog("It's a standard dictionary.")
  If parsedData.HasKey("data") Then
    System.DebugLog(parsedData.Value("data").StringValue)
  End If
End If

That’s it. For more info on JSONItem, don’t forget to check the online documentation at: https://documentation.xojo.com/api/text/json/jsonitem.html

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

The Goal

We want to:

1. Search through subfolders automatically.
2. Add a maxDepth parameter so we don’t accidentally crawl the entire hard drive.
3. Keep the simple version working using method overloading.

Step 1: Move File Reading to its own Method

The original FindInFiles function did everything: validated the folder, looped through children, read file content, and matched text. Adding recursion to that would make the code look ugly, so let’s refactor our code.

We’ll start by moving the file-reading logic into its own private method: SearchFile. This keeps the “search” logic separate from the “looping” logic.

Private Sub SearchFile(file As FolderItem, searchTerm As String, hits() As SearchHit)
  Try
    Var input As TextInputStream = TextInputStream.Open(file)
    input.Encoding = Encodings.UTF8
    Var lineNumber As Integer = 0
    While Not input.EndOfFile
      Var line As String = input.ReadLine
      lineNumber = lineNumber + 1
      If line.Contains(searchTerm, ComparisonOptions.CaseInsensitive) Then
        hits.Add(New SearchHit(file.NativePath, lineNumber, line))
      End If
    Wend
    input.Close
  Catch error As IOException
    // Skip unreadable files
  End Try
End Sub

Step 2: Recursive Folder Traversal

Now we create SearchFolder. This method loops through a folder. If it finds a file, it calls SearchFile. If it finds a folder, it calls itself.

To keep this safe, we Use maxDepth:

• maxDepth = 0: Search only this folder.
• maxDepth > 0: Search this folder and N levels of subfolders.
• maxDepth = -1: Search everything (unlimited).

Private Sub SearchFolder(folder As FolderItem, searchTerm As String, hits() As SearchHit, maxDepth As Integer)
   Try
    For Each item As FolderItem In folder.Children
      If item Is Nil Or Not item.Exists Or Not item.IsReadable Then Continue
      If item.IsFolder Then
        If maxDepth <> 0 Then
          Var nextDepth As Integer = If(maxDepth > 0, maxDepth - 1, maxDepth)
          SearchFolder(item, searchTerm, hits, nextDepth)
        End If
      Else
        SearchFile(item, searchTerm, hits)
      End If
    Next
  Catch error As IOException
    // Skip inaccessible folders
  End Try
End Sub

The logic in nextDepth lets us count down if there’s a limit, or stay at -1 if there isn’t.

Step 3: Support Both Versions with Method Overloading

Overloading is a feature that lets you have multiple methods with the same name, as long as they have different parameters. In our case, it allows us to provide a simple version for one folder, and a recursive version with a depth limit. Xojo will automatically pick the right one based on the arguments you pass. You can read more about it in the Xojo Documentation.

The default version (depth 0):

Public Function FindInFiles(targetFolder As FolderItem, searchTerm As String) As SearchHit()
  Return FindInFiles(targetFolder, searchTerm, 0)
End Function

The recursive version:

Public Function FindInFiles(targetFolder As FolderItem, searchTerm As String, maxDepth As Integer) As SearchHit()
  Var hits() As SearchHit
  If targetFolder Is Nil Or Not targetFolder.Exists Or Not targetFolder.IsFolder Or searchTerm.IsEmpty Then
    Return hits
  End If
  Try
    SearchFolder(targetFolder, searchTerm, hits, maxDepth)
  Catch error As IOException
    // Skip inaccessible folders
  End Try
  Return hits
End Function

By separating the validation, traversal, and processing, the code is much easier to modify. If you want to add Regex support, you only change SearchFile. If you want to filter by file extension, you only change SearchFolder.

Summary

Now, you can search a single folder just like before, or crawl a directory tree with one extra parameter:

// Search up to 3 levels deep
Var results() As SearchUtils.SearchHit = SearchUtils.FindInFiles(myFolder, "TODO", 3)

The Complete Recursive Code

The SearchUtils Module

Module SearchUtils

  Class SearchHit
    Public Property FilePath As String
    Public Property LineNumber As Integer
    Public Property LineText As String

    Public Sub Constructor(filePath As String, lineNumber As Integer, lineText As String)
      Self.FilePath = filePath
      Self.LineNumber = lineNumber
      Self.LineText = lineText
    End Sub
  End Class

  Public Function FindInFiles(targetFolder As FolderItem, searchTerm As String) As SearchHit()
    // Simple usage: depth = 0
    Return FindInFiles(targetFolder, searchTerm, 0)
  End Function

  Public Function FindInFiles(targetFolder As FolderItem, searchTerm As String, maxDepth As Integer) As SearchHit()
    // Recursive usage: maxDepth ( -1 is unlimited )

    Var hits() As SearchHit

    If targetFolder Is Nil Or Not targetFolder.Exists Or Not targetFolder.IsFolder Or searchTerm.IsEmpty Then
      Return hits
    End If

    Try
      SearchFolder(targetFolder, searchTerm, hits, maxDepth)
    Catch error As IOException
      // Skip inaccessible folders
    End Try

    Return hits
  End Function

  Private Sub SearchFolder(folder As FolderItem, searchTerm As String, hits() As SearchHit, maxDepth As Integer)
    Try
      For Each item As FolderItem In folder.Children
        If item Is Nil Or Not item.Exists Or Not item.IsReadable Then Continue

        If item.IsFolder Then
          If maxDepth <> 0 Then
            Var nextDepth As Integer = If(maxDepth > 0, maxDepth - 1, maxDepth)
            SearchFolder(item, searchTerm, hits, nextDepth)
          End If
        Else
          SearchFile(item, searchTerm, hits)
        End If
      Next
    Catch error As IOException
      // Skip inaccessible folders
    End Try
  End Sub

  Private Sub SearchFile(file As FolderItem, searchTerm As String, hits() As SearchHit)
    Try
      Var input As TextInputStream = TextInputStream.Open(file)
      input.Encoding = Encodings.UTF8
      Var lineNumber As Integer = 0

      While Not input.EndOfFile
        Var line As String = input.ReadLine
        lineNumber = lineNumber + 1

        If line.Contains(searchTerm, ComparisonOptions.CaseInsensitive) Then
          hits.Add(New SearchHit(file.NativePath, lineNumber, line))
        End If
      Wend

      input.Close
    Catch error As IOException
      // Skip unreadable files
    End Try
  End Sub
End Module

Happy coding!

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

Now, that we already know all the pieces involved in this particular puzzle (certificates, sandboxing, notarization, hardened runtime, etc.), the question to answer is…

What kind of macOS code signing do you want to do today?

Apple developer certificates installed on your Mac determine the kind of code signing and, thus, the distribution options available for your macOS app. They can also support certain macOS security requirements that distribution methods or features may impose, such as entitlements or provisioning profiles.

This diagram can help determine these based on the certificate used when signing the app, so you can get a better idea:

As a practical summary:

• Ad-Hoc signing / None: This option makes sense primarily when you’re developing and running or debugging the app on your Mac or on the same computer, since it typically doesn’t require special entitlements or provisioning profiles.
• Apple Developer / Development. Using this certificate enables sandboxing, hardened runtime, entitlements and provisioning profiles even when debugging from the IDE or testing the build on your own computer. It offers a better experience, but you won’t be able to notarize it or bypass the Gatekeeper barrier if distributed to other users.
• Developer ID Application / Direct Distribution. With this certificate, you can notarize your app so Gatekeeper won’t block distribution outside the Mac App Store. When debugging from the IDE, entitlements and provisioning profiles (if needed) are applied as well, along with optional sandboxing.
• Apple Distribution / App Store. Use this certificate when the app has been tested and it is ready to be sent to App Store Connect… or even when you’re planning to send it to the App Store Connect so a group of beta-testers can test it using Apple’s TestFlight.

How the Xojo IDE helps with all of this?

We have been adding features to the Xojo IDE to make code signing and distributing your macOS apps an easier and leaner process; most of these are available under Build Settings > macOS > Sign:

Developer ID – Build For

This is the most recent addition to better deal with the first, and most important, piece of the puzzle: handling certificates! Instead of having to go back and forth between the Keychain Access and the Xojo IDE to copy/paste the expected data from the certificates for the kind of build or distribution you plan for the app, you can now find under the Developer ID field all the available Developer Teams (usually just yours) and, when a Developer Team is selected, the “Build For” popup menu will be populated with the available options for builds/distributions based on the installed developer certificates for that team.

When all the Apple developer certificates are properly installed for a given Developer Team, the available options will be: Development, Direct Distribution and App Store (plus None, meaning Ad-Hoc signing).

If you find that some of these options are missing from the “Build For” popup menu, that means the corresponding certificate is not installed or there is some kind of issue with that certificate (maybe it has expired or has its private key missing). In those cases, we included the “Inspect…” option under the “Developer ID” popup menu. Selecting Inspect lets you gain a better picture about everything related to your Apple developer certificates and even get advice about how to fix the most common issues.

Sandboxing

Enable this feature if you plan to debug, build, or distribute your app as a sandboxed app. In that case, the associated editor will make it even easier to enable the sandboxing features that may apply to your particular app. The IDE will take care of all the rest. Note that, while sandboxing was previously only applied to built/distributed macOS apps in previous Xojo releases, starting with Xojo 2026r1 it is also applied when the app is being debugged from the IDE.

Hardened Runtime

Enable this option mainly for apps meant to be built and/or distributed using Direct Distribution or the App Store options. While this is optional when distributing it via the Mac App Store, it is still highly recommended to enable it for that scenario.

When the app is debugged from the IDE, the hardened runtime won’t be applied even if it is enabled… mainly so you can debug it!

As with sandboxing, the hardened runtime option also includes its own editor to make your app-specific selections easier. The IDE will take care of the under the hood processing when the app is built.

Notarization

If you haven’t started notarizing your macOS apps yet, now is the time! This will be possible only with the Direct Distribution option (equivalent to the Developer ID Application Certificate) and implies enabling hardened runtime. When you enable notarization, the associated hardened runtime will be enabled for you, even if you don’t select additional option from its editor.

Notarization requires the use of what Apple calls an App-Specific Password, which you can set up by following the steps found in the window that appears when the associated Setup button is clicked.

Once everything has been setup, the notarization process will happen the next time the app is built. Note, the notarization process will not take place when the app is debugged from the IDE (as with hardened runtime); you don’t need to specifically disable that option.

Entitlements

The combination of certain certificates, build, and distribution options you choose for your app may require you to set a series of entitlements; for example, when enabling sandboxing and/or hardened runtime. Additionally, with Xojo 2026r1 it is possible to attach your built or debugged apps to Xcode Instruments for further inspections beyond the current capabilities of Xojo’s debugger.

In all of the above scenarios, Xojo will take care of the required entitlements without you needing to notice it; but if your app also makes use of some features that require adding extra entitlements (and probably a matching provisioning profile), as happens with most of the Apple specific services such as iCloud, Keychain, In-App Purchases, etc., you will need to craft the corresponding .plist file for them and add it using the User Entitlements option. These entitlements will be combined with the ones automatically generated by Xojo and included in the app during the code signing process.

Provisioning Profiles

On macOS, provisioning profiles are supported by a Copy Files build step, which requires selecting Contents as the destination folder. Not ideal, but that way you can select what kind of provisioning profile you want to apply to builds or when debugging your project (this is a new feature starting with Xojo 2026r1).

Property List Editor

The ability to add your own property list entries to the compiled/distributed macOS app is enhanced by a complete Property List Editor available under Build Settings > macOS since Xojo 2025. It makes it easier to create these entries and even save them for reuse in other projects.

The entries you add with the Property List Editor will be combined with those automatically generated by the IDE, or with entries that may have been added to the project using previous methods (such as adding an external .plist file to the Project Navigator sidebar).

Publishing to the Mac App Store

While there are some steps that need to be done both at Apple’s Developers Portal and App Store Connect Website, you will be able to set your app category directly from the IDE under Build Settings > macOS.

In addition, the Publish feature (responsible for sending your app to App Store Connect) will be in charge of verifying that the project meets everything that Apple requires prior to send it for reviewing or making available through TestFlight.

In order for the Publish button to be enabled, you need to select the App Store option for the selected “Developer ID” Team from the “Build For” popup menu under Build Settings > macOS > Sign.

Dealing with Certificates Issues

It doesn’t matter if your app requires entitlements, provisioning profiles, or if you are going to notarize it or enable sandboxing plus hardened runtime. All of this is based on the signing of your developer certificates, so let’s go back and see how to deal with the most common issues related with these.

Backup Your Certificates

Once you have installed your certificates, the first thing you should do is export them from Keychain Access to a secure place (ideally, not in your computer but an external USB key or drive). Why? Here’s why:

1. Apple only allows you to create certificates a maximum of five times per year (mostly because they expire after one year, as we did see in a previous entry). Every time you install certificates, whether on the same computer or a different Mac you own, they count as new certificates, with different serial numbers and SHA1/SHA256 data. In practice, this reduces the number of installations available per year.
2. In addition, some features, like provisioning profiles, rely on the specific certificates selected during their creation. You will get a signing error if you build the app on a Mac with different certificates.
3. If you need to restore your Mac or migrate to a new Mac, your certificates won’t be restored using the usual tools from Apple. Having a backup of your developer certificates will make easier to restore them in Keychain Access after restoring your computer or when you change to a new Mac.

Instead of using Xcode to install new certificates on every Mac you intend to use for code signing, install them on just one Mac, export them from that Mac, and import them into the Keychain Access app on your other Macs. This ensures all of your Macs will use the same certificates.

Review Pending Apple Developer Agreements

This is one of the most common issues related to code signing: it just stops working and you don’t know why and even the returned error messages doesn’t reveal why. If you’re sure you have the required developer certificates installed, they are valid (not expired), and don’t have any other issues then it is time to sign-in into the Apple Developer and App Store Connect portals to check if there are some pending agreements you need to accept.

Missing and Expired Certificates

This is another very common issue. Starting with Xojo 2026r1, we made easier to detect this situation. If a given certificate for your team is not installed, then you won’t be able to select the signing option from the “Build For” popup menu under Build Settings > macOS > Sign. You can further dig into it selecting the “Inspect…” option from the “Developer ID” popup menu, and even receive some advice on how to fix it!

Certificates are all good… but the signing throws errors

When using the Direct Distribution or App Store options, the code signing process uses Apple Time Servers to add the date and time as part of the signing. That means that the computer requires an active Internet connection, and that such time servers must be reachable from Apple’s side (it’s very rare for them to be down).

Other operations such as notarization and publish also require an active Internet connection, and the corresponding Apple services must be up and running. Some times these can be down.

When these issues occur, it is a good idea to check the Apple Services status webpage.

In summary

It’s been a long four-article ride with the aim of giving you a clearer understanding of what happens under the hood when you code sign your macOS apps, what kind of certificate you need for a given distribution, and which macOS security features are supported by Development, Developer ID Application or Apple Distribution certificates; and, most importantly, how Xojo helps you with all of it!

I’d love to hear about your experience with macOS code signing, the rough corners you still need to tackle, and other improvements you would welcome. The Xojo forums are a great place to keep the conversation going!

Happy macOS code signing 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

Code Signing on macOS: What Developers Need to Know

• Part 1, Get Started
• Part 2, Code Signing With Developer Certificates
• Part 3, Entitlements and Provisioning Profiles
• Part 4, How Xojo helps with Certificates, Signing and Distribution

In this post, we’ll build a simple Find in Files utility in Xojo that:

• searches the files in a folder
• reads each file line by line
• performs a plain-text, case-insensitive match
• returns the file path, line number, and matching line

The goal is simple: build something useful while leaving the door open for the fancier stuff.

What this Find in Files function will do

Let’s keep the scope clear:

• search one folder
• search plain text only
• skip subfolders for now
• return the matching file path, line number, and line contents

Step 1: A class in a module and some properties

Before touching the file system, let’s define what a match looks like.

You could return raw strings, but that gets messy fast. A small class keeps the code readable and gives us an obvious place to extend later. In this version, I like keeping that class inside the same module as the search function. It keeps the entire utility self-contained instead of spraying helper types all over the project.

So, we start by adding a module SearchUtils and inside the module we will add a class SearchHit.

Module SearchUtils

  Class SearchHit

    Public Property FilePath As String
    Public Property LineNumber As Integer
    Public Property LineText As String

    Public Sub Constructor(filePath As String, lineNumber As Integer, lineText As String)
      Self.FilePath = filePath
      Self.LineNumber = lineNumber
      Self.LineText = lineText
    End Sub

  End Class

End Module

Each result stores three things:

1. the file path
2. the line number
3. the matching line

Step 2: Walk through the folder

FolderItem.Children lets us loop through a folder with a For Each loop, which keeps the code clear.

We’ll also reject bad input early:

• the folder is Nil
• the folder does not exist
• the item passed is not actually a folder
• the search term is empty

This process is simple, fast and effective.

Step 3: Read files line by line

For text files, TextInputStream.Open is the right tool. From there, we can call ReadLine until EndOfFile becomes True.

I prefer this over ReadAll for a utility like this. ReadAll is fine when the file is small and you know what you’re doing, but line-by-line reading is a better default here. It keeps memory use in check and gives us line numbers for free.

For the sample code, I’m explicitly using UTF-8:

input.Encoding = Encodings.UTF8

That keeps the sample predictable. It does not mean this code can gracefully decode every text file you throw at it. Files with unknown encodings or binary-ish content are a separate problem, and they deserve their own solution.

Step 4: Match the text

For a plain-text search, String.Contains does exactly what we need:

line.Contains(searchTerm, ComparisonOptions.CaseInsensitive)

It handles the case-insensitivity without the overhead, or the headache, of regex.

Step 5: The full module and class and function

Module SearchUtils

  Public Class SearchHit
    Public Property FilePath As String
    Public Property LineNumber As Integer
    Public Property LineText As String

    Public Sub Constructor(filePath As String, lineNumber As Integer, lineText As String)
      Self.FilePath = filePath
      Self.LineNumber = lineNumber
      Self.LineText = lineText
    End Sub
  End Class

  Public Function FindInFiles(targetFolder As FolderItem, searchTerm As String) As SearchHit()
    Var hits() As SearchHit

    If targetFolder Is Nil Then
      Return hits
    End If

    If Not targetFolder.Exists Or Not targetFolder.IsFolder Then
      Return hits
    End If

    If searchTerm.IsEmpty Then
      Return hits
    End If

    For Each item As FolderItem In targetFolder.Children
      If item Is Nil Then Continue
      If item.IsFolder Then Continue
      If Not item.Exists Then Continue
      If Not item.IsReadable Then Continue

      Try
        Var input As TextInputStream = TextInputStream.Open(item)
        input.Encoding = Encodings.UTF8

        Var lineNumber As Integer = 0

        While Not input.EndOfFile
          Var line As String = input.ReadLine
          lineNumber = lineNumber + 1

          If line.Contains(searchTerm, ComparisonOptions.CaseInsensitive) Then
            hits.Add(New SearchHit(item.NativePath, lineNumber, line))
          End If
        Wend

        input.Close

      Catch error As IOException
        ' Skip files that cannot be read as text.
        Continue
      End Try
    Next

    Return hits
  End Function

End Module

How it works

Let’s break down the important parts.

Input validation

This block prevents pointless work and avoids avoidable runtime problems:

If targetFolder Is Nil Then
  Return hits
End If

If Not targetFolder.Exists Or Not targetFolder.IsFolder Then
  Return hits
End If

If searchTerm.IsEmpty Then
  Return hits
End If

Rule of thumb: reject bad input early.

Folder iteration

This is the core loop:

For Each item As FolderItem In targetFolder.Children

We’re only scanning the folder’s immediate contents. If an item is another folder, we skip it.

If item.IsFolder Then Continue

Safe text reading

Each file is opened with TextInputStream.Open inside a Try...Catch block:

Try
  Var input As TextInputStream = TextInputStream.Open(item)
  input.Encoding = Encodings.UTF8
  ...
Catch error As IOException
  Continue
End Try

That way, one unreadable file does not take down the whole search. It gets skipped and the rest of the folder still gets processed.

Line-by-line matching

This is where the actual work happens:

While Not input.EndOfFile
  Var line As String = input.ReadLine
  lineNumber = lineNumber + 1

  If line.Contains(searchTerm, ComparisonOptions.CaseInsensitive) Then
    hits.Add(New SearchHit(item.NativePath, lineNumber, line))
  End If
Wend

Because we’re reading one line at a time, attaching the correct line number is trivial.

Why keep SearchHit inside the module?

Because it belongs to this utility. The search function and its result type are part of the same little unit of behavior, so keeping them together makes the project easier to scan and easier to transform it to a Library.

It also means code outside the module uses the namespaced type:

Var results() As SearchUtils.SearchHit = SearchUtils.FindInFiles(folder, "xojo")

Using the function

Here’s a simple example that lets the user choose a folder and then writes the results to the debug log:

Var folder As FolderItem = FolderItem.ShowSelectFolderDialog
If folder Is Nil Then Return

Var results() As SearchUtils.SearchHit = SearchUtils.FindInFiles(folder, "error")

For Each hit As SearchUtils.SearchHit In results
  System.DebugLog(hit.FilePath + " | line " + hit.LineNumber.ToString + " | " + hit.LineText)
Next

If you want to display the results in a DesktopListBox, that works nicely too:

Var folder As FolderItem = FolderItem.ShowSelectFolderDialog
If folder Is Nil Then Return

Var results() As SearchUtils.SearchHit = FindInFiles(folder, "error")

ListBox1.RemoveAllRows
ListBox1.ColumnCount = 3

For Each hit As SearchUtils.SearchHit In results
  ListBox1.AddRow(hit.FilePath)
  ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 1) = hit.LineNumber.ToString
  ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, 2) = hit.LineText
Next

A few sample results might look like this:

C:\Logs\app.log | line 18 | Error connecting to database
C:\Logs\app.log | line 42 | Error writing audit record
C:\Configs\service.txt | line 7 | Last error message: timeout

Practical limitations of this version

This utility is useful, but limited.

It assumes UTF-8

That is fine for plenty of modern text files, but not all of them. If you’re dealing with mixed encodings, you’ll need a smarter approach that detects the file encoding.

It doesn’t recurse into subfolders

That is deliberate. Recursive search is useful, but it adds another layer of behavior and another place to make the code harder to read.

Final thoughts

A basic Find in Files function is one of those utilities that looks small but pays off quickly. This is a base-layer utility. Once you have this working, adding recursion or regex is a much smaller lift.

Let’s discuss in the forums.

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

With this feature you can provide custom drawing for a control at design time, making it easier to visualize your UI without running the project.

If this sounds familiar, it’s because it brings Desktop and iOS/Android projects closer to what’s already possible in Web projects with WebSDKUIControl, where custom layout rendering has been available for some time.

Why this matters

Previously your custom Canvas controls would appear as generic placeholders, making it difficult to understand how they would look at runtime. Now you can:

• Render a preview of your control directly in the layout editor
• Display dynamic or state-based visuals
• Make custom controls much easier to work with at design time

How it works

For Desktop projects, you can subclass DesktopUIControl and implement the DrawControlInLayoutEditor event. Your drawing code is executed by the IDE as it renders the control in the layout. For iOS and Android projects, this event is available on MobileUIControl.

You can also use this event directly with DesktopCanvas and MobileCanvas controls, so you can start drawing in DrawControlInLayoutEditor without needing to subclass anything.

This event gives you the flexibility to draw whatever you need—shapes, text, or even simplified representations of runtime content. For example, a custom media player control could display a play button and timeline, or a chart control could render a sample graph.

A note about XojoScript limitations

One important detail to keep in mind is that DrawControlInLayoutEditor runs using XojoScript. This allows the IDE to safely execute your drawing code at design time, but it also means not everything you’d typically expect to use in Xojo is available, especially when it comes to the graphics APIs.

In practice, most common drawing operations—such as shapes, lines, and text—work as expected. However, in some cases these graphics calls use a slightly different API, as is the case with LinearGradientBrush.

Also, because this runs as XojoScript, you cannot call other methods from within your DrawControlInLayoutEditorcode. To access your control’s properties, you’ll need to use the built-in  ColorProperty, BooleanProperty, IntegerProperty, DoubleProperty, and StringProperty methods.

Support for more Graphics

In 2026r1, we’ve expanded the graphics capabilities available to DrawControlInLayoutEditor, building on what was previously supported for WebSDKUIControl. New additions include support for:

• LinearGradientBrush, PictureBrush, and ShadowBrush
• LineDash, LineDashOffset, LineCap, LineJoin, and MiterLimit
• Outline
• Scale, Rotate, and Translate
• SaveState, RestoreState
• Color constants (Red, Green, Blue, Yellow etc.)

Since XojoScript does not support the Pair type, the LinearGradientBrush API was adapted slightly:

Class LinearGradientBrush

  Sub Constructor()

  Sub AddStop(stop As Double, c As Color)

  Property StartPoint As Point
  Property EndPoint As Point

End Class

The main difference is how the brush is constructed and how stops are added, without needing Pair. With this new API, you can turn a basic graph into something much more visually appealing.

Turning off this feature

While many may prefer custom rendering for custom controls, it can become a bottleneck when a large number of controls are rendering content. If you prefer a less resource-intensive experience, you can disable this behavior in Settings → Layout by enabling the Static Rendering option.

Finally

With DrawControlInLayoutEditor now available for Desktop and Mobile projects, you can take advantage of the same benefits Web projects have enjoyed for years. Be sure to check out the new DrawControlInLayoutEditor example project, adapted from the WebSDK → CustomButton example. We hope you enjoy designing and previewing your custom controls with this new event—and yes, it also works in Libraries!

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

What Are Watchpoints?

Watchpoints let you pause execution when the value of a variable or property changes. Instead of asking “how did I get here?”, watchpoints help you answer “when did this change?”

This is especially useful when:

• A value is being modified unexpectedly
• Multiple parts of your code interact with the same object
• You’re tracking down subtle state-related bugs

How Watchpoints Work

Setting up a watchpoint requires pausing execution where you would like to start monitoring the variable or property of an object.

In this example, we want to monitor the count variable, so you can right-click it in the variables debugger list and select Watch from the context menu. Once a watchpoint is set on a variable or property, the debugger keeps track of its value during execution. When the value changes, execution pauses and shows the line that triggered the change. Notice that the watchpoint break line is highlighted differently from the current execution line, and a Watchpoints list is now displayed.

This gives you immediate visibility into:

• What code caused the modification
• What the previous and new values are
• What the surrounding state looks like

Why This Matters

Traditionally, tracking down a value change required manually stepping through code or adding temporary logging. Both approaches are time-consuming and error-prone.

Watchpoints eliminate that friction by:

• Reducing the need for repetitive stepping
• Highlighting only meaningful changes
• Letting you focus on the root cause faster

Conditional Watchpoints

Watchpoints in Xojo aren’t limited to triggering on every change—you can make them conditional. For example, you can break only when a value is equal to, greater than, or less than a specific threshold, or even when it falls within a defined range. For string, both case-sensitive and case-insensitive comparisons are supported. This makes it much easier to focus on the changes that actually matter, especially when a variable updates frequently but only becomes problematic under certain conditions.

To add a condition to a watchpoint, right-click the watched variable or property and choose Edit Watchpoint Expression from the context menu.

The expression editor adapts based on the type of variable or property you’re watching, providing hints about what values and conditions you can enter.

Handling Object Lifetimes

One important detail when working with watchpoints is object lifetime.

If a watchpoint is attached to a property of an object that goes out of scope or is destroyed, the debugger can no longer track it. In these cases, Xojo provides feedback through the Messages pane so you know the watchpoint is no longer valid, along with the last known value.

What works and what doesn’t

You can set watchpoints on most variables and properties, even variants; however, Arrays, Structures, and computed properties are not supported. Code within #pragma DisableBackgroundTasks or #pragma Debug False blocks will not trigger watchpoint breaks. Watchpoints are also not currently available for Android projects.

Final Thoughts

Watchpoints bring a new level of precision to debugging in Xojo. Instead of chasing bugs through code, you can now let the debugger do the work of tracking down exactly where things go wrong.

Give them a try in your next debugging session—you might find yourself solving problems faster than ever!

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

But timers have a limit: they still run on the UI thread. If your background work is genuinely heavy (database queries, file I/O, complex calculations), a timer won’t save you. You need actual background processing and that’s where threads come in.

The Core Idea: Threads

A thread is a separate execution path that runs outside the UI thread. While your thread does the heavy lifting, the UI stays responsive to clicks, typing, scrolling. When your thread finishes a chunk of work, it notifies the UI thread via UserInterfaceUpdate, and only that callback runs on the main thread.

The rule is simple: threads cannot touch UI controls directly. If you try, you get a crash. UserInterfaceUpdate is your bridge.

For a deeper dive into how Xojo’s threading model works under the hood, including cooperative vs. preemptive threading, see Cooperative to Preemptive: Weaving New Threads Into Your Apps.

Let’s Code

Prerequisites: Add a StatusLabel (DesktopLabel), a DesktopButton, and a Thread control. Also define:

kCountTo As Integer = 100

The Thread Control

Drag a Thread from the library into your window and name it BackgroundWorker.

The Button (Start the Thread)

Place this in the Pressed event of a button:

Sub Pressed()
  If BackgroundWorker.ThreadState = Thread.ThreadStates.NotRunning Then
    BackgroundWorker.Start
  End If
End Sub

This checks if the thread is already running. If not, start it. This prevents multiple threads from piling up if someone clicks fast.

The Thread.Run Method (Background Work)

Implement the Run method on your Thread:

Sub Run()
  For i As Integer = 0 To kCountTo
    
    ' Do background work here. No UI access allowed.
    ' It can be: database query, file read, API call, pretty much anything that might block "freeze" the UI of the app
    
    ' Prepare a Dictionary payload for the UI
    Var info As New Dictionary
    info.Value("progress") = i
    info.Value("message") = "working"
    Me.AddUserInterfaceUpdate(info)
    
    ' Sleep (optional)
    Thread.SleepCurrent(10)   // Sleep 10 ms
  Next
End Sub

The key line is Me.AddUserInterfaceUpdate(info). This queues data for the UI thread to process. Each call adds one item to a queue, and the UI thread drains it in UserInterfaceUpdate.

The Thread.UserInterfaceUpdate Method (UI Sync)

Implement this event to handle updates from the thread:

Sub UserInterfaceUpdate(data() As Dictionary)
  ' Runs on the main UI thread. Safe to update controls here.
  
  ' Guard against empty or malformed data
  If data = Nil Or data.Count < 0 Then Return
  
  Var d As Dictionary = data(0)
  
  ' Extract the progress value safely
  Var progress As Integer = 0
  If d.HasKey("progress") Then
    progress = d.Value("progress").IntegerValue
  End If
  
  ' Update the UI
  StatusLabel.Text = progress.ToString
  
  ' Mark completion when we hit the target
  If progress >= kCountTo Then
    StatusLabel.Text = "done"
  End If
End Sub

Important notes:

• data() is an array of Dictionaries.
• Always check HasKey before accessing a value to avoid runtime errors.
• Use .IntegerValue (or .StringValue, etc.) to safely extract values.
• This runs on the UI thread, so it is safe to update StatusLabel and any other visual controls.

How It Works

1. Button press: Click the button and the thread starts.
2. Background loop: The thread iterates from 0 to kCountTo, sleeping 10 ms each step. After each step, it queues an update.
3. Responsiveness: While the thread works, you can still interact with the rest of your application. No freezing.

A Note on Thread Safety

Threads are powerful but risky if misused. Here is the boundary:

• Safe in Run(): Anything that doesn’t touch UI controls. File I/O, database queries, calculations, network calls.
• Unsafe in Run(): Reading or writing UI control properties directly. StatusLabel.Text = ... is a no no!
• Safe in UserInterfaceUpdate(): All UI control access. This runs on the main thread.

If you forget this rule and try to update a label from inside Run(), your app will crash with a ThreadAccessingUIException. Instead pass data through AddUserInterfaceUpdate.

When to Use Threads vs. Timers

Use timers for:

• Short, frequent tasks (10-50 ms ticks).
• Simple progress updates.
• Cases where you are just deferring work a bit.

Use threads for:

• Long-running operations (seconds, minutes, hours).
• Genuinely blocking work (I/O, network, heavy calculations).
• Multiple independent background tasks.

In this series, we moved from blocking the UI to using timers on the UI thread, then to actual background threads. Each approach solves a different problem.

Wrapping Up

Threads are the heavy artillery of responsive design. They run independent of the UI and communicate safely via UserInterfaceUpdate. Once you grasp the boundary between thread code and UI code, you can build applications that never freeze, no matter how much work is happening behind the scenes.

See the Thread documentation for more details on priority, stack size, and advanced patterns.

Until then, happy threading!

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

Optimizing Code Series:

• Optimizing Xojo Code, Part 1: Getting Started
• Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive
• Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler
• Optimizing Xojo Code, Part 4: Timer.CallLater
• Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

For this example, we’ll use the x and y coordinate values of the sine and cosine functions as the data for our scatter DataSets. Go ahead and create a new Desktop project in the Xojo IDE.

Next, select the default Window1 and drag a DesktopChart control from the Library panel into the Layout Editor for Window1. Adjust the right margin to the recommended right layout guide, then lock the Top, Left, and Right layout locks for the Chart1 instance using the Inspector. At this point, your design should look similar to this:

While you’re there, select Chart1 and, in the Inspector, set the option Behavior > Mode to Scatter.

Next, with Window1 selected, add two properties using the following values:

Property 1:

• Name: CosStyle
• Type: ChartLinearStyle
• Scope: Private

Property 2

• Name: SineStyle
• Type: ChartLinearStyle
• Scope: Private

These properties will be used to store references to the Style objects associated with the cosine and sine function DataSets.

Finally, with Window1 still selected, add the Opening event and enter the following lines of code into the associated code editor:

CosStyle = New ChartLinearStyle
CosStyle.Line = ChartLinearStyle.LineTypes.Dashed

SineStyle = New ChartLinearStyle
SineStyle.Line = ChartLinearStyle.LineTypes.Solid

DrawScatterChart

In brief, this code creates new ChartLinearStyle instances for the properties added earlier. It assigns a solid line style to connect the cosine function data points and a dashed line style to connect the sine function data points. After that, it calls the DrawScatterChart method, which is responsible for rendering the sine and cosine functions on the Chart1 instance.

Now, let’s create that method on Window1 using the following values in the Inspector:

• Name: DrawScatterChart
• Scope: Private

Type the following snippet of code in the associated Code Editor for the method:

// These are the Array variables in charge of storing the Scatter data points
// for the Sine and Cosine functions
Var sinePoints() As ChartScatterDatapoint
Var cosinePoints() As ChartScatterDatapoint

// …and these variables will handle the DataSet instances
// for the previous arrays of data points on both functions
Var sineDataSet As ChartScatterDataset
var cosDataSet As ChartScatterDataset

Const pi = 3.14159265359
Var y As Double
Var maxXValue As Double = 2.0 * pi

// Using a simple loop to feed the x and y
// values for the Sine and Cosine
For x As Double = 0.0 To maxXValue Step 0.5
  
  y = Sin(x)
  sinePoints.Add(New ChartScatterDatapoint(x, y, 1))
  
  y = Cos(x)
  cosinePoints.Add(new ChartScatterDatapoint(x, y, 1))
  
Next

// Next, we create the new instances for the Scatter DataSets
sineDataSet = New ChartScatterDataset(Color.Blue, sinePoints)
cosDataSet = New ChartScatterDataset(color.Red, cosinePoints)

// …and we set the Style to be used on each of them
sineDataSet.Style = SineStyle
cosDataSet.Style = CosStyle

// … and of course the labels to be shown on the Legend section
// of the chart itself
sineDataSet.Label = "Sine Function"
cosDataSet.Label = "Cos Function"

// As the last step, we add both DataSets to the chart
// so these can be rendered
Chart1.AddDatasets(sineDataSet, cosDataSet)

Run the app, and it should look similar to this:

A change of Style… on the fly!

As with many aspects of DesktopChart, any changes made at runtime are reflected immediately, without the need to redraw the chart, re-feed the data sets, or perform any other complex operations. Let’s take advantage of this by changing the sine and cosine styles at runtime, allowing users of our example app to toggle whether the points are connected.

Add two DesktopCheckBox controls below the bottom margin of the Chart1 instance on Window1. Set the Caption of the first checkbox to “Connect Sine Points” and the second to “Connect Cos Points.” For both checkboxes, use the Inspector to set Initial State > Visual State to Checked.

The final layout should look similar to this:

Lastly, add the ValueChanged event to both CheckBox instances. Then, for the checkbox with the caption “Connect Sine Points,” add the following lines of code to its event handler:

If Me.Value Then
  SineStyle.Line = ChartLinearStyle.LineTypes.Dashed
Else
  SineStyle.Line = ChartLinearStyle.LineTypes.None
End If

Add the following lines of code to the ValueChanged event handler for the checkbox with the caption “Connect Cos Points”:

If Me.Value Then
  CosStyle.Line = ChartLinearStyle.LineTypes.Solid
Else
  CosStyle.Line = ChartLinearStyle.LineTypes.None
End If

Run the app again and, this time, click each checkbox to see how the points are no longer connected when a checkbox is unchecked, and are connected when it is selected.

Summary

As you can see, styles can be used not only to connect points in a Scatter chart, but also to customize the point endpoints beyond the default appearance. For example, you can set the endpoint to “None” or choose from many other available options. Even better, any changes made to a style at runtime are applied immediately.

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

Now, for even simpler one-off or chained delayed tasks, Xojo offers Timer.CallLater: no Timer instance required.

The Strategy: Timer.CallLater

Timer.CallLater(milliseconds, AddressOf MethodName, arg As Variant) schedules your method to run after the specified delay on the main UI thread. Pass data via the Variant parameter. To chain calls (like our countdown), re-call it from within the method. Use Timer.CancelCallLater(AddressOf MethodName) to abort pending calls.

For full details, see the Timer documentation.

Looking at the Code

Prerequisites: Add a StatusLabel (DesktopLabel control) and a constant kCountTo As Integer = 20000.

Let’s look at how we implement this.

The Setup (Button Pressed)

Place the following code in the Pressed event handler of a button control:

Sub Pressed()
  Timer.CancelCallLater(AddressOf UpdateProgress)
  
  StatusLabel.Text = "0"
  
  Timer.CallLater(100, AddressOf UpdateProgress, 100)
End Sub

The Handler (Recursive Chain)

Create the following method that handles the recursive chain of delayed updates:

Sub UpdateProgress(elapsedMs As Variant)
  Var elapsed As Integer = elapsedMs.IntegerValue
  
  If elapsed >= kCountTo Then

    StatusLabel.Text = "done"

  Else

    StatusLabel.Text = elapsed.ToString
    Timer.CallLater(100, AddressOf UpdateProgress, elapsed + 100)

  End If
End Sub

Crucial Note: The handler method must accept a Variant parameter to receive the argument passed to CallLater. Always use type-safe extraction like .IntegerValue.

How It Works

1. Initial Schedule: The button cancels any pending calls and schedules the first UpdateProgress after 100ms, passing 100 as the elapsed time (just in case we like pressing a button multiple times quickly).
2. Recursion: Each call updates the UI and, if not finished, schedules the next one 100ms in the future with incremented elapsed time.
3. Automatic Management: No Timer properties or handlers to manage; Xojo handles scheduling and cleanup.
4. Cancellation: Ensures only one chain runs at a time.

Wrapping Up

Timer.CallLater shines for delayed UI updates or chained tasks without the overhead of Timer objects. It’s concise, safe, and powerful for responsive apps.

In Part 5, we’ll tackle true background processing with Threads and UserInterfaceUpdate.

Until then, happy coding!

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

Optimizing Code Series:

• Optimizing Xojo Code, Part 1: Getting Started
• Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive
• Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler
• Optimizing Xojo Code, Part 4: Timer.CallLater
• Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

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

At a high level, the workflow looks like this:

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

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

Visual States in XAML

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

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

Example XAML

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

<UserControl>
  <Grid>
    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup Name="FlameStates">

        <VisualState Name="Bottom">
          <Storyboard>
            <DoubleAnimation
              Storyboard.TargetName="FlameTransform"
              Storyboard.TargetProperty="Y"
              To="40"
              Duration="0:0:1" />
          </Storyboard>
        </VisualState>

        <VisualState Name="Top">
          <Storyboard>
            <DoubleAnimation
              Storyboard.TargetName="FlameTransform"
              Storyboard.TargetProperty="Y"
              To="-100"
              Duration="0:0:1" />
          </Storyboard>
        </VisualState>

      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>

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

      <TextBlock.RenderTransform>
        <TranslateTransform Name="FlameTransform" />
      </TextBlock.RenderTransform>

    </TextBlock>
  </Grid>
</UserControl>

In this XAML:

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

Triggering the Transition from Xojo

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

XAMLContainer1.GotoState("Top")

And to move it back down:

XAMLContainer1.GotoState("Bottom")

Why This Is Powerful

What makes this feature especially useful is that:

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

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

<UserControl>
  <Grid Width="160" Height="240">

    <!-- Fire emoji 1 -->
    <TextBlock Name="Fire1"
           Text="🔥"
           FontSize="32"
           VerticalAlignment="Bottom"
           HorizontalAlignment="Center">
      <TextBlock.RenderTransform>
        <TranslateTransform Name="Move1"/>
      </TextBlock.RenderTransform>
    </TextBlock>

    <!-- Fire emoji 2 -->
    <TextBlock Name="Fire2"
           Text="🔥"
           FontSize="26"
           VerticalAlignment="Bottom"
           HorizontalAlignment="Center"
           Margin="20,0,0,0"
           Opacity="0.8">
      <TextBlock.RenderTransform>
        <TranslateTransform Name="Move2"/>
      </TextBlock.RenderTransform>
    </TextBlock>

    <!-- Fire emoji 3 -->
    <TextBlock Name="Fire3"
           Text="🔥"
           FontSize="22"
           VerticalAlignment="Bottom"
           HorizontalAlignment="Center"
           Margin="-20,0,0,0"
           Opacity="0.7">
      <TextBlock.RenderTransform>
        <TranslateTransform Name="Move3"/>
      </TextBlock.RenderTransform>
    </TextBlock>

    <VisualStateManager.VisualStateGroups>
      <VisualStateGroup Name="FireStates">

        <VisualState Name="Off"/>

        <VisualState Name="On">
          <Storyboard RepeatBehavior="Forever">

            <!-- Fire 1 -->
            <DoubleAnimation Storyboard.TargetName="Move1"
                     Storyboard.TargetProperty="Y"
                     From="0"
                     To="-180"
                     Duration="0:0:1.2"/>

            <DoubleAnimation Storyboard.TargetName="Move1"
                     Storyboard.TargetProperty="X"
                     From="0"
                     To="10"
                     Duration="0:0:0.6"
                     AutoReverse="True"/>

            <!-- Fire 2 -->
            <DoubleAnimation Storyboard.TargetName="Move2"
                     Storyboard.TargetProperty="Y"
                     From="0"
                     To="-160"
                     Duration="0:0:1.0"
                     BeginTime="0:0:0.3"/>

            <DoubleAnimation Storyboard.TargetName="Move2"
                     Storyboard.TargetProperty="X"
                     From="0"
                     To="-12"
                     Duration="0:0:0.5"
                     AutoReverse="True"/>

            <!-- Fire 3 -->
            <DoubleAnimation Storyboard.TargetName="Move3"
                     Storyboard.TargetProperty="Y"
                     From="0"
                     To="-140"
                     Duration="0:0:1.4"
                     BeginTime="0:0:0.15"/>

            <DoubleAnimation Storyboard.TargetName="Move3"
                     Storyboard.TargetProperty="X"
                     From="0"
                     To="8"
                     Duration="0:0:0.7"
                     AutoReverse="True"/>

          </Storyboard>
        </VisualState>

      </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>

  </Grid>
</UserControl>

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

XAMLContainer1.GotoState("On")

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

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

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

But what if you need a timer inside a Class or a Module where you can’t drop a visual control?

The Strategy: AddHandler

When you use a Timer control from the library, you double-click it to add an Action event. When we create a Timer in code, we don’t have a “code editor” for it in the same way. Instead, we use the AddHandler command to tell Xojo: “When this timer fires its Action event, run this specific method instead.”

Looking at the Code

Let’s look at how we implement this. In our example project, we have a button that initializes our timer and a separate method to handle the “ticks.”

The Setup

First, we define a property on our window (or class) to hold our timer: mWaitTimer As Timer

Then, in the Pressed event of our button, we instantiate it:

Sub Pressed() Handles Pressed
  ' 1. Cleanup
  If mWaitTimer <> Nil Then
    mWaitTimer.RunMode = Timer.RunModes.Off
    mWaitTimer = Nil
  End If
  
  ' 2. Initialization
  mElapsedMs = 0
  StatusLabel.Text = "0"
  
  ' 3. Create the dynamic timer
  mWaitTimer = New Timer
  mWaitTimer.Period = 100 ' 100 ms tick
  mWaitTimer.RunMode = Timer.RunModes.Multiple
  
  ' 4. The Magic: Link the Action event to our WaitTick method
  AddHandler mWaitTimer.Action, AddressOf WaitTick
End Sub

The Handler (Doing the Work)

Now, let’s create the method named WaitTick. Crucial Note: When using AddHandler for a Timer, the first parameter of your receiving method must be of the type Timer so it knows which object triggered it.

Sub WaitTick(t As Timer)
  mElapsedMs = mElapsedMs + t.Period
  
  If mElapsedMs >= kCountTo Then
    ' Achievement unlocked! Stop the timer and clean up
    t.RunMode = Timer.RunModes.Off
    StatusLabel.Text = "done"
    
    ' It's good practice to remove the handler when done
    RemoveHandler t.Action, AddressOf WaitTick
  Else
    StatusLabel.Text = mElapsedMs.ToString
  End If
End Sub

How It Works

1. New Timer: We create a new instance of the Timer class in memory.
2. AddHandler: This command connects the Action event of our new timer to the WaitTick method. The AddressOf operator tells Xojo the memory location of the code we want to run.
3. Passing the Object: Because WaitTick receives t As Timer as a parameter, you can actually use the same handler for multiple different timers and knows exactly which one is calling for attention.

Wrapping Up

By moving your Timers into code, you take a significant step toward writing more modular Xojo applications. You’ve moved the logic from “Global UI state” into “Managed Code execution.”

In the upcoming Part 4, we’ll look at a shortcut that makes one-off background tasks a breeze: Timer.CallLater.

Until then, happy coding and don’t forget to add your own solution in the Xojo Forum!

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

Optimizing Code Series:

• Optimizing Xojo Code, Part 1: Getting Started
• Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive
• Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler
• Optimizing Xojo Code, Part 4: Timer.CallLater
• Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

When you create a Library in Xojo, it’s tailored to the project type you’re working in, whether that is Desktop, Web, Mobile or Console, so everything stays organized and easy to manage. The Library format was designed to support all project types simultaneously; unfortunately, the Xojo IDE was not. The good news is that there are still ways to take advantage of the flexible underlying format. Since Libraries are simply .zip files, you can change the extension to .zip and decompress them to explore their contents. Inside, you’ll find a folder named for the project type you originally created it from, making it easy to understand the structure. Here are two ways to create Libraries that support multiple project types.

Merging Libraries Manually

To manually create a multi-project-type Library, start by building a separate Library for each project type your functionality supports, then change each one’s extension to .zip and decompress it. Choose one decompressed Library to serve as the final version, and copy the project-type folders (Desktop, Web, iOS, Android or Console) from the others into it. When everything is combined, recompress the folder back into a .zip file and change the extension to .xojo_library. You now have a single Library that works across all the project types you included.

Using LibMerge

LibMerge is a utility we created to make it easier to merge Libraries.

1. Download LibMerge for Linux, macOS or Windows. It will be included in the Extras folder in the next major release.
2. Launch LibMerge and then click the Add button to select the Libraries you wish to merge or drag them into the Libraries list in the LibMerge window.
3. On the Info tab, make sure the Version, Copyright and Description values are as you want them for the merged Library. These initial values are loaded from the first Library you add to the list.
4. Click the Save As button to choose a name and location for your merged Library. That’s it!

If you choose two libraries that both already support the same project type, LibMerge will tell you and not load the second Library. Included with LibMerge is the LibMerge Library which you can use to build the merging of Libraries into your own build tools. Check out the included LibMerge API Guide for details. Here is an example:

Try
   Var merge As New LibMerger
   merge.AddLibrary(SpecialFolder.Desktop.Child("MyDesktopLibrary.xojo_library"))
   merge.AddLibrary(SpecialFolder.Desktop.Child("MyWebLibrary.xojo_library"))
   merge.SaveMergedLibrary(SpecialFolder.Desktop.Child("MergedLibrary.xojo_library"))
Catch error as UnsupportedFormatException
   System.Beep
   MessageBox(error.Message)
End Try

Whether you prefer to roll up your sleeves and merge Libraries manually or let LibMerge handle the heavy lifting, Xojo gives you the flexibility to build reusable components that work across all your project types. With a little exploration and the right tools you can streamline your workflow, reduce duplication and keep your projects cleaner and more maintainable. LibMerge makes this process fast and reliable whether you’re merging two Libraries or twenty. Read more about Libraries in the Xojo Documentation.

Geoff Perlman is the Founder and CEO of Xojo. When he’s not leading the Xojo team he can be found playing drums in Austin, Texas and spending time with his family.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Step 1: Let’s sketch the goal

We will need a button that, when pressed, starts a simulated wait that updates a label every 100 ms until a fixed duration (kCountTo, which remains 20000 ms in our example) is reached. So, the timer will fire periodically and handle the counting there. The button simply resets state and starts the timer.

Step 2: Prepare the UI components

Create a DesktopLabel named StatusLabel to display progress.
Add a DesktopButton (caption it “Method 1”) whose Pressed event will kick off the timer.
Finally, place a Timer control onto the window, name it mTimer, set its Period to 100, and set RunMode to Multiple (but leave it off until the button starts it).
Add an Integer property to the window such as mMsWaited to accumulate elapsed milliseconds, and keep kCountTo defined as 20000.

Step 3: Wire up the button

The button handler becomes very simple. Reset the tracked milliseconds, show "0" in the label, ensure the timer runs at 100 ms ticks, and let it fire repeatedly:

Sub Pressed()
  // Reset the tracked elapsed ms and start the timer at 100 ms ticks.
  mMsWaited = 0
  StatusLabel.Text = "0"
  mTimer.Period = 100
  mTimer.RunMode = Timer.RunModes.Multiple
End Sub

This code primes the state but does not block. The timer will perform the actual counting.

Step 4: Let the timer take over

Implement mTimer.Action to run on the UI thread. Each tick adds the timer’s period to mMsWaited, updates the label, and turns itself off once kCountTo has been reached:

Sub Action()
  mMsWaited = mMsWaited + Me.Period

  If mMsWaited >= kCountTo Then
    Me.RunMode = Timer.RunModes.Off
    StatusLabel.Text = "done"
  Else
    StatusLabel.Text = mMsWaited.ToString
  End If
End Sub

This keeps your UI responsive because the timer fires briefly and returns control back to the event loop instead of spinning inside a While loop.

Step 5: Test the flow

Run the app, click the button previously created and watch the label count up and stop at the target value. The timer approach lets other interface interactions remain responsive while still providing clear progress feedback.

What makes this timer driven solution a solid first step?

It shows how you can preserve the original behavior while giving the UI breathing room. It avoids App.DoEvents, reduces tight loops, and still delivers frequent updates. In the next article we’ll build on this idea and explore alternative approaches that continue to improve responsiveness and structure.

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

Optimizing Code Series:

• Optimizing Xojo Code, Part 1: Getting Started
• Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive
• Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler
• Optimizing Xojo Code, Part 4: Timer.CallLater
• Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

Now, we’re going to tackle another key feature: customizable text alignment. By the end of this tutorial, you’ll be able to set the button’s text to align left, center, or right, and we’ll introduce a small amount of padding to keep the text from touching the edges when it’s not centered. This approach uses a strongly typed Enumeration to ensure we only accept valid alignment values, maintaining the high quality of our custom control.

1. Define the Text Alignment Options

To make our alignment property easy to use and type-safe, we will define a new enumeration inside the CanvasButton class.

Inside your CanvasButton class, go to Insert > Enumeration and add the following:

  Left = 0
  Center = 1
  Right = 2

2. Add New Properties for Alignment and Padding

Next, we need two new properties in the CanvasButton class to store the selected alignment and the padding value.

The TextAlignment property will use our new TextAlign enumeration, and, crucially, it defaults to TextAlign.Center.
The TextPadding property provides an adjustable inner margin, which is especially important for left and right alignment.

Public Property TextAlignment As TextAlign = TextAlign.Center
Public Property TextPadding As Integer = 8

3. Update the Paint Method

The core of this change happens in the Paint event handler. We need to modify the logic that calculates the horizontal position of the text (tx) to respect the value of our new TextAlignment property.

Locate the Paint event and replace the existing code with the following:

Sub Paint(g As Graphics, areas() As Rect) Handles Paint
  #Pragma unused areas
  
  // Use the custom CornerRadius property.
  Var currentCornerRadius As Integer = CornerRadius
  
  // Declare variables for the colors used in drawing.
  Var currentBgColor As Color
  Var currentBorderColor As Color
  Var currentTextColor As Color
  
  // Determine colors based on the button's current state (enabled, pressed, hovered).
  If Enabled Then
    If IsPressed Then
      // Use highlight color if pressed.
      currentBgColor = HighlightColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    ElseIf IsHovered Then // Check for hover only if not pressed
      // Use hover color if hovered.
      currentBgColor = HoverColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    Else
      // Use the custom background color for the default state.
      currentBgColor = BackgroundColor
      currentBorderColor = BorderColor
      currentTextColor = TextColor
    End If
  Else
    // Use appropriate system or standard gray colors for the disabled state.
    currentBgColor = Color.LightGray
    currentBorderColor = Color.Gray
    currentTextColor = Color.DisabledTextColor // Use system disabled text color
  End If
  
  // Set the drawing color and draw the background shape with rounded corners.
  g.DrawingColor = currentBgColor
  g.FillRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)
  
  // Set the drawing color and pen size for the border.
  g.DrawingColor = currentBorderColor
  g.PenSize = 2
  // Draw the border shape just inside the background rectangle.
  g.DrawRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)
  
  // Draw the focus ring
  If IsFocused And AllowFocusRing Then
    g.DrawingColor = Color.HighlightColor
    g.PenSize = 1
    g.DrawRoundRectangle(2, 2, g.Width-4, g.Height-4, CornerRadius-2, CornerRadius-2)
  End If
  
  // Enable anti-aliasing for smoother text rendering.
  g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
  g.AntiAliased = True
  // Calculate the width and height of the button text.
  Var tw As Double = g.TextWidth(ButtonText)
  Var th As Double = g.TextHeight
  // Calculate the X position to center the text horizontally.
  // Updated: compute X based on TextAlignment (Left, Center, Right) while preserving centered behavior as default.
  Var tx As Double
  Select Case TextAlignment
  Case TextAlign.Left
    tx = TextPadding
  Case TextAlign.Right
    tx = g.Width - tw - TextPadding
  Case TextAlign.Center
    tx = (g.Width - tw) / 2
  End Select
  // Calculate the Y position to center the text vertically, with a small adjustment.
  Var ty As Double = (g.Height + th) / 2 - 3
  // Set the drawing color for the text.
  g.DrawingColor = currentTextColor
  // Draw the button text at the calculated centered position.
  g.DrawText(ButtonText, tx, ty)
End Sub

The magic happens at line 60

4. Inspector Integration

If you want the alignment to be easily adjustable in the Xojo Inspector, you should expose the TextAlignment and TextPadding properties. For TextAlignment, because it uses an Enumeration, Xojo will automatically display a helpful dropdown menu with Left, Center, and Right options once you expose it through the Inspector Behavior editor.

• Right-click the CanvasButton class in the Project Navigator.
• Select ‘Inspector Behavior…’
• Scroll through the property list and check the checkboxes for both TextAlignment and TextPadding.

Try It Out

You can now set the text alignment directly in the code or via the Inspector.

For example, to set alignment in code:

// Set the button to right-aligned text
MyCanvasButton.TextAlignment = CanvasButton.TextAlign.Right

Since the default value for TextAlignment is Center, no existing code needs to be modified, and all your current custom buttons will continue to render perfectly centered unless you explicitly change the alignment property.

Hope this update was useful.

You can grab the latest source on GitHub: GitHub – CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

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

• Modules: organize shared helpers that don’t store data. They just do a job and return a result.
• Classes: represent objects that keep data and have actions.
• Interfaces: agreements about what methods exist so parts can work together without caring how they’re built.
• Delegates: a way to pass a function around so another part of your app can call it later (a callback).

Modules

Purpose

• Provide a namespace for related helpers, constants, and enums.
• Offer reusable helpers that don’t remember data between calls.
• Add extension methods that make calling code cleaner.

Use when

• You need shared helpers (formatting, parsing, conversions).
• You want to group constants/enums (error codes, log levels).
• You’re adding behavior to existing types via extension methods.

Avoid when

• You’re tempted to store changeable global data that creates hidden dependencies.

Benefits

Read more: Xojo Modules Documentation

Classes

Purpose

• Represent real concepts in your app (e.g., an order, a report, a session).
• Keep data and the related rules/actions in one place.
• Separate concerns: core logic in classes, screen logic in the UI.

Use when

• You have data that changes over time and rules to enforce.
• You need services that coordinate steps (for example, “Export report” or “Sync data”).
• You want testable units that don’t depend on UI elements.

Avoid when

• You only need a simple helper that returns a result (that belongs in a Module).
• Platform-specific calls would leak into core logic (hide those behind Interfaces).

Benefits

• Clear rules kept close to the data they protect.
• Clean boundaries between UI, core logic, and data access.

Read more: Xojo OOP Classes Documentation

Interfaces

Purpose

• Define the what without the how.
• Let you swap implementations (e.g., memory vs. SQLite vs. REST) without changing calling code.
• Make testing simple by substituting fakes/mocks.

Use when

• A feature may vary by platform or environment (file system, keychain, camera, notifications).
• You want to keep app logic separate from the details of databases, files, or network calls.
• You’ll have multiple strategies that share the same shape.

Avoid when

• There’s only one implementation and you don’t need to test in isolation.

Benefits

• Loose coupling and easier future changes.
• Cleaner, more stable internal APIs.

Read more: Xojo Interfaces Documentation

Delegates

Purpose

• Provide type-safe callbacks by letting you hand a function to another part of your app.
• Enable flexible behavior without defining a whole interface and class.
• Power progress updates, cancel handlers, filters, or small strategies.

Use when

• You need a one-off callback (progress, completion, error reporting).
• You want to inject small pieces of behavior (sorting, filtering, formatting).
• You’re wiring up dynamic behavior at runtime.

Avoid when

• You need a broader contract with multiple related methods (use an Interface instead).
• You need lifecycle or semantic grouping (a Class with events may be clearer).

Benefits

• Lightweight and expressive.
• Less boilerplate than creating full classes for simple callbacks.
• Encourages small, composable, testable pieces.

Read more: Xojo Delegates Documentation

Quick Decision Guide

• I need to group common helpers and constants. → Module
• I’m modeling an object with data and rules. → Class
• I want to depend on behavior, not a specific implementation. → Interface
• I need a small callback or injected behavior. → Delegate
• I need many subscribers to a lifecycle change. → Event on a class

Quick glossary

• Interface: a contract, a named list of methods something promises to have.
• Delegate: a variable that holds a function to call later (a callback).
• Event: a signal that something happened; other parts can listen for it.

Use Modules to organize shared helpers, Classes to model your world, Interfaces to decouple and swap implementations, and Delegates to pass behavior flexibly. Combined thoughtfully, these features keep Xojo projects easy to change, easy to test, and ready to ship across platforms.

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

Let’s build a simple but incredibly powerful Desktop app: a threaded image resizer. This tool will let you pick a folder of images and resize them all without ever locking up the app. It’s a perfect showcase of how easy and effective threading can be in Xojo.

Let’s get started!

Step 1: Designing the User Interface

First things first, let’s lay out our app’s window. We’re going for a clean and simple design. All you need to do is create a new Xojo Desktop project and add the following controls from the Library onto your main window:

1. DesktopButton: This will be our “start” button. The user will click this to select a folder and begin the resizing process. Let’s set its Caption to “Select folder && Start”.
2. DesktopProgressBar: This will give the user visual feedback on the progress of the resizing operation.
3. DesktopLabel: We’ll use this label to display status updates, like which file is currently being processed or when the job is complete. Let’s call it StatusLabel.

Your app layout should look something like this:

Step 2: Adding the Magic Ingredient: The Thread

Now for the star of the show! Go to the Library and find the Thread object. Drag and drop one onto your window. By default, it might be named Thread1, but I’ve renamed mine to ResizeThread to make its purpose crystal clear. This object is where our background work will happen.

Quick note on thread types: Cooperative threads (the default) share a single CPU core with the main/UI thread and other cooperative threads. Preemptive threads can run on separate CPU cores and deliver true parallelism for CPU-bound work. More info on this subject: Cooperative to Preemptive: Weaving New Threads into your Apps

Why this project uses Preemptive threads: resizing many images is CPU-bound and benefits from parallel cores without blocking the UI.

Step 3: Kicking Off the Process

With the UI and thread in place, let’s add the code to get things moving. Double-click the “Select folder & Start” button to add its Pressed event. This is what will run when the user clicks it.

Here’s the code for the Pressed event:

' Ask the user for a source folder (contains images)
Var f As FolderItem = FolderItem.ShowSelectFolderDialog
If f = Nil Then Return ' user cancelled

mSourceFolder = f

' Reset UI
ProgressBar1.Value = 0
StatusLabel.Text = "Starting…"

' Kick off background work!
ResizeThread.Start

Let’s break this down. First, we ask the user to select a folder. If they don’t pick one, we simply exit. If they do, we store the selected folder in a window property called mSourceFolder (Public Property mSourceFolder As FolderItem). We then reset our progress bar and status label and, most importantly, we call ResizeThread.Start. That one simple line tells our thread to wake up and get to work by running its Run event.

Step 4: The Heavy Lifting (in the Background)

The Run event of the ResizeThread is where the core logic lives. This is where we’ll find, load, resize, and save the images. Remember, the golden rule of threads is: never touch the UI directly from the Run event. Doing so can cause crashes and unpredictable behavior.

Instead, we perform our task and then send a message back to the main thread with an update. We do this using a method called AddUserInterfaceUpdate.

Here’s the Run event code:

' Quick validation up-front
If mSourceFolder = Nil Or Not mSourceFolder.Exists Or Not mSourceFolder.IsFolder Then
  Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"No folder selected"))
  Return
End If

Try
  ' Ensure output subfolder "<selected>/resized" exists
  Var outFolder As FolderItem = mSourceFolder.Child("resized")
  If Not outFolder.Exists Then outFolder.CreateFolder
  
  ' Build a list of candidate image files.
  ' Note: Using Picture.Open to validate images is simple and robust.
  '       (For very large folders, you could pre-filter by extension first.)
  Var images() As FolderItem
  For Each it As FolderItem In mSourceFolder.Children
    If it = Nil Or it.IsFolder Then Continue ' Ignore subfolders
    Try
      Var p As Picture = Picture.Open(it)
      If p <> Nil Then images.Add(it)
    Catch e As RuntimeException
      ' Non-image or unreadable; skip
    End Try
  Next
  
  Var total As Integer = images.Count
  If total = 0 Then
    Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"No images found"))
    Return
  End If
  
  ' Resize settings (simple “fit within 800x800” bounding box)
  Const kMaxW As Double = 800.0
  Const kMaxH As Double = 800.0
  
  ' Short delay after each file so the main thread can repaint the UI
  Const kDelayMS As Integer = 50
  
  For i As Integer = 0 To total - 1
    Var src As FolderItem = images(i)
    Try
      ' Load source (immutable)
      Var pic As Picture = Picture.Open(src)
      If pic = Nil Or pic.Width <= 0 Or pic.Height <= 0 Then Continue
      
      ' Compute proportional scale (never upscale)
      Var sW As Double = kMaxW / pic.Width
      Var sH As Double = kMaxH / pic.Height
      Var scale As Double = Min(Min(sW, sH), 1.0)
      
      Var newW As Integer = Max(1, pic.Width * scale)
      Var newH As Integer = Max(1, pic.Height * scale)
      
      ' Render into a new mutable bitmap of the target size
      Var outPic As New Picture(newW, newH)
      outPic.Graphics.DrawPicture(pic, 0, 0, newW, newH, 0, 0, pic.Width, pic.Height)
      
      ' Build a safe base name (strip the last extension; handle dotfiles)
      Var name As String = src.Name
      Var ext As String = name.LastField(".")
      Var baseName As String
      If ext = name Then
        ' No dot in the name
        baseName = name
      Else
        baseName = name.Left(name.Length - ext.Length - 1)
      End If
      If baseName.Trim = "" Then baseName = "image"
      
      ' Save JPEG (fallback PNG if JPEG export not supported)
      Var outFile As FolderItem = outFolder.Child(baseName + "_resized.jpg")
      If Picture.IsExportFormatSupported(Picture.Formats.JPEG) Then
        outPic.Save(outFile, Picture.Formats.JPEG, Picture.QualityHigh) ' adjust the quality of the jpeg here
      Else
        outPic.Save(outFolder.Child(baseName + "_resized.png"), Picture.Formats.PNG)
      End If
      
    Catch io As IOException
      ' Likely a write/permission/disk issue; skip this file
    Catch u As UnsupportedOperationException
      ' Unsupported format/operation on this platform; skip
    End Try
    
    ' Progress + message to the UI (safe handoff)
    Var pct As Integer = ((i + 1) * 100) / total
    Me.AddUserInterfaceUpdate(New Dictionary("progress":pct, _
    "msg":"Resized " + src.Name + " (" + pct.ToString + "%)"))
    
    ' Let the main thread paint the update
    Me.Sleep(kDelayMS, True) ' wakeEarly=True allows early resume when idle
  Next
  
  ' Final UI message
  Me.AddUserInterfaceUpdate(New Dictionary("progress":100, "msg":"Done"))
  
Catch e As RuntimeException
  ' Any unexpected failure: report a friendly error
  Me.AddUserInterfaceUpdate(New Dictionary("progress":0, "msg":"Error: " + e.Message))
End Try

Step 5: Receiving Updates and Safely Changing the UI

So, how does the main thread “hear” these updates? Through the UserInterfaceUpdate event on the ResizeThread itself! This event fires on the main thread, making it the one and only safe place to update our controls.

Here’s the code for the UserInterfaceUpdate event:

' This event runs on the main thread – SAFE to update controls here.
If data.Count = 0 Then Return

Var latest As Dictionary = data(data.LastIndex)

If latest.HasKey("progress") Then ProgressBar1.Value = latest.Value("progress")
If latest.HasKey("msg") Then StatusLabel.Text = latest.Value("msg")

' A little bonus: when we are done, open the output folder!
If latest.HasKey("msg") And latest.Value("msg") = "Done" Then
  Var outFolder As FolderItem = mSourceFolder.Child("resized")
  If outFolder <> Nil And outFolder.Exists Then
    outFolder.Open
  End If
End If

In this event, we receive an array of Dictionaries (all the updates that have queued up). We usually only care about the very latest one, so we grab data(data.LastIndex). Then, we safely access the values from the dictionary and assign them to ProgressBar1.Value and StatusLabel.Text. That’s it!

Conclusion

And there you have it! A fully functional, non-blocking image resizer. By moving the heavy work to a Thread, we’ve created an application that provides a smooth, professional user experience.

The pattern is simple:

1. Start the task from the main thread (ResizeThread.Start).
2. Work inside the thread’s Run event.
3. Communicate back to the UI with AddUserInterfaceUpdate.
4. Update the UI safely in the UserInterfaceUpdate event.

That’s pretty much it! Go ahead, download this project’s source code from GitHub, play around with it, and think about how you can use threads in your own applications!

Happy coding!

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

This guide focuses on production-ready Caddy configurations that streamline deployments for self-managed Xojo applications, delivering:

• Automated TLS certificate management
• Native load balancing between instances
• Simplified configuration compared to traditional proxies
• Header optimizations specifically tuned for Xojo’s framework

You’ll learn configuration strategies that in some benchmarks, can have resource savings as high as 40% over conventional proxies while maintaining Xojo’s signature performance characteristics.

Core Configuration Strategies

Basic Reverse Proxy Setup

yourdomain.com {
    # Connect to Xojo application
    reverse_proxy localhost:8080 {
        # Preserve client information
        header_up X-Forwarded-For {http.request.remote.host}
        header_up Host {http.request.host}
    }
    
    # Automate HTTPS
    tls admin@yourdomain.com
}

Note: The header_up directives ensure Xojo correctly logs client IPs in web events

Load Balancing Across Instances

app.yourdomain.com {
    reverse_proxy localhost:8080 localhost:8081 localhost:8082 {
        load_balancer {
            policy round_robin
            health_interval 10s
            health_uri /health
        }
        # Timeouts for heavy processing
        lb_try_duration 30s
    }
}

Security Hardening Measures

yourdomain.com { 
	# Critical protection headers 
	header { 
		X-Content-Type-Options "nosniff" 
		X-Frame-Options "DENY" 
		Content-Security-Policy "default-src 'self'" 
	} 

	# Rate limiting for API endpoints 
	route /api/* { 
		rate_limit { 
			zone api 
			burst 100 
			period 10s 
		} 
	} 
}

Production-Ready Deployment Scripts

Linux Systemd Service
/etc/systemd/system/xojo-caddy.service:

[Unit]
Description=Xojo Caddy Reverse Proxy
After=network.target

[Service]
Type=simple
User=caddy
ExecStart=/usr/bin/caddy run --config /etc/caddy/Caddyfile
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

For a broader, step-by-step guide on preparing your server, please see our foundational tutorial: Tutorial: Deploying Web Apps on Linux. The systemd service above integrates perfectly into that workflow.

Windows Deployment Package
Xojo-Caddy.bat:

@echo off
REM Start Xojo application instances
start "Xojo Instance 1" /MIN XojoWebApp.exe --port=8080
start "Xojo Instance 2" /MIN XojoWebApp.exe --port=8081

REM Launch Caddy reverse proxy
start "Caddy Proxy" /MIN caddy.exe run --config C:\caddy\Caddyfile

Optimized Xojo-Caddy Template
Save as Caddyfile in your deployment root:

# Production-Grade Xojo Proxy Template
yourdomain.com, www.yourdomain.com {
    # Automated HTTPS
    tls contact@yourdomain.com
    
    # Primary app routing
    reverse_proxy localhost:8080 localhost:8081 {
        header_up X-Forwarded-Proto https
        header_up X-Real-IP {http.request.remote}
    }
    
    # Static content handling
    handle /static/* {
        root * /var/www/static
        file_server
    }
    
    # Security headers
    header {
        Strict-Transport-Security "max-age=31536000"
        Referrer-Policy "strict-origin-when-cross-origin"
    }
}

Conclusion

Caddy eliminates proxy complexity while delivering enterprise capabilities:

1. Simplified Operations: Single configuration file replaces complex proxy setups
2. Automatic Security: Continuous HTTPS protection without maintenance
3. Effortless Scaling: Built-in load balancing grows with your user base
4. Reduced Overhead: 40% fewer resources than traditional proxies in benchmarks

Implement the provided Xojo-Caddy template to achieve production-grade deployment in under 15 minutes. Monitor performance via Caddy’s built-in /metrics endpoint and scale horizontally as traffic increases.

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

• Tab to the button
• See a neat focus ring when it has focus
• Grab focus on click

1. Track the Focus State

Add a private property to keep track of whether the button has focus:

  Private IsFocused As Boolean = False

2. Respond to Focus Events

Implement FocusReceived and FocusLost so we can set/clear the flag and force a redraw:

  Sub FocusReceived()
    If Enabled And AllowFocusRing Then
      IsFocused = True
      Refresh(False)
    End If
  End Sub

  Sub FocusLost()
    If Enabled And AllowFocusRing Then
      IsFocused = False
      Refresh(False)
    End If
  End Sub

3. Grab Focus on Mouse Click

Modify your MouseDown to call SetFocus. Now clicking the button also gives it focus immediately:

  Function MouseDown(x As Integer, y As Integer) As Boolean
    #Pragma unused x
    #Pragma unused y

    If Enabled Then
      IsPressed = True
      SetFocus       // ← new
      Refresh(False)
      Return True
    Else
      Return False
    End If
  End Function

4. Draw an Inset Focus Ring

In the Paint event, after drawing the border, add:

// … after the border code …
If IsFocused And AllowFocusRing Then
  g.DrawingColor = Color.HighlightColor
  g.PenSize = 1
  // Inset by 2px so it sits inside the border
  g.DrawRoundRectangle(2, 2, g.Width-4, g.Height-4, CornerRadius-2, CornerRadius-2)
End If

5. Enable Canvas Focus

By default, DesktopCanvas won’t accept focus, so make sure to check AllowFocusRing in the Inspector when you drop CanvasButton onto a window.

Try It Out

1. Run the app:
   • Tab to the button → you’ll see the focus ring

What’s Next?

Stay tuned for more awesome updates!

You can grab the latest source on GitHub: GitHub – CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

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

Now, let’s make the CanvasButton control even easier to use in the Xojo IDE by leveraging the Inspector Behavior feature. This allows you (and anyone using your control) to configure its appearance and behavior at design time, right in the Properties panel.

Why Inspector Behavior Matters

When you create a custom control, its custom properties will not appear in the Inspector by default. Inspector Behavior lets you choose which properties are shown and how they’re grouped. This makes your control feel polished and professional, and saves users from digging into code to tweak settings.

Step 1: Open Inspector Behavior

To customize Inspector options for your CanvasButton:

1. In the Xojo IDE, select the CanvasButton class in the Project Navigator.
2. Right-click it and choose Inspector Behavior…

Step 2: Expose and Organize Properties

In the Inspector Behavior dialog, you’ll see a list of all public properties (inherited and custom).

• Make the following properties visible:
  • ButtonText
  • CornerRadius
  • BackgroundColor, HoverColor, HighlightColor, BorderColor, TextColor (all grouped under a custom “Button Colors” section)
• Organize properties into logical groups for clarity.

Tip: Defining default values for your properties in the class code means they will be automatically populated in Inspector Behavior. However, Xojo gives you even more flexibility. You can override these default values directly in the Inspector Behavior dialog, so you have full control over what new instances of your control will look like by default.

Step 3: Enjoy Design-Time Customization

With Inspector Behavior set up, you (or other developers) can now:

• Change the button text right in the Properties panel.
• Pick custom colors for normal, hover, pressed, border, and text states using the color picker.
• Adjust the corner radius visually.

Step 4: Best Practices and Tips

• Use clear group names (like “Button Colors”) to help users find related properties.
• Set sensible defaults for all properties in your code, but remember you can override them in Inspector Behavior.

Conclusion

With Inspector Behavior, your custom controls feel like first-class citizens in Xojo. You and others can now design beautiful, custom buttons by simply dragging, dropping, and tweaking settings in the Inspector. No code required!

Stay tuned for future parts where we’ll explore even more advanced features.

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

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

In this second part, we will enhance our CanvasButton by adding more customization with new properties to:

• set the button’s colors for different states (default, hovered, pressed)
• adjust the corner radius of the button
• implement a disabled state

Let’s get started!

Adding New Properties for Customization

We need to add several properties to our CanvasButton class to store the custom colors for different states, the border color, the text color, the corner radius, and the enabled state.

1. In the Project Navigator, select your CanvasButton class.
2. Go to Insert > Property (or right-click the class and select Add to “CanvasButton” > Property).
3. Add the following properties with the specified names, types, and default values:
   • Name: BackgroundColor Type: Color Default Value: &c5e2d8b
   • Name: HoverColor Type: Color Default Value: &c729fcf
   • Name: HighlightColor Type: Color Default Value: &c628eff
   • Name: BorderColor Type: Color Default Value: &c525252
   • Name: TextColor Type: Color Default Value: &ceeeeee
   • Name: CornerRadius Type: Integer Default Value: 4

These properties will hold the values that determine the button’s appearance and behavior.

Updating Event Handlers for the Enabled State

We need to modify the existing mouse event handlers (MouseDown, MouseEnter, MouseExit, MouseUp) to check if the button is Enabled before processing any mouse actions.

Select each of the following event handlers in the CanvasButton class and update the code as shown:

MouseDown(x As Integer, y As Integer) As Boolean

#Pragma unused x
#Pragma unused y

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the button is being pressed.
  IsPressed = True
  // Refresh the control to show the pressed state visually.
  Refresh(False)
  // Return True to indicate that this event was handled.
  Return True
Else
  // If disabled, do not handle the event.
  Return False
End If

MouseEnter()

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the mouse is hovering over the button.
  IsHovered = True
  // Refresh the control to show the hover state visually.
  Refresh(False)
End If

MouseExit()

// Only process if the button is enabled.
If Enabled Then
  // Set internal state to indicate the mouse is no longer hovering.
  IsHovered = False
  // Reset pressed state if mouse leaves while pressed (prevents accidental clicks).
  IsPressed = False
  // Refresh the control to revert from the hover state.
  Refresh(False)
End If

MouseUp(x As Integer, y As Integer) As Boolean

#Pragma unused x
#Pragma unused y

// Only process if the button is enabled.
If Enabled Then
  // Check if the button was pressed down AND the mouse is still hovering over it.
  If IsPressed And IsHovered Then
    // If true, the button was successfully clicked. Raise the custom Pressed event.
    RaiseEvent Pressed
  End If
  // Reset the pressed state regardless of whether the click was successful.
  IsPressed = False
  // Refresh the control to revert from the pressed state.
  Refresh(False)
End If

In these updated event handlers, we added an If Enabled Then check at the beginning. If the button is not enabled, the code inside the If block is skipped, preventing the button from reacting to mouse interactions. We also added #Pragma unused to the parameters x and y in MouseDown and MouseUp as they are not used in the code, which helps avoid compiler warnings. In MouseExit, we added IsPressed = False to ensure the pressed state is reset if the mouse leaves the button while the mouse button is held down.

Updating the Paint Event for Enhanced Appearance

The most significant changes will be in the Paint event where we will use the new properties to draw the button based on its current state (enabled/disabled, hovered, and pressed).

Select the Paint(g As Graphics, areas() As Rect) event handler and replace its content with the following code:

#Pragma unused areas

// Use the custom CornerRadius property.
Var currentCornerRadius As Integer = CornerRadius

// Declare variables for the colors used in drawing.
Var currentBgColor As Color
Var currentBorderColor As Color
Var currentTextColor As Color

// Determine colors based on the button's current state (enabled, pressed, hovered).
If Enabled Then
  If IsPressed Then
    // Use highlight color if pressed.
    currentBgColor = HighlightColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  ElseIf IsHovered Then // Check for hover only if not pressed
    // Use hover color if hovered.
    currentBgColor = HoverColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  Else
    // Use the custom background color for the default state.
    currentBgColor = BackgroundColor
    currentBorderColor = BorderColor
    currentTextColor = TextColor
  End If
Else
  // Use appropriate system or standard gray colors for the disabled state.
  currentBgColor = Color.LightGray
  currentBorderColor = Color.Gray
  currentTextColor = Color.DisabledTextColor // Use system disabled text color
End If

// Set the drawing color and draw the background shape with rounded corners.
g.DrawingColor = currentBgColor
g.FillRoundRectangle(0, 0, g.Width, g.Height, currentCornerRadius, currentCornerRadius)

// Set the drawing color and pen size for the border.
g.DrawingColor = currentBorderColor
g.PenSize = 2
// Draw the border shape just inside the background rectangle.
g.DrawRoundRectangle(1, 1, g.Width-2, g.Height-2, currentCornerRadius, currentCornerRadius)

// Enable anti-aliasing for smoother text rendering.
g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
g.AntiAliased = True
// Calculate the width and height of the button text.
Var tw As Double = g.TextWidth(ButtonText)
Var th As Double = g.TextHeight
// Calculate the X position to center the text horizontally.
Var tx As Double = (g.Width - tw) / 2
// Calculate the Y position to center the text vertically, with a small adjustment.
Var ty As Double = (g.Height + th) / 2 - 3
// Set the drawing color for the text.
g.DrawingColor = currentTextColor
// Draw the button text at the calculated centered position.
g.DrawText(ButtonText, tx, ty)

Let’s break down the changes in the Paint event:

• We now use the CornerRadius property instead of a static constant for drawing the rounded rectangles.
• We introduced an If Enabled Then ... Else block.
• Inside the If Enabled Then block, we have a nested If IsPressed Then ... ElseIf IsHovered Then ... Else structure. This determines the currentBgColor:
  • If IsPressed is True, currentBgColor is set to HighlightColor.
  • If IsPressed is False but IsHovered is True, currentBgColor is set to HoverColor.
  • If neither IsPressed nor IsHovered is True, currentBgColor is set to BackgroundColor.
  • The currentBorderColor and currentTextColor are set directly from the BorderColor and TextColor properties when the button is enabled.
• Inside the Else block (when Enabled is False), we set the colors to standard gray values (Color.LightGray for background, Color.Gray for border, and Color.DisabledTextColor for text) to give the button a disabled appearance.
• Finally, the drawing commands use these currentBgColor, currentBorderColor, currentTextColor, and currentCornerRadius variables.

Using the Enhanced Custom Control

Now that our CanvasButton has more customization options and supports a disabled state, let’s see how to use these features.

1. If you don’t already have an instance, drag the CanvasButton class from the Project Navigator onto a window in the Layout Editor.
2. You can now access and set the new properties programmatically. For example, in a button’s Opening event, you could add code like this:

// Customize colors
Me.BackgroundColor = Color.RGB(200, 50, 50) // A shade of red
Me.HoverColor = Color.RGB(255, 100, 100) // A lighter red for hover
Me.HighlightColor = Color.RGB(150, 0, 0) // A darker red for pressed
Me.BorderColor = Color.Black
Me.TextColor = Color.White

// Adjust corner radius
Me.CornerRadius = 10

You can experiment with different values to see how they affect the button’s appearance. To test the disabled state, you can set the Enabled property to False.

Conclusion

We’ve now taken our custom button to the next level by adding extensive color customization, adjustable corners, and a disabled state.

This project can be downloaded from GitHub at: https://github.com/xolabsro/CanvasButton

Hope you enjoyed making the button your own! While it’s much more flexible now, there might be other features we could add down the road, so stay tuned!

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus
• How to Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

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

You can read more about DesktopCanvas in the Xojo Docs.

Let’s begin!

Add a Custom Class:

• In the Project Navigator, add a new Class.
• Name it CanvasButton.
• Set its Super class to DesktopCanvas.

Add Properties:

• ButtonText As String (Set Scope to Public, Default Value to "Click Me". To make this property visible in the Inspector, right-click the CanvasButton class in the Project Navigator, select ‘Inspector Behaviour…’, scroll through the property list to find the ButtonText variable, and make sure its checkbox is checked.)
• IsHovered As Boolean (Set Scope to Private, Default Value to False)
• IsPressed As Boolean (Set Scope to Private, Default Value to False)

Define Pressed Custom Event:

• Go to Insert > Event Definition.
• Name the event Pressed. This is the event that will be raised when the button is clicked.

Add Event Handlers:

• Select the CanvasButton class in the Project Navigator.
• Go to Insert > Event Handler. Add the following event handlers and paste the corresponding code into each:

MouseDown(x As Integer, y As Integer)

// Set internal state to indicate the button is being pressed.
IsPressed = True
// Refresh the control to show the pressed state visually.
Me.Refresh(False)
// Return True to indicate that this event was handled.
Return True

MouseEnter

// Set internal state to indicate the mouse is hovering over the button.
IsHovered = True
// Refresh the control to show the hover state visually.
Me.Refresh(False)

MouseExit

// Set internal state to indicate the mouse is no longer hovering.
IsHovered = False
// Refresh the control to revert from the hover state.
Me.Refresh(False)

MouseUp(x As Integer, y As Integer)

// Check if the button was pressed down AND the mouse is still hovering over it.
If IsPressed And IsHovered Then
   // If true, the button was successfully clicked. Raise the custom Pressed event.
  RaiseEvent Pressed
End If
// Reset the pressed state regardless of whether the click was successful.
IsPressed = False
// Refresh the control to revert from the pressed state.
Me.Refresh(False)

Paint(g As Graphics, areas() As Rect)

// Corner radius of the button shape.
Static CornerRadius As Integer = 4

 // Declare variables for the colors used in drawing.
Var bgColor As Color
Var borderColor As Color = Color.DarkBevelColor
Var TextColor As Color = Color.LightTingeColor

 // Determine the background color based on the button's current state (pressed or hovered).
If IsPressed Or IsHovered Then
  // Use a highlight color if pressed or hovered.
  bgColor = Color.HighlightColor
Else
  // Use the accent theme color for the default state.
  bgColor = Color.AccentThemeColor
End If

// Set the drawing color and draw the background shape with rounded corners.
g.DrawingColor = bgColor
g.FillRoundRectangle(0, 0, g.Width, g.Height, CornerRadius, CornerRadius)

// Set the drawing color and pen size for the border.
g.DrawingColor = borderColor
g.PenSize = 2
// Draw the border shape just inside the background rectangle.
g.DrawRoundRectangle(1, 1, g.Width-2, g.Height-2, CornerRadius, CornerRadius)

// Enable anti-aliasing for smoother text rendering.
g.AntiAliasMode = Graphics.AntiAliasModes.HighQuality
g.AntiAliased = True
// Calculate the width and height of the button text.
Var tw As Double = g.TextWidth(ButtonText)
Var th As Double = g.TextHeight
// Calculate the X position to center the text horizontally.
Var tx As Double = (g.Width - tw) / 2
 // Calculate the Y position to center the text vertically, with a small adjustment.
Var ty As Double = (g.Height + th) / 2 - 3
// Set the drawing color for the text.
g.DrawingColor = TextColor
// Draw the button text at the calculated centered position.
g.DrawText(ButtonText, tx, ty)

Use the Custom Control:

• Open Window1.
• Drag the CanvasButton class from the Project Navigator onto the window.

Handle the Click Event:

• Double-click the CanvasButton instance on the window layout.
• Add the custom Pressed event handler.
• Add code inside this handler: MessageBox("Custom Button Clicked!").

Run the Project:

• Run the project. Test the button by hovering, pressing, and clicking to see the visual feedback and trigger the Pressed event.

And just like that, you’ve built your own custom button! Hope you had fun following along. Keep an eye out for our next tutorials, where we’ll take this button and give it some awesome upgrades!

This project can be downloaded from GitHub at: https://github.com/xolabsro/CanvasButton

More in this series:

• How To Create a Custom Button Control in Xojo
• How To Create a Custom Button Control in Xojo – Part 2
• How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly
• How To Create a Custom Button Control in Xojo – Part 4: Adding Focus

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