These new options are available in the Inspector Panel when selecting the Sign step available under Build Settings > macOS.

Requirements

In order to apply Sandboxing, Hardened Runtime and go through the Notarization process for your macOS app, you will need to make sure that the following is installed on your Mac:

• macOS 11.3 or later.
• Xcode 13 or later – Run it at least one time and make sure that all its required components and SDKs are installed.
• Apple Developer ID – This needs to be a paid Apple Developer membership. Also, make sure you have your Developer certificates installed in the Mac.
• A working Internet connection.

Sandboxing

With the Sandboxing switch enabled, you can access the associated editor in order to enable the appropriate entitlements for the purposes of the app.

The Sandboxing settings will be applied even when the app is run from the IDE (debug mode). That means that Sandboxing can be applied both using an Ad-Hoc Certificate or the user Developer ID Application Certificate.

Hardened Runtime

When the Hardened Runtime switch is enabled, you will be able to access the associated editor in order to set the appropriate hardening entitlements for the purposes of the app.

Note: The Hardened Runtime will not be applied when the project is run from the IDE.

When building the app, if Hardened Runtime is enabled and no Developer ID Application value is entered in the Developer ID field (that is, signed as ad-hoc), then the following dialog will be shown and the build process will stop.

Notarization

When the Notarization switch is enabled, it will automatically enable the Hardened Runtime Switch if it is not already enabled (because the Notarization process requires Hardened Runtime!).

With the Notarization switch enabled, you will be able to access the Setup dialog in order to setup the app-specific password required by this process to properly work. Creating this password only needs to be done one time, because it will be saved to the computer keychain and even synced via iCloud to others Macs from the same user (that is, iCloud account).

Note: As with the Hardened Runtime feature, the Notarization process will not take place if the project is run from the IDE.

When building the app, if Notarization is enabled and no Apple Development value is entered in the Developer ID field, then the following dialog will be shown and the build process will stop.

The Notarization process does require an active network connection to the Internet because it needs to talk with the Apple Service responsible of checking the app bundle contents. This means that the required time to complete the process will vary depending of your Internet connection speed and the load or availability of the Apple Notarization service itself.

Custom User Entitlements

Besides the entitlements you may have selected in the Sandboxing and Hardened Runtime editors, you may need to add other ones not available in these editors. This is something you can do through the User Entitlements field (.Plist file format). Such custom entitlements will be merged with the ones selected in the editors. If the custom entitlements entries collide with the ones selected in the editors, then the ones from the editors will be applied, discarding the duplicated ones found in the provided file.

Building macOS apps… from Windows

When the macOS app is built from Windows, and Sandboxing, Hardened Runtime or Notarization is applied (and optionally custom entitlements), then the final compressed archive will include all the required supporting files including the shell script required to run from a macOS computer to complete the signing process using the provided Apple Developer certificate (except the option to create an App-specific password for the Notarization step, because that can’t be done from Windows).

Summary

As you can see, Xojo 2024r4 streamlines the ability to apply Sandboxing, Hardened Runtime and Notarization to your macOS apps, and even run them as sandboxed from the IDE, so you can get better feedback during the debugging process to everything related with the access to files, network user, camera access, etc. That is, the same behaviour your users will have once they run the app downloaded from the Mac App Store or from your website.

See detailed steps in the Xojo Documentation. If you need to know about what Sandboxing, Hardened Runtime or Notarization means, please take a look to the “macOS Apps: From Sandboxing to Notarization, The Basics” blog post.

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

More in this series on distributing Mac apps:

• Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE
• macOS Apps: From Sandboxing to Notarization, The Basics
• Uploading macOS Builds to App Store Connect
• Provisioning Profiles for macOS Apps

What’s New in Xojo 2024r4

Xojo 2024r4 brings a range of exciting updates that enhance cross-platform development, improve security, and provide more tools for creating dynamic and interactive applications. Here are some of the standout features:

Web Framework
Enjoy smoother and more efficient web applications with updates to Xojo’s Web Framework. Improved memory usage and numerous bug fixes ensure that your web apps run reliably and perform optimally, providing a better experience for your users.

Discover Web Framework Improvements

These updates and enhancements are designed to make your development process more efficient, productive, and enjoyable. Whether you’re building new applications or enhancing existing ones, Xojo 2024r4 provides the tools and capabilities you need to succeed.

