Tutorials – Xojo Programming Blog

Code Signing on macOS: What Developers Need to Know, Part 4

Javier Menendez — Tue, 07 Apr 2026 19:00:00 +0000

In the previous article, we saw how signing a macOS app is more than just handling certificates. Other factors come into play based on the distribution method you choose and the features it will offer.

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:

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

Code Signing on macOS: What Developers Need to Know

Build a Simple Find in Files Function

Gabriel Ludosanu — Thu, 02 Apr 2026 16:15:00 +0000

Sooner or later most apps need some version of the ability to find text in those files, whether you’re scanning log files, config files, exported data, or source code.

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:

the file path
the line number
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!

Custom Control Rendering with DrawControlInLayoutEditor

William Yu — Tue, 31 Mar 2026 15:22:00 +0000

One of the notable additions in Xojo 2026 Release 1 is that the DrawControlInLayoutEditor event is now available for Desktop and iOS/Android projects, giving you more possibilities over how your controls appear in the layout editor.

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.

Watchpoints in Xojo: A Smarter Way to Track Your Data

William Yu — Tue, 31 Mar 2026 13:22:00 +0000

Debugging isn’t just about stepping through code anymore, it’s about understanding how your data behaves over time. With the new watchpoints feature in Xojo, you can now monitor variables and object properties more intelligently, without constantly stepping line by line or adding logging just to see when values change.

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!

Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

Gabriel Ludosanu — Mon, 02 Mar 2026 23:43:13 +0000

In Part 1, we learned why tight loops with DoEvents freeze your UI. Part 2 showed us Timer controls. Part 3 moved timers into code. Part 4 simplified scheduling with CallLater.

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

Button press: Click the button and the thread starts.
Background loop: The thread iterates from 0 to kCountTo, sleeping 10 ms each step. After each step, it queues an update.
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!

Optimizing Code Series:

Scatter Chart: Connecting the Points

Javier Menendez — Mon, 09 Feb 2026 16:26:56 +0000

A user recently asked whether it’s possible to connect the (x, y) points in a Scatter chart using DesktopChart, and if so, how to do it. The short answer is yes, it is possible. Read on and I’ll show you just how easy it is.

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.

Optimizing Xojo Code, Part 4: Timer.CallLater

Gabriel Ludosanu — Mon, 02 Feb 2026 21:25:28 +0000

In Part 1 of this series, we looked at a common but discouraged approach using a tight loop with DoEvents to keep the UI from freezing. In Part 2, we explored a better alternative by replacing that loop with a Timer control dragged onto a Window. In Part 3, we advanced to creating Timers programmatically with AddHandler for use in classes and modules.

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

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).
Recursion: Each call updates the UI and, if not finished, schedules the next one 100ms in the future with incremented elapsed time.
Automatic Management: No Timer properties or handlers to manage; Xojo handles scheduling and cleanup.
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!

Optimizing Code Series:

Xojo + XAML + Goto = 🔥

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

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

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

At a high level, the workflow looks like this:

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

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

Visual States in XAML

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

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

Example XAML

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


  
    
      

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

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

      
    

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

In this XAML:

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

Triggering the Transition from Xojo

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

XAMLContainer1.GotoState("Top")

And to move it back down:

XAMLContainer1.GotoState("Bottom")

Why This Is Powerful

What makes this feature especially useful is that:

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

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

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

XAMLContainer1.GotoState("On")

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

Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler

Gabriel Ludosanu — Wed, 14 Jan 2026 16:27:11 +0000

In Part 1 of this Optimizing Xojo Code series, we looked at a working but discouraged approach using a tight loop with DoEvents to keep the UI from freezing. In Part 2, we explored a better alternative by replacing that loop with a Timer control dragged onto a DesktopWindow. This is a simple and effective solution that takes advantage of Xojo’s object-oriented nature.

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

New Timer: We create a new instance of the Timer class in memory.
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.
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!

Optimizing Code Series:

Creating Libraries that Support Multiple Project Types

Geoff Perlman — Tue, 09 Dec 2025 16:31:12 +0000

Libraries, introduced in Xojo 2025r3, make it easy to reuse your classes and interface items such as windows, webpages, and mobile screens across projects. As compiled code, Libraries ensure your projects always use a specific version of your functionality while allowing you to share features with other Xojo users without exposing your intellectual property. Think of them like plugins written in Xojo instead of C++, with the flexibility to use them in a single project folder or in the Plugins folder for access across all projects. The Xojo documentation provides guidance on creating your own Libraries.

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.

Download LibMerge for Linux, macOS or Windows. It will be included in the Extras folder in the next major release.
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.
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.
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.

Optimizing Xojo Code, Part 2: Using a Timer to Keep the UI Responsive

Gabriel Ludosanu — Tue, 25 Nov 2025 16:00:00 +0000

Welcome back! If you missed the first part in this series, check out Optimizing Xojo Code, Part 1: Getting Started, where we dissected the blocking While loop that counted up to kCountTo, updated a label, and kept the UI responsive only by calling App.DoEvents. That code works, but it spends most of its life running on the UI thread. In this tutorial we’ll rebuild that workflow step by step and end up with the first optimized solution: a timer-driven solution that keeps the interface responsive.

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!

Optimizing Code Series:

How To Create a Custom Button Control in Xojo – Part 5: Adding Text Alignment

Gabriel Ludosanu — Wed, 08 Oct 2025 15:54:00 +0000

In our previous installment, we successfully wired up keyboard focus to our custom DesktopCanvas subclass, making it fully accessible and user-friendly.

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:

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

Building Blocks for Beginners: Modules, Classes, Interfaces, and Delegates

Gabriel Ludosanu — Wed, 24 Sep 2025 15:50:00 +0000

If terms like “Modules,” “Classes,” “Interfaces,”, “Delegates” feel new or abstract, keep this article as a map. I’ll explain what each one does, why they matter, and how to choose the right one. Think of these features as your toolkit:

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

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.

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.

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.

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!

Implementing a Non-Blocking Image Processor with Xojo Threads

Gabriel Ludosanu — Thu, 28 Aug 2025 14:56:33 +0000

Have you ever written an app that needs to do some heavy lifting, like processing a big batch of files? Maybe you click a button, and suddenly your entire app just … stops. The cursor turns into a spinning wheel, the windows won’t respond, and your users are left wondering if it crashed. It’s a frustrating experience, but don’t worry, there’s a solution: Threads!

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:

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”.
DesktopProgressBar: This will give the user visual feedback on the progress of the resizing operation.
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 "/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:

Start the task from the main thread (ResizeThread.Start).
Work inside the thread’s Run event.
Communicate back to the UI with AddUserInterfaceUpdate.
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!

Deploy Xojo Web Apps with Caddy Reverse Proxy

Gabriel Ludosanu — Mon, 04 Aug 2025 18:45:28 +0000

Deploying Xojo web applications offers developers flexible pathways to production. For devs prioritizing minimal infrastructure management, Xojo Cloud provides a fully-managed solution with automatic scaling, SSL, and zero-server-maintenance. However, for developers requiring granular control over their deployment environment, implementing a reverse proxy like Caddy delivers enterprise-grade performance while simplifying critical operations.

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:

