Filetypes and UTIs

@IBOutlet weak var inputFld: NSTextField!

@IBOutlet weak var outputLabel: NSTextField!

@IBAction func saveStuff(_ sender: NSButton) {
let savePanel = NSSavePanel()
savePanel.isExtensionHidden = false
savePanel.canSelectHiddenExtension = true
savePanel.allowedFileTypes = ["unicorn"] let userChoice = savePanel.runModal()
switch userChoice {
case .OK:
if let panelResult = savePanel.url {

//1) Saving a string to file
saveString(to: panelResult)
}
case .cancel:
print("saving cancelled")
default:
break
}
}

@IBAction func loadStuff(_ sender: NSButton) {
let openPanel = NSOpenPanel()
let userChoice = openPanel.runModal()
switch userChoice{
case .OK :
if let panelResult = openPanel.url {

//1) Loading a string from file
loadString(from: panelResult)

}
case .cancel :
print("user cancelled")
default:
break
}
}

func saveString(to saveURL: URL){

let myString = inputFld.stringValue
print(myString)
do {
try myString.write(to: saveURL, atomically: true, encoding: .utf8)
// most basic encoding; used here to allow the file to be read more easily by almost any text processing app
} catch {
print(error)
}
}

func loadString(from loadURL: URL){

do {
let myUnicorn = try String.init(contentsOf: loadURL)
outputLabel.stringValue = myUnicorn
} catch {
print(error)
}
}

1a) The next step modifies your application’s info.plist, but I’ve had no luck actually changing values there – you need to go through Target: Info and add a document type.

Name, identifier, extensions should be self-explanatory. Class does not apply here (we’re not working with NSDocument), we’re not messing with mime types. Role should be ‘Editor’ rather than ‘Viewer’.

While this example by Apple asks you to add CFBundleTypeRole as an additional property, that is the ‘Role’ above, so you can skip that step; LSHandlerRank, on the other hand, should be set to ‘Owner’ (we’re the primary creator and handler of unicorns).

You can ignore pasteboard type (up to 10.5) and mime type. If you’re using an NSDocument-based application, you need to specify your subclass of that in the ‘Class’ setting.

1b) For Exported UTIs, you want to fill out all of the obvious items: description, extensions, identifier, (leave icon alone for now, that one is more complicated than it looks at first, we deal with it later), and find the right value for ‘conforms to’. In this case, because we’re saving strings, it’s public.text; for a customary file format with our own objects, it would be public.data.

You need to add an additional property: UTTypeTagSpecification (this does not autocomplete). Change it to a Dictionary, and add a row: public.filename-extension, which needs to be an array; add one row to it, which is a String: unicorn.

If you have all of these set correctly, where ‘correct’ = ‘as detailed in the documentation linked above’, your app will finally move from

to

As you may guess from the filename, at this point I had tried this several times, checked and double-checked and disregarded the first tutorial to google again, and we have _partial_ success: the Finder knows that unicorns belong to my UTI Creation app.

1c) We’ll ignore imported UTIs, though they are a neat feature: if your application handles an uncommon filetype belonging to another application – say, WordPerfect files (.wp, .wpd), and you don’t expect that application to be present on users’ computers (AFAIK, there is no current version or variant of WordPerfect that will run on macOS), but you still want users to be able to see in the Finder that they can open the file in your app, you can define an _imported UTI_. This means you won’t save (export) that format, but you can open (import) it.

2) The problem of opening files is quite interesting in itself. Right now, our app does not have a concept of ‘opening files’. It has a method that can be pointed at a URL and which does things with that URL, but it does not have an entry point for ‘opening files’, so when the FileManager asks our app ‘can you open this file’ it just goes ‘huh?’.

2a) Luckily for us, the AppDelegate protocol defines such a method:

func application(_ sender: NSApplication, openFile filename: String) -> Bool

This function should call on whatever function you use to open a file. If you’re using URLs in your app, convert it using URL(fileURLWithPath: filename)

One would expect, to be a good citizen, that you should return ‘true’ only when you actually opened the file, as opposed to ‘trying to open a file with the right extension’. Given how many unicorns are running around since the ‘Saving Files with Codable‘ tutorial, many with different contents (there are Strings, and NSCoding compliant, and Modern unicorns… ) this seems like a good idea. However, this ideal runs up against Swift error handling: while you can attempt return a value from the catch part of a do–try–catch block, it gets ignored; so the only thing I have found that’s possible here is to return ‘true’ whatever happens.

func application(_ sender: NSApplication, openFiles filenames: [String]) works in exactly the same manner as the single file variant, with the slight quirk that it overrides the single filename version, so you either the single filename version gets called several times in succession or you always call the multiple filenames function even if you only open one file and the other remains unused.

Why am I emphasizing ‘filename’ so much? It turns out that there is a
func application(_ application: NSApplication, open urls: [URL])
function coming up in code completion, (without a matching open url function); but using _that_ in your application gets us back to the _UTI Creation cannot open files in the “unicorn” format_ error we had before implementing application(openFile:). Turns out that the compiler was slightly asleep here: the documentation offers no advice on this method whatsoever, but tells you it’s available in 10.13+. If you’re working on 10.13, you should use the URL-based version instead of a path(string-) based method.

2b) Of interest may be two other points: an ‘untitled file’ is a new, untitled file, while ‘temporary file’ is a new file that the application is supposed to clean up (similar to opening files shared from e-mail on iOS?). I’m not certain what the use cases are. According to this StackoverflowDiscussion from 2012, the behaviour for untitled files has changed in Lion (macOS 10.7); as far as I can make out applications created (or not) new, untitled files on startup; but with the restoration of apps, it can happen that you simply re-open the new untitled document you opened the last time you opened the app, rather than creating a new one, so this method will not get called every time you start up the app. Or something. (This seems relevant only for document-based apps, and when I get around to those, I might play with this function again). Other than that, Google has returned one page of links to Apple’s documentation with a single mention elsewhere which is simply a listing of functions without explanation of what they do, so that’s gonna be a fun rabbit hole when the time comes.

3) We’re nearly there. We can now double-click files in the finder (or drag them onto the application’s dock tile, or choose ‘open’), and the Finder Info says that our app is the default app for opening .unicorn files. What we haven’t got yet is an icon for our files. This is not as straightforward as one might hope: there are fairly strict rules for icons. In fact, the rules for File icons are the same as those for Application icons – both used by the Finder – but while you can create your app icons and drop them into your Assets catalogue, this was only enabled in 10.13 for file icons (and thus, I haven’t tested it yet.) For 10.12 or lower, you need to create a special folder containing all of your resolutions.

3a) First, hunt your unicorn. Find a unicorn, ideally with a white or transparent background, with a size of 1024x1024px, and save it in .png format. (Feel free to borrow for your experiments. Don’t use it in a commercial project.)

3b) Next, transform your image to the correct sizes and give them the correct names, as stated in the Human Interface Guidelines. This involves Retina (2x) as well as standard files, so
icon_16x16.png
icon_16x16@2x.png
…

The reason for having separate 1x and 2x resources (and five steps instead of a single icon to scale up and down) is that this allow for highly detailed large images and simplified smaller icons. Instead of having to rely on the computer to scale, you can have, say, a single-hue 16×16 icon (where only the outline matters), and add a second hue and more definition to your larger version.

Personally, I’ve used the Free AppIcon Generator (free in the Appstore) to generate my icon sets; but I have to warn that it will generate an OSX.iconset from your image and ruthlessly overwrite any previous OSX.iconset in the same folder, so you want to give each one a sepate location.

Rename the folder (unicorn.iconset), right-click on it in the Finder and choose ‘quicklook’. This now gives you the chance to preview the icon in any size you like, or to seamlessly change the size and view the results. (If you’ve created it from a single large image, this is not overly interesting.)

You can add an imposter to your set: replace one unicorn with a kitten, and watch it scale from 1pt above the previous size to its nominal size, which tells us how the system handles scaling: 17-32pt uses icon_32x32.png, etc.

3c) Add your unicorn.iconset into your project and in both the document types and Exported UTI settings set the icon name for .unicorn files to unicorn. It should immediately show up in the settings; if the imageWell remains blank, check that you typed the iconset name correctly. (There is no autocomplete for this).