Get Started

To learn more about Xojo 2024 Release 4 and begin your development journey, please visit the Xojo 2024r4 Release Notes. The update is available for download now from the Xojo downloads page.

What’s Next?

We’re continuously working on new features, updates, and enhancements to our platform. If you have any suggestions or ideas, please add them to the Xojo tracker. We’re always looking to improve and expand Xojo to better serve our community.

Thank you for being part of the Xojo community. We’re excited to see what you create with Xojo 2024r4!

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

In fact, Apple recommends to Notarize the software even if you are going to distribute it from your own website, outside of the Mac App Store. But, don’t be scared! Currently there are good third parties options available that ease the path, like App Wrapper from Ohanaware, or some OpenSource options as for example Xojo2DMG; and through this article you will see how to enable Sandboxing, runtime hardening and even Notarizing on a simple example app. Of course, this will touch only the basics and it is up to you to read the related Apple Documentation to add the entries, both the Entitlements and additional keys/values in the app Info.plist file, required by the purposes of your particular app, for example file access, camera or mic access, network access, etc.

A Bit of Common Ground

At this point, your head may be spinning if you are unfamiliar with these app security terms; so, what do Sandbox, hardened runtime and Notarizing mean when they are applied to macOS apps?

Sandboxing

When a macOS app is sandboxed, that means that macOS will create an exclusive container for everything related to the app the first time it is launched. This is what happens when installing an iOS app, too! Such a container will have its own structure to access things like documents, pictures, downloads, etc. Think about it as the own private execution space for the app:

Of course, there are entitlements waiting for you so your sandboxed app can access the files created by other apps (including the Desktop, Downloads, Movies, Music and Picture folders), among other things.

Hardened Runtime

When enabled for your macOS app, hardened runtime adds an extra layer of protection to the running code itself. For example, it prevents certain classes of exploits, like code injection, dynamically linked library (DLL) hijacking, and process memory space tampering. This kind of protection is also enhanced by the System Integrity Protection (SIP).

Notarization

In brief, this is a third layer of confidence for the potential users of your macOS app. When the app is notarized, that ensures to the user that the Developer ID-signed software you distribute has been checked by Apple for malicious components. This is not related with the Apple Review process of your app when it is submitted to the Mac App Store, it’s related to the macOS Gatekeeper technology. So, when a Notarized app is downloaded from Internet, for example, Gatekeeper will use the notarization ticket attached to your app/DMG file to provide more meaningful information about the origin of the app, including if it is safe for the user to open it.

Preparation

In order to follow this article, you will need:

• Xojo. Download it for macOS if you have not done yet.
• macOS 11.3 or later.
• Xcode 13 or later. Run it at least one time and make sure that all its required components and SDKs are installed.
• Apple Developer ID. This needs to be a paid Apple Developer membership. Also, make sure you have your Developer certificates installed in the Mac.
• A working Internet connection.

With all of this in place, open Xojo to create a macOS Desktop project and do some basic layout in the by default window. It is not required to add any functionality to keep the focus in the task at hand. Then, use Build Settings > macOS > Mac App Name to give an appropriate name to the built application (for this example I named it “SandboxedApp”).

Lastly, save the project (for example into the Documents folder) and click the Build button to build the app! It is not required at this point to assign the Developer ID in the Build Settings > macOS > Sign section, because we are going to sign it (again) in the next steps.

Creating the Entitlements File

The entitlements file is pretty similar to the Info.plist file you probably already know that is in charge of storing the required keys and values for the app to properly work. Both of these are in XML format, and the only difference is that while the Info.plist file is created for you by Xojo, the Entitlements file needs to be, currently, manually created for you.

So, open your text editor of choice (there a lot of there out there, both free and paid ones; personally I tend to use BBEdit from BareBones Software). Add the following lines to the text document and save it with the name “Entitlements.plist” (if you keep it next to the saved built macOS app, the better). This is the file where you will probably want to add more entitlement entries as your app requires them:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
  <key>com.apple.security.app-sandbox</key>
  <true/>
</dict>
</plist>

Sandbox Your App

With the compiled app and the entitlements file in place, open the Terminal app and type the following command and press the return key:

> codesign --force --deep --timestamp --entitlements <path-to-your-entitlements.plist-file> -s "Developer ID Application: <your-full-developer-name (including-the-team-id)>" <path-to-the-bundle-of-your-app>

Once executed, run the “SandboxedApp”, open the Activity Monitor app and make sure that the Sandbox option is enabled under the View > Columns options. Then, use the search box of the main window to filter the displayed processes so it only displays your app. Take a look to the value under the Sandbox column and you will see that the app is now Sandboxed, and the Container for it has been created under the Library/Containers path. Quit the app when you are done.

Hardened Runtime

With our app already sandboxed, let’s look how to add the hardened option to it. Once again, type the following command in the Terminal prompt:

> codesign --force --deep --options runtime --timestamp --entitlements <path-to-your-entitlements.plist-file> -s "Developer ID Application: <your-full-developer-name (including-the-team-id)>" <path-to-the-bundle-of-your-app>

As you can see, it doesn’t vary much from the previous command. All it adds is the “–options runtime” text in charge of enabling the runtime hardening. Also, as you might guess, using this command will enable the Sandboxing of the app and also the runtime hardening, at all once.

Do you want to check if it worked? Well, type the following command at the Terminal prompt:

> codesign --display --verbose <path-to-the-bundle-of-your-app>

It will produce an output similar to this one:

Executable=<path-to-the-executable>
Identifier=com.xojo.sandboxedapp
Format=app bundle with Mach-O universal (x86_64 arm64)
CodeDirectory v=20500 size=43297 flags=0x10000(runtime) hashes=1342+7 location=embedded
Signature size=9100
Timestamp=13 Aug 2024 at 12:51:28 PM
Info.plist entries=15
TeamIdentifier=************
Runtime Version=11.1.0
Sealed Resources version=2 rules=13 files=4
Internal requirements count=1 size=184

It is the “flags=0x1000(runtime)” which shows that, in fact, the app runtime is hardened. Congrats!

Notarizing the App

This is the final step, but is going to require an extra step from your side. Because the notarytool command line tool, used for notarizing the app, is going to require the ID and password from your Apple ID account, plus the fact that it uses 2FA authentication, it is very convenient to create an app specific password for it.

Creating an App-Specific Password

In order to create the password used by the notarytool process, follow this steps:

1. Sign in to appleid.apple.com
2. In the Sign-in and Security section, select the App-Specific Passwords option:

3. The previous action will bring a new dialog displaying all the app-specific passwords already created. Click the “+” button to add a new one:

4. Type a meaningful name for as the “Title” or description for your new password in the presented dialog (notarytool could be a good one):

5. Once you click the Create button it is possible that you will be asked to authenticate again using your Apple ID. Once done, a new dialog will present the generated password to you. Copy it and write it down (or paste it) into a safe place, because we are going to need it in the next step.

Adding the notarytool specific password to the Keychain

Because this app-specific password is going to be used by the notarytool command line tool, it would be very convenient to have it stored in the macOS Keychain. To do so, type the following command at the Terminal prompt, and press the Return key:

> xcrun notarytool store-credentials "notarytool-password" --apple-id "<your-apple-ID>" --team-id <your-developer-team-id> --password <the-password-copied-from-the-previous-step>

Once executed, you will be able to see the password added to the Keychain app under the name of “notarytool-password”:

Creating a Zip file for your app

The notarization process is handled by the Apple notary service running in the Internet, what means that notarytool needs to send (upload) the bundle of your app in an appropriate format. There are two options: as a DMG file (that needs to be signed before submitting), or as a zipped file, what is even faster and easier (Trivia: Did you know how easy it is to create Zip files in Xojo code?)

So, in order to upload our app for notarization, we need to create a Zip file first. Once again, it is time to type a new command at the Terminal prompt:

> /usr/bin/ditto -c -k --keepParent <path-to-app-bundle> <path-to-generated-zip-file/file-name.zip>

Uploading the app for Notarization

With our Zip file in place, we now have all the pieces to send it to the notarization process. The time spent by that process may (and will) vary depending of several factors.

In order to send the file, type the following command at the Terminal prompt:

> xcrun notarytool submit <path-to-zip-file/file-name.zip> --keychain-profile "notarytool-password" --wait 

After pressing the Return key, the process will start and the Terminal will output information about the progress; something similar to this:

Conducting pre-submission checks for <name-of-your-zip-file> and initiating connection to the Apple notary service...
Submission ID received
  id: <some-id-number-goes-here>
Upload progress: 100.00% (8.65 MB of 8.65 MB)   
Successfully uploaded file
  id: <some-id-number-goes-here>
  path: <path-of-the-zip-file>
Waiting for processing to complete.
Current status: Accepted........
Processing complete
  id: <keep-this-id-in-a-safe-place-you-will-need-it-later>
  status: Accepted

Have you seen the last line? The “status: Accepted” means that everything worked OK, and the notarization process has been successful, but it’s better if we check! Type the following command at the Terminal prompt. This one will ask the notarytool command to download the log file in JSON format to be saved at the desired path. It is a good habit to do it, because such a log file will include some eventual error and explanation about possible errors during the notarization process, including those related to the app itself:

> xcrun notarytool log <put-here-the-value-you-saved-in-a-secure-place-from-the-id-field-in-the-previous-output> --keychain-profile "notarytool-password" <path-to-save-the-log.json>

Staple the Ticket!

Assuming that everything worked OK, it is time to staple the notarization ticket to the app itself. It is not required, but is convenient to avoid online checks when the user runs the app, or Gatekeeper inspects it.

Yeah, that means using a new command from Terminal on the already signed, sandboxed and runtime hardened app bundle (not the Zip file you created for submitting using notarytool):

> xcrun stapler staple "<path-to-the-signed-sandboxed-and-hardened-app-bundle>"

After that, you can check that everything went OK using the following command:

> spctl -a -vvv -t install <path-to-the-signed-sandboxed-and-hardened-app-bundle>

And you should get something similar to this as the output:

source=Notarized Developer ID
origin=<your-full-developer-ID-Application>

App Distribution

That’s fine, but you will probably want to distribute your app from the Internet using a DMG container. In that case, follow these steps:

1. Create a DMG container (file).
2. Copy your already notarized app bundle into it.
3. Notarize the DMG file.
4. Staple the ticket to the DMG file.

That way the DMG container will be Notarized along with the app bundle inside it.

In Summary

As we did see, all the process of sandboxing, runtime hardening and Notarization involves a bunch of commands from the terminal, including the creation of the Zip file. But the good news is that all the process could be automated using Xojo itself! (take a look to the Shell class and the Zip method from the FolderItem class if you are not familiar with them).

As I said before, this article only on touches the basics and doesn’t dig into Provisioning Profile creation (associated with Capabilities required by the app), the Entitlements your app may need to properly work, among other topics; so you may find these Apple Developer Documentation of interest:

– Provisioning profiles.
– macOS Entitlements.
– macOS Sandbox.
– macOS Hardened Runtime.
– macOS Notarization.

Happy Xojo Coding!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

• Facebook
• X
• LinkedIn
• GitHub
• YouTube

More in this series on distributing Mac apps:

• Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE
• macOS Apps: From Sandboxing to Notarization, The Basics
• Uploading macOS Builds to App Store Connect
• Provisioning Profiles for macOS Apps

Apple Developer

1. Go into Certificates, Identifiers, & Profiles.
2. Select Identifiers on the left.
3. Click the plus sign to add a new identifier.
4. Select App ID and hit Continue to Register an App ID.
5. Choose iOS under Platform, enter a Description, and enter an ExplicitBundle ID. This must be the same as your Xojo project’s Bundle Identifier. Make sure In-App Purchase is checked (it should be by default).
6. Click Continue, then click Register on the next screen after you verify the information.

7. Back in Certificates, Identifiers, & Profiles, make sure you have a physical device listed. This will be used for the IAP test purchase since you cannot test a purchase in Simulator.
8. Select Devices on the left. If your device is not listed, click the plus sign to add it.
9. Select iOS as the Platform, enter in a name for the device, and enter in the Device ID (UDID). You get the UDID by connecting your phone to the computer, opening Xcode, choosing Window >> Devices and Simulators, right-click on your device listed on the left and select Copy Identifier.
10. Copy this into the UDID box in Apple Developer Register a Device.

iTunes Connect

In the Agreements, Tax, and Banking section, make sure you have active agreements for Free Apps and Paid Apps. The process of getting these agreements set up can take a couple of days.