Simplified Operations: Single configuration file replaces complex proxy setups
Automatic Security: Continuous HTTPS protection without maintenance
Effortless Scaling: Built-in load balancing grows with your user base
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!

How To Create a Custom Button Control in Xojo – Part 4: Adding Focus

Gabriel Ludosanu — Mon, 23 Jun 2025 22:35:31 +0000

In part 3 of this series we made our CanvasButton inspector-friendly by exposing all our colors, corner radius and other properties. Today we’re going to wire up real keyboard focus so that you can:

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

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:

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!

How To Create a Custom Button Control in Xojo – Part 3: Make Your Controls Inspector-Friendly

Gabriel Ludosanu — Wed, 28 May 2025 17:54:20 +0000

In Part 1, we built a custom button control in Xojo by subclassing DesktopCanvas. In Part 2, we enhanced it with customizable colors, corner radius, and a disabled state.

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:

In the Xojo IDE, select the CanvasButton class in the Project Navigator.
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:

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!

How To Create a Custom Button Control in Xojo – Part 2

Gabriel Ludosanu — Wed, 14 May 2025 15:00:00 +0000

In the first part of this tutorial, we built a basic custom button control using the DesktopCanvas class, giving it a custom appearance and handling the basic mouse events to provide visual feedback and raise a Pressed event when clicked.

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.

In the Project Navigator, select your CanvasButton class.
Go to Insert > Property (or right-click the class and select Add to “CanvasButton” > Property).
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.

If you don’t already have an instance, drag the CanvasButton class from the Project Navigator onto a window in the Layout Editor.
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:

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!

How To Create a Custom Button Control in Xojo

Gabriel Ludosanu — Fri, 02 May 2025 14:00:00 +0000

This tutorial demonstrates how to create a custom button control in Xojo using the DesktopCanvas class. It covers defining properties, handling mouse events for visual feedback, and drawing the control in the Paint event.

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:

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!

How to Publish macOS and iOS Apps to the App Store Directly from Xojo

Javier Menendez — Tue, 25 Mar 2025 15:34:03 +0000

Starting with Xojo 2025r1, you can publish macOS and iOS apps to App Store Connect directly from the Xojo IDE. Keep reading to learn how!

App Store Connect is where developers create app records as part of the process to make their apps available on the Mac App Store and/or iOS App Store. All apps must go through Apple’s review process for approval. Once an app record exists in App Store Connect, every new app build uploaded from the Xojo IDE will be available there!

First Things, First

Before exploring how to use Xojo’s new Publish feature, let’s review the requirements and previous processes to better understand how it works.

You may have already met these requirements, but it’s always a good idea to review them.

A paid Apple Developer membership (approximately US $99/yr).
Xcode installed on your Mac, preferably the latest version (Xcode 16.2 at the time of writing, which requires macOS Sequoia 15.2). However, Xojo also works with Xcode 13 or later, such as on macOS Ventura.
The following certificates are present in your Mac’s Keychain:
- Developer ID Application
- Apple Distribution
- 3rd Party Mac Developer Installer
An explicit App ID (Identifier) has been created for your app at developer.apple.com.
A Provisioning Profile has been created at developer.apple.com to ensure the uploaded build is available for testing via TestFlight.
No pending agreements are waiting for your approval at both developer.apple.com and appstoreconnect.apple.com.

Handling Certificates

The best way to ensure you have the correct certificates installed in your Mac’s Keychain is to manage them directly from Xcode. Open Xcode, go to Preferences > Accounts, and make sure you are signed in with your developer.apple.com credentials.

Next, click the “Manage Certificates…” button. A new window will appear, displaying the installed certificates—including expired ones or those missing a private key. From here, you can also download any missing certificates.

Once the required certificates are installed on your Mac, I recommend opening the Keychain app to remove any revoked, expired, or incomplete certificates (those missing a private key) to keep your Keychain clean and organized.

Handling App ID

The App ID, Identifier, or ‘Bundle Identifier’ is something you should be familiar with whenever you create a new macOS or iOS app in the Xojo IDE.

You also need to create the same App ID at developer.apple.com. Log in to the Apple Developer portal using your Apple Developer credentials, then click “Identifiers” under the “Certificates, IDs & Profiles” section.

Note: Keep in mind that you must create a new App ID and follow these steps for each macOS or iOS app you want to distribute through the Mac or iOS App Store.

On the page displayed after the previous step, click the “+” button next to the “Identifiers” header to register a new Identifier.
On the next page, ensure that “App IDs” is selected, then click “Continue”.
On the following page, select “App”, then click “Continue” again.
Now, you’ll reach the most important step—entering the explicit Bundle ID. Make sure it exactly matches the “Application Identifier” used when creating the project in the Xojo IDE.
Also, verify that the App ID Prefix matches the Team ID of the certificates installed in your Mac’s Keychain via Xcode.
Select any Capabilities and/or App Services your app requires. (For this example, none are selected.)
Click “Continue” to proceed to the summary page, where you can review all the entered details and selected Capabilities/App Services.
If everything looks correct, click “Register” to finalize the process.

Once registered, the new Identifier will appear in the list under the “Identifiers” section.

Handling Provisioning Profiles

TestFlight is an Apple service that allows developers to gather feedback from users and teammates while an app is still in development, before it becomes publicly available on the Mac or iOS App Store. When a new app build (version) is published from the Xojo IDE, it will also become available through TestFlight.

However, for this to work, the app must have a “Provisioning Profile” embedded. This profile needs to be created on the “developer.apple.com” website, as we did in the previous “App ID” section.

There are two main types of provisioning profiles: “Development” and “Distribution.” The key difference is:

“Development” profiles specify which devices an app can be installed on. They are primarily used for internal testing on user devices or, in the case of iOS apps, for running tests on a physical device using the “Run On Device” option in the Xojo IDE.
“Distribution” profiles are used for submitting apps to the App Store or making them available for TestFlight testing.

In this example, we will focus on creating a “Distribution Provisioning Profile” to ensure that apps published from the Xojo IDE are eligible for TestFlight testing.

Log in to “developer.apple.com” and navigate to the “Certificates, IDs & Profiles” section.
Select “Profiles” and click the “+” button next to the “Profiles” header.
On the next page, under the “Distribution” section, select “Mac App Store Connect” if you are creating a profile for a macOS app. For iOS apps, choose “App Store Connect” instead. Click “Continue.”
Select the “App ID” you previously created. Notice that the App ID is prefixed with the “Team ID” from when the App ID was created (e.g., “BW7PU32485”).
Under “Profile Type,” make sure the “Mac” option is selected instead of “Mac Catalyst.” Click “Continue.”
On the next page, select the same “Distribution” certificate that will be used when building the Xojo app (i.e., the “Apple Distribution” certificate installed on your Mac). Click “Continue.”
Give the Provisioning Profile a meaningful name so you can easily distinguish it later from other profiles. Click “Generate.”
After a few seconds, the Provisioning Profile summary page will appear with a “Download” button. Click it to download the profile.

NOTE: Provisioning Profiles for iOS
For iOS apps, you need to create both “Development” and “Distribution” provisioning profiles.

