API 2 guidelines

With Xojo 2019 Release 2 there are significant changes for API 2.0. In most cases you do not need to do anything as you can continue to run your old code as it is, but there are a few changes that may affect your projects.

Xojo 2021 Release 3 added new Desktop-prefixed controls that replace the existing desktop controls but with event names that follow the API 2.0 guidelines. Existing projects will continue to use the legacy controls while new projects will use the new controls. However, as long as you are using 2021r3 or later, you can mix and match new and old controls in the same project.

Note

There's no need to rush to change code to API 2.0. We expect that most of you will upgrade parts of your code only when doing so provides some advantage like a bug fix or new functionality. The APIs that have been replaced with new ones will likely be around for many, many years. For more information, check out our Your Path Forward with API 2.0 blog post about transitioning to API 2.0.

General information

Analysis warnings

The warning for "Item1 is deprecated. You should use Item2 instead." is now unchecked by default in the Project->Analysis Warnings window. If you want to see all the API 2.0 deprecations when you Analyze Project (or Analyze Item), you can turn it on manually.

Project file Format

Files created in versions prior to 2019r2 can be opened in 2019r2. These projects will have new Inspector properties converted when the project loads, which can slow down loading for large projects. This does ensure your project remains backwards compatible, however.

If you want to convert your project to 2019r2 format, which means it cannot be opened in earlier versions, you can do a Save As. This will save the converted property names in the project file, thus allowing the project to open more quickly since it will no longer have to do any conversions.

Language

Var

You can now use Var in place of Dim to declare variables.

This change means you can no longer use "Var" as a name for a method, property, class, etc.

Use Arrays.ResizeTo in place of Redim to resize an array.

Extension methods

You should check to see if you have any extension methods that conflict with new Xojo class methods as these can cause compilation errors.

Classes

Date and DateTime

The DateTime class was added to provide a smarter way to managing your dates and times. Date continues to work as before.

Classes that had a date property now have an additional property that uses "DateTime" as the suffix instead of just "Date". For example, FolderItem.ModificationDateTime.

Application

If you use the (now deprecated) ToolTip class on a DesktopContainer or within a DesktopUIControl subclass you will have to prefix it with "Global" so that it does not get confused with the new Tooltip property.

Global.ToolTip.Show("Hello", 10, 10)

Or you can instead use the ShowTooltip and HideTooltip methods on DesktopApplication.

SerialConnection

When migrating from Serial to SerialConnection, if you change the Super from Serial to SerialConnection you may now have events on SerialConnection that no longer are relevant (for example, DataAvailable). You should add the appropriate SerialConnection events (DataReceived, for example), move the code over and then remove the older events.

SocketCore.Error

Sockets now use exceptions so the Error event has a new parameter to pass in the exception. If you are using AddHandler to map this event to a method then you will need to update your method signature to include the new parameter.

User Interface controls

DesktopSegmentedButton

The DesktopSegmentedButton replaces SegmentedControl. You cannot just change the Super of a SegmentedControl to DesktopSegmentedButton, however. You will need to add a DesktopSegmentedButton and move your code over to events as appropriate.

File I/O

FolderItem

FolderItem was updated to use the latest APIs on macOS.

These properties and methods were removed as they are no longer supported by macOS:

FolderItem.AbsolutePath
FolderItem.MacDirID
FolderItem.MacFSRef
FolderItem.MacCreator
FolderItem.MacType
FolderItem.VRefNum
FolderItem.ResourceForkLength

Note: The : (colon) character is no longer the path delimiter on MacOS. Paths are now delimited with the / (forward slash) character.

Note: In past versions, the FolderItem constructor that took a path truncated at the ? character. The same constructor now provides the entire path.

SpecialFolder

The Var property has been removed and replaced with Variable. Correspondingly, VarLog is now VariableLog.

Databases

PreparedSQLStatement interface

This interface has two new methods: ExecuteSQL and SelectSQL. If you are using this interface in your projects or plugins then you will also need to implement the two new methods.

SQLiteBLOB

This class now raises an IOException on any Read/Write errors (instead of you having to check the ReadError/WriteError methods to see if they are True).

Other

Readable interface

The EndOfFile method was added. If you have classes that uses Readable you will also need to implement the EndOfFile method on the class.

Backwards compatibility and events

There are a few features you can use to help make it easier to keep your projects and libraries backwards compatible with pre-API 2.0 versions of Xojo.

Compatibility flags

There are two compatibility flags available for projects items, methods, etc. that you can use to indicate the API version that the item is compatible with. For example, you can indicate that a method should only be available in 2019r2 or later by checking the API 2 compatibility flag. Or you can indicate something should only be available for versions prior to 2019r2 by checking the API 1 flag.

Note: Compatibility flags are shown on the Advanced tab of the Inspector.