Firstly, the MVPs work as your advocates, drawing attention to issues that they feel are important to the community. Their passion comes through in all interactions with the Xojo team, from justifiably reminding us of bugs we need to address or features that would be appreciated by many.

Since the MVPs all use Xojo in different ways, this helps to make sure we get a wide variety of feedback. Sometimes we get direct, specific suggestions such as the Set class, which (due to the provided code), we were able to add as a feature to Xojo relatively quickly. Some especially valuable MVP insights regarding stack checking helped us to pinpoint areas where we could make changes to the Xojo framework that resulted in dramatic performance improvements to Xojo itself along with all your projects. MVP tips and testing have also helped us nail down some issues that helped improve debugger stabilization. MVPs have even created a supplemental unit testing suite to help test the Android framework!

Speaking of testing, the MVPs certainly do more than their fair share of testing. They have helped with an enormous amount of testing for many parts of Xojo, most recently including PDF, Barcode, Charts and Android. When they find bugs, MVPs always create thorough, well-explained Issues, usually with sample projects, allowing us to fix things faster for everyone’s benefit. At times MVPs even review your own submitted Issues and may offer suggestions or advice for you to try.

In addition to testing and providing feedback on the product as you see it today, MVPs get to see stuff early, sometimes even before designs or implementations are finalized. This may be in the form of demos or test builds. Their tips, comments and suggestions can help provide direction to how we end up actually implementing a feature or change.

The Xojo documentation is also continuously improved by MVP feedback and suggestions. MVPs were first to see the new documentation site before it was unveiled to everyone and their keen eyes have helped us improve search, sample code and continue to polish things.

From inception to documentation, this group of dedicated Xojo experts has helped us shape Xojo. If you are pleased with what Xojo is today, you should thank a Xojo MVP.

To Anthony, Christian, Gavin, Jeremie, Kem, Martin and Wayne we at Xojo offer a heartfelt “Thank You!” and have made donations on your behalf to several open-source projects that also help make Xojo possible: LLVM Foundation, Bootstrap and Ubuntu.

User Comments about Conversion

After initial testing I quickly recognized the great performance gain Xojo Web 2.0 brings to our application. Transitioning to Web 2.0 was easier than we had expected. The backend code could be taken over almost completely without changes and the user interface was redesigned based on the new controls. The performance gain, especially with many concurrent sessions, is huge and allows a fluent user experience, with a very modern look and feel.

Andreas Reichmann of inoxision GmbH

Should You Convert Your Project

There are two reasons that it might not make sense to convert a project at this time. The first would be if this project is both quite large and a short-term solution. If you don’t see it being in use in 5 years, it might make more sense to continue to maintain it in 2019r3. The second reason would be if your project currently relies on some function of Web Framework 1.0 that does not exist in Web Framework 2.0. Primarily this would be mouse events for Label, Canvas, MapViewer and ImageViewer. If your app depends on mouse events for these controls, wait for a future release.

How Much Work Will It Be?

I personally converted the Eddie’s Electronic’s demo web app from Web Framework 1.0 to 2.0. The end result was a project with 9 layouts and just over 400 compiler errors. I was able to fix the errors, update the layouts (modernizing the main layout a bit in the process), and updated the non-web framework code to API 2.0 as well. The Eddie’s project file is 11.6MB and the entire process took about a day to complete.

Custom Controls

If you have any WebSDK-based custom controls on your layouts, you should remove them first as they will not convert. A new WebSDK is coming soon and the authors of those controls will need to update them to work with Web Framework 2.0.

Work with a Backup

First and foremost, make sure that you have a backup of your project before you start the conversion process. You will want to be able to maintain your existing Web Framework 1.0 projects while you go through this conversion process. It may be short, it may be long, depending on how big your project is and what it uses.

The Overall Process of Conversion

The best order in which to do a conversion is the following:

1. Convert Container Controls
2. Convert Web Framework Code
3. Convert Layouts
4. Convert API 1.0 code to API 2.0

Let’s look at each of these steps in order.

Don’t Panic

When you initially open your project in Xojo 2020r1 (or later), you’re likely to see this dialog box:

This is simply telling you that you’re using a control, event or property that no longer exists in Web Framework 2.0. Once you save your project, these incompatible items will be removed. Fear not, however, as you are working with a copy of your project so you can always refer back to your original Web Framework 1.0 project if the need arises.

Converting Container Controls

If your project utilizes Container controls, you’ll want to open it in Xojo 2020r1, immediately save it and then reopen it again. This will convert your Container controls properly allowing them to render correctly in the Layout Editor.

Converting Events

While many event names have changed, only a few have changed dramatically. Most have changed to make it more clear when they occur. For example, WebPage.Open is now Opening to reflect the fact that the page is actually in the process of opening and is not open yet. WebPage.Close on the other hand has been renamed Closed, because at the point at which the event fires, the page has already closed.

All of the code in events is automatically moved over to the new events when you open your project in 2020r1. However, you will likely have some code in events that cannot be auto-converted because a similar event does not exist. You will need to move this code manually. If there’s not an obvious new event, save this code somewhere until you get through the rest of the process and can decide where it should go. Then you can delete the unconvertible event.

In the case of Eddie’s Electronics, the project had 107 events, 7 of them could not be auto-converted.

Converting Web Framework Code

Once you have handled any events that can’t be auto-converted, the next step is to fix the compiler errors that are the result of changes in APIs between Web Framework 1.0 and 2.0. Web Framework 2.0 uses API 2.0 exclusively.

API 2.0 was designed to be extremely consistent. At first it may seem slightly foreign because you are accustomed to the original framework. Most find they get used to the new APIs fairly quickly and appreciate the consistency as it makes it far easier to find the API you’re looking for and thus faster for development.

Unfortunately, for the web framework it was not practical to keep both the old and the new APIs, so this means you’ll need to make some code changes before your web project will compile. The easiest thing to do is click the Run button and let the compiler figure out what it doesn’t understand. It will give you a list of errors most of which can be fixed by simply replacing an old API with a new one.

The most common change will be that the property that holds the primary value of a control is (in most cases) called Value. TextField1.Text for example, becomes TextField1.Value. These are fairly quick to change. The only code you must update is code that is associated with the web framework. While code not specific to the web framework might generate warnings that it should be updated to API 2.0, that’s not absolutely required to get your project converted and running. Depending on the size of your project, you may choose to do that conversion work at a later date.

Referring to the internal project I mentioned earlier, after dealing with 7 events that could not be auto-converted, clicking Run again results in just over 400 compiler errors. Now that may seem like a daunting task but it’s not as bad as it sounds. Almost half of those errors come from things that can be fixed with a simple search/replace. For example:

There are many others as well that can be converted via/search and replace.

Note on Search/Replace: When replacing class members, always start with a period and for methods end with an open parenthesis to reduce the chance you're going to replace something that matches but isn't a class member or is the wrong class member.