When creating the “Development” provisioning profile, be sure to include all registered devices you want to use for installing and testing the app directly from Xojo (using the “Run On Device” option in the IDE).

Once these provisioning profiles are downloaded to your Mac, double-click on them to ensure Xcode installs them in the correct location (as of this writing: “Library > Developer > Xcode > User Data > Provisioning Profiles”).

Adding the Distribution Provision Profile to your Xojo Project

Move the downloaded macOS Distribution Provisioning Profile to a more convenient location related to your Xojo project, and rename it to “embedded.provisionprofile”.

Next, open your Xojo project and add a new “Copy Files” step:

Right-click (or use the contextual menu) and choose “Add to ‘Build Settings’ > Build Step > Copy Files”.
Select the “macOS” item under “Build Settings.”

Next, click the “Add File” button in the “Copy Files” toolbar and select your “embedded.provisionprofile” file.

In the associated “Inspector” panel, use the following values:

Name: Distribution Profile
Applies To: Release
Architecture: Any
Destination: Contents Folder

NOTE: For Xojo iOS projects, provisioning profiles are applied automatically when building or publishing the app. This happens based on the profiles installed by Xcode when you double-click them after downloading from developer.apple.com.

App Store Connect: Creating the Record for the App

You need to create an App Record for every macOS or iOS app that will be distributed through the Mac or iOS App Store. To upload an app from the Xojo IDE, it is not necessary to complete every required field in the various sections right away—you can do that at your own pace. However, you must at least have an App Record created for the app.

To do this, log in to “appstoreconnect.apple.com” using your developer credentials. Once logged in, select the “Apps” icon. On the next page, click the “+” button and choose “New App” to create a new App Record. The previous action will open a dialog where you need to enter the essential app information required to create the record.

Platforms: Select “macOS.”
Name: Enter the same name used in your Xojo project for the app (Build Settings > macOS > Mac App Name). Apple can be strict about this during the app review process if the names differ, as this will also be the name displayed in the App Store listing.
Bundle ID: Select the App ID you created for the app by following the steps in the “Handling App ID” section.
SKU: Enter any arbitrary SKU value that makes sense to you for uniquely tracking this app.
User Access: If you are a solo developer, the choice doesn’t make much difference. However, if you are part of a team, selecting “Limited Access” allows more control over which team members can access the app.

Once you are confident with the information provided, click the “Create” button to generate the new app record.

If you receive an error stating that another app has already been registered with the same name, you will need to choose a different name for your app.

NOTE: Values such as the App Name and Bundle ID can be changed later, if needed, from the “General > App Information” section on the App Record page.

Once the App Record has been created, there will be a lot of required information to fill in before the app can go through the App Store Review Process and be publicly listed in the Mac/iOS App Store upon approval. However, as mentioned earlier, you can add this information at your own pace. The most important thing right now is that, once the record is created, you have everything set up to start uploading your app builds (versions) from the Xojo IDE.

Publishing Mac Apps From Xojo

General Information

Open your Xojo project in the IDE and go to Build Settings > macOS. Then, make sure the correct values are set in the associated Inspector Panel for the following fields:

Mac App Name: This should match the name entered for the App Record on appstoreconnect.apple.com.
Bundle Identifier: This should match the App ID created for the app.
Category: Select the category that best fits your app from the available options.

App Store Connect Setup

To allow the IDE to upload the app to App Store Connect, you need an app-specific password. You can add it by clicking the App Store Connect > Setup button. If you have already created this app-specific password in a previous version of Xojo (under Build Settings > Sign > Notarization > Setup), you don’t need to do it again. Also, keep in mind that this setup only needs to be done once for all your Desktop (macOS) and iOS projects.

Signing and Sandboxing

Select Build Settings > macOS > Sign in the project browser in order to access the associated Inspector Panel:

Developer ID: Type (or paste) the full string from the Apple Distribution certificate installed on your Mac. In this example, it is: “Apple Distribution: Francisco Javier Rodriguez Menendez (BW7PU32485)”. This certificate should match the one selected when the Distribution Provisioning Profile was created, and the Team ID (the value in parentheses) should match the one used when the App ID (Identifier) was created for the app at developer.apple.com.
Sandboxing: Apps uploaded to App Store Connect require Sandboxing to be enabled. Turn on this option and click the associated “Edit” button to enable the necessary sandboxed features for your app. In our example, we only enabled the ability to read/write the selected user files.

Shared Settings

Select Build Settings > Shared in the project browser to access the associated Inspector Panel:

If you are going to publish the final (release) version of your app after it has been thoroughly tested, you will likely want to set the Stage Code value to “Final.” Additionally, make sure to enter the short version string in the Version field and the copyright information for the app in the Copyright field.

NOTE: Did you forget something? Every time you click the Publish button (or select the equivalent “Build and Publish to App Store Connect” menu item from the Project menu), the IDE will run a “checklist.” If something needs to be set in the IDE before uploading the app to App Store Connect, any errors will be shown in the IDE’s Error Panel, pointing out “what” needs to be fixed and “where” to make the changes.

App Icon

Nothing new here, apart from building your macOS app for regular or “web-based” distribution. Your app needs an icon in the required sizes. However, when it comes to publishing to the Mac/iOS App Store, this requirement is even more strict. Xojo will catch this before starting the app building process to save you time spent on compilation and uploading. So, make sure you add all the required icon sizes by selecting the App item in the project browser, then clicking the Appearance > Icon option in the associated Inspector Panel.

That action will open the Icon Editor, where you can drag and drop the different icon files for each size or paste them directly from your preferred image editor.

Publishing!

Click the Publish button. Once the “checklist” passes without any errors, a confirmation dialog will appear. Click the “OK” button to begin the process and upload your app’s new build to App Store Connect.

If everything goes smoothly, you will see a “Success” dialog at the end of the process. However, if there is an error during any of the steps, an error message dialog will provide more details about the issue, and the process will be interrupted, returning you to the IDE.

In either case—whether your new app build was successfully uploaded to App Store Connect or not—you can find the generated Log file in the same folder as the built app. If there are errors, you can open the Log file to review the information about the issue(s), which will help you resolve them before trying again. For example:

2025-01-23 12:54:35.030 *** Error: [ContentDelivery.Uploader.6000028E01C0] The provided entity includes an attribute with a value that has already been used (-19232) The bundle version must be higher than the previously uploaded version: ‘1.0.6’. (ID: d422b9bf-049f-4263-af43-8357c2fe5f00)

In this case, the Log file entry indicates that we tried to publish a build with the same version number as an already uploaded build on App Store Connect. If this new build includes changes or new features, the way to fix this issue is simply by increasing the version number (and the short version string) before publishing it.

Testing with TestFlight

When you create a new app record in App Store Connect and access it, one of the tabs at the top of the page is named “TestFlight.” Click on it, and you will see all the uploaded builds of your app that are eligible for testing.

As you can see, there is a warning icon next to the app build we just uploaded (A). This is because Apple requires additional information from you regarding the app’s compliance with Encryption Export Regulations. To provide this information, click the associated “Manage” link to access the dialog where you can make your choice about it.

TIP: Use the new Property List Editor in Xojo’s IDE and add the following Key/Value pair to avoid manually going through the Encryption Export Regulations compliance process:

Key: ITSAppUsesNonExemptEncryption

Value: False

Once the requirement has been completed, the build status will change to “Ready to Submit.” As you can see, it also indicates that this build will be available to your testers for the next 90 days before expiring. This should be enough time before you send new test builds to them, anyway.

For each of your apps, you can create as many tester groups as needed. By default, there is only one entry: “Internal Testing.” You can create additional groups and add any members of your Apple Development Team to the groups you create. Click on the “+” icon to create your first group.

Give the new group a name and uncheck the “Enable automatic distribution” checkbox. Then, click the “Create” button.
Once the new internal testing group is created, you will be able to assign any uploaded (and not expired) builds of your app to it. You can also add members to the group (remember, these should be members of your Apple Developer Team!).

However, having internal testing groups might not be very helpful if you are a solo developer or part of a small team. The good news is that once you create the first, mandatory internal group, a new option will be added to the TestFlight sidebar.

External Testing

In this case, you will be able to invite up to 10,000 members to test your app. The main difference compared to internal groups is that once you select a build to be tested in any of the external groups, it must go through the Beta App Review process. This means the build won’t be immediately available to your testers until the review is complete. However, this process is only required for the first build—subsequent builds will be available immediately, just like in internal groups.

When inviting members to an external group, you have several options: you can create and share a public link, manually add testers, or even import them from a .csv file.

In any case, your testers will be able to download, install, and begin testing your app, as well as provide feedback!

In Summary

The new Publish feature simplifies the process of submitting your macOS and iOS apps to App Store Connect, making them available on the Mac App Store and iOS App Store directly from the IDE, without needing any external apps (such as Transporter).

A Complete Dockerfile for Web Apps

Gabriel Ludosanu — Wed, 19 Mar 2025 15:19:48 +0000

For a comprehensive guide on deploying Xojo web apps to any server, please refer to the video tutorial available at: https://youtu.be/ARr7d6Z6CRY

The Dockerfile below should be placed in the same directory as your Xojo project
Remember to modify the WEBAPP_NAME variable on line 33 to match the name of your project
Feel free to customize this Dockerfile to suit your specific needs. We encourage you to share your modifications and experiences in the Xojo forum

# Step-by-Step Instructions for Building, Saving, and Running the Image:
# 1. Build the Docker image:
#    "docker build -t hellodocker-image ."
#    This creates a Docker image named "hellodocker-image" based on this Dockerfile.
#
# 2. Save the Docker image to a tar file:
#    "docker save -o hellodocker-image.tar hellodocker-image"
#    This saves the "hellodocker-image" to a file named "hellodocker-image.tar".
#    You can use this file to transfer the image to another server.
#
# 3. Upload the .tar file to the remote server.
#    After transferring the tar file, follow these steps on the remote server:
#
#    3.1 Load the Docker image:
#        "docker load -i hellodocker-image.tar"
#        This imports the image into the Docker environment on the server.
#
#    3.2 Run a container from the image:
#        "docker run -d --name hellodocker-container --restart always -p 7000:80 hellodocker-image"
#        This creates and starts a container named "hellodocker-container" that:
#        - Restarts automatically if it stops (via `--restart always`).
#        - Maps port 80 inside the container to port 7000 on the host machine.
#
#    3.3 Verify the web app is running:
#        Open a web browser and navigate to http://server-ip:7000
#        Replace "server-ip" with the IP address of your remote server.
#
# Complete video guide at: https://youtu.be/ARr7d6Z6CRY

# Use Ubuntu 22.04 as the base image for the container.
FROM ubuntu:22.04

# Define the name of the Xojo web app executable.
# This should match the exact name of your compiled Xojo web app (case-sensitive).
ENV WEBAPP_NAME=HelloDocker

# Prevent interactive prompts during the installation of dependencies.
ENV DEBIAN_FRONTEND=noninteractive

# Install required system libraries for the Xojo web app to run, and purge unnecessary software (PHP, Python, Apache)
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    libunwind8 \
    libsoup2.4 \
    libpango-1.0 \
    libicu70 \
    libglib2.0 \
    libgtk-3-0 \
    && apt-get purge -y php* python3* apache2* libapache2-mod-php* \
    && apt-get autoremove -y \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

RUN useradd --create-home ${WEBAPP_NAME}

# Set the working directory inside the container.
# This is where the web app files will be located.
WORKDIR /${WEBAPP_NAME}

# Copy the built Xojo web app from the build context into the container.
# Remember, this Dockerfile must be placed in the same folder as the Xojo project.
COPY ["Builds - ${WEBAPP_NAME}/Linux 64 bit/${WEBAPP_NAME}", "."]

# Change ownership of the application files to the non-root user
RUN chown -R ${WEBAPP_NAME}:${WEBAPP_NAME} /${WEBAPP_NAME}

# Ensure the main web app executable has permission to run
RUN chmod +x ${WEBAPP_NAME}

# Create a directory for persistent data storage.
# Ensure the data directory is owned by the non-root user.
RUN mkdir -p /home/${WEBAPP_NAME}/data && chown -R ${WEBAPP_NAME}:${WEBAPP_NAME} /home/${WEBAPP_NAME}/data

# Define the volume for the container to store data.
# The contents of "/home/${WEBAPP_NAME}/data" will persist outside the container.
VOLUME /home/${WEBAPP_NAME}/data

# Switch to the non-root user for security purposes.
# All subsequent instructions (including CMD) will run as this user.
USER ${WEBAPP_NAME}

# Expose port 80 inside the container.
# This allows the web app to listen on port 80, which will be mapped to port 7000
# on the host machine when the container is run.
EXPOSE 80

# Start the Xojo web app when the container runs.
# The app will listen on port 80 inside the container.
CMD ["sh", "-c", "./${WEBAPP_NAME} --port=80"]

I also recommend reading this article for additional details on Xojo and Docker: https://blog.xojo.com/2021/05/17/running-xojo-web-applications-in-docker/

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!

Customize and Extend Core Databases Functionality

Gabriel Ludosanu — Wed, 05 Feb 2025 19:00:33 +0000

Have you ever debugged your Xojo database app and wondered about the SQL queries being executed and the parameters used? You are not alone. Whether you’re developing a desktop, web, or mobile app, having clear insight into your database interactions is crucial for effective debugging and ensuring your app functions correctly.

This article will show you how to automatically record queries and commands in any Xojo database class to help you debug and improve database operations by using method overriding. This will help you:

Debug SQL operations faster by seeing exactly what’s being executed.
Spot errors in your SQL queries or parameters before they become runtime issues.
Gain transparency into your app’s database behavior.

By the end of this tutorial, you’ll have a clear understanding of:

Method overriding: What it is and how you can use it to extend built-in Xojo classes.
Subclassing database classes: Learn how to develop a custom database class with added logging functionality to improve database management and tracking.
Logging SQL commands and parameters: Discover how to effectively capture and log database operations such as SELECT, INSERT, and DELETE to enhance visibility and improve database performance.

What is Method Overriding?

