UserGuide

API 2.0 Guidelines

From Xojo Documentation

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.

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.

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 not longer have to do any conversions.

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.

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.

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.

ToolTip

If you use the (now deprecated) ToolTip class on a ContainerControl or within a RectControl 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 Application.

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.

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.

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

Toolbar

You will want to change your button Supers from ToolButton to ToolbarButton so that they are properly passed into the Toolbar.Pressed event.

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.

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.

See Also

UserGuide:Moving To API 2.0 topic