To set up the in-app purchase product select Features at the top, then In-App Purchases on the left. Click the plus sign next to the In-App Purchases and choose which IAP you are using in your app then click Create.

Fill out the necessary data on the following screen:

• Reference Name: This is a name that is not displayed to the user. It is only for your reference.
• Product ID: Enter in the Bundle ID you made in Apple Developer but also include an end tag of the in-app purchase product name. For example, your Product ID might look like com.mycompany.myapp.myinappproduct.
• Check the box for Cleared for Sale (this should be checked by default).
• Choose a pricing tier.
• Scroll down, under App Store Information enter in a Display Name and a Description. These will be shown to the user.
• Scroll down to Review Information. You can include a screenshot of your app now or you can save your IAP product and add in a screenshot later. If you skip adding a screenshot, you will see a message saying Missing Metadata. This message will go away after you add a screenshot. The screenshot needs to be at least 640×920, which is the size of the iPhone 5s. The screenshot I used is a display of my purchase view in the app. Not sure if that is what they expect, but the app and IAP got approved.

Turn on In-App Purchases Xojo

1. Under Build Settings in left panel, click iOS.
2. Then, in the Inspector, click the Entitlements (gear icon) and move the switch for In-App Purchases to on.

3. Include Jason King’s iOSKit folder.
4. In my sample project, I have a ModalPurchaseView to handle the purchase/restore pieces. If you want to activate this the same way, add to your project Jeremie Leroy’s iOSExtensions which has the method to call the modal in a neat way. The ModalPurchaseView from the sample project can be copied to your project and used to cover the purchase/restore functions. Be sure to change the pieces in the code that points to your in-app purchase product, such as com.mycompany.myapp.myIAPproduct
5. Build your app with all features, then choose which features you want to be included in your premium version. I have a boolean property ActivatePremium in Module1 to be set to true if the premium is purchased.

Testing the In-App Purchase

You won’t be able to test the IAP in Simulator, so don’t even try. Instead, you will need to test on a physical device.

5. You will need to sign out of your Apple ID on your device. In the Settings of your device, go into the iTunes & App Store section, click your Apple ID at the top, then click Sign Out.

6. Open your app and click the Purchase option. You will be asked to sign in. Sign in with your sandbox account you created. After you sign in, you should see a Confirm Purchase [Sandbox Environment] box. Enter in your password and see what happens.

7. If you need to test it again, go back into Settings >> iTunes and App Store, scroll to the bottom, and sign out of the sandbox test account. Try with another account.
8. You should also test the Restore function of your IAP. It might be best to test this before testing a purchase to make sure you don’t end up getting the app for free without “purchasing”. When testing your Restore after purchasing, you will need to delete the app from the device and add it back through the Xcode method above in steps 2 through 4.

Credit to Jason King for creating iOSKit and to Jeremie Leroy for his personalized help with helping me get my first iOS app with in-app purchases off the ground. I hope you found this tutorial useful. You can download the project here.

Ryan Hartz has been a Xojo user for over 10 years.  He is a registered dietitian with no formal education in software development, illustrating that anyone can learn development in Xojo with its ease of use and understandable language.  In 2005, Ryan started his company, Visual Veggies Software, which offers software study guides to young nutrition students preparing to become registered dietitians.

What is the App Sandbox and why is it a chore?

The App Sandbox is a great end user security concept. The Sandbox governs what an application can and cannot do. This means that a virally infected word processor, cannot go on to infect other applications nor rampantly damage files on the users disk. It can however affect files which the user has created or opened within the word processor.

The developers’ pain comes from the App Sandbox’s greatest strength. The app developer must perform additional work, just to reclaim functionality that the App Sandbox took away. If you want to sell an app in the Mac App Store, the app must adopt the App Sandbox security.

Note: There are some functions which simply cannot be done within a Sandboxed application.

Trying to figure out solutions to these new issues often results in much head scratching and consulting with other developers via the Xojo Forums. I’ve seen some really creative solutions to reclaim features when using this security mechanism. In this post, I’m going to cover a few Sandboxing issues and how to resolve them with the tools / code that I’ve built for the apps that we sell.

Chocks away…

Taking my latest, greatest app, which just so happens to be a really cool Text Editor built with Xojo.

1. If I simply Sandbox the application (using App Wrapper 3, with just the minimum), I can create new documents, but I can’t save or even open documents.

2. The Recent Items menu no longer works.

3. I personally like apps that re-open the last documents I was working on. The same issue persists, code that used to work, no longer does.

4. Even more scary, is that users can’t even print- what kind of text editor can’t print?

Problems 1 and 4

We’ll start with the simplest, problems #1 & #4 are easily resolved with the options (“Open & Save Panels” & “Printer”) on the “Capabilities” panel within App Wrapper.

Note: There appears to be a new issue with Yosemite, I’m not 100% certain of the cause, but it seemed that changing the case of the application’s bundle identifier solved it. So “com.ohanaware.mytexteditor” doesn’t work, where as “com.ohanaware.myTextEditor” does.

Problem 2: Recent Items list

In order to solve problem 2, we’ll use the “OWRecentItems” class from the Sandbox Kit. It’s a little more complicated than just selecting checkboxes, but not much more complicated.

Add the Sandbox Kit to your Xojo project.

In the “Open” event of the “App” object, add the following line of code

OWRecentItems.installRecentMenu( fileMenu, 1 )

This single line of code will tell the OWRecentItems class to install the recent menu, you pass in the menu on the to add to, and where in the menubar you’d like the “Open Recent” submenu to appear.

For my Text Editor, I added it to the file menu and in position 2.

3. Now all that’s required is when a document is saved or opened, another line of code needs to be called.

OWRecentItems.addToRecentMenu( file )

Simply call the OWRecentItems class again and use the addToRecentMenu method, passing in the Xojo folderitem where the document is being saved. It will be added to the Recent Menu (it’s okay to call it multiple times as it will only list it once).

That’s it. Now the application has a Sandbox safe recent items menu.

Note: Using this code will also add the Recent Item menu to the App’s dock item. It’s also pretty cool in the fact that the Apple Recent Item system work across Sandboxed and un-sandboxed versions.

Problem 3: Re-opening last open documents

There’s a bit more work involved to implement this solution, the great news is once you’ve mastered it for one window, it’s trivial to add to other windows.

1. In your Xojo application, you need to select your document window and click on the “Choose” button next to “Interfaces” in the Xojo inspector.

2. Some new methods will be added to the Window class.

• classIdentifer as string
• restoreData( data as JSONItem )
• storeData as JSONItem

“classIdentifer” is where we return a identifier, to which our restoration service uses to determine what window instance to create when the data is restored. I tend to return the window class name.

Function classIdentifier() As string
  // Part of the OWRestorableWindow interface.
  return "documentWindow"
End Function

“restoreData” is used to populate the controls when restoring the window. For our word processor, we’ll use the code below.

Sub restoreData(data as JSONItem)
  // Part of the OWRestorableWindow interface.
  if data <> nil then
    if data.hasName( "text" ) then TextArea1.text = data.value( "text" )
  end if
End Sub

It’s important to check that the data object isn’t NIL and also to check for each setting (this will help to future proof your application).

“storeData” is the last method to populate in the Window class. For our purposes we’ll use the following code. It will simply store the TextArea into the property “text”.

Note: As we’re using JSONItems to save and restore the data, it’s not designed to contain vast amounts of data and some data types will need to be converted to text before storing.

Function storeData() As JSONItem
  // Part of the OWRestorableWindow interface.
  if me.folderitem <> nil then call saveFile
  Dim r as new JSONItem
  if textArea1.text <> "" then r.value( "text" ) = textArea1.text
  Return r
End Function

It’s important to know that if you’re writing Auto Save files, this is the place to do so. Once Window Restoration is properly configured, the window will never receive the “CancelClose” or “Close” events. Consider this the last place to save the user data.

Modify the Save routine of the window, to store the file into the Window, this is done by using the window.folderitem property.

me.folderitem = f

Note: This is one of the key elements, without this the Window Restoration will not work correctly. The folderitem must be attached to the Window using this method.

Modify your file open routine to also use this property.

3. Now we need to alter the App object.
In the “CancelClose” event of the “App” Object, add the code to store the open windows.

Function CancelClose() As Boolean
OWWindowRestoration.storeOpenWindows
End Function

Note: Once this line is executed, no more code will be executed after it, nor will the application’s “Close”, window “CancelClose” and “Close” events will not fire.

4. The next step is to create a subclass of the “OWWindowRestoration” class, name this class something appropriate (for “My Text Editor”, I used the name “MTERestoration” ).

Add the event “windowByClassIdentifier” and in here is where we create a new instance of our window when requested. Earlier on, I returned “documentWindow” from the Window’s classIdentifer method.

Function windowByClassIdentifier(classIdentifier as string) As window
  select case classIdentifier
  case "documentWindow"
    return new documentWindow
  end select
End Function

5. Back to the “Open” event of the “App” and we ask our subclass to restore windows. For example, this app uses the following code.

Sub Open()
  // --- Initiate the Recent Items Menu.
  OWRecentItems.installRecentMenu( fileMenu, 2 )
  // --- Initate Window Restoration.
  Dim nwrc as new MTERestoration
End Sub

In order to test this, make sure that “Close windows when quitting an app” is unchecked, in the “General” section of “System Preferences”.

Now run the application, leave some windows open, quit the application and re-launch it…

6. Cleaning up
In the final step, we need to restore window positions for files that were auto re-loaded (not just data that is stored). This is done by adding the following line to your file open routine.

OWWindowRestoration.restoreWindowBounds( myNewWindow, fileToOpen )

Replace “MyNewWindow” with the new instance of your window and “fileToOpen” with the file that was opened by the routine. Below is how it’s used in “My Text Editor”.

Sub OpenDocument(item As FolderItem)
  Dim theText as string
  try
    Dim tis as textInputStream = textInputStream.open( item )
    if tis <> nil then
      theText = tis.readAll
      tis.close
      Dim ndw as new documentWindow
      ndw.TextArea1.text = theText
      ndw.contentsChanged = false
      ndw.folderitem = item
      OWRecentItems.addToRecentMenu( item )
      OWWindowRestoration.restoreWindowBounds( ndw, item )
      ndw.show
    end if
  catch err as IOException
    MsgBox "Unable to open the file """ + item.name + """." + EndOfLine + endOfLine + err.message
  End try
End Sub

You may have noticed that your Xojo application is also creating new blank windows, which may be undesirable. This is can be solved by adding a property to the “App” class, name it “blockFirstNewWindow” and make it a boolean. Update the “NewDocument” event to use this new property.

Sub NewDocument()
  if blockFirstNewWindow = false then
    Dim ndw as new documentWindow
    ndw.show
  else
    blockFirstNewWindow = false
  end if
End Sub

Switch back to the “Open” event and add a line of code to set that property to the result of the window restoration code.

Sub Open()
  // --- Initiate the Recent Items Menu.
  OWRecentItems.installRecentMenu( fileMenu, 2 )
  // --- Initate Window Restoration.
  Dim nwrc as new MTERestoration
  blockFirstNewWindow = nwrc.restored
End Sub

Now, if you run the project, create some documents, open some, save others, then quit and re-launch, your app should restore the open documents as they were when the application was quit.

Benefits of using this code

Apart from solving some App Sandbox issues, you’ll also get some additional functionality for free.

• Using the Apple Recent Item system, recent documents are also available from the dock menu.
• The Apple Recent Item system is compatible with both the Sandboxed application and unsandboxed (while everything else is not). Users of either version can swap between the two and still be able to use the Recent Items.
• Using the Window Restoration system will make an application follow and behave more consistently with other applications.
• The Window Restoration system will also add the file icon to the Window titlebar, and if the user control clicks on the file icon, they can see where on the disk the file is located.

What’s included in the Sandbox Kit

• OWRecentItems; Used to implement a Sandbox Safe Recent Items menu
• OWWindowRestoration; The Window Restoration handler
• OWRestorableWindow; A Class Interface adding the functions for Window Restoration
• OW_Sandbox_Kit; A shared module that the Sandbox Kit object require
• OWAppleScript; The preferred method of executing Apple Scripts from within a Sandboxed application
• OWBookmark; A last resort function for storing references to files, use this only if OWRecentItems & OWWindowRestoration cannot solve the issue
• SSBToken; Used by the OWBookmark class to ensure access to a referenced file is closed properly
• OWShell; A Shell subclass that can also use NSTask, the only way to launch embedded “Helper” applications within a Sandboxed application

How to get the Sandbox Kit

The Sandbox Kit is sold via the Ohanaware web site for $99.99.