Method overriding, a fundamental concept in object-oriented programming (OOP), lets you customize how a subclass implements its superclass’s methods. In Xojo, this powerful feature allows you to enhance built-in classes without modifying their original code, ensuring you preserve core functionality while adding your own features.

How Method Overriding Works in Xojo

Let’s break it down step by step with a simple example. Imagine you’re working with the SQLiteDatabase class, and you want to modify the behavior of the ExecuteSQL method to log every SQL command executed.

Create a Subclass:
- Create a new class in Xojo and set its Super to SQLiteDatabase. This means your new class inherits all the properties and methods of SQLiteDatabase.
Override the Method:
- In your new subclass, define a method and from the Method Name picker, select ExecuteSQL.
- Add your custom logic, like logging the SQL command to the Xojo debugger.
Call the Original Method:
- Use the Super keyword to call the original ExecuteSQL method in the superclass. This ensures the original behavior is preserved alongside your custom logic.

Extending Xojo’s SQLiteDatabase with Method Overriding

Let’s enhance Xojo’s SQLiteDatabase class by creating a subclass that automatically logs SELECT queries and their parameters. To make this process easier, use the built-in “Full-Text Searching 5” example project, which already includes various database operations.

1. Create the `MySQLiteDatabase` Subclass

From the Insert menu, select Class.
Name the new class MySQLiteDatabase.
In the Inspector, set the Super field to SQLiteDatabase.

This tells Xojo that MySQLiteDatabase will inherit all the behavior of SQLiteDatabase, allowing you to override its methods.

2. Override the `SelectSQL` Method

Now, you’ll override the SelectSQL method in your MySQLiteDatabase class. This method is used for SELECT queries, so you’ll add logging to display the query and its parameters in the debugger.

Public Function SelectSQL(query As String, ParamArray values() As Variant) As RowSet
  // Log the SELECT query
  System.DebugLog("[DEBUG] SelectSQL called: " + query)
  
  // Log the parameters (if any)
  If values.LastIndex >= 0 Then
    Var stringValues() As String
    For Each v As Variant In values
      stringValues.Add(v.StringValue) // Convert Variant to String
    Next
    System.DebugLog("[DEBUG] Parameters: " + String.FromArray(stringValues, ", "))
  End If

  // Call the original SelectSQL method
  Try
    Return Super.SelectSQL(query, values)
  Catch error As DatabaseException
    // Log any errors
    System.DebugLog("[ERROR] DatabaseException: " + error.Message)
    Raise error // Re-raise the exception so the app can handle it
  End Try
End Function

3. Replace the Database Property

Now that you’ve created the MySQLiteDatabase subclass, you need to update the example project to use it.

Open Window1 in the Project Browser.
Locate the DB property in Window1. It is currently defined as DB As SQLiteDatabase:
Change the type of DB from SQLiteDatabase to MySQLiteDatabase. To do this:
- Select the DB property.
- In the Inspector, update the Type field to MySQLiteDatabase.

Additionally, under the Opening event of Window1, change DB = New SQLiteDatabase to DB = New MySQLiteDatabase.

This replaces the original SQLiteDatabase with your custom subclass, ensuring all database operations now use your overridden SelectSQL method.

4. Test the Logging

With the subclass in place, run the project and test the logging functionality.

Run the project.
Perform a search in the app’s UI. Each search generates a SELECT query using the SelectSQL method.
Check Xojo’s Messages Panel for output. You should see the SQL query and its parameters logged.

Example Output:

[DEBUG] SelectSQL called: SELECT highlight(ftstest, 0, '<', '>') FROM ftstest WHERE ftstest MATCH 'know' ORDER BY rank;

Additional Enhancements

Now that you’ve created a foundation for extending Xojo’s database classes by logging queries with your custom subclass, it’s time to think about how you can take this further. Below are several ideas for additional enhancements that will make your subclass more robust, versatile, and useful for debugging and performance monitoring.

Log Additional Methods

While you’ve started with the SelectSQL method, your app likely performs other database operations, such as INSERT, UPDATE, DELETE, or even transactions. You can override methods like ExecuteSQL to log these operations along with their parameters. Extending the logging functionality to these key methods ensures a complete picture of all database activity.

Additionally, logging transactional methods like BeginTransaction, CommitTransaction, and RollbackTransaction can help you trace when database changes are grouped together and ensure data integrity.

Tip: You can incorporate the Log4Xojo project.

Support for Multiple Database Classes

If your app uses different database types, such as MySQLCommunityServer or PostgreSQLDatabase, you can generalize your logging functionality to work with all of them. This can be achieved by creating a base class for logging that inherits from Database and then extending it for specific database types. This approach ensures consistency and reusability across different database systems.

Monitor Query Performance

Tracking the time it takes for queries to execute can give you valuable insights into your application’s performance. By measuring the duration of each query, you can identify slow queries and optimize them for better efficiency. Additionally, you could log a warning if a query takes longer than a specified threshold, helping you catch performance issues early.

Automatically Retry Failed Queries

Sometimes, database operations fail due to transient errors, such as network interruptions or locked tables. Implementing retry logic for failed queries can make your app more resilient. For example, you could attempt a query up to three times before logging it as a failure. This is particularly useful for apps that rely on remote database servers, where connectivity issues are more likely.

Add Context-Specific Metadata

Including additional context in your logs can make them more meaningful. For example, you might log:

The name of the method or function that triggered the query.
The user ID or session ID (if applicable) for tracking user-specific database activity.
Tags or labels to group related queries or transactions.

This kind of metadata makes it easier to understand the “why” behind a query, not just the “what.”

Wrapping It All Up

Congratulations! You’ve taken a deep dive into one of the most powerful techniques in Xojo development: extending built-in classes, like SQLiteDatabase, to meet your specific needs. By following the steps in this tutorial, you’ve learned how to override methods, create a custom database subclass, and log SQL queries for better debugging and transparency.

What’s Next?

If you enjoyed this tutorial, we’d love to hear from you! Share your thoughts, your customizations, or any challenges you faced in the Xojo forums. If you’ve built something amazing using this technique, let us know—we’d love to feature your work in our community showcase.

Keep coding, keep innovating, and as always, happy developing!

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!

Provisioning Profiles for macOS Apps

Javier Menendez — Thu, 30 Jan 2025 15:22:00 +0000

Continuing our series on distributing Mac apps, this post will take you through properly setting up a provisioning profile, which is required for your apps to get tested by others in TestFlight. To review or catch up on earlier steps in this process, see my posts on Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE, macOS Apps: From Sandboxing to Notarization, The Basics and Uploading macOS Builds to App Store Connect. But if you have those steps done, let’s set up the provisioning profile you need.

Development or Distribution

There are two types of provisioning profiles: Development and Distribution. Development provisioning profiles are for builds sent to the AppStore Connect service that are not meant to be available on the Mac App Store. Development profiles allow apps to be tested by the eligible users associated with that app in TestFlight. For Development provisioning profiles, set the Stage Code value (under Build Settings > Shared) to “Development”, “Alpha” or “Beta”.

On the other hand, Distribution provisioning profiles for macOS are required for builds meant to be publicly available on the Mac App Store once approved by the App Store Reviewing Process, they are also available for TestFlight. For Distribution provisioning profiles, make sure the Stage Code value is set to “Final” under Build Settings > Shared.

