Here's a scenario that trips up more Xojo developers than it should. You're working through a tutorial, a forum answer, or an older project. The code looks reasonable. You paste it into your IDE. It doesn't compile. The error message points to a class name you've never seen, or worse, a class name that looks almost right but isn't quite.

The culprit, more often than not, is the API rename that shipped with Xojo 2019r2.

Understanding what changed, why it changed, and how to work cleanly within one API generation is one of those things that separates developers who fight Xojo from developers who work with it.

What Changed and Why

In 2019r2, Xojo introduced a significant rename of its core framework classes. The goal was clarity: the old names didn't indicate what kind of control something was. PushButton could be a desktop button or something else. Listbox didn't tell you it was a desktop control. The new names do.

The pattern is straightforward. Desktop controls gained a Desktop prefix. Web controls gained a WebUI prefix or were reorganized under the web framework. Some classes were renamed outright to better reflect their function.

Here's a sample of the most common renames:

  • PushButton became DesktopButton
  • Listbox became DesktopListBox
  • TextField became DesktopTextField
  • TextArea became DesktopTextArea
  • Canvas became DesktopCanvas
  • Label became DesktopLabel
  • CheckBox became DesktopCheckBox
  • RadioButton became DesktopRadioButton
  • PopupMenu became DesktopPopupMenu
  • ComboBox became DesktopComboBox
  • Slider became DesktopSlider
  • ProgressBar became DesktopProgressBar
  • HTTPSocket became URLConnection
  • TCPSocket stayed TCPSocket (unchanged)
  • Window became DesktopWindow
  • MoviePlayer became DesktopMoviePlayer

This isn't a complete list, but it covers the controls and classes you'll encounter most often. When in doubt, check the Xojo documentation for your version. The framework reference is the authoritative source.

The Core Problem: Mixed API Code

The rename wasn't a remove-the-old-add-the-new swap. For a period, both naming conventions coexisted. Old projects continued to work. New projects used the new names. Documentation evolved over time.

The result: the internet is full of Xojo code samples that mix both.

You'll see a code snippet that uses DesktopButton in one line and Listbox in the next. You'll find forum answers from 2021 that still use pre-2019r2 class names because the person answering was working on an older project. You'll find tutorials that were written before the rename and never updated.

This creates a specific, frustrating failure mode. The code looks coherent. The logic is sound. But it won't compile cleanly on a modern Xojo installation because half the class names are from a different era.

The rule is simple: pick one API generation and stay in it. Don't mix old and new names in the same project. Every code sample you write, every class you create, every method signature you define should use the same naming convention throughout.

How to Tell Which API a Code Sample Targets

Before copying code from any external source, do a quick scan:

  • If you see PushButton, Listbox, TextField, or Canvas without a Desktop prefix, the code targets the old API.
  • If you see DesktopButton, DesktopListBox, DesktopTextField, or DesktopCanvas, the code targets the new API.
  • If you see both in the same sample, the code has a problem. Fix it before using it.

For networking code specifically: HTTPSocket is old API. URLConnection is new API. These aren't just renames. URLConnection has a different event model. You can't swap one name for the other and call it done.

Migrating an Existing Project

If you're maintaining a project built before 2019r2 and you want to move it to the new API, Xojo provides a migration assistant. It's not perfect, but it handles the mechanical renames reliably.

The process looks like this:

  1. Open your project in a current version of Xojo.
  2. Xojo will flag old API usage in the IDE. Look for the deprecation indicators.
  3. Use the built-in autocorrect and migration tools to rename controls and classes systematically.
  4. Test thoroughly after migration. The renames are mostly mechanical, but event model changes (particularly around URLConnection) require code review, not just find-and-replace.

A few specific things to verify after migration:

HTTPSocket to URLConnection: The event model changed. HTTPSocket used synchronous-style callbacks; URLConnection is event-driven with ContentReceived, Error, and RequestComplete events. Review every place you were making HTTP calls.

Subclasses: If you subclassed any of the renamed controls, your subclass declarations need to be updated too.

String references: If you stored class names as strings anywhere (unusual, but it happens), those strings won't be updated automatically.

In practice, I've found that the migration tool handles 90% of it cleanly. The remaining 10%, the places where behavior changed and not just names, is where you earn your debugging time.

Writing Version-Consistent Code

When you write Xojo code, whether for yourself, for a team, for a blog post, or for a forum answer, always specify which API generation you're targeting and stay consistent within that context.

Here's an example of new API code (2019r2+) that creates a simple HTTP request using URLConnection: 

// New API (Xojo 2019r2+)
// Fetch a URL asynchronously using URLConnection

Dim request As New URLConnection

AddHandler request.RequestComplete, AddressOf RequestDone
AddHandler request.Error, AddressOf RequestError

request.Send("GET", "https://example.com/api/data")

And the corresponding event handlers: 

// New API (Xojo 2019r2+)

Sub RequestDone(sender As URLConnection, url As String, httpStatus As Integer, _
                headers As InternetHeaders, content As String)
  If httpStatus = 200 Then
    // Process content
  Else
    // Handle non-200 response
  End If
End Sub

Sub RequestError(sender As URLConnection, url As String, error As RuntimeException)
  // Handle connection error
  MessageBox("Request failed: " + error.Message)
End Sub

For comparison, here's the equivalent using the old API (pre-2019r2) with HTTPSocket. Notice the structural differences. This isn't just a rename: 

// Old API (pre-2019r2)
// Fetch a URL using HTTPSocket

Dim socket As New HTTPSocket
socket.Get("https://example.com/api/data", 30) // synchronous with timeout
Dim result As String = socket.PageHeaders.Value("content")

These two patterns aren't interchangeable with a find-and-replace. They represent different approaches to handling network I/O. That's why migration requires review, not just renaming.

The Maturity Lens

If you're just starting with Xojo today, start with the new API. There's no reason to learn old naming conventions when you're building something new. Use DesktopButton, not PushButton. Use URLConnection, not HTTPSocket. The documentation, the IDE, and the framework are all organized around the new API now.

If you're maintaining a legacy project and the migration feels daunting, consider doing it incrementally. You don't have to migrate everything at once. Pick one module, migrate it, test it, and move on. The mixed-API problem is only dangerous when it exists within a single file or class. A project can have some old-API modules and some new-API modules, as long as each one is internally consistent.

If you're writing code to share, whether in a blog post, a forum reply, or a GitHub repo, always label which API you're using. A one-line comment at the top of the sample ("New API, Xojo 2019r2+") saves someone hours of confusion downstream.

The Bottom Line

The 2019r2 rename was the right call. Xojo's class names are clearer now. The framework is better organized. The old naming convention was a source of ambiguity that accumulated real maintenance debt over time.

But the rename created a years-long transition period that the ecosystem is still working through. Old code is everywhere. Not all of it is labeled. Not all of it has been updated.

Your job is to know which world you're in, stay consistent within it, and fix the mixed-API problems when you find them, before they find you at 11pm the night before a deadline.

Pick your API. Stay in it. Label your code.