Setup

Debugging on device requires your device be connected to your computer using a lightning cable.

Computer
You’ll need to launch Xcode, plug your phone in using USB and open Xcode’s Devices and Simulators window. In the navigation pane on the left, select the device and check the Show as run destination checkbox.

Device
If you’ll be debugging over USB, go to the Settings app on your device, select Personal Hotspot and turn that on.

Apple Developer Portal

For on-device debugging, your app profiles must be set up properly. For help on this, read The Crazy Exercise That Is The Apple Signing Process.

1. Certificates: You will need a Development certificate for yourself. Download it and double-click the file to install it.
2. Identifiers: You will need an Application Identifier that matches the Bundle Identifier in your app.
3. Devices: You must register all of the devices that you intend to debug on.
4. Profiles: You will need to create a Development profile for the app and make sure it contains your Development certificate (from step 1) as well as each of the devices that you want to debug on (step 3). Download the profile and double-click the file to install it.

Xojo

Debugging on-device requires that you set the Team from your account as well as setting the Build For property to App Store.

When you’re ready to run on a device, from the menu select Project > Run On and select your device from the list. If everything is configured properly, your app should be transferred to the device and automatically run for you.

Notes

The first time you debug an app, you will get a dialog on the device asking if your app can connect to the local network. You will need to allow that and then run your app from Xojo again.

Don’t allow your device to go to sleep while waiting for the app to build and transfer or the app won’t be able to launch. You can increase the amount of time on the device by going to Settings > Display & Brightness and selecting a new Auto-Lock timeout. The options are 2, 5, 10 or 15 Minutes or Never.

It’s All About Operational Security

Just so we’re all clear about why this process seems so complicated in the first place. What Apple is trying to do is to provide operational security, that is, separation of responsibilities so that on a big team, a single developer can’t just create and push out an app without anyone’s approval. While it adds a bit of complication for individual developers, it also means that as your product (and more importantly your team) grows, you’ll be able to deal with the changes gracefully.

Seemingly Disparate Pieces

There are six different parts that need to come together to successfully sign and deploy on iOS and macOS using the App Store (or Enterprise) which need to be configured properly for all this to work. If you’re just starting out, we suggest doing them in the order specified below to avoid having to go back and regenerate things later.

1. The Application Identifier – This is the identifier which Apple requires be unique for every application installed on an Apple device. Typically in the form: com.yourcompany.app-name You will have the best luck with this process if you decide what this is going to be up front because it affects nearly everything going forward. You will define any capabilities which require entitlements in this section. Enabling things in this section may mean that you need to check a corresponding capability in your Xojo project. Changing these capabilities will invalidate the Profiles below.
2. Testing Devices – This is a list of devices which are allowed to be used for testing. They are specified using the Apple Developer portal using the device UDID. For an iOS device, this can be found either in Finder or in iTunes when the device is connected. I suggest using a meaningful name for the device if you have a lot of them.
3. Certificates – Development and Distribution certificates are based on a public-private key-pair (like SSH) and are used for signing applications for testing and distribution respectively. See the Troubleshooting section below for more information.
   1. Development Certificate – Each person who is writing code for you on your projects and needs to be able to build for a testing device will need one of these which was created in your account. This means that if you have a contractor working for you, you’ll need to add them to your account, set their Role to Developer and specify the apps that this developer is allowed to work on. One certificate per developer, and these need to be renewed each year.
   2. Distribution Certificate – The person, group or machine that is responsible for building for the App Store (or Enterprise) has a separate key-pair certificate. One certificate per account, and they need to be renewed each year.
4. Profiles
   1. Development Profile – This file is used to link up the who, what and where of developing an iOS or macOS app. When creating a development profile, give it a name appropriate to the group you are creating. It’s important to understand that because these profiles rely on the testing devices and on the individual developers that changes to those groups will require regenerating this profile. If your developers and/or testing devices change often, I suggest creating individual profiles for each developer. If not, you’ll have better luck with just one profile that contains all of your developers and devices. These need to be regenerated at least once per year.
      1. The Application Identifier – Select the Application Identifier for the app to which this profile applies.
      2. Certificates – Select each of the developers that should be able to test this app on the selected devices.
      3. Devices – Select each of the devices that the developers should be able to use in their testing.
   2. Distribution Profile – This file links together the Application Identifier and the Distribution Certificate. Remember, there is typically one Distribution Certificate per account, so this allows you to grant or revoke the ability to distribute an app. These need to be regenerated at least once per year.

Dependencies

I’ve touched on this in places above, but I want this to be perfectly clear to anyone that is having trouble with certificates or profiles. The Development and Distribution profiles are highly dependent on the integrity of the Application Identifiers, Devices and Certificates. Any change to those items will mean that either or both of the profiles will need to be regenerated. Luckily (for the profiles anyway), it’s just a matter of editing the profile, adding or updating the data (if any) and clicking Save. Once that’s done, you can download the new profile, give it to anyone on your team that needs it (anyone whose certificates are contained therein) and just by double-clicking on the new file, it will be installed on your system by Xcode.

The table below shows the dependencies of the Development and Distribution profiles. Any changes to the indicated items (including expiration of a certificate) will render the profile Invalid and require that it be regenerated.

Troubleshooting

Overall

If you’re getting errors during the build process, there’s usually some information about whether it is a Profile or a Certificate that is causing the trouble. The first thing you should do is go to your Apple Developer portal and under Certificates, Identifiers & Profiles check to make sure that none of your Certificates have expired and that all of your Profiles for the current project are still Valid and have also not expired.

Certificates

If for any reason you do not have both parts of the certificate you are trying to use, whether it’s the user’s Development certificate when building for your test devices or the Distribution certificate when trying to build for the App Store (or Enterprise), you’re not going to be successful. Both the public and the private key must be present on your machine for them to work.

It’s important to remember that these certificates can only be downloaded from Apple’s Developer portal once, after which downloading will only give you the public key. If you need to transfer a development certificate from one account to another (like if you replace your computer mid-year), you should find the certificate in your keychain, right-click on it and select Export. When the save dialog appears, make sure the file format is set to Personal Information Exchange (.p12), and set a password for the key after you click Save. When you take the exported key to your new account/machine and double-click on it, the system will ask you for the password and you should be all set.

Enterprise Distribution

If you are a Xojo developer using an Enterprise developer account to distribute iOS applications within your own company without going through the App Store, we highly suggest checking out 2021r3 or later as some important changes have been made to make your builds more successful.

Starting in Xojo 2021r2, users with a Xojo Cloud server can deploy web apps which can hook into the Apple Push Notification service directly with a user friendly Xojo API.

Things You Will Need

1. An iOS App that is set up to accept remote notifications.
2. An Apple Push Notification Certificate. You can get this from your Apple Developer control panel at https://developer.apple.com/account, under Certificates, Identifiers & Profiles. When doing so, you’ll want to make note of your Apple account identifier (in the upper right corner of the window) and the certificate Key ID located in the Key details. Both of these are 10 character alphanumeric codes at this time.
3. A Xojo Cloud server. Depending on your needs, even a small server will likely do.

Sending a Basic Remote Notification

The first thing you’ll need to do is to add your APNs certificate to your Xojo Cloud server. This can be done by logging into the Xojo Cloud Control Panel and clicking the Options Tab. There you will find a link that says Manage APNs Certificates. Clicking that will take you to a dialog which allows you to add and remove APNs certificates for a machine.

Sending remote notifications is a relatively simple process, but there’s a little infrastructure you’ll need. Typically the process goes something like this:

In your iOS application which will be receiving the remote notifications, you’ll need to request permission to show notifications (if the notifications will be visible to the user) and then register for remote notifications. When you do this, you’ll be provided with a hex-encoded globally unique token that identifies this device for your app. This identifier should be sent to your notification server along with any information that you may need to determine what type of user this is. This identifier may change from time to time so you should request it whenever your app is launched and send the new one to your server whenever it changes.