Creating Provisioning Profiles

Regardless of which type of provisioning profile you are creating, you’ll need to do it from the Apple Developer website (using your paid developer membership).

In this example we will create a Distribution provisioning profile.

Login into the Apple Developer Website.
Select the Profiles option found under the “Certificates, IDs & Profiles” section.
Click on the “+” icon found next to the “Profiles” header.
Next, select the “Mac AppStore Connect” option under the Distribution section, and click on the “Continue” button.

Select the “Mac” option under the Profile Type section, and select the App ID value from those available in the associated Popup menu. Make sure that the chosen one (without the value between parentheses) matches the one entered under Build Settings > macOS > Bundle Identifier. Then, click on the “Continue” button.

For example the selected one in the screenshot (that, is BW7PU32485.com.aprendexojo.vcardtoqr), matches the one used as the Bundle Identifier for the app in the Xojo IDE (com.aprendexojo.vcardtoqr).

Next, select the “Distribution” Certificate to be included in the generated provisioning profile. The one selected must be the same one entered in the Developer ID field when building the App from the Xojo IDE (Build Settings > macOS > Sign). For example, I’m going to use the value (without the quotes) “Apple Distribution: Francisco Javier Rodriguez Menendez (BW7PU32485)” as the Developer ID value in Xojo, so I’m selecting that same Distribution certificate here. Next, click the “Continue” button.

Name the provisioning profile using a significative name, so you can easily distinguish it later among the many available ones. Next, click the “Generate” button so the provisioning profile is generated and downloaded to your local Mac disk (probably in the Downloads folder).
The downloaded provisioning profile will have the name you entered in the previous step. Select it and use the Finder options to rename it as “embedded.provisionprofile”.

Adding the Provisioning Profile to the Project

macOS provisioning profiles need to be added to the Contents folder on the app bundle, and that is easy to do from the Xojo IDE!

Open your project in the Xojo IDE and add a new Copy Files build step under Build Settings > MacOS.
Add the “embedded.provisionprofile” file to the just added CopyFile build step.
Select the “Contents Folder” option from the Destination popup menu in the associated Inspector Panel for the Copy Files build step.
Select the “Release” option from the “Applies To” popup menu in the associated Inspector Panel for the Copy Files build step, so only this file is copied to the Contents folder when the app is built as a standalone app.

Adding New Entries to the Entitlements File

In order for the provisioning profile to be recognized by TestFlight when the app package is sent to AppStore Connect, we need to add a couple more entries to the Entitlements file (see “Uploading macOS Builds to App Store Connect” for more details on the Entitlements file).

Full Application Identifier. Use the “com.apple.application-identifier” as the Key for the entry. The value should be the Application Bundle Identifier (in our example com.aprendexojo.vcardtoqr) prefixed with the Team ID value of the Certificate we used both for signing our app and the provisioning profile itself. In this example it is BW7PU32485, making the string value for this key BW7PU32485.com.aprendexojo.vcardtoqr
Team ID. Use “com.apple.developer.team-identifier” as the Key for the entry, while the value (following with our example) is just the Team ID from the certificate: BW7PU32485

All in all, the final Entitlements file will look like this:





	com.apple.security.app-sandbox
	
	com.apple.security.files.user-selected.read-write
	
	com.apple.application-identifier
	BW7PU32485.com.aprendexojo.vcardtoqr
	com.apple.developer.team-identifier
	BW7PU32485

That is: Sandboxing enabled, plus the ability for the app to read/write the selected user files, plus the two new entries required so the provisioning profile is recognized by TestFlight when the package is submitted to the AppStore Connect.

Save the changes to the modified Entitlements file (in our example named as “myEntitlements.entitlements”).

Resign, Re-Package, and Uploading

If you followed the two previous blog posts in this series, you may have already guessed the next step! Yep, because we modified our “myEntitlements.entitlements” file, we need to re-sign the app bundle, package it and submit it to AppStore Connect.

So for re-signing, type the following in a new Terminal window:

codesign --force --timestamp --entitlements path-to-your-myEntitlements.entitlements-file  -s "Apple Distribution: whatever-name-you-use (BZXXXXXXX)" path-to-the-bundle-of-the-compiled-app.app

In order to create a package from the bundle, issue this command from the Terminal:

productbuild --sign "3rd Party Mac Developer Installer: whatever-name-you-use (BZXXXXXXX)"  --component path-to-the-bundle-of-the-compiled-app.app  /Applications path-to-the-generated-package-file.pkg

And in order to upload the package to the AppStore Connect, type the following command in a Terminal window:

xcrun altool  --upload-package path-to-the-package-file.pkg -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --type osx -apple-id "6111111111" --bundle-id "com.yourcomany.yourIdentifier" --bundle-short-version-string "current-short-value" --bundle-version "current-version-value"

If everything went OK, open your Internet Browser and go to http://appstoreconnect.apple.com, select your app record from the Apps section and click on the TestFlight tab. You should be able to see the just submitted build ready for testing!

In Summary

As you see, adding provisioning profiles to macOS apps sent to the AppStore Connect website to be tested by in TestFlight, requires a bit of previous preparation for the provisioning profile generation itself, copying the file to the project using a Copy Files build step and, then, adding a couple more entries to the Entitlements file.

Once everything this is done, your testers will be able to use the TestFlight app to download and test your builds and report feedback, crash reports and other information about it!

More in this series on distributing Mac apps:

Uploading macOS Builds to App Store Connect

Javier Menendez — Tue, 14 Jan 2025 20:53:32 +0000

Since Xojo 2024r4 the IDE includes the ability to automatically compile macOS apps with Sandboxing, Hardened Runtime and Notarization. Continue reading to learn that extra step in order to submit the created bundle directly to the App Store Connect website!

There is a Xojo-made tool out there that can simplify the process, and if that’s your route, check out AppWrapper from Ohanaware. But if you are the kind of developer that enjoys “how things work under the hood”, then follow these steps to do it manually from the command line (or convert these instructions into Xojo Scripts that can be executed as part of the build process itself from the Xojo project).

There are some requirements for all of this to work, but you took care of them already if you already followed our previous post about how to apply Sandboxing, Hardened Runtime and Notarize manually to your Xojo macOS builds. Perhaps, the most important one is that this requires a paid Apple Developer Program membership (around US $99/yr). Additionally, Xcode needs to be installed on your Mac in order to use its included altool and productbuild command line tools. Create an app-specific password in order to execute the notarytool command line tool, which is also required when using the altool command line. You likely created one already for the notarytool command line tool which you can use as the password required by the altool command line tool.

If distributing your macOS apps from your website, these need to be signed using the “Apple Development” Certificate, but if you are compiling a macOS app for distribution through the Mac App Store, you need to sign it using the “Apple Distribution” certificate. So make sure to fill-in the macOS > Signing > Developer ID field properly.

Also important, in order to upload the app to App Store Connect, you need to create a package file from the app bundle, and that package file (.pkg) needs to be signed using the “3rd Party Mac Developer Installer”. Make sure you have this certificate installed in your Mac Keychain.

First things … First

