First, I’m going to create a headless desktop application. A console application would work, but shows a command box.

In the Xojo IDE, create a new desktop project and delete Window1 and MainMenuBar. Then add the Opening Event Handler to App and add this code:

Self.AllowAutoQuit = True

This will allow the application to quit when done.

Add the DocumentOpened Event Handler to App and add this code:

If item _ ' Using item
 .NativePath _ ' property NativePath
 .NthField(":", 1) <> "AlertDemo" Then ' Compare the value left of the ":"
 Return ' If invalid return (quit)
End If
Var alert As String ' Define the variable
alert = item _ ' Using Item
 .NativePath _ ' property NativePath
 .NthField(":", 2) ' Extract the contents to the right of the ":"

alert = DecodeURLComponent(alert) ' Convert the content to plain text
MessageBox(alert) ' Show the alert
' The app will now quit

To test you can select Shared in Build Settings.

And enter a value into Command Line Arguments:

Running the app in debug mode will show:

Now build the project and create an installer using Inno Setup.

[Setup]
AppId={{B4D9ABDA-9F58-4FE0-A5F3-3E39C28EAB59}
AppName=Alert Demo
AppVersion=1.0
DefaultDirName={commonpf64}\Axis Direct Ltd\Alert Demo
DefaultGroupName=Axis Direct
OutputDir=C:\Xojo Projects\Alert Demo\Installer
OutputBaseFilename=AlertDemoInstaller
Compression=lzma
SolidCompression=yes
ChangesEnvironment=yes
[Languages]
Name: "english"; MessagesFile: "compiler:Default.isl"
[Tasks]
[Dirs]
Name: "{app}\Alert Demo Libs"
[Files]
Source: "C:\Xojo Projects\Alert Demo\Project\Builds - Alert
Demo\Windows 64 bit\Alert Demo*"; DestDir: "{app}"; Flags:
ignoreversion
Source: "C:\Xojo Projects\Alert Demo\Project\Builds - Alert
Demo\Windows 64 bit\Alert Demo\Alert Demo Libs*"; DestDir:
"{app}\Alert Demo Libs"; Flags: ignoreversion
[Icons]
[Run]
[Registry]
Root: HKCR; Subkey: "AlertDemo"; Flags: uninsdeletekey
Root: HKCR; Subkey: "AlertDemo"; ValueType: "String";
ValueData: "URL:AlertDemo Protocol"; Flags: uninsdeletekey
Root: HKCR; Subkey: "AlertDemo"; ValueName: "URL Protocol";
ValueType: "String"; ValueData: ""; Flags: uninsdeletekey
Root: HKCR; Subkey: "AlertDemo\shell"; Flags: uninsdeletekey
Root: HKCR; Subkey: "AlertDemo\shell\open"; Flags:
uninsdeletekey
Root: HKCR; Subkey: "AlertDemo\shell\open\command"; Flags:
uninsdeletekey
Root: HKCR; Subkey: "AlertDemo\shell\open\command";
ValueType: String; ValueData: "{app}\Alert Demo.exe %1";
Flags: uninsdeletekey

The registry section creates the registry entries per William’s blog post.

Now that the application Is installed, we’ll look at the Web Application. For the sake of testing, I’m just adding a Button to a WebPage and adding the following code into the pressed event.

Var s As String = "Hello World"
Var Alert As String
Alert = EncodeURLComponent(s) ' Make the string URL safe
GoToURL("AlertDemo:" + Alert, True) ' Launch the app in a new tab

And that is it!

For printing a docket, I would pass a unique identifier for the transaction using this method then access the data using URLConnection & HandleURL.

Wayne Golding has been a Xojo developer since 2005 and is a Xojo MVP. He operates the IT Company Axis Direct Ltd which primarily develops applications using Xojo that integrate with Xero www.xero.com. Wayne’s hobby is robotics where he uses Xojo to build applications for his Raspberry Pi, often implementing IoT for remote control.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

Ok, now that you’ve read that article let’s take a closer look at how you, as a Xojo developer, can handle this. Well, as you’ve diligently read in the above article, the first step is to register your application to handle a particular URI scheme by modifying the registry. The preferred approach is to do this as part of your Application’s installation process because at that point the user has given access rights to install your app and access rights therefore to modify the registry. This is the general structure as discussed in the MSDN article:

HKEY_CLASSES_ROOT
    alert
        (Default) = "URL:Alert Protocol"
        URL Protocol = ""
        DefaultIcon
            (Default) = "alert.exe,1"
        shell
            open
                command
                    (Default) = "C:\Program Files\Alert\alert.exe" "%1"

Where “alert” is your URI scheme, so if you navigate to a URI like alert:Hello, your web browser will launch your application with an extra command line argument: “alert:Hello”

The MSDN article goes into detail about how spaces, quotes, or backslashes affect your command line arguments depending on how the URI is invoke (i.e. Web Browser vs. ShellExecute/Run command). The take home message is just to avoid spaces, quotes, or backslashes in your URI if possible.

If you simply want to create a quick test to see how this works, you could execute the following Xojo code to add this URI scheme to the registry:

Dim reg As New RegistryItem("HKEY_CLASSES_ROOT")
reg = reg.AddFolder("alert")
reg.DefaultValue = "URL:Alert Protocol"
reg.Value("URL Protocol") = ""

Dim defaultIcon As RegistryItem = reg.AddFolder("DefaultIcon")
defaultIcon.DefaultValue = """" + App.ExecutableFile.NativePath + """,1"

Dim commandItem As RegistryItem = reg.AddFolder("shell").AddFolder("open").AddFolder("command")
commandItem.DefaultValue = """" + App.ExecutableFile.NativePath + """ ""%1"""

Because you’re modifying the registry, you will need to run your application as administrator (i.e. contextual/right click your app and select “Run as administrator” in the menu). This will add the necessary registry entries.

After this is done, your URI scheme is ready to be tested. Launch Internet Explorer and enter “alert:hello” in the URL field. After pressing Enter, your Application that added those registry entries will be launched. Now all you need to do is check the System.CommandLine property to see what alert message was passed. For example, if I added a MsgBox System.CommandLine to my App.Open event, I’d get something like this after entering “alert:how cool isXojo” in the URL field in Internet Explorer.

As you can see it’s very easy to set this up and handle the custom URI schemes in your application.  Just be aware of the potential security issues that malicious people could be passing to your command line and handle those appropriately.

To use custom URIs on Mac OS X visit this post: Let Your OS X Desktop App React to Custom URIs 

Implementing this kind of behavior in your OS X apps is not rocket science! Follow these simple steps in order to register a custom URI from your app.

Register the custom URI you want to manage

You’ll need to modify the “info.plist” file generated by Xojo every time the app is compiled, so it necessarily involves the use of the powerful Build Steps! To smooth the road, follow these steps first:

1. Control + Click the OS X item under the Build Settings section of the Project Browser panel (the leftmost column in the Xojo IDE)
2. Select the option Add to “Build Settings” > Build Step > Script.
3. Paste the following code (make sure PlistBuddy from Apple’s Developer Tools is installed on your Mac!):

Dim App As String = CurrentBuildLocation + "/" + CurrentBuildAppName
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes array"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0 dict"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLName string 'Demo'"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLSchemes array"" " + App + "/Contents/Info.plist" )
call DoShellCommand("/usr/libexec/PlistBuddy -c ""add :CFBundleURLTypes:0:CFBundleURLSchemes:0 string 'demo'"" " + App + "/Contents/Info.plist" )

Observe the use of the strings ‘Demo’ and ‘demo’ for the CFBundleURLName and CFBundleURLSchemes keys, respectively. The second one, CFBundleURLSchemes, is the customized URI that anyone will be able to use to pass information to our application.

Make sure to select the option “Both” on the Inspector for this build step, and type a name to identify this script  (for example, “Insert URI on Plist”). This way the URI will be registered every time you run the app from the Debugger or once it is compiled for deployment (release or standalone app).

Let your app react to the URI

The second main step is letting your Xojo app react to the URI, this is something you can do by adding the HandleAppleEvent event to the App Object.

As for the code, you will probably want to to use inside this Event, the main point is to identify the received Event and compare it to the “GURL” string, because this is the identifier used by OS X for sending an URI event:

    if eventClass = "GURL" then
      //do your thing
      return true
    end if
    return false

This way the app doesn’t interferes with the events we are not interested in.

It is very important to point out that the HandleAppleEvent event should exit with Return False for the ignored Events. Otherwise the user of your app probably will experience malfunctions using keyboard shortcuts on TextFields or TextAreas among other problems.

Getting the information

The final step is to extract the passed information along the “GURL” event. Xojo provides several methods that helps you do this; but for this example we are going to provide the code for the most common uses: getting the information sent as a text String.

    dim s() as string = DecodeURLComponent(theEvent.StringParam("----")).DefineEncoding(encodings.UTF8).Split(":")
    s.Remove(0)

The main point here is the ‘theEvent.StringParam(“—-“)’ code. This gets the string available and that is associated with the keyDirectObject key of the Dictionary (the value of that constant is the “—-” string used here.)

The second thing to highlight is that you have to assign a Text Encoding for the received string and use the DecodeURLComponent function to restore the original text sent along the URI (“demo:”, for this example).

Lastly, you can use the Split function to get an Array of strings so you can discard the first component from the received string (the URI itself) and join the remaining elements to get the final string.

You can watch the video (in Spanish only) that talks you though this example.

Visit this post to learn how to Customize URI Schemes on Windows.

Javier Rodríguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has used Xojo since 1998. He is in charge of AprendeXojo.com and the developer behind the GuancheMOS plug-in for Xojo Developers and the Snippery app among others.

*Read this post in Spanish.