For example: .Cell(

Converting Layouts

Most controls in Web Framework 2.0 are taller than their 1.0 counterparts. This means you’ll need to resize them and then in many cases, reposition them. For the controls that have a standard height such as Label, TextField, Button, PopupMenu, Checkbox, SegmentedButton, it is recommended that you initially resize them to their new standard height of 38 first. You can do this all at once for a single layout. Just shift-click on several controls then change their Height property collectively to 38.

Now that you have all the controls at the proper height, you can begin repositioning them. However, before you do that, you may want to resize the layout itself to create additional room for the new, taller versions of your controls. Before you do that, look at ListBox, ImageViewer, TextArea and MapViewer controls to see if their locking properties are set in such as way that they will resize when you resize the page. If they are, turn those off for now so you can easily create more room.

Now you’re ready to make your layout taller to accommodate the taller controls. The most popular controls (Label, TextField, Button, Checkbox, Popupmenu and others) are 42% taller. To understand how much taller to make your layout, measure the height of the area with the controls that have become taller (a Rectangle works great as a measuring tool) and then add 42%. For example, in the internal project example we’ve been using, the area of the CustomerDetailsPage layout that includes the name and address fields is 158 pixels tall in the original version. 158 * 1.42 = 224 pixels. The difference is 66. Thus, making the entire layout 66 pixels taller created enough room for the various controls at their new heights.

If you follow these guidelines, you’ll find that that webpages, containers and web dialogs can be updated very quickly. The example took 5 minutes to update.

Here’s a video showing the process:

In Summary:

1. Turn off LockTop for any controls below the controls being resized and turn on LockBottom for those same controls so that when you make the layout bigger, those controls will move downward.
2. Measure the area these controls currently require, multiple that by 1.42 then subtract the original height. This will give you the number of pixels you should add to the height of the layout in the Inspector to make room for the taller controls.
3. Select all Labels, TextFields, Buttons, CheckBoxes, PopupMenus and SegmentedButtons. In the Inspector, set their height to 38.
4. Starting with the newly resized controls closest to the bottom of the layout, move them downward then work your way towards the top.
5. Turn back on any locking properties you turned off in step 1.

Note about Toolbars: While a new visual editor is in the works, it's not available for 2020r1. Toolbars are supported in the framework so you can create them in code. See WebToolbar in the language reference for an example.

Note about Separators: The separator control no longer exists. When your project is imported, separators are converted to Rectangles and made thin to do the same job.

Note about WebAnimator: This class no longer exists. However, See the WebStyle class for details on how to add animated transitions.

Note about WebStyles: Because Web Framework 2.0 relies heavily upon themes rather than styling individual controls, there is no visual web style editor. You can, however, use the WebStyle class to style individual controls. You can also create your own Bootstrap theme which will be applied across all controls on all layouts.

Testing the Initial Conversion

At this point you are ready to test your initial project conversion. Click Run and test all of your functionality. You may still need to make some additional changes to get these just right.

Bonus Step: Converting Remaining Code to API 2.0

Now that your app is converted, you may want to consider converting the remaining code to API 2.0 since that is the API we will be focusing our attention on going forward. It’s also the API that is shared with the desktop and will be shared with our mobile support soon.

Now, you are probably asking yourself, “What a minute, didn’t I just convert my code to API 2.0 when I fixed all of those compiler errors?” You did but that was just for the Web Framework itself. Your app likely also uses parts of the console framework which is the part that handle things like reading/writing files, network connectivity, database connectivity, and more. This code doesn’t have to be immediately converted to API 2.0 but you should plan to do it at some point.

When you decide to do so, choose Project > Analysis Warnings. When the dialog appears, make sure that the first two checkboxes are checked. Those are the ones that will inform you of deprecation warnings. Now choose Project > Analyze Project. The Warnings and Error panel will provide you with a list of places where you are using a class, method or property that has been replaced and will provide the replacement. At that point you just need to go error by error making the indicated changes. API 2.0 and API 1.0 share a lot of the same implementation under the hood so it may be a while before you really need to make this switch. You could also decide to do it slowly or just do it when you need to like when you encounter a bug in something from API 1.0 that is fixed in the API 2.0 version for example.

You will find that these conversions are easy to do and many can be handled with search and replace. I especially enjoyed converting database prepared statements as most went from four or five lines of code down to just one.

Conclusion

The bigger your project is, the more work it will be to convert. Fortunately, this is a one-time process for each project. The process suggested above will save you time during your project conversion.

You absolutely can. Xojo creates native apps that are also cross-platform. It can be done. It’s just a matter of choosing the right framework. At Xojo, we didn’t take the easy path of drawing controls ourselves or using HTML5. We didn’t dumb things down to the least common denominator. We did the hard work of creating a framework with an API that manages the nuances, intricacies, and subtle yet important differences between 7 different platforms (macOS, Windows, Linux, web, Raspberry Pi, iOS and soon, Android) and multiple OS versions so you can focus on what makes your application unique. We have been doing it for over 20 years.

When discussing Facebook’s blog post, John Gruber of Daringfireball.net said, “…native apps are smaller, faster, and more reliable.”

Nearly every user interface element in Xojo is native. The one exception is the desktop Listbox because way back when, none of the desktop operating systems provided one. Everyone made their own. Having said that, the Listbox is made up of native controls. The scrollbar is a native scrollbar. If the developer makes the contents editable by their end user, a native TextField control appears. The headers are native controls. The advantages of native controls can’t be overstated, Facebook was right about that. Modern operating systems provide an ever-increasing array of features via their native controls and thus using them gives you immediate and nearly free access to these features. From focus rings to spellchecking to accessibility and more much, using native controls makes the most sense.

Event aesthetics come into play. Because the Xojo framework uses native controls, when Apple and Microsoft make changes to the look and feel of their controls, apps made in Xojo automatically change in appearance and behavior. Most recently, Apple added Dark Mode to both macOS and iOS and for most Xojo developers, adding this support required nothing more than indicating they wanted their apps to support it by clicking a checkbox.

While Xojo provides the developer with an easy drag-and-drop way to create their application’s user interface, it also provides a straightforward API for interacting with controls via code. The TextField control, for example, provides events that tell you when the control has appeared for the first time, when the user has changed the selection or the text itself, and even when they press down on a key or release it. There are properties to change the size, style and behavior of controls. And all of this is a level of abstraction that lets you focus not on the details of the platform but on what makes your application unique.

For example, under the hood for the desktop, Xojo’s TextField uses NSTextField on macOS, EditControl on Windows and GTKEntry on Linux. On iOS it’s the UITextField, on Android it’s EditText and on the web it’s <input type=”text”>. Each of these is very different but Xojo has done the hard work to provide a standard, straight-forward API so that you get the benefit of native controls without needing to learn the thousands of APIs and unique behaviors necessary to create a cross-platform app.

It’s not just controls. The Xojo cross-platform framework includes dialog boxes, menus, access to the file system, printing, sockets, database access and much more.

Native is more than the user interface. It’s also about performance. Xojo compiles to native code for each platform as well. Behind the scenes it uses LLVM, the same optimizing compiler that Apple, Google, Intel, AMD, Nvidia and many others use. Native code means native speed.

Thousands upon thousands of Xojo users have built cross-platform apps. The Xojo IDE itself and much of the Xojo framework are written in Xojo. So yes, we eat our own dog food. Studiometry and Property Me are just two of the many examples of commercial cross-platform apps written in Xojo. There are countless others.

We have also done this in a way that makes it easy for students and hobbyists to learn programming so they can take it into their workplaces and build business applications. In some cases, those citizen developers create something revolutionary and become full-time professional developers. That’s why the Xojo user community is so diverse.

So yes, you can create native applications that are also cross-platform. You just have to choose the right tool.

Last year at XDC 2018, Jérémie Leroy talked about making sure your screenshots mimicked the Apple method so that the date was always Jun 9th, the time was always 9:41 AM, the battery always shows as full and the WiFi strength always shows full. It got me thinking that it might be handy to be able to make the simulator always show those values when you do a debug run so that you don’t need to think about it when you are ready to start taking screenshots and movies of your app. One way to do that is to build & run project like SimulatorStatusMagic on the simulator before running your project, but it would be more useful if it was automatic.

Build the Framework

First of all, go to the SimulatorStatusMagic Github page and clone or download the project. Just like Xojo iOS development, you’ll need Xcode for this step. After you’ve downloaded the project, double-click on the SimulatorStatusMagic.xcodeproj file to open it in Xcode. When the project opens, change the target to SimulatorStatusMagiciOS and build it by either pressing CMD-B or pressing the Play button. Once the build is complete, go to the project navigator, scroll down to the bottom and open the Products group to reveal the built parts of this project. The only item we’re concerned with here is the file named SimulatorStatusMagiciOS.framework. Right-click on it and select Show in Finder.

Build the Project

Let’s start off by making sure the framework will be available to your project at runtime.

1. Create a folder on your drive named SimulatorStatusMagic and copy the framework file that you just built into it.
2. Launch Xojo and create a new iOS project. Save the project into that folder as well.
3. To make sure the framework will be available to your project when debugging, go to the iOS target in the Xojo navigator, right-click and select Build Step > Copy Files. Make sure the step is between the Build step and the Sign step.
4. Drag the SimulatorStatusMagiciOS.framework file from the Finder into the Copy Files Step.
5. In the Xojo inspector, set Applies To to “Debug” and Destination to “App Parent Folder”.

Now let’s make it so you can access the framework! We’re going to add this code in the App.Open event so that the status bar gets set up before you do anything else.

Getting the framework to load is fairly straightforward:

#If DebugBuild
  Declare Function dlopen Lib "/usr/lib/libSystem.dylib" (name As CString, flags As Int32) As Ptr
  Call dlopen("@executable_path/SimulatorStatusMagiciOS.framework/SimulatorStatusMagiciOS", 1 Or 8)
#EndIf

That magic string “@executable_path” gets translated into “wherever the current application currently is” at runtime. Now this just loads the framework. We still need to hook up the methods and properties. Note: If you’re working with a framework that “activates itself” like the one that comes with Reveal (an excellent tool for tracking down iOS layout issues), this is as far as you would need to go.

To figure out what we need to do next, we need to look at the documentation and header files that come with SimulatorStatusMagic. Go back to Xcode and look at the navigator. What we’re looking for is a header file (with a .h extension) which has the definitions of each of the methods and properties which are available in this framework. The only file that meets this criteria (and the one that all the others seem to point to) is named SDStatusBarManager.h. There’s a bit of functionality available here, but the framework is set up to use the Apple recommended settings by default, so all we’re going to do here is call the enableOverrides method to activate it.

Go back to Xojo and update App.Open event:

#If DebugBuild
  Declare Function dlopen Lib "/usr/lib/libSystem.dylib" (name As CString, flags As Int32) As Ptr
  Call dlopen("@executable_path/SimulatorStatusMagiciOS.framework/SimulatorStatusMagiciOS", 1 Or 8)

  // Start by creating a pointer to the SDStatusBarManager class itself
  Declare Function NSClassFromString Lib "Foundation" (clsName As CFStringRef) As Ptr
  Dim smclass As Ptr = NSClassFromString("SDStatusBarManager")

  // Next, we need a pointer to the shared instance of the SDStatusBarManager class
  Declare Function sharedInstance Lib "Foundation" Selector "sharedInstance" (clsref As Ptr) As Ptr
  Dim smclassShared as Ptr = sharedInstance(smclass)

  // Last, turn on the overrides
  // NOTE: We're specifically NOT using the actual lib name here. 
  // This is just to satisfy the Xojo linker. The correct framework will be used at runtime.
  Declare Sub enableOverrides Lib "Foundation" Selector "enableOverrides" (obj As Ptr)
  enableOverrides(smclassShared)
#EndIf

Now if you run the project, when it opens the status bar automatically changes to the recommended defaults!

Please Note: These changes persist until the simulator device that you are running on is completely erased. If you need to disable it, you can do that with the disableOverrides method.

After posting this article, it was brought to my attention that I’d forgotten to show you how to sign the frameworks so you can build for the app store. To do that, you’ll need to add a script build step to your project, just after the Copy Files step you added above. The step can probably be set to Applies To: Release. The code should look like this:

// Replace the text in the signingIdentity property with your own
Dim signingIdentity As String = "iPhone Distribution: Your Company (XXXXXXXXXX)"
Dim code As Integer
Dim cmd As String
Dim result As String
Dim builtApp As String

builtApp = CurrentBuildLocation + "/" + ReplaceAll(CurrentBuildAppName, " ", "\ ")

// Get a list of all frameworks, one per line
cmd = "ls -d1 " + builtApp + "/*.framework"
result = Trim(DoShellCommand(cmd, 30, code))

// If there was no error (like none being there), sign each one
If code = 0 Then
  Dim frameworks() As String = split(result, chr(13))
  For i As Integer = 0 To UBound(frameworks)
    frameworks(i) = ReplaceAll(frameworks(i), " ", "\ ")
    cmd = "/usr/bin/codesign -fs """ + signingIdentity + """ " + frameworks(i)

    Result = DoShellCommand(cmd, 30, code)

    // If the sign fails, print the error and stop the build
    If code <> 0 Then
      print Result
      cancelBuild
    End If
  Next i
End If