Before you can upload you .pkg file to the App Store Connect website, there are some things you need to take care of that are required by Apple for apps to be distributed through the Mac App Store.

The first thing is to register an App ID (or Identifier) in the Apple Developer Portal. When doing it, make sure you are creating an explicit Identifier instead of a wildcard one. Also very important, make sure that the identifier (in the reversed DNS form) is the same one you are using in the field macOS > Build > Bundle Identifier of your Xojo project. If they don’t match, then you can expect errors throughout the process.
The second thing is to create a new record for the App itself in the App Store Connect website. This is the place where you need to provide all the information requested by Apple for two main things: 1. what will be available as the app information when the users reach your app in the Mac App Store (for example product description, price, images, etc.), and, 2. what is for internal and compliance use. All in all, make sure you create a new macOS app record and go through all the available sections to fill in the requested information.

Once these two steps are completed, we can focus on the command line itself to create the .pkg file and upload it manually (optionally, it is possible to use the Transporter app to select the .pkg file and upload it).

Sing, sing, sing … the re-signing song!

When building the macOS app from the Xojo IDE, it will be correctly signed based on the settings selected in the Build Settings > Sign section. But because of the way Apple requires some entries to be formatted (specifically those for the CFBundleShortVersionString and CFBundleVersion keys), and the fact that it also requires the LSApplicationCategoryType key to be present in the Plist file with the associated value (the app category value among those you can find here), we need to manually edit the generated Info.Plist file for the compiled app.

Yeah, sure we can create an additional text file named Info.Plist file with the appropriate/expected keys and values and drop such file in the IDE navigator for our project so this information gets added/modified, as for example this one:




	CFBundleShortVersionString
	1.0.0
	CFBundleVersion
	1.0.0
	LSApplicationCategoryType
	public.app-category.business

The bad news is that the value for the CFBundleVersion key will not be replaced with the one from our Info.Plist file.

What’s the downside of manually editing the Info.Plist file for the already compiled app? Well, as soon you make a change and save it, the app bundle signature will be invalidated. But no fear! We know how to do it already, right? If not, I suggest you to take a look to the blog post about Sandboxing, Hardened Runtime and Notarization for macOS apps that I mentioned earlier.

Go ahead, select your compiled app in the Finder, click on its icon and select the option “Show package Contents” from the contextual menu. This action will show the “inner files” of the bundle that composes your app. Inside the Contents folder you will see the Info.Plist file. Click on it and select the option from the contextual menu allowing you to edit it with the text editor of your preference (mine is to use BBEdit from BareBones Software).

Locate the CFBundleVersion key entry and change its string value so it doesn’t have more than three numbers separated by the dot character (as shown in the previous Plist example file).
Locate the CFBundleShortVersionString and change its string to make sure it has three version numbers separated by the dot character.

Of course for both of the previous keys, make sure these match your expected version numbers for the app! In the example I used 1.0.0 as it’s typical for the initial release of an app.

Next, add the expected LSApplicationCategoryType key with the value that better fits your app among those available at the Apple Documentation website. In the previous Plist file example I’m using the one for the Business category:

	LSApplicationCategoryType
	public.app-category.business

Save the changes to our modified Info.Plist file. Now it is time to sign it again!

What about the Entitlements?

Heh… wait! Because we need to re-sign our app bundle again, we also need to attach the expected entitlements to it! That means at least one very-important-and-required entitlement: enabling Sandboxing, which needs to be done to any app sent for distribution through the Mac App Store.

While Xojo 2024r4+ is able to do it automatically when building the app, now we also need to do it manually. That means creating our own .entitlements file that will be used when re-signing the app. For example, for a very typical (and bare-bones) app that only needs to read and write files it would look like this:




	com.apple.security.app-sandbox
	
	com.apple.security.files.user-selected.read-write

Save it as “myEntitlements.entitlements” to your Mac drive. Of course, if you app requires more entitlements, go ahead and add them to the previous “template” .entitlements file.

We now have our modified .Plist file and the required .Entitlements file… so we have everything we need to re-sign the app bundle again!

Open a Terminal window and type the following command:

codesign --force --timestamp --entitlements path-to-your-myEntitlements.entitlements-file  -s "Apple Distribution: whatever-name-you-use (BZXXXXXXX)" path-to-the-bundle-of-the-compiled-app.app

Look how we are using the reference to the entitlements file, and the “Apple Distribution” certificate instead of the “Apple Development” certificate.

Packaging Acme

So far so good. We have our app bundle signed again, so we are ready now to create a .pkg file from it! All you need to do is to type the following command from a Terminal window:

productbuild --sign "3rd Party Mac Developer Installer: whatever-name-you-use (BZXXXXXXX)"  --component path-to-the-bundle-of-the-compiled-app.app  /Applications path-to-the-generated-package-file.pkg

As you can see, we are using the “3rd Party Mac Developer Installer” certificate in order to create the package file.

Uploading it!

With the package file already created, we now have all we need to upload it to the App Store Connect website. At this point you can follow two paths. The first one is to use the Transporter App that you can download from the Mac App Store itself. In that case:

Open the Transporter app.
Click on the “+” icon. That action will bring a dialog where you can select the previously created .pkg file.
Once it is added, Transporter will make some early checks on the package contents. If everything goes OK, you should see something like this:

The interesting thing about using Transporter is that you can select the “Verify” option from the associated contextual menu (the one with the three dots icon). That action will start some more deeply checking on the package (and its contents) so you can get some early information about things that need to be fixed prior uploading it to the App Store Connect Website. For example, this error generated when the bundle version is duplicated:

The second option involves using the aforementioned altool command line to automatically upload the package to the App Store Connect website. If you choose this path, all you need to do is to execute the following command from a Terminal window:

xcrun altool  --upload-package path-to-the-package-file.pkg -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --type osx -apple-id "6111111111" --bundle-id "com.yourcomany.yourIdentifier" --bundle-short-version-string "1.0.0" --bundle-version "1.0.0"

Some considerations about the provided options/values for this command:

-u: This is the login name you use when accessing the Apple Developer website
-p: This is the app-specific password you created from scratch following the steps provided in the aforementioned blog post.
-apple-id: This is the numeric value you can find under General > App Information at the appstoreconnect.apple.com website for the record created for this app:

This information can also be retrieved using:

xcrun altool --list-apps -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --output-format json

–bundle-id: Make sure to provide the same value as the one used when creating the Identifier for the App and, thus, the same one used under Build Settings > macOS > Build > Build Identifier field in your Xojo project.
–bundle-short-version-string: Make sure it’s the same value used for the CFBundleShortVersionString key in the .Plist file.
–bundle-version: Make sure to provide the same value as the one used for the CFBundleVersion key in the .Plist file.

Once the command is executed, your package file will be uploaded to the App Store Connect website and, once completed, eligible as a new Build to be added to your app record so you can send it to review as part of the Apple reviewing process.

In Summary

There are several details to take care of, but Xojo has simplified the process of covering the “last mile” of sending you compiled app for review at the App Store Connect website.

More in this series on distributing Mac apps:

Conditional Statements: Select Case vs. If…Else Explained

Gabriel Ludosanu — Mon, 16 Dec 2024 19:00:00 +0000

