Author: Mark Szymczyk

Renaming Xcode Projects

Renaming Xcode projects is not intuitive or obvious. If you do it wrong, you can mess up your project. In this article you will learn how to safely rename your app and your project.

Rename the Target to Rename the App

Most of the time when people want to rename their project, what they really want to do is rename their app. By renaming the app target, you can rename the app without having to rename the project.

Select the project from the project navigator to open the project editor and see a list of the app’s targets.

TargetList

To rename a target, select it, press the Return key, and enter the new name. If all you want to do is rename the app, you’re finished.

Renaming the Project

Continue reading if you really want to rename the project. If you look at the screenshot from the previous section, you might think you could rename the project by selecting it and pressing the Return key. But you’ll discover that you can’t change the project name from the project editor.

Use the project navigator to change the project name.

ChangeXcodeProjectName

Select the project file and press Return to change the name. A sheet will open.

RenameProjectSheet

Xcode is initially set to rename all the project’s targets to reflect the new name of the project. Deselect a checkbox next to any item you don’t want to rename. Click the Rename button to rename the project.

Clicking the Don’t Rename button will rename the project file but won’t rename anything else.

How to Notarize a Mac App

Notarizing a Mac app allows it to work better with Apple’s Gatekeeper feature in macOS. If you do not notarize your app, when someone downloads the app and tries to run it, an alert will open saying the app is from an untrusted developer. This alert may make people afraid to run your app. Notarizing your app keeps that alert from appearing and makes it easier for people to run your app. In this article you will learn how to notarize your Mac app so you can distribute it from your own website.

Prerequisites

You must have a paid developer account with Apple to notarize apps.

Your app must have the Hardened Runtime capability enabled to notarize it. Open the project editor and click the Signing & Capabilities button to see if you have enabled the Hardened Runtime capability

Hardened Runtime

High Level Notarization Steps

Take the following steps to notarize your Mac app:

  1. Archive your project in Xcode by choosing Product > Archive.
  2. Open Xcode’s Organizer window by choosing Window > Organizer.
  3. Select your archive from the list of archives.
  4. Distribute the app.
  5. Choose a distribution method.
  6. Choose a destination.
  7. Choose a code signing option.
  8. Review and upload.
  9. Wait for Apple to notarize.
  10. Export the notarized app.

I will go into more detail on Steps 3–10 in the rest of the article.

Finding Your Archive and Distributing

In Xcode 12 the Organizer window looks similar to the following screenshot:

ArchiveListInOrganizer

In the upper left window is a menu with a list of your archived apps. Choose your app from the list. Click the Archives item in the Organizer sidebar to see a list of archives for your app. Select an archive from the list.

Click the Distribute App button on the right side of the Organizer to start the process of notarizing your app.

Choose a Distribution Method

When you click the Distribute App button, a sheet opens with a list of distribution methods.

DistributionMethod

To notarize your app and upload it to your website, you should choose Developer ID. Click the Next button.

Choose a Destination

The next step is to choose a destination.

Destination

There are two destination options: Upload and Export. You must choose Upload to notarize the app. Click the Next button.

At this point, another sheet may appear with a checkbox to receive symbolicated crash reports from Apple. Select that checkbox and click the Next button.

Choose a Signing Option

Apple provides two methods to manage the signing of your app: Automatic and Manual.

SigningOptions

I recommend automatically manage signing. Click the Next button.

At this point you will be asked for your Mac user’s password. Enter it.

Review and Upload

Now you can review options for notarizing the app.

ReviewContent

If you find a mistake, click the Previous button to go back and fix the mistake. When things look good, click the Upload button to upload your app to Apple to notarize.

Wait for Apple to Notarize

If the upload is successful, Apple will send you an email when they finish notarizing the app. Normally notarizing takes 20–30 minutes.

Export the Notarized App

When the app is notarized, a button with the title Export Notarized App appears on the right side of the Organizer. You may need to scroll the window to see the button. Click that button to export the app to a location on your Mac. When you finish exporting, you can upload the app to your website for people to download.

Customizing the About Box in Your Mac App

Every Mac app has an About box, which you can access by choosing AppName > About AppName. For a new Cocoa project, the About box looks similar to the following image:

AboutBoxBefore

How do you customize the About box? Add a file named Credits.rtf to your project. Fill the file with your app credits. When you build the project, the text you entered in the RTF file will appear in a box between the version number and the copyright notice in the About box.

Choose File > New > File in Xcode to add a new file to the project. The RTF File template is in the Resource section.

Select the Credits.rtf file to edit the credits.

CreditsExample

Now build your project and choose AppName > About. Your About box should look similar to the following screenshot:

AboutBoxAfter

If your credits are not appearing in a white scroll view, make sure you make the text long enough to trigger the need for a scroll view. When I just added the developer credit in the screenshot, the Credits appeared without a scroll view, and it didn’t look good.

Working with Open and Save Panels in Mac Apps

My short article on changing the button title for open and save panels gave me the idea to write a longer article on working with open and save panels.

You May Not Need to Deal with Open and Save Panels

Apple’s document architecture gives you a lot of default behavior for free. You can write an app that opens and saves files without having to write any code for the open and save panels. The most common case of having to write code that involves open and save panels is importing and exporting data. For example an image editor would use a save panel to export the image to common file formats, such as GIF, JPEG, and PNG.

Creating the Panel

Creating the open or save panel is the easiest step. Call the constructor for NSOpenPanel or NSSavePanel.

let savePanel = NSSavePanel()

Customizing the Panel’s Appearance

When you create an open or save panel, you get the default appearance, which works well most of the time. But if you’re using a save panel to export a file, you want the button to say Export instead of Save because you’re exporting a file. AppKit provides several ways to customize the appearance of open and save panels. Some of the most popular ways include the following:

  • The prompt property lets you change the text of the default button.
  • The title property lets you change the title of the panel.
  • The nameFieldLabel property lets you change the label text in front of the filename text field.
  • The nameFieldStringValue property lets you set the filename currently shown in the filename text field.
  • The directoryURL property lets you set the current directory for the panel.
  • The accessoryView property lets you add an accessory view. A common use of an accessory view is to show a popup button with a list of file types.
  • The allowedFileTypes property lets you limit the file types you can open or save.

Custom Appearance Example

As an example, I’m going to share the code for a custom save panel for an app I’m developing. In this project I’m using a save panel to publish an EPUB book.

func buildPublishSavePanel() -> NSSavePanel {
    let savePanel = NSSavePanel()
    savePanel.title = "Publish Book"
    savePanel.nameFieldLabel = "Book Name:"
    savePanel.nameFieldStringValue = self.displayName
    savePanel.prompt = "Publish"
    savePanel.allowedFileTypes = ["epub"]
    return savePanel
}

Because the save panel is for publishing books, I changed the panel’s title, name field label, and prompt (button text) to let people know this panel is for publishing books. I’m publishing EPUB books so I’m limiting the file types to files with the pub extension.

The most confusing line of code is the line that sets the text field value to self.displayName. The display name is the filename of the document that I’m publishing.

Showing the Panel

There are two ways to show an open or save panel. The easiest way is to show a panel as a modeless window. Call the panel’s begin method and supply a closure.

savePanel.begin { (result: NSApplication.ModalResponse) -> Void in
    // Code to come later
}

The other way is to show the panel as a sheet inside the document window. Call the panel’s beginSheetModal method. Supply the window and a closure.

savePanel.beginSheetModal(for: window) { 
    (result: NSApplication.ModalResponse) -> Void in {
    // Put your code here
}

Handling the Default Button Click

After showing the panel, you must handle the clicking of the default button (Open for an open panel, Save for a save panel). What you must do is check if the result of the panel running is NSFileHandlingPanelOKButton, which occurs when someone clicks the default button. Usually you will call a function that performs the task you want to do. For example if you were exporting a file, you would call a function that exports the file.

The Full Example

The following code shows the full example of using a save panel to publish a book:

func showPublishSavePanel() {
    let savePanel = buildPublishSavePanel()
        
    savePanel.begin { (result: NSApplication.ModalResponse) -> Void in
        if result.rawValue == NSFileHandlingPanelOKButton {
            if let panelURL = savePanel.url {
                // Replace this code with 
                // a call to a function you wrote.
                publishEPUB(location: panelURL)
            }
        }
    } // End of closure
}

The code begins by calling the buildPublishSavePanel function I wrote earlier to create the save panel and customize how it looks.

The next line of code calls the save panel’s begin method to show the save panel. The closure in the begin method uses a variable, result that stores the result of someone interacting with the save panel.

The first if statement checks if the person clicks the default (Publish) button. If so, the second if statement runs.

The second if statement gets the URL of the location the person chose to store the published book and calls a function to publish an EPUB book at the supplied URL. In your app you would call a function you wrote that creates (examples: importing or exporting a file) a file at the given URL.

Changing the Button Title for Open and Save Panels

Open and save panels are how Mac apps let people open and save files. An open panel defaults to using Open as the text for the main button. A save panel defaults to using Save. The default values make sense, but suppose you want to use an open panel to import a file in your app. How do you change the button text from Open to Import?

Use the prompt property to change the button text. The following example shows how to change the button text in an open panel from Open to Import:

func buildImportOpenPanel() -> NSOpenPanel {
    let openPanel = NSOpenPanel()
    openPanel.prompt = "Import"
    return openPanel
}

Look at the NSSavePanel class reference to see other ways to customize the appearance of save and open panels.

Adding Undo Support for NSTextView

Mac text views support undo and redo for text editing without you having to write any code. All you have to do is set the text view’s allowsUndo property to true, which you can set in the attributes inspector.

NSTextViewAllowUndo

Select the Allows Undo checkbox to turn on the text view’s undo/redo support.

Showing a Sheet When Choosing a Menu Item

VoodooPad is a Mac app for building a personal wiki. When you create a new wiki page in VoodooPad, a sheet opens for you to name the page.

I wanted something similar in one of my Mac app projects that uses storyboards. I created a view controller for the sheet. I added a toolbar button, made a connection to the sheet’s view controller and chose Sheet from the list of available storyboard segues.

One of Apple’s guidelines for Mac user interfaces is that every toolbar button should have a menu item. So I created a menu item to show the sheet and made a connection from the menu item to the sheet’s view controller. But there was no Sheet segue available. The only available segues were Custom, Show, and Modal. How do you show a sheet after choosing a menu item?

Solution Overview

You must perform the following steps to show a sheet from a menu in a Mac app using storyboards:

  1. Give the sheet’s view controller a storyboard ID to identify the view controller.
  2. Add an action to the main view controller that creates an instance of the sheet view controller and presents it as a sheet.
  3. Connect the menu item to the action.

Give the Sheet’s View Controller a Storyboard ID

The sheet’s view controller needs a storyboard ID so you can create an instance of the view controller in your code. Select the sheet’s view controller from the storyboard and open the identity inspector.

ViewControllerStoryboardID

Enter the ID in the Storyboard ID text field. Remember the ID because you will need it when writing the code to show the sheet.

Add an Action to the Main View Controller to Show the Sheet

You must write an action in the main view controller to show the sheet. When someone chooses the menu item, your app performs the action. The main view controller is the controller that shows the window’s content.

The first step is to get the storyboard where the sheet view controller resides. I’m going to assume the main view controller and sheet view controller reside in the same storyboard so I can use the main view controller’s storyboard property to get the storyboard.

After getting the storyboard, call its instantiateController method, supplying the sheet view controller’s storyboard ID. After instantiating the sheet view controller, call the presentAsSheet method, supplying the sheet view controller.

@IBAction func showSheet(_ sender: AnyObject) {
    if let theStoryboard = storyboard,
        let sheetViewController = 
            theStoryboard.instantiateController
                (withIdentifier: "sheetViewControllerID") 
                as? MySheetViewController {

        presentAsSheet(sheetViewController)
    }
}

Connect the Menu Item

The last step is to connect the menu item to the action you wrote to show the sheet. Make a connection from the menu item to the First Responder object in the Application scene. A long list of actions opens. Choose the action you created to show the sheet.

When someone chooses the menu item, your app will call the action you wrote. Calling the action will show the sheet.

Code Signing and the Sparkle Framework

Sparkle is a framework that simplifies updating Mac apps. With Sparkle people can check for updates inside your app. If there is a new version of your app, they can download and install it from your app.

I recently added Sparkle support to an app I’m developing. Sparkle has good setup instructions, but I ran into one issue not covered by their instructions. This article tells the story of me discovering and fixing this issue.

Background Information

Sparkle currently has two branches: a stable version 1 and a beta version 2, which adds support for sandboxed apps. Version 1 has a binary framework and related files that you can download and add to your project. You can also download the Xcode project from GitHub and build the framework yourself. Version 2 must be built from source by downloading the Xcode project.

Sparkle supports CocoaPods, but I chose to download the version 1 binary framework and add it to my project. My app isn’t sandboxed so I didn’t need version 2, and version 1 has much more documentation.

The Problem

I followed the installation instructions on the Sparkle site. I built and run the app, but it kept crashing at launch. The following error message appeared in Xcode’s debug console for the Sparkle framework:

not valid for use in process using Library Validation: mapped file has no Team ID and is not a platform binary

The Team ID is the code signing development team.

Initial Search to Find the Problem

I started my search for a solution by browsing the GitHub issues for the Sparkle project. I did not find any issues similar to the one I found.

The next step was to paste the console error message into a search engine. I found a thread in Apple’s paid developer forums where an Apple engineer said you have to code sign the framework with your code signing identity.

Yes! Code sign Sparkle with my code signing identity, and the problem will go away.

Code Sign Sparkle

I knew I wouldn’t be able to code sign the Sparkle binary framework. I would have to clone the project in Xcode, change the code signing build settings to use my code signing identity, build the framework, and add it to my project.

I wasn’t able to build version 1 from source (compiler errors) but was able to build version 2 so I went with that. I changed the code signing build settings, built the framework, and added it to the project.

The app continued to crash at launch with the same error message in the debug console. What was going on?

The Solution

Some more Internet searching for the error message took me to an article on testing a Swift Package Manager package. A sentence in the article, “To avoid signing issue, we need to select a Team for all frameworks”, led me to the solution.

I did not need to modify any code signing build settings to fix the issue. I had to change the Signing Certificate value for my app target in the Signing & Capabilities section.

SigningTargetSettingsHighlighted

The original Signing Certificate value was Sign to Run Locally. I had to change it to Development.

After changing the Signing Certificate value, I was able to use Sparkle in my app. I was able to use both the binary version 1 framework and the version 2 framework I built from the Xcode project. I ended up using the binary version 1 framework.

It took me several hours to solve the code signing issue. I hope this article keeps someone else from making the same mistakes I made.

Saving Data in a Swift App

People new to iOS development frequently ask how to save data in their apps. Apple provides the following technologies for saving app data on a local device:

  • UserDefaults
  • Keychain
  • Files
  • Core Data

You can use multiple methods to save data in your app. Many iOS and Mac apps use both UserDefaults and Core Data to save data. Use all the methods for saving data that make sense for your app.

UserDefaults

Apple provides a UserDefaults class that provides a programming interface to your app’s defaults database. The defaults database contains user settings and preferences.

Use UserDefaults to store small amounts of data, like settings and preferences. If you are writing a plain text editor, you could store the font to use in UserDefaults.

Keychain

Use the keychain to store small amounts of data securely, such as passwords. If you were writing a Twitter app, you could use the keychain to store the person’s Twitter handle and password.

Apple provides a Keychain Services API for apps to work with the keychain. The documentation is in the System > Security section of Apple’s documentation in Xcode. Choose Help > Developer Documentation in Xcode to read the documentation.

Files

You can use files to store larger amounts of data. Document-based apps, such as text editors, spreadsheets, and drawing apps, usually save their data in files.

Apple provides the Codable protocol to simplify reading and writing data to files. An Internet search for Swift Codable tutorial yields many results, most of which cover JSON.

Core Data

Core Data is Apple’s framework for creating and working with a data model for iOS and Mac apps. One of the things Core Data does is save data for you.

Core Data is a huge subject. People have written books about it. You can find an overview of Core Data in Apple’s documentation in Xcode under App Services. Apple also has a Core Data Programming Guide on their developer website.

Core Data or Files?

Should you use Core Data or files to save larger amounts of data?

Core Data is a powerful framework that does a lot, much more than saving app data. But with that power comes a learning curve.

You must determine if your app’s data needs require Core Data. Avoid Core Data (or at least do some more research before using Core Data) in the following cases:

  • Your app supports non-Apple platforms like Android, Linux, and Windows. Core Data does not run on non-Apple platforms.
  • Your data can easily be saved in one file.
  • Your app data has only one class or struct.
  • You are writing a document-based app. Core Data supports document-based apps, but it doesn’t add much to Apple’s document architecture.

A text editor is an example of a project where you should save your data in a file. The app data is just a bunch of text. The data can easily be saved in one file. Core Data would not help you much.

Use Core Data to save your app’s data in the following cases:

  • You store large amounts of data in the app.
  • The data makes more sense to store in a database than in a single file.
  • Your app data has multiple classes or structs.
  • You are writing a shoebox (not document-based) app.

A blog editor is an example of a project where you should use Core Data. A blog can contain hundreds of posts that would be difficult to store in a file. A blog has multiple pieces of data: titles, tags, categories, and authors. Core Data can do things like show you all the blog posts with a given tag. Take advantage of Core Data if it will help for your app.

If you are still not sure whether or not to use Core Data, use it.

Scrolling an iOS Text View When the Keyboard Appears

A common issue iOS developers run into is dealing with the onscreen keyboard. The keyboard appears and blocks what you’re typing.

The fix is to scroll the text view when the keyboard appears. The code to do this is not too hard. iOS posts a notification when the keyboard appears and when the keyboard disappears. Write a function to handle each notification. Scroll the text view when the keyboard appears and return it to its original position when the keyboard disappears.

Handling the Keyboard Appearing Notification

You must write the function keyboardWasShown. This function gets called when the keyboard appears.

There are two things to do in keyboardWasShown to scroll the text view. First, set the text view’s content inset so the bottom edge is the keyboard’s height. Second, set the scroll indicator insets to the text view’s content inset.

@objc func keyboardWasShown(notification: NSNotification) {
    let info = notification.userInfo
    if let keyboardRect = info?[UIResponder.
        keyboardFrameBeginUserInfoKey] as? CGRect {

        let keyboardSize = keyboardRect.size
        textView.contentInset = UIEdgeInsets(top: 0, left: 0, 
            bottom: keyboardSize.height, right: 0)
        textView.scrollIndicatorInsets = textView.contentInset
    }  
}

Swift functions that work with notifications require the @objc keyword at the start of the function declaration. The userInfo property of the notification contains the rectangle where the keyboard appears on the screen.

Use the keyboard rectangle to get the keyboard’s height. Set the text view’s bottom edge inset to the keyboard’s height. The text view will scroll when the text insertion point gets near the top of the keyboard.

Handling the Keyboard Hiding Notification

You must write the function keyboardWillBeHidden. This function gets called when the person entering text hides the keyboard.

When the keyboard disappears, set the text view’s content inset back to all zeroes. Set the text view’s scroll indicator insets to the text view’s content inset.

@objc func keyboardWillBeHidden(notification: NSNotification) {
    textView.contentInset = UIEdgeInsets(top: 0, left: 0, 
        bottom: 0, right: 0)
    textView.scrollIndicatorInsets = textView.contentInset
}

Example Project

I have a text editor project on GitHub to see the keyboard handling code in practice.