From Anthony: Let’s Talk API 2.0

Xojo 2019R2 is here! API 2.0 is here! Wait, what does that mean for GraffitiSuite? In short: Nothing right now! GraffitiSuite compiles without modification!

I’ve played with the Pre-Releases as work on API 2.0 progressed. I have to admit that I had some fairly major concerns as to how it was going to affect GraffitiSuite. So what were they?

Event Renaming

This was my big one. AddHandler calls could’ve been broken. I might’ve had to convert the entire codebase to using Opening event handlers/definitions as opposed to Open. The good news is, though, this was all dealt with! I did some more testing this morning, and everything seems to work the way I want, though users may need to be careful if they actually use the Opening event rather than the Open event as there might be some unexpected results.

The way this was handled works for me, as it gives me a bit more time to let the dust settle before I release a version of GraffitiSuite that begins targeting API 2.0.

Immutable Dates

Concerning. The vast majority of the Date code I’ve ever written in Xojo would need to be replaced to account for the changes. Feedback Reports and forums discussions again prevailed. We get to keep our original mutable Date class (albeit deprecated), and we have the new immutable DateTime class.

Again, I’m pretty happy with the direction they eventually took, but I hate the current implementations of DateInterval and TimeZone with a passion. It unnecessarily complicates the workflow. I’d have imagined something like the following if they really wanted to get away from the mutable Date:

  • dateInstance.AddDays(1)
  • dateInstance.Add("1d")
  • dateInstance.toTimeZone("GMT")
  • dateInstance.toTimeZone(TimeZone.GMT)

Any or all of those would’ve been nice to have built-in. There’s a lot of room for improvement here, and I’m optimistic that they’ll add some more functionality here.

Global Moves

A lot of stuff that used to be in the Global namespace has been moved to relevant places. Color functions are now under Color. String functions are now extensions. Overall I think this is good, but there is room for improvement. As pointed out by countless others at this point, to perform functions on strings in API 2.0 like Mid, you now have to have the value stored in a variable. No more of that Dim keySeparator as Integer = Mid( "someKey=someValue", "=") nonsense. There are some suggestions to ease this from Norman Palardy and Thom McGrath by implementing generics in the compiler, but that’s probably a long time in the future (if it ever happens).

Overall, I think this is a decent change. Hopefully it’ll help speed up autocomplete to not have so much in the global namespace.

To Var or Not To Var

I actually really support the addition of the Var keyword. I work in JavaScript a fair bit these days, and I often catch myself typing Var in Xojo and Dim in JavaScript. This makes it easier for me to switch back and forth, and that I welcome.

Other Random Name Changes

I understand the goal. Make Xojo more like the English language, and less like its BASIC roots. I get it, I do. Then there’s Append vs AddRow. No. Just no. If you want to change it, fine, but who adds a Row to an array? It’s not a list. It’s not a database table. It’s an array. Just make it Add or AddItem, willya?!


I think the fair majority of us have bumped up against using 0-based indexes when functionality required 1-based indexes and vice-versa. Switching everything to a common start is definitely a positive, whether that be 1- or 0-based. That said, I’ve been doing this too long to support 1-based indexes across the board, so I’m all in on this change.


One thing I don’t like is that all of these deprecations are going to show up when customers analyze their projects. This means that I will inevitably get tickets about these, even though it’s not a bug and has no effect on the code’s functionality.


I’d love to be able to move to API 2.0 starting today, but I have some customers who, for one reason or another, are still using versions as old as 2015. If I move, I lose. I lose customers. I lose income. So, for the time being, I’ll be working to keep GraffitiSuite API 1.0 compatible.

I’ve also considered maintaining an API 1.0 codebase and an API 2.0 codebase. That, however, would be onerous when the code continues to function as well as it ever has. It just doesn’t make sense to double the workload.

I’ve always tried to keep up with each Xojo release, but this one I’ll have to avoid for a little while. I can’t abandon what could potentially be a massive portion of my customers over some changes that really didn’t create any major problems with GraffitiSuite.

All that being said, I will be using 2019R2 and API 2.0 for my other projects and consulting as required, but I can’t alienate customers with these changes. The tipping point will come when I’ll go all in on API 2.0, but this is not that day.