In your Xojo Cloud app, sending one or more notifications is relatively easy. You’ll need to create two objects:

1. An instance of XojoCloud.RemoteNotifications.DeliveryOptions which is where you’ll put the Application Identifier of the iOS application to which you are sending, the Apple account identifier and the certificate Key ID. This class also defines when the messages you are sending will expire, their priority and their type.
2. For each message being sent, you’ll need an instance of XojoCloud.RemoteNotifications.Message which defines the content of the message.

Your code might look something like this:

// Set up Delivery Options
Var deliveryOpts As New XojoCloud.RemoteNotifications.DeliveryOptions(kAppID, kAPNSKeyID, kAppleTeamID)

// Set up a message
Var message As New XojoCloud.RemoteNotifications.Message
message.alertTitle = "Bethany's Bagels – Sale Today!"
message.alertBody = "Today Only – Buy one bagel, get one 50% off!"
message.badge = 1
message.soundName = "default"

// Assuming this RowSet contains all of the device tokens that you are sending to:
Var rs as RowSet = db.SelectSQL(kQueryToGetDeviceTokens)
While Not rs.AfterLastRow
  XojoCloud.RemoteNotifications.SendAppleNotification(message, deliveryOpts, rs.Column("token").StringValue)
  rs.MoveToNextRow
Wend
rs.close

Sending Notifications With APNs Feedback

The second signature for SendAppleNotification allows you to get feedback from Apple’s Push Notification service, including situations like when a device token is no longer valid which can happen if the user turns off notifications or deletes your app from their device. Because sending messages is asynchronous, you will need to define a callback method and include a pointer to that method when calling SendAppleNotification, like this:

// Signature for the callback method
Sub CallbackMethod(MessageID as String, error as RuntimeException)

When you pass the address of the callback method, SendAppleNotification will return a unique message identifier so that if the callback is called, you can identify which notification failed.

Var messageID as String
messageID = XojoCloud.RemoteNotifications.SendAppleNotification(message, deliveryOpts, rs.Column("token").StringValue, AddressOf CallbackMethod)

The possible response codes are defined here.

Advanced Usage

The Xojo Framework covers a large portion of the capabilities of the Apple Push Notification service, but Apple is adding new features all the time. In addition to the two methods described above, there are two methods which take a JSONItem instead of a XojoCloud.RemoteNotifications.Message object. Using this method you can define the message payload which uses features which have not yet been added to the Xojo framework.

Documentation of the JSON payload can be found in the Apple Developer documentation here.

Demo

Here’s a short video showing a remote notification being sent from a Xojo Cloud server in the datacenter in New York City to an iPhone at my house in North Carolina.

In addition, we’ve added a new Binary option which allows you to automatically create sets that aren’t mutually exclusive. That is, the values of the elements are automatically powers of two and can have binary operations applied to them:

This new feature comes with the requirement that they be placed inside a Module because they’re rendered into your project as a Class. The reason for this is that these classes automatically have some helper methods on them to make working with the binary data easier.

• An Operator_Convert which takes an Integer:
  Var x as MyEnum = 3 // MyEnum.George, MyEnum.John
  
• …as well as one that returns an integer:
  Var y as Integer = MyEnum.George // y = 2
  
• Automatic conversion to and from Integer:
  Var x as Integer = MyEnum.Ringo // x = 4
  
• Binary operations And, Or and Xor:
  Var x as MyEnum = MyEnum.Paul Or MyEnum.Mary // x has a value of 40
  
• Equality operations so you can compare the internal value of one instance to another:
  Var x as MyEnum = MyEnum.Paul
Var y as MyEnum = MyEnum.Ringo
If x = y Then
  
• Contains helper method:
  If x.Contains(MyEnum.Peter) Then
  
• A Read-Only Value property so you can see the internal value in the debugger

Just like regular Enumerations, the editor also allows you to explicitly specify the value of an element:

This is so instead of having to write:
Var x as MyEnum = MyEnum.George Or MyEnum.John Or MyEnum.Ringo Or MyEnum.Paul

You can simply write:
Var x as MyEnum = MyEnum.TheBeatles

We hope that you’ll enjoy this feature as much as we do!

1. Add a class to your project and name it TempFolderItem.
2. Add a Private property to the class named mFolderItem with a type of FolderItem.
3. Add a Method to the class named Constructor.
4. In the method, add the following code:
   mFolderItem = FolderItem.TemporaryFile()
5. Add a Method to the class named Destructor.
6. In the method, add the following code:
   mFolderItem.Delete
7. Add a new Method to the class named Operator_Convert with a return type of FolderItem.
8. In the method, add the following code:
   Return mFolderItem

That’s it! Now when you need a temporary file, create one of these objects like this:

Var myTempFile as New TempFolderItem

The Operator_Convert method makes it so you can use this object in any place where a FolderItem is expected and as soon as myTempFile goes out of scope, *POOF* the file disappears (assuming of course that no other process has locked the file).

memoryDB.Backup(fileDB, Nil, -1) 

Something that’s often overlooked is that you can use the Backup method to go the other way… that is, it can be used to load a disk-based database back into memory by simply swapping the parameters:

// Connect to the database file on disk
Var fileDB as New SQLiteDatabase
fileDB.DatabaseFile = SpecialFolder.Resources.Child("template.db")
fileDB.Connect

// Create the database in memory
Var memoryDB as New SQLiteDatabase
memoryDB.Connect

// "Backup" the file database into memory
fileDB.Backup(memoryDB, Nil, -1)

// Close the file database
fileDB.Close

And voila! You’ve restored the database back into memory!

For more information about this command, please see SQLiteDatabase.Backup on https://documentation.xojo.com.

1. Don’t ping or port scan the server. Our adaptive firewall is designed to look for behavior which looks like the type of traffic that comes just before an attack. Pings and Port Scans will get you blocked from your own server for a period of time. If your server isn’t accessible, head on over to https://downforeveryoneorjustme.com and type in your server’s IP address. That will help us understand if the problem is on your end or ours. Restarting or Deploying to your server will clear this up for you.
2. Stats only work after you have deployed. Displaying stats in the IDE can be processor intensive for your Xojo Cloud server, especially if there is more than one user requesting them. To prevent this, statistics are only available to users who have been specifically whitelisted on the firewall and the easiest way to do that is to deploy, even if it’s a simple empty app.
3. Databases require memory and processor cores. When adding a database to your Xojo Cloud server, it’s important to remember that they do require memory and CPU processor cores to run. For the best experience, we recommend that users upgrade to a Xojo Cloud server with at least 4 vCPUs.

Positioning

First of all, the primary function of Position Locking in the IDE is to prevent accidentally moving controls that you’ve already placed on a Window or Container. For users with very complex layouts and layers of overlapping controls, this feature is a must.

In previous versions of the IDE when you lock a control’s layout position, it stays in that position no matter what, and while that sounds like the desired result, it does have some not-so-desirable side effects, the least of which is that the control no longer obeys runtime control locking. If you follow these steps in 2019r1.1, you get a very strange result:

1. Create a new Desktop Project.
2. In Window1, drag a Canvas control to the lower-right corner of the window.
3. Set the control locking in the inspector so that only the right and bottom sides are locked.
4. Right-click the control and select “Lock Position”
5. Resize the Window by dragging the lower-right handle

In 2019r1.1 and below, the Canvas acts like it’s locked on the top-left corner and stays at the same x and y position as when you locked it. If you do these same steps in 2019r2, the control now follows it’s runtime locking rules and stays with the lower-right corner of the Window. 

Alignment

