Xojo 2019 R2: API 2.0 is Here

Xojo 2019 Release 2 arrived this week, and to say that this is a massive release would be an understatement.  Among a large number of bug fixes and IDE enhancements is the first release of API 2.0.  With every release I say that you should test your projects thoroughly, but in this case it needs to be mandatory.

API 2.0

API 2.0 is Xojo’s latest attempt to make the framework consistent across all the classes and should be easier to learn and use than the old framework.  The properties, methods, and event names of practically every single class have changed.  Some have changed in subtle ways, and others in a bash you over the head fashion.  What might be even more important is that classes that used to set an error bit or error code will now throw an exception.

Some of the most basic things in Xojo have changed.  Declaring a variable has changed from using the Dim keyword to the new Var keyword.  Declaring an array is the same but resizing it is now accomplished like this:

//Declare the array

var arNames() as string

//Set it to a new size

arNames.ResizeTo(SomeIntegerValue)

//Clear the Array

arNames.ResizeTo(-1)

In various conversations Xojo has claimed that many users new to Xojo are confused about declaring variables.  I don’t claim to know a lot of other languages, but the few that I’ve looked up don’t appear to be any more helpful.  Looking at JavaScript and Swift, neither requires the data type when declaring a variable.  With no functionality enhancement this seems like a change for the sake of change.

Every Window and Control that comes with Xojo 2019 R2 has new events.  Open, which admittedly can be confusing, is now replaced with the equally confusing Opening event.  Close is Closing and so on.  I have yet to find any direct mapping document of old events to new events and that’s a crime.  

A complex control like the Listbox has dozens of events, properties, and methods and nearly all of them are renamed.  Some make sense.  ListBox.ListCount is now ListBox.RowCount.  But ListBox.EditCell is now ListBox.EditCellAt.  To append a row to a Listbox you still use ListBox.AddRow, but to insert a Row you substitute ListBox.InsertRow with ListBox.AddRowAt.  I simply don’t see why AddRowAt is easier to remember than Insert (I could argue that InsertRow makes more sense).

Some changes I strongly disagree with.  For example, Arrays in the old framework were simple enough to add items to:

dim arMyArray() as integer

arMyArray.Append 1000

arMyArray.Insert 0, 2000

With API 2.0 the Append and Insert methods are replaced with AddRow and AddRowAt.  Again, one can argue that removing Insert and replacing with AddRowAt is simply a poor use of the English language.

Pre-API 2.0 Projects

The good news is that existing pre-API 2.0 projects will work with only a few modifications.  In our projects (Task Timer, Shorts, ARGen) there were little to no changes required to get them to compile in R2.  And the good news is that you can continue to use the old API in R2.  The Code Editor AutoComplete will show you the old API and the new API with the old API call in Red and show you the new API 2.0 method or property.

Starting a new project in R2 will only show you the new API and events.  Certainly one of the drawbacks is that Xojo projects created in R2 are not backwards compatible.  Xojo has never really guaranteed that newer versions would be compatible and this is one of those cases where it’s simply not possible (theoretically if you never implement any events it will work).

My advice: Treat R2 with kid gloves and make backups of your project files before you play with it.

Events

Let’s talk about events for a bit.  I’ve already hit on the Open event that is replaced with Opening and Close that is now Closing.  I find nothing wrong with the new event names, per se, but anyone with an older project, or someone taking an older class and putting it into R2 must be extremely careful. The old Open and Close (and other) events will fire as expected – until someone implements the new API 2.0 event like Opening.  Once you do that the old event no longer works.  This has the potential of really messing with legacy products that use the old Events and new users not knowing the difference and implementing new events and crushing functionality.

Frankly I find events to the most problematic part of API 2.0 since I, as a provider of 3rd party code, can’t enforce that a Xojo developer use the new or old events.  It’s going to be a nightmare for the next couple of years (maybe forever?) as new people find old classes and implement them in their new R2 projects.  Events cannot be coded out with #if statements.  There is simply no way to control which events to use in a mixed environment.

If you’ve created your own control subclasses with custom events let’s hope you don’t have naming conflicts with the new event names.  The only way to solve this is to change your Event definitions in a pre-API 2.0 version of Xojo.

String Classes

Despite being a great idea, the Text datatype from the Xojo framework never really caught on.  As part of API 2.0 many of the Text methods have been brought to the String datatype.  As with all the other classes nearly every method and property name has changed in some way, shape, or form.  

The biggest change, and perhaps the most problematic, is that the string functions are now zero-based.  The first character of a string is zero and no longer one.  The InStr method has been replaced with IndexOf (bad name in my opinion) and instead of returning a zero if the search string is not contained it will return a -1.  Don’t get me wrong, this is a good change in the long run, but when developers are converting their projects from pre-API 2.0 things like this are going to bite a lot of developers as it’s not a direct replacement.  You can’t just simply use IndexOf to replace InStr because it will break your code.  Expect some grumbling about this from the greater community.

Date and DateTime Classes

Xojo has deprecated (not removed) the existing Date class and has created a new DateTime class.  This is mostly a rehash of the Xojo.Core.Date class but it uses Strings.  The new DateTime class is not a direct replacement for Date since the DateTime class is immutable. In effect if you’re doing any sort of date math you’ll need to use the new DateInterval class.  The DateTime class also does not have TotalSeconds but instead has a SecondsFrom1970 property.  To get a New DateTime you use the Now shared method instead of creating a new instance of it.

FolderItem Changes

The FolderItem class was significantly updated on macOS and uses Apple’s more modern API’s.  This should make file operations significantly faster on newer versions of macOS. FolderItem.AbsolutePath has been removed (it’s been deprecated for a while now).

Because of these changes you really need to be careful with URL Paths with query parameters.  The behavior between R2 and earlier versions of Xojo has changed significantly.

Database Changes

The database classes have some welcome changes that have huge implications.  Besides new classes, methods, and properties for everything to do with the database, any interaction with the database has the potential of throwing an exception.  In the old API you had to explicitly check for the Error property.  Now it will throw an exception that you have to capture and handle.  This is both good and bad.

With ActiveRecord and ARGen we’ve been throwing exceptions for years when we found the database error property to be true.  So not a big change for us, but for anyone that’s ever checked to see if a RecordSet is nil will be surprised when the exception is thrown.  This is guaranteed to get your attention (many people never checked for the db error anyway!) but it will be a pain for many developers. Database code will need to be in a Try-Catch block, and doing this in a proper Transaction will cause some structural changes to your code.  

RecordSets are deprecated.  Long live the RowSet!  RowSets are returned from Database.SelectSQL and instructions are passed through Database.ExecuteSQL.  This is in contrast to the old SQLSelect and SQLExecute methods respectively.  I can guarantee that I will mix the old and new versions up for many years to come.

PreparedStatements are no longer needed as they are built-in to the SelectSQL and ExecuteSQL statements.  You no longer have to Bind the DataType and Value as the class does it for you.  This is similar to what iOSSQLiteDatabase has done for years and hopefully this gives everyone more incentive to use them.  PreparedStatements were a pain to use and this new method is considerably more streamlined.

One word of caution to anyone that uses the MBS SQL plugin:  You must update to the 19.4 version as the database class changes required the plugin to be updated. Older versions of the plugin will fail silently and may cause other plugins to not load properly.

Other Things

URLConnection received some updates.  In Windows 7 and 8 it picks up proxy settings.  It also no longer hangs a Windows application when downloading large files or content.  In Linux a ResponseHeader that no longer exists doesn’t crash the application.  They also made the ResponseHeaders an iterable function allowing the use of For-Each loops.

They (finally) added BeginTransaction to the Database class.  It’s silly that this hasn’t been part of the framework for the past decade.

The Code Editor received some interesting changes.  Pressing Shift-Return on an existing If-Then or If-Then-Else will now break the statement into multiple lines.  On a comment line holding the shift key and pressing Return automatically adds another line of comment.

The Layout Editor has some changes too.  It now has a control to switch between Light and Dark modes.

There is now a number of new Refactoring Tools available and they fixed a number of bugs in the refactoring tools.  They added a new code assistant for wrapping the selected code in an #if XojoVersion block (handy with all the new API 2.0 changes).  The Add Event dialog has been updated to allow adding deprecated events when a checkbox is selected (deprecated events are in red).  In the same light you can right-click on an event in the Navigator and choose to convert it to the newer API 2.0 event.

The FileTypes editor and Associated File Types editor have been combined into a single editor.  File Type Roles have been renamed to None, View, Edit, and Execute.  For MacOS you can set if the File Type is unique to the application.

Catalina may force many developers to upgrade sooner rather than later.  The SelectColor function was updated in R2 to no longer use an outdated API function.  Using SelectColor with an app built before R2 will reliably crash on Catalina.  The only solution is to build with R2 or use NSColorPanel yourself with declares or the MBS plugin.

Documentation

Maybe I’m just an old school person and a curmudgeon but I find the lack of Old to New documentation extremely disappointing.  Xojo has a Deprecated list at https://docs.xojo.com/Category:Deprecated but I find it worthless.  I’d like to look at a single class at a time and have all of the events, properties, and methods showing the old name and then the new name along with any comments.  I realize this is a lot of work but I’m surprised that Xojo didn’t create this documentation BEFORE doing any coding to use as their coding bible. 

Any old example, sample project, old forum post, Google search result is now obsolete.  BKeeney Software’s 65+ hours of Xojo training video that covers a good chunk of the Xojo framework is now practically worthless.  I will be shutting the doors of the training site because it’s not worth my time (at this point) to redo over 200 videos.  Xojo needs to convince me otherwise.

Deprecation Items That Have a Replacement

The Xojo IDE tries to be helpful in converting your projects to API 2.0. There will probably be a handful of things that will flag compiler errors in your pre-API 2.0 projects. If you Check your project you will get a rather large list of items that are deprecated that have a replacement. This list can be overwhelming and I recommend NOT doing global search and replace on these items because the code is sometimes quite a bit different. Good luck!

My Advice

If you have an existing project I would be very carefully with R2.  Sure, try it out on a *copy* of your project, but don’t expect to use R2 right away.  I’m almost sure that there will be changes to fix bugs and strong community objections to certain things.  We already know that Reporting and XML was NOT done for R2 and I’m sure we’ll find other things along the way too.

For developers using R2, please be patient.  Get used to the question:  What version of Xojo did you start with?  The community is going to struggle with the changes for a while and we have no idea that his means.

All in all I think there are some good changes to Xojo 2019 R2 but I also think that there was a lot of change merely for the sake of change.  I’m not convinced that all the changes were for the better.  But really, only time will tell.

The Good

  • IDE received quite a few tweaks
  • Lots of bug fixes and enhancements
  • API 2.0 is mostly consistent with naming (with some oddities for sure)
  • Lots of bug fixes and enhancements
  • Exceptions now thrown instead of having to check for error codes
  • FolderItem significantly upgraded for macOS
  • DateTime added as a replacement for Date class

The Bad

  • API 2.0 is not entirely done yet with more changes to come
  • Change for the sake of change in some cases
  • Exceptions for common and expected errors is not ideal
  • New String methods are not drop-in replacements because they are zero-based

The Ugly

  • API 2.0 event handling prevents API 1.0 events from being raised
  • Documentation woefully incomplete
  • All existing documentation, examples, videos are obsolete

What topics would you like for me to talk about with API 2.0?  What do you like and dislike about API 2.0?

Edit: Fixed some typo’s.

XDC 2019 Ruminations

The 2019 Xojo Developers Conference (XDC) wrapped up last Friday. It’s my favorite event of the year and while I’m sure many people think that I’m an extrovert I can only play one for shorts periods of time. I’m enjoying the peace, and more importantly, the quiet at home today hoping to recharge my social battery before having to attending a high school robotics meeting, mandolin orchestra rehearsal, and a mandolin concert this week. Oh, and I have to pick my sone up in Chicago. No pressure to get things done, no?

XDC is my favorite time of the year. While attendance was down this year (more on this in a bit) a lot of people from Europe made the trip over to Miami. It was good to see a lot of old friends and awesome to make some new ones. To me, it’s the connections you make and the stories you hear from other Xojo developers that is inspiring in so many ways.

The keynote address by Geoff was…underwhelming. It was the usual mix of how the community is doing, what they’ve done since last XDC and what they’re working on. As expected they’re working on Web 2.0, API 2.0, Interops, and Android. The best timeframe Geoff gave for anything was ‘soon’. At least we didn’t have the mental gyrations over ‘priority’ and ‘important’ like last years XDC.

It’s hard to show much for big ticket items like Web 2.0 and Android. These are big multi-year projects that you just can’t show off without having significant work done on them. For Web 2.0 the demo that Greg gave seemed pretty solid but then there weren’t a lot of details. It did seem solid and that was good news in my opinion. The Android demo, on the other hand, looked much more scripted and not nearly as smooth – it had the feel of ‘this is something we know works and we’re not going to do much outside the script’ feel to it. For API 2.0 there wasn’t much to show except some before and after code snippets.

So on one hand the keynote wasn’t all that exciting. On the other they didn’t have much to show because it’s work in progress. They threw some numbers out like 70% complete in which the pessimist in me said, “great, that means there’s still 70% of the work left to be done.” The people around me at the keynote had some similar thoughts as mine. To be fair, ‘completion percentage’ means something different to everyone.

I am very excited about Web 2.0. It’s a rewrite of the entire framework. You have to keep in mind the original framework was done ten years ago and the web has changed drastically since then. The work they’ve done on theming is going to make our Xojo web apps look fantastic and since more processing is done on the client side it should make apps a lot more responsive. We’ll have a LOT more controls to play with too.

To be honest, I’m pessimistic about Android. I’m sorry, but two years later we’re still waiting for a release. With work still to be done on the Xojo framework items (think FolderItem) and the debugger I just don’t see that happening by the end of the year. Prove me wrong, Xojo.

Jim Meyer’s presentation on using AWS and Google Machine Learning API’s with Xojo was fascinating. Using their API’s it’s easy to do text transcription from text and video, recognize images, do facial recognition and much more. It was by far my favorite session I attended. I can’t wait to get the example projects and try them out on a few things.

I didn’t attend this session but attendees were buzzing about Monkeybread Software’s DynaPDF plugin. The big news was that Unicode support will be added by the end of the year and that we’ll be able to create PDF’s by drawing directly into the Graphics object provided by the DynaPDF class. All good news.

Michael Dettmer showed an interesting way to quickly create database applications for Xojo using an Apache Velocity and his own open source software called CAPP, or Computer Aided Program Production. Essentially you create templates for the various things you want and it creates a project for you. The drawback is you have to use Apache Velocity and Java to do some of the coding. I’m not doing the demo justice but it did look a bit more complex than many Xojo developers might be capable of. However, consultants might find this tool essential since you do a little work up front to create a database application. You can read more at https://capp.systems

Yousaf Shah had a great session on how to get happy customers, successful projects, and live stress free. Yousaf said that developers aren’t always the most empathetic people and it’s hard to put yourself in the client position. When mistakes are made you don’t have to admit a mistake but saying, “I’m sorry you feel that way,” is important. He also spent some time showing how we can go from features to tasks (wrong word) so that you can get a better feeling for what the client really wants while also letting them be in control driving what’s important to them.

