Xojo API 2.0 - What and Why? Revised 10/28/2022
Back in 2019 (with release 2) Xojo shifted to API 2 (also referred to as API 2.0) subsequent releases fleshed out more of API 2.0 and finally with Xojo 2021 release 3, the rollout of API 2.0 was declared complete. There will surely be some additional tweaks and adjustments. And even Xojo's founder and CEO, Geoff Pearlman, has made it abundantly clear in developer conferences, videos and blog posts that there is no reason to rush your own transition, particularly for older projects. For the most part, API 2.0 and prior (API 1.0?) controls, methods and objects can be used and intermixed.
Geoff, as Founder and CEO of Xojo gives a great explanation of the reasons for the introduction of API 2.0 (mainly inconsistencies which had crept into Xojo over the years, inconsistency of naming properties, methods and events, and adjustments to naming of objects and classes which are similar but not identical on various platforms, such as Desktop, Mobile and Web, and modernizing the API). Watch his brief video on YouTube linked above. In less than 7 minutes he gives the rational and main points of the transition, from Xojo's perspective.
Many of the changes may seem quite minor, some of them I, and certainly many others, had already implemented as 'extensions' to the main classes we frequently used. At least in my case, my extensions didn't come close to the consistent and well thought-out naming API 2.0 brought, and certainly didn't span all the classes in the framework. Let me give two examples of API 2.0's improvements that contribute to better and more reliable code:
- Xojo now provides 'LastIndex', in addition to the traditional 'Count', as a property for many classes which contained lists of items. This is a much nicer, expressive and more consistent way of comparing index values or looping through the items, rather than using 'Count-1' countless times and hoping you never forget the '-1', nor use it when not appropriate.
- Xojo provides 'Add', 'AddAt', and similar methods to manipulate the list of items.
This paradigm is not perfectly replicated across all items and classes (not really even close in my view), for example, the DesktopComboBox, does not include 'Add', 'AddAt', 'LastIndex' etc. but rather uses 'AddRow', 'AddRowAt', and 'LastRowIndex'. The case, though, is easily made that 'Row' makes these methods & properties more expressive. Particularly given that it is obviously possible that a class might have multiple 'lists' of items within it. So using indicators like 'Row' to enhance the 'Add', 'AddAt', 'Count' and 'LastIndex' language makes sense. OK, so I'm on-board with DesktopComboBox (and the other similarly implemented controls)
Similarly, DesktopMenuItem, which has a list of child items in it's structure, includes 'AddMenu' and 'AddMenuAt'. For consistent implementation, you would then expect that you would have 'LastMenuIndex' and 'MenuCount', but alas, NO, those are actually 'LastRowIndex' and 'Count'. Strike One!
While I'm on the subject of counter examples, here is another one which sins in slightly different ways, consider the DesktopApplication class (new for 2021 Release 3). The list of windows the application has are found in the 'Windows' array. And there are the properties/methods 'WindowCount' and 'LastWindowIndex', so far, so good. But, look as much as you might, no 'WindowAt' method exists. Strike Two!
One last example, FolderItem. There are shared methods & properties for 'DriveAt', 'DriveCount' and 'LastDriveIndex'. But no Iterable, or directly accessible property for 'Drive' or 'Drives'. And, while we have 'Child', 'ChildAt' and 'Children', there is no 'ChildCount' (it is just 'Count') and 'LastChildIndex' is totally missing. Strike Three!, Four! ... is it Five?
So do I consider API 2.0 to be a swing and a miss? Is it Out? Game-over? No!
I admit that I may be nit-picking, but since API 2.0 is touted as greatly improving consistency, and yet, very commonly used classes have such notable inconsistencies still present, it is a splash of cold water on API 2.0 for me. It is easy for me to focus on the inconsistencies, but there is a much more consistent undertone in API 2.0 that should not be missed. Also, I am expectant and confident, that some, if not all, of these and similar inconsistencies will be addressed over time. It is quite easy for the Xojo team to add a new property/method, and deprecate old ones, while still maintaining compatibility for the previous usage, as they have consistently done this for many years. To fulfill the promise of API 2.0, I really hope that they will.
To wrap-up, API 2.0 is a welcome improvement (it really is) and I choose to view it, not as a completed transition, but as a statement of Xojo's intention and direction which will continue to drive and guide the API's evolution. It certainly gives me a better pattern and renewed initiative as I re-implement my class extensions for API 2.0. I will strive to follow the newly expressed naming conventions, and to fill-in the gaps (until Xojo does). To this end, I will be providing a continually updated module of 'class extensions', starting right now, totally free and open. Check the Xojo article table of contents for the download link and documentation as I re-build my Xojo development library for API 2.0.
Personally, I have also determined to restructure and update all my existing 'library' code when it is needed for use in any new project. I am using API 2 exclusively for new projects, and, whenever I'm working on older projects, with either bug-fixes or feature additions, I take good opportunities to update old code to API 2.
I strongly encourage you to consider a similar approach. Despite the lingering quirks, it is much better!