The second issue we had was that Position Locking did not affect the alignment tools. Previously, if you selected one or more controls whose positions were locked, the alignment toolbar buttons were always enabled, but clicking them didn’t affect all locked controls. Instead, the IDE would figure out the outer bounds of all selected controls and move the unlocked controls to align with this boundary. This leads to unexpected results if one or more locked controls are selected because they don’t move. 

Starting in 2019r2, the rules for alignment have changed somewhat.

• The alignment controls are now only enabled if you have at most one locked control selected. 
• If no locked controls are selected, the IDE will align controls using the outer boundary of all selected controls as a guide, just like it did before.
• If a locked control is selected, the controls will be aligned to that control.

Improved Overall Speed
One of the most obvious areas that hurt people with large projects is the speed of the IDE itself. We worked on a number of pain points to improve the overall IDE experience. Specifically, we were looking for things which by themselves were not too bad, but in a cumulative effect they could take large chunks out of your day.

One such area was in saving text projects. Now you wouldn’t think that there was much room for improvement here, since it’s just File I/O right? We found an optimization point in the way we save Bookmarks and Breakpoints, which in the IDE project represents a huge savings when making lots of changes. In our case, we went from 30 seconds down to 1, and for someone who insists on saving before every run, it makes a huge difference.

We also optimized drawing in the Navigator, and that change resulted in huge overall speed increases in many parts of the IDE, from selecting large number of items in the Navigator itself, making changes to multiple items, to even just typing code in the code editor.

Improved Tab Management
Tabs have been broken in one way or another for a long time. They finally got some TLC this cycle and we think you’re going to be much happier with the way they work now. We’ve rewritten the logic surrounding how tabs are chosen when you take an action which results in a new location request and made the behavior consistent, no matter where that request comes from. Whether that’s a Go To Location request or a search or clicking on an error result. The rules are applied in the following order:

1. If there is at least one locked tab which matches the Go To target, the first one will be used (left to right).
2. If there is at least one unlocked tab which matches the Go To target, the first one will be replaced.
3. If the current tab is unlocked, it will be replaced with the new location.
4. If there are any unlocked tabs, the first one will be replaced.
5. If none of the above conditions are met, a new tab will be created for the target location.

NOTE: Debugger Tabs are never eligible as a Go To target. This may seem obvious, but it wasn’t always true before. Now it is. Debugger tabs are also locked by default and cannot be unlocked.

The only exceptions to these rules are the Open In New Tab rules. That is, if you right-click on an item and select Open In New Tab or you double-click on an item with the “Double-click opens item in new tab” preference set, they will always open a new tab for you.

Once you start using the new logic, I think you’ll agree that it’s much more intuitive and you won’t feel like the IDE is constantly switching contexts on you. Personally I find that I’m using fewer tabs than in previous versions because I’m more confident that the objects I opened will still be there when I get back.

MacOS Dark Mode Layout Editor Toggling
On macOS 10.14 and above we’ve added a new toolbar button which allows you to quickly switch the Window you are editing between light and dark mode. No more switching your entire OS just to see how your app will look in the other mode.

Navigator Contextual Menu
We’ve done some cleanup work here to make it more obvious what you can and can’t do with objects in the Navigator. Gone are all of the disabled items that were not “in-context” for the currently selected item because, well duh, they’re not “in-context”. We’ve also enhanced the Edit Superclass and Edit Subclass menus. Edit Superclass now shows the entire superclass hierarchy, including things that you can’t edit (disabled of course) so you can track down common parentage. The Edit Subclass menu has been alphabetized so you don’t have to read the entire list just to find all of the items that begin with “c”.

Code Editor Contextual Menu
This menu has also gotten some love and attention. First of all, the menu has been reorganized so that the menu groups are based on the context of the thing that you’ve clicked on and the object where the code itself lives.

Group 1: Just like previous versions of the IDE, Cut, Copy, Paste, Delete and Select All are still at the top of the menu. They’re a common thing for mouse oriented users and we don’t want to hurt that functionality.

Group 2: The next group is for things that are for accessing or modifying the object that you’re currently editing. This is where you’ll find the Switch To menu for directly accessing the other code items within the current item.

We’ve also added two new submenus to this section that are specifically for copying the event and delegate signatures of the thing you’ve clicked on. For example if your code refers to a URLConnection object, you can now right-click on URLConnection and select Add Method > From Event > ContentReceived and the IDE will automatically add a method to the current object with the same signature including the object itself for use with AddHandler! In this case, you’d end up with a method that looks like this:

URLConnection_ContentReceived(obj As URLConnection, URL As String, HTTPStatus As Integer, content As String)

Then you could type something like:

AddHandler h.ContentReceived, AddressOf URLConnection_ContentReceived

Delegates work the same way, albeit without including the object reference in the method signature. No more flipping back and forth between your current code and the target object or Language Reference to copy the signatures!

Group 3: If it exists, this group is for things that are specific to the object or instance of the object that you clicked on in the code editor. This is where you’ll see the “Find” and “Go To” menu items for finding other uses of or going to the definition of an item, respectively.

Group 4: This group is for selection and code-specific tools including the Insert Color command, Standardize Format and the Wrap In menus for wrapping the current selection if an #If #EndIf or While/Wend block. This section also sports the menu for converting the current selection to a Constant or a Method.

Group 5: From here you can toggle Breakpoints and Bookmarks

Group 6: Help and Language Reference access.

For more information about the changes in 2019r2, read the full Release Notes.

Uniform Type Identifiers (UTIs) are one of the many often misunderstood parts of building native macOS apps. While they’re not just for specifying file types, that’s what I’m going to focus on today. First, a little background:

Uniform Type Identifiers are the successor to Apple’s Creator and Type codes that were used in MacOS Classic 15+ years ago. Back then, every mac application had a creator code (Four characters) which had to be unique and therefore registered with Apple for use in an app. Then, each file type that you wanted to create also needed a unique code. Common types were TEXT for text files, APPL for applications and RTFd for RTF documents. This was their attempt to keep from having file extensions and while it “worked” there were some severe limitations.

When MacOS X appeared on the scene, file extensions became a necessity again what with their BSD Unix underpinnings and when 10.6 was released, Apple revisited their position on exposing users to extensions again. (Don’t get me wrong, macOS does an excellent job of hiding extensions from users that don’t need to see them and exposing them to users who do. As an old-school user, I’m grateful for that.) This meant that they had an opportunity to update their antiquated system for application and file type association. 

At first glance, wrapping your head around UTIs may seem a little daunting, but let’s break it down for you:

1. First, your application needs a valid Bundle Identifier. This setting is found in the macOS build target settings and its value is in reverse domain name format. While it’s not required, I suggest you use your personal or company domain name to form this identifier. If your domain was example.com, the bundle identifier would look like com.example.myappname.
2. Next, you’ll need to add a special kind of File Type to your app. Add a “File Type Set” to your project and add a new type by clicking the + button at the top of the editor.
   1. Give your type a name like “FolderWithIcon”.
   2. Assign a UTI Identifier. This must start with the same reverse name that you used for your bundle identifier when making file types for something that your app creates. For example: com.example.myfolder. This value must be unique within your app.
   3. Add “public.folder” to the Conforms To field. This value represents the other type(s) of files that your type is associated with. For more information see Apple’s list of public identifiers.
   4. Set the Extensions field to “.myfolder”. This value must be unique within your app.
   5. Set UTI Type to Exported
   6. Add a unique folder icon to your file type.
3. In places where you want to have these custom folders all you have to do now is add the extension and then hide the extension from the user:

   Dim f As FolderItem = SpecialFolder.Desktop.Child("Test.myfolder")
   f.CreateAsFolder
   f.ExtensionVisible = False

