Have you ever wondered how the magic behind the “mailto://” or other similar Uniform Resource Identifiers (URI) work? Whether from the web browser URL field or from Xojo via the ShowURL function, when URIs are executed the registered app opens showing the passed parameters (for example, in the Mail app for the ‘To’, ‘Subject’ and ‘Body’ fields).
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:
- Control + Click the OS X item under the Build Settings section of the Project Browser panel (the leftmost column in the Xojo IDE)
- Select the option Add to “Build Settings” > Build Step > Script.
- 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.