One session that I thought was fairly depressing was the Ask the Engineers session. Greg, Travis, William, and Paul did a good job of answering questions from the audience but it was shocking to see that few of developers working on the product. They’re one heart attack away from major portions of the project to be delayed. If you didn’t know, Paul has been moved from his Evangelist role to an engineering role. Since last XDC Norman was let go and Joe (compiler) has moved on to another job. Geoff can say all day long that they have enough resources but I just don’t buy it. More engineers means more stuff gets done.

Not giving us any timeframe for releases is one reason why I think attendance was down this year. If you don’t think there will be any big news and hands-on with cool, new, stuff then what’s the point of the attending? I disagree with the reasoning but I understand it when it’s a significant cost to attend.

No XDC in the United States next year. They are looking at something overseas. No word on where they’re looking but since MBS has conferences in Germany that are well attended I suspect some place other than Germany. But who knows? Like everything else they’ll tell us when they tell us and BKeeney Software will most likely be there. After all, it wouldn’t be a Xojo Developer Conference with us being there! See what whenever and wherever the next one is held.

Thoughts on XDC 2019?

XDC 2019 – API 2.0

At XDC 2019 Paul Lefebvre and Travis Hill did a session on API 2.0.  For those not familiar with API 2.0 it’s the result of the best parts of the Xojo Framework getting merged back into the global framework without the heavy use of the Text and Auto datatypes.

The first version of Xojo (AKA REALbasic) was in 1998.  Supported Mac 8.  Now in 2019 MacOS, Linux, Windows, iOS, Web, Raspberry Pi and soon to be Android.

The goals of API 2.0:

Utilities language improvements.  In 1998 no shared methods and other features available now.

Improve Consistency.  Naming was often based on specific OS things that don’t exist before.  

Better Naming.  

Exceptions, not Error Codes.  Error codes get ignored – Exceptions are now.

Fewer Globals.

More Enumerations.  Constants lead to enforcement issues.

Similar API for Controls

But overall, don’t want to change what works.  The global framework has worked great for many years.

Progress Update:

Large portion of API 2.0 will be rolled out soon.  “All” from Geoff’s keynote may not be accurate

When it happens they’ll be deprecated – NOT removed.  It’ll be there for many many years.

Stop using in documentation and code examples.

API 2.0 Benefits

Code is more readable.

Easier for new users to learn.  Most consistent for existing users.

Easier for all when working across project types.

Notable New Features

URLConnection.  New in 2018 R4.  Added Synchronous to the Asynchronous option.  Uses OS API’s.

Var and ResizeTo.  Synonyms for Dim and Redim.  Var is better term and used in other languages.  

Notable Changes

Databases

Exception Handling.  No longer uses error checking.  Works on Connect, ExcecuteSQL, SelectSQL.  

DatabaseField -> DatabaseColumn

DatabaseRecord ->DatabaseRow

Recordset -> RowSet

BeginTransaction

Binding is now embedded in the SelectSQL.  Infers the BindType from the DataType.  

FolderItem

Uses Exceptions

Open methods moved to more appropriate classes (OpenAsMovie, OpenAsSound, OpenAsVector)

Item -> Child

Listbox

ListCount -> RowCount

ListINdex -> SelectedIndex

Cell -> CellValueAt

DeleteAllRows -> RemoveAllRows

RemoveRow -> RemoveRowAt

ColumnFromXY -> ColumnAtPoint

Header -> HeaderAt

Other

ToString/FromString on Date and numeric types

String.BeginsWith, EndWith, IndexOf.  All methods will be zero based.

Timer.CallLater, Tolerance

Date intervals and time zones

Random is now a singleton class.

Point, Size, Rect no longer need the “Realbasic” prefix.

Desktop is first.  Then Web 2.0 and then mobile (first with Android then iOS).

You’ll be able to change code at your own pace.  None of the existing methods are going away.

This is a one way move.  The goal is to let older versions of the IDE still *open* API 2.0 projects.  Obviously you’ll get compile errors then.

Will deprecated stuff will not show in AutoComplete.  It’s doubtful if it will improve AutoComplete performance.