When you’re writing code, you often need to make decisions based on different situations. These decisions are handled using conditional statements. Conditional statements let your program choose what code to run based on whether certain conditions are true or false. Two of the main ways to do this are: Select Case and If…Else statements. They both help your program decide what to do, but they work a bit differently. This article will explain how each statement works, when to use them, and how to choose the best one for your code.

The If…Else Statement

You’ve probably seen If...Else statements in other programming languages too. They’re like the basic building blocks for making decisions in your code. The main strength of If...Else is that it’s very flexible. It lets you check if something is true or false and then do different things based on the answer.

You can also combine conditions using And and Or.

And: Checks if both conditions are true. For example, If age > 18 And hasLicense = True Then (You need to be over 18 and have a license).
Or: Checks if at least one of the conditions is true. For example, If score > 90 Or extraCredit = True Then (You can get an A if your score is over 90 or if you did extra credit).

You can even add more options using ElseIf to create more complex sets of rules. Think of it like a choose-your-own-adventure book where the story changes based on your choices.

Pros of If…Else:

Flexibility: Handles all sorts of situations, even complicated ones where you need to check many things at once.
Suitable for Two-Outcome Scenarios: Perfect when you just need a simple true/false check.

Cons of If…Else:

Readability: When you have lots of ElseIf parts, the code can get really long and confusing, like a maze with too many turns.
Maintainability: Changing a big If...Else statement can be tricky. It’s easy to make a mistake and mess up how the code works without realizing it.

Example:

Var age As Integer = 25
Var message As String

If age < 18 Then
  message = "Minor"
ElseIf age >= 18 And age < 65 Then
  message = "Adult"
Else
  message = "Senior"
End If

System.DebugLog(message)

The Select Case Statement

The Select Case statement is like a neat and organized way to deal with a list of options for one thing. Imagine you have a variable, like a number grade. Select Case lets you check that grade against different cases (like “A”, “B”, “C”) and then do something specific for each grade.

Example:

Var grade As String = "B"
Var feedback As String

Select Case grade
Case "A"
  feedback = "Excellent"
Case "B"
  feedback = "Good"
Case "C"
  feedback = "Fair"
Case "D", "F"
  feedback = "Needs Improvement"
Else
  feedback = "Invalid Grade" // This is the default case
End Select

System.DebugLog(feedback)

The Else Case In a Select Case statement, acts like a default. If none of the other cases match the value you’re checking, the code inside Else will run.

Using Ranges in Select Case

You can also check for ranges of values using To. For example:

Var score As Integer = 85
Var grade As String

Select Case score
Case 90 To 100
  grade = "A"
Case 80 To 89
  grade = "B"
Case 70 To 79
  grade = "C"
Case Else
  grade = "D" 
End Select

System.DebugLog(grade)

Pros of Select Case:

Readability: Makes your code super clear when you’re dealing with multiple options for a single thing.
Maintainability: It’s easy to add, remove, or change the different options without messing up the rest of your code.
Efficiency: Sometimes, Select Case can be faster than a long If...Else chain.

Cons of Select Case:

Only Works with One Thing at a Time: It’s mostly for checking one variable or one simple calculation against a list of possibilities.
Less Flexible: It’s not great when you need to check lots of different things at once or do complicated comparisons.
Range limitations: If you are comparing ranges of numbers, you have to be careful about the order of your cases.

When to Use Which

Use If...Else when:
- You only need to check if something is true or false.
- You need to check many different things at the same time using “and” or “or”.
- You need the most flexibility to handle all sorts of situations.
Use Select Case when:
- You’re checking one thing against a list of possible values.
- You want your code to be super clear and easy to understand.
- You want a neat way to organize different options.

Best Practices

Use meaningful names: Choose names for your variables that clearly describe what they store (e.g., studentAge instead of just age).
Keep it short: Try to keep the code blocks within your If...Else or Select Case statements relatively short and focused. If a block gets too long, consider breaking it down into smaller parts.
Comment your code: Add comments to explain what your code is doing, especially in complex If...Else statements. This will help others (and your future self) understand your code.

Conclusion

Both Select Case and If...Else are useful tools for making decisions in your code. Choosing the right one depends on what you need your code to do. If...Else is great for handling complicated situations, while Select Case is perfect for keeping things clear when you have a list of options. Knowing when to use each one will help you write better code that is easier to understand and work with. By thinking about what you need to check and how clear you want your code to be, you can use both of these statements to create awesome apps!

Update

Since the time this article was published, our great Xojo community has taken the discussion even further! On the Xojo Forum, developers have shared advanced examples, creative use cases, and expert tips for using If…Else and Select Case statements.

Be sure to check out the thread here: https://forum.xojo.com/t/re-if-then-vs-select-case/83633

We’re continually inspired by the passion and knowledge of our community—thank you for making Xojo such a collaborative and supportive space!

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!

Tutorials – Xojo Programming Blog

Code Signing on macOS: What Developers Need to Know, Part 4

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

How the Xojo IDE helps with all of this?

Developer ID – Build For

Sandboxing

Hardened Runtime

Notarization

Entitlements

Provisioning Profiles

Property List Editor

Publishing to the Mac App Store

Dealing with Certificates Issues

Backup Your Certificates

Review Pending Apple Developer Agreements

Missing and Expired Certificates

Certificates are all good… but the signing throws errors

In summary

Build a Simple Find in Files Function

What this Find in Files function will do

Step 1: A class in a module and some properties

Step 2: Walk through the folder

Step 3: Read files line by line

Step 4: Match the text

Step 5: The full module and class and function

How it works

Input validation

Folder iteration

Safe text reading

Line-by-line matching

Why keep SearchHit inside the module?

Using the function

Practical limitations of this version

It assumes UTF-8

It doesn’t recurse into subfolders

Final thoughts

Custom Control Rendering with DrawControlInLayoutEditor

Why this matters

How it works

A note about XojoScript limitations

Support for more Graphics

Turning off this feature

Finally

Watchpoints in Xojo: A Smarter Way to Track Your Data

What Are Watchpoints?

How Watchpoints Work

Why This Matters

Conditional Watchpoints

Handling Object Lifetimes

What works and what doesn’t

Final Thoughts

Optimizing Xojo Code, Part 5: Threads and UserInterfaceUpdate

The Core Idea: Threads

Let’s Code

The Thread Control

The Button (Start the Thread)

The Thread.Run Method (Background Work)

The Thread.UserInterfaceUpdate Method (UI Sync)

How It Works

A Note on Thread Safety

When to Use Threads vs. Timers

Wrapping Up

Scatter Chart: Connecting the Points

A change of Style… on the fly!

Summary

Optimizing Xojo Code, Part 4: Timer.CallLater

The Strategy: Timer.CallLater

Looking at the Code

The Setup (Button Pressed)

The Handler (Recursive Chain)

How It Works

Wrapping Up

Xojo + XAML + Goto = 🔥

Visual States in XAML

Example XAML

Triggering the Transition from Xojo

Why This Is Powerful

Optimizing Xojo Code, Part 3: Programmatic Timers and AddHandler

The Strategy: AddHandler

Looking at the Code

Why keep `SearchHit` inside the module?

Define `Pressed` Custom Event: