Xojo 2021 Release 3 introduces a new set of Desktop controls. Each of these controls replaces its original control counterpart and is prefixed with Desktop. For example, Window is now DesktopWindow and TextField is now DesktopTextField. The driving logic behind these new controls is both historical and technical, they allow us to make the event names match the Web and Mobile versions and give us the opportunity to make other changes to some methods that would have been problematic to make in the existing controls. Desktop controls are now a much closer match in terms of API to their Web and Mobile counterparts. The new Desktop controls use the same underlying implementation so, for example, Window and DesktopWindow, look the same and behave the same to the end user. These new controls make more of your code work without changes when you move from one project type to another. There’s no rush to begin using these new Desktop controls, your existing code will continue to function for many years. You can update one function, one class or the entire project at once. Transitioning to the new Desktop controls can be done at your leisure.
Existing Projects: When you open a project you created prior to 2021r3, you can continue to use the original Desktop controls. You can mix and match old and new controls on layouts. But, once a project has any new project items in it, it is incompatible with Xojo releases prior to 2021r3. For your existing, large projects, update the controls when you need to. And even then, you can update only the specific controls you want. Whether you update a project or not is a decision you can make on a project by project basis. But don’t be overwhelmed! You project will continue to run as-is, allowing you to take your time to update. Because the new Desktop controls currently share nearly all of the same implementation under the hood, bug fixes to them will likely also pass through to their original control counterparts.
When you are ready to update a project with a new Desktop control, launch your project in Xojo 2021r3 (or future releases) and chose what you want to update:
- To update the entire project, chose Project > Update Controls to API 2.0
- To update a single class (including the Application class), right-click on it and choose “Update to <New Class Name>”
- To update a Window and all of its controls, right-click on the Window in the Navigator and choose “Update to DesktopWindow”
- To update a ContainerControl and all of its controls, right-click on the ContainerControl in the Navigator and choose “Update to DesktopContainer”
- To update a specific control on a Window, right-click on the control and choose “Update to <New Class Name>”
- To update the menubar or a specific menu or menu item, right-click on the menubar or item and choose “Update to DesktopMenuItem”
New Projects: When you create new Desktop projects in 2021r3 or later, you will automatically use the new Desktop controls. The first place you will likely notice the new Desktop controls, or API 2.0 in general, is when using Auto-Complete. Projects created in versions of Xojo prior to 2019r2 will still show methods, properties and other items that have been deprecated along with their API 2.0 replacements. Projects created in 2019r2 or later will not. Should you need to use one of the original controls in a new project, just change the Super property to the original control’s class name. Please note, deprecated items do not show up in the documentation unless you search for them by name. To get to a deprecated item, type the complete name in the Search field and you’ll go directly to that deprecated item in the Language Reference. For example, typing “FolderItem.Item” will take you to the Item method even though it’s been deprecated. These deprecated items will remain accessible both in the framework and in the Language Reference for many years to give you plenty of time to transition.
This is Xojo’s final step in the transition to API 2.0. This provides an API that is as easy to use and consistent across classes and project types as we can make it. Transitions can be painful times but in the long run I believe these changes are to the benefit of Xojo. There’s no rush to update, your existing code will continue to function for many years. You can update one function, one class or the entire project at once. It’s up to you. Having a very consistent and intuitive API makes Xojo easier to learn and use which is good for us all.
Learn more about the new controls and Xojo API 2 in general in this video:
Helpful links: Xojo Blog: Why isn’t a button just a button?, Xojo Documentation: Xojo UserGuide: Moving to API 2 and UserGuide: API 2 Guidelines