4. Build your app (running won’t always work). Note: macOS reads these specs right from the latest version of your app and caches them, so if you need to update your icon you’ll need to at least increase your app’s non-release version number.

That’s all there is to it! From now on, when you create a folder in your app, it’ll get your snazzy new icon!

There’s an advanced feature in Xojo called Compiler Directives which allows you to direct the compiler to conditionally compile a block of code based on a boolean comparison. For instance, if you wanted to temporarily disable a block of code (as opposed to commenting it out) you could wrap your code like this:

#If False
  // Code that you don't want to compile
#EndIf

You can also use constants with the #if directive, so if you created a module called “Switches” and it contained a Public or Protected constant named “EnableDeepLearning” with a value of True or False you could write code like this:

#If Switches.EnableDeepLearning
  // Code for your deep learning feature goes here
  // This code will only be included in your app if EnableNewFeature is set to True
#EndIf

There are also some built-in constants for you to use. For instance, there are two constants that tell you which version of the IDE is running, one is a Double, the other is a String. Here’s an example which allows you to use the new Dark Mode capability depending on whether you’re running 2018r3 or something earlier:

#If XojoVersion < 2018.03
  Var myTextColor As Color = &c000000
#Else
  Var myTextColor As Color = &c1C1C1C
  If IsDarkMode Then
    myTextColor = &cFEFEFE
  End If
#EndIf

There are also build-in constants per platform and processor type:

#If TargetMacOS
  // macOS Specific Code
#ElseIf TargetWindows
  // Windows Specific Code
#ElseIf TargetLinux
  // Linux Specific Code
#ElseIf TargetIOS
  // iOS Specific Code
#EndIf

#If Target32Bit
  // Code for 32-Bit Processors
#ElseIf Target64Bit
  // Code for 64-Bit Processors
#ElseIf TargetARM
  // Code for ARM Processors
#EndIf

For more information on Compiler Directives, see https://documentation.xojo.com/＃If…＃Endif

In addition to code for specific platforms, sometimes you need to know the specific version of the OS that the user is running. In 2019r3 we added the System.Version method specifically for this purpose:

#If TargetMacOS
  If System.Version = "10.15" Then
    // Code that works exclusively on 10.15
  ElseIf System.Version >= "10.15.1"
    // Code that only works on 10.15.1 and above
  End If
#EndIf

If you’re working with Windows, keep in mind that System.Version returns NT System Versions, so you’ll need to compare to these values instead:

• Windows 10 = NT 10
• Windows 8.1 = NT 6.3
• Windows 8 = NT 6.2
• Windows 7 = NT 6.1
• Windows Vista = NT 6.0

For more information about System.Version, See http://documentation.xojo.com/api/os/system.html#system-version.

The command is:

xcrun altool -u [username] -p [password] -f [path to bundle] -t ios

In a Xojo build script you can even show a prompt asking if you want to submit it. Just make a post-build script and paste in this code.

dim btn As String = ShowDialog("Do you want to upload this build to Apple?", "", "Yes", "No", "")
if btn = "No" Then
  Return
end if

// Find the path to the .ipa file that was just built
Dim result as String = DoShellCommand("cd " + CurrentBuildLocation + " && ls -1 *.ipa")
Dim IPAPath As String = CurrentBuildLocation + "/" + ReplaceAll(trim(result), " ", "\ ")

// Make the command
Dim username as string = "Your iTunesConnect Username"
dim password as string = "Your iTunesConnect Password"
Dim cmd As String = "xcrun altool -u -p -f -t ios"
cmd = Replace(cmd, "", IPAPath)
cmd = Replace(cmd, "", username)
cmd = Replace(cmd, "", password)

// Validate the package (with a 2 minute timeout)
// If an error occurs, show the error and abort
Dim errorcode As Integer
result = DoShellCommand(cmd + " -v", 120, errorcode)
If errorcode <> 0 Then
  print result
  Return
End If

// Upload the package (with a 15 minute timeout)
// If an error occurs, show the error and abort
result = DoShellCommand(cmd + " --upload-app", 900, errorcode)
If errorcode <> 0 Then
  print result
  Return
End If

Print "Upload Complete."

For more information about this powerful command-line tool, open a Terminal and type:

xcrun altool -h

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

Variable Height iOSTable Rows

When laying out lists of data in iOS, often there’s more than one way to get to where you need to be. The Bedtime, Stopwatch or Timer modes in the iOS Clock app are a great example of this. Instead of using a scrollable view, they use an TableView with variable height rows and starting in 2018r2 we’ve made this really simple to do too.

To make variable height rows, you’ll need to use a datasource with your iOSTable and create a subclass of iOSCustomTableCell just like you did previously and set the UseDynamicHeight property to True in the inspector. Then just make sure that you have a continuous string of constraints from the top of the cell to the bottom to tell the layout system how tall the cell needs to be. So if you have a layout that looks like this:

You would need to make sure that you have constraints like this:

1. A constraint from the top of the cell to the top of the Username Label
2. A constraint defining the height of the Username Label
3. A constraint from the bottom of the Username Label to the Top of the Username TextField
4. A constraint defining the height of the Username TextField
5. A constraint from the bottom of the Username TextField to the bottom of the cell.

Making this change also gets us a little bit of built-in magic such that any Label controls without a height constraint will automatically resize themselves to match the height of the text they contain, making your cells adapt better to localization or variable text. This also makes it possible to put a DatePicker in a cell and use it as the editor for the previous row by inserting it on-the-fly.

For an example of how to do this, see the CustomCellDynamicHeight project in the Example Projects/iOS/Controls/Table/ folder.

Pull-To-Refresh

Another feature that we got several requests for was the ability to use the iOS TableView’s built-in pull-to-refresh capability. An example of this can be seen in the Mail application when you are looking at the Mailbox list. Just drag downward until you see a progress wheel. That’s pull-to-refresh.

In Xojo it’s as simple as setting the new AllowRefresh property to True, implementing the Refreshed event and then call EndRefresh when you’ve received and updated the table to make the progress wheel disappear.

For an example of how to do this, see the TableDataSourceDatabase project in the Example Projects/iOS/Controls/Table/TableDataSourceDatabase folder.

Row Add/Remove Animations

Ever notice that when you add or remove a row on an iOSTable at runtime that they just kind of *POP* into existence? We’ve made it so that adding or removing a visible row is now animated, just like other apps on the device. This looks especially good when inserting a DatePicker control to edit a date!

For an example of how to do this, see the TableEditing project in the Example Projects/iOS/Controls/Table folder.

*Want to talk to Xojo engineers about what you want to see? Come to XDC 2019 in Miami, Florida!

With Apple’s announcements at WWDC 2018 and the introduction of dark mode it was time to revisit our graphics and the overall appearance of the IDE again. Here are some things which contribute to the changes that have been made and ones that you will see in the coming months.

Dropping macOS 10.9

Xojo 2018r3 drops support for macOS 10.9 and as the last version which had the skeuomorphic design elements all of our supported OS’s now have the flatter modern design. It’s not that this has held anything up per se, but it’s a good reminder that “it’s time”. 

To that end, we have taken that opportunity to remove some of the graphics that make the IDE look out of place and doing so subtly lowers the memory footprint and accelerates drawing of the IDE itself across all platforms. We’re also using a variation of Apple’s image templates which has somewhat reduced the on-disk footprint of the IDE itself.

macOS Dark Mode

Apple’s addition of a darker variant of the visual “Aqua” theme in macOS means that we needed to do an audit and update of several of our base framework controls so that your apps would render correctly as well as ours. 

Events

While it probably won’t be used very often (how often does one change themes while running a piece of software, besides the novelty of seeing it happen), we added an event to the App class named AppearanceChanged to notify you when the user changes from light to dark or changes their accent color. This is a good place to clear any graphic or color caches which contain theme specific UI graphics. 

Methods

There is also a new global method called IsDarkMode(Boolean) which will return True if your app is running with the Dark Mode theme on macOS 10.14 or higher. If your app is running on 10.13 or lower or in light mode on 10.14, IsDarkMode will return False.

Build Settings

Enabling Dark Mode in your apps is as easy as flipping a switch in the Shared Build Settings. Unfortunately, because Apple made the assumption that most apps would “just work” versions of your apps compiled with older versions of Xojo will either need to be recompiled with Xojo 2018r3 or you’ll need to push out a new version with a plist entry to prevent macOS 10.14 from showing your app dark in Dark Mode. 

Testing

When testing apps for use with Mojave’s dark mode, I seriously suggest that you test on a system that allows you to see the translucency effects of dark mode. Virtual Machines are usually really handy for testing, but in this case, Parallels Desktop 14, VirtualBox 5.2 and VMWare Fusion 11 do not show the subtleties of dark mode.

Colors

One of our goals at Xojo is to remove some of the headaches involved with the minutiae of each OS that you deploy for and to that end, we wanted to make drawing custom controls easier too. What this means is that the built-in global colors are largely theme aware now and will change depending on whether your app is running in light or dark mode on macOS. This affects things like TextColor, FillColor, FrameColor, HighlightColor, etc, so if you use those methods when drawing in pictures and canvases, you will want to audit that code. If you want a specific color, you should use a color constant. For instance, use &c000000 if you want black because TextColor will now return white in Dark Mode. 

In terms of the framework controls themselves, we are taking this opportunity to make some changes to make your apps appear better in the macOS 10.10+ ecosystem. Ever notice that a Label control and the text portion of a CheckBox or RadioButton control are not exactly the same color? Going forward, the default colors of controls which should automatically change between Light and Dark modes will do that. So if you have a Label using the default color of &c00000000 (Black with Transparency = 0), the color that is actually used is what Apple calls labelColor. It’s still black, but is a tiny bit translucent. TextFields and TextAreas will automatically change text, placeholder, selection and background colors to match the Apple prescribed colors for automatic Light/Dark compatibly. We think you’ll find that building your apps with 2018r3 will largely make them just behave and appear the way you expected them to.

IMPORTANT NOTE: These color and framework changes affect how your apps draw on all versions of macOS, so make sure you try them out on your 10.10 through 10.14 VMs before shipping!

Eating our own dog food

One thing we hear from users every so often is the desire for Xojo to use our own products for building apps. As most of you know the IDE itself is written in Xojo, but we also have several other apps (big and small) that are written in Xojo.

• Feedback – Our bug reporting system
• Xorders – Our internal order system
• Lingua – The Xojo localization app
• Remote Debugger – The remote debugger stubs for desktop and console

While the 2018r3 cycle was in progress, all four of these projects got updated for Mojave’s Dark Mode and definitely helped us find framework rendering bugs early on in the pre-release process.

What about Windows and Linux?

The TL;DR version is that we’re still looking into it. 

Currently there are several different ways to change Windows 7, 8 and 10 to use a dark interface, not all of which are compatible with the Xojo Framework controls and the Windows 10 2018 Fall Update promised yet another way but that ended up only being for UWP. We are looking into which method gets you the most “bang for the buck” so to speak. 

Because of the latency involved, external items shared in a shared folder on a server or a file sharing service are never truly in-sync with one another. While this technique works with a single developer across two or three projects, it gets more and more complicated as you add more projects and even more-so if you try to add more developers.

One of the largest issues with this type of system is that everything must be kept in sync all the time. Making one little change to a shared file or method which works fine in the current project could completely break a project that you haven’t worked on in a year. When you do get around to working on it again, there’s three possibilities:

1. The project compiles and everything works just like it did before.
2. The project doesn’t compile.
3. The project compiles and doesn’t work like it did before.

With careful planning, you’ll probably hit #1 75% of the time, but the other two are wrought with problems. If the project compiles but doesn’t work correctly, you may not find out until you’ve given it to your users, with the worst case being unrecoverable data corruption. If it doesn’t compile, then what? The shared code is now required to be different in two different projects and you may have no history as to what was changed.

Thankfully the folks at who are maintaining Subversion at the Apache Software Foundation made it super easy to create shared code repositories using a feature called Externals. (For those of you that are using Git, I suggest looking into Submodules. Of the two techniques I’ve encountered, Submodules seem to require the least individual overhead.)

SVN Externals

SVN Externals are exposed as a property (svn:externals) on the containing folder and is set up using the svn propset or svn propedit commands, but most SVN visual clients have an interface for creating an SVN External to make the process easier. Once it’s set on a versioned directory, everyone who checks out or updates the working copy also gets the external definition.

It’s worth keeping in mind that because an SVN External definition points to a specific place within another repository, that this other location is also versioned. That is, you can (and probably should) point an external definition at a particular revision within that repository unless there’s a very good reason to always be pointing at the latest/greatest version. This helps alleviate the problems with shared library changes. Once you have it working for a particular version, you can lock-in to a particular date/time until you’re ready to check with a newer version.

Externals in Xojo

Setting up externals for use with a Xojo Text Project is fairly simple to do. As an example, let’s say you have two projects … ProjectX and ProjectY. ProjectX contains some items that you’d like to share with ProjectY.

1. Within Xojo, Open ProjectX and make a folder named “Shared_Items” and move any items you wish to share into this folder.
2. Save ProjectX and close it.
3. Quit the IDE.
4. Depending on whether you’re using a visual SVN client or the SVN command line the steps are similar:
   1. Go to the directory above where the “Shared_Items” folder is located in ProjectY
   2. Remove the empty “Shared_Items” folder.
   3. Add an SVN external with the name “Shared_Items” which points to the Shared_Items in the other repository (or branch or wherever it is).
      1. If you’re doing this using the command line, the command is:
         svn propset svn:externals "Shared_Items https://path/to/other/Shared_Items" .
         If you want to lock the project to a particular revision, you’ll need to tell SVN which revision to use:
         svn propset svn:externals "Shared_Items -r12345 https://path/to/other/Shared_Items" .
         Each of these commands are basically saying: Create a new external named “Shared_Items” using the https://path/to/other/Shared_Items source in the local directory (.), with the second one specifying that you want to use revision 12345.
      2. If you’re using a GUI client you usually select the parent folder and then add an external definition from there. There are usually fields for specifying the Local Path (Shared_Items), URL (https://path/to/other/Shared_Items) and Revision (either HEAD or a specific revision number)
   4. Now you need to update the contents of the folder.
      svn update Shared_Items
5. Open ProjectY.
6. Drag the “Shared_Items” folder from the project folder directly into your project. DO NOT SAVE YET. Any modules which contained other items will be represented by a Module in the project and an identically named Folder which contains the items that should be put inside the module.
7. Referring back to Project X, drag each of the items in Shared_Items to its corresponding location in ProjectY. It’s very important that the on-disk representation in both projects be identical, so make sure you’re using the same version of Xojo in both projects. For example, if after dragging in the Shared_Items folder, you might have:

   Shared_Items
     Module1 (Module)
     Module1 (Folder)
       Class1
       Module2 (Module)
       Module2 (Folder)
         Class2

8. If you have multiple levels of nested modules, I suggest working from the bottom up, that is from the lowest directories up to the highest ones to avoid confusion. Once you’ve emptied a folder, delete it. Using the example above:
   1. Drag Class2 from the Module2 folder directly into the Module2 module.
   2. Delete the Module2 folder.
   3. Drag Class1 from the Module1 folder directly into the Module1 module.
   4. Drag Module2 module into the Module1 module.
   5. Delete the Module1 folder.
9. Once the structure looks the same between the two projects, Save ProjectY. You’ll notice that on disk the folders are still there. That’s exactly what you should see. Check your SVN client, there should be no changes to be checked in. If there are, make sure they’re not file additions and/or deletions.

From now on (if you’re using a non-revision specific external), whenever you make a change to one of the items in this Shared_Items folder and check them in, they’ll be available to any other projects that use them, whether it’s the original items or any project where this folder is defined as an external.

While this looks really complicated to set up, once it’s done using the external will work and feel just like any other folder in your project.

A few things to remember:

1. Make sure you’ve named the shared items container so that it’s obvious that the items are shared between projects, so things don’t get inadvertently dragged into the folder if they’re not needed anywhere else and not dragged out of the folder if they are.
2. Make sure everyone on your team understands that this code is shared among projects.
3. Write Unit Tests for your shared items so when making changes you can verify that you’re not breaking other projects or inadvertently changing their behavior.

Challenges

The foremost issue that we had to fix was that the original protocol was designed so that it required you to close the IPCSocket to get your command to run. That meant there was no longer a connection on which the IDE could send any kind of response. It also meant that dealing with issues required making multiple connections.

The second was that there were many things that raised dialogs when something went wrong, which meant that an unattended IDE could get “stuck” waiting for user input which would never come. We’d heard that developers would have their systems take a screenshot if an hour had passed with no activity so they could figure out what had gone wrong, but that can be a huge waste of time if you’re waiting on a build.

Solutions

The new protocol (which was beta in 2016r4 and officially released in 2017r1) addresses both of these problems. The new protocol uses JSON for the command format and the IDE can send back all kinds of information including (but not limited to):

* Script syntax errors
* Script runtime errors
* IDE version conflicts
* Missing assets
* Compile errors

All of these things are returned to your calling script so you can take appropriate action. Because this is truly a two-way protocol now, you can also send data back to your script, like if you wanted to return the path of the built app back to your build system.

We’ve also been working to make anything that would normally show a dialog to the user gets sent back to the app communicating with the Xojo IDE. As far was we know, all but one was caught, and a fix for it has been submitted for 2017r2.

If you’d like to see the new IDECommunicator protocol in action, look in the Examples folder next to the IDE: Examples > Advanced > IDE Scripting > IDECommunicator > v2 > IDECommunicator-Tester.xojo_binary_project

For documentation and more information refer to the doc page here: IDE Communicator

Just a note for those of you who have already been using the IDECommunicator project (or something similar) for controlling your builds, when updating to the new protocol make sure you don’t include a QuitIDE command in the script you initially send to the IDE. Doing so will cause the IDE to quit before you get a response which would present as a false positive. I suggest waiting until you do get a response and then issue a separate QuitIDE command at the end.

QuickStart

The simplest way to see this in action is to see it in a label.

1. Create a new Web project.
2. Add a WebLabel instance to WebPage1
3. Set its text to “This is a <raw><strong><em>test</em></strong></raw>.”
4. Run the project.
5. The label’s text should be “This is a test.”

Using <raw> tags

So you’re probably wondering where you can use these <raw> tags. The answer is just about anywhere…

• App.DisconnectMessage – You can now add a link to the message to help users get back to your app if they get disconnected.
• App.LaunchMessage – Add some text styling to the text that appears below the app icon.
• WebLabels
• WebCheckboxes
• WebLinks
• WebListboxes*
• WebRadioButtons

* You may have noticed that we added pictures to WebListbox in 2016r4… now you can add any html tags to a listbox cell if you want to!

Go have fun with this new feature. We’re looking forward to seeing how you use it!

After a bit of experimentation this January we were able to isolate one huge cause of this annoying behavior. Unfortunately it has to do with a misconfigured IPv6 DNS server configuration and whether or not yours is correct may be up to your service provider.

Whose bug is this?

According to the spec, IPv6 DNS servers are supposed to return immediately if they can’t fulfill the request. Unfortunately this is almost the exact opposite of what an IPv4 DNS server does, in that it may forward your request to the next server to see if it knows where your request should go. Unfortunately we found that only about two-thirds of the ones we tested were correctly configured.

On macOS and Linux, DNS requests are sent concurrently, that is, two requests are sent at the same time, one each for IPv4 and IPv6. The one that returns first is used. On Windows, the requests are unfortunately sent sequentially, IPv6 and then IPv4. What this means is that IPv6 requests just hang there, waiting for a response that will either never come or will wait until the underlying socket reaches its timeout. When that fails, the IPv4 request is sent and fulfilled and your socket request goes through.

What To Do

Here are a few things you can do to test this theory. While you can’t really ask all of your users to do this, it will tell you if this is where the problem lies.

1. Turn off IPv6.
   1. Click Start and then Settings.
   2. Search for Network Connections.
   3. Click View network connections.
   4. Right-click on the active connection and select Properties.
   5. On the Networking tab, clear the Internet Protocol Version 6 (TCP/IPv6) check box, and then click OK.
2. Change the DNS entries for IPv6 from the defaults to point to Google Public DNS or OpenDNS.
3. Make a Hosts file entry. If your installer runs as an administrator, you can make an entry in the hosts file to force the computer to use IPv4. This is not a long term solution as the world moves to IPv6.The hosts file on Windows 7/8/10 is located at:

   C:\Windows\System32\drivers\etc

   and you should add an entry which looks like this:

   Server IP Address<TAB>domain name

4. If it’s a domain that you control, make sure you only use IPv4 DNS entries and that your server is only listening on the IPv4 interface.

All in all, it’s a frustrating problem. While there’s no easy solution, the good news is that because there are no IPv4 addresses left to be distributed, the world is moving to IPv6. The more demand there is, the more likely that the incorrect DNS servers will get fixed because they’ll cause problems for other sites as well.

CREATE TABLE "Servers" ("id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "name" TEXT, "ip" TEXT)

If you wanted to use that in a string, you need to double up each of those quotes to make them work:

dim sql as string = "CREATE TABLE ""PendingControllers"" (""id"" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, ""name"" TEXT, ""ip"" TEXT)"

One line isn’t bad, but if you have a bunch to do, it can become quite tedious.

IDE Scripts to the rescue! With a simple script (less than 10 lines) you can have the IDE do this for you automatically.

1. In the Xojo IDE, select File > IDE Scripts > New IDE Script
2. In the script editor place the following code:

   // Get the text from the clipboard
   Dim c As String = Clipboard
   
   // Double up all of the quotes
   c = c.ReplaceAll("""","""""")
   
   // Insert the text into the code editor
   SelText = c

3. Select File > Save As and save the script to the “Scripts” folder next to the IDE.

Now whenever you have quoted text to paste into the IDE, just select your script from the File > IDE Scripts menu instead!

General Changes

First, the Web Framework now has support for Retina/HiDPI in supported browsers. All controls have been updated with new graphics to allow your Web Apps to look great on any screen. All you have to do is just flip the “Supports Retina/HiDPI” switch and start using Image objects instead of Pictures and you’re off and running!

NOTE: Regardless of whether you check the “Supports Retina/HiDPI” switch, the web framework now stores all of your image assets in the Resources directory next to your app and they are only loaded momentarily when a browser requests one. This means that your app should use a lot less memory overall.

Controls

WebCanvas: HiDPI/Retina drawing out of the box! No code change required!

WebPicture: Just start using Images instead of Pictures and flip the Retina/HiDPI switch and the web framework will automatically send the correct resolution image to the browser.

WebImageView: Because it’s backed with a WebPicture, it just works!

WebToolbar: Toolbar icons now support Images as well.

Events

WebSession.ScaleFactorChanged: Fires whenever the ScaleFactor of the current session’s browser changes.

Properties

WebSession.ScaleFactor (Read-Only): Reflects the current ScaleFactor of the browser.

WebSDK

The WebSDK has been given a ScaleFactorChanged event so your control is notified when a change occurs instead of your control needing to periodically check the ScaleFactor property on the Session object.

WebControlWrapper.ScaleFactorChanged: Fires whenever the ScaleFactor of the current session’s browser changes.

Also for WebSDK, we are now enforcing unique Javascript Namespaces throughout a project at compile time. This means you’ll be able to tell ahead of time if your controls are missing a namespace or if you’ve inadvertently used the same exact namespace more than once!

Having said that, if you are creating or using pictures in your project, there may be a few adjustments you’ll need to make to your code. A little over a year ago the process of making sure we had all of the necessary graphics together to build a Retina/HiDPI IDE was added to my to-do list. While 95% of the icons created for the Xojo IDE in 2013 already existed, most of the graphics that made up the IDE itself did not, and the IDE itself needed a bit of an overhaul to get it ready for the big change, both in graphics and in code…

Graphics

Since the Xojo framework didn’t have any HiDPI support yet, everything done last year was done brute force, that is, 2x images were loaded, scaled down by 50% and drawn where they belonged, just to make sure things would mostly line up correctly. While doing this did reveal the amount of work that we were in for, it also hid some issues that we ran into when the HiDPI-enabled frameworks started coming available this spring.

To give you an idea of the size of the task, there are a little over 1000 distinct icons and images used in the IDE today, of which ~370 we did not have a HiDPI version. Now while I like using programs like Photoshop® or Fireworks® for doing work like this, I wanted to transition our graphics to a vector drawing tool so that if/when a higher resolution screen is available, we’ll be able to go back to the originals and start from resolution-independent source-material. That said, we settled on using Bohemian Coding’s Sketch for the majority of the new graphics work. Total time to generate the missing images was about two man-months.

Code

Once the HiDPI-enabled frameworks started coming together, every place where a picture was being drawn needed to be audited (see why in the next section). This work took us from mid-December all the way through mid-March. I won’t tell you that it took two of us three full months of 60 hour weeks to accomplish, but it sure felt like it.

A couple of legacy coding issues came to light which would have to be resolved for everything to work right and I wanted to go over them just in case your projects don’t render correctly right off the bat. Let’s look at what’s changed.

Points vs. Pixels

This is by far the most common issue you’ll probably run into. Before Xojo had HiDPI support, a single element of color on a Picture and a single element of color on a Graphics object were exactly the same thing, pixel for pixel.. If your code looked like this:

Dim p As New Picture(100, 100)
Dim g as Graphics = p.Graphics
Dim widthPic as Integer = p.Width
Dim widthGraphics as Integer = g.Width

both widthPic and widthGraphics would have values of 100.

Now with HiDPI turned on, Picture coordinates and Graphics coordinates can be different from one another if the scale factor of the screen is greater than one. If you were to change the code above to:

Dim p As TrueWindow.BitmapForCaching(100, 100)
Dim g as Graphics = p.Graphics
Dim widthPic as Integer = p.Width
Dim widthGraphics as Integer = g.Width

The value of widthPic will differ depending on whether your application is running on a HiDPI screen or not:

…and this is where the trouble begins because the number of physical pixels has actually doubled (in both directions, by the way) while the width and height of the Graphics object still reflect the original dimensions. The difference between these values is the scale factor of the screen you are drawing to.

Now, if you consider that Picture.Width and Graphics.Width have been interchangeable until now, you can see that this can cause a bit of a problem. When drawing to the Graphics object, you need to be working in Graphics pixels, not Picture pixels:

Dim p As TrueWindow.BitmapForCaching(100, 100)
Dim g as Graphics = p.Graphics
Dim widthPic as Integer = p.Width
Dim widthGraphics as Integer = g.Width
g.ForeColor = &cFF0000
g.DrawOval(0, 0, g.Width, g.Height) // Correct
g.DrawOval(0, 0, p.Width, p.Height) // This will draw too large

To wrap up this already long story, make sure all of your drawing routines are using coordinates relative to the Graphics object.

Immutable Pictures

Another hurdle you’ll undoubtedly encounter is the fact that multiresolution images are not inherently editable. This allows the framework to be more intelligent about loading and unloading images at runtime. This affects Image objects created in the IDE as well as ones created in code using the new Picture Constructor API. The most obvious effect is that you can’t draw directly to these images any more and the Graphics and RGBSurface properties will be Nil. If you need the ability to draw onto a picture via its Graphics property, draw the image onto a Picture created in code and work from that – don’t forget to copy the scale properties!

Nested Drawing

If your application creates pictures, and draws other pictures and clips into it using several levels of nesting, make sure you start from the top level when refactoring your code. You’ll find any compounded scaling errors much earlier this way, but you’ll also run a much smaller risk of creating issues that will only manifest when you go back and fix the top level drawing routines.

Drawing Without Context

For most of you, your drawing code will be directly in the Paint event of a Canvas and the Graphics object passed to the event already has all of the information that you need to succeed. In addition, you can always get a mutable picture that is all set up for the current screen by calling the new Window.BitmapForCaching method. This method is available from any RectControl, Window or ContainerControl subclass using TrueWindow.BitmapForCaching.

If (for some reason) you don’t have access to a window from your code, you can create a HiDPI image from a Graphics context by using the new ScaleX and ScaleY properties to set things up. For consistency, we created an extends method in a module like this:

Function BitmapForCaching(Extends g as Graphics, Width as Integer,  Height as Integer) As Picture
  Dim p as New Picture(Width * g.ScaleX, Height * g.ScaleY)
  // Set the appropriate resolution
  p.HorizontalResolution = 72 * g.ScaleX
  p.VerticalResolution = 72 * g.ScaleY

  // Set the scale factor so drawing to it will be correct
  p.Graphics.ScaleX = g.ScaleX
  p.Graphics.ScaleY = g.ScaleY

  // Very important to remember the mask!
  p.Mask.Graphics.ScaleX = g.ScaleX
  p.Mask.Graphics.ScaleY = g.ScaleY

  // Return the new picture
  Return p
End Function

If neither a Window nor a Graphics context is available, you can always create a multi-representation picture and leave it up to the framework to choose the right one when the image is being drawn to a Window, like this:

Dim pa() as Picture
Dim p1 as new Picture(100, 100)
p1.Graphics.DrawOval(0, 0, 100, 100)
pa.append p1

Dim p2 as New Picture(200, 200)
p2.Graphics.DrawOval(0, 0, 200, 200)
pa.append p2

Dim RetinaPicture as New Picture(100, 100, pa)

You’ll have to draw everything twice, so I suggest caching these images so you don’t need to do this more than once, especially if your drawing code is complicated. You can use a similar technique to load images from disk:

Dim pa() as Picture
Dim f as Folderitem = GetFolderItem("Test.png")
Dim pic as Picture = Picture.Open(f)
pa.append pic

f = GetFolderItem("Test@2x.png")
pic = Picture.Open(f)
pa.append pic

Dim RetinaPicture as New Picture(100, 100, pa)

Just remember that the images passed into this form of the Picture.Constructor must all have exactly the same aspect ratio or the framework will throw an InvalidArgumentException!

Conclusion

We’re looking forward to seeing all of your apps become HiDPI-aware and hearing about your experiences. I hope that our experience and suggestions make your transition just a little bit easier!

Read more: Advanced Retina/HiDPI: BitmapForCatching and ScaleFactorChanged

When we created the iOS app for XDC 2015 last spring, I decided to take a different route and try out a few of the commercial REST API clients to see if any of them would make my life easier. The one I settled on was Paw from LuckyMarmot, primarily for its support of extensions written in JavaScript.

There is a small library of extensions available on the Paw website, most of which are for code examples and that got me thinking… why not have examples of the request in Xojo code, both old and new framework so that I don’t need to do that by hand every time.

Examples

For the sake of this example, let’s say that we’re making a request to login to a fictitious API. The URL of this request is https://www.example.com/api/login, it expects that you will pass the username (name) and password (1234) as URL parameters and that a preshared key is to be included in the body of the request as JSON.

Paw comes with an extension for creating cURL requests and the output of that extension looks like this:

curl -X "GET" "https://www.example.com/api/login?username=name&password=1234" 
 -H "Content-Type: application/json" 
 -d "{"preshared-key":"QU^k9h36zdF8nx7Y"}"

Using our Paw extensions, the Old Framework Xojo extension generates code that looks like this:

// Login (Old Framework)

// Set up the socket
dim h as new HTTPSecureSocket
h.Secure = True
h.ConnectionType = h.TLSv12
h.setRequestHeader("Content-Type","application/json")

// JSON
Dim js As New JSONItem
js.Value("preshared-key") = "QU^k9h36zdF8nx7Y"

// Convert Dictionary to JSON Text
Dim data As String = js.toString()

// Assign to the Request's Content
h.SetRequestContent(data,"application/json")

// Set the URL
dim url as string = "https://www.example.com/api/login?username=name&password=1234"

// Send Synchronous Request
dim s as string = h.SendRequest("GET",url,30)

If you’re using the new framework extension, it generates code that looks like this:

// Login (New Framework)

// Set up the socket
// "mySocket" should be a property stored elsewhere so it will not go out of scope
mySocket = new Xojo.Net.HTTPSocket
mySocket.RequestHeader("Content-Type") = "application/json"

// JSON
Dim d As New Dictionary
d.Value("preshared-key") = "QU^k9h36zdF8nx7Y"

// Convert Dictionary to JSON Text
Dim json As Text = Xojo.Data.GenerateJSON(d)

// Convert Text to Memoryblock
Dim data As Xojo.Core.MemoryBlock = Xojo.Core.TextEncoding.UTF8.ConvertTextToData(json)

// Assign to the Request's Content
mySocket.SetRequestContent(data,"application/json")

// Set the URL
dim url as Text = "https://www.example.com/api/login?username=name&password=1234"

// Send Asynchronous Request
mySocket.Send("GET",url)

These extensions are available for download using the link below. Once downloaded, extract the folders into the Paw Extensions folder which you can reach by going to the Paw menu and selecting Extensions->Open Extensions Directory. Once they’re in there, you can make them available by selecting Extensions->Reload All Extensions.

Versions for the Classic Framework and Xojo Framework are available on GitHub:

• Paw Extension for HTTPSocket
• Paw Extension for Xojo.Net.HTTPSocket
• Paw Extension for URLConnection

CONCLUSION:

Paw is an excellent tool for storing and managing API configurations and examples, plus adding the ability to copy and paste Xojo HTTP socket code makes it an even better part of your library if you work with a lot of HTTP RESTful APIs.

Unfortunately this means that you’re often working with an engine that’s way out of date and it makes using the HTMLViewer as a control a real pain if you want to use any relatively new technologies.

There have been a few ideas to fix this over the years, but the most reliable solution I’ve seen has been to modify the registry and tell Windows what version of IE you want to use. Problems include: you can’t really expect an end user to do something like that; it can be risky to edit the registry if you don’t know what you’re doing; and most corporate users are locked out of the registry for that reason anyway.

Now for a better way

If you have control over the content being displayed, that is, you have the ability to modify the HTML being displayed, there is a way for you to get Windows to use a newer engine. You’ll need to add a very specific tag to your html within the <head> section of the page. You can do this one of two ways:

<meta http-equiv="X-UA-Compatible" content="IE=edge" />

This version will tell Windows to use the latest engine it has available. If IE11 is installed, you’ll get the IE11 engine.

<meta http-equiv="X-UA-Compatible" content="IE=8" />

This version tells Windows to use a very specific version of the engine. If you have IE11 installed, it will still use the IE8 engine. Looking for more tips for Xojo on Windows?

Adding a Database

Adding a database server to your Xojo Cloud server is easy! Just go to your Xojo Cloud control panel and click “Enable MySQL” or “Enable PgSQL.” In a moment, you will be presented with a username and password. That’s it!

Connecting to a Database from a Xojo Cloud app:

Connecting to the database server is just as easy:

Dim db as new PostgreSQLDatabase // (or MySQLDatabase)
db.username = "username"
db.password = "password"
db.host = "localhost" // Use "127.0.0.1" for MySQLDatabase
db.port = 5432 // 3306 for MySQL
db.databasename = "your database name"
if db.connect then
  // You're connected!
end if

Note the entry for Host. Your database is only accessible from the server itself. Even if you open a port in the firewall, neither of the database engines (MySQL or PostgreSQL) are listening on the addresses for the server’s IP addresses.

Connecting to a Database from Somewhere Else

Up to now, everything’s been very straightforward, but what happens if you need to access the database from your local machine for testing? What if you want to use a database management tool like pgAdmin, MySQL Workbench or any of the many commercial management tools out there? This is where the power of SSH tunnels come into play.

Before I show you how to make an SSH tunnel, lets talk a little about what they are. An SSH tunnel is a secure connection, between your computer and another (in this case your Xojo Cloud server) which is used for transmitting data on a particular port. In essence, it allows us to create a private connection through the internet which allows you to see into your server on the other end and connect to a particular service there.

To create a tunnel between your computer and your Xojo Cloud server, you first need to turn on the tunnel capability on your server. Go to your control panel and click the “Enable Tunnel” button. You will be presented with a username and a password which you will use later for establishing the connection.

Connecting a Database Management Tool

Most of the database server management tools have the capability to connect using an SSH tunnel. In the dialog used to set up the connection, look for something that says SSH or SSH Tunnel. In most cases, you will need to fill out four fields:

• Host Name or IP Address – Enter the IP address for your Xojo Cloud server
• Port – Enter 22. This is the SSH port number.
• User Name – Enter the user name that was provided to you in the Xojo Cloud control panel when setting up the tunnel.
• Password – Enter the password that was provided to you in the Xojo Cloud control panel when setting up the tunnel.

Now, as far as setting up the connection to the database itself, you will have another set of fields to fill out:

• Host Name or IP Address – Enter “localhost”*
• Port – 5432 for PostgreSQL, 3306 for MySQL
• Database – Enter the user name that was provided to you in the Xojo Cloud control panel when setting up the database server.
• User Name – Enter the user name that was provided to you in the Xojo Cloud control panel when setting up the database server.
• Password – Enter the password that was provided to you in the Xojo Cloud control panel when setting up the database server.

* The reason you enter localhost for the server name is that you want to connect to your side of the tunnel. SSH will do the job of hooking things up on the other end for you.

Voila! You can now connect to your database server to create and edit users, databases, tables, etc.

Manually Creating a Tunnel

Sometimes you need to create a tunnel outside of a management app. This is a great way of testing your app locally while still having it connected to the actual database server. If you are using OS X or Linux, you can just open a Terminal window:

On OS X and Linux the command is quite simple:

ssh -L 5432:localhost:5432 dbadmin@ipaddress -N

If you want to see more information about the tunnel and when it is in use, add -v at the end of that command to use it in verbose mode.

If you are using Windows, I suggest using a program like PuTTY. There are a number of tutorials available on the internet, just put putty ssh tunnel into your favorite search engine. [Xojo Blog Post: Setting up puTTY to create a SSH tunnel from Windows to Xojo Cloud]

That’s it! Connecting a web app to a database server has never been easier and we hope this will encourage you to build bigger and better web apps!

For more information, you can also refer to the Xojo Cloud Databases topic in the docs.