Swift Dev Journal

Composing Parsers with the swift-parsing Library

Wed, 11 Mar 2026 13:19:03 -0500

One of the selling points of the swift-parsing library is that you can create small parsers that do one simple thing and combine them to parse more complex data. This article shows how to combine smaller parsers to create a larger parser.

Creating a parser

A swift-parsing parser is a struct that conforms to the Parser protocol. Conform to the protocol by creating a body property that returns a parser that conforms to Parser.

public struct ParserName: Parser {
  public var body: some Parser<T, U> {

  }
}

Notice that the struct and the body property have public access. The swift-parsing library requires public access to parse the data. If you forget to add public, you will get build errors.

The T type is the input type the parser takes. Most parsers use the Substring type as the input type. If you are parsing lots of data and require maximum performance, use UTF8View as the input type. The examples in this article use substrings.

The U type is the output type the parser returns. The return type can be a simple type, such as an integer or Boolean value, or it can be more complex, such as one of your app’s structs or classes.

Parsing example

The example in this article parses the output of the Jujutsu version control system’s jj show command that shows details of a change. A Jujutsu change is similar to a git commit. The output of the jj show command looks similar to the following text:

Commit ID: 73d31d1766b0bc211d22b87f2f911429f3846a61
Change ID: lyrzonnxolkpxytwwykkqpvvlqmvlxqm
Author   : Bob Ducca <ducca@example.com> (2025-06-23 18:04:09)
Committer: Bob Ducca <ducca@example.com> (2025-06-23 18:04:49)

  Add sentence that you have to set a bookmark and push.
  
  Add a paragraph so the change description has multiple paragraphs, which is good for unit testing change descriptions.

Modified regular file GitHub.md:
    ...
   4    4: 
   5    5: ## Working with Existing GitHub Repo
   6    6: 
   7    7: In most cases you have an existing GitHub repo. This is what you do.
        8: 
        9: You have to set a bookmark and call `jj git push`.

The Change struct stores the change information.

public struct Change {
  var changeId: String
  var author: String
  var timestamp: String
  var description: String
}

Parsing the change ID

Parsing the change ID involves the following steps:

Skip everything through the text Change ID:.
Skip any additional whitespace.
Capture everything up to the end of the line.

public struct ChangeId: Parser {
  public var body: some Parser<Substring, 
    Substring> {
    
    Skip {
      PrefixThrough("Change ID:")
      Whitespace()
    }
    // Capture everything until the next whitespace.
    PrefixUpTo("\n")
  }
}

Parsing the author

Parsing the author requires the following steps:

Skip everything through the text Author.
Skip whitespace.
Skip the colon.
Skip more whitespace.
Capture everything up to the < character, which marks the start of the author email address.

public struct ChangeAuthor: Parser {
  public var body: some Parser<Substring, 
    Substring> {
    
    Skip {
      PrefixThrough("Author")
      Whitespace()
      ": "
    }
    // Capture everything until the start of the email address.
    PrefixUpTo(" <")
  }
}

Parsing the timestamp

The timestamp looks like the following:

(2025-06-23 18:04:09)

Parsing the timestamp involves the following steps:

Skip everything through the first left parenthesis.
Capture everything up to the next right parenthesis.

public struct ChangeTimestamp: Parser {
  public var body: some Parser<Substring, 
    Substring> {
    
    Skip {
      PrefixThrough("(")
    }
    PrefixUpTo(")")
  }
}

Parsing the change description

The change description starts after the first blank line. The description ends with a blank line and one of the following phrases:

Modified regular file
Added regular file
Removed regular file

Start by writing a parser for each possible end of a description.

let modifiedFile = Parse {
  PrefixUpTo("\n\nModified regular file")
}

let addedFile = Parse {
  PrefixUpTo("\n\nAdded regular file")
}

let removedFile = Parse {
  PrefixUpTo("\n\nRemoved regular file")
}

Use the OneOf parser to capture everything until you reach one of the possible ends of the description. Use the Rest() parser as a fallback if you hit the end of the text before reaching one of the possible description ends.

public struct ChangeDescription: Parser {
  public var body: some Parser<Substring, 
    Substring> {
    
    let modifiedFile = Parse {
      PrefixUpTo("\n\nModified regular")
    }

    let addedFile = Parse {
      PrefixUpTo("\n\nAdded regular")
    }

    let removedFile = Parse {
      PrefixUpTo("\n\nRemoved regular")
    }

    // Skip everything to the first blank line and any whitespace after the blank line.
    Skip {
      PrefixThrough("\n\n")
      Whitespace()
    }

    // Capture everything up to one of the phrases that marks the end of a description.
    OneOf {
      modifiedFile
      addedFile
      removedFile
      Rest()
    }
  }
}

Composing a change parser

The last part is to build a change parser that runs the parsers for each piece of the change and returns a Change instance.

The tough part is building the Change instance. Each of the smaller parsers returns a string. How do you build a Change instance from a group of strings?

Add a local variable for the change to the body property. After running each parser, add a map modifier and supply a closure to fill the change’s property with the output from the parser. Return the local variable after running the parsers.

public struct ChangeParser: Parser {
  public var body: some Parser<Substring, 
    Change> {
    
    let change = Change()
    
    Parse {
      ChangeId()
        .map { id in
          change.changeId = String(id)
        }
      ChangeAuthor()
        .map { author in
          change.author = String(author)
        }
      ChangeTimestamp()
        .map { time in
          change.timestamp = String(time)
        }
      ChangeDescription()
        .map { message in
          change.description = String(message)
          return change
        }
    } // End Parse block
  } // End body
    
}

Measure App Launch Time with Instruments

Tue, 10 Feb 2026 12:34:53 -0500

Take the following steps to measure your app’s launch time with Instruments:

Press Cmd-I or choose Product > Profile to profile your app.
Select the App Launch template when Instruments launches.
Click the Choose button.
Click the Record button to start profiling.
Select the item with the name of your app from the timeline pane.
Press Cmd-4 to open the App Lifecycle section.

The App Lifecycle section lists the app’s launch steps and how long each step took.

Do you want to learn more about Instruments?

I wrote a book, Profiling Swift Apps, that shows you how to use Instruments to find and fix problems in your code. The book will help you make apps that run faster and use less memory. You can learn more about the book and download a sample at the following link:

Profiling Swift Apps page

Add an Open Recent Menu to a SwiftUI app

Thu, 05 Feb 2026 14:00:00 -0500

Why would you need to add an Open Recent menu? The most common reason is you created an app that doesn’t use the document architecture, and you want a way for your app’s users to access recent items.

Adding an Open Recent menu requires you to do the following things:

Use the NSDocumentController class to track recent items.
Add an @Observable class to hold the recent items so SwiftUI can update the Open Recent menu when its contents change.

Using `NSDocumentController` to track recent items

The name NSDocumentController implies that it works with NSDocument. However, the parts of NSDocumentController that deal with the Open Recent menu require only an array of URLs. You can use NSDocumentController without creating a document app.

Use the shared instance to access the standard document controller.

NSDocumentController.shared

Use the recentDocumentURLs property to access the URLs of the recent items and fill the Open Recents menu. Call the noteNewRecentDocumentURL function to update the recent items after opening or creating an item. Call the clearRecentDocuments function to clear the recent items list and clear the Open Recent menu.

An initial version of an Open Recent menu looks like the following code:

struct OpenRecentMenu: View {
  @Environment(\.openWindow) private var openWindow
    
  var body: some View {
    Menu("Open Recent") {
      ForEach(NSDocumentController.shared.
        recentDocumentURLs, id: \.self) { url in
        
        Button(url.lastPathComponent) {
          // Item is a class in your app.
          let itemToOpen = Item(location: url)
          openWindow(value: itemToOpen)
          NSDocumentController.shared.
            noteNewRecentDocumentURL(url)
        }
      }
            
      Divider()
        Button("Clear Menu") {
          NSDocumentController.shared.
            clearRecentDocuments(nil)
        }
    }
  }
}

The code creates the Open Recent menu and fills it with recent items. There is one big problem. The Open Recent menu doesn’t update until you restart the app.

The reason the menu doesn’t update is SwiftUI doesn’t automatically update the menu when the shared document controller’s array of recent items changes.

To get the menu to update, you must add an @Observable class that holds the recent item URLs and pass that class to the menu view.

Create the `@Observable` class

The class has two requirements. First, it needs a property that holds the URLs of the recent items. Second, it needs a function to update the array from the shared document controller.

@Observable
class RecentItems {
  @MainActor static let shared = RecentItems()
  var items: [URL] = []
  
  init(items: [URL]) {
    self.items = items
  }
    
  @MainActor func refresh() {
    let docControllerRecents = NSDocumentController.
      shared.recentDocumentURLs
    if docControllerRecents != items {
      items = docControllerRecents
    }
  }
}

Supply the value NSDocumentController.shared.recentDocumentURLs to the RecentItems initializer to fill the Open Recent menu when your app launches.

When you open or add an item in your app, call the refresh function to update the Open Recent menu.

Add the `@Observable` class to the Menu

To use your @Observable class in the menu, you must add a @State property for the class to the App struct. Pass the value to the menu using a binding. Use the array in your @Observable class to fill the Open Recent menu.

The following code shows the updated Open Recent menu:

struct OpenRecentMenu: View {
  @Environment(\.openWindow) private var openWindow
  @Binding var recents: RecentItems
    
  var body: some View {
    Menu("Open Recent") {
      ForEach(recents.items, id: \.self) { url in
        Button(url.lastPathComponent) {
          let item = Item(location: url)
          openWindow(value: item)
          NSDocumentController.shared.
            noteNewRecentDocumentURL(url)
          recents.refresh()
        }
      }
            
      Divider()
        Button("Clear Menu") {
          NSDocumentController.shared.
            clearRecentDocuments(nil)
          recents.refresh()
        }
      }
  }
}

Supporting SwiftUI Sidebar Selection with Multiple Data Types

Tue, 06 Jan 2026 13:29:32 -0500

When handling the sidebar selection in a SwiftUI app, the usual approach is to add a @State property to the view to store the selection. The code looks similar to the following code:

@State private var selection: Chapter? = nil

The usual approach works well if all the items in the sidebar have the same data type. What do you do if the sidebar items have different data types?

Supporting selection with multiple data types involves the following tasks:

Create an enum for the sidebar selection.
Use the enum you create as the data type for the selection.
Add a .tag modifier to each list item that holds the item’s data type and value.

Creating the enum

Create an enum for the sidebar selection with a case for each possible data type a sidebar item can have.

As an example I’m going to show code for an app I’m currently making, a Mac GUI client for the Jujutsu version control system. The app’s sidebar has multiple items for controlling what appears in the list of changes (commits). The selection can be either a change category (all changes, mutable changes, my changes) or a bookmark (branch). Selecting a bookmark shows its changes.

The following code shows the enum for the sidebar selection:

enum SidebarSelection: Hashable, Sendable {
  case change(category: ChangeCategory)
  case bookmark(bookmark: Bookmark)
}

enum ChangeCategory: CaseIterable {
  case allChanges
  case mutableChanges
  case myChanges
    
  func stringValue() -> String {
    switch(self) {
    case .allChanges:
      return "All Changes"
    case .mutableChanges:
      return "Mutable Changes"
    case .myChanges:
      return "My Changes"
    }
  }
}

struct Bookmark: Equatable, Hashable, Codable, Sendable {
  // Other properties removed for clarity.
  var name: String
  
  static func == (lhs: Bookmark, rhs: Bookmark) -> Bool {
      lhs.name == rhs.name
  }
}

Using the enum for the selection

In the sidebar view, add a property to store the selection. The data type is the enum you created.

@State private var selection: SidebarSelection?

Adding the .tag modifier

Each list item in the sidebar needs a .tag modifier so SwiftUI knows what the item represents. The value of the modifier is one of the sidebar selection enum’s cases. You must also supply any additional data the enum case requires.

The following code shows a sidebar list with sections for change categories and bookmarks:

List(selection: $selection) {
  Section(header: Text("Changes")) {
    ForEach(ChangeCategory.allCases, id:\.self) { category in
      Text(category.stringValue())
        .tag(SidebarSelection.change(category: category))
    }
  }

  Section(header: Text("Bookmarks")) {
    ForEach(bookmarks, id:\.name) { bookmark in
      Text(bookmark.name)
        .tag(SidebarSelection.bookmark(bookmark: bookmark))
    }
  }
}

Introduction to the Swift Subprocess Package

Mon, 29 Dec 2025 13:12:41 -0500

The Swift language group’s Subprocess package lets you spawn processes in Swift apps. The package makes it easier to run Terminal commands and launch command-line programs from Swift apps.

Launching a program

Call the run function to launch a process. In most cases a process will be a Terminal command, a shell script, or a command-line program.

The run function is asynchronous so you must add await when calling run. The function can throw errors so you should wrap the call in a do-catch block to handle errors.

If the program to run is installed on the user’s computer, use the .name parameter and supply the name of the program to run. You must also supply an output argument to specify how to store the output.

The following code runs the ls command and collects its output in a string:

do {
  let result = try await run(.name("ls"), 
    output: .string(limit: 2048))
} catch {
  print(error)
}

Use the standardOutput property from the result to access the program’s output.

Launching a program from a Mac app bundle

If you bundle a command-line program with a Mac Swift app, you can’t use .name to run the program because the program isn’t installed on the user’s Mac. You must use the .path parameter and supply a path to the program’s location. If you have a URL for the program, use its path property as the path.

The following code runs a program in the app bundle named MyProgram:

var executableLocation: FilePath

let bundle = Bundle.main
let resourceFolder = bundle.resourceURL
let executableURL = resourceFolder?.appendingPathComponent("MyProgram")
executableLocation = FilePath(executableURL?.path(percentEncoded: false) ?? "/")

do {
  let result = try await run(.path(executableLocation), 
    output: .string(limit: 2048))
} catch {
  print(error)
}

Passing arguments

Many Terminal commands and command-line programs take arguments. To pass these arguments to the run function, add an arguments parameter to the run function and supply the arguments.

arguments: ["arg1", "arg2", "arg3"]

The Subprocess package has an Arguments data structure for the arguments. If you create a variable to hold a program’s arguments, make sure its data type is Arguments and not an array of strings.

Setting the working directory

If you need to set the working directory for a program, add a workingDirectory argument to the run function and supply the working directory.

The workingDirectory argument takes a FilePath instance, not a URL. If you have a URL, use the URL struct’s path function to get a file path.

var currentFolder: URL
var workingDirectory: FilePath

workingDirectory = FilePath(currentFolder.path(percentEncoded: false))

Output options

The examples so far have returned the output as a string. You must specify a length limit for the string. Make sure you set a high enough limit. If the output’s length exceeds the limit, the run function returns no output.

Other output options include the following:

A Data object
A file descriptor
An array of bytes

Returning error messages

If you need to return an error message if the program runs unsuccessfully, add an error argument to the run function. The data type for the error message can be one of the output option types: string, Data object, file descriptor, or array of bytes.

error: .string(limit: 2048)

Use the standardError property from the result to access the error message.

Supplying input

If you need to supply input to a program, add an input argument to the run function. You can supply the following kinds of input:

A string
A Data object
A file descriptor
An array of bytes
A data sequence
An async data sequence

// content contains the input string
input: .string(content)

Check if a program ran successfully

To see if the program ran successfully, check the terminationStatus property of the result. The isSuccess property returns true if the program ran successfully.

if result.terminationStatus.isSuccess {
  // Success
} else {
  // Failure
}

A more complex example

The following function runs the Jujutsu version control system command jj bookmark list:

func runListBookmarksCommand(repoFolder: URL) async -> Result<String, JujutsuError> {
  do {
    let result = try await run(
      .name("jj"),
      arguments: ["bookmark", "list"],
      workingDirectory: FilePath(repoFolder.path(percentEncoded: false)),
      output: .string(limit: 8192),
      error: .string(limit: 8192)
    )
    
    if result.terminationStatus.isSuccess {
      return .success(result.standardOutput ?? "")
    } else {
      return .failure(JujutsuError(message: result.standardError ?? "Error"))
    }
    
  } catch {
    return .failure(JujutsuError(message: error.localizedDescription))
  }
}

struct JujutsuError: Error, Equatable {
  var message: String = ""
}

Reducing the Number of .sheet Modifiers in Your SwiftUI Views

Mon, 15 Dec 2025 14:07:01 -0500

Showing sheets is something most SwiftUI apps do. The most common way to show sheets is to have the following items in a SwiftUI view:

A @State property in the view that determines whether to show the sheet.
Code to set that property to true from the UI.
A .sheet modifier to show a view in a sheet.

@State private var showSheet = false

Button {
  showSheet = true
} label: {
  Label("Add Page", systemImage: "plus")
}

.sheet(isPresented: $showSheet) {
  AddPageView()
}

This way of showing sheets works well if your app shows one or two sheets in a view. If your app shows more sheets in a view, you wind up with a @State property and a .sheet modifier for each sheet your app can show. Add enough sheets, and your code becomes a mess.

You can reduce the number of Boolean sheet showing properties and .sheet modifiers by doing the following:

Create an enum for the sheets you want to show.
Create a sheet view to show the correct sheet based on the enum you create.
Create a focused value to show sheets from menu items.

Creating an enum for the sheets

Create an enum with one case for each sheet your app shows. The enum should conform to the Identifiable and Hashable protocols.

enum Sheet: Identifiable, Hashable {
  case addBookmark
  case addChange
  case addRemote
  case editChangeDescription
  case push
  case clone
  
  var id: Self { self }
}

Creating a sheet view

Start by creating a SwiftUI view. Add a constant that lets the sheet view know what sheet to know. The type for the constant should be the enum you created. In the body property, write a switch statement on the enum to show the correct sheet.

struct SheetView: View {
  let sheet: Sheet
  
  var body: some View {
    switch sheet {
    case .addBookmark:
      AddBookmarkView()
    case .addChange:
      AddChangeView()
    case .addRemote:
      AddRemoteView()
    case .editChangeDescription:
      EditDescriptionView()
    case .push:
      PushView()
    case .clone:
      CloneView()
    }
  }
}

Creating a focused value

If you want to show sheets from menu items, you must create a focused value that stores the sheet to show. Add an extension to the FocusedValues struct to create the focused value property. The type of the focused value should be an optional binding to the enum you created.

extension FocusedValues {
  @Entry var sheetToShow: Binding<Sheet>?
}

The @Entry macro supports iOS 18+ and macOS 15+.

In the views for your menu items that show sheets, add a @FocusedValue property so you can set the sheet to show.

@FocusedValue(\.sheetToShow) private var sheet

In your menu’s UI code, set the sheet property’s wrapped value to the enum for the sheet you want to show.

Button(action: {
  sheet?.wrappedValue = .clone
}, label: {
  Text("Clone")
})

Showing a sheet

To show a sheet from a SwiftUI view, you must do the following:

Add a @State property to store the sheet to show.
Add a .focusedSceneValue modifier if you want to show sheets from menus.
Set the sheet to show from the view’s UI.
Add a .sheet modifier to show the sheet.

Add `@State` property

Add a @State property to the SwiftUI view to store the enum for the sheet to show.

@State private var sheetToShow: Sheet? = nil

The type must be an optional value so you can pass the sheet enum to the .sheet modifier.

Add `.focusedSceneValue` modifier

If you are showing sheets from menus, add a .focusedSceneValue modifier to the view. The modifier takes two arguments. The name of the first argument must match the name of the variable you added as a FocusedValues extension. The second argument is a binding to the @State property you added to the view.

.focusedSceneValue(\.sheetToShow, $sheetToShow.safeBinding(defaultValue: .addChange))

The safeBinding function is an extension to convert an optional binding to a non-optional binding. The .focusedSceneValue modifier cannot accept a binding to an optional value so you must convert the sheetToShow value to a non-optional value.

extension Binding {
  // Convert an optional binding to a non-optional one.
  func safeBinding<T: Sendable>(defaultValue: T) -> Binding<T> where Value == Optional<T> {
      
    Binding<T>.init {
      self.wrappedValue ?? defaultValue
    } set: { newValue in
      self.wrappedValue = newValue
    }
  }
}

The code for the safeBinding function comes from the Stack Overflow question Converting optional Binding to non-optional Binding.

Set the sheet to show

Set the sheet to show from the view’s UI.

Button(action: {
  sheetToShow = .push
}, label: {
  Label("Push", systemImage:"square.and.arrow.up")
}).accessibilityLabel("Push Changes")

Add `.sheet` modifier

Finally add a .sheet modifier to the view and pass a binding to the @State property as the item argument. Show the sheet view inside the closure. The argument you pass to the closure contains the enum value that tells the sheet view what sheet to show.

.sheet(item: $sheetToShow) { sheet in
  SheetView(sheet: sheet)
}

Azam Sharp wrote the article Global Sheets Pattern in SwiftUI that covers how to show global sheets in SwiftUI apps. Azam’s article focuses more on iOS and using environment values while this article focuses more on Mac and focused values. His article also shows how to support older OS versions that don’t support the @Entry macro.

Find the SwiftUI Views that Update the Most Using Instruments

Mon, 03 Nov 2025 12:44:02 -0400

When profiling a SwiftUI app with Instruments, one thing you want to know is what views update the most. If a view updates more than you expect, you want to know what causes the updates. In this article you will learn how to use the SwiftUI instrument to find the views in your app that update the most and find what triggers view updates.

This article uses the new SwiftUI instrument Apple added in Xcode 26. If you are using an earlier version of Xcode, read the following article:

See How Many Times Your SwiftUI Views Redraw Using Instruments

Profile your app

Take the following steps to profile your app with the SwiftUI instrument:

Go to Xcode.
Press Cmd-I or choose Product > Profile to build your project and launch Instruments.
Choose SwiftUI from the template list.
Click the Choose button.
Click the Record button above the sidebar to start profiling.
Click the Stop button when you are finished.

Find the views that update the most

Use the all updates summary to find the views that update the most. Instruments should show the all updates summary when you stop profiling, but if you don’t see it in the detail view, press Cmd-1 or choose Summary: All Updates from the jump bar menu.

The SwiftUI instrument’s all updates summary shows the following statistics for the views in your app:

Number of updates
Total update time
Shortest update
Longest update
Average update time

Take the following steps to find the views that update the most:

Click the disclosure triangle next to the name of your app to see the app’s modules.
Click the disclosure triangle next to your app’s module to see a list of your app’s views.
Click the Count column heading to sort the views by update count so you can see what views update the most.

Find what causes a view to update

Use the cause and effect graph in the SwiftUI instrument to find the cause of view updates. Take the following steps to show the cause and effect graph for a view:

Move the pointer over a view in the all updates summary.
Click the small button that appears next to the name of the view.
Choose Show Cause & Effect Graph.

The cause and effect graph looks similar to the following screenshot:

The graph consists of a collection of nodes with arrows showing the flow of events. Graph nodes for your code are blue. System-defined nodes are gray.

Initially the graph is focused on the view you selected from the summary. The nodes to the left of the view show the events that trigger the view update. The nodes to the right of the view show the effects of the view update.

To figure out what triggers an update, move left along the graph until you find other blue nodes. The most common cause of view updates is data updates. When the data the view shows changes, the view updates.

If you are not seeing any nodes to the left of a particular node, move the pointer over the node to show one or two buttons at the top of the node.

Clicking the left button toggles showing and hiding the nodes to the left of the selected node. If no buttons appear, you reached the end of a path.

Do you want to learn more about the SwiftUI instrument?

I wrote a book, Profiling Swift Apps, that shows you how to use Instruments to find and fix problems in your code. The book has a chapter on using the SwiftUI instrument to find problems in your SwiftUI code. You can learn more about the book and download a sample at the following link:

Profiling Swift Apps page

Swift-Parsing Library Introduction

Mon, 13 Oct 2025 14:54:57 -0400

The swift-parsing library helps Swift developers parse data. Outside of the library documentation, there isn’t a lot of material on using the library so I am sharing what I learned using swift-parsing in an app I’m developing.

Example

The example in this article parses the output of the Jujutsu version control system’s jj show command that shows details of a change. The output of the jj show command looks similar to the following text:

Commit ID: 73d31d1766b0bc211d22b87f2f911429f3846a61
Change ID: lyrzonnxolkpxytwwykkqpvvlqmvlxqm
Bookmarks: trunk@origin
Author   : Bob Ducca <ducca@example.com> (2025-06-23 18:04:09)
Committer: Bob Ducca <ducca@example.com> (2025-06-23 18:04:49)

  Add sentence that you have to set a bookmark and push.
  
  Add a paragraph so the change description has multiple paragraphs, which is good for unit testing change descriptions.

Modified regular file GitHub.md:
    ...
   4    4: 
   5    5: ## Working with Existing GitHub Repo
   6    6: 
   7    7: In most cases you have an existing GitHub repo. This is what you do.
        8: 
        9: You have to set a bookmark and call `jj git push`.

The Change struct stores the change information.

struct Change {
  var changeId: String
  var author: String
  var timestamp: String
  var description: String
}

The rest of the article covers how to use swift-parsing to parse the jj show command output into the fields of the Change struct.

Parsing the Change ID

The change ID looks like the following:

Change ID: lyrzonnxolkpxytwwykkqpvvlqmvlxqm

Parsing the change ID involves the following steps:

Skip everything through the text Change ID:.
Skip any additional whitespace.
Capture everything up to the end of the line.

Use the Skip parser to skip text. Use the PrefixThrough parser to go through a certain substring. Use the Whitespace parser to go through whitespace. The following code performs the first two steps:

Skip {
  PrefixThrough("Change ID:")
  Whitespace()
}

The following code performs the third step:

PrefixUpTo("\n")
  .map(String.init)

Let’s show the whole code to create the parser to parse the change ID.

let changeInfo = Parse {
  Skip {
    PrefixThrough("Change ID:")
    Whitespace()
  }
  
  PrefixUpTo("\n")
    .map(String.init)
}

The parsers in the swift-parsing library return Swift substrings. The .map line in the code listing converts the parser output into a Swift string.

The last thing to do is to get the change ID into the Change struct. Call the parser’s parse function to get the change ID. Supply the string for the parser to parse. The parse function can throw errors so you must wrap the call in a do-catch block.

do {
  changeId = try String(changeInfo.parse(commandOutput))
} catch {
  print(error)
}

Parsing the Author

The author looks like the following:

Author   : Bob Ducca <ducca@example.com> (2025-06-23 18:04:09)

Parsing the author requires the following steps:

Skip everything through the text Author.
Skip whitespace.
Skip the colon.
Skip more whitespace.
Capture everything up to the < character, which marks the start of the author email address.

let authorInfo = Parse {
  Skip {
    PrefixThrough("Author")
    Whitespace()
    ":"
    Whitespace()
  }
  // Capture everything up to the start of the email address.
  PrefixUpTo(" <")
    .map(String.init)
}

The following code gets the author into the Change struct:

do {
  author = try String(authorInfo.parse(commandOutput))
} catch {
  print(error)
}       }

Parsing the Timestamp

The timestamp looks like the following:

(2025-06-23 18:04:09)

Parsing the timestamp involves the following steps:

Skip everything through the first left parenthesis.
Capture everything up to the next right parenthesis.

Code:

let timestampInfo = Parse {
  Skip {
    PrefixThrough("(")
  }
  PrefixUpTo(")")
    .map(String.init)
}

The following code gets the timestamp into the Change struct:

do {
  timestamp = try String(timestampInfo.parse(commandOutput))
} catch {
  print(error)
}

Parsing the Description

The change description starts after the first blank line. The description ends with a blank line and one of the following phrases:

Modified regular file
Added regular file
Removed regular file

Start by writing a parser for each possible end of a description.

let modifiedFile = Parse {
  PrefixUpTo("\n\nModified regular file")
}

let addedFile = Parse {
  PrefixUpTo("\n\nAdded regular file")
}

let removedFile = Parse {
  PrefixUpTo("\n\nRemoved regular file")
}

Use the OneOf parser to capture everything until you reach one of the possible ends of the description. The following code parses the change description:

let descriptionInfo = Parse {
  // Get to the start of the change description.
  Skip {
    PrefixThrough("\n\n")
    Whitespace()
  }
  // Capture everything up to one of the 
  // possible description ends.
  OneOf {
    modifiedFile
    addedFile
    removedFile
  }
  .map(String.init)
}

The following code gets the description into the Change struct:

// Remove the indentation at the start of paragraphs 
// and the blank line at the end.
do {
  description = try String(descriptionInfo.parse(commandOutput))
    .trimmingCharacters(in: .whitespacesAndNewlines)
} catch {
  print(error)
}

Skipping the Remaining Text

I ran into a problem when I started parsing change details. The parser returned no matches. Xcode’s console printed the following error message:

error: unexpected input
 --> input:1:10
1 | Change ID: lyrzonnxolkpxytwwykkqpvvlqmvlxqm
  |          ^ expected end of input

I learned that when you have captured everything you want to parse and there’s text left to read, you must run the Rest parser that goes through the rest of the text.

Skip {
  Rest()
}

Find the Slow Spots in Your Code with the CPU Profiler Instrument

Thu, 24 Jul 2025 13:29:07 -0400

If you find your Swift app is running slowly, Instruments includes a CPU Profiler instrument to help you find the code causing your app to run slowly. This article shows you how to use the CPU Profiler instrument to find the slow code in your app.

Launching Instruments

In Xcode choose Product > Profile or press Cmd-I to build your Xcode project and launch Instruments.

When Instruments launches a window opens for you to choose a template to profile your app. Select the CPU Profiler template and click the Choose button. If you are running an older version of Xcode that does not have the CPU Profiler template, select the Time Profiler template.

Profiling Your App

Click the Record button at the top of the trace document window or press Cmd-R to start profiling your app. Run your app.

Click the Pause button or press Cmd-Shift-R to pause recording. Click the Stop button or press Cmd-Dot to stop recording.

Reading the Profiling Data

When you stop recording Instruments shows the call tree view.

The call tree view has a listing for each function that executed while profiling.

Finding Your Code in the Call Tree

When you first look at the call tree view, you will see it shows lots of functions that you didn’t write. How do you find your functions in the call tree view?

To find your code in the call tree view, click the Call Tree button at the bottom of the window and click the Hide System Libraries and Invert Call Tree checkboxes.

Hiding the system library code makes it easier to find your app’s functions in the call tree view. Inverting the call tree brings the executed functions to the top of the call tree view.

Finding the Slow Code

How do you know which functions are the slow functions?

Each function in the call tree view has a Weight value and a Self Weight value. The Weight value tells you how long the function was on the call stack. The Self Weight value tells you how long the function was at the top of the call stack.

The Self Weight value is more important. Suppose you have a function A that calls functions X, Y, and Z. The Weight value for A tells you the amount of time your app was in functions A, X, Y, and Z. The Self Weight value for A tells you the amount of time your app was in A. When you’re looking for the slow spots in your code, look at functions with a high Self Weight value.

Clicking the Self Weight column heading sorts the call tree view listings by their Self Weight value. Sorting by Self Weight brings the slow functions to the top of the call tree view.

Viewing the Slow Code

Double-clicking a function in the call tree view opens the source view, where you can see the lines of code that take the most time in the function. Make sure you double-click a function you wrote. If you double-click a function you didn’t write, the source view shows unreadable assembly language code.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Show an Alert from a Menu Item in a SwiftUI Mac App

Mon, 23 Jun 2025 12:44:56 -0400

SwiftUI provides an .alert view modifier you can apply to a view to show an alert in your app. If you add the .alert modifier to a SwiftUI view that is part of a CommandGroup menu, the alert does not appear. SwiftUI does not support directly showing an alert from a menu in the menu bar because a menu does not have a view for SwiftUI to attach the alert. How do you show the alert?

There are two ways to show an alert from a Mac menu item in a SwiftUI app. The first way is to apply the .alert modifier to the app’s content view. The second way is to use AppKit and NSAlert.

Apply .alert to the Content View

To get the alert to open, apply the .alert modifier to the content view in the body of the App struct.

@State private var showAlert = false

var body: some Scene {
  WindowGroup {
    ContentView()
      .alert("Alert message text", 
        isPresented: $showAlert) {
          Button("OK", role: .cancel) { }
      }
  }
}

In the menu item’s view, add a binding for showing the alert.

@Binding var showAlert: Bool

Set the showAlert property to true in the menu item code to tell SwiftUI to show the alert.

Finally, pass the property from the App struct to the menu item.

CommandGroup() {
  MenuItemView(showAlert: $showAlert)
}

Applying the .alert modifier to the content view works well if your app has only one main window or uses SwiftUI’s document architecture. If your app shows multiple windows of the same type using SwiftUI’s WindowGroup, which I wrote about in the Open Document-like Windows Using SwiftUI WindowGroup article, you will notice a problem when you apply the .alert modifier to the content view.

The alert opens once for each open window. If no windows are open, the alert doesn’t open.

NSAlert

To open the alert once no matter how many windows are open, use AppKit to show the alert. The AppKit way to show an alert is to create an NSAlert object, set the alert text, and call the runModal function.

let alert = NSAlert()
alert.messageText = "Alert Title"
alert.informativeText = "More explanatory text"
alert.runModal()

Place the NSAlert code inside a function and call the function when you want to show the alert.

Open Document-like Windows Using SwiftUI WindowGroup

Mon, 16 Jun 2025 14:53:48 -0400

Why would you need to open document-like windows without using SwiftUI’s document architecture?

Suppose you’re planning to use SwiftUI to make a Mac git client app like SourceTree or Fork. The app should open a window for each open git repo. SwiftUI’s document architecture supports opening a window for each open document, but a git repo can’t use most of the document architecture. You’re not going to open a blank repo window by pressing Cmd-N, save a repo by pressing Cmd-S, or mark a git repo as being edited. How do you open windows for each repo without using SwiftUI’s document architecture?

Create a SwiftUI app project and use the WindowGroup scene type to open additional windows. You must set up the window group to support creating additional windows and write code to open the window.

Setting up the Window Group

The body for the App struct in a new SwiftUI project has the following code:

var body: some Scene {
  WindowGroup {
    ContentView()
  }
}

To support creating additional windows, add a for argument to the WindowGroup and supply a data type. The data type should be one of your app model’s structs or classes that holds the data to show in the window.

Add an argument to the closure (after the opening brace) so that each window shows a unique instance of the window group’s data type.

The following code creates a new window for each open folder in the app and sets the window’s title to the folder’s display name:

struct Folder: Hashable, Codable {
  var url: URL
  var displayName: String {
    url.path.components(separatedBy: "/").filter{ !$0.isEmpty }.last ?? ""
  }
}

WindowGroup(for: Folder.self) { $folder in
  ContentView()
    .navigationTitle(folder?.displayName ?? "Window")
}

In a real app you would have a @Binding property in the content view and pass the equivalent of $folder as an argument to the content view.

Opening the Window

SwiftUI provides an openWindow environment property for opening windows in SwiftUI Mac apps. Add an @Environment property to your SwiftUI view.

@Environment(\.openWindow) private var openWindow

Create a new instance of the data structure you used as the for argument to the window group and pass that instance as the value to the openWindow function. The following code opens a new window for a user-selected folder:

// Get the URL from a file importer.
let folder = Folder(url: url)
openWindow(value: folder)

Add an Open menu item to the File menu or add a toolbar button to open new windows in your app.

Sample Project

I have a sample project on GitHub for you to view and download. Choose File > Open and select a folder on your Mac. The app creates a window and sets its title to the name of the selected folder.

Instruments Flame Graph Introduction

Mon, 24 Mar 2025 14:09:38 -0400

Apple added flame graphs to Instruments in Xcode 16 to let developers visualize call tree statistics. Unfortunately Apple did not add much documentation on using flame graphs. I’m writing this article to partially fill the documentation void.

Showing the Flame Graph

You must be in the call tree view to show the flame graph.

There are two buttons on the right side above the detail view. Click the rightmost button to show the flame graph.

If you don’t see the buttons, the instrument does not show flame graphs. Currently only the Time Profiler instrument shows flame graphs. Some time in the future (hopefully soon) all the instruments that have a call tree view will show flame graphs.

Reading the Flame Graph

When you click the button to show the flame graph, the flame graph initially looks similar to the following screenshot:

The flame graph consists of stacks of rectangles. Each rectangle represents a function in your app’s call stack. Looking at the screenshot of the flame graph, you will notice that iOS and Mac apps have a lot of functions. Most of the rectangles are so narrow that you can’t read the function names.

The top of the flame graph shows the function at the bottom of the call stack. This function is most likely the name of your app. Underneath the top rectangle are rectangles for the functions the bottom function called. The stack of rectangles continues downward until you reach the bottom rectangle, which is the function at the top of the call stack.

One area where flame graphs excel is telling you the relative amount of time spent in the functions that a function calls. Suppose you have a function A that calls functions B, C, and D. You can tell whether your app spends more time in B, C, or D by the width of the rectangle. The wider the rectangle, the more time the function was on the call stack.

If you look at the second row in the flame graph screenshot, you will see the start function is on the call stack the most, over 70 percent of the time. The start_wqthread function is on the call stack the second most, around 10 percent. After that are a bunch of other functions whose names you can’t read. The names of the functions and the percentages aren’t important in this case because they involve code I didn’t write. I’m using the second row as an example of reading the flame graph. You have to move farther down the flame graph to find code you wrote.

The functions that spend the most time on the call stack appear on the left side of the graph.

Finding Your Code in the Flame Graph

Functions you wrote have a blue rectangle. You must scroll down the flame graph to find your code because the top of the graph has blue rectangles for functions in your app that you didn’t write, such as main.

The easiest way to find your code is to hide functions in system libraries from the flame graph. Click the Call Tree button at the bottom of the window and select the Hide System Libraries checkbox.

Navigating the Flame Graph

Click a rectangle in the flame graph to select it. After selecting a rectangle, use the arrow keys to navigate the flame graph.

Zooming the Flame Graph

The number of functions in iOS and Mac apps makes it tough to read the function names for most of the flame graph rectangles. How do you zoom the flame graph so you can read those function names?

Create a zoom area. Start by clicking in the flame graph to establish the start of the zoom area. Hold down the Option key, scroll, and release the mouse button to set the zoom area. You can also zoom with a trackpad gesture, but I don’t have a trackpad to test this.

Combine creating a zoom area and hiding system libraries to make your function names readable in the flame graph.

To zoom out, hold down the Option key and click in the graph. Scroll to the top of the flame graph and option-click to zoom out completely.

Summary

The following list has the most important things to remember when reading Instruments flame graphs:

Rectangle width indicates the percentage of time the function was on the call stack.
The functions that spend the most time on the call stack appear on the left side of the graph.
Functions in your app have blue rectangles.
Hide system libraries to focus on your code. Click the Call Tree button at the bottom of the window to hide system libraries.
Option-scroll to zoom the flame graph to read function names.

Acknowledgments

Thanks to James Dempsey and Philippe Casgrain for the information on zooming the flame graph.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Using Jujutsu Version Control in Xcode Projects

Mon, 17 Mar 2025 13:31:16 -0400

Last update: January 2026

Jujutsu, also known as jj, is a version control system that is growing in popularity with developers. One reason for its popularity is that it works with git repositories and services like GitHub.

In this article I share what I learned about using Jujutsu in Xcode projects and putting Jujutsu repos on GitHub. The article has two main sections: one on adding Jujutsu to an Xcode project with an existing git repo and one on adding Jujutsu to a project with no git repo.

Disclaimer: I am learning Jujutsu. I am not an expert on it.

I refer to Jujutsu in this article using both Jujutsu and jj.

Adding Jujutsu to an Xcode Project with a Git Repo

To add Jujutsu support to an Xcode project, you must create a jj repository for the project from the Terminal app. In the Terminal navigate to the directory above your Xcode project’s folder. If you are inexperienced with the Terminal, go to the directory above your project folder in the Finder, right-click, and choose Services > New Terminal at Folder. A Terminal window will open with the current directory being the directory above the project folder.

Run the following command to create a jj repo:

jj git init --colocate RepoName

Where RepoName is the name you give to the repo.

Now your Xcode project has two version control repos: a git repo and a jj repo. You can see this for yourself in the Finder by pressing Cmd-Shift-Dot. There will be a .git folder and a .jj folder inside your project folder.

Using the --colocate option tells Jujutsu that the git and jj repos share the same working copy. Xcode will continue to track the changes in your project. If you commit changes using Xcode or another git app like SourceTree, the commits appear in both the git and jj repos.

Putting the Jujutsu Repo on GitHub

If you want your Jujutsu repo on GitHub and have not created a remote GitHub branch for the Xcode project, do so from the Source Control navigator, which you can access by pressing Cmd-2. The following article has detailed instructions on putting an Xcode project on GitHub:

Putting Your Xcode Project on GitHub, Bitbucket, or GitLab

You must push the jj repo to GitHub. You have to do this from the Terminal. Go to your project folder in the Terminal.

Run the following commands to push the local jj repo to GitHub:

jj describe -m "Initial push to GitHub"

jj bookmark set trunk --allow-backwards -r @-

jj git push --allow-new -b trunk

The first command creates a description for a commit. I got an error when I pushed to GitHub without creating a description.

The second command creates a trunk branch for you to push to GitHub. The --allow-backwards option lets you move the bookmark backwards or sideways, which you need the first time you set a bookmark.

The -r option specifies the change (commit) where the bookmark should point. In most cases you should point the bookmark to the most recent change you made. Run the jj status command to check if the working copy is empty.

If the working copy is not empty, point the bookmark to the working copy by passing @ as the change ID. If the working copy is empty, point the bookmark to the working copy’s parent commit by passing @- as the change ID.

The final command pushes the local jj repo to the trunk branch on GitHub. Supply the --allow-new and -b options along with the name of the bookmark. The --allow-new option allows creating new bookmarks, which you need to do the first time you push.

If you don’t supply the -b argument, Jujutsu issues a warning about the working copy commit becoming immutable.

The GitHub repo should have a main branch that contains the project’s git repo and a trunk branch that contains the jj repo.

Adding Jujutsu to an Xcode Project with no Git Repo

To add Jujutsu support to your Xcode project, you must create a jj repo for the project. Go to your project folder in the Terminal and run the following command:

jj git init

Running the command creates a .jj folder in your project folder. You can see this for yourself in the Finder by pressing Cmd-Shift-Dot.

Xcode will not show the changes in your code because the project has a jj repo and no git repo. If you want Xcode to show the changes in your code, you must create a git repo. In Xcode choose Integrate > New Git Repository to add a git repo to your project.

Putting the Jujutsu Repo on GitHub

You must create a repository in GitHub and push your local jj repo to that repo. When you create the repo in GitHub, GitHub provides instructions on how to push an existing repo. The commands in those instructions provide a guide on what you need to run to push your local jj repo to GitHub.

Run the following commands to put your local jj repo on GitHub:

jj git remote add origin https://github.com/GitHubAccount/RepoName.git

jj describe -m "Initial push to GitHub"

jj bookmark set trunk --allow-backwards -r @-

jj git push --allow-new -b trunk

The first command adds a remote branch to your local repo. The branch contains the repo you created on GitHub. Replace GitHubAccount with your GitHub username, and replace RepoName with your repo name.

The second command creates a description for a commit. I got an error when I pushed to GitHub without creating a description.

The third command creates a trunk branch for you to push to GitHub. The --allow-backwards option lets you move the bookmark backwards or sideways, which you need the first time you set a bookmark.

If you don’t supply the -b argument, Jujutsu issues a warning about the working copy commit becoming immutable.

Looking for a Jujutsu GUI Client?

If so, I’m developing Jjewel, a native Mac app that provides a GUI for Jujutsu. Use Jjewel to perform the most common version control tasks and spend less time entering Terminal commands.

Go to the Jjewel site to learn more about the app and download it.

See How Many Times Your SwiftUI Views Redraw Using Instruments

Mon, 10 Mar 2025 12:07:02 -0500

If you run into a performance problem in your SwiftUI app, the cause could be your app’s views redrawing too often. Apple provides instruments in the Instruments app that let you see how many times SwiftUI draws your app’s views and the view properties that trigger redraws. This article shows how to use those instruments.

Profile Your App

Take the following steps to profile your app with the SwiftUI instruments:

Go to Xcode.
Press Cmd-I or choose Product > Profile to build your project and launch Instruments.
Choose SwiftUI from the template list.
Click the Choose button.
Click the Record button above the sidebar to start profiling.
Click the Stop button when you are finished.

The SwiftUI template has the following instruments:

View Body
View Properties
Core Animation Commits
Time Profiler
Hangs

I cover the View Body and View Properties instruments in this article. Read the following article to learn more about the Time Profiler instrument:

Finding the Slow Spots in Your Code with the Time Profiler Instrument

See the Number of View Redraws

Use the View Body instrument to see statistics about the redraws of the SwiftUI views in your app. The View Body instrument table has the following columns of data:

Count
Total Duration
Minimum Duration
Average Duration
Maximum Duration
Standard Deviation Duration

The most important columns are Count, Total Duration, and Average Duration. The Count column tells you how many times SwiftUI drew the view. The Total Duration column tells you the total time of those draws. The Average Duration column tells you the average time of each draw.

The View Body instrument table has at least two rows: one for SwiftUI and one for your app. Start by looking at the statistics for your app. You will see the total number of times SwiftUI drew your app’s views.

To see what views were drawn the most, click the disclosure triangle next to your app. There will be a row for each view in your SwiftUI app.

The views that were drawn the most should appear at the top. If you don’t see the views that were drawn the most, click the Count table header to sort the views by count.

See the Properties that Trigger Redraws

If you find one of your views is being redrawn often, you want to figure out what is causing the view to redraw so much. How do you find the cause of redraws?

SwiftUI views redraw when the data bound to the views changes. Use the View Properties instrument to see the properties (variables) that change the most. Anything in your code that uses property wrappers like @State and @Binding will appear in this instrument.

When you select the View Properties instrument, you will see a long list of properties with their current values. You can get more useful information from the summary. Press Cmd-2 or choose Summary from the jump bar to see the summary.

The summary looks similar to the summary for the View Body instrument. There are rows for SwiftUI and your app. There is one column that tells you the number of updates.

Where the View Properties instrument differs is it has levels you can drill down by clicking disclosure triangles. The View Properties instrument has the following levels:

View type
Property type
Property value

The view types for your app are your app’s views. They should be the same as the views in the View Body instrument.

The property types are the data types for the properties in your SwiftUI views. An example of a property type in a SwiftUI view is Binding<String>, which is a binding to a string. The instrument shows the data types, not the names of your variables.

The property values show the different values the property had during profiling. A Boolean property will show the number of times it was set to true and set to false.

You are noticing there’s a lot of disclosure triangle clicking when looking at view properties. Option-clicking a disclosure triangle will expand the list to show all the levels so you don’t have to click as much. Option-clicking again will contract the list.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Set the Sidebar Initial Width in SwiftUI Navigation Split View

Mon, 24 Feb 2025 14:22:06 -0500

When you use a navigation split view in a SwiftUI Mac app, you normally have a sidebar in the left column. You want to give the sidebar an initial width that is wide enough to show the sidebar contents while letting people resize the sidebar. How do you provide the initial width?

Add the .navigationSplitViewColumnWidth modifier to the sidebar view and supply the initial width you want. The following code sets the sidebar width to 192 points:

NavigationSplitView {
	Sidebar()
    	.navigationSplitViewColumnWidth(ideal: 192)
} detail: {
  	DetailView()
}

Downloading Older Versions of Xcode

Tue, 28 Jan 2025 13:50:14 -0500

Those of you running older versions of macOS will run into problems if you try to install Xcode from the Mac App Store. The Mac App Store has only the most recent version of Xcode. The most recent version of Xcode usually requires the latest version of macOS. How do you download older versions of Xcode?

Apple’s Xcode Downloads Page

Apple has an Xcode Downloads page where you can download older Xcode versions.

Xcode Releases

A faster way to find Apple’s download links is to go to Xcode Releases. The Xcode Releases site has Apple’s download links for every version of Xcode. Xcode Releases also lists the minimum version of macOS required for each Xcode version.

Xcodes App

The Xcodes app provides another way to install older versions of Xcode. I have not use Xcodes, but lots of developers recommend it for downloading and installing Xcode.

Latest Xcode Versions for Older macOS Versions

Xcode 16.2 is the latest version for macOS 14.
Xcode 15.3 is the latest version for macOS 13.
Xcode 14.2 is the latest version for macOS 12.
Xcode 13.2.1 is the latest version for macOS 11.
Xcode 12.4 is the latest version for macOS 10.15.
Xcode 11.3.1 is the latest version for macOS 10.14.

You can see the pattern for earlier macOS versions.

Troubleshooting File Loading Problems in Swift Apps

Mon, 25 Nov 2024 14:08:58 -0500

A problem that people learning to develop iOS and Mac apps run into is being unable to load files they include in their app, such as image files, sound files, and text files. This is a frustrating problem because your code is usually not the source of the problem. The problem is the operating system cannot find the file in the app bundle.

This article has tips on fixing file loading problems in your app.

Where do Swift GUI apps look for files?

Swift apps look for files in the Resources folder of your app bundle. When you write code to load a file, such as the following:

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

The operating system looks in the Resources folder. If it does not find the file, the function returns nil. The operating system does not search the entire app bundle, just the Resources folder.

It is very important that the files your app loads are in the app bundle’s Resources folder. If the files are not in the Resources folder, your app will not be able to load them.

Make sure the files are in the app bundle’s Resources folder

If you run into problems with loading files, make sure the files you want to load are going to be copied to the app bundle’s Resources folder when Xcode builds your project. To make sure the files will be copied to the Resources folder, make sure they are in the app target’s Copy Bundle Resources build phase. The files must be part of this build phase to get copied to the app bundle.

Take the following steps to see the files in the Copy Bundle Resources build phase:

Open the project editor by selecting the project file from the left side of the project window.
Select the app target from the target list on the left side of the project editor.
Click the Build Phase button at the top of the project editor.
Click the disclosure triangle next to the Copy Bundle Resources build phase.

If your files are not in the Copy Bundle Resources build phase, click the Add button below the list of files to open a sheet where you can choose the files to add to the build phase.

Make sure the file names match exactly

The code example earlier in this article,

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

Looks for a file with the name SampleData.json in the Resources folder. The Bundle class file search is case sensitive. If the name of the file in the app bundle is sampledata.json, the code example above won’t find the file because the file names don’t match exactly.

Also make sure you didn’t misspell the name of the file in your code. It’s easy to make a small typo that causes file loading problems.

Don’t include the dot when giving the file extension

The Bundle class’s url function takes a file extension as an argument. An easy mistake to make is to include the dot in the extension, such as the following code:

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: ".json")

With this code, the operating system is going to look for a file named SampleData..json, which most likely does not exist.

Do not include the dot when specifying file extensions.

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

Using folders of files in your app

If you include a lot of files in your app, you may place them in separate folders to make them easier to organize. You might have a folder for data files and a folder for audio files.

Suppose you have a separate folder for your JSON files. If you use the code I have used throughout this article to load a JSON file,

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json")

The url function returns nil because the JSON files are in a folder inside the Resources folder. The function looks in the Resources folder, doesn’t find the JSON file in that folder, and returns nil.

The fix is to add a subdirectory argument to the url function call and specify the name of the folder where the file is located.

let sampleData = bundle.url(forResource: "SampleData", 
    withExtension: "json", subdirectory: "JSON")

SwiftUI Tip: Avoid Nesting ObservableObjects

Mon, 26 Aug 2024 23:02:12 +0000

A problem many SwiftUI developers have is their views not updating when the data changes. A common reason for this problem is having nested ObservableObjects in their code.

In this article you will learn what a nested ObservableObject is, why nested ObservableObjects cause problems, and how you can get your views to update correctly.

What is a Nested ObservableObject?

A nested ObservableObject occurs when you have a class that conforms to ObservableObject and has a property whose class also conforms to ObservableObject.

Let’s look at an example of a nested ObservableObject. Suppose you have an issue tracking app. The data model for the app includes projects and issues. Each project can have multiple issues.

If you make Project a class, have it conform to ObservableObject, and give it a list of issues,

class Project: ObservableObject {   
  @Published var issues: [Issue]
  ...
}

And the Issue class conforms to ObservableObject,

class Issue: ObservableObject {
  ...
}

You have a nested ObservableObject. Issue is nested inside Project.

What’s Wrong with Nested ObservableObjects?

Why do nested ObservableObjects cause problems? When a change occurs in the inner object, SwiftUI does not automatically report the change to the outer object. This means the view for the outer object will not update when the data in the inner object changes.

In the issue tracking app example, the project does not get notified of any changes to its issues. When an issue changes, the project’s view will not update to reflect the changes.

Fixing the Problem

At this point you’re wondering what you have to do to fix the problem and get your views to update correctly. The following techniques can fix the problem:

Use structs instead of classes for your data models.
Use the Observation framework.
Manually send a message when there is a change in the inner object.

Use Structs Instead of Classes

Using structs for your data models can be the easiest fix. Structs do not use the ObservableObject protocol so you won’t get nested ObservableObjects. In the issue tracker example, making Project or Issue a struct will eliminate the nested ObservableObject.

But you might find that parts of your app’s data model must be classes. When I was developing Bartleby, I initially tried using a struct for book chapters, but the chapter text would not save when I switched chapters. The only way to get the chapter text to save was to make Chapter a class. You may have a similar situation in your app.

Remember you don’t have to change every class in your app to a struct. Make sure you don’t have one class nested inside another class.

Use the Observation Framework

Apple added the Observation framework in iOS 17 and macOS 14. If you use the Observation framework for your data and to pass data to views, you will fix the problem.

The downside of using Observation is you can’t use it in earlier iOS and macOS versions. If you need to support iOS 16 or earlier in your app, you can’t use the Observation framework.

Manual Changes

If you can’t use structs for your data model, can’t avoid nesting ObservableObjects, and can’t use the Observation framework, you have one more workaround. Manually sending a message when the data changes.

Call the objectWillChange.send function to manually send a message when the data changes. The function takes no arguments.

macOS by Tutorials Book Review

Mon, 05 Aug 2024 17:33:14 +0000

I received a review copy of the new version of Sarah Reichhelt’s macOS by Tutorials book and decided to share details about the book so you can determine if it’s right for you.

Who the Book is for

The book is written for people with some iOS development experience who want to learn to make Mac apps with SwiftUI. AppKit developers who want to get up to speed with SwiftUI would also benefit from this book.

The book assumes the reader knows some Swift and SwiftUI. Someone with no programming experience would need to learn the basics of Swift before going through the book.

Book Contents

The title of the book gives away what the book covers. You create four Mac apps in the book, three SwiftUI apps and an AppKit menu bar app, and the book uses a tutorial format to teach the material. You learn by building the apps. The projects are available on GitHub for you to view and to check for any mistakes you might make following the tutorials.

The final section of the book covers how to distribute your Mac app.

The projects have been tested and run on both Xcode 15 and 16.

What the Book Doesn’t Cover

SwiftData
Core Data
The Observable framework

The First SwiftUI App

The first app you build in the book is On This Day, an app that shows information about events, births, and deaths that occurred on a particular date. You build the app over five chapters.

The first chapter covers the design of the data model for the app. Topics covered in the chapter include the following:

Fetching data from the network
Decoding JSON
Saving JSON to a local file

The second chapter is where you start building the user interface for the app. The app uses a navigation split view with a sidebar and detail area. Topics covered in the chapter include the following:

Building a sidebar
Building a card view to display events
Building a grid to display cards
Creating multiple windows

In the third chapter you add a toolbar to the window and add menus to the app. Topics covered in the chapter include the following:

Adding a menu to the menu bar
Adding menu items to an existing menu
Using a picker as a menu item
Adding a search field to the toolbar to filter what appears in the detail view

The fourth chapter covers using tables and custom views. Topics covered in the chapter include the following:

Getting the app to show the event data as a table or grid
Using the @SceneStorage property wrapper to save settings for each window
Adding an inspector
Creating a custom date picker to let people choose a date to view events

The final chapter covers the following topics:

Adding a preferences window to the app
Adding an app icon
Customizing the app’s About box
Replacing the default Help menu item with an item that takes you to a website

The Menu Bar App

The second app you create in the book is a Pomodoro timer menu bar app. You build the app over three chapters.

In the first chapter you convert the standard AppKit app project to a menu bar app. A big part of the chapter is adding the menu items to the menu bar. Topics covered include the following:

Adding menu items in a storyboard
Adding dynamic menu items in code
Using custom views in menu items.

The second chapter covers working with timers, alerts, and notifications. You will learn how to start and stop pomodoro tasks.

In the final chapter you learn how to add your own tasks to the app.

The Document-Based App

The third app you create in the book is a Markdown editor with live preview. You build the app over two chapters.

The first chapter covers the following topics:

Creating and configuring a document-based app
Adding a Swift package to a project
Using AppKit views in a SwiftUI app

The second chapter focuses on adding menu controls to the app. The chapter covers the following topics:

Adding a menu to the app to show the HTML using a CSS stylesheet
Adding menu items that are specific to a single window
Exporting a document to a file

The Final App

The final app you build is an app that provides a GUI for the sips Terminal command. The sips command manipulates images. You build the app over three chapters.

The first chapter introduces you to the Terminal and shows you how to use the Process class to run Terminal commands from a Mac GUI app.

In the second chapter you build the user interface for the app. The chapter covers the following topics:

Opening files with SwiftUI’s file importer
Dragging and dropping files and folders to a SwiftUI view

The final chapter covers adding support for macOS automation features to the app. The chapter covers the following topics:

Creating a service that can be accessed from the macOS Services menu
Creating an app intent that can be used by the Shortcuts app or Siri

Distributing Your App

The final two chapters of the book cover how to distribute your Mac apps so other people can use them. The first chapter covers how to put your app on the Mac App Store.

The second chapter shows you how to distribute your app outside the Mac App Store. You learn how to notarize your app and create a DMG disk image for your app.

Should You Buy This Book?

I recommend buying the book under the following conditions:

You want to learn how to make SwiftUI Mac apps
You know some Swift
You like learning through tutorials where you build apps

Save Data in Your Swift App with PropertyListEncoder

Wed, 29 May 2024 19:41:28 +0000

Apple provides a PropertyListEncoder class to save data as a dictionary in a property list file. If your app’s data can be saved to a dictionary, using PropertyListEncoder provides a relatively easy way to save the data.

You must do the following to save app data with PropertyListEncoder:

Create a struct or class that conforms to the Codable protocol.
Create a CodingKeys enum for the properties in your struct or class.
Create a property list encoder and encode the data.

Creating the Struct or Class

For this article, I’m going to use a stripped down version of a struct I created in Phel to store an Apple help book’s Info.plist file. The following block shows the code for the struct:

struct HelpBookInfo: Codable {
  // The values are placeholder values.
  // The app has a view to set the values.
  var appTitle = "My App"
  var bookTitle = "My App Help"
  var bundleIdentifier = "com.CompanyName.MyApp.Help"
}

Every property in the struct or class must also conform to Codable. If you can’t get the struct’s properties to conform to Codable, you must use the NSKeyedArchiver class to create the property list. The following article shows you how to use NSKeyedArchiver:

Saving with NSKeyedArchiver

Creating a CodingKeys Enum

It’s not mandatory to create a CodingKeys enum, but if you don’t create the enum, the property list encoder uses the name of the property as the key. In many cases the key must have a specific value. The CodingKeys enum lets you save the property list with the correct key names while letting you use clear property names in your code.

Add the CodingKeys enum inside your struct or class. Add a case for each property. The following code shows the enum for the HelpBookInfo struct.

private enum CodingKeys: String, CodingKey {
  case appTitle = "CFBundleName"
  case bookTitle = "HPDBookTitle"
  case bundleIdentifier = "CFBundleIdentifier"
}

When saving the property list, the file will use the key CFBundleName to store the name of the app, the key HPDBookTitle to store the name of the help book, and the key CFBundleIdentifier to store the help book’s bundle identifier.

Creating the Property List Encoder

Now you can create the property list encoder to save data. Start by creating an instance of PropertyListEncoder.

Property lists have two possible formats: XML and binary. Set the encoder’s outputFormat property to set the format.

Call the encode method to save the data. Supply the value that you want to encode. The encode method can throw errors so you must wrap the call in a do-try-catch block.

Adding the following method to the HelpBookInfo struct saves the help book information to an XML property list:

func write() -> Data? {
  let encoder = PropertyListEncoder()
  encoder.outputFormat = .xml
            
  do {
    return try encoder.encode(self)
  } catch {
    print(error)
    return nil
  }
}

Running a Command-Line Program from a Mac App

Mon, 08 Apr 2024 17:39:53 +0000

Apple provides the Process class that lets you run Terminal commands and command-line programs inside a Mac app. If you were creating a git GUI client, such as SourceTree or Tower, you would use the Process class to run git commands from your app.

To run a command-line program from your Mac app, you must do the following:

Create a Process instance
Configure the process
Run the process

Create the Process

Creating a process is the easiest step. Call the Process class’s initializer.

let task = Process()

Configure the Process

What you must configure depends on the command or program you want to run. You must set the executable URL, the location of the command or program you want to run. Some other things you may need to configure include the following:

Arguments to pass to the process
The current directory
Environment variables
Standard error
Standard input
Standard output

In my help book building app Phel, I run the hiutil command to index the help book. I configure the following items to run the command:

The executable URL, which is usr/bin/hiutil.
The directory to run the command, which is the Resources folder inside the help book bundle.
The arguments, which are -I, lsm, -Caf, the name of the index file, -vv, and ..

I must run the hiutil command a second time to generate a spotlight index file. I replace the lsm argument with corespotlight and supply the name of the spotlight index file.

Run the Process

Call the run function inside a do-catch block to run a process.

The following code runs the hiutil to generate an index file for an Apple help book:

// location is the URL of the help book bundle.
func createIndexFile(location: URL) {
  let task = Process()
  task.executableURL = URL(fileURLWithPath: "usr/bin/hiutil")
            
  // Get to the Resources folder in the help book bundle.
  let contentsFolder = location.appendingPathComponent("Contents",
    conformingTo: .data)
  let resourcesFolder = contentsFolder.appendingPathComponent("Resources",
    conformingTo: .data)
  task.currentDirectoryURL = resourcesFolder
            
  // indexFile is the name of the file the hiutil command creates.
  task.arguments = ["-I", "lsm", "-Caf", indexFile, "-vv", "."]
            
  do {
    try task.run()
  } catch {
    print(error)
  }
}

Creating a UIKit Xcode Project

Mon, 12 Feb 2024 19:02:16 +0000

A common problem people learning UIKit have when following a tutorial is that what they see in Xcode does not match what the tutorial shows. The tutorial shows a view controller file, but they see a content view file.

The most common cause of this problem is creating an Xcode project that uses SwiftUI instead of UIKit. When you create a new project in Xcode, the default is to create a SwiftUI project.

To create an Xcode project that uses UIKit, you must create an iOS app project and tell Xcode to use a storyboard for the user interface. UIKit uses storyboards, and SwiftUI doesn’t.

Create an iOS App Project

In Xcode choose File > New > Project to create a new project. The New Project Assistant opens.

Click on iOS at the top of the assistant to see the iOS app project templates. Choose either App or Document App. If you’re not sure, choose App. Click the Next button.

Choose Storyboard for the User Interface

When you click the Next button, the New Project Assistant takes you to the next step in creating the project.

Choose Storyboard from the Interface menu to create a UIKIt project.

If you don’t see an Interface menu (or a menu with a similar name), click the Previous button and make sure you choose an iOS app project. Xcode’s multi-platform project templates create SwiftUI projects.

How to Learn SwiftUI to Develop Mac Apps

Mon, 05 Feb 2024 19:09:03 +0000

A common complaint I hear online from Mac developers is that all the SwiftUI learning material focuses on iOS development, and there’s nothing on Mac development. This article provides advice on learning SwiftUI for Mac development.

A lot of iOS SwiftUI learning material also works on Mac

Mac developers have to accept the fact that iOS development is much more popular than Mac development. People creating SwiftUI tutorials, videos, and courses are going to focus on iOS developers.

The good news with SwiftUI is that most of the iOS learning material also applies to Mac development. Apple created SwiftUI so developers can create user interfaces for all of their platforms with one framework. If you find a SwiftUI tutorial or course that you like, such as Hacking with Swift’s 100 Days of SwiftUI course, you can use the tutorial or course to make Mac apps. You may have to make some changes to get things to work on Mac.

Lists are one area of SwiftUI where there are large differences between iOS and Mac. If you read an article about lists and try to use the code in a Mac app, you’ll run into problems. The following articles cover those differences:

You can use AppKit views in SwiftUI Mac apps

SwiftUI is not a finished framework, especially on Mac. Some views that Mac apps need do not have native SwiftUI equivalents, and some of SwiftUI’s views do not work well on Mac. A workaround for SwiftUI’s Mac limitations is to use AppKit views in your app.

To use an AppKit view in a SwiftUI Mac app, create a struct that conforms to the NSViewRepresentable protocol. My Using a UIKit or AppKIt View in SwiftUI article provides more details on using AppKit views in a SwiftUI app.

SwiftUI resources for Mac development

To address complaints about a lack of learning material on Mac development, I compiled a list of Mac development resources. Many of those resources cover using SwiftUI for Mac development.

This site has a number of SwiftUI articles, most of which apply to Mac development. You can see a complete list of articles on the Articles page.

Deleting an Xcode Project’s Git Repository

Thu, 25 Jan 2024 18:48:49 +0000

Deleting a git repository for an Xcode project is relatively easy: move the folder that holds the git repository out of the project folder. But the Finder makes locating the repository folder difficult. In this article you will learn how to find the repository folder so you can delete it.

Where is the git repository?

The git repository is in a .git folder inside the project folder. If you go to the project folder in the Finder, you won’t see the .git folder. Why can’t you see it?

You can’t see the .git folder in the Finder because the Finder hides files and folders that start with a dot. To see the .git folder in the Finder, press Cmd-Shift-Dot. Pressing Cmd-Shift-Dot shows hidden files and folders.

Press Cmd-Shift-Dot a second time to stop showing the hidden files and folders in the Finder.

Deleting the repository

Move the .git folder out of the project folder, and git will stop tracking changes in your project. You will normally move the .git folder to the Trash.

If you want to create a new git repository for your project after removing the previous one, choose Integrate > New Git Repository in Xcode. Older versions of Xcode have a Source Control menu instead of an Integrate menu.

Want to learn more about git?

Check out my version control book. It shows you how to do the most common git tasks without leaving Xcode. Some of the material covered in the book includes cloning projects from GitHub, branching, and going back to earlier versions of your project.

Where is the Info.plist file?

Tue, 02 Jan 2024 19:20:01 +0000

Recent versions of Xcode do not add an Info.plist file to new iOS app projects. How do you add settings to your app that you would normally place in Info.plist?

Xcode’s project editor has an Info section for the app target, where you can add the settings. Take the following steps to access the Info section:

Select your project from the project navigator on the left side of the project window to open the project editor.
Select your app from the target list on the left side of the project editor.
Click the Info button at the top of the project editor.

At the top of the Info section is a Custom Target Properties list. To add an item to the Info section, move the mouse arrow over one of the keys in the list. Tiny buttons to add and remove an item will appear on the right side of the key where the mouse arrow is. Click the Add (+) button to add a setting to the Info section.

Dealing with the init(destination:tag:selection ) was deprecated in iOS 16.0 message

Thu, 14 Dec 2023 19:36:59 +0000

People starting out with SwiftUI development may get a message like the following from Xcode when building their project:

`init(destination:isActive:label:)’ was deprecated in iOS 16.0: use NavigationLink(value:label:) inside a NavigationStack or NavigationSplitView

‘init(destination:tag:selection????️ )’ was deprecated in iOS 16.0: use NavigationLink(value????️ ), or navigationDestination(isPresented:destination:), inside a NavigationStack or NavigationSplitView

Why are you getting this message?

You are getting this message because you are using NavigationView in your user interface.

The original version of SwiftUI used navigation views to navigate from one screen to another in an app and for master-detail interfaces with split views on iPad. In iOS 16 Apple replaced NavigationView with NavigationStack and NavigationSplitView for navigation.

The message is telling you to replace NavigationView in your app with either NavigationStack or NavigationSplitView.

NavigationStack and NavigationSplitView don’t run on earlier iOS versions. If you want your SwiftUI app to run on iOS 15, you must use NavigationView.

Is the message a problem?

Not currently. The message is a compiler warning, not an error. Your project will build and run, assuming there are no errors in the rest of your code.

Eventually Apple will stop supporting iOS 15. A future version of Xcode will drop support for building an app that runs on iOS 15. For reference Xcode 14 does not support iOS versions older than iOS 11. When Apple releases a version of Xcode that does not support building an app that runs on iOS 15, the message will be a problem.

How do you remove the message?

Use either NavigationStack or NavigationSplitView instead of NavigationView in your app. Apple provides the following guide to migrate code from NavigationView:

Migrating to new navigation types

If you are following a tutorial that uses NavigationView, find a more recent tutorial that uses the newer navigation APIs.

Dealing with Core Data Duplicate Class Errors

Mon, 20 Nov 2023 18:23:29 +0000

Many people learning Core Data take the following steps when creating their first Core Data app:

Create a new Xcode project that uses Core Data.
Create Code Data entities and relationships in Xcode’s data model editor.
Create subclasses for their entities by choosing Editor > Create NSManagedObject Subclass in Xcode.

They build the project and get the following build error:

Invalid redeclaration of Entity

Where Entity is the name of a Core Data entity.

What Causes the Error?

When you create a new Xcode project that uses Core Data, Xcode is set to automatically create NSManagedObject subclasses for your Core Data entities. Xcode creates the subclasses when you build the project.

The source code files Xcode creates are in the project’s derived data location. You can’t see the files in the left side of the project window like the other source code files in your project. You’re not meant to access and edit the source code files Xcode creates for your Core Data entities. The point of Xcode creating the files is to automatically update the files when you make changes to the data model.

If you create NSManagedObject subclasses from Xcode’s Editor menu, you wind up with two files for each subclass: the one Xcode automatically generates and the one you create.

When you have two classes with the same name, Xcode gives you the “Invalid redeclaration” error, and your project won’t build.

How do You Fix the Error?

There are two ways to fix the error. The first way is to remove the class files you added and let Xcode generate the classes for you.

The second way is to tell Xcode not to generate class files for your Core Data entities by choosing Manual/None from the Codegen menu in Xcode’s data model inspector. Choose View > Inspectors > Data Model in Xcode to access the data model inspector. Read the following article for screenshots and more details on Core Data class generation options:

Core Data Code Generation

Highlighting the Selected Item Button in a SwiftUI List

Mon, 09 Oct 2023 17:55:44 +0000

If you use a button for list items in SwiftUI, the list item does not highlight when you select it. This is expected behavior for a bordered button. But some apps need to use buttons that look like text to perform actions when selecting the list item. If you have a button that looks like text, you want to highlight the selection so people can easily see the selected item.

How do you highlight the selected item? You must do two things to highlight the selected item. First, you must set the background color for the list row. Second, you must set the foreground color for the list item.

Setting the Background Color

Add a .listRowBackground modifier to the button to set the background color. Use the accent color for the selected item to highlight it and the clear color for the other items to match the standard selection highlighting.

.listRowBackground(self.selection == item ? Color.accentColor : Color(.clear))

Setting the Foreground Color

When you select an item from a SwiftUI list in an app running in light mode, the text color for the item changes from a dark color to a light color. You must set the color based on the current color scheme or else the text of the selected item will be tough to read.

Start by adding an @Environment property to your SwiftUI view that stores the current color scheme: light or dark.

@Environment(\.colorScheme) private var colorScheme

Next, create computed properties for the item color based on whether or not it’s selected. Use white for the selected item. For unselected items make the text white in dark mode and black in light mode.

var unselectedItemTextColor : Color {
  return (colorScheme == .dark ? Color(.white) : Color(.black))
}
        
var selectedItemTextColor : Color {
  return Color(.white)
}

Finally add a .foregroundColor modifier to the button. Use the selected item color for the selected item and the unselected item color for the other items.

  .foregroundColor(self.selection == item ? selectedItemTextColor : unselectedItemTextColor)

Creating a SwiftUI Toolbar Button with an Image and a Label

Mon, 02 Oct 2023 19:30:30 +0000

Many toolbar buttons in Mac and iOS apps include an image and a label. The Mac apps Finder, Mail, and Pages are examples of apps whose toolbar buttons have an image and a label.

If you try to create a button in a SwiftUI toolbar with an image and a label, you will notice the label does not appear. You must do the following to create a toolbar button with an image and a label:

Create a label style for the button.
Add a .labelStyle modifier to your button label and use the label style you created.

Creating a Label Style

To create a label style, you must create a struct that conforms to the LabelStyle protocol. Add a makeBody function to the struct that returns a SwiftUI view.

A label style for a toolbar button should create a VStack with the image first and the text label second. Supply a font to use for the image and the label in the VStack.

struct VerticalLabelStyle: LabelStyle {
  func makeBody(configuration: Configuration) -> some View {
    VStack {
      configuration.icon.font(.headline)
      configuration.title.font(.footnote)
    }
  }
}

Add the .labelStyle Modifier

After creating the label style for your toolbar button, add a .labelStyle modifier to the button’s label and supply the name of the struct you created for the label style. The following code shows an example of a SwiftUI button that uses a custom label style:

Button(action: {
  isPublishing = true
}, label: {
  Label("Publish", systemImage: "book.closed.fill")
    .labelStyle(VerticalLabelStyle())
}).accessibilityLabel("Publish Book")

Credits

The answer from Eduardo to the following Stack Overflow question helped me with the code for this article:

Add Button with Image and Text in ToolbarItem SwiftUI

Adding a Help Menu to a SwiftUI App

Mon, 11 Sep 2023 17:56:46 +0000

When you create and run a SwiftUI Mac app project, the Help menu has a menu item named AppName Help, where AppName is the name of your app. If you choose that menu item, an alert opens saying help isn’t available for the app.

Help Books

The included menu item works only if your app has a Help Book bundled in the app. Many of Apple’s apps have Help Books. Choose Help > Xcode Help in Xcode to see an example of a Help Book.

Creating Help Books is painful. Apple’s Help Book Programming Guide was last updated in 2013, and there aren’t many articles online on creating Help Books.

Take Users to Your Site

For most apps it’s easier to add a page to your app’s website with your app’s help and add a menu item to go that page. You can even include a link on the page for people to download a user guide for your app. Creating a menu item that takes someone to your site involves the following steps:

Create a view for the menu item.
Create a SwiftUI link for the menu item.
Add the menu item to the menu bar.

Creating the Link and Menu Item

A SwiftUI link takes two arguments. The first argument is the link name, which is the menu item text for menus. The second argument is the link destination. The following code shows an example of a menu item with a link:

struct HelpMenu: View {
  var body: some View {
    Group {
      Link("Your App Website", destination: URL(
        string: "https://www.your-site.com/your-app/")!)
      // Place other Help menu items here.
    }
	}
}

Adding the Menu Item to the Menu Bar

Add a .commands modifier to the window group or document group in the App struct for your app. Add a command group for the menu, replacing the default Help menu item with your Help menu items.

.commands {
  CommandGroup(replacing: .help) {
    HelpMenu()
}

Do you want to add a help book to your app?

Earlier in this article I mentioned that creating a help book for a Mac app is painful. To help developers deal with this pain, I’m developing Phel, an app that creates help books from Markdown files.

Write your help pages in Markdown, import the help pages and images, hit the Publish button, and get an indexed help book you can add to your Xcode project.

You can download and try Phel at the Phel page.

Showing a SwiftUI sheet from a Mac Menu

Wed, 30 Aug 2023 19:13:28 +0000

Most articles on showing sheets in SwiftUI apps show an example of a button with a .sheet modifier that shows the sheet. But if you try to apply the example to a menu in a Mac app,

struct PreviewMenu: View {
  @State private var isPreviewing = false
            
  var body: some View {
    Button(action: {
      isPreviewing = true
    }, label: {
      Text("Preview")
    })          
    .sheet(isPresented: $isPreviewing) {
      PreviewView()
    }
  }
}

The sheet does not appear when you choose the menu item. How do you show the sheet when someone chooses the menu item?

Add a focused value for showing the sheet.
Set the focused scene value in your main view.
Add the menu item to show the sheet.
Add the menu item to the app’s menu bar.

Read the Accessing the Document in a SwiftUI Menu article to learn more about focused values and working with SwiftUI menus.

Add a Focused Value

Add a focused value that your app uses to control whether or not to show the sheet. In this article I’m going to use the example of a menu item that previews some content in a sheet.

struct ShowPreviewKey: FocusedValueKey {
  typealias Value = Binding<Bool>
}
    
extension FocusedValues {
  var showPreview: Binding<Bool>? {
    get { self[ShowPreviewKey.self] }
    set { self[ShowPreviewKey.self] = newValue }
  }
}

Set the Focused Scene Value

After creating the focused value to show the sheet, you must make that value a focused scene value to show the sheet from a menu. Start by adding a property to the main SwiftUI view.

@State private var showingPreview: Bool = false

The next step is to add a .focusedSceneValue modifier to the view. The first argument is the name of the variable you created for the focused value. The second argument is a binding using the property you created in the view.

.focusedSceneValue(\.showPreview, $showingPreview)
.sheet(isPresented: $showingPreview) {
  PreviewView()
}

Apple added the .focusedSceneValue modifier in macOS 12.

Add the Menu Item

Menus in SwiftUI apps are SwiftUI views. To show a sheet from the menu, start by creating a property with the @FocusedValue property wrapper that contains the focused value to show the sheet.

Create a button for the menu item. The action for the button is to set the focused value’s wrapped value. The focused value for showing a sheet is a Boolean value so you give it the value of true, which shows the sheet when someone chooses the menu item.

struct PreviewMenu: View {
  @FocusedValue(\.showPreview) private var showPreview
            
  var body: some View {
    Button(action: {
      showPreview?.wrappedValue = true
    }, label: {
      Text("Preview")
    })
    .disabled(showPreview == nil)    
  }
}

Add the Menu to the App

After creating the menu you must add it to your app’s menu bar. Add a .commands modifier to the app’s window group or document group to add the menu to the menu bar.

.commands {
  // Replace .newItem with wherever you want to insert your menu item.
  CommandGroup(after: .newItem) {
    PreviewMenu()
  }
}

Credits

Thanks to Jason Armstrong for his answer to the following Stack Overflow question:

Calling a sheet from a menu item

Showing Local HTML Content in a WKWebView

Mon, 07 Aug 2023 18:20:56 +0000

Apple provides the WKWebView class to show web content in Swift apps. Most apps use web views to show content from websites, but you can also show local HTML in a web view. There are two common ways to show local HTML in a web view.

Loading HTML strings
Loading HTML files

Loading HTML Strings

The easiest way to display HTML content in a web view is to create a string for the HTML and call the loadHTMLString function.

var html: String
    
webView.loadHTMLString(html, baseURL: nil)

A common reason to load an HTML string is to preview Markdown content. You can see examples of loading HTML strings in my WikiDemo and SwiftUIMarkdownEditor GitHub projects.

The biggest limitation of loading HTML strings and showing them in a web view is that images will not show. Inserting images in a HTML string is a security risk so the web view won’t display them.

Loading HTML Files

If you want to show images in a web view, you must create a HTML file and show it in the web view by calling the loadFileURL function. The function takes two arguments. The first argument is the URL of the file to show in the web view. The second argument is a URL that you give the web view access to read. You normally give read access to a folder that contains subfolders you want to show, such as image and CSS files.

I recently added code in an app to preview EPUB books in a web view. An EPUB book has an OEBPS folder that holds most of the book’s content. The OEBPS folder has the following subfolders:

A Text folder that contains the book’s chapters.
An Images folder that contains the book’s images.
A Styles folder that contains any CSS files to style the book.

To preview the book I needed to pass the URL of the current chapter’s HTML file as the first argument to loadFileURL and the URL of the OEBPS folder as the second argument. Giving the web view access to the OEBPS folder gives the web view access to the images and CSS files.

var bookURL: URL
var currentChapterFilename: String
    
let oebpsFolder = bookURL.appendingPathComponent("OEBPS")
let textFolder = oebpsFolder.appendingPathComponent("Text")
let chapterFile = textFolder.appendingPathComponent(currentChapterFilename)
webView.loadFileURL(chapterFile, allowingReadAccessTo: oebpsFolder)

Running a Mac App Outside of Xcode

Mon, 31 Jul 2023 18:56:53 +0000

When you are developing a Mac app, you run it often from Xcode. But eventually you will run it outside of Xcode. You have two ways to run a Mac app outside of Xcode.

Locate the build folder
Archive and export the project

Locate the Build Folder

If you’re actively developing your app, locating the app from its build folder is the easiest way to run the app outside of Xcode. In Xcode choose Product > Show Build Folder in Finder to show the app’s build folder.

Go to the Finder. The app will be in a folder inside the Products folder. Usually the name of the folder is Debug or Release.

Archive and Export the Project

When you have your app at a point where you can use it regularly on your Mac or share with other people, you should archive and export the project to create an app file that is not buried deep inside Xcode’s Derived Data folder.

In Xcode choose Product > Archive to archive the project. Xcode’s Organizer window contains your app archives. Choose Window > Organizer in Xcode to open the Organizer.

Click the Archives item on the left side of the Organizer to show your app’s archives. If you have archived multiple projects, you may have to choose your app from the app menu that is above the Archives item.

Select the archive from the archive list and click the Distribute App button to export the archive. When you click the Distribute App button, a sheet opens asking you to choose a method of distribution. Xcode provides the following distribution methods:

App Store Connect
Developer ID
Development
Copy App

The first two methods require a paid Apple developer membership. I’m not sure about the Development method. If you don’t have a paid membership or are making an app for personal use, choose Copy App and click the Next button. Choose a location to save the app and click the Export button.

Now you have an app file that you can run on your Mac just like any other app. You can also use the file to copy the app to another Mac.

The Other Distribution Methods

The App Store Connect distribution method is for apps that are going to be in the Mac App Store.

The Developer ID distribution method is for apps that you are going to have people download from your own website. When you choose Developer ID, Apple notarizes the app so that people who download and install your app can trust it. The How to Notarize a Mac App article has more details on the Developer ID distribution method.

The Development distribution method is for creating an app file to share with people you know. When I tried the Development distribution method for a Mac app, I saw no difference between the Development and Copy App distribution methods.

Scene Editor Development: Showing a SwiftUI View Based on a Selection

Mon, 17 Jul 2023 18:34:39 +0000

The inspector for the scene editor has separate SwiftUI views for each kind of item in a SpriteKit scene. There’s a sprite inspector for sprites, a label inspector for labels, and so on.

When someone selects an item from the scene graph, the inspector should show the correct view. If someone selects a sprite, the inspector view should show the sprite inspector. How do you show the correct view based on the selection?

My solution is to get the class name for the selected item, add a switch statement to the view body, and show the correct view based on the class name.

Getting the Class Name

The inspector has a property that contains the selected item from the scene graph.

@State var node: SKNode

Because each kind of item in a SpriteKit scene has its own class, I can get the name of the class for the node property and show the correct view based on the name of the class.

NSObject is the base class for every SpriteKit class. The NSObject class has a nameOfClass property for Mac, but not iOS. But I saw on Stack Overflow that you can add an extension to NSObject to get the name of the class on iOS.

public extension NSObject {
  class var nameOfClass: String {
    return NSStringFromClass(self).components(separatedBy: ".").last!
  }
    
  var nameOfClass: String {
    return NSStringFromClass(type(of: self)).components(separatedBy: ".").last!
  }
}

Adding a Switch Statement to the SwiftUI View

Now that I can get the names of the SpriteKit classes, I can add a switch statement in the SwiftUI view body and show the correct view based on the class of the selected item in the scene graph.

struct Inspector: View {
  @State var node: SKNode
        
  var body: some View {
    switch node.nameOfClass {
    case "SKSpriteNode":
      SpriteInspector(node: node as! SKSpriteNode)
    case "SKLabelNode":
      LabelInspector(node: node as! SKLabelNode)
    case "SKLightNode":
      LightInspector(node: node as! SKLightNode)
    // Other SpriteKit classes go here.
    default:
      EmptyView()
    }
  }
}

I can safely cast with as! because I know the class of the selected item.

Using ReferenceFileDocument to Save SwiftUI Documents

Mon, 26 Jun 2023 17:59:45 +0000

When you create a SwiftUI Document App project, the Swift file for the document contains a struct for the document that conforms to FileDocument. Using a struct for the document works in most cases, but you can make the document a class by conforming to ReferenceFileDocument.

When to Make Your SwiftUI Document a Class

The most common reason to use a class for a SwiftUI document is to update SwiftUI views when a property in the document changes. Using the @Published property wrapper for a property triggers updates to SwiftUI views when the property’s value changes. But the @Published property wrapper works only for classes.

If you are going to pass the document to many views, it can be more effective to make the document a class and use @StateObject, @ObservedObject, or @EnvironmentObject to pass the document to other views.

If you can’t mark the document as changed when using a struct, you can mark the document as changed by making the document a class and registering with the undo manager.

Changing the Document from a Struct to a Class

Apple’s Swift file for the document creates a struct.

struct Document: FileDocument

You must make the following changes to change the document from a struct to a class:

Change struct to class
Change FileDocument to ReferenceFileDocument
Have the document conform to ObservableObject

class Document: ReferenceFileDocument, ObservableObject

Creating a Snapshot

You must add a snapshot function to your document’s class to use ReferenceFileDocument. The snapshot function creates a snapshot of the document’s current state that SwiftUI uses to save the document.

func snapshot(contentType: UTType) throws -> GameScene {
  return self.scene
}

Replace GameScene with the data type your document saves. Replace scene with a property in your document class.

Marking the Document as Changed

If you find your document isn’t marked as changed when you make changes to the document, register your document with the undo manager by calling the registerUndo function. Usually you call registerUndo from a view’s .onAppear modifier.

// Add this property to the SwiftUI view.
@Environment(\.undoManager) var undoManager
    
.onAppear {
  undoManager?.registerUndo(withTarget: document, handler: {
  // Use the handler to do anything your app
  // needs to do when registering the undo.
  print($0, "undo")
  })
}

Acknowledgements

The answers to the following questions on Stack Overflow helped me write this article:

Scene Editor Development: Unable to Open Scenes

Mon, 19 Jun 2023 18:40:56 +0000

I ran into a problem where I was unable to open the scenes I created in the editor. When I choose File > Open in the Mac version, the scene file is disabled. The scene file appears to save as the wrong type.

The Document Type and UTIs

The scene editor saves scenes as binary property lists. I used the following identifier for the document type, imported UTI, and exported UTIs:

com.apple.binary-property-list

That identifier is the UTType for binary property lists.

The type conforms to the following UTI:

com.apple.property-list

I set the file extension for the UTIs to .sks.

The Problem

When I saved a scene I got the following error message in Xcode’s console:

Error Domain=NSCocoaErrorDomain Code=256 “The autosaved document “TestScene” could not be reopened. SpriteKit Editor cannot open files in the “property list” format.”

I also noticed the saved scene had the extension .plist instead of .sks.

The Solution

I created a custom identifier for the document type and UTIs. The document type conforms to the binary property list type, com.apple.binary-property-list.

Scene Editor Development: Saving with NSKeyedArchiver

Tue, 30 May 2023 18:18:40 +0000

In the last article, I wrote about how I couldn’t use the PropertyListEncoder class to save scenes because SpriteKit’s classes don’t conform to the Codable protocol. I have to use NSKeyedArchiver to save the scenes, and that’s what I’m going to write about in this article.

Using NSKeyedArchiver

Archiving data with NSKeyedArchiver requires one function call. Call the class function archivedData. Supply a root object and whether or not the archive requires secure coding. You should set the second argument to true. I used the following initial code to archive a scene:

let sceneData = try NSKeyedArchiver.archivedData(withRootObject:
  GameScene.self, requiringSecureCoding: true)

Calling the archivedData function is enough in most cases. But I also had to say that my SKScene subclass supports secure coding.

override static var supportsSecureCoding: Bool {
  get {
  	return true
  }
}

Problem 1: Unrecognized Selector Error

When I saved the scene, the app would crash with the following error message in Xcode’s console:

+[SpriteKit_Editor.GameScene encodeWithCoder:]: unrecognized selector sent to class 0x10cb6aa60

The error message is saying that my GameScene class does not have an encodeWithCoder function. The cause of the error is I was passing my SKScene class as the root object instead of the scene itself. Passing the scene as the root object fixed the error.

let sceneData = try NSKeyedArchiver.archivedData(withRootObject:
  scene, requiringSecureCoding: true)

Problem 2: Root Object Has the Wrong Class

I wanted to see if I could load a scene I saved in a SpriteKit game project. I created a test project in Xcode, added a scene I created in the editor, and tried to load the scene with the following code:

currentScene = SKScene(fileNamed: "TestGameScene")!

The app crashed with the following error message in Xcode’s console:

Terminating app due to uncaught exception ‘NSInvalidUnarchiveOperationException’, reason: ‘*** -[NSKeyedUnarchiver decodeObjectForKey:]: cannot decode object of class (SpriteKit_Editor.GameScene) for key (root) because no class named “SpriteKit_Editor.GameScene” was found; the class needs to be defined in source code or linked in from a library (ensure the class is part of the correct target). If the class was renamed, use setClassName:forClass: to add a class translation mapping to NSKeyedUnarchiver’

The error message says the type of the root object in the archive is the SKScene subclass in the scene editor app when it needs to be SKScene. I have to archive the scene as type SKScene.

My first attempt was to cast the scene as type SKScene.

let sceneData = try NSKeyedArchiver.archivedData(withRootObject: 
  scene as SKScene, requiringSecureCoding: true)

But I got the same crash when trying to load the scene in a SpriteKit project.

My second attempt was to create a SKScene variable and archive that variable.

let skScene: SKScene = scene
let sceneData = try NSKeyedArchiver.archivedData(withRootObject: 
  skScene, requiringSecureCoding: true)

That did not fix the error.

The solution is to call the setClassName function to tell the archiver to save the scene as type SKScene. The following code saves the scene correctly:

func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
  NSKeyedArchiver.setClassName("SKScene", for: GameScene.self)
  let sceneData = try NSKeyedArchiver.archivedData(withRootObject: 
  	scene, requiringSecureCoding: true)
  return .init(regularFileWithContents: sceneData)        
}

Pleasant Surprise: BBEdit Can Show Binary Property Lists

I learned that the text editor BBEdit shows binary property lists as XML files. Now I don’t have to worry about being unable to examine the contents of the scene. I can save the scenes as binary property lists and view them in BBEdit. I can also view the scene in Xcode as a SpriteKit scene.

Unarchiving the Scene

To open scenes in the scene editor, I have to add support for unarchiving the data. To support unarchiving I use the NSKeyedUnarchiver class. I have to set the class name to treat the SKScene root object as an object of my subclass. The last step is to call the unarchivedObject function to read the archived data and create an instance of my subclass from the data. The following code loads the scene document:

init(configuration: ReadConfiguration) throws {
  guard let data = configuration.file.regularFileContents
                
  else {
      throw CocoaError(.fileReadCorruptFile)
  }
            
  NSKeyedUnarchiver.setClass(GameScene.self, forClassName: "SKScene")
  scene = try NSKeyedUnarchiver.unarchivedObject(ofClass: 
    GameScene.self, from: data) 
    ?? GameScene(size: CGSize(width: 2048, height: 1536))
}

Scene Editor Development: Trouble Conforming to Codable

Mon, 22 May 2023 17:32:39 +0000

For a SpriteKit scene editor to be usable, it must be able to save scenes.

Choosing a File Format

SpriteKit scene files are binary property lists with the extension .sks. At the very least the scene editor must be able to export scenes as binary property lists.

During development I would like to view a saved scene’s data in a text editor to make sure everything saves correctly. The Foundation framework supports saving property lists as XML or binary so I decided to save the scenes as property lists. Start by saving as XML and switch to binary later in development.

PropertyListEncoder

Looking through Apple’s documentation I saw the Foundation framework has PropertyListEncoder and PropertyListDecoder classes to save and load property list files. I wrote the following code to save a scene:

func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
  let propertyListEncoder = PropertyListEncoder()
  propertyListEncoder.outputFormat = .xml
  let sceneData = try propertyListEncoder.encode(scene)
            
  return .init(regularFileWithContents: sceneData)
}

Saving to a property list requires only three lines of code. Create an instance of PropertyListEncoder, set the output format, and call the encode function.

If you need to save data in a property list in your app, start by using PropertyListEncoder. But I ran into problems when I tried to use PropertyListEncoder in the scene editor.

SpriteKit Classes Don’t Conform to Codable

To encode data with PropertyListEncoder, the data you are encoding must conform to the Codable protocol. SpriteKit classes don’t conform to Codable.

I searched online to see if there was a way to make SpriteKit classes conform to Codable. To make a struct or class conform to Codable, the struct or class must implement the following functions:

required init(from decoder: Decoder) throws {
    
}
    
func encode(to encoder: Encoder) throws {
    
}

I tried creating a class extension file for the SKScene class and learned I cannot add a required initializer in a class extension file. Since I don’t have access to the source code files for Apple’s SpriteKit framework, I can’t make SpriteKit classes conform to Codable.

Use NSKeyedArchiver to Save Scene Data

Because SpriteKit classes don’t conform to Codable, I can’t use PropertyListEncoder to save scenes as property lists. I have to use NSKeyedArchiver. I will cover using NSKeyedArchiver in the next article.

Scene Editor Development: Saving with NSKeyedArchiver

Scene Editor Development: SwiftUI Navigation Issues

Mon, 15 May 2023 17:49:30 +0000

I have the following main view in the scene:

struct ContentView: View {
  @Binding var document: Level
    
  var body: some View {
    NavigationView {
      SceneGraph(document: $document)
      SpriteView(scene: document.scene)
      Inspector(node: SKNode())
    }
  }
}

When selecting an item from the scene graph, I want to show the details in the inspector. I created a navigation link to do this.

List {
  ForEach(gameScene.children, id: \.self) { node in
    NavigationLink(destination: Inspector(node: node), tag: node, 
      selection: $selection) {
                            
      Text(node.name ?? "Node")
    }
  }
}

The problem is that when I select an item from the scene graph, the inspector replaces the sprite view.

NavigationSplitView

I took a look at the new NavigationSplitView view Apple added in iOS 16 and macOS 13 to handle the navigation. But I found the three column view doesn’t suit this app.

The behavior of a three column split view is that selecting an item from the first column affects the second column, and selecting an item from the second column affects the third column.

But I don’t want someone to have to select an item from the sprite view (scene canvas) to view it in the inspector. Selecting an item from the scene graph should show the details in the inspector.

Workaround

The workaround is to move the sprite view from the center column to the left column. Now the navigation link from the scene graph to the inspector works the way I want it to work.

For now I’m sticking with NavigationView to support iOS 15, which has a version of Swift Playgrounds that can make apps. It also allows me to support macOS 11+. But I may switch to a two column navigation split view if I need it.

Scene Editor Development: Updating a SwiftUI List When Adding an Item

Mon, 08 May 2023 17:28:57 +0000

This article talks about the first big problem I encountered when starting to develop a SpriteKit scene editor in SwiftUI. It’s a problem every SwiftUI developer has seen: a view doesn’t update when the data changes.

Initial Code

My initial idea for the scene editor interface was to have a split view with three columns.

A scene graph to show the items in the scene
A canvas to place items in the scene
An inspector to view and edit details for an item

I started with the following SwiftUI view:

struct ContentView: View {
  @Binding var document: Level
    
  var body: some View {
    NavigationView {
      SceneGraph(document: $document)
    	SpriteView(scene: document.scene)
      Inspector()
    }
  }
}

I used a SwiftUI sprite view for the canvas.

The document struct has a property that holds a SpriteKit scene.

struct Level: FileDocument {
  var scene: GameScene
}

GameScene is a subclass of SKScene, SpriteKit’s scene class.

The scene graph looks like the following:

struct SceneGraph: View {
  @Binding var document: Level
        
  var body: some View {
    List {
      ForEach(document.scene.children, id: \.self) { item in
        Text(item.name ?? "Node")
      }
                
    }
  }
}

My Initial Goal

My initial goal was to add a sprite to the scene by clicking or tapping on the canvas. The sprite’s location is the location of the click or tap. Adding the sprite also adds an item to the scene graph.

Problem: The SwiftUI List Doesn’t Update when Adding an Item

I ran the app and tried adding sprites to the canvas. The sprites appeared on the canvas, but the scene graph was empty.

I stepped through the code in the debugger and saw that the new sprites were in the scene’s array of children. When I saved the document the sprites appeared in the scene graph.

Adding sprites works, but the scene graph doesn’t update. This is a common problem SwiftUI developers run into. The user interface doesn’t update when the data changes.

Fix Attempts that Didn’t Work

There are two common approaches to get the user interface to update when the data changes. First, if your data model uses structs, use @State and @Binding.

Second, if your data model uses classes, make the class conform to ObservableObject. Add the @Published property wrapper to class members that you want to trigger a UI update when the member’s value changes.

I tried the following things to get the scene graph to update when adding a sprite to the scene:

Make GameScene conform to ObservableObject.
Add a @Published variable to GameScene that holds an array of the scene’s items, have GameScene conform to ObservableObject, and have the scene graph show the array of scene items.
Make Level a class with a @Published property for the scene and use @StateObject instead of @Binding in the scene graph.
Add a @Published variable that tracks whether the scene was edited and set it to true when placing the sprite.
Add a refresh ID to the GameScene class and change it when placing the sprite.
Add a refresh ID to the Level struct and change it when clicking on the canvas.
Add a property for the level to the GameSceneclass.
Give the scene graph a binding to a game scene instead of a level.
Give the scene graph a @StateObject property for the scene.

None of these attempts updated the scene graph after adding a sprite to the canvas.

The Solution

I struggled to fix this problem for weeks. Finally I asked a question on Reddit about the problem and learned what the problem was. The problem has two parts.

First, SwiftUI’s data flow system does not automatically track changes in SpriteKit scenes. I have to manually trigger changes when the scene changes.

Second, The binding for the level in the scene graph won’t trigger an update unless I make the level show a new scene. The app is a scene editor so I am never going to change the scene in a level. Because I don’t change scenes in a level, any changes I make to the level will not trigger a UI update.

The solution to the problem has the following parts:

Make GameScene conform to ObservableObject.
Send an objectWillChange message after placing the sprite.
Add a private property for the scene to the scene graph with the @ObservedObject property wrapper.
Add a private property for the level.
Use the private property for the scene in the ForEach block.

Sending the objectWillChange message required adding one line of code.

self.objectWillChange.send()

I had to add the following code to the SceneGraph struct:

private var document: Level
@ObservedObject private var gameScene: GameScene
        
init(document: Level) {
  self.document = document
  self.gameScene = document.scene
}

The final thing I had to do was change the code of the ForEach block for the list to the following:

ForEach(gameScene.children, id: \.self) { item in
  Text(item.name ?? "Node")
}

SwiftUI Open and Save Panels

Thu, 04 May 2023 17:56:29 +0000

AppKit has the NSOpenPanel and NSSavePanel classes to let people choose files to open and save in Mac apps. What is the SwiftUI equivalent to NSOpenPanel and NSSavePanel?

SwiftUI has .fileImporter and .fileExporter modifiers to let people choose files to open and save. Apply the modifier to a SwiftUI view, such as a button or a menu item. The .fileImporter and .fileExporter modifiers are available on both iOS and Mac.

File Importers

You must provide the following to .fileImporter:

A Boolean value that determines whether or not to show the panel
A list of allowed file types to open
A completion handler that runs when the panel closes

The following code lets someone open an image file:

@State private var isImporting: Bool = false
    
Button(action: {
  isImporting = true
}, label: {
  Text("Import Image")
})
.fileImporter(isPresented: $isImporting, 
  allowedContentTypes: [.png, .jpeg, .tiff], 
  onCompletion: { result in
                
  switch result {
  case .success(let url):
    // url contains the URL of the chosen file.
    let newImage = createImage(imageFile: url)
  case .failure(let error):
    print(error)
  }
})

If the person chooses a file and clicks the Open button, the result is .success, and the file importer provides the URL of the chosen file for you.

File Exporters

You must provide the following to .fileExporter:

A Boolean value that determines whether or not to show the panel
The document to export
The file type for the exported file
A completion handler that runs when the panel closes

You can also supply a default file name to the file exporter.

The following code exports a document to EPUB:

@State private var isPublishing: Bool = false
    
Button(action: {
  isPublishing = true
}, label: {
  Text("Publish")
})
.fileExporter(isPresented: $isPublishing,
  document: book,
  contentType: .epub,
  defaultFilename: book.title) { result in
             
  switch result {
  case .success(let url):
    book.publishEPUB(location: url)
  case .failure(let error):
    print(error)
  }
}

If the person chooses a location to save the file and clicks the Export button, the result is .success, and the file exporter provides the URL of the chosen file for you to write data from your app to the file.

Scene Editor Development: Intro

Mon, 01 May 2023 17:53:45 +0000

As a fun side project, I’m starting to develop a SpriteKit scene editor for iPad and Mac using SwiftUI. I decided to write about the development of this project.

This post is the first in a series of posts. Future posts will be more technical than this one.

Why Make a SpriteKit Scene Editor?

Doesn’t Xcode include a SpriteKit scene editor? Yes it does.

So why make a SpriteKit scene editor?

The Swift Playgrounds app lets people make SpriteKit games on an iPad. Use a SwiftUI sprite view to display a SpriteKit scene, and you can make a 2D game on an iPad.

Swift Playgrounds does not include a scene editor so you must build your scenes in code if you have only an iPad. By making a scene editor people on an iPad can create scenes for a game visually.

What Will I Write About?

Most of the time I’ll be writing about a problem I faced and how I solved it. I think that will interest the most people, solving problems in SwiftUI apps.

Where Can I Download the Editor?

The editor currently isn’t available to download because it’s not usable. Right now I’m in a prototyping stage to see what I can do with SwiftUI. I would also like to find a good name for the editor before I release an early version.

When I have the editor ready for others to use, I’ll make it available to download.

Keep in mind that progress may be slow at times. This is a side project that does things that not many SwiftUI apps do. Doing unusual things makes finding solutions to problems more difficult because people haven’t written articles or asked questions about them.

Scene Editor Development Article List

Working on a SwiftUI Project in Xcode and Swift Playgrounds

Fri, 14 Apr 2023 18:39:30 +0000

You have a Mac with Xcode and an iPad with Swift Playgrounds. You have a project that you want to develop using both devices. How do you create a project that you can edit in both Xcode and Swift Playgrounds?

Create a Swift Playgrounds App project in Xcode. This project template is designed to work in both Xcode and Swift Playgrounds.

The Swift Playgrounds App project is in the iOS section of the New Project Assistant in Xcode.

Scrolling a SwiftUI Sprite View

Thu, 30 Mar 2023 18:38:43 +0000

SwiftUI provides a sprite view to show a SpriteKit scene in a SwiftUI app. Supply a SpriteKit scene to the sprite view.

struct ContentView: View {
  @State var currentScene: SKScene = GameScene(size: 
    CGSize(width: 2048, height: 1536))
        
  var body: some View {
    SpriteView(scene: currentScene)
  }
}

SwiftUI provides a scroll view to scroll content that won’t fit in the main SwiftUI view. Place the sprite view inside the scroll view to scroll the scene.

var body: some View {
  ScrollView {
    SpriteView(scene: currentScene)
  }
}

If you build and run this code, you will notice the scroll view covers the sprite view so you can’t see the sprite view or interact with it. How do you keep the scroll view from blocking the sprite view?

Add a .frame modifier to the sprite view.

var body: some View {
  ScrollView {
    SpriteView(scene: currentScene)
      .frame(width: 768, height: 768)
  }
}

If you want to scroll the scene horizontally and vertically, supply the scrolling directions in an array when creating the scroll view.

var body: some View {
  ScrollView([.horizontal, .vertical]) {
    SpriteView(scene: currentScene)
      .frame(width: 768, height: 768)
  }
}

Using a UIKit or AppKIt View in SwiftUI

Mon, 20 Feb 2023 18:48:41 +0000

When to Wrap a UIKit or AppKit View

There are two cases where you would wrap a UIKit or AppKit view in a SwiftUI app. The first case is your app needs a view that SwiftUI doesn’t have. If your app needs to show web content or a PDF file, you must use a WebKit web view or PDFKit’s PDF view. SwiftUI currently doesn’t have a native web view or PDF view.

The second case is your app needs to do something that a SwiftUI view can’t do. To let people edit rich text in your app, you must use UITextView or NSTextView. SwiftUI’s TextEditor view only allows plain text editing. Text views are a common control where you have to drop down to UIKit or AppKit because SwiftUI’s text editor is very limited currently.

Wrapping a UIKit or AppKit View

To wrap a UIKIt or AppKit view in a SwiftUI app, perform the following steps:

Create a struct that conforms to the UIViewRepresentable(iOS) or NSViewRepresentable(Mac) protocols.
Write a makeUIView or makeNSView function to create the UIKit or AppKit view.
Write an updateUIView or updateNSView function to handle view updates.

The following code creates a web view that displays HTML text:

import WebKit
import SwiftUI
    
struct WebView: UIViewRepresentable {
  var html: String
        
  init(html: String) {
    self.html = html
  }
        
  func makeUIView(context: Context) -> WKWebView {
    let webView = WKWebView()
    return webView
  }
        
  func updateUIView(_ uiView: WKWebView, context: Context) {
    uiView.loadHTMLString(html, baseURL: nil)
  }
}

Notice that makeUIView returns the view type. The view type is also the type of the first argument to updateUIView.

After creating the view struct, you can add the view as part of the body of a SwiftUI view the same way you would add one of SwiftUI’s native views.

Examples and Further Reading

I have a demo project on GitHub that wraps a web view in a multi-platform SwiftUI app.

The CodeEditor package wraps a text view that supports syntax highlighting. It’s a more complex example than my demo project.

The following articles have additional information on using UIKit and AppKit views in SwiftUI:

Storing a Swift Enum in Core Data

Mon, 13 Feb 2023 19:01:42 +0000

You must do the following to store a Swift enum in Core Data:

Create an enum with a raw value with a type Core Data can store, such as an integer or a string.
Add an attribute for the enum to the Core Data entity. Set the attribute’s type to the raw value type.
Add a computed property to the entity to convert the enum to and from the attribute’s raw value.

Creating the Enum

Core Data has no way of knowing your enum. That’s why you must give your enum a raw value type. Supplying a raw value type lets Core Data store the enum value.

The following code shows an enum for issue priorities whose raw value type is an integer:

enum IssuePriority: Int {
  case low = 1
  case medium = 2
  case high = 3
}

Core Data will save the integer values of the issue priorities.

Adding the Computed Property

Adding a computed property to the Core Data entity allows you to use the Swift enum in your code. The usual way to add a computed property is to create an extension for the Core Data entity type.

The computed property requires a getter and a setter. The getter creates an enum value from its raw value. The setter sets the raw value for the enum value.

The next example shows an Issue entity with a priorityLevel attribute of type Int64. The following code creates a computed property for the issue priority:

extension Issue {
  var priority: IssuePriority {
    get {
      return IssuePriority(rawValue: Int(self.priorityLevel)) ?? .low
    }
    set {
      self.priorityLevel = Int64(newValue.rawValue)
    }
  }
}

Now you can use the priority property to set issue priorities using the enum values.

When writing the setter make sure to use the same data type as the attribute in the Core Data model, Int64 in the example.

Fixing the Type () cannot conform to View Error in Swift

Mon, 23 Jan 2023 18:18:39 +0000

Why am I getting this error?

You are trying to do something inside the body of a SwiftUI view besides displaying views. Placing print statements in a SwiftUI view will give you this error. Using if statements to conditionally show a view may also generate this error.

Let’s look at a simple example that shows a name in a SwiftUI Text label.

struct ContentView: View {
  @State var name: String = ""
        
  var body: some View {
    name = "Angela"
    Text(name)
  }
}

The code in the example is trying to set the name to show inside the body computed property. But you can’t run arbitrary code, such as setting a variable’s value, inside the body property. The body property must return a SwiftUI view so the code generates the Type () cannot conform to View error.

Ways to fix the error

The easiest way to fix the error in the example is to set the name when creating the name variable.

@State var name: String = "Angela"
    
var body: some View {
  Text(name)
}

Use the .onAppear modifier to do something when a SwiftUI view appears. The following code changes the name correctly:

var body: some View { 
  Text(name)
    .onAppear {
      name = "Angela"
  }
}

You can also make the error go away by adding a return statement to explicitly return a view.

var body: some View {
  name = “Angela” 
  return Text(name)
}

Remove print statements from your SwiftUI views. If you need to print something to debug your app, use Xcode breakpoint actions to print to Xcode’s console.

If you need to do something in a SwiftUI view, move the code out of the body property to a separate function and call the function in the view.

Fixing the Thread 1: Fatal error: Unexpectedly found nil while implicitly unwrapping an Optional value error

Tue, 17 Jan 2023 18:49:30 +0000

Why am I getting this error?

You are getting this error because you are doing something with an optional value that is nil. The most common reasons for doing something with a nil optional value are the following:

You have an implicitly unwrapped optional
You have a disconnected outlet in a storyboard
You force unwrap an optional
You use as! to cast to a data type

Storyboard outlets are the most common use of implicitly unwrapped optionals.

The textView outlet has type UITextView!. Adding the ! character makes the outlet an implicitly unwrapped optional. A disconnected outlet has an empty circle in Xcode’s source code editor, as you can see in the image. Accessing a disconnected outlet crashes your app.

Force Unwrapping Example

The following code demonstrates force unwrapping by getting the contents of a file wrapper:

let data = file.regularFileContents!

Adding the ! after regularFileContents force unwraps the optional. If regularFileContents is nil, setting the data constant crashes the app.

Avoid force unwrapping because it can crash your app.

as! Example

The following code demonstrates using as! to cast to a data type:

func readFont(_ tagData: NSDictionary) -> NSFont? {
  let fontName = tagData["FontName"] as! String
  let fontSize = tagData["FontSize"] as! NSNumber
  let styleFont = NSFont(name: fontName, size: CGFloat(fontSize.floatValue))
  return styleFont
}

The function reads font data from a dictionary in a JSON file. The following line of code reads the font name:

let fontName = tagData["FontName"] as! String

If there isn’t an item in the dictionary with a key named FontName, the app crashes.

Ways to fix the error

Use guard statements to exit early if the optional value is nil.

guard let data = file.regularFileContents else {
	// Do anything you need to do if data is nil.
	return
}
    
// Do something with data, such as load it

Use if let statements to do something only if the optional value is not nil.

if let data = file.regularFileContents {
  // Do something with data
}

Use as? instead of as! to cast to a specific data type.

let fontName = tagData["FontName"] as? String

Use the ?? operator to provide a default value if the optional is nil. The following example returns an empty PDF document if you provide a nil URL to create a PDF document:

return PDFDocument(url: fileURL) ?? PDFDocument()

Check that the optional value is not nil before unwrapping it. This technique is less elegant than the others, but it will prevent the app from crashing.

let data = file.regularFileContents
if data != nil {
  // Do something with data
}

Make sure the outlets in your storyboards are connected. Open the Connections Inspector for the storyboard by choosing View > Inspectors > Connections.

The article Connecting UI Elements has detailed information on connecting outlets.

Additional Reading

Fixing the ForEach requires that T conform to Identifiable error in Swift

Wed, 11 Jan 2023 19:11:18 +0000

The actual error message is too long for an article title. The error message looks like the following:

Error: Referencing initializer ‘init (_:content:)’ on ‘ForEach’ requires that ‘T’ conform to ’Identifiable’

Where T is a struct or class.

Why am I getting this error?

You have a ForEach block that does not uniquely identify each item. The compiler needs a way to uniquely identify each item in the ForEach block. If you do not provide a way to uniquely identify the items, you get the error.

The most common cause of the error is the only argument you supplied to the ForEach is the collection of items, and the item’s struct or class does not conform to the Identifiable protocol.

ForEach(items) { item in
    
}

Ways to fix the error

The easiest way to fix the error is to provide an id argument to the ForEach and using \.self as the value.

ForEach(items, id: \.self) { item in
    
}

Another way to fix the error is to make the struct or class of the items in the ForEach conform to the Identifiable protocol. Add an id property to the struct or class that uniquely identifies each instance of the struct or class.

struct MyStruct: Identifiable {
  let id = UUID()
}

The call to UUID creates a unique identifier for each instance of the struct your app creates.

Fixing the “Async call in a function that doesn’t support concurrency” error in Swift

Thu, 05 Jan 2023 19:27:54 +0000

The error message may also say “Cannot pass function of type ‘() async -> Void’ to parameter expecting synchronous function type”.

Why am I getting this error?

You are using Swift’s async await syntax and calling an async function in a function that does not support async await. If you have the following function that calls an async function:

func myFunction() {
  await asyncFunction()
}

You are going to get the “Async call in a function that doesn’t support concurrency” build error because myFunction is not an async function.

Apple added async await support to Swift in 2021 so the support is relatively new. Many of Apple’s frameworks do not support the new async await syntax.

Apple’s ASWebAuthenticationSession class, which apps use to log into websites, does not support async await. When you create an instance of ASWebAuthenticationSession, you supply a completion handler that runs after a successful login. If you make an async function call in the completion handler, you’ll get the “Async call in a function that doesn’t support concurrency” build error.

Ways to fix the error

The most common way to fix the error is to place the call to the async function in a Task block.

Task {
  await asyncFunction()
}

If the error occurs in a function you wrote, you can fix the error by marking that function as async.

func myFunction() async {
  await asyncFunction()
}

Don’t forget to add await when calling the function you marked as async.

Replace Swift print Statements with Xcode Breakpoint Actions

Mon, 12 Dec 2022 19:11:30 +0000

When you run into problems with your Swift code, your first instinct may be to add print statements. There’s nothing wrong with print statements, but you can also use Xcode breakpoint actions to print to Xcode’s debug console. Using Xcode breakpoint actions instead of print statements has the following advantages:

You don’t have to write any code.
They fire only when debugging.
You can turn them on and off easily without having to rebuild your project.

Take the following steps to create a breakpoint action equivalent of a print statement.

Add a breakpoint.
Add a breakpoint action.
Choose Log Message from the breakpoint action menu.
Enter what you want to print in the text field.
Select the Automatically continue after running checkbox.

Add a Breakpoint

Click on the left side of Xcode’s editor next to the line of code where you want to set the breakpoint.

The breakpoint appears as a blue arrow in the editor.

Add a Breakpoint Action

Right-click on a breakpoint in Xcode’s editor or in Xcode’s breakpoint navigator (Press Cmd–8) and choose Edit Breakpoint. A popover opens to edit the breakpoint.

Click the Add Action button to add a breakpoint action.

Printing Text

Clicking the Add Action button expands the breakpoint editor.

Choose Log Message from the Action menu. The Log Message action is the equivalent of a Swift print statement.

If you want to show that you entered a function in your code, enter the text in the text field.

Reached viewDidLoad.

If you want to print the value of a variable, wrap it with the @ character. The following message:

Player X: @player.position.x@

Prints the following in Xcode’s debug console if the x position is 12:

Player X: 12

Automatically Continue

At the bottom of the breakpoint editor is a checkbox to automatically continue after running the breakpoint action. Select the checkbox.

Now if you run your project, the messages will appear in Xcode’s Debug console. You created the equivalent of a print statement without writing any code.

Turning off Printing

To turn off printing, disable the breakpoint. Click on the breakpoint in Xcode’s source editor to disable the breakpoint. Click a disabled breakpoint to enable it.

Showing a Swift Enum’s Values in a SwiftUI Picker

Tue, 06 Dec 2022 18:53:43 +0000

Swift enums let you create your own data types with a limited number of possible values. You may want to use a picker in a SwiftUI app to choose one of the enum’s values. Filling a picker with an enum’s values requires you to do two things.

Make the enum conform to the CaseIterable protocol.
Wrap the picker in a ForEach block, supplying an array of the enum’s values.

Conforming to CaseIterable

Your Swift enum must conform to the CaseIterable protocol to get an array of the enum’s values. In most cases, conforming to CaseIterable is easy. Add CaseIterable after a colon when creating the enum. The following code shows a simple enum that conforms to CaseIterable:

enum IssuePriority: Int, CaseIterable {
  case low = 1
  case medium = 2
  case high = 3
        
  // Convert to string to display in menus and pickers.
  func stringValue() -> String {
    switch(self) {
    case .low:
      return "Low"
    case .medium:
      return "Medium"
    case .high:
      return "High"
    }
  }
}

By conforming to CaseIterable, the enum gets an allCases property that contains an array of the enum’s values. Use the property in a picker or any other SwiftUI view that shows an array of items.

Wrap the Picker in a ForEach Block

To provide picker items for each enum value, wrap the picker in a ForEach block. Supply the enum’s allCases property in the ForEach block. Create a Text view or whatever view you want for the picker item. The following code demonstrates how to create a picker with items for each value in the IssuePriority enum from the previous section:

@State var issuePriority: IssuePriority = .low
    
Picker("Issue Priority:", selection: $issuePriority) {
  ForEach(IssuePriority.allCases, id: \.self) { priority in
    let menuText = priority.stringValue()
    Text("\(menuText)")
    .tag(priority)
  }
}

Genrerating Swift Code for REST APIs with CreateAPI

Mon, 21 Nov 2022 19:26:12 +0000

If you are starting to develop a Swift app that works with a REST API, you may be overwhelmed thinking about all the code you have to write. What if you forget a data structure? What if you forget to add a property to a data structure? Wouldn’t it be nice to have someone create the Swift code for you?

The command-line app CreateAPI makes this possible. Supply a JSON or YAML file that contains the REST API, and CreateAPI creates a Swift package with Swift code for the REST API. By using CreateAPI you can make faster progress on a Swift app that uses REST APIs.

Installing CreateAPI

The CreateAPI GitHub page has installation instructions. You can install it using Homebrew or Mint or by cloning the GitHub repository and installing it from source. Installing from source worked for me.

Generating a Swift Package with CreateAPI

Generating a Swift package with CreateAPI has the following steps:

Download a JSON or YAML file that contains the REST API.
Open the Terminal app.
Navigate to the folder that contains the file.
Run CreateAPI.

The most common way to run CreateAPI is to run the create-api generate command with the --output and --config-option options. The following example demonstrates running CreateAPI:

create-api generate "APIFile.json" 
  --output "./PackageName" 
  --config-option "module=PackageName"

The name of the JSON file must be in quotes. Replace APIFile.json with the name of the file containing the REST API. Replace PackageName with the name you want for your Swift package.

The CreateAPI GitHub page has a tutorial that contains more detailed instructions.

NOTE

CreateAPI is in its early stages of development. It may not work with every REST API. I was unable to generate a Swift package for GitHub’s REST API.

Add the Package to Your Xcode Project

After creating the Swift package you can add it to your project like any other Swift package. If you have never added a Swift package to a project in Xcode, take the following steps:

Select the project file from the left side of the project window to open the project editor.
Select the project from the left side of the project editor.
Click the Package Dependencies button at the top of the project editor to show a list of Swift packages in the project.
Click the Add button at the bottom of the package list.
Click the Add Local button in the sheet to add your package.

Import the package module in your source code files, and you can start using the package in your app.

If you want to see an example of a Swift package that CreateAPI creates, I have a package for Jira’s REST API on GitHub.

Navigation Basics for SwiftUI on macOS

Fri, 11 Nov 2022 03:00:17 +0000

If you’re looking for information on using the new SwiftUI navigation APIs in a Mac app, check out the following article:

https://www.kiloloco.com/articles/019-swiftui-macos-navigation-basics/

Working with Lists in Multiplatform SwiftUI Apps

Mon, 07 Nov 2022 18:34:36 +0000

One of SwiftUI’s best features is you can use it to make apps that run on both iOS and Mac. Almost every SwiftUI article you find online is about iOS development, but most of the material also applies to Mac as well.

Differences in List Behavior

The main reason you can’t use the same list code on iOS and Mac is because the way people interact with lists is different in iOS and Mac.

iOS apps have an Edit button that people use to delete and move items. When someone wants to delete a list item, they tap the Edit button. Each item has a Delete button next to it. Tapping the button deletes the item. Because each list item has a Delete button, you don’t have to keep track of the selected items.

Mac apps don’t have an Edit button for deleting and moving list items. In a Mac app, people delete list items by selecting them and either pressing the Delete key or clicking a Delete button. People move items by selecting them and dragging them to the desired destination. When developing a Mac app that uses lists, you must keep track of the selected item.

Tip: Create Separate List Views for iOS and Mac App Targets

Because list behavior is so different between iOS and Mac apps, you should create separate SwiftUI list views for the iOS and Mac versions of your app. If you try to support iOS and Mac in the same view, your code is going to be littered with #if os() checks, making the code tough to read.

You can share a list view if the list only displays data. If your app doesn’t allow people to delete and move items, it doesn’t require an Edit button on iOS. In that case you can share the view.

Deleting List Items

iOS

Deleting a list item on iOS requires the following steps:

Place the list items in a ForEach block.
Add an .onDelete modifier to the ForEach block.
Write a function to delete the item from its array.

You can’t apply the .onDelete modifier directly to a list on iOS. That’s why you must place the list items in a ForEach block.

Call the function to delete the item in .onDelete.

.onDelete(perform: deleteItem)

The function to delete the item takes an IndexSet as an argument. Call the array’s remove function to remove the item from the array.

func deleteItem(at offsets: IndexSet) {
  array.remove(atOffsets: offsets)
}

Mac

Deleting a list item on Mac requires the following steps:

Keep track of the selected item.
Add an .onDeleteCommand modifier to the list.
Write a function to delete the item from its array.

The usual way to keep track of the selected list item is to add a @State property to the view.

@State private var selection: Model? = nil

Call the function to delete the item in .onDeleteCommand.

.onDeleteCommand {
  deleteItem()
}

Removing an item from an array in a Mac app is trickier. Call the array’s firstIndex function to find the selected item in the array. If the item is in the array, call the remove function to delete the item.

func deleteItem() {
  if let selection = self.selection,
    let selectionIndex = array.firstIndex(of: selection) {
                
    array.remove(at: selectionIndex)
  }
}

Moving List Items

iOS

Moving list items on iOS requires the following steps:

Place the list items in a ForEach block.
Add an .onMove modifier to the ForEach block.
Add a function to move the item in its array.

You can’t apply the .onMove modifier directly to a list on iOS. That’s why you must place the list items in a ForEach block.

Call the move function in .onMove

.onMove(perform: move)

The move function takes two arguments: a location for the source and a location for the destination. Call the array’s move function to move the items in the array.

func move(from source: IndexSet, to destination: Int) {
  array.move(fromOffsets: source, toOffset: destination) 
}

Mac

Moving list items on Mac requires the following steps:

Add an .onMove modifier to the list.
Add a function to move the item in its array.

You have to do a little more work on Mac with the .onMove modifier, providing the arguments in the closure to call the move function.

.onMove { indices, destination in
  move(from: indices, to: destination)
}

The move function is the same as iOS.

func move(from source: IndexSet, to destination: Int) {
  array.move(fromOffsets: source, toOffset: destination)
}

Want More Articles Like This?

This article is an example of the exclusive articles for Swift Dev Journal newsletter subscribers. Subscribers also get a guide on going from tutorials to making your first app, discounts on books, and any benefits I decide to add later.

Use the form at the end of this article to subscribe to the newsletter.

Saving Images in Core Data

Mon, 31 Oct 2022 18:06:03 +0000

A common question I see on Swift developer forums is how to save images in Core Data. You have to do the following to save an image in Core Data:

Add an attribute for the image with data type Binary Data.
Use external storage to save the image in a separate file.
Convert the image to a Data object to save it in Core Data.

Add Attribute of Type Binary Data

Core Data does not have a data type specifically for images. Binary data is the closest data type that Core Data supports.

Use External Storage

Images take a lot of space so it’s more efficient to save them in separate files instead of saving them in the persistent store where Core Data saves your app’s data.

To tell Core Data to save the image in its own file, select the attribute and open the data model inspector. Choose View > Inpsectors > Data Model to open the data model inspector.

Select the Allows External Storage checkbox to save the image in a separate file.

Convert the Image to a Data Object

You must convert the image to a Data object to set the image attribute’s value in your code. Data is the underlying data type for a Core Data attribute of type Binary Data.

Swift apps generally use either UIImage or NSImage to work with images. UIImage has pngData and jpegData functions to convert an image to Data. NSImage has a tiffRepresentation function to convert to Data.

Xcode Multiplatform App Targets

Mon, 24 Oct 2022 17:57:43 +0000

Starting in Xcode 14, when you create a multiplatform app project, Xcode creates a single app target with destinations for each platform you want to support: iPhone, iPad, Apple TV and Mac. This article provides an introduction to multiplatform app targets.

When to Use the Multiplatform App Target

Use the Multiplatform App Target if you want people to buy one version of your app on the App Store and run the app on all the platforms you support: iPhone, iPad, AppleTV, and/or Mac. Use separate targets if you plan to charge for each platform separately.

If you plan to sell a Mac version of your app outside the App Store, create a separate app target. Use the multiplatform app target to sell on the App Store and the Mac app target to sell outside the App Store.

Viewing, Adding, and Removing Platform Destinations

Select the target from the target list on the left side of the project editor and click the General button at the top of the project editor to see a list of the app’s platform destinations:

The supported destinations list has buttons to add and remove destinations. If you created a project in an older version of Xcode, you must add destinations to have a single app target that supports iPhone, iPad, AppleTV, and Mac. Older versions of Xcode have separate targets for each platform.

Mac Destination Choices

When adding the Mac destination to an app target, you have the following choices:

Mac
Mac Catalyst
Designed for iPad

Choosing Mac uses SwiftUI and/or AppKit for the Mac app. Mac is the best choice for a new app, especially one that uses SwiftUI.

Choosing Mac Catalyst uses UIKit for the Mac app. Mac Catalyst is the best choice if you want to make a Mac version of an existing iOS app.

Choosing Designed for iPad runs the iPad version of the app on Macs with Apple Silicon chips. Choose Designed for iPad if you want a Mac version of your iOS app and don’t want to do any work converting the app.

Choosing the Platform to Build and Run

Xcode can build and run for only platform at a time. How do you specify the platform to build and run?

There’s a jump bar in the project window toolbar.

Click the right part of the jump bar to choose the platform: Mac, a connected iOS device, or an iOS simulator.

Compiling Files for Specific Platforms

Previous versions of Xcode have separate targets for each platform. If you have separate targets with code that should be compiled for a specific platform, make the file a member of that target. But you can’t do that with the multiplatform app target because there’s only one target. What do you do if you have platform-specific source code files?

Tell Xcode what platforms a source code file should compile for. Click the Build Phases button at the top of the project editor and examine the Compile Sources build phase.

Xcode initially sets each source code file to build for each destination. Click on the Filter column for a source code file to open a popover.

Deselect the Allow any platform checkbox and deselect the destinations you don’t want to use. Now that file compiles only for the platforms you specified.

Using the Sparkle Framework in a Sandboxed App

Mon, 26 Sep 2022 18:19:45 +0000

Sparkle is a framework that simplifies updating Mac apps that are not on the Mac App Store. There is a guide for using Sparkle in a sandboxed app, but I found parts of it unclear so I’m writing about it in this article.

It is very important to set things up correctly with the initial version of your app. If you forget to add something to either the entitlements file or the Info.plist file, people will see the following alert when they try to install an update for your app:

Overview

You have to perform one or more of the following steps to properly add Sparkle support to a sandboxed app:

Add the Installer Service (required)
Add the Installer Connection and Status Services (probably required)
Add the Downloader Service (maybe)

Most sandboxed apps only need to perform the first two steps. You may have to do more if you have more complex update requirements. See the sandboxing guide for those cases.

Add the Installer Service

To add the Installer Service to your app, you must add the following entry to the Info.plist file:

Key: SUEnableInstallerLauncherService
Type: Boolean
Value: YES

Add the Installer Connection and Status Services

To add the Installer Connection and Status Services to your app, you must add the following entry to your app’s entitlements file:

Key: com.apple.security.temporary-exception.mach-lookup.global-name
Type: Array
    
Key: Item 0
Type: String
Value: $(PRODUCT_BUNDLE_IDENTIFIER)-spks
    
Key: Item 1
Type: String
Value: $(PRODUCT_BUNDLE_IDENTIFIER)-spki

The entry is an array with two string items.

Add the Downloader Service

If you have the Outgoing Connections checkbox selected in the App Sandbox settings, you can skip this section. You’re done.

If your app does not allow outgoing connections (the Outgoing Connections checkbox is not selected), you must add the Downloader Service to update your app with Sparkle. Add the following entry to the Info.plist file:

Key: SUEnableDownloaderService
Type: Boolean
Value: YES

Accessing the Sparkle Binary from its Swift Package

Wed, 21 Sep 2022 17:35:26 +0000

A common task when using the Sparkle framework is to update the appcast when you release an update to your app. Running the command to update the appcast requires access to the Sparkle binary. Finding the Sparkle binary can be difficult if you added Sparkle using the Swift Package Manager. But by using Xcode and the Finder, you can create a Terminal window in the right location to run Sparkle commands.

Overview

Running a Sparkle command when using the Swift Package Manager requires the following steps:

Locate the Sparkle binary folder in the Finder.
Go to the Sparkle binary folder in the Terminal.
Run the Sparkle command.

Locate the Sparkle Binary Folder in the Finder

The easiest way to find the Sparkle binary folder is to use Xcode. The project navigator has an entry for Sparkle in the Package Dependencies section. Click the disclosure triangle next to the Sparkle entry.

The Sparkle binary is in the Referenced Binaries section. Select the Sparkle binary, right-click, and choose Show in Finder to open the Sparkle binary folder in the Finder.

Xcode 14 Update

Xcode 14 does not have a Referenced Binaries selection. Select the Sparkle 2.x item from the project navigator, right-click, and choose Show in Finder.

When you choose Show in Finder, the Finder takes you to a Sparkle folder inside a checkouts folder. That Sparkle folder contains source code, not the scripts you need to run.

Move one directory above the checkouts folder, which should be named Source Packages. Go to the artifacts folder. That’s where the Sparkle folder you need is.

Go to the Sparkle Binary Folder in the Terminal

In the Finder you have to navigate one folder above the Sparkle folder to open the Sparkle folder in the Terminal. In the Finder toolbar is the name of the current folder, which should be Sparkle. Select the folder name, right-click and choose artifacts to move to the artifacts folder.

In the artifacts folder, select the Sparkle folder, right-click, and choose Services > New Terminal at Folder. A new terminal window will open at the correct location to run Sparkle commands.

Run the Sparkle Command from the Terminal

Now that you are in the right folder in the Terminal, you can run Sparkle commands. Since updating the appcast is the command you’ll run the most, I’ll use that as an example. To update the appcast, run the following command:

./bin/generate_appcast "/path/to/your app/Sparkle files"

Where the path is the path to the folder where the appcast.xml file and the app file you are distributing (the .zip or .dmg file) reside on your Mac. I recommend placing those files in a place that is easy to reference so you don’t have to type an insanely long path to update the appcast.

Passing Data to SwiftUI Views

Mon, 12 Sep 2022 18:51:04 +0000

A common question I see from people learning SwiftUI is how to pass data from one view to another. There are three ways to pass data in SwiftUI apps.

Use @State and @Binding property wrappers
Use @StateObject and @ObservedObject property wrappers
Use @EnvironmentObject property wrapper

You’re going to use the first two ways more than you’ll use @EnvironmentObject.

Use `@State` and `@Binding` for Structs

If you use structs for your data, you must use @State and @Binding to pass data. Use the @State property wrapper in the master view and the @Binding property wrapper in any view where you want to pass the data.

Suppose you have a wiki app. The wiki consists of a list of pages. There are two views: the master view has a list of pages, and the detail view shows the contents of the selected page.

The master view needs to store the selected page.

@State private var selectedPage: Page = Page()

The detail view needs access to the selected page.

@Binding var page: Page

The following line of code demonstrates how to pass the selected page from the master view to the detail view:

NavigationLink(destination: PageView(page: $selectedPage))

When using bindings, you must put the $ character before the name of the @State variable.

The master and detail view point to the same page. Any changes you make in the detail view will appear in both views.

I have a demo project on GitHub that provides a full example on using @State and @Binding.

Use `@StateObject` and `@ObservedObject` for Classes

Use the @StateObject property to pass a class instance to other views. Using @StateObject has the following requirements:

The class must conform to the ObservableObject protocol.
Any properties you want automatically updated must use the @Published property wrapper.
The SwiftUI views must use the @StateObject and @ObservedObject property wrappers.

Suppose you have a Project class that has a list of issues.

class Project: ObservableObject {
  @Published var issues: [Issue]
}

By making the class conform to ObservableObject and using @Published for the issues array, you can use @StateObject in the view that owns the project.

@StateObject var project: Project

Pass the project variable to any view that needs to access the project. The other views should use @ObservedObject so that all the views are referring to the same project.

@ObservedObject var project: Project

Remember that @StateObject is the class equivalent of @State and @ObservedObject is the class equivalent of @Binding.

I have an issue tracking project on GitHub that demonstrates passing data to views using @StateObject.

Use `@EnvironmentObject` for Data You Want Any View to Access

Create an environment object when you have a piece of data you want any SwiftUI view to access.

A common situation where you would use environment objects is an app that uses Core Data. When working with Core Data, your app needs to access the managed object context to add, update, and delete entities. Apple provides an environment object for the managed object context so you don’t have to create one. Use the @Environment property wrapper to access the managed object context.

@Environment(\.managedObjectContext) private var context

If you need to create your own environment object, you must create a class that conforms to ObservableObject.

In the SwiftUI view, use the @EnvironmentObject property wrapper to access your environment object.

@EnvironmentObject var project: Project

Use the .environmentObject modifier to pass the environment object to another view.

DetailView()
  .environmentObject(project)

Getting Started with the Get Networking Framework

Mon, 15 Aug 2022 18:39:47 +0000

The Get framework is a lightweight Swift framework for working with web APIs. Get is a nice framework, but the README file doesn’t provide much explanation on how to use the framework. This article shows how to start using the Get framework in your apps.

Basic Workflow

Using the Get framework involves the following basic steps:

Create an API client instance
Create a network request
Send the request

Create an API Client Instance

Get provides an APIClient class for API clients. Create an instance, supplying the base URL to the network API you want to use. The following example creates an API client for the Jira REST API:

let client = APIClient(baseURL: 
  URL(string: "https://api.atlassian.com"))

Create a Network Request

Get has a Request struct that represents a network request. Fill the Request struct to create a network request. The Request struct has the following fields:

The body, which you use to send data from your app to the API. POST and PUT methods require you to supply a body.
Headers for the request. The headers field is a Swift dictionary where each key and value are strings.
An ID for the request. You probably won’t need to set an ID.
The method, such as GET, POST, or PUT.
Query items. The query field is an array of Swift tuples, consisting of two strings.
The URL for the network call.

The Get framework defaults to using GET methods and leaving the other fields blank so the only fields you have to fill are the ones you need to make the network call.

To create a request for a GET method, start by creating a variable of type Request. Place the data type you want to return in angle brackets and supply the URL for the network call.

var request = Request<T>(url: urlPath)

Replace T with the type you want to return from the network call. Replace urlPath with the URL string for the API call to make.

After creating the request, fill the fields your network call requires.

request.headers =  [
  "Accept": "application/json",
   "Content-Type": "application/json"
]
    
// Sort results alphabetically
request.query = [("orderBy", "name")]

If you have a method that sends data to the server, such as a POST or PUT method, you must create the body data and supply it when creating the request. The body property is a let constant so you can’t set the body after creating the request.

var request = Request<T>(url: urlPath, body: bodyData)
request.method = "POST"
request.headers =  [
  "Accept": "application/json",
  "Content-Type": "application/json"
]

The body must conform to the Encodable protocol.

Sending the Request

The API client has a send method to send the network request. Supply the request.

Usually a network call returns data. By attaching the value property when sending the request, you will get decoded data back in the type you specified when creating the request.

return try await client.send(request).value

You’re going to use this code a lot when using Get. In one line of code you can send a network request and get data back in a form that your app can use.

Saving Passwords in the Keychain in Swift

Tue, 12 Jul 2022 18:29:42 +0000

The Keychain is the place to store small amounts of data securely, such as passwords and API tokens. In this article you’ll learn how to work with the Keychain in iOS and Mac apps using the Keychain Services framework.

Parts of a Keychain Action

There are four common actions to perform on keychain items: add an item, update an item, read an item, and delete an item. To perform a keychain action, create a query and run a Keychain Services function.

Query

A query tells Keychain Services what you want to do. A query is a Swift dictionary that you must cast to CFDictionary.

Every query must include an entry with the key kSecClass, which specifies the kind of item to add, update, read, or delete. There are the following Keychain item types:

Generic password, kSecClassGenericPassword
Internet password, kSecClassInternetPassword
Certificate, kSecClassCertificate
Cryptographic key item, kSecClassKey
Identity item, kSecClassIdentity

I’m going to focus on generic passwords in this article, as that’s what most apps use. You’re not limited to passwords when using generic passwords. I was able to use generic passwords to store OAuth tokens in the Keychain.

The query keys you can use depend on the class. You can find a list of possible keys in the following section of Apple’s documentation:

Item Class Keys and Values

Click the link for a class to see the available items. You can also read the documentation in Xcode by choosing Help > Developer Documentation.

Two common item attributes for generic passwords are services, kSecAttrService, and accounts, kSecAttrAccount.

The value you supply for the service is the text that appears for the item in the Keychain Access app on Mac. Make sure the text clearly shows the keychain item is part of your app. A generic value like password will be hard to find in the Keychain Access app.

The value for the account is the name of the password’s account. If you’re writing a Mastodon client, Mastodon would be a good value for the account.

Keychain Services Functions

Call the following functions to work with the Keychain for passwords:

SecItemAdd to add an item to the Keychain
SecItemUpdate to update an existing Keychain item
SecItemCopyMatching to read an item from the Keychain
SecItemDelete to delete an item from the Keychain

Adding a Keychain Item

Start by importing the Authentication Services framework. The Keychain Services API is in the Authentication Services framework.

import AuthenticationServices

You should also create a class for the Keychain functions.

Let’s start by writing a function to add an item to the Keychain.

func save(_ data: Data, service: String, account: String) {
  let query = [
    kSecValueData: data,
    kSecClass: kSecClassGenericPassword,
    kSecAttrService: service,
    kSecAttrAccount: account
  ] as CFDictionary
            
  let saveStatus = SecItemAdd(query, nil)
    
  if saveStatus != errSecSuccess {
    print("Error: \(saveStatus)")
  }
        
  if saveStatus == errSecDuplicateItem {
    update(data, service: service, account: account)
  }
}

The function starts by building a query. Tell Keychain Services that you’re adding a generic password. Supply the data, service, and account. The data is what you want to save in the Keychain.

After building the query, call the function SecAddItem to add the item to the Keychain. If the item is added to the Keychain successfully, SecAddItem returns the value errSecSuccess.

If the item already exists in the Keychain, SecAddItem returns the value errSecDuplicateItem. In this case update the existing item, which I cover next.

Updating an Existing Keychain Item

Let’s look at the code to update a keychain item.

func update(_ data: Data, service: String, account: String) {
  let query = [
    kSecClass: kSecClassGenericPassword,
    kSecAttrService: service,
    kSecAttrAccount: account
  ] as CFDictionary
            
  let updatedData = [kSecValueData: data] as CFDictionary
  SecItemUpdate(query, updatedData)
}

Notice that the update function doesn’t include the data in the query. The code creates another dictionary for the data and passes it as an argument to the function SecItemUpdate.

Reading an Item from the Keychain

Saving items to the Keychain isn’t going to help unless your app can read the keychain items.

func read(service: String, account: String) -> Data? {
  let query = [
    kSecClass: kSecClassGenericPassword,
    kSecAttrService: service,
    kSecAttrAccount: account,
    kSecReturnData: true
  ] as CFDictionary
            
  var result: AnyObject?
  SecItemCopyMatching(query, &result)
  return result as? Data
}

The big difference in the query is the kSecReturnData key, which tells Keychain Services you want to return data from the function call. The function SecItemCopyMatching returns its results as type AnyObject?. You saved the item as Data so you should return a Data object. If there is no matching item in the Keychain, SecItemCopyMatching returns nil.

Deleting an Item from the Keychain

The last major task to perform on Keychain items is to delete items from the Keychain.

func delete(service: String, account: String) {
  let query = [
    kSecClass: kSecClassGenericPassword,
    kSecAttrService: service,
    kSecAttrAccount: account
  ] as CFDictionary
            
  SecItemDelete(query)
}

The query for deleting an item is the simplest one. Supply the class, service, and account. Call SecItemDelete to delete the item from the Keychain.

Intro to Making SwiftUI Apps with Swift Playgrounds

Tue, 07 Jun 2022 17:40:42 +0000

The Swift Playgrounds app lets you create SwiftUI apps if you are using Swift Playgrounds 4 on an iPad running iOS 15 and above or a Mac running macOS 12.4 and above. In this article you’ll learn the basics of Swift Playgrounds. After reading this article you’ll be able to follow SwiftUI tutorials using Swift Playgrounds.

The screenshots in this article are from the Mac version of Swift Playgrounds. But the iOS and Mac versions have a similar look.

Create an App Playground

When you launch Swift Playgrounds, a window opens for you to either create a playground or open an existing playground.

Tap or click App from the More Playgrounds section to create an app playground. The app gives a generic name for the playground. Tap or click on the name to change the app name.

The Playground Window

When you open the playground, the playground window opens.

The playground window has the following sections:

Sidebar
Editor
Console
Preview

The sidebar shows a list of files in the playground and a control to change the app settings.

The editor is where you write code.

The console shows output and error messages. If your code uses print statements, the text in the print statements appears in the console. The console is hidden initially. Tap or click the small button at the bottom of the window to toggle showing and hiding the console.

The preview shows how the interface is going to look when you run the app.

Changing App Settings

Tap or click the App Settings item in the sidebar to change the app settings.

Use the Name text field to change the name of the app.

Choose a color for the app icon from the Accent Color color picker. Use the view below the color picker to choose an image for the app icon.

Use the Capabilities control to add app capabilities like giving the app access to things like the device’s camera, the user’s contacts, and the user’s media library.

The Mac version has a button to install the app in the Applications folder.

Editing Source Code

Select a Swift file from the sidebar to open it in the editor and start coding. When you create an app playground Swift Playgrounds creates two files: a file for the app and a file for the content view. The app file creates a window whose main view is the content view. The content view file has the code for the views and controls inside the content view. The preview shows what the content view looks like.

Clicking the Add button at the top of the window opens a popover that shows a list of SwiftUI controls and items you can add to your code.

SwiftUI has many items you can add so they’re broken up into four groups that have buttons below the search field. Selecting an item from the popover inserts code for that item in the editor.

Adding Files to the Playground

Virtually every app requires more files than the two source code files provided when you create an app playground. Swift Playgrounds lets you add the following items to a playground:

New Swift files
Existing files
Folders to group files in the sidebar
Swift packages that contain code libraries

Compared to Xcode, Swift Playgrounds has limited options for adding files. If you’re following a SwiftUI tutorial that uses Xcode, you’ll run into problems if the tutorial adds new files that aren’t Swift files.

The iOS version has an Add Document icon at the top of the sidebar. Tap the icon and choose what you want to add from the menu that opens.

Use the File menu in the Mac version to add files to the playground. Choose File > New Source File to create a new Swift file. Choose File > Add File to add an existing file to the playground. Choose File > New Folder to add a folder to the sidebar. Choose File > Add Package to add a Swift package to the playground.

Running the App

Tap or click the Run (Play) button at the top of the window to build and run the app. A newly created app playground should build with no errors.

If there are errors in your code, the app won’t build and run. There will be a small button with a red X for any error in the code. Tap or click the button to see the error message.

Reading Developer Documentation

The iOS version has a button with a circle and three dots inside it. Tap that button and choose Documentation to read Apple’s developer documentation.

Choose Help > Show Developer Documentation in the Mac version to read Apple’s developer documentation.

Where to go from here?

Check out the following WWDC video:

Build your first app in Swift Playgrounds

Rija Development: Using OAuth Tokens to Make REST API Calls

Mon, 23 May 2022 17:50:17 +0000

In my last Rija development post I talked about getting an OAuth access token for Jira so other people can use Rija. This post covers using the access token to make calls to Jira’s REST API. You must perform the following tasks to make API calls with an OAuth token:

Get the user’s Jira cloud ID
Get the URL for Jira’s REST APIs
Add the access token to the authorization header

Get User’s Cloud ID

Each Jira site has a unique cloud ID. You can’t make calls to Jira’s REST API with an OAuth token without the cloud ID for the user’s Jira site. The first thing you must do is get the cloud ID. To get the cloud ID, make a URL request to the following URL:

https://api.atlassian.com/oauth/token/accessible-resources

Add the access token string to the authorization header. Run a URL session with the URL request. The following code retrieves a Jira cloud ID:

func retrieveCloudID() async -> String {
  // Build the URL    
  var components = URLComponents()
  components.scheme = "https"
  components.host = "api.atlassian.com"
  components.path = "/oauth/token/accessible-resources"
  var request = URLRequest(url: components.url!)
            
  guard let accessToken = getAccessToken() else {
    return ""
  }
            
  // Add the access token to the authorization header
  let authString = String("Bearer \(accessToken)")
  request.addValue(authString, forHTTPHeaderField: "Authorization")
  request.addValue("application/json", forHTTPHeaderField: "Content-Type")
            
  // Retrieve the cloud ID
  do {
    let (data, error) = try await URLSession.shared.data(
      for: request, delegate: nil)
    let decoder = JSONDecoder()
    let cloudDictionary = try decoder.decode([JiraCloudID].self, 
      from: data)
    return cloudDictionary.first?.id ?? ""
  } catch {
    print(error)
    return ""
  }
}

JiraCloudID is a struct I created with the properties id, name, and url. The id property contains the cloud ID.

Get Jira’s REST API URL

Jira has a different URL for making API calls with an OAuth access token than they have for making calls with a personal access token. The base URL is the following:

https://api.atlassian.com/ex/jira

Append the cloud ID and the path to the REST API call you’re making.

Add the Access Token to the Authorization Header

I showed the code to add the access token in the code to retrieve the cloud ID. But let’s show it again.

guard let accessToken = getAccessToken() else {
  return ""
}
            
let authString = String("Bearer \(accessToken)")
request.addValue(authString, forHTTPHeaderField: "Authorization")

Jira’s REST API requires the string Bearer followed by the access token string. Add the string to the URL request’s authorization header.

If you read Apple’s documentation for the URLRequest class, they tell you not to set the Authorization header manually because it’s a reserved header. But Apple provides no alternative to manually setting the header manually so I have to set the Authorization header manually.

An Example API Call

The following code fetches someone’s Jira projects:

func fetchProjects() async throws -> JiraProjectList {
  let cloudID = await getCloudID()
            
  // Build the URL 
  var components = URLComponents()
  components.scheme = "https"
  components.host = "api.atlassian.com"
  components.path = "/ex/jira/" + cloudID 
    + "/rest/api/3/project/search"
        
  // Sort projects alphabetically by default
  components.queryItems = [
    URLQueryItem(name: "orderBy", value: "name")
  ]
  var request = URLRequest(url: components.url!)
            
  // JiraProjectList contains an array of projects.   
  guard let accessToken = getAccessToken() else {
    return JiraProjectList()
  }
            
  // Add access token to authorization.
  let authString = String("Bearer \(accessToken)")
  request.addValue(authString, forHTTPHeaderField: "Authorization")
  request.addValue("application/json", forHTTPHeaderField: "Content-Type")
            
  let (data, error) = try await URLSession.shared.data(for: 
    request, delegate: nil)
  let decoder = JSONDecoder()
  return try decoder.decode(JiraProjectList.self, from: data)
}

I start by building the URL. I want to sort the projects alphabetically so I supply a URL query item. Then I add the access token to the authorization header. Finally I run the URL request.

Jira’s REST API returns the projects in a dictionary instead of an array. I have to create a JiraProjectList struct to decode the JSON properly. All the struct contains is an array of projects.

About Rija

Rija is a Jira issue tracker under development for Mac (and possibly iOS). The following article provides more details on Rija:

Rija Development: Intro

Log in to Websites with ASWebAuthenticationSession

Wed, 11 May 2022 17:52:38 +0000

What is ASWebAuthenticationSession?

ASWebAuthenticationSession is a class in Apple’s Authentication Services framework that simplifies logging into websites from iOS and Mac apps. When you create and start an instance of ASWebAuthenticationSession, a private browser window opens for someone to sign into a website.

When would you use ASWebAuthenticationSession? Use it if your app needs to log into a website. Suppose you’re writing a Twitter app like Tweetbot or Twitterific. The first time someone launches your app, they need to sign into Twitter so they can use your app.

Add a Custom URL Type for Your App

When someone finishes logging in to the website, they should go back to your app. You must add a URL type to your app to go back to the app.

Select your app target from the project editor and click the Info button at the top to add a URL type to the app.

Give your URL type a name in the Identifier text field. Enter the URL type in the URL Schemes text field. The type should take the following form:

appname://

Create a Class for the Login Session

To use ASWebAuthenticationSession you must add a class to hold the login session.

import AuthenticationServices
    
class LoginSession: NSObject, 
  ObservableObject, 
  ASWebAuthenticationPresentationContextProviding {
    
  var webAuthSession: ASWebAuthenticationSession?
}

The ASWebAuthenticationSession class is part of the Authentication Services framework so you must import that framework.

The class must conform to the ASWebAuthenticationPresentationContextProviding protocol. Inheriting from NSObject is the easiest way to conform to the protocol. Conforming to ObservableObject isn’t mandatory, but it helps for SwiftUI apps.

Add a Presentation Anchor

The login session requires a presentation anchor, which is a window to show the login session.

func presentationAnchor(for session: 
  ASWebAuthenticationSession) -> ASPresentationAnchor {
            
  return ASPresentationAnchor()
}

ASPresentationAnchor is an instance of UIWindow on iOS and an instance of NSWindow on Mac.

Create an ASWebAuthenticationSession Instance

Now you can create an instance of ASWebAuthenticationSession. You must supply the following arguments:

The URL of the website to log in.
The callback URL, the URL to go when the login session finishes.
A completion handler closure (function) that runs when the session finishes successfully.

The callback URL is the custom URL type you created for the app, minus the ://.

appname

The code looks like the following:

webAuthSession = ASWebAuthenticationSession.init(
  url: websiteURL, 
  callbackURLScheme: callbackUrl, 
  completionHandler: { (callback:URL?, error:Error?) in
    
  // Do what you need to after someone logs in.
})
    
// Run the session
webAuthSession?.presentationContextProvider = self
webAuthSession?.prefersEphemeralWebBrowserSession = true
webAuthSession?.start()

You should use ephemeral web browser sessions. If you set prefersEphemeralWebBrowserSession to false, information from previous sessions will be available in the session.

If you need to make any async calls in the completion handler, wrap them in a Task block. ASWebAuthenticationSession does not support Swift’s async await concurrency features.

Task {
  // Put async calls here
}

You can see an example of using ASWebAuthenticationSession to sign in to Jira’s website in the following article:

Rija Development: OAuth Authorization

Fri, 06 May 2022 17:52:19 +0000

Authorization Flow

When someone launches Rija for the first time, Rija must get a Jira access token that gives the app access to the person’s Jira account. This involves the following steps:

Show a login view with a button to sign in to Jira.
When the person clicks the button, a private browser opens.
The person signs in to their Jira account.
The person grants Rija permission to access their Jira account.
Jira gives Rija an authorization code.
Rija exchanges the authorization code for the access token.
Rija saves the access token in the Keychain.

This post is going to focus on Steps 3–6.

Sign in to Jira with ASWebAuthenticationSession

The ASWebAuthenticationSession class simplifies logging into websites from Swift apps. To create a login session, create a ASWebAuthenticationSession object and supply three arguments:

An authorization URL
A callback URL
A callback closure

When the login session finishes successfully, the code in the callback closure runs.

Authorization URL

The authorization URL is the URL for the website where you’re logging in. Jira has the following URL for OAuth authorization:

https://auth.atlassian.com/authorize?
  audience=api.atlassian.com&
  client_id=YOUR_CLIENT_ID&
  scope=REQUESTED_SCOPE_ONE%20REQUESTED_SCOPE_TWO&
  redirect_uri=https://YOUR_APP_CALLBACK_URL&
  state=YOUR_USER_BOUND_VALUE&
  response_type=code&
  prompt=consent

I use the following code to set the URL to sign in to Jira:

var components = URLComponents()
components.scheme = "https"
components.host = "auth.atlassian.com"
components.path = "/authorize"
components.queryItems = [
  URLQueryItem(name: "audience", value: "api.atlassian.com"),
  URLQueryItem(name: "client_id", value: clientID),
  URLQueryItem(name: "scope", value: 
    "read:jira-user 
    read:jira-work 
    manage:jira-configuration 
    manage:jira-project 
    write:jira-work 
    offline_access"),
  URLQueryItem(name: "redirect_uri", value: callbackUrl + "://auth"),
  URLQueryItem(name: "state", value: UUID().uuidString),
  URLQueryItem(name: "response_type", value: "code"),
  URLQueryItem(name: "prompt", value: "consent")
]
            
guard let authURL = components.url else {
  return
}

Jira’s authorization URL is complex, as you can see by the amount of code needed to build the URL.

Callback URL

The callback URL is where you go when the login session finishes. For iOS and Mac apps the callback URL should take you back to the app.

Creating a callback URL requires you to add a custom URL type to your Info.plist file.

Enter the URL type in the URL Schemes text field. It should look like the following:

appname://

But when you supply the callback URL for the login session, you should omit the :// part of the URL. ASWebAuthenticationSession cannot handle colons in the callback URL.

let callbackUrl = "rija"

The ASWebAuthenticationSession Code

Using Apple’s ASWebAuthenticationSession class simplifies signing in to websites. The following code initializes and starts the login session:

var webAuthSession: ASWebAuthenticationSession?
    
webAuthSession = ASWebAuthenticationSession.init(url: authURL,  callbackURLScheme: callbackUrl, 
  completionHandler: { (callback:URL?, error:Error?) in
    
  guard error == nil, let successURL = callback else {
    return
  }
    
  // Get the authorization code.
  let query = URLComponents(string: (successURL.absoluteString))?
    .queryItems?.filter({$0.name == "code"}).first
                
  let authorizationCode = query?.value ?? ""
                
  // Exchange the authorization code for an access token and save it 
  // in the Keychain. I have to make the calls inside the 
  // callback to ensure there's a valid authorization 
  // code before doing anything else.
    
  // Have to wrap the code in a Task block because 
  // ASWebAuthenticationSession does not 
  // support Swift concurrency (async await).
  Task {
    if let token = await self.exchangeAuthorizationCodeFor
      AccessToken(code: authorizationCode) {
                        
      self.saveTokenInKeychain(token: token)
    }
  }
})
    
// Run the session
webAuthSession?.presentationContextProvider = self
webAuthSession?.prefersEphemeralWebBrowserSession = true
webAuthSession?.start()

The following article has more details on login sessions:

Exchange the Authorization Code for the Access Token

After getting the authorization code from Jira, you have to exchange the code for an access token, which you use to make REST API calls in Jira. The exchange involves making a POST request to Jira, supplying the authorization code as part of the body. The following code demonstrates how to exchange the authorization code for an access token:

func exchangeForAccessToken(authorizationCode: String) async -> AuthToken? {
  var components = URLComponents()
  components.scheme = "https"
  components.host = "auth.atlassian.com"
  components.path = "/oauth/token"
            
  var request = URLRequest(url: components.url!)
  request.addValue("application/json", forHTTPHeaderField: "Content-Type")
            
  let clientID = ProcessInfo.processInfo.environment["CLIENT_ID"]!
  let clientSecret = ProcessInfo.processInfo.environment["CLIENT_SECRET"]!
            
  request.httpMethod = "POST"
  let body = [
    "grant_type": "authorization_code",
    "client_id": clientID,
    "client_secret": clientSecret,
    "code": authorizationCode,
    "redirect_uri": "rija://auth"
  ]
  let bodyData = try? JSONSerialization.data(withJSONObject: body)
  request.httpBody = bodyData
            
  do {
    let (data, error) = try await URLSession.shared.data(
      for: request, delegate: nil)
    let decoder = JSONDecoder()
    return try decoder.decode(AuthToken.self, from: data)
  } catch {
    print(error)
  }
            
  return nil
}

About Rija

Rija is a Jira issue tracker under development for Mac (and possibly iOS). The following article provides more details on Rija:

Rija Development: Intro

Rija Development: Using Jira’s REST APIs

Mon, 02 May 2022 17:52:34 +0000

Developing Rija has me spending a lot of time working with Jira’s REST APIs. This post details some issues I have run into when working with the APIs.

The REST API Wraps Arrays in Dictionaries

In GitHub’s API, if you want to get someone’s repositories or the issues for a given repository, you make the API call, and GitHub gives you an array of repositories or issues.

But Jira’s REST API does not work like GitHub’s. When you make an API call to get a Jira account’s projects, the API returns a dictionary. The array that has the projects is one of the fields in the dictionary.

Wrapping the array inside a dictionary makes decoding the JSON difficult. I kept getting errors saying I was trying to decode an array but the JSON was a dictionary. I had to create new data structures that contained an array of what I what I wanted to get the JSON decoding to work.

struct JiraProjectList: Codable {
  var projects: [Project]
        
  enum CodingKeys: String, CodingKey {
    case projects = "values"
  }
        
  init() {
    projects = []
  }
        
  init(from decoder: Decoder) throws {
    let valueContainer = try decoder.container(keyedBy: CodingKeys.self)
    self.projects = try valueContainer.decode([Project].self, 
      forKey: CodingKeys.projects)
    }
}

You have to Use JQL to Fetch Multiple Issues

Jira’s REST API does not provide a call to get multiple issues. If you want to do something like fetch a list of a project’s issues or the issues assigned to a person, you have to use JQL, Jira’s query language. You have to build a URL string to make a query.

Fortunately the Foundation framework has URLComponents to make building a URL safer. Here’s the code I had to write to set up JQL to retrieve a selected project’s issues.

let projectString = "project = " + project.key
var components = URLComponents()
components.scheme = "https"
components.host = domain + ".atlassian.net"
components.path = "/rest/api/3/search"
components.queryItems = [
  URLQueryItem(name: "jql", value: projectString),
  URLQueryItem(name: "fields", value: "issue,summary,description")
]

Atlassian Document Format

The latest version of Jira’s REST API changed the data type for an issue’s description and its comments. Instead of returning a string, the API returns the description and comments in Atlassian Document Format. Atlassian Document Format is a JSON format that provides support for headings, code blocks, lists, bold text, and italic text.

The problem I ran into is that most of the examples I found on working with issue descriptions and comments used the old API version that returns strings. There aren’t many examples on using Atlassian Document Format.

Early versions of Rija are going to treat everything as a paragraph. Supporting Markdown is a nice to have feature for a future version. Write in Markdown in Rija and have the text in Atlassian Document Format in Jira.

About Rija

Rija is a Jira issue tracker under development for Mac (and possibly iOS). The following article provides more details on Rija:

Rija Development: Intro

Mon, 25 Apr 2022 18:46:04 +0000

I have started developing Rija, a native Mac (and possibly iOS) app for tracking issues in Jira. I’m experimenting with developing in the open. While I was creating a Twitter thread on developing Rija, I realized there are technical details that might interest other developers that won’t fit a tweet.

This post is the first in a series of posts detailing Rija’s development journey. Future posts are going to be more technical than this one.

Why am I Making Rija?

I used Bee, a Mac issue tracking app that worked with Jira and GitHub issues. The developer stopped developing Bee. I remember some people were upset about the news. I didn’t think much about it and moved on to doing issue tracking online and using text files on my Mac.

Then I saw Atlassian announced they were stopping development of their Mac Jira app. People were disappointed to hear this news.

After doing some more research I learned people hated using Jira’s website. The website is slow and uses lots of RAM. The website does not support Dark Mode. I saw numerous complaints about the difficulty of figuring out how to do things on Jira’s website.

I realized I could help people by making a native Mac app for Jira. A native app would be faster than the website and use less RAM. A native app supports both Light and Dark modes. Developers wouldn’t need to have a browser tab open for hours at a time and wouldn’t have to worry about mistakenly closing the tab. Issue tracking is the area where developers spend the most time on Jira so I should focus on that first.

Rija’s Technology Stack

I’m using SwiftUI to make Jira. By using SwiftUI I can make Rija run on both Mac and iOS. I’m focusing on the Mac version first because Atlassian stopped making a Mac app and continue to develop an iOS app for Jira.

Rija’s Current Development Status

Rija is in the very early stages of development. I wanted to know if I could work with Jira’s REST APIs in a Mac app. I was able to get a list of projects, a list of issues for a project, and show an issue’s summary and details using my Jira account.

The next step in Rija’s development is to get the app to work for anyone with a Jira account. That’s what I’m working on right now.

If you are interested in trying Rija when it’s ready for me to show to other people, go to the Rija page and click the Send Feedback button.

Dealing with “Failed to prepare device for development” Error Message in Xcode

Fri, 25 Mar 2022 18:56:19 +0000

You update your iOS device to the latest version of iOS. Now you try to run your Xcode project on that device. An alert pops up in Xcode with the message Failed to prepare device for development.

Why Are You Getting This Message?

You are getting the Failed to prepare device for development message because the device is running a newer version of iOS than Xcode supports.

Each version of Xcode ships with a version of the iOS SDK. The Xcode Releases site has a list of each version of Xcode along with the iOS SDK. The version of the SDK is the latest version of iOS that version of Xcode supports. You won’t be able to run your Xcode project on a device running a newer version of iOS.

For example Xcode 13.2.1 ships with the iOS 15.2 SDK. If you are running Xcode 13.2.1, you won’t be able to run your project on a device running anything newer than iOS 15.2. If you have a device running iOS 15.4, you won’t be able to run the project on that device with Xcode 13.2.1.

How Do You Fix the Error?

The easiest solution is to install the latest version of Xcode. The latest version of Xcode has the latest version of the iOS SDK so you’ll be able to run and debug your project on a device running the latest version of iOS.

If your Mac is running an older version of macOS, you might not be able to update to the latest version of Xcode. Xcode 13.3 requires macOS 12. If your Mac is running macOS 11 and can’t run macOS 12, you won’t be able to update to Xcode 13.3. What do you do then?

There are two workarounds. The first is to download iOS support files for the newer iOS version and copy them to your Xcode app bundle.

The second workaround is to deselect the Debug executable checkbox in the Run step of the scheme. After the app launches, attach it to the debugger. The following article provides details and screenshots:

Debugging on iOS 15 with Xcode 12

iOS 17 Update

Starting with iOS 17 Apple no longer includes iOS support files so the first workaround won’t work. According to the following Stack Overflow question:

How to run on iOS 17 Device using Xcode 14

The solution is to run the following command in the Terminal and restart Xcode:

defaults write com.apple.dt.Xcode DVTEnableCoreDevice enabled

Turn off Automatic Updates on Your Device

Keeping up with the latest version of iOS requires using the latest version of Xcode. Xcode takes a long time to install. If you don’t want to be constantly updating Xcode, turn off automatic updates on your iOS device.

Why Won’t My Xcode Project Build?

Wed, 23 Mar 2022 19:58:02 +0000

It’s frustrating to click the Run button in Xcode and find that your project won’t build and run. Xcode initially shows you a message like Command CompileSwiftSources failed with a nonzero exit code, which really doesn’t help much. How do you find where the error is so you can fix it and run your project?

Get a List of the Errors

The first step to figuring out why your project won’t build is to find the compiler errors in your project. Open Xcode’s issue navigator by pressing Cmd–5.

The issue navigator shows the compiler errors in your project. Select an error to show the line where the error is.

Seeing More Detailed Information about an Error

To see more detailed information about a compiler error, open the report navigator by pressing Cmd–9. Select a build from the report navigator to see the build steps and errors for that specific build.

Click the Log button (the small button with the horizontal lines) to see a detailed log of that particular build step.

Tips for Fixing Errors

You found the compiler errors in your project. How do you fix them?

I can’t tell you specifically how to fix the errors because I can’t see your code. But I have some general tips to help you fix the compiler errors in your Xcode projects.

Make Sure Argument Types Match

When calling functions, make sure the data types for the function arguments match. When the argument types don’t match, you get a compiler error message like the following:

Can’t convert value of type X to expected argument type Y

Where X and Y data types.

If a function takes an integer as the first argument and you pass a string, you’re going to get the Can't convert value compiler error.

Check for Typos

If I make a typographical error in this article, you’ll still be able to read the article. But if you make one small typo in your code, the project won’t build.

Make sure you spell function names correctly when calling them. If you have a function called doSomething and you call it like the following:

doSomethng()

You are going to get a compiler error because you made a typo when calling the function. There is no doSomethng function.

Make sure that you spell variable names correctly when accessing them. If you have a player variable in your app and misspell it,

move(playr)

You are going to get a compiler error because there is no playr variable.

Make sure each left brace, bracket, parenthesis, and quotation mark has a matching right one. An extra left or right brace can lead to compiler errors with bizarre messages.

Import Missing Modules

Make sure you import the modules for the frameworks your app uses. If you’re writing an app that works with PDF documents, you must import the PDFKit framework to call its functions in your app.

import PDFKit

Document Types in SwiftUI Apps

Fri, 14 Jan 2022 19:24:13 +0000

SwiftUI supports making document-based apps that let people create and save documents. To ensure the documents have the right file extension and save and load correctly, you must configure the app’s document types. There’s not much information online about document types in SwiftUI apps so I’m sharing what I learned in this article.

Accessing the Document Type Settings

Take the following steps to access the document type settings for your SwiftUI project:

Select the project file from the left side of Xcode’s project window to open the project editor.
Select your app from the target list on the left side of the project editor.
Click the Info button at the top of the project editor.

There are three sections of document type settings.

Document Types
Exported Type Identifiers
Imported Type Identifiers

A new SwiftUI document-based app project gives you a plain text editor. Unless you’re making a plain text editor, you must change the document type settings.

Document Types

Every document type in a SwiftUI app requires you to supply the following information:

Name
Identifier
Handler Rank

The name describes the document. Enter a descriptive name in the text field.

The identifier uniquely identifies the document type. An iOS app has a Types text field to enter the identifier. Apple has a list of system defined types for common file types. But you can also define your own type using the following convention:

com.CompanyName.DocumentName

I found in an app I’m developing that the document had the wrong file extension and type on the Mac until I made the DocumentName part of the identifier match the file extension for the document. I didn’t have this problem on iOS.

The handler rank tells Xcode whether your app owns the document type. In most cases you can choose Default.

Mac document types also require you to choose whether your app can edit documents of that type or just view them. Choose Editor to let people edit documents in your app.

Exported Type Identifiers

You need an exported type identifier for each document type your app owns. If you create a custom document type for your app, you must add an exported type identifier for the custom document type. Do not add exported type identifiers for file types your app exports.

You must supply the following information for an exported type identifier:

Description
File extension
Identifier
Conforming identifiers

If you are adding a description for a custom document type, the description usually matches the name of the document type.

Enter the file extension without the leading dot in the Extensions text field.

The identifier should match the identifier for the document type.

You may be able to avoid entering conforming identifiers, but most document types require them. The conforming identifiers are a list of identifiers the type identifier conforms to. For example if you have a custom document type that saves the document in a file package, it must conform to com.apple.package. If you look at the list of system defined types, the Apple System Base Types section has the most common conforming types.

There are also fields to enter a MIME type and a reference URL for the exported type identifier. If your document type has a MIME type or a reference URL, enter them in the appropriate fields.

Imported Type Identifiers

Imported type identifiers are for types your app uses but doesn’t own. Xcode provides an imported type identifier for your document type. If your app imports other file types, you must add imported type identifiers for the other types. If you’re making an image editor, you would add imported type identifiers for the image file formats your app supports, such as PNG and JPEG files.

You supply the same information for imported type identifiers as you do for exported type identifiers so I’m not going to repeat the information here.

SwiftUI Code for Document Types

Open the Swift file for the document struct and you should see the following code:

extension UTType {
  static var exampleText: UTType {
    UTType(importedAs: "com.example.plain-text")
  }
}
    
static var readableContentTypes: [UTType] { [.exampleText] }

If you changed the document type, you should replace the string com.example.plain-text with the identifier for your app’s document type. You should also change the variable name exampleText to something that better describes your document type.

Notice that the init for UTType has an importedAs argument. The UTType class reference in Apple’s documentation has a list of inits you can use for your document types.

The readableContentTypes property contains an array of the document types your app can read. There should be an array entry for each imported type identifier in your app. Apple has Swift enums for common document types.

SwiftUI documents also have a writableContentTypes property. This property defaults to matching the readable content types. If your app exports to a type that is not in readableContentTypes, you must add a variable for the writable content types and supply the writable types.

// Replace PDF with the file types your app
// can export and save.
static var writableContentTypes: [UTType] { [.pdf] }

Summary

The most important points about SwiftUI document types are the following:

Document types must have a unique identifier.
Add exported type identifiers for any custom document types you make.
Add imported type identifiers for any file types your app can import.
You need a UTType property in your code for the document type.
You need to supply a readableContentTypes array in your code with an entry for each imported type identifier.

I have a WikiDemo project on GitHub that has its own document type. Clone the project to examine the settings for the document type, exported type identifiers, and imported type identifiers.

Edit Swift Files Outside Xcode

Wed, 24 Nov 2021 19:21:36 +0000

Does Xcode’s editor frustrate you? Do you have problems with Xcode’s code completion? Do you wish you could use a different text editor to edit the Swift files in your Xcode projects?

Xcode supports opening and editing Swift files in other text editors, such as BBEdit, Sublime Text, TextMate, and Visual Studio Code. Keep reading to learn how to use your favorite text editor to edit the Swift files in your Xcode projects.

Make Your Text Editor the Default Editor for Swift Files

Start by making your preferred text editor the default editor for Swift files on your Mac. Perform the following steps to change the default editor for Swift files:

Go to the Finder.
Select a Swift file.
Press Cmd-I to open the file’s info panel.
Choose your text editor from the Open with menu.
Click the Change All button.

Now when you open a Swift file in the Finder, the file opens in your text editor.

Opening from Xcode

The final step is to open the Swift files in your text editor from Xcode. Select a Swift file in Xcode’s project navigator, right-click, and choose Open with External Editor. The file will open in your text editor.

The changes you make to the text in your text editor will also appear in Xcode. If your project is under version control, an M will appear next to the file in the project navigator, indicating you modified the file.

Disable a Text Field in a SwiftUI List Until Tapping Edit Button

Tue, 02 Nov 2021 18:03:09 +0000

SwiftUI lists support using text fields to change the name of list items. But if your list items are navigation links, you will run into some annoying behavior on iOS. You tap a list item expecting to go to the navigation link destination, but you end up changing the name of the list item.

When you tap a list item that is a navigation link, you normally want to go to the link destination. But you still want to be able to rename list items. In SwiftUI iOS apps, you can disable the list item’s text field until someone taps the Edit button. In edit mode you can tap the list item to rename it. When the person taps the Done button, disable the text field.

Variables to Add to the SwiftUI View

Start by adding two variables to your SwiftUI view that has the list. The first variable is an environment variable for the editing mode. This variable tracks when someone taps the Edit and Done buttons.

@Environment(\.editMode) private var editMode

The second variable is a Boolean value that tracks if the text field is disabled. The name disabled is used by SwiftUI. I got a compiler error when I named the variable disabled so use another name for the variable.

@State private var disableTextField = true

The text field should be disabled until someone taps the Edit button.

Modifiers to Add to the Text Field

Add two modifiers to the text field. The first modifier is the .disabled modifier. Supply the Boolean variable you added to the view.

The second modifier is the .onChange modifier. The change you’re going to track is the change in edit mode. When someone taps the Edit button, the isEditing property is set to true. Set the Boolean variable to false, which enables editing in the text field. When someone taps the Done button, isEditing becomes false. Set the Boolean variable to true, which disables editing in the text field.

TextField("", text: $item.name)
  .disabled(disableTextField)
  .onChange(of: editMode?.wrappedValue) { newValue in
    if (newValue != nil) && (newValue!.isEditing) {
      // Edit button tapped
      disableTextField = false
    }
    else {
      // Done button tapped
      disableTextField = true
    }
}

Sample Project

I have a sample project on GitHub. Look at the PageListView.swift file in the iOS folder to see the code for disabling the text fields in the list.

Moving List Items Using Drag and Drop in SwiftUI Mac Apps

Thu, 28 Oct 2021 18:44:05 +0000

Mac apps usually use drag and drop to rearrange items in a list. You search for how to move list items in SwiftUI, and you find a bunch of examples for iOS that use the .onMove modifier. But when you start to type .onMove in your Mac list, Xcode’s autocomplete shows only an .onMoveCommand modifier. If you try to use .onMove directly on a list in a Mac app, you’ll get a compiler error.

SwiftUI has an .onMoveCommand modifier to move items in a list in a SwiftUI Mac app, but it works with the keyboard, not with drag and drop. How do you use drag and drop to move items in a SwiftUI list in a Mac app?

.onMove Requires ForEach on Mac

The .onMove modifier is the modifier to use to move list items using drag and drop in SwiftUI Mac apps. But you must place a ForEach statement inside the list to enable .onMove. The ForEach statement takes two arguments: the array of items you’re showing in the list and an ID that uniquely identifies each list item.

Apply the .onMove modifier to the ForEach block. The .onMove modifier’s closure takes two arguments: the indices for the list items being moved and the drop destination. Call the array’s move method to reorder the list items.

The following code creates a list of a book’s chapters that you can rearrange using drag and drop:

// The chapter has an id property that uniquely identifies it.
List {
  ForEach($book.chapters, id: \.id) { $chapter in
    TextField("", text: $chapter.title)
  }
  .onMove { indices, destination in
    book.chapters.move(fromOffsets: indices, 
      toOffset: destination)
	}
}

What Xcode Files Should Git Track and Ignore?

Thu, 21 Oct 2021 19:08:30 +0000

When you start using version control in your Xcode projects, you may become confused about which files git should track and which files git should ignore. This confusion is normal. Xcode projects contain much more than your Swift files, and some of these extra files are basically unreadable. What files in your project should you tell git to ignore?

Fortunately the site gitignore.io has solved this problem for you. Go to gitignore.io, enter Xcode in the search field, and click the Create button. You will get a git ignore file with a list of file types that git should ignore. Add the git ignore file to your project folder.

Need More Information on Using Git with Xcode?

Check out my version control book. It has an entire chapter on ignoring files, including what to do when git starts tracking an unwanted file.

Accessing the Document in a SwiftUI Menu

Mon, 20 Sep 2021 17:50:02 +0000

You’re making a SwiftUI document-based Mac app. You have a menu item in your app that performs an action on the document. How do you give the menu access to the document?

Use focused values and focused bindings.

Creating a Focused Value

A focused value provides a way for a SwiftUI app to observe values from the focused view or one of its ancestors. In a document-based SwiftUI Mac app, one of the focused view’s ancestors is the document window. By using a focused value your app can access the focused document.

To create a focused value, you must write two pieces of code. The first is a struct that conforms to the FocusedValueKey protocol. The second is a property for the document as an extension to the FocusedValues struct.

struct DocumentFocusedValueKey: FocusedValueKey {
  typealias Value = Binding<Document>
}
    
extension FocusedValues {
  var document: DocumentFocusedValueKey.Value? {
    get {
      return self[DocumentFocusedValueKey.self]
    }
            
    set {
    	self[DocumentFocusedValueKey.self] = newValue
    }
  }
}

The struct creates a type alias for the document’s type, which is usually a binding to your document type.

The document variable is the value you will use when setting the focused value. The value must match this variable name.

Notice the type of the variable, DocumentFocusedValueKey.Value?. The first part of the type is the name of the struct you created for the focused value. The second part is the name of the type alias you created in the struct.

Setting a Focused Value

The .focusedValue modifier sets a focused value.

.focusedValue(\.document, value)

The name of the first argument must match the name of the variable you created in the FocusedValues extension.

Apple added the .focusedSceneValue modifier in iOS 15 and macOS 12. This modifier works much better than .focusedValue, which requires the person using the app to be focused on a text view or text field. If you can require iOS 15 and/or macOS 12, use .focusedSceneValue.

.focusedSceneValue(\.document, value)

Where do you place the code to set the focused value? Attaching the focused value modifier to the content view in the app file is the most common place in a document-based SwiftUI app.

var body: some Scene {
  DocumentGroup(newDocument: Document()) { file in
    // The document argument matches the name
    // of a property in the content view, 
    // giving the content view access to the document.
    ContentView(document: file.$document)
      // Give the app access to the document.
      .focusedSceneValue(\.document, file.$document)
  }
}

Focused Bindings

A focused binding gives a SwiftUI view access to the focused value. To create a focused binding, declare a variable with the @FocusedBinding property wrapper and supply the name of the focused value in parentheses.

@FocusedBinding(\.document) var document: Document?

Using Focused Bindings in SwiftUI Menus

To use a focused binding in a SwiftUI menu, you must create a SwiftUI view for the menu items. Create the menu items in the group. The following example shows a menu with items to make text bold and italic:

struct BoldItalicView: View {
  @FocusedBinding(\.document) var document: Document?
        
  var body: some View {
    Group {
      Button(action: {
        // In your app call a function that
        // does something to the document.
        applyMarkup(tagType: .bold, document: document)
      }, label: {
            Text("Bold")
      }).keyboardShortcut("b", modifiers: [.command])
                
			Button(action: {
				applyMarkup(tagType: .italic, document: document)
			}, label: {
				Text("Italic")
			}).keyboardShortcut("i", modifiers: [.command])
		}
	}
}

Creating Menu Commands

If you have a menu with multiple menu items, creating a set of menu commands lets you keep the menu creation code in its own Swift file. To create a set of menu commands, supply the views inside the CommandMenu block.

struct MarkupCommands: Commands {
  var body: some Commands {
    CommandMenu("Markup") {
    	BoldItalicView()
      // Add other menu items here
    }
  }
}

Add the Menu to the App

The final step is to add the menu to the app.

struct Swift_Book_BuilderApp: App {
  var body: some Scene {
    DocumentGroup(newDocument: Document()) { file in
      ContentView(document: file.$document)
        .focusedValue(\.document, file.$document)
    }
    .commands {
      MarkupCommands()
    }
  }
}

By creating a struct for the menu commands, the code inside the app’s body is much cleaner.

Credits

I learned much of the information shared in this article from the following article by Lost Moa:

Provide the current document to menu commands in a SwiftUI app

Using New API Features in Swift While Supporting Older OS Versions

Wed, 08 Sep 2021 18:07:59 +0000

Every year at WWDC Apple adds new features to their developer SDKs. Usually these new features require the upcoming version of iOS and macOS. You would like to use the new features while also supporting older versions of iOS and macOS. How do you do this?

Apple provides two Swift keywords to use both new code and old code in your apps: #available and @available.

#available

The #available keyword works with if and guard statements. Supply an operating system version version, and the code inside the if block (or after the guard) executes only on machines capable of running the code. Use the else block for code to run on older operating systems. The following example shows how to run one block of code on iOS 15 and another block on earlier iOS versions:

if #available(iOS 15, *) {
  // iOS 15 code here
} else {
  // Code for earlier iOS versions
}

The following example shows how to run one block of code on macOS 12 and another block on earlier macOS versions:

if #available(macOS 12, *) {
  // macOS 12 code here            
} else {
  // code for earlier Mac versions
}

What Does the Asterisk Do?

The asterisk in the last argument to #available tells the compiler to require the minimum deployment target for other platforms. You must always supply the asterisk to support future platforms Apple may add.

Checking for Multiple Platforms

Suppose you have a multiplatform SwiftUI project and you want to conditionally run code for iOS 15 and macOS 12. Supply the second platform operating system as an additional argument to #available. The following example checks for both iOS 15 and macOS 12:

if #available(iOS 15, macOS 12, *) {
  // Code for newer systems here
} else {
  // Code for older systems here
}

guard Statements

Using available with a guard statement works best with code that should only run on newer versions of iOS and macOS. You can exit and do nothing on machines running on older operating systems.

guard #available(iOS 15, *) else { return }
// iOS 15 code here

@available

The @available keyword lets you mark a function, struct, or class as being available only on certain versions of iOS and macOS. Supply the same information as #available: an operating system version and an asterisk. The following code demonstrates the use of @available in a function:

@available(iOS 15, *)
func myiOS15Function() {
    
}

Struct example:

@available(macOS 12, *)
struct MyMacOS12Struct {
    
}

Class example with multiple platforms:

@available(iOS 15, macOS 12, *)
class MyMultiplatformClass {
    
}

Convert a Swift Range to Use String.Index

Thu, 02 Sep 2021 18:44:53 +0000

The Situation

I was working on a SwiftUI app where I wanted to select text in a text view and insert some text at the start of the selection. SwiftUI’s native text editor currently does not support getting the selection range so I had to wrap an AppKit text view and store the selection range when the selection changes.

func textViewDidChangeSelection(_ notification: Notification) {
  guard let textView = notification.object as? 
    NSTextView else {
            
    return
  }
  control.model.selectionRange = 
    Range.init(textView.selectedRange())
}

The Problem

The code in the previous example gives me a Swift range, which uses integers, Range<Int>. I wanted to use the selection range’s start index as the destination to insert the string.

model.text.insert(contentsOf: textToInsert, 
  at: model.selectionRange?.startIndex)

But the compiler gave me an error. The reason for the error is the String struct’s insert method takes a range that uses string indexes, Range<String.Index>, not integers.

The Solution

The solution is to create a string index for the string and use that as the argument to the insert method. The base for the string index is the string’s start index. The offset for the string index is the selection range’s lower bound.

let insertionPoint = model.text.index(model.text.startIndex, 
  offsetBy: model.selectionRange?.lowerBound ?? 0)
model.text.insert(contentsOf: textToInsert, at: insertionPoint)

Using File Wrappers in a SwiftUI App

Fri, 27 Aug 2021 18:11:55 +0000

What Is a File Wrapper?

A file wrapper is a bundle, which is a collection of one or more directories (folders) and files that appears as a single file in the Finder (Mac) or Files app (iOS). Most Mac applications use bundles. If you want to see what a bundle looks like, select an application, right-click, and choose Show Package Contents.

When should you use a file wrapper? Use a file wrapper when you want to save your app’s data in multiple files. Suppose you’re developing a website building app. A website can have multiple pages, plus folders and files for images, videos, and custom CSS. By using a file wrapper you can save all these files and have it look like a single file to the person using the app. Most apps don’t need to use file wrappers

Types of File Wrappers

The FileWrapper class has the following file wrappers:

Directory
Regular file
Symbolic link

The symbolic link file wrapper points to a file. The most common case of using a symbolic link file wrapper is to point to a large file (image, audio, or video file) to keep the wrapper from getting too big. I’m going to focus on directory and regular file wrappers in this article.

Making Your File Wrapper Appear as a Single File

Document-based apps are more likely to use file wrappers than shoebox apps. If you forget to configure the document to be a file wrapper, the document will appear as a folder instead of a single file.

To configure the document to be a file wrapper, perform the following steps:

Select the project from the project navigator to open the project editor.
Select the app from the Targets list in the project editor.
Click the Info button at the top of the project editor.
Click the disclosure triangle next to the Exported Type Identifiers section in the project editor.
Enter com.apple.package in the Conforms To text field.
Click the disclosure triangle next to the Imported Type Identifiers section in the project editor.
Enter com.apple.package in the Conforms To text field.

Creating a Document File Wrapper

You must create a file wrapper when saving the document. If you create a document-based SwiftUI app, you should see the following function in the document struct’s Swift file:

func fileWrapper(configuration: WriteConfiguration) 
  throws -> FileWrapper

This function is called when saving the document. Your code to create the file wrapper goes in this function.

To create a file wrapper you must perform the following tasks:

Create a directory file wrapper
Convert your app’s data to a Data object
Create a regular file wrapper
Add the file to a directory file wrapper

Creating a Directory File Wrapper

At a minimum you must create a root directory for the file wrapper. You will return this wrapper in the call to fileWrapper. To create a directory file wrapper, call the FileWrapper method directoryWithFileWrappers and supply an empty Swift dictionary.

let mainDirectory = FileWrapper(directoryWithFileWrappers: [:])

Call directoryWithFileWrappers and supply an empty dictionary for any additional directories you want to create.

let pagesDirectory = FileWrapper(directoryWithFileWrappers: [:])

The root directory of a wrapper does not need a name because it does not appear in the Finder or Files app. But any other directories you create require a name. Set the preferredFilename property to name the directory.

pagesDirectory.preferredFilename = "Pages"

Call the addFileWrapper method to add the directory to the root directory.

mainDirectory.addFileWrapper(pagesDirectory)

Convert App Data to a Data Object

Files in file wrappers store their data in a Data object. You must convert your app’s data to Data to use file wrappers. Converting to Data depends on what you are storing, but the following code converts a string to Data:

let pageData = pageString.data(using: .utf8)

Creating a Regular File Wrapper

To create a file wrapper for a regular file, call the FileWrapper method regularFileWithContents and supply the Data object that contains the file’s data.

let wrapper = FileWrapper(regularFileWithContents: data)

Set the preferredFilename property to name the file.

wrapper.preferredFilename = "index.html"

In a real app you won’t be hardcoding filenames often. Suppose you have a document that has a list of pages. You would use the page’s title as the filename instead of giving the file a specific name. Remember that you use file wrappers to save multiple files. If you have 20 files to save, hardcoding the name of each file is going to be a pain. The following code demonstrates how to save a collection of text files:

// A page has a title and text
for page in pages {
  if let data = page.write() {
    let wrapper = FileWrapper(regularFileWithContents: data)
    wrapper.preferredFilename = page.title
    pagesDirectory.addFileWrapper(wrapper)
  }
}
    
func write() -> Data? {
  return text.data(using: .utf8)
}

Call addFileWrapper to add a file to a directory.

Reading from a File Wrapper

At this point you know how to create a file wrapper and save data to it. The next step is to read data from the file wrapper when opening a document.

The SwiftUI document structure provides the following initializer to read data from a file wrapper:

init(configuration: ReadConfiguration) throws

This initializer is where you add the code to read from the file wrapper. To read from a file wrapper, you must perform the following tasks:

Access the directory holding the files
Read the individual files
Load the data from the file

Access the Directory Holding the Files

If you store all the files inside the root directory, you won’t need to write any code to access the directory. But if you have files inside a subdirectory, you must call the fileWrappers method and supply the name of the subdirectory as the dictionary value.

if let wrappers = mainDirectory.fileWrappers {
  let pagesDirectory = wrappers["Pages"]
}

The SwiftUI initializer takes a read configuration as an argument. The ReadConfiguration struct has a file property that provides access to the root directory of the file wrapper.

init(configuration: ReadConfiguration) throws {
  guard let pagesDirectory = configuration.file.fileWrappers?["Pages"] else {
    throw CocoaError(.fileReadCorruptFile)
  }
}

Reading the Individual Files

Use the fileWrappers property to access the files in a directory file wrapper. Go through each file and load the data. Use the regularFileContents property to access the file contents.

if let pageFiles = pagesDirectory.fileWrappers {
  for pageFile in pageFiles {
    readPage(pageFile: pageFile.value)
  }
}
    
mutating func readPage(pageFile: FileWrapper) {
  if let filename = pageFile.filename,
    let fileData = pageFile.regularFileContents {
    
    // Create a page, load the data
    // from the file, and add it to an array.
    let page = Page()
    page.title = filename
    page.read(data: fileData)
    pages.append(page)
	}
}

Loading the Data

The file wrapper’s regularFileContents property gives you a Data object to load the file’s contents in your app. Loading the file’s contents depends on the type of data being stored. The following code loads a file’s contents into a string variable:

func read(data: Data) {
  if let fileContents = String(data: data, encoding: .utf8) {
    text = fileContents
  }
}

Sample Project

I have a sample project on GitHub that demonstrates saving data to a file wrapper. Look at the files Wiki.swift and Page.swift.

Creating a Master-Detail Interface in SwiftUI

Mon, 23 Aug 2021 18:27:46 +0000

Master-detail interfaces are common in iOS and Mac apps. Select an item from the master view to see additional information in the detail view. In SwiftUI you use two views to create a master-detail interface: NavigationView and NavigationLink.

UPDATE

Apple deprecated NavigationView in iOS 16 and macOS 13. The replacements for NavigationView are NavigationStack and NavigationSplitView, but they require iOS 16+ and macOS 13+. If you want to support earlier OS versions, you must use NavigationView.

Navigation View

A navigation view is the most common way to create a master-detail interface in SwiftUI. On iOS selecting an item from the master view, which is usually a SwiftUI list, takes you to the detail view. On macOS selecting an item from the master view shows the details in the detail view.

The following code shows how to create a navigation view:

var body: some View {
  NavigationView {
    MasterView()
    DetailView()
  }
}

In a real app you will pass data as arguments to the master view and detail view. The data depends on your app, which is why I didn’t supply any arguments in the code listing.

The article Passing Data to SwiftUI Views provides more detailed information on passing data to views.

Navigation Link

The final part of creating a master-detail interface is to add a navigation link in the master view and set its destination to the detail view.

List(items) { item in
  NavigationLink(destination: DetailView()) {
    Text(item.title)
  }
}

This example creates a navigation link for each item in the list. Selecting an item from the list fills the detail view with information about the selected item. In a real app you will pass the data to show in the detail view as an argument to the detail view.

Handling Selection

There are some situations where you may need to hold on to the selection. Mac apps need access to the selected item when deleting an item from a list.

In the master view create a property to store the selection. Make it optional and set its value to nil.

@State private var selectedItem: Item? = nil

When someone selects an item from the list, the selectedItem property will store it. In the call to create the navigation link, add the tag and selection arguments. The tag is usually the current item. The selection is the selected item.

List(items) { item in
  NavigationLink(destination: DetailView(),
                tag: item,
              	selection: $selectedItem) {
    Text(page.title)
  }
}

Sample Project

I put a sample project on master-detail interfaces on GitHub. It builds upon the project from the Make a Markdown Editor in SwiftUI article by displaying a list of Markdown pages to edit. Look at the files ContentView.swift and PageListView.swift for the code on making the master-detail interface.

Using a Scrollable Text View in a Mac SwiftUI App

Mon, 16 Aug 2021 17:40:47 +0000

In the article Using Text Views in a SwiftUI App I showed how to use a UIKit text view in a SwiftUI app. But if you use the code from that article in a Mac app, you’ll run into a problem. The text view won’t scroll when you reach the bottom of the text view. In this article you’ll learn how to make the text view scroll in a Mac app.

Much of the code for this article comes from the CodeEditor Swift package, which is a text editor for SwiftUI with syntax highlighting.

Create a Scroll View

The reason the text view won’t scroll is that Mac text views aren’t wrapped in scroll views like iOS text views are. When you create the text view, you have to create both a text view and a scroll view. Set the scroll view’s document view to the text view. Give the scroll view a vertical scroller. Return the scroll view.

func makeNSView(context: Context) -> NSScrollView {
  let textView = NSTextView()
  textView.autoresizingMask = [.width, .height]
  textView.isEditable = true
  textView.delegate = context.coordinator
  textView.allowsUndo = true
    
  let scrollView = NSScrollView()
  scrollView.hasVerticalScroller = true
  scrollView.documentView = textView
  return scrollView
}

Setting the autoresizing mask ensures the text view resizes properly when the window resizes.

Updating the View

When writing the updateNSView function, supply the scroll view as the argument. Use the documentView property of the scroll view to access the text view and update its contents.

func updateNSView(_ scrollView: NSScrollView, context: Context) {
  guard let textView = scrollView.documentView 
    as? NSTextView else {
    
    assertionFailure("unexpected text view")
    return
  }
    
  if textView.delegate !== context.coordinator {
    textView.delegate = context.coordinator
  }
    
  // model is your data model whose text you are
  // showing and editing in the text view.
  textView.string = model.text
}

Removing Items from SwiftUI Lists in Mac Apps

Thu, 01 Jul 2021 17:35:58 +0000

Most examples of removing items from SwiftUI lists use the .onDelete handler, which is not available for Mac apps. In this article I share what I learned to remove list items from SwiftUI Mac apps.

To remove items from SwiftUI lists in Mac apps, you must perform the following tasks:

Add a variable to the list view to store the selected list item.
If you are using a navigation link, supply a tag and selection when creating the link.
Make your struct or class conform to the Equatable and Hashable protocols.
Add the .onDeleteCommand handler to the list. The .onDeleteCommand handler is the handler SwiftUI Mac apps use to remove list items.

Add a Selection Variable to the List View

To remove an item from a SwiftUI list, the list view requires a variable to store the item you want to remove. Create an optional for the variable and set it to nil initially.

@State private var selection: ListItemStruct? = nil

ListItemStruct is the name of the data structure in your app that you want to show in the list.

When you supply this selection when creating a navigation link, SwiftUI keeps track of the selected item in the list.

Supply a Tag and Selection to the Navigation Link

Most SwiftUI apps that use lists use a navigation link to create master-detail interfaces. Select an item from the list to show additional information in the detail view. Add a call to NavigationLink in the master view and set its destination to the detail view.

NavigationLink(destination: DetailView(detailItem: item)) {
  ...
}

To support more complex selection behavior, you must supply two additional arguments to the navigation link call: tag and selection. Usually the tag is the current list item you’re adding to the list. The selection is the variable you added to the list view.

The following code demonstrates how to show a list of a book’s chapters:

// The book has an array of chapters.
@Binding var book: Book
@State private var selection: Chapter? = nil
    
List($book.chapters) { $chapter in
  // ChapterView is a SwiftUI view that 
  // displays the chapter's contents.
  NavigationLink(destination: ChapterView(chapter: chapter), 
    tag: chapter, 
    selection: $selection) {
    TextField("", text: $chapter.title)
  }
}

This example uses the improved syntax Apple added in Xcode 13 to bind list text fields to items in an array. If you’re using Xcode 12 you will have to use a Text to display the titles and remove the $ character from $chapter.

Make Your Struct/Class Conform to Equatable and Hashable Protocols

To use the tag and selection arguments in a navigation link, your struct or class must conform to the Equatable and Hashable protocols. Your project won’t compile until you make the struct or class conform to those protocols.

Making your struct or class conform to Equatable requires you to implement the == operator to check for equality.

static func == (lhs: Chapter, rhs: Chapter) -> Bool {
  lhs.id == rhs.id
}

Replace Chapter with the name of your struct or class. Do whatever comparisons you need to make to determine that two objects are equal. SwiftUI list items require a unique ID. That’s what I used to determine equality in the example.

To conform to the Hashable protocol, you must implement the hash function.

func hash(into hasher: inout Hasher)

Inside the hash function, call the hasher’s combine function for each property in your struct or class. Supply the name of the property.

func hash(into hasher: inout Hasher) {
  hasher.combine(id)
	// Call hasher.combine() for each property 
  // in your data structure.
}

Add the .onDeleteCommand Handler to the List

The last step is to remove the item from the list. Add the .onDeleteCommand handler to the list to enable the Delete menu item in the Edit menu. Inside the block of code, you will use the selection variable you added to the list view to find the selection index. Use the selection index to remove the item from the list.

.onDeleteCommand {
  if let selection = self.selection,
    let selectionIndex = book.chapters.firstIndex(of: selection) {
    
    book.chapters.remove(at: selectionIndex)
  }
}

The firstIndex function returns the first selected item in the list. After getting the index of the selected item, remove that item from the array that populates the list.

Now let’s put the whole list view together.

List($book.chapters) { $chapter in
  NavigationLink(destination: ChapterView(chapter: chapter), 
    tag: chapter, 
    selection: $selection) {
    TextField("", text: $chapter.title)
  }
}
.onDeleteCommand {
  if let selection = self.selection,
    let selectionIndex = book.chapters.
      firstIndex(of: selection) {
    
    book.chapters.remove(at: selectionIndex)
  }
}

Removing an Item with a Button and the Delete Key

At this point you can remove a list item by choosing Edit > Delete. But you may want to provide a button to remove an item. How do you remove list items by clicking a button?

Start by moving the code inside the .onDeleteCommand handler into its own function. Moving the deletion code into a separate function will also make the list code cleaner.

func deleteChapter() {
  if let selection = self.selection,
    let selectionIndex = book.chapters.
      firstIndex(of: selection) {
    
    book.chapters.remove(at: selectionIndex)
  }
}

Now the .onDeleteCommand handler looks like the following:

.onDeleteCommand {
  deleteChapter()
}

Call the function in your button. Add a .keyboardShortcut handler to the button to remove list items with the Delete (Backspace) key.

Button(action: { 
  deleteChapter() 
}, label: {
   Label("Delete", systemImage: "trash")
  .foregroundColor(.red)
})
.keyboardShortcut(.delete, modifiers: [])

I haven’t figured out how to add a keyboard shortcut for the Delete menu item in the Edit menu. Every example I’ve seen on creating keyboard shortcuts for menu items in SwiftUI uses custom menu items, not the menu items that Apple supplies. I’ll update the article if I ever find a solution.

Sample Project

I have a project on GitHub that supports removing items from lists. Look at the PageListView.swift and Wiki.swift files for the list removal code.

Another sample project for SwiftUI list item removal is the Feed Read project by TrozWare for the Back to the Mac conference.

Storing an Array of Custom Structs in Core Data

Wed, 23 Jun 2021 18:35:47 +0000

A common question I see online about Core Data involves storing arrays. You have an array of a custom struct or class that you want to store in Core Data. Your initial instinct is to create an attribute for the array in your Core Data entity. But you discover that none of the available attribute types work. How do you store the array?

The Solution: Create a To-Many Relationship

There are two steps to storing an array of a custom struct or class in Core Data. The first step is to create a Core Data entity for your custom struct or class.

The second step is to add a to-many relationship in the Core Data entity where you want to store the array. The destination for the relationship is the entity you created for the custom struct or class. The to-many relationship holds the array items. Saving the main entity, the entity where you want to store the array, will save the array items.

Keep in mind that Core Data uses sets to store to-many relationships instead of arrays. Each item that Core Data stores must be unique. Each element of a set must also be unique, which is why Core Data uses sets.

A Simple Example

Let’s look at a simple example of creating a to-many relationship. Suppose you have a Note entity and you want to store a list of each note’s tags. Start by creating a Tag entity and adding the attributes you want a tag to have.

After creating the Tag entity, select the Note entity in Xcode’s data model editor and add a relationship. Name the relationship tags. Choose Tag as the destination.

When you select the relationship, the data model inspector should be visible on the right side of the project window. Choose To Many from the Type menu. The relationship must be to-many to store a set (array) of items.

Select the Ordered checkbox if you need the relationship items to be in a specific order.

After creating the relationship each note has a list of tags. With the right controls in the app, you can add and remove tags. When you save a note Core Data also saves the tags.

Resources for Learning Combine

Thu, 22 Apr 2021 18:37:13 +0000

Combine is Apple’s framework for handling asynchronous events in Swift. Combine and SwiftUI are the future for making iOS and Mac apps. This post lists resources for learning Combine.

Books

Joseph Heck’s Using Combine is freely available online.
Daniel Steinberg’s A Combine Kickstart provides a nice introduction to Combine.
Donny Wals’s Practical Combine provides many practical examples of using Combine.
Ray Wenderlich’s Combine: Asynchronous Programming with Combine is a comprehensive resource for Combine.
Mark Moeykens’ Combine Mastery in SwiftUI provides a visual guide to learning Combine with SwiftUI.

Websites

I don’t know of any websites focused solely on Combine, but the following websites have articles on Combine:

Saving Data When Your Swift App Quits

Mon, 12 Apr 2021 17:48:34 +0000

A common scenario for iOS and Mac apps is to save data when someone quits the app. You have written a function to save the data. Where do you make the call when the app quits? This article answers that question, both for the SwiftUI app life cycle and the classic AppDelegate life cycle.

Using the SwiftUI App Life Cycle

In Xcode 12 Apple introduced a native SwiftUI app life cycle. The new life cycle has a scenePhase environment value that stores the app’s current phase, such as active, inactive, or background.

Add a property to the app struct for the scene phase. Add the .onChange modifier to the app’s window group or document group. Check if the phase is .background. If it is, make a call to save the data. The following code shows how to check when the app goes in the background:

@main
struct MySwiftUIApp: App {
  @Environment(\.scenePhase) private var scenePhase
    
  var body: some Scene {
    WindowGroup {
      ContentView()
    }
    .onChange(of: scenePhase) { phase in
      if phase == .background {
        // Save here
      } 
    }
	}
}

Using the AppDelegate Life Cycle

If your Xcode project has a file named AppDelegate.swift, it is using the AppDelegate life cycle. Open the AppDelegate.swift function, and you should see multiple empty functions for handling app events.

An iOS app that wants to save when someone quits the app should make a call to save the data in the function applicationDidEnterBackground. This function is called when the person quits your app.

func applicationDidEnterBackground(_ application: UIApplication) {
  // Save here
}

A Mac app should make the save call in applicationWillTerminate.

func applicationWillTerminate(_ aNotification: Notification) {
  // Save here
}

Xcode Installation Questions

Mon, 05 Apr 2021 17:58:43 +0000

People learning iOS development without prior programming experience have a lot of questions on installing Xcode, Apple’s tool for developing iOS and Mac apps. This post collects these questions and answers them.

Where do I get Xcode?

The easiest way to install Xcode is from the Mac App Store. The Mac App Store has the latest version, which usually requires the latest version of macOS.

If your Mac can’t run the latest version of Xcode, go to Apple’s Xcode Downloads page and install an older version. You can also use the Downloads page to install the latest version if you run into problems with the Mac App Store.

A faster way to find Xcode download links is to go to Xcode Releases, a site that has download links for every version of Xcode. Xcode Releases also lists the minimum version of macOS required for each Xcode version.

Another alternative to the App Store is to use the Xcodes app to install Xcode. I have not used Xcodes, but many people swear by it, saying it installs Xcode much faster than the App Store.

Why does Xcode take forever to install?

Xcode is a huge app. Verifying and expanding it takes a really long time. Even with a fast Internet connection, it will take 1–2 hours to install Xcode.

A Twitter thread explains why expanding takes so much time and provides a tip to speed up the expanding.

If you are installing Xcode from the Mac App Store, you can see the progress of the install from the LaunchPad app.

Why does Apple say I don’t have enough disk space to install Xcode?

Xcode requires a lot of disk space to install. You need 4–5 times the size of the Xcode download to install it. The file you are downloading is a compressed file. You need enough free space to temporarily store both the compressed and expanded files. If you have a Mac with a 128 GB drive, you will have a tough time installing Xcode.

If you get an error message saying there isn’t enough free space to install Xcode, free up more disk space until the error message goes away.

Some ways to free up disk space and work around space limitations include the following:

Download Xcode from the Xcode Releases site onto an external drive and expand it there. Copy the expanded file to your main drive.
Restarting your Mac can free up disk space if you haven’t restarted the Mac in several days.
The Dev Cleaner app can free up space used by Xcode caches and old iOS simulators.
Delete existing versions of Xcode before installing a new version.

Can I install Xcode on an external drive?

Xcode must be installed on your Mac’s startup disk. If you make an external drive the startup disk, you can install Xcode on an external drive. Use the System Preferences app (Choose Apple > System Preferences from the menu bar) to set the startup disk.

Can I run Xcode on an iPad?

Xcode currently runs only on Macs. Apple has a Swift Playgrounds app for iPad to learn Swift programming. Version 4, which requires iOS 15, lets you develop iOS apps on an iPad.

Can I run Xcode on a Windows PC?

Not without violating Apple’s license on macOS. Xcode currently runs only on macOS. Apple’s license forbids installing macOS on non-Apple hardware.

Can I have multiple versions of Xcode on my Mac?

Yes you can.

If you are installing Xcode from the Mac App Store, make sure you don’t overwrite your existing Xcode install. When installing from the Mac App Store, Apple adds a file named Xcode in your Applications folder. Change the name of the existing Xcode app on your Mac before installing the new version.

Where are the Single View and Master-Detail App Project Templates?

Mon, 15 Feb 2021 19:53:03 +0000

Prior to Xcode 12 Xcode had the following iOS application project templates:

Single View App
Master-Detail App
Page-Based App
Tabbed App

If you create an iOS application project in Xcode 12, you will notice these project templates are missing. In Xcode 12 Apple consolidated these project templates into one template: App. If you are following a tutorial that tells you to choose one of the older templates that no longer exist, choose the App template.

Using Environment Variables in Swift Apps

Mon, 25 Jan 2021 19:44:04 +0000

When to Use Environment Variables

Most Swift apps do not need environment variables. A common reason to use environment variables is for apps that call a website’s REST APIs. To gain access to someone’s account on the website, your Swift app uses a client ID and client secret from the website. Storing the client ID and client secret in environment variables is safer than storing them as strings in your code.

Suppose you are developing a git client app. Your app wants to push commits to GitHub. To push commits to GitHub you must create an OAuth app for your app in GitHub. The GitHub OAuth app contains a client ID and a client secret that your Swift app uses to authenticate the user so your Swift app can access the person’s GitHub account. GitHub recommends using environment variables to store the client ID and client secret.

Add the Environment Variables from Xcode’s Scheme Editor

The first step to using environment variables is to add them to your Xcode project. Use Xcode’s scheme editor to add environment variables to your app. Use the jump bar next to the Run and Stop buttons in the project window toolbar to open the scheme editor.

Select the Run step on the left side of the scheme editor. Click the Arguments button at the top of the scheme editor to access the environment variables. Use the Add (+) button to add the environment variables.

Accessing Environment Variables in Your Swift Code

After adding environment variables, you can access them in your code. Use the ProcessInfo class to access environment variables. The class has a processInfo property that contains a dictionary of values. The name of the environment variable is a key in the dictionary. Use that key to get the environment variable’s value. The following code demonstrates how to access a variable containing a GitHub OAuth app’s client ID:

if let clientID = ProcessInfo.processInfo.
  environment["GITHUB_CLIENT_ID"] {
    
}

Should I learn Swift or SwiftUI?

Mon, 11 Jan 2021 05:02:19 +0000

I see a lot of new iOS developers ask the question in the title of this article. The short answer is both. To write SwiftUI apps you must also learn Swift because Swift is the programming language SwiftUI uses. The rest of this article provides a more detailed explanation.

UIKit

In 2008 Apple gave developers a SDK (Software Development Kit) to let them make native iOS apps. The heart of the SDK was UIKit, a framework for creating the views and controls in iOS apps, such as buttons, text fields, and table views.

UIKit uses the Objective-C programming language. Using Objective-C worked well for existing Mac developers, who were already using Objective-C to make Mac apps. But the release of the iOS SDK attracted lots of new developers to the Apple developer community. These new developers found Objective-C’s syntax to look strange and found it difficult to understand. They wanted a language with a syntax that looked more familiar.

Swift

In 2014 Apple unveiled their solution for developers who hated Objective-C: the Swift programming language. Swift’s syntax looked more familiar to people who came to iOS development from web development and Windows development. Now iOS developers had two language choices for making iOS apps with UIKit: Swift and Objective-C.

SwiftUI

In 2019 Apple released the initial version of SwiftUI, a new framework for developing apps for all of Apple platforms: iOS, Mac, tvOS, and watchOS. SwiftUI has only one language: Swift. You must know Swift to use SwiftUI.

The Language and Framework Options for iOS Apps

Someone who wants to make iOS apps with Apple’s frameworks has three options.

Use UIKit with Objective-C.
Use UIKit with Swift.
Use SwiftUI with Swift.

Which option should use choose? You won’t be making a mistake no matter which option you choose. But for someone new to iOS development, I recommend Option 3, write the app with SwiftUI using Swift. SwiftUI is the future of iOS development. You’re eventually going to have to learn it so you might as well learn it now.

Getting Started with Swift Unit Testing in Xcode

Tue, 15 Dec 2020 19:05:21 +0000

In this article you’ll learn what you need to start unit testing your Swift code in Xcode.

Adding a Unit Test Target to Your Xcode Project

To unit test your app, your Xcode project must have a unit test target. The easiest way to add a unit test target to your project is to select the Include Tests checkbox when you create the project. Selecting the checkbox creates targets for unit tests and UI tests.

To add a unit test target to an existing Xcode project, choose File > New > Target.

Select your app platform (iOS, macOS, watchOS, tvOS) from the top of the New Target Assistant. Select the Unit Testing Bundle target from the list of targets. You will have to scroll through a long list of application extension targets to find the test targets.

Adding a Unit Test Class to Your Xcode Project

When you create the unit test target, Xcode includes a unit test class file. It has the name AppNameTests.swift, where AppName is the name of your project. Unless you have a really small project, you will have multiple unit test classes.

Choose File > New > File to add a new file to your project.

Select Unit Test Case Class from the list of file templates. Click the Next button.

Enter the name of the class in the Class text field. The subclass should be set to XCTestCase, and the language should be set to Swift. Click the Next button.

Save the file inside the Tests folder. Make sure to select the checkbox for the unit test target.

Click the Create button to finish creating the unit test class.

The Initial Unit Test Class

Select the unit test class’s Swift file to open it. It should look similar to the following code:

import XCTest
@testable import Scrumdinger
    
class ScrumdingerTests: XCTestCase {
    
  override func setUpWithError() throws {
    // Put setup code here. This method is called before the invocation of each test method in the class.
  }
    
  override func tearDownWithError() throws {
    // Put teardown code here. This method is called after the invocation of each test method in the class.
  }
    
  func testExample() throws {
    // This is an example of a functional test case.
    // Use XCTAssert and related functions to verify your tests produce the correct results.
  }
    
  func testPerformanceExample() throws {
    // This is an example of a performance test case.
    self.measure {
      // Put the code you want to measure the time of here.
    }
  }
    
}

The first two lines of code import the XCTest framework, which is the framework Xcode uses for unit testing Swift code, and your app. You must use the @testable import statement to give the unit test class access to your app’s code. If your app name has spaces in it, use the underscore character instead of spaces in the @testable import call.

@testable import My_App_Name

Next comes the declaration of the unit test class. It inherits from XCTestCase, the base class for Xcode’s unit test classes.

Finally comes the four empty test methods.

The setUpWithError method gets called before running each test in the class. Put any setup code you need to run before each test in this method.
The tearDownWithError method gets called after each test runs.
The testExample method provides a shell for a unit test. You can delete this method.
The textPerformanceExample method provides a shell for a performance unit test. You can delete this method.

The throws keyword means the test method throws an exception if the test fails.

Older versions of Xcode may not have the throws keyword in the test methods. The setup and teardown methods may not have the WithError part at the end.

XCTest Test Methods

Each unit test requires you to write a method for it. A unit test method has the following requirements:

It must start with the word test.
It takes no arguments.
It returns no value.

The following code shows the definition of a unit test method:

func testMyExample() throws {
    
}

In the test start by calling the code in your app that you want to test. Then make an assertion, which I talk about next.

XCTest Assertions

Each test needs at least one assertion, which determines whether or not the test passes. XCTest assertions start with XCTAssert. If you start typing XCTAssert, Xcode’s code completion should show you a list of all the available assertions, but the following are the most widely-used assertions:

XCTAssertNotNil asserts a variable is not nil.
XCTAssertTrue asserts a condition is true.
XCTAssertFalse asserts a condition is false.
XCTAssertEqual asserts two values are equal.

The simplest way to write an assertion is to supply an expression.

XCTAssertTrue(temperature > 0)

But when you supply only the expression, all you get when a test fails is a message that the test failed. In this assertion example, when the assertion fails, you would like to know what the value of temperature is. Supply an error message to report as the final argument in the assertion. Wrap the variable whose value you want to report using the following syntax:

\(variableName)

The following shows an improved assertion that the temperature is above 0.

XCTAssertTrue(temperature > 0, "The temperature should be 
  above 0. Temperature: \(temperature)")

Running Unit Tests

Xcode provides multiple ways to run your tests.

Press Cmd-U to run all your tests.
Run a unit test class’s tests from the Xcode editor by clicking the diamond-shaped button on the left side of the editor next to the test class name.
Run a single test from Xcode’s editor by clicking the diamond-shaped button next to the test method.
Press Cmd–6 to open the test navigator. Selecting the test target, a test class, or a test will make a small button appear on the right side of the navigator. Click the button to run the target’s tests, the class’s tests, or the single test, depending on what you selected.

Unit Testing Checklist

Use the following checklist to start unit testing your Swift code in Xcode:

Create a unit test target by selecting the Include Tests checkbox when creating your Xcode project.
Add unit test classes to the test target by choosing File > New > File.
Import the XCTest framework in your unit test classes.
Use the @testable import statement to give your unit test classes access to your app’s code.
Add test methods to your unit test classes.
Test methods start with test, take no arguments, and return no value.
Add at least one XCTest assertion in your test methods.
Press Cmd-U to run the tests.

Make a Markdown Editor in SwiftUI

Mon, 23 Nov 2020 19:43:37 +0000

In this tutorial you will make a Markdown editor with live preview using SwiftUI. This editor will run on both iOS and Mac. It’s a nice example to demonstrate how to create a document-based, multi-platform SwiftUI app. Plus, it shows how to use a WebKit web view in SwiftUI.

This tutorial uses the new document-based app features Apple added in Xcode 12. You must be running Xcode 12.2+ to create a multi-platform SwiftUI app. The iOS app requires iOS 14+, and the Mac app requires macOS 11+. If you are running macOS 10.15 (Catalina) on your Mac, you can still make the editor. You won’t be able to run the Mac version.

To keep the tutorial from getting too long, I will gloss over some steps and explanations that I covered in the following articles:

Create the Project

Start by creating the project.

Choose File > New > Project in Xcode.
Click the Multiplatform button at the top of the New Project Assistant.
Choose Document App from the list of application templates.
Click the Next button.
Name the project in the Product Name text field.
Click the Next button.
Choose a location to save the project.
Click the Create button.

If you look at the project navigator, you will see Xcode creates the following folders for your project:

The Shared folder contains files that both the iOS and Mac app targets use.
The iOS folder contains files that the iOS app uses.
The Mac folder contains files that the Mac app uses.

In the Shared folder are Swift files for the app, document, and content view.

Run the project and you will see that you have a working plain text editor. You can create documents, edit text, save documents, and load documents.

Add the Ink Package

This project uses the Ink Markdown parser to convert the Markdown you type in the text editor to HTML that you will preview. Ink has Swift Package Manager support to simplify adding it to your Xcode project.

Select the name of your project from the project navigator to open the project editor. Select the project from the project editor and click the Swift Packages button at the top of the editor to add the Ink package.

A current limitation in Xcode’s Swift Package Manager support is you can add a package to only one target initially. To add Ink to the other app target, select the target from the project editor and add the Ink framework from the Frameworks, Libraries, and Embedded Content section.

Add Web Views

To preview the Markdown you write, you need a web view to display the HTML. SwiftUI does not currently have a native web view so you must use a WebKit web view, WKWebView, for the preview.

WKWebView has both iOS and Mac support, but you’re going to have to create two web view files: one for the iOS app and one for the Mac app. The code is going to be almost identical. The reason you need two files is that SwiftUI has separate protocols for working with UIKit(iOS) and AppKit(Mac) views.

Create one new Swift file in the iOS folder in the project navigator and create a second file in the Mac folder. Make sure the file in the iOS folder is a member of the iOS app target. Make sure the file in the Mac folder is a member of the Mac app target. You can set the target membership for a file using the File Inspector on the right side of the project window.

Add the following code to the iOS Swift file:

import SwiftUI
import WebKit
    
struct WebView: UIViewRepresentable {
  var html: String
        
  init(html: String) {
    self.html = html
  }
        
  func makeUIView(context: Context) -> WKWebView {
    let webView = WKWebView()
    return webView
  }
        
  func updateUIView(_ uiView: WKWebView, context: Context) {
    uiView.loadHTMLString(html, baseURL: nil)
  }
}

The web view uses the SwiftUI and WebKit frameworks so you must import them. When you use a UIKit view in a SwiftUI app, the view must conform to the UIViewRepresentable protocol. The html property stores the HTML to display in the web view.

There are three functions. The init function initializes the web view with some HTML to display. The makeUIView function creates the web view. The updateUIView function loads the HTML string to show in the web view.

The Mac code is almost identical. Replace anything starting with UI with NS.

Parsing the Markdown

The next step is to write some code to parse the Markdown to HTML. Open the ContentView.swift file. Import the Ink framework.

import Ink

Add the following computed property to the ContentView struct:

var html: String {
  let parser = MarkdownParser()
  return parser.html(from: document.text)
}

This code creates an Ink parser and calls a function that converts the document text into HTML. This code is much easier to write than creating your own Markdown parser.

Build the User Interface

The last step is to build the user interface. The user interface contains a text editor and a web view side by side.

The body property for the content view should look like the following code:

var body: some View {
  HStack {
    TextEditor(text: $document.text)
    WebView(html: html)
  }
}

The code creates a horizontal stack so the text editor and web view are side by side. The text editor is on the left and contains the document’s text. The web view is on the right and displays the HTML you parsed from the Markdown text. The iOS app uses the iOS version of the web view. The Mac app uses the Mac version of the web view.

Run the project. Any Markdown you type in the text editor will appear as HTML in the web view. The Ink parser does not currently support creating code blocks with indentation. You must add three backticks on the line above and below the code to create a code block.

I have the project on GitHub for you to look at if you run into problems.

Renaming Xcode Projects

Mon, 19 Oct 2020 18:18:42 +0000

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.

I recommend placing your project under version control or backing up your project before you rename it. If something goes wrong during the rename, you can go back to the way your project was before. Read the following article to learn how to put your Xcode project under version control:

Putting Your Xcode Project on GitHub, Bitbucket, or GitLab

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.

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.

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

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

Thu, 08 Oct 2020 19:01:44 +0000

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

High Level Notarization Steps

Take the following steps to notarize your Mac app:

Archive your project in Xcode by choosing Product > Archive.
Open Xcode’s Organizer window by choosing Window > Organizer.
Select your archive from the list of archives.
Distribute the app.
Choose a distribution method.
Choose a destination.
Choose a code signing option.
Review and upload.
Wait for Apple to notarize.
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:

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.

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.

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.

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.

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

Mon, 14 Sep 2020 18:41:25 +0000

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:

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.

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

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

Tue, 08 Sep 2020 18:05:09 +0000

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 epub 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

Tue, 01 Sep 2020 19:20:49 +0000

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

Mon, 22 Jun 2020 17:31:07 +0000

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.

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

Showing a Sheet When Choosing a Menu Item in AppKit

Tue, 09 Jun 2020 18:12:08 +0000

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:

Give the sheet’s view controller a storyboard ID to identify the view controller.
Add an action to the main view controller that creates an instance of the sheet view controller and presents it as a sheet.
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.

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

Wed, 03 Jun 2020 19:14:21 +0000

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.

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

Tue, 12 May 2020 19:07:23 +0000

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.

The following article provides an introduction on working with the keychain:

Saving Passwords in the Keychain in Swift

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

Mon, 04 May 2020 19:08:42 +0000

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.

Xcode Breakpoint Actions

Fri, 24 Apr 2020 19:18:49 +0000

Xcode’s breakpoints pause your program so you can step through your code line by line and examine the values of your variables. But sometimes you don’t want to pause your program. You want to do something like print the value of a variable to the console. Xcode has breakpoint actions that let you do things like print a variable’s value, run debugger commands, and run scripts.

If you’re unfamiliar with Xcode breakpoints, read Introduction to Xcode’s Debugger.

Creating a Breakpoint Action

Right-click on a breakpoint in Xcode’s editor or in Xcode’s breakpoint navigator (Press Cmd–8) and choose Edit Breakpoint. A popover opens to edit the breakpoint.

Click the Add Action button to create a breakpoint action.

Breakpoint Actions

When you click the Add Action button, the popover looks similar to the following screenshot:

Xcode provides the following breakpoint actions:

AppleScript
Capture GPU Frame
Debugger Command
Log Message
Shell Command
Sound

A breakpoint can have multiple actions. For example you can run a debugger command and play a sound when reaching a breakpoint.

AppleScript

The AppleScript breakpoint action runs an AppleScript script.

Enter the script text in the text view. Most of you using the AppleScript action will write the script in a text editor and paste it into the text view. Click the Compile button to make sure the script works.

Capture GPU Frame

The Capture GPU Frame action captures a frame from the graphics card. This action helps most with apps that work with graphics, such as games, image editors, and video editing apps.

Debugger Command

The Debugger Command action runs an LLDB debugger command. The LLDB site has information on all the LLDB commands.

Enter the command in the text field.

Log Message

The Log Message breakpoint action logs a message to Xcode’s debug console. A common use of message logging is to write the value of a variable to the console. Use this action as an alternative to littering your code with print statements for debugging purposes.

Most text that you enter in the text field will appear that way in the console. Wrap variable names with the @ character. Suppose you have a game and want to display the player’s x position. The following log message:

Player X: @player.position.x@

Prints the following in the console if the x position is 12:

Player X: 12

Shell Command

The Shell Command action runs a shell script. You can use this action to run command-line programs as well as shell scripts.

Enter the command in the top text field, or click the Choose button to locate a shell script on your Mac. Enter any arguments in the bottom text field. Selecting the Wait until done checkbox tells Xcode to wait until the shell script finishes to continue.

Sound

The Sound action plays a sound. Playing a sound lets you know you hit the breakpoint. Normally you mix the Sound action with other breakpoint actions.

Choose a sound from the menu.

Automatically Continue

At the bottom of the breakpoint editor popover is a checkbox to automatically continue after running the breakpoint actions. If you’re using breakpoint actions, you should select the checkbox so you don’t have to click the Resume button to resume running your app.

It’s OK to Use Storyboards

Tue, 14 Apr 2020 18:57:54 +0000

A common question new iOS developers ask is how to build their app’s user interface: code or storyboards. People adamant about building their interfaces in code inevitably join in to say that building interfaces in code is the right way, the way big companies make iOS apps. But it’s OK to use storyboards for your user interface, especially if you are new to iOS development.

What’s Wrong with Storyboards?

Storyboards have two main issues. The first issue involves version control. If multiple people make changes to a storyboard, commit the changes, and merge the changes, conflicts occur that are difficult to resolve.

Merge conflicts are a serious issue, but if you’re a new iOS developer, you probably are working alone. You’re the only one editing the storyboard so you don’t have to worry about merge conflicts.

The second issue with storyboards is that editing them can be slow if you jam 10 or more screens into a single storyboard. If you run into this issue, the solution is to use multiple storyboards. Select the view controller scenes you want to put in a new storyboard and choose Edit > Refactor to Storyboard.

Why Use Storyboards?

The point of this article isn’t to show that storyboards are better than code for building user interfaces, but the following list shows some reasons to use storyboards:

UIKit is meant to work with storyboards. Xcode projects that use UIKit include a storyboard for a reason.
Using storyboards is easier for new iOS developers than building a user interface entirely in code. Dragging a button or other control to a screen is easier than figuring out the code you have to write to create and place that control.
Storyboards let you see how your interface looks before running the app. With code you have to build and run the project to see how the interface looks.

Conclusion

Build your user interface however you want. But it’s OK to use storyboards. You’re not doing it wrong if you use a storyboard for your app’s user interface, no matter what someone on Reddit or Slack tells you.

Creating Custom Elements and Attributes in the Plot HTML Framework

Wed, 08 Apr 2020 19:22:04 +0000

Plot is a framework for creating HTML and XML documents in Swift. The Plot framework supports the most common HTML elements and attributes. But if you want to do something Plot doesn’t natively support, such as create an EPUB book, you must create custom elements and attributes. In this article I share what I’ve learned about creating custom elements and attributes.

Custom Elements

You can think of an element as a tag. Examples of HTML elements include p for paragraphs, h1 for heading 1, and li for a list item. Create a custom element if there is an element you need that Plot does not have. You are more likely to create custom elements for XML than HTML.

Custom Attributes

An attribute is a value that appears inside an HTML or XML element. HTML links have a href attribute with the link destination.

<a href="https://github.com">

Like elements, you are more likely to create custom attributes for XML than HTML. Custom elements are likely to require custom attributes.

Creating a Custom Element

Call the .element function to create a custom element. There are multiple ways to call the .element function. A simple way to call it is to supply a text value for the element. The following call:

.element(named: "country", text: "Mexico")

Creates the following XML tag:

<country>Mexico</country>

You normally write a static function to create a custom element that makes a call to .element. The following function creates a custom element for a country:

static func country(_ location: String) -> Self {
  .element(named: "country", text: location)
}

Supplying Attributes

Another way to call .element is to supply a list of attributes. The following call:

.element(named: "meta", attributes: 
	[.attribute(named: "name", value: "cover"),
		.attribute(named: "content", value: "cover.png")
])

Creates the following tag:

<meta name="cover" content="cover.png" />

Supplying a List of Nodes

The final way to call .element is to supply a list of nodes. Supplying a list of nodes helps when creating nested tags. Normally when you have nested tags, the child nodes are nodes of a custom context.

extension XML {
  enum MyMetadataContext {}
}
    
static func metadata(_ nodes: Node<XML.MyMetadataContext>...) -> Self {
	.element(named: "metadata", nodes: nodes)
}

I explain custom contexts later in this article.

Another situation to supply a list of nodes is to create a custom element that includes both a text value and attributes. The following function creates a custom modified date element:

static func modifiedDate(_ dateString: String) -> Self {
  .element(named: "meta", nodes: 
    [.attribute(named: "property",  
       value:"dcterms:modified"), 
    .text(dateString)
    ])
}

Calling modifiedDate creates an element that looks like the following:

<meta property="dcterms:modified">2020-04-03</meta>

The exact value depends on the date string.

Creating a Custom Attribute

Call the .attribute function to create a custom attribute. Supply the name of the attribute and its value. The following call:

.attribute(named: "xml:lang", value: "en")

Creates the following attribute:

xml:lang="en"

Like with custom elements, you normally write a static function to create a custom attribute. The following function creates a custom attribute for the language of an XML document:

static func xmlLang(_ language: String) -> Self {
  .attribute(named: "xml:lang", value: language)
}

Example: Create a Spine for an EPUB Book

Now it’s time for a real example, creating the spine for an EPUB book. The spine contains a list of files in the order they appear in the book. The following code shows the XML of a sample spine:

<spine toc="ncx">
  <itemref idref="Chapter1"/>
  <itemref idref="Chapter2"/>
  <itemref idref="Chapter3"/>
  <itemref idref="Chapter4"/>
  <itemref idref="Chapter5"/>
</spine>

Building the spine in Plot requires two custom elements: one for the spine and one for the item references. The spine element requires a custom attribute for the table of contents (toc). The item reference element requires a custom attribute for the ID reference.

Create New Contexts

A context is a section of an HTML or XML document where elements and attributes reside. Plot has a BodyContext for HTML documents that corresponds to the body tag in the document. Most HTML elements reside in the body context.

Custom attributes usually require you to create a custom context. Sometimes custom elements also require a custom context.

To create the spine, create new XML contexts for the spine and spine item.

extension XML {
  enum SpineContext {}
  enum SpineItemContext {}
}

The SpineContext context contains anything inside a spine tag, which is going to be the spine items and the spine element’s custom attribute. The SpineItemContext context contains anything inside an itemref tag, which is each item’s ID reference.

Create the Spine Custom Element

The next step is to create the spine custom element, which you can see in the following code:

extension Node where Context == XML.DocumentContext {
  static func spine(_ nodes: Node<XML.SpineContext>...) -> Self {
    .element(named: "spine", nodes: nodes)
  }
}

The code creates an element named spine with a list of child nodes. The child nodes include the spine’s custom attributes and the item reference elements. The child nodes must be in the spine context.

Create the Spine Custom Attribute

Now let’s create the spine’s custom attribute, which you can see in the following code:

extension Node where Context == XML.SpineContext {
  static func spineTOC() -> Self {
    .attribute(named: "toc", value: "ncx")
  }
}

Notice the class extension for the spineTOC function applies to the spine context so the attribute appears inside the spine tag.

Create the Item Reference Element

The next task is to write the code to create the item reference element.

extension Node where Context == XML.SpineContext {
  static func item(_ nodes: Node<XML.SpineItemContext>...) -> Self {
    .element(named: "itemref", nodes: nodes)
  }
}

The item function must be inside the spine context for the item reference elements to appear inside the spine tag.

The nodes are going to be the ID references.

Create the ID Reference Attribute

There’s one more custom attribute to write, the item’s ID reference.

extension Node where Context == XML.SpineItemContext {
  static func itemID(_ name: String) -> Self {
    .attribute(named: "idref", value: name)
  }
}

The itemID function must be inside the spine item context for the attributes to appear inside the item reference tag.

Creating the Spine

The last step is to write a function to build the spine using the custom elements and attributes. Assume there is a Book struct that contains a list of chapters. Each chapter has a title.

func buildSpine() -> Node<XML.DocumentContext> {
  let spine = Node.spine(
    .spineTOC(),
    .forEach(chapters) {
    .item(Node.itemID($0.title))
  })
    
  return spine
}

The first line of code in the buildSpine function creates the spine custom element. The second line creates the spine element’s custom attribute.

For each chapter in the book, the code creates a spine item custom element and an item ID (idref) custom attribute for the spine item. The item ID’s value is the chapter’s title.

Once you do the work of writing functions for the custom elements and attributes, it doesn’t take much code to do something like build the spine for an EPUB book.

Submitting Bug Reports to Apple

Fri, 03 Apr 2020 19:06:51 +0000

If you find a bug or want to request a new feature in Xcode or one of Apple’s frameworks, you can submit a bug report using Xcode’s Help menu. Choose Help > Report an Issue to access Apple’s Feedback Assistant site.

5 Tips to Get Help Faster Online

Wed, 01 Apr 2020 18:58:39 +0000

When you run into problems developing an iOS or Mac app, you can get help by asking a question online at sites like Stack Overflow, Reddit, Slack, and Apple’s developer forums. If you need to ask a question, use the tips in this article to get answers faster.

Tip 1: Search First

The fastest way to get an answer to a question online is to not have to ask it. Before you ask a question, search the site or do a search in a search engine to see if someone else had the same question. The chances are pretty good that someone had the same question and received an answer.

Tip 2: Use a Descriptive Title/Subject

I’m amazed by the number of programming questions I see online with the title “Help”. Just about everyone asking a question on a forum is looking for help. Post a brief summary of the issue in the title that is clear enough that people have a general idea of the problem you’re having.

Examples of poor question titles:

Xcode doesn’t work
Source code
Keyword
Crash

Those titles are too vague. People are less likely to read a poorly titled question. If they don’t read your question, they won’t answer it.

Examples of good question titles:

How do I download Xcode outside the Mac App Store?
Using NSArrayController in multiple storyboard scenes
UITextView not scrolling in portrait orientation on iOS 11
How can I sort a Swift set in alphabetical order?

With titles like these someone can tell if the question is worth reading. Poorly titled questions aren’t worth reading.

Tip 3: Don’t Post Screenshots of Error Messages and Code

On Reddit and Slack people like to ask a question and show a screenshot of Xcode on their computer. Text in screenshots is difficult to read. In the best case scenario, people will ask for more information, delaying you receiving an answer. In the worst case scenario people will ignore your question.

If you are going to include a code listing or error message in your question, paste the code/error message into the question as text.

Tip 4: Post Relevant Information

The biggest mistake I see people make when asking programming questions online is not supplying enough information to answer the question. People have to ask for additional information, which delays you getting an answer. To get an answer faster, supply all the information that people need to answer your question.

What information is relevant depends on the question, but examples of relevant information include the following:

What you are trying to accomplish.
What you tried.
What the specific problem is.
The steps to take to reproduce the issue.
If you are following a tutorial, provide a link to the tutorial.
The code where the problem occurs, if the question is about code.

Remember to be specific with the information you provide. Saying something like “it doesn’t work” can mean many things. It can mean the project doesn’t compile. It can mean the app crashes. It can mean the app does something you don’t expect.

Tip 5: Don’t Show All the Code in Your Project

Sometimes people go too far the other way with code listings. They share all the code from their project.

People who answer questions online don’t want to read hundreds of lines of code. Post only as much code as you need to show the problem.

Create a Mac Markdown Editor with Live Preview

Wed, 19 Feb 2020 22:41:49 +0000

I’m working on a Mac app that previews HTML in a web view, and it gave me a good idea for a tutorial. Create a simple Markdown editor with live preview.

I have the project on GitHub for you to download.

Prerequisites

To take full advantage of this tutorial, you must be running Xcode 11 or later. I use the Swift Package Manager support added in Xcode 11 to add the Ink parser to the project. It might be possible to build a framework for Ink by cloning the GitHub project, but I have not tried it. You could also try searching GitHub for another Markdown parser that supports earlier Xcode versions.

I recommend reading the Create a Document-Based Mac App in Swift article. It provides an introduction to creating document-based Mac apps and covers some topics that I gloss over in this tutorial. It also has links to other introductory Mac development articles. This tutorial is long enough. If I were to add explanations on basic topics like making connections in storyboards, the tutorial would be as long as a short book.

Create the Project

Create a Cocoa App project in Xcode. Choose Storyboards from the User Interface menu because this project does not use SwiftUI. Select the Create Document-Based Application checkbox. Enter md for the document extension, which is the file extension for Markdown documents.

Deal with the App Sandbox

When I created this project I could not get the live preview to display any HTML. The issue involved the App Sandbox. New Xcode projects use the App Sandbox, which disables all network connections by default.

There are two ways to work around the App Sandbox. You can turn off the App Sandbox or turn on network connections by selecting the two Network checkboxes.

Import the Ink Parser

This article uses John Sundell’s Ink Markdown parser to convert Markdown to HTML. Add the Ink parser to the list of Swift packages.

Select the project from the project navigator to open the project editor. Select the project file in the project editor. Click the Swift Packages button at the top of the project editor to see a list of installed Swift packages. Click the Add button to add a Swift package.

Enter Ink in the search field and press the Return key to see a list of Swift package repositories with Ink in the name.

Select the Ink item whose owner is JohnSundell. Click the Next button.

Now you must determine which version of the Ink parser to use. Click the Branch radio button and enter master. This tells Xcode to use the most recent stable version of the Ink parser.

Click the Next button to finish adding the Ink parser Swift package to the project.

Build the User Interface

The user interface for the Markdown editor consists of a vertical split view with two items. The left view is a plain text text view where you enter Markdown text. The right view is a web view that shows the HTML version of the Markdown text.

Open the storyboard. You will see a window with a view controller. Delete that view controller. Add a vertical split view controller to the storyboard. Make the split view controller the window’s content controller by making a connection from the Window Controller item in the window controller scene to the split view controller and selecting the window content relationship segue.

Adding the split view controller creates view controller scenes for the two items in the split view. Remove the views in the two view controllers. Add a Plain Document Content Text View item to the first view controller. Add a WebKit View item to the second view controller.

Select the text view’s scroll view, open the size inspector, and click the two arrows in the inner autoresizing square. Select the web view and do the same thing. The text view and web view will now resize properly when the window resizes.

Set the Text View’s Delegate

Set the text view’s delegate to the text view controller so the text view controller will get notified when the text view’s contents change.

Make a connection from the text view to the text view controller in the storyboard to set the delegate.

Create View Controller Subclasses

The next step is to create Swift files for the three view controllers you created in the storyboard: split view controller, text view controller, and web view controller. I use the name preview view controller for the web view controller.

Choose File > New > File to add a new file to the project. Select Cocoa Class from the list of Mac file templates. Enter the name of the class. For the subclass enter NSSplitViewController for the split view controller and NSViewController for the other two view controllers. Do not create xib files for the view controllers. You created the view controllers in the storyboard.

The text view controller must conform to the NSTextDelegate protocol to receive any text view notifications, such as the text view contents changing.

class TextViewController: NSViewController, NSTextDelegate {
    
}

Open the storyboard and the identity inspector. Set the custom class for each view controller to the subclass you created.

Create Outlets

The text view controller needs an outlet to access the text view. The preview view controller needs an outlet to access the web view.

Open the storyboard and the view controller source file in separate editors. Make a connection from the view in the storyboard to the class in the source code file to create and connect an outlet.

Accessing the Document

The view controllers need access to the document to access and change its contents. The split view controller has access to the document so you can get the document from the split view controller. Add the following function to the split view controller:

func getDocument() -> Document? {
  if let window = view.window,
    let windowController = window.windowController {
    
    return windowController.document as? Document
  }
  return nil
}

Reaching the document requires some deep navigation. You have to get the view, get the view’s window, and get the window’s window controller to access the document.

Accessing the Other View Controllers

An annoying aspect of Mac split view controllers is they have no easy way for the child view controllers to communicate with each other, even though they’re grouped together in the split view. Each view controller scene is self-contained. For the Markdown editor the text view controller knows nothing about the web view. The web view controller knows nothing about the text view. The view controllers have to go through the split view controller to access the other view controllers.

The split view controller has a children property that contains a list of child view controllers. The text view controller is the first child.

func getTextViewController() -> TextViewController? {
  if let viewController = children.first as? TextViewController {
    return viewController
  }
  return nil
}

The preview view controller is the second child.

func getPreviewViewController() -> PreviewViewController? {
  if let viewController = children[1] as? PreviewViewController {
    return viewController
  }
  return nil
}

Add those two functions to the split view controller.

Coding the Live Preview

When the text changes, you must convert the Markdown to HTML and display it in the web view. Start by importing the Ink framework in the preview view controller.

import Ink

To convert the Markdown to HTML in Ink, create a MarkdownParser object and call its html function.

func parse(text: String) -> String {
  let parser = MarkdownParser()
  return parser.html(from: text)
}

To display the HTML in the web view, call the web view’s loadHTMLString function. Supply the HTML string as an argument. You can also supply a base URL for relative paths, which can help if you’re going to display images.

func updatePreview(text: String) {
  let html = parse(text: text)
  previewView.loadHTMLString(html, baseURL: nil)
}

Add the parse and updatePreview functions to the preview view controller.

Telling the Web View to Update

Call the preview view controller’s updatePreview function to update the web view. Add the following function to the text view controller:

func updateLivePreview(text: String) {
  if let splitViewController = parent as? SplitViewController,
    let previewController = 
      splitViewController.getPreviewViewController() {
    
    previewController.updatePreview(text: text)
  }
}

Notice how the text view controller has to go through the split view controller to access the preview view controller to update the preview.

Call updateLivePreview when the text view’s contents change. Add the following function to the text view controller:

func textDidChange(_ notification: Notification) {
  updateLivePreview(text: textView.string)
}

Run the project now. You should be able to type in the text view and see the HTML in the web view.

Updating the Document Contents

When the text view’s contents change, the document’s contents should also change. Start by adding the following property to the Document class:

var markdown = ""

The markdown property stores the document’s contents.

Add the following functions to the text view controller:

func saveTextViewContents() {
  if let document = getDocument() {
    document.markdown = textView.string
  }
}
    
func getDocument() -> Document? {
  if let splitViewController = parent as? SplitViewController {
    return splitViewController.getDocument()
  }
  return nil
}

The saveTextViewContents function sets the document’s contents to the text view’s contents. The getDocument function is a helper function to give the text view controller access to the document.

Add a call to saveTextViewContents to the textDidChange function. Now the document’s contents update when the text view’s contents change.

Marking the Document as Changed

When someone types in the text view, you must mark the document as being edited so it will autosave. Add the following code to the textDidChange function:

if let document = getDocument() {
  document.updateChangeCount(NSDocument.ChangeType.changeDone)
}

Saving the Document

Open the Document.swift file. Change the data function to the following:

override func data(ofType typeName: String) throws -> Data {
  return markdown.data(using: .utf8) ?? Data()
}

The code takes the Markdown string and converts it to a Data object that can be saved to a file. If the conversion fails, save an empty file.

Loading the Document

Open the Document.swift file. Change the read function to the following:

override func read(from data: Data, ofType typeName: String) throws {
  if let fileContents = String(data: data,encoding: .utf8) {
    markdown = fileContents
  }
}

The code takes the Data object from the saved document and converts it to a Swift string. If there is saved text, set the document’s contents to the saved text.

Fill the Text View When Opening a Document

The last step is to fill the text view with the document’s contents when you open a document. Override the viewDidAppear function in the text view controller and set the text view’s contents to the document’s contents.

override func viewDidAppear() {
  if let document = getDocument() {
    textView.string = document.markdown
    updateLivePreview(text: textView.string)
  }
}

While you’re setting the text view contents you should also update the web view so it shows the HTML preview. That’s why there’s a call to updateLivePreview. If you didn’t have the call, the preview would be blank until you typed in the text view.

Now when you run the project you should have a basic Markdown editor. You can create documents, preview the HTML contents, save documents, and open documents.

Cherry Picking a Git Commit in Xcode

Fri, 07 Feb 2020 17:46:28 +0000

Xcode 11 adds support for cherry picking commits. Cherry picking involves taking a commit from one git branch and applying it to another branch. Cherry picking lets you apply a commit to a branch without having to merge all your recent commits into that branch.

Take the following steps to cherry pick a commit in Xcode.

Open the source control navigator by pressing Cmd–2.
Checkout the destination branch, the branch that will receive the cherry picked commit.
Select the branch with the commit to cherry pick. Xcode’s editor will show all the commits for that branch.
Select the commit.
Right-click and choose Cherry-Pick.
An alert will open asking if you want to cherry pick. Click the Cherry-Pick button.

Want to Learn More About Git?

Check out my version control book. It shows you how to do the most common git tasks without leaving Xcode. Some of the material covered in the book includes seeing the changes you made to your code, branching, and going back to earlier versions of your project.

Creating Document-Based Apps with SwiftUI

Mon, 06 Jan 2020 20:00:08 +0000

Xcode 12 Note from the Author

Xcode 12 made a bunch of changes to SwiftUI for document-based apps. If you choose a multi-platform document app project, you will get the text editor project I create in this article without having to write any code. I’m keeping this article up for people who are still using Xcode 11.

The article Make a Markdown Editor in SwiftUI shows how to create a document-based SwiftUI app with Xcode 12.

Start of Original Article

I have not seen any articles or tutorials on creating a document-based app with SwiftUI so I’m writing one. In this tutorial you will build an iOS plain text editor.

If you haven’t already, I recommend reading two articles before going through the tutorial. Creating Document-Based iOS Apps Part 1 provides an overview of creating document-based iOS apps. Using Text Views in a SwiftUI App provides an explanation of using a UIKit text view in a SwiftUI app. SwiftUI does not currently have a built-in text view.

Create the Project

Start by creating a project. Create an iOS document-based app project. Choose SwiftUI from the User Interface menu if it’s not already selected.

The most interesting files Xcode creates for a document-based SwiftUI app are the following:

DocumentBrowserViewController.swift contains code for the document browser, where people create and open documents.
DocumentView.Swift contains code for the document’s main view.
Document.Swift contains code for the document.

Creating a New Document

If you run the project, you’ll notice that tapping the Create Document button does nothing. You must write some code to create the document when someone taps the button. The easiest way to create a new document is to add an empty file to the project. The empty file should have the same file extension as the document’s. This file will be copied to the app bundle when building the project. You’ll have to write some code to load the file from the app bundle.

One last thing to do to create documents properly is to configure the document type in Xcode so that the app is an editor of plain text files.

Add an Empty Document File

Choose File > New > File to add a new file to the project. Select Empty from the list of iOS file templates. The empty file is in the Other section. You have to scroll down a bit to reach the Other section.

Name the file. I named the file New Document.txt. You can choose a different name, but remember the name.

Load the Empty Document

Open the DocumentBrowserViewController.swift file and go to the didRequestDocumentCreationWithHandler function. Replace the following line of code:

let newDocumentURL: URL? = nil

With the following code:

let newDocumentURL: URL? = Bundle.main.url(
  forResource: "New Document", withExtension: "txt")

This code loads the empty document file from the app bundle and uses that as the base for a new document.

There is one more piece of code to change. In the same function, find the following code:

if newDocumentURL != nil {
  importHandler(newDocumentURL, .move)
} else {
  importHandler(nil, .none)
}

There is a problem with the code inside the if block.

importHandler(newDocumentURL, .move)

This line of code moves the file from the application bundle. Your app will crash the second time you create a document because the empty document file was moved out of the application bundle. The fix is to copy the file from the application bundle when creating a new document.

importHandler(newDocumentURL, .copy)

Edit the Document Type

Xcode initially sets the document type for an iOS document-based app to be a viewer of image files. You must configure the document type in Xcode so that the app is an editor of plain text files. You’re making a text editor, not a text viewer.

Select the project from the project navigator to open the project editor. Select the app target from the left side of the project editor. Click the Info button at the top of the project editor to access the document types. Click the disclosure triangle next to Document Types.

Enter PlainText in the Name text field.
Enter public.plain-text in the Types text field. public.plain-text is the UTI (Uniform Type Identifier) for plain text files.
In the Additional document type properties section, set the CFBundleTypeRole value to Editor so people can edit documents.
Set the LSHandlerRank value to Alternate to ensure this text editor isn’t the default text editor for all plain text files.

Create the Data Model

The data model for this project is simple. The document is the data model. All you have to do is add a property to store the text. Open the Document.swift file and add the following code inside the Document class:

var text = ""

The code declares a property to store the text and has the initial value of an empty string.

Building the Text View

Now it’s time to add the text view so people can edit text. Currently SwiftUI does not include a text view so you have to write code to create a UIKit text view. But it’s not too much code. Add a new Swift file to your project for the text view. Import the SwiftUI and UIKit frameworks. Add the following struct:

struct TextView: UIViewRepresentable {
    
}

The text view must conform to the UIViewRepresentable protocol, which is the protocol that allows the use of UIKit views in SwiftUI apps. To conform to the protocol, you must write the following functions:

makeUIView
updateUIView
makeCoordinator

The makeUIView function creates and configures the view. The function takes an argument of type Context and returns the type of view you want to make, which is UITextView for a text view. The Context type is a type alias for the context where updates to the UIKit view take place.

func makeUIView(context: Context) -> UITextView {
  let view = UITextView()
  view.isScrollEnabled = true
  view.isEditable = true
  view.isUserInteractionEnabled = true
  view.contentInset = UIEdgeInsets(top: 5, 
    left: 10, bottom: 5, right: 5)
  view.delegate = context.coordinator
  return view
}

The code listing creates a text view, configures the view so people can edit large amounts of text, and adds some padding so the text isn’t on the left edge of the screen. The code also sets the view’s delegate to the context’s coordinator, which you will create shortly.

The updateUIView function handles updates to the view.

func updateUIView(_ uiView: UITextView, context: Context) {
    
}

I will fill in this function later.

The makeCoordinator function creates a coordinator so the UIKit view can communicate with data in SwiftUI.

func makeCoordinator() -> TextView.Coordinator {
  Coordinator(self)
}

Create the Coordinator

Add a Coordinator class inside the struct for the text view.

class Coordinator: NSObject, UITextViewDelegate {
  var control: TextView
    
  init(_ control: TextView) {
    self.control = control
  }
}

The class inherits from NSObject, which is the base class for all UIKit classes. A text view’s coordinator should conform to the UITextViewDelegate protocol so it can respond to text view notifications, such as the text changing.

The coordinator needs a property to hold the UIKit view and an initializer. I will be adding more to the coordinator later in the article.

Add the Text View to the Document View

The last step to adding the text view is to have the document view display it. Open the DocumentView.Swift file. Inside the body property you should see a VStack that contains a HStack and a button. The HStack shows the name of the file. The button lets you go back to the browser when you’re done writing.

The text view should appear between the HStack and button. Add the following line of code between the HStack and button:

TextView()

If you build and run the project, you should be able to create a new document and type in it.

Connect the Text View to the Document

For the app to do more than let people type text in a text view, you must connect the text view to the document so the text you type updates the document as well. In the document view, you should see the following variable:

var document: UIDocument

This variable contains a reference to the document. Make the following changes to the variable:

@State var document: Document

The @State property wrapper will allow the text view to bind to the document in order to display the document’s text. Changing the type of the variable to Document is also necessary for the text view to work with the document properly.

Now add the following property to the text view:

@Binding var document: Document

The @Binding property wrapper binds the document property in the text view to the document property in the document view. The text view and document view are both pointing to the same document. The text view now has access to the document.

Now that you created the binding you must go back to the document view and change the call to create the text view by supplying the document as an argument.

TextView(document: $document)

The $ at the start of $document indicates that you are passing a binding to the text view. You must pass a binding so the document view and text view both point to the same document.

Fill the updateUIView Function

Now that the text view has access to the document, you can write the text view’s updateUIView function. Set the text view’s contents to the document’s contents.

func updateUIView(_ uiView: UITextView, context: Context) {
  uiView.text = document.text
}

Handling Text Changes

One last thing to do is to update the document when the text view contents change. Add the following function to the Coordinator class:

func textViewDidChange(_ textView: UITextView) {
  control.document.text = textView.text
  control.document.updateChangeCount(.done)
}

The first line of code sets the document’s contents to the text view’s contents. The second line marks the document as changed so it will be saved.

Save the Document

At this point you’re finished with the SwiftUI material, but there’s still some work to do to finish the app. The text editor is missing one really big feature: saving text. Open the Document.Swift file. Xcode created a blank contents function for saving the document.

What you have to do is convert the text in the document to a Data object and archive that object. Apple provides the NSKeyedArchiver class and an archivedData function so you can do both steps in one line of code.

override func contents(forType typeName: String) throws -> Any {
  return try NSKeyedArchiver.archivedData(withRootObject: text,
    requiringSecureCoding: true)
}

The root object is the document’s text. Requiring secure coding ensures your app will be able to unarchive the data when loading the document.

Load the Document

After saving the document, the next task is to load the document when someone chooses a document from the browser. Xcode supplies a blank load function, where you write the code to load the document from disk.

The first argument to the load function is the contents of the file. You must first cast the contents to the Data type. Call the NSKeyedUnarchiver class’s unarchiveTopLevelObjectWithData function to unarchive the text from the file. The last step is to set the document’s text to the contents of the file.

override func load(fromContents contents: Any, 
  ofType typeName: String?) throws {
    
  guard let data = contents as? Data else { return }
  guard let fileContents = try 
    NSKeyedUnarchiver.unarchiveTopLevelObjectWithData(data) 
    as? String else { return }
    
  text = fileContents
}

Conclusion

Now you have a simple, working text editor. You can create documents, edit text, save documents, and open them. You can use this project as a foundation for building your own text editing app, such as a Markdown editor. I have the project on GitHub for you to download if you run into issues.

Using Text Views in a SwiftUI App

Fri, 20 Dec 2019 18:43:47 +0000

SwiftUI currently lacks native support for text views. (Note: Xcode 12 adds text view support to SwiftUI). If you want people to enter large amounts of text in a SwiftUI app, you have to wrap a UIKit or AppKit text view. This article shows you how to use a text view in an iOS app that uses SwiftUI. Most of this material should also apply to Mac apps. Replace anything that has a UI prefix with NS.

UIViewRepresentable

To use UITextView in a SwiftUI app, you must create a struct for the text view and have it conform to the UIViewRepresentable protocol. The UIViewRepresentable protocol is how you wrap UIKit views in SwiftUI apps.

struct TextView: UIViewRepresentable {
    
}

Don’t forget to import the UIKit framework.

Create the View

To conform to the UIViewRepresentable protocol, you must add two functions to the struct you created. The first function is makeUIView, which creates and configures the view. It takes an argument of type Context and returns the type of view you want to create, which is UITextView for a text view. The Context type is a type alias for the context where updates to the UIKit view take place. The following code shows an example of creating and configuring a text view:

func makeUIView(context: Context) -> UITextView {
  let view = UITextView()
  view.isScrollEnabled = true
  view.isEditable = true
  view.isUserInteractionEnabled = true
  view.contentInset = UIEdgeInsets(top: 5, 
    left: 10, bottom: 5, right: 5)
  return view
}

At a minimum you must create the view and return it. In the code sample I decided to make the text view scrollable and editable. I also added some padding so the text isn’t on the left edge of the screen.

Update the View

The second function you must write is updateUIView, which handles updates to the view. The updateUIView function takes two arguments: a view and a context.

func updateUIView(_ uiView: UITextView, context: Context) {
    
}

I will be filling the function later in the article.

Try Creating Your Own Text View

At this point you have enough to add a text view to a SwiftUI app. Create an iOS app project in Xcode. Add a file for the TextView struct. Fill the struct with the code I’ve shown so far in the article. Open the ContentView.swift file and replace the text label in the body property with a text view.

var body: some View {
  TextView()
}

Build and run the app. You should be able to type in the text view.

Connecting to Your Data Model

At this point you can type in the text view, but you’ll lose what you type when you quit the app. For a text view to be useful, it needs a connection to your app’s data model.

In the struct for the text view, add a property for the data model. For a simple app, you can create a @State property wrapper that holds the text.

@State var text: String

In a real app you’re more likely to have a reference to the data model in another SwiftUI view. Use the @Binding property wrapper to access data from another SwiftUI view.

@Binding var model: MyModel

Replace MyModel with whatever the name of your data model is.

Now that you have a connection to your data model, you can fill in the updateUIView function. Make the text view show the text from the data model.

func updateUIView(_ uiView: UITextView, context: Context) {
  uiView.text = model.text
}

Coordinators

In order for a UIKit view to communicate with data in SwiftUI, the view needs a coordinator. To conform to the UIViewRepresentable protocol, you must add a new function to the TextView struct, makeCoordinator. The makeCoordinator function creates the coordinator. The return type takes the form StructName.Coordinator.

func makeCoordinator() -> TextView.Coordinator {
  Coordinator(self)
}

The next step is to set the text view’s delegate to the context’s coordinator. Add the following line of code to makeUIView before the return statement:

view.delegate = context.coordinator

The last step is to add a class for the coordinator. Create a class for the coordinator inside the struct for the text view. Make sure the name of the class matches the name you supply to the makeCoordinator function.

class Coordinator: NSObject, UITextViewDelegate {
  var control: TextView
    
  init(_ control: TextView) {
    self.control = control
  }
    
  func textViewDidChange(_ textView: UITextView) {
    control.model.text = textView.text
  }
}

The Coordinator class inherits from NSObject, which is the base class for all UIKit and AppKit classes. A coordinator for a text view should conform to UITextViewDelegate so it can respond to text view notifications, such as the contents of the text view changing.

The coordinator needs a property for the control it’s going to coordinate. The control property contains a reference to the text view.

The Coordinator class needs an initializer to set its view, which is the control property in the code sample.

The last block of code tells the coordinator to respond when the contents of the text view change. The function sets the model’s contents to the text view’s contents. If you want the text view to handle other notifications, add the functions to the coordinator.

Responding to Text Changes in Mac Apps

Responding to text changes has more differences in Mac apps. Let’s look at the code to respond to text changes on Mac.

func textDidChange(_ notification: Notification) {
  guard let textView = notification.object 
    as? NSTextView else {
    
    return
  }
  control.model.text = textView.string
}

The name of the function is textDidChange. Instead of taking the text view as an argument, it takes a notification. The object property of the notification is the object that sent the notification. When entering text, the text view is the object that sends the notification that the text changed. The guard statement ensures the object that sent the notification is a text view. The property to get the text in NSTextView is string, not text.

Summary

To use UIKit views in a SwiftUI, you must perform the following tasks:

Create a struct for the view that conforms to the UIViewRepresentable protocol.
Write the makeUIView function to create and configure the view.
Write the updateUIView function so SwiftUI can update the view.
Write the makeCoordinator function to create a coordinator for your view to communicate with SwiftUI data.
Create a class for the coordinator.

I have a simple plain text editor project on GitHub if you want to see an example of a SwiftUI project that uses a text view.

Learn SwiftUI or UIKit?

Tue, 03 Dec 2019 19:12:52 +0000

With the release of SwiftUI in iOS 13, a common question from people new to iOS development is whether they should learn SwiftUI or UIKit.

Why Learn SwiftUI

The most compelling reason to learn SwiftUI is it’s the future. 2–3 years from now, most iOS developers will use SwiftUI to build their user interfaces. You’re eventually going to need to learn SwiftUI so you might as well learn it now. It makes sense to learn SwiftUI instead of learning UIKit and learning SwiftUI a year or two later.

SwiftUI Limitations

SwiftUI is new technology. At the time I’m writing this, SwiftUI has been out for six months, and three of those months it was in beta. Because SwiftUI is new technology, it has bugs and missing features. Apple is going to be making changes to SwiftUI over the next few years so there’s going to be a lot of work keeping up with the changes. Should you decide to learn SwiftUI instead of UIKit, prepare for a lot of frustration.

Apple’s SwiftUI documentation is limited at best. Many outsiders have been writing books, articles, and tutorials on Swift UI. But at this time, everyone is a beginner at SwiftUI development. There’s much less SwiftUI learning material than UIKit.

SwiftUI has a limited set of user interface elements. For example SwiftUI currently lacks text views and collection views.

SwiftUI apps don’t run on iOS 12 and earlier iOS versions. For people new to iOS development, this isn’t a big limitation, but it is a limitation.

Why Learn UIKit

UIKit is mature and stable. It has all the available iOS user interface elements. There is a lot more UIKit learning material available than SwiftUI.

If you want to use a text view, collection view, or another view that SwiftUI doesn’t have, you need to know some UIKit.

Should You Learn SwiftUI or UIKit?

If you can put up with the SwiftUI limitations I mentioned earlier and deal with limited documentation, learn SwiftUI. Otherwise learn UIKit.

Creating a Simple SwiftUI App

Thu, 21 Nov 2019 18:48:00 +0000

SwiftUI is Apple’s new framework for building user interfaces in Swift. Let’s introduce SwiftUI by creating a simple app. The app displays the number of times you tap a button. I couldn’t think of a simper app idea.

I’m going to focus on making an iOS app in the article, but you can also make a Mac version of this app. Create a macOS App project instead of an iOS project.

Apple added SwiftUI support in Xcode 11 so you must be running Xcode 11 or higher to use SwiftUI.

Create the Project

Create a single-view iOS app (App on Xcode 12) project. Choose SwiftUI from the User Interface menu. Deselect all the checkboxes.

When you create the project, the project navigator should look similar to the following screenshot:

The file you’re going to edit in this article is ContentView.swift. This file contains the main view for the app’s user interface. You will be adding controls to the content view.

The Content View

Open the ContentView.swift file. You’ll see the following struct for the content view:

struct ContentView: View {
  var body: some View {
    Text("Hello, World!")
  }
}

The body property contains the main view. In the code Apple supplies, the view consists of a label (the Text struct is a label) with the text Hello, World!. If you build and run the project, you will see the label.

Previews and the Canvas

If you look at the end of the ContentView.swift file, you’ll see the following struct:

struct ContentView_Previews: PreviewProvider {
  static var previews: some View {
    ContentView()
  }
}

That struct is for displaying a preview of the view in Xcode’s canvas. The canvas is next to the Swift file in Xcode so you can view your source code and the canvas side by side..

I’m not going to use previews and the canvas in this article. I find the canvas gets in the way, is flaky, and doesn’t help much. But the canvas is there for you if you want it. You can toggle the canvas on and off using a button on the right side of the jump bar.

The button is at the top left in the screenshot.

Change the Label

Let’s start by changing the label’s text to Taps:. Change the code for body to the following:

var body: some View {
  Text("Taps: ")
}

Build and run the project, and you should see the label’s text is Taps:.

You can modify how the text in the label looks using functions and properties of the Text struct. Start with a period. The following code displays the label in bold text:

var body: some View {
  Text("Taps: ")
    .bold()
}

The following code changes the font to the system title font:

var body: some View {
  Text("Taps: ")
  	.font(.title)
}

Add a Variable to Store the Tap Count

To display the number of times someone taps the button, you need a variable to store the number of taps. Add the following code before the body variable:

@State var taps = 0

You must use the @State property wrapper so you can change the value of taps when someone taps the button. If you omit the @State part, you will get a compiler error saying that you’re trying to change an immutable value.

Now modify the label so it also shows the number of taps.

Text("Taps: \(taps)")

Build and run the project. The label will show zero taps.

Place the Label in a Stack

The next logical step is to add a button. But you can’t just add the button after the label.

var body: some View {
  Text("Taps: ")
    .font(.title)
  // This won't compile.
  Button("Tap Me") {
    
  }
}

The compiler will complain about that code. You have to place the label and button inside a stack. Start by placing the label inside a stack.

VStack {
  Text("Taps: \(taps)")
    .font(.title)
}

I placed the label in a vertical stack. When you add the button, it will appear below the label. Build and run the project. There aren’t any visible changes, but you’re ready to add the button now.

Add the Button

Let’s add the button to the stack in the content view.

VStack {
  Text("Taps: \(taps)")
    .font(.title)
  Button("Tap Me") {
    self.taps += 1
  }
}

The button’s title, Tap Me, is in parentheses. A closure for the button’s action (what happens when someone taps the button) follows. For this app you increment the taps variable. If you have more complicated behavior, write a function and call that function from the closure.

Build and run the project. The number of taps increases each time you tap the button.

Add Space Between the Label and Button

The app works, but there’s not much space between the label and button. Use the padding function to add some padding between the label and button.

VStack {
  Text("Taps: \(taps)")
    .font(.title)
    .padding()
  Button("Tap Me") {
    self.taps += 1
  }
}

If you supply no arguments, the padding function adds a small amount of space. To add more space, you can supply the edge to apply the padding and the amount. The following line of code provides 100 points of padding at the bottom:

.padding(.bottom, 100)

When you build and run the project, you should see better spacing between the label and button.

Challenge

Add a Reset button that sets the taps variable back to zero. Don’t forget to add padding between the two buttons. I have the project on GitHub if you get stuck.

Going from Tutorials to Your First Real Swift App: First Steps

Wed, 13 Nov 2019 19:45:55 +0000

If you want to learn iOS development, there are many places for you to learn. Hacking with Swift has two free 100 day courses for learning iOS development, one with UIKit and one with SwiftUI.

Getting started with iOS development normally isn’t the big issue. Go through a book or course, and you’ll learn the basics of iOS programming. The trouble starts when you finish a book or course and start to make your first app on your own. You feel stuck and don’t know where to start. You share some of the following feelings:

“I’m a little lost as to where to go next. I’ve completed Swift for Beginners courses on at least four different sites, and if I build one more My First App I may cry.”
“I just am having a hard time finding the tutorials/courses I specifically need to acquire the skills I need for MY project. I’m frankly not even sure I know what skills I actually need because so much of the information I’m seeing is so outdated that I’m not sure it’s relevant to me or if I’ll begin working on it only to find it’s no longer the way things are done or that there’s a better way after I’ve put in a lot of effort.”
“Making the jump from basic concepts to actual coding is hard.”
“Basic lessons have very basic concepts but when I look at the code being used in other projects, they use methods and syntax I’ve never seen.”
“I watched almost every video (Stanford course) and I did everything that professor do. I built them all. But when I’m trying to build apps alone, even the things I built earlier I can’t do anything. I know Swift syntax and other stuff but I just can’t program.”

Why Do You Feel Stuck?

When you were following the book, course, or tutorial, you were doing the equivalent of watching someone make an app. You weren’t making the app. When you try to make your own app, you get stuck because you don’t have the book, course, or tutorial telling you what to do.

To apply to what you learned, you have to make an app on your own. And there’s a lot less material on going from beginner to making your first real app than there is on getting started.

Step 1: Choose a Suitable Project

The first step you have to take when creating an app is choosing the app to make. When choosing an app to make, you must balance the following:

Making something small enough that you can finish.
Making something that interests you.

A big mistake many new iOS developers make is starting with a huge app. They want to make something like Uber or a social media app with realtime chat, something that requires people to sign up for an account to use the app. Making a social media app requires you to have a backend server with a database to store all the data. No iOS development tutorial or book is going to teach you things like that. No wonder people feel stuck.

For your first app make something small and relatively simple. Make an app that uses only Apple technologies. Make something that you have a chance to finish. Once you finish your first app, choose something more ambitious as your next project.

But you also have to make an app that interests you. If you choose an app that bores you, you’ll stop making it.

Step 2: Learn the Necessary Frameworks to Make Your App

You may be able to skip this step if you pick a simple enough app to make. But most projects force you to learn some additional frameworks to make the app.

If you open Xcode’s documentation window (choose Help > Developer Documentation in Xcode), you’ll see that Apple has dozens of frameworks for iOS developers. There’s no way for you to learn them all. Use your choice of project to determine the frameworks you need to learn.

A fitness app may use HealthKit.
An app that uses locations may use MapKit.
A text editing app uses TextKit. You may even need to learn about UIDocument and making document-based apps.
A drawing app may use PencilKit and Quartz2D.
An app that generates PDF files uses PDFKit and possibly Quartz2D.

Step 3: Do a Little Planning

You may be tempted to create a new project in Xcode and start writing code. But development will go more smoothly if you do some planning before you start writing code. You don’t have to plan everything upfront, but doing the following will help you:

Draw the screens for the app on paper
Make a list of the app’s must-have features
Make a list of the types of data your app uses

Once you do some planning, pick the simplest feature you can implement and work on that. When you get a small part working, you’ll feel good and use that energy to move on to the next part of the app. Build the app piece by piece, and you’ll eventually finish your first app.

Are You Doing It Right?

You may be wondering as you develop your app if you’re doing things the right way. I can’t tell you if you are, but it’s software, not something physical. Code can be changed and improved. If you find out you’re doing things wrong, you can change the code so you’re doing thing the right way.

I recommend placing your project under version control. Using version control makes your code easier to change. If you make a bunch of mistakes, you can go back to a working version of your code. When you create a project in Xcode, there’s a checkbox to place your project under version control. You can place an existing Xcode project under version control by choosing Source Control > Create Git Repositories.

Accessing the SwiftUI Views Library in Xcode

Mon, 11 Nov 2019 05:04:37 +0000

Are you running macOS 10.15 and trying to build a SwiftUI user interface visually? Are you having trouble finding the SwiftUI user interface elements, the SwiftUI equivalent of Xcode’s object library for storyboards?

When you click the Add button in the toolbar, Xcode shows the code snippets library instead of the view library. You must click the View Library button in the library window to access the SwiftUI views.

The View Library button is the left button in the group of five buttons in the screenshot. The canvas must be open for the View Library button to appear in the library window. Once you have access to the view library, you can drag views to the canvas and build your interface visually.

Timers in Swift

Tue, 05 Nov 2019 18:20:16 +0000

A timer sends a message to an object after a certain amount of time passes. Start by declaring a variable for the timer.

var saveTimer = Timer()

Starting a Timer

Call the scheduledTimer method to start a timer. The scheduledTimer method takes the following arguments:

A time interval for how often the timer fires, specified in seconds.
Target, which is the object that receives the message from the timer.
Selector, which is the function the target should run after receiving the message.
UserInfo, which is optional additional information you can send.
Repeats, which indicates whether the timer runs once or repeats.

The following code starts a timer to autosave data every 30 seconds:

func startTimer() {
  saveTimer = Timer.scheduledTimer(timeInterval: 30.0,
    target: self, selector: #selector(self.autosave),
    userInfo: nil, repeats: true)
}

The function for the selector needs @objc at the start of the declaration.

@objc func autosave(timer: Timer) {
    
}

Stopping a Timer

Call the invalidate method to stop a timer. The following code stops a timer:

func stopTimer() {
  saveTimer.invalidate()
}

Xcode Missing View Controllers

Sun, 13 Oct 2019 20:24:35 +0000

I have seen a lot of questions recently from people who are creating iOS projects in Xcode and not being able to find the ViewController.swift file and not being able to find view controllers. Usually these questions come from people who are following a tutorial written with an earlier version of Xcode.

The cause of the issue is that Xcode defaults to using SwiftUI for new iOS and Mac projects.

SwiftUI is a new framework from Apple for making user interfaces for Apple devices. SwiftUI does not use view controllers so when you create a SwiftUI project, there aren’t going to be any view controllers in the project.

The solution to the issue is to choose Storyboard from the User Interface menu when you create the project. When you tell Xcode to use storyboards for the user interface, your project will include a view controller and a ViewController.swift file.

Limiting an iOS App to Friends and Family

Thu, 10 Oct 2019 17:46:47 +0000

I sometimes see questions on forums from people who have developed an iOS app and want only friends and family to be able to install the app. Apple does not currently allow you to restrict an app to friends and family, but there are two alternatives that will allow you to effectively reach that goal.

Update

Apple now has unlisted app distribution for releasing apps that won’t appear in App Store listings.

Put the App on the App Store

The simplest solution is to just put your app on the App Store. Many of you think this is a bad idea, that putting your app on the App Store will allow anyone with an iOS device to install the app.

Technically you’re correct. When you put an app on the iOS App Store, anyone can install the app. But no one will know your app exists. The only people who will install your app are the people you tell about the app.

In early 2017 I released a free word game for iOS and Mac, LetterMiner. When I released the game I got a few dozen downloads on the iOS App Store due to the game being new. But then the downloads dried up. In almost three years, I have had fewer than 100 downloads of the iOS version. And I wanted people to play the game.

As long as you don’t publicize the app, your app will effectively be limited to your inner circle of friends and family. You may get a few outside downloads when you first release the app, but after that the downloads will trickle down to zero. There are so many apps on the App Store that people are not going to stumble upon your app by browsing the store.

Keep the App Perpetually in Beta

A more complicated solution is to keep your app perpetually in beta and add your family and friends as beta testers in TestFlight.

The advantage of TestFlight is that no outsiders will be able to install your app. The disadvantage is that you have to submit a new beta build every 90 days. That’s why I recommend putting your app on the App Store. Release your app once and as long as you avoid publicizing the app, you will reach your goal of limiting your iOS app to friends and family.

Introducing the Swift Package Manager

Thu, 12 Sep 2019 17:39:39 +0000

Xcode 11’s improved support for the Swift Package Manager simplifies adding and updating third party frameworks in your projects. In this article you’ll learn how to use the Swift Package Manager to add third party frameworks to your apps.

Accessing the Swift Packages

You can access the Swift packages by selecting your project from the project navigator and clicking the Swift Packages button at the top of the project editor.

Initially the list of Swift packages is empty.

Adding a Swift Package to Your Project

Click the Add button to add a package to your project. Enter the name of the package or the URL of the package repository in the search field. You’ll get more accurate results if you know the repository URL. The following screenshot shows a search for the SwiftCheck testing library:

After choosing the package to add, click the Next button.

Specifying Version Rules

The next step is to specify the rules for what version of the package to use. You can choose a version, a branch from the git repository, or a specific git commit. Most of the time, you’ll either use a version or a branch. Using the master branch would ensure you’re using the latest stable version.

Xcode provides four different version rules.

Up to next major. If the current version of the package is 1.1, it will use the latest 1.x version. It won’t use version 2 of the package.
Up to next minor. If the current version of the package is 1.1, it will use the latest 1.1.x version. It won’t use version 1.2 of the package.
Range, which lets you specify the version ranges of the package to use.
Exact, which uses a specific version of the package.

Xcode defaults to using up to next major. Click the Next button. Xcode will generate the package for you. Click the Finish button.

Viewing the Dependencies

After adding a Swift package to your project, the project navigator will show the Swift package dependencies.

Adding the SwiftCheck package dependency to the project also adds the packages SwiftCheck depends on: FileCheck, llbuild, SwiftPM, and Rainbow. Xcode added the dependencies without me having to do anything. Now I can import the SwiftCheck module into my unit testing classes and use SwiftCheck to generate test cases for me.

Changing a Rule

Suppose you made a mistake specifying a version rule when you added a Swift package to your project. How do you change the rule?

Access the list of Swift packages in your project from the project editor. Double-click on the package to open a sheet to change the rule.

Create a Document-Based Mac App in Swift

Thu, 15 Aug 2019 19:05:09 +0000

The Mac development series continues with an article on making document-based apps. You’re going to learn about document-based apps by making a plain text editor.

If you’re new to Mac development, read the following articles before reading this one:

Those articles go into more detail on things that I gloss over in this article.

Document-Based Apps

A document-based app lets people create documents, where each document is stored in its own file. On the Mac document-based apps take advantage of the File menu. The New menu item creates a new document. The Open menu item opens a document. The Save menu item saves the document. Examples of document-based apps are text editors, spreadsheets, and drawing apps.

Apple provides the NSDocument class for Mac apps to work with documents. When you create a document-based app project in Xcode, Xcode provide a subclass of NSDocument for you to work with.

Create the Project

Start by creating a new project in Xcode. Choose File > New > Project to open the New Project Assistant. Choose Cocoa App from the list of Mac app project templates. Click the Next button.

Enter the project name in the Product Name text field. Select the Use Storyboards and Create Document-Based Application checkboxes. Deselect the Use Core Data and Use SwiftUI (Xcode 11 and later) checkboxes. Enter txt in the Document Extension text field because a plain text editor saves plain text files.

Click the Next button. Choose a location to save the project. Click the Create button to finish creating the project.

Project Files

There are three files you will work on in the project.

Main.storyboard contains the user interface.
ViewController.swift contains the code for the view controller.
Document.swift contains the code for the document. The document is a subclass of NSDocument.

The names ViewController and Document are generic. I kept these names for this project because there’s only one view controller in the project and a text editor deals with documents. If you write your own document-based applications, you would benefit from renaming the classes and files ViewController and Document to something more descriptive.

Dealing with the App Sandbox

When you create a new Cocoa project in Xcode, the App Sandbox is turned on. The initial permissions for dealing with user selected files in the sandbox is read-only. This means that you will be unable to open a Save panel to save the document.

There are two ways to fix the issue. First, you can turn off the App Sandbox. Second, you can set the permission and access for user selected files to Read/Write

You can access the App Sandbox settings by selecting the project from the project navigator, selecting the app target from the project editor, and clicking the Capabilities button at the top of the project editor.

Build the User Interface

The user interface for this project is simple. It consists of a text view that covers the whole window.

Open the storyboard. Delete the label in the window that says Your document contents here.

Open the Object Library and type text view in the search field. Drag the Plain Document Content Text View item from the Object Library to the view controller on the storyboard canvas. If you are running an older version of Xcode that doesn’t have a plain document content text view, drag a text view to the view controller.

Resize the text view so it fills the whole view. Select the text view’s enclosing scroll view and open the size inspector. Click the two arrows in the inner autoresizing square. Clicking the arrows will ensure the text view fills the whole window when the window resizes.

If your version of Xcode doesn’t have a plain document content text view, select the text view and open the attributes inspector. Deselect the Allows Rich Text checkbox.

Create an Outlet for the Text View

The next step is to create an outlet for the text view so you can access it in your code. Open the assistant editor and make sure both the storyboard and view controller source code file are open. Select the text view in the storyboard and control-drag inside the ViewController class to create an outlet for the text view.

Add Properties to the Document Class

Now it’s time to start writing some code by adding some properties to the Document class. There are two properties to add. The first property stores the contents of the document. You’re going to need this property when loading the document.

var contents = ""

The second property is a computed property to access the view controller. When saving the document, you’re going to set the contents property to the text view’s contents. To access the text view, the document needs access to the view controller.

var viewController: ViewController? {
  return windowControllers.first?.contentViewController 
  	as? ViewController
}

The code takes advantage of the fact the document has only one window controller. Access the first item in the windowControllers array and get its content view controller.

Saving the Document

The text view handles common text editing tasks without you having to write any code. For this project the only code you have to write is the code to save and load documents.

To save the document you must write the dataOfType function. Xcode provides a shell of the function for you to fill in, which you can find in the Document.swift file.

Set the document’s contents property to the text view’s string. Convert the document contents to a Data object by using the String struct’s data function.

override func data(ofType typeName: String) throws -> Data {
  // Save the text view contents to disk
  if let textView = viewController?.textView {
    contents = textView.string
    return contents.data(using: .utf8) ?? Data()
  }
  throw NSError(domain: NSOSStatusErrorDomain, 
    code: unimpErr, userInfo: nil)
}

Notice that you don’t have to write any code to open a Save panel. Cocoa’s document architecture handles opening the Save and Open panels for you.

Loading the Document

To load the document you must write the readFromData function. Xcode provides a shell of the function for you to fill in. The shell has a throw statement in the function. Remove that line of code. If you keep that line, an alert will open when you try to open a document saying that the document can’t be opened.

Loading involves converting a Data object to a string and setting the document’s contents property to that string. The String struct has an initializer that takes a Data object as an argument.

override func read(from data: Data, 
  ofType typeName: String) throws {
    
  if let fileContents = String(data: data, 
    encoding: .utf8) {
    
    contents = fileContents
  }
}

Filling the Text View

After loading the document from disk, fill the text view with the document’s contents. Your first instinct may be to fill the text view from the readFromData function. If you do that, you’ll find the view controller is nil, and you won’t be able to access the text view.

What you have to do is override the function viewDidAppear in the view controller. Gain access to the document through the view controller’s window controller and set the text view’s string to the document’s contents.

override func viewDidAppear() {
  // Fill the text view with the document's contents.
  if let document = self.view.window?.
    windowController?.document as? Document {
    
    textView.string = document.contents
  }
}

Conclusion

If you made it this far, congratulations. You wrote a usable text editor. Adding a text view provides most basic text editing functions so you don’t have to reinvent common behavior. Cocoa’s document architecture handles opening Save and Open panels, reducing the amount of code you have to write. There’s fewer than 20 lines of code to write in this project.

The project is on GitHub for you to download if you have trouble building or running the project.

Why Make Mac Apps?

Wed, 07 Aug 2019 17:28:07 +0000

Why would anyone want to make Mac apps? Apple sells way more iPhones than Macs. Why not go where the people are and just develop iOS apps?

But there are valid reasons, especially business reasons, to make Mac apps.

You don’t have to pay an annual fee to Apple.
You can distribute apps from your website.
You can make what you want.
Mac users buy apps.
Less competition.

Not Paying Apple’s Annual Fee

Have you ever wanted to make an iOS app for your personal use? You have to join Apple’s paid developer program, pay Apple $99(US) each year and put the app on the App Store. The only alternatives are to jailbreak your iOS device or reinstall the app every week with a fresh provisioning profile.

You can make a Mac app for your personal use without paying Apple every year. Download Xcode, create a Cocoa application project, develop the project, and run it on your Mac.

Distributing Outside the App Store

Suppose you want to start a business selling software. If you want to sell iOS apps, you have to pay the annual fee, get your app approved by Apple, and have Apple take 30 percent of each sale.

To distribute and sell a Mac app, all you need is a website and a payment processor, such as Paddle or FastSpring. Upload your app to your website and create an account with a payment processor. Payment processors usually take around 10 percent of each sale. With a Mac app you can keep 20 percent more of each sale.

Make What You Want

You don’t need Apple’s permission to distribute Mac apps. If you want the freedom to make the apps you want, make Mac apps instead of iOS apps.

Mac Users Buy Apps

Mobile users want apps to be free or cost a few dollars at most. That’s a hard way to sustain a business.

Mac users are willing to pay more for software, especially if it’s an app they use to get work done. It’s going to be easier to get a few thousand people to pay $50(US) for a Mac app than to get tens of thousands of people to buy an iOS app at any price.

Less Competition

Apple sells way more iPhones and iPads than Macs. But there are also lots more iOS developers and iOS apps than Mac apps. Good luck getting someone to stumble upon your app by browsing the App Store.

Apple sells millions of Macs each year. Presumably some of these people are also buying software for their Macs. A market with millions of potential customers and relatively few competitors is easier to reach.

Want to Learn About Making Mac Apps?

I wrote a book on Mac development.

Building a Product Business: the 30×500 Method

Mon, 22 Jul 2019 19:27:57 +0000

Many Swift developers dream of building a business developing their own products. I found a realistic method of building a product business, the 30×500 method, which was developed by Alex Hillman and Amy Hoy at Stacking the Bricks. The method is geared towards people with full-time jobs who want to start a product business on the side and build a full-time business from there. This article provides an introduction to the 30×500 method.

Choose an Audience to Serve

Instead of choosing a product idea and hoping that people will buy it, start with an audience to serve. Research the audience, find what they need, and come up with a product that serves one of their needs.

A good audience has the following characteristics:

They hang out online.
They buy things.
They share information.

If you’re not sure of what audience to serve, start with an audience that you already are in. Most of the people reading this article are Swift developers making apps for Apple platforms so I will use Swift developers as the example audience for the rest of this article.

Find Your Audience’s Watering Holes

After choosing an audience, the next step is to find their watering holes, where they hang out online. Some examples of places where Swift developers hang out online include the following:

Twitter
Reddit
Slack chat rooms
Stack Overflow
Apple’s developer forums
Mailing lists
Blogs
GitHub
Micro.blog

The best watering holes are places where people have discussions. That makes Reddit a better watering hole than Stack Overflow.

Twitter

Finding Swift developers on Twitter is going to require some searching and use of hashtags. The following are some search terms that will help you find Swift developers:

#swiftlang
Xcode
The names of Apple frameworks, such as UIKit and Core Data
The names of classes in Apple’s frameworks
Apple developer conferences, such as WWDC and AltConf

Either follow the Swift developers you find through your searches or build a list so you can see what they’re talking about on Twitter.

The following Reddit groups are where Swift developers congregate:

Slack

The following Slack chat rooms are where Swift developers congregate:

Slack chat rooms require an invite to join.

Sales Safari

Visit the watering holes and research what people are talking about. When you find an interesting discussion, create a new text document with the URL of the discussion so you can go back to it in the future. Add sections named Pain, Jargon, and Recommendations in the text document.

Write down any phrases that express pain and frustration in the Pain section. The original question will be the major source of pain.

Write down any jargon in the Jargon section. Examples of jargon for Swift developers are the names of Apple’s classes and frameworks. The term massive view controller is another example. You can use the list of jargon to search the watering holes and the Internet for more discussions and data.

Write down any recommendations in the Recommendations section. Many of the answers to the original question are going to be recommendations. If someone suggests doing something or avoiding something, write it down.

Sales safari takes a long time to generate data, 30 hours or more. But when you gather the data you will have a better understanding of your audience and its needs. Patterns will emerge.

Participate in the Community

While you do the sales safari, participate in the community to build trust. If someone asks a question that you can answer, answer the question. When people see you helping other people, they are more likely to trust you.

E-bombs

E-bombs are educational blog posts or videos. If you find multiple people asking the same question during your sales safari, answering that question is a good topic for an e-bomb.

When someone asks that question in the future, you can answer the question and link to your e-bomb for more detailed information. Doing this lets you get the word out about your e-bombs without being seen as self-promoting. Answering a question with a link to your e-bomb is going to be more effective than posting links to the e-bombs on Reddit or Twitter.

Develop a Small Product

Once you gather data on your audience, know what they need, and build a following with e-bombs, you can start building the product. Start with a small product that you can finish in 2–3 months. If you pick something too big, you may never complete and ship the product. You’re more likely to ship a smaller product.

Additional Information

The Stacking the Bricks website has numerous articles and podcasts on the 30×500 method. They also have a free email course.

If you have two thousand dollars, you can enroll in the 30×500 class that walks you step by step through the 30×500 method. They have signups every 3–4 months.

Displaying Data in a Mac Table View

Mon, 15 Jul 2019 19:08:18 +0000

Displaying data in a Mac table view has the following requirements:

Data to display.
Make the table view controller conform to the NSTableViewDelegate and NSTableViewDataSource protocols.
Write the function numberOfRows.
Write the function viewForTableColumn.
Set the table view’s data source and delegate.

Data to Display

A table view needs data to display. Usually table view data is in an array. As an example, suppose you have a note-taking app with a struct for a note.

struct Note {
	var title: String = ""
	var contents: String = ""
}

You will have an array of notes to display in the table view.

var notes = [Note]()

Conform to Delegate and Data Source Protocols

To make a Swift class or struct conform to protocols, add a colon after the name of the struct/class and add the protocol names, separated by commas. It’s similar to inheriting from a class.

The following code shows how to declare a class extension for a table view controller that conforms to the required protocols, NSTableViewDelegate and NSTableViewDataSource:

extension TableViewController: NSTableViewDelegate, NSTableViewDataSource {
  // Place the data source and delegate functions
  // inside the extension.
}

numberOfRows

The first function you must write is numberOfRows, which returns the number of rows in the table view. The number of rows is going to equal the number of items in the data source array. The following code shows an example of the numberOfRows function for a note-taking app:

func numberOfRows(in aTableView: NSTableView) -> Int {
	return notes.count
}

viewForTableColumn

The second function you must write is viewForTableColumn, which returns the view for a table view column.

Before you write code, you need to enter an identifier for the table column so you can load the cell from the storyboard. Open the storyboard, select the table column, and open the identity inspector. Enter an identifier for the column in the Identifier text field.

Remember the identifier you used because you’re going to need it when you write viewForTableColumn.

Now you can write the viewForTableColumn function. The function will create the table view cell from the storyboard by calling the NSTableView method makeView. After creating the table view cell, set the cell’s text field contents to the data you want to display in the cell.

The following code demonstrates how to display a note’s title in the table column:

func tableView(_ tableView: NSTableView, 
  viewFor tableColumn: NSTableColumn?, 
  row: Int) -> NSView? {
    
  guard let cellView = tableView.makeView(withIdentifier: 
    NSUserInterfaceItemIdentifier(rawValue: "TitleColumn"), 
    owner: self) as? NSTableCellView 
  else {
    return nil   
  }
    
  cellView.textField?.stringValue = notes[row].title
  return cellView      
}

The guard statement says to return nil if a user interface element with the raw value of TitleColumn, the identifier you set in the storyboard, is not found in the storyboard. If the element is found, set the cell’s text field to display the title of the note at subscript row in the notes array, then return the cell’s view.

Set the Table View’s Data Source and Delegate

The last step is to set the table view’s data source and delegate to the table view’s view controller. Setting the data source and delegate allows the functions numberOfRows and viewForTableColumn to be called when loading the table view controller.

Open the storyboard and make a connection from the table view to the table view’s view controller. A HUD like the following will open:

Select dataSource. Repeat the connection and select delegate.

Responding to Mac Menu Selections

Mon, 08 Jul 2019 18:53:22 +0000

It’s not too difficult to add menus and menu items to a Mac app using Xcode’s Object Library. What can be tricky is how to get your app to respond properly when someone chooses a menu item that you added.

Create an Action

There are two steps to handling a menu selection. The first step is to create an IBAction, which is a function that will get called when someone chooses the menu item. The following code shows an example of defining an IBAction for an Export menu item:

@IBAction func export(_ sender: NSMenuItem) {
    
}

Normally you write another function that does the actual work and call that function from the IBAction.

Connect the Menu Item to the Action

The second step is to connect the menu item to the action you created. Connecting the menu item is required to enable the menu item. If you find your menu items are disabled, make sure they’re connected.

Open the storyboard and make a connection (Control-drag) from the menu item to the First Responder item in the application scene. A HUD panel with a long list of actions will open. Select your action from the list. Now your app should be responding properly to menu selections.

An Introduction to Xcode’s Debugger

Wed, 19 Jun 2019 04:15:10 +0000

I see a lot of questions on forums from iOS and Mac developers having issues with their code not working properly or crashing with cryptic error messages, like the following:

Thread 1: signal SIGABRT
Thread 1: Fatal error: Unexpectedly found nil while implicitly unwrapping an Optional value
EXC_CRASH (SIGTRAP)
Unrecognized selector sent to instance
Thread 1: EXC_BAD_ACCESS (code=2, address=0x102044190)

Many of these issues can be fixed quickly with the help of Xcode’s debugger. In this article I will show you the basics of Xcode’s debugger so you can find and fix bugs in your code more quickly.

Breakpoints

Breakpoints are fundamental to using debuggers. Breakpoints pause your app so you can debug it. If you want to debug an Xcode project, you will have to set at least one breakpoint.

Setting Breakpoints

The easiest way to set a breakpoint is to click on the left side of Xcode’s editor next to the line of code where you want your app to pause.

The blue arrow in the editor indicates a set breakpoint.

Disabling Breakpoints

Suppose you set a breakpoint inside the loop. You don’t want your app to pause every time you go through the loop. By disabling the breakpoint after going through the loop once, Xcode won’t pause at the breakpoint until you enable it.

Click on an enabled breakpoint to disable it.

Setting an Exception Breakpoint

Setting a breakpoint on a line of code works when you have an idea of where the problem is in your code. But if your app is crashing, it can be tough to find the source of the crash in your code.

Finding the source of crashes is where exception breakpoints come in. When your app crashes, it throws an exception. Setting an exception breakpoint pauses execution of your app when it crashes so you can locate the source of the crash.

To create an exception breakpoint, choose Debug > Breakpoints > Create Exception Breakpoint. A popover opens.

You shouldn’t have to change anything in the popover. Make sure the Exception menu is set to All and the Break menu is set to break on throw.

You can find more information on the common causes of app crashes in the Fixing and Avoiding Crashes in Swift Code article on this site.

Debug Area

Now that you set some breakpoints, you can build and run your project. When your app reaches a breakpoint, Xcode pauses the app, showing the debug area of the project window at the bottom of the window.

As you can see in the screenshot, there are three sections of the debug area.

Debug bar
Variables view
Console

Debug Bar

The debug bar contains buttons to perform the most common debugging commands. There are two sets of buttons divided by a thin vertical separator. The first set has the following buttons, running from left to right:

Show/hide the debug area
Activate/deactivate breakpoints, which allows you to quickly toggle your active breakpoints with one click.
Resume program execution
Step over
Step into
Step out

The second set has the following buttons:

Debug view hierarchy
Debug memory graph
Override appearance
Simulate location

The buttons in the second set are beyond the scope of this article. Debugging the view hierarchy and debugging the memory graph could be the subject of their own articles.

Stepping

In the previous section you saw that the debug bar has three buttons for stepping through your code: step over, step into, and step out. When should you step over, step into, and step out?

You are going to step over code the most. When you step over a line of code, the debugger executes that line of code and moves to the next line. Unless the current line of code calls another function, you should step over that line.

If the current line of code calls another function, you may want to step into the function. Suppose you have a function A that calls function B. If you step over the call to B, the debugger goes through all the code in B and takes you to the next line in A. This behavior may be what you want, especially if you are making a call to a function in Apple’s frameworks, where you don’t have the source code.

But you may want to step through the code in B. To step through the code in B, step into the call to B in function A. The debugger will take you to the start of B, where you can step over the code in B line by line.

When you step into a function, you can use the Step Out button to go back to the previous function. If you are in B and want to go back to A, click the Step Out button.

Variables View

The variables view shows your app’s variables and their values. Sometimes it can be tough to find the value you want in the variables view. The variable you want may be nested inside data structures. The value may show up as a memory address instead of the real value. When the variables view doesn’t show what you want, you must resort to the console.

Console

The console shows any messages your app generates as it runs. If you have any print statements in your code, the printed messages will appear in the console.

You can also use the console to run LLDB debugger commands. The LLDB page has a list of commands.

One common command is the po command that prints out the contents of a variable. If you type a variable name, you’ll notice the console supports Xcode’s autocompletion.

Introduction to Mac Development: Connecting UI Elements

Sun, 07 Apr 2019 18:20:17 +0000

If you read the Connections Inspector section of the article on how to build a user interface for a Mac app, you’ll notice I didn’t mention how to make connections in your user interface. Making connections is a large enough topic to warrant its own article, which you are reading now. After reading this article you’ll know how to connect UI elements so you can access them in your code.

Virtually all the material in this article also applies to iOS apps.

Outlets

In Interface Builder (it’s part of Xcode) you create connections by creating outlets and actions. An outlet is a variable that holds a reference to an item in a storyboard or xib file. Use outlets to access UI elements in your code.

Actions

An action is a function that gets called when someone interacts with your app’s user interface, such as choosing a menu item or clicking a button.

Creating and Connecting an Outlet

Interface Builder lets you create and connect outlets and actions in one step. To create an outlet and connect it, start by opening the assistant editor. Choose Editor > Assistant to open the assistant editor. If you’re running an older version of Xcode, choose View > Assistant Editor > Show Assistant Editor.

Have the storyboard open in one editor. Have the source code file open in the second editor for the class, most likely a view controller, where you want to add the outlet.

Select the UI element in the storyboard. Hold down the Control key, and drag to the source code file. When you are inside the class, Xcode’s editor will display the message Insert Outlet or Action. Release the button. A popover like the following will open:

Enter the name of the outlet in the Name text field. The type is the type of the UI element you selected in the storyboard. Make sure the Storage menu is set to Strong. Click the Connect button to create the outlet and connect the UI element to the outlet.

Notice the filled-in circles on the left side next to each outlet. Those circles tell you the outlets are connected. Once you connect an outlet, you can access it in your code.

Creating and Connecting an Action

Creating and connecting an action is pretty much the same as creating and connecting an outlet. Open the assistant editor so the storybord and source code file are both open. Select the UI element and control-drag to the source code file.

Enter a name for the action in the Name text field. Xcode defaults to using the Any type for actions, which means the sender of the action can be any data type. You can also use the type of the UI element you selected in the storyboard. Use the type of the UI element if you need to access a property of that element in the action’s code.

Click the Connect button to create the action and connect the UI element to the action.

The filled-in circle indicates the action is connected. Once you connect an action, you can add code for the action so your app responds properly to the action.

Exercise

Create an app that keeps track of the number of times someone clicks a button. In the user interface, add a button and two labels: one with the text Clicks: and one with the initial value of zero.

Add an outlet for the label that displays the number of clicks. Add an action to handle the button click, which involves increasing the number of clicks by one and displaying the current number of clicks in the label. I have the project on GitHub for you to look at if you get stuck.

Introduction to Mac Development: Build the UI

Fri, 05 Apr 2019 18:03:13 +0000

After creating a project, the next step in developing a Mac app is to build the user interface. In this article you’ll learn the basics of building user interfaces with Interface Builder, which is a part of Xcode.

I talk about storyboards in this article, but most of the material applies to xib files as well. The main differences are that xib files do not have scenes and do not have view controllers.

Open the Storyboard

Select the main.storyboard file to open it in Xcode. The following screenshot shows what a storyboard looks like initially:

The left side of the storyboard (or xib file) contains the document outline, which shows the items in the storyboard. The right side of the storyboard contains the canvas, which is where you lay out the user interface.

A basic storyboard in a Mac app has the following scenes:

Application scene
Window controller scene
View controller scene

The application scene contains the menu bar. The window controller scene contains the main window for the app. The view controller scene contains the view controller that manages the window’s content. You place the controls in your user interface in the view controller.

Simple user interfaces can get away with one window controller and one view controller. More complex user interfaces require more scenes. If you were going to recreate the interface for Apple’s Mail app, you would need four view controller scenes:

A view controller for the outline view with the list of mailboxes and folders.
A view controller for the table view containing the messages in the selected mailbox or folder.
A view controller for the text view showing the contents of the selected message.
A split view controller to contain the three view controllers.

A Mac app with user preferences would have a window controller scene for the preferences window.

Finding the UI Elements

To build a user interface you must first find the user interface elements. The user interface elements are in the object library. In Xcode 10 Apple changed the location of the object library so it can be difficult to find. The Library button is on the right side of the toolbar at the top of the project window.

Newer versions of Xcode have an Add (+) button to open the object library.

Click the Library button to open the object library. Option-clicking the Library button keeps the object library open until you explicitly close it.

At the top of the object library window is a search field. Enter a search term to more easily find an item in the object library. If you enter button in the search field, the object library shows all the available buttons.

Add UI Elements to Your Interface

To add an element to your app’s user interface, select it from the object library and drag it to the canvas. For most visible controls, including labels and buttons, you should drag the control to a view controller in the canvas.

Moving and Resizing Elements

Select a UI element from the canvas or document outline to move or resize it.

To move an element, select it and drag it to where you want it to be. To resize an element, select it, click one of the squares on the edges of the selected element, and drag.

Making Other Changes

To make other changes to UI elements, use the inspectors on the right side of the project window. If you don’t see the inspector, either choose View > Inspectors > Show X Inspector, where X is the name of the inspector or click the button in the upper right corner of the project window.

Xcode has the following inspectors for Mac UI elements:

Identity inspector
Attributes inspector
Size inspector
Connections inspector
Bindings inspector
View effects inspector

The attributes inspector is the inspector you’ll use the most.

Identity Inspector

The thing you’ll use the identity inspector for most is setting the class of a UI element.

Set the class for a UI element if you create a subclass of one of Apple’s classes. Set the class to tell Xcode that the UI element is your subclass. View controllers are what you’re most likely to subclass.

Attributes Inspector

The attributes inspector is where you view and edit a UI element’s attributes. What you can set in the attributes inspector depends on the UI element. The following screenshot shows the attributes inspector for a button:

As you can see there are a lot of attributes you can set for a button.

Size Inspector

The size inspector is where you can see and change a UI element’s position and size.

If you are not using auto layout, use the Autoresizing mask to determine how the element’s size and position changes when someone resizes the window.

Connections Inspector

The connections inspector shows the connections a UI element has and can have.

The Sent Actions section in the screenshot shows an actual connection along with the button outlet in the Referencing Outlets section. The rest of the items in the screenshot are the possible connections that element can have.

Click the X on a connection to remove the connection.

Bindings Inspector

The bindings inspector works with Cocoa bindings. Cocoa bindings are not available on iOS and have not been changed since macOS 10.5 so you’re not going to find a lot of current information on how to use them.

Cocoa bindings use special controllers to keep user interface elements and data objects in sync. If you open the object library and enter Controller in the search field, you can see the bindings-compatible controllers: object controller, array controller, dictionary controller, tree controller, and user defaults controller.

To use bindings add one of the bindings-compatible controllers to the storyboard or xib file. Use the attributes inspector to determine the type of data the controller manages. Use the bindings inspector to bind a UI element to the controller.

The bindings inspector shows all the bindings a UI element has.

You can bind a UI element by selecting the Bind to checkbox, choosing a controller to bind to, and supplying the appropriate keys.

View Effects Inspector

The view effects inspector works with Core Animation to animate UI elements.

Exercise

Add some controls to a storyboard. Run the project and see those controls in the window.

Summary

Remember the following points to build your Mac app’s user interface:

Select the storyboard or xib file in the project navigator to open it.
Option-click the Library button to access the UI elements.
Drag a UI element from the object library to the canvas to add it to the user interface.
Use the inspectors to make changes to the elements.

Introduction to Mac Development: Create a Project

Mon, 25 Mar 2019 19:25:21 +0000

The first step in creating a Mac app is to create a project in Xcode. This article walks you through creating a Mac app project and explains the files Xcode creates for the project.

Creating the Project

Choose File > New > Project to create a new project. The New Project Assistant window opens.

Select macOS from the top of the window to show the Mac project templates. Select Cocoa App from the list of application project templates. Click the Next button.

Now things become a little more complicated. You must supply the following information for the new project so Apple can set the project the way you want:

Product name
Team
Organization name
Organization identifier
Language
Whether to use storyboards or xib files for the user interface
Whether or not to create a document-based app
Whether or not to use Core Data
Whether or not to add testing targets

Product Name

The product name is the name of the project. It’s also the name of the application. The menu bar for the app will have a menu with the product name that has menu items to quit and hide the app that use the product name.

It is possible to rename a project after creating it. But choosing a good name for the project when you create it makes things easier.

Team

The Team menu is for people who have a paid Apple developer account. Choose your team from the menu, and Xcode will use it to code sign your app. If you don’t have a paid developer account, choose None from the Team menu.

Organization Name

The organization name appears in the copyright notice of the source code files you create for your project. If you don’t have an organization name, use your name.

Organization Identifier

The organization identifier uniquely identifies the organization. The identifier takes the form com.OrganizationName. There should be no spaces in the organization identifier.

Language

The Language menu determines the programming language for the source code files Xcode creates for the project. There are two language choices for Mac apps: Swift and Objective-C.

Storyboards or Xib Files

The Use Storyboards checkbox determines whether Xcode creates a storyboard or a xib file for your project’s user interface. Storyboards let you see the app’s entire user interface in one place. Storyboards also make working with view controllers easier. But xib files make creating master-detail interfaces easier.

Xcode 11 Update

Xcode 11 replaces the Use Storyboards checkbox with a User Interface menu item. For a Mac app the user interface options are SwiftUI, Storyboards, and Xib Files.

Document-based Apps

The Create Document-Based Application checkbox determines whether your app uses Apple’s document architecture. Document-based apps let people create, open, and save documents as separate files that they can share with other people. Examples of document-based apps include text editors, spreadsheets, and drawing apps.

If you decide to create a document-based app, use the Document Extension text field to supply the file extension for the document files your app creates.

Core Data

The Use Core Data checkbox determines whether your app uses Core Data for your app’s data. Core Data is a complex technology so I recommend not using it when starting out making Mac apps.

Testing Targets

The Include Unit Tests and Include UI tests checkboxes determine whether Xcode creates targets for unit testing your app’s code and testing your app’s user interface. If you’re learning Mac development, you can deselect the checkboxes. When you start making more complex apps, unit testing and UI testing can help you write better code and design better user interfaces.

Finishing Creating the Project

When you supply all the information Xcode demands for the project and click the Next button, the last step is to choose a location to save your project. At the bottom of the Save panel you should see the following controls:

If you select the Create Git repository on my Mac checkbox, Xcode will place your project under version control. You can get away with not using version control for small projects. If you write an app you want to share with the public, I recommend using version control so you can track changes to files and go back to earlier versions of files if you make mistakes. I wrote a book on version control for Mac developers if you want to learn more about version control.

Project Files

The project navigator on the left side of the project window lists the files in your project. The following screenshot shows the files Xcode creates for a Mac project that uses Swift, uses storyboards, is not document-based, and does not use Core Data:

The files in the project name folder (ButtonClickCounter in the screenshot) are the most interesting.

AppDelegate.swift
ViewController.swift
Assets.xcassets
Main.storyboard
Info.plist
ProjectName.entitlements

When you’re starting Mac development, focus on the source code and storyboard files. You’ll use the other files and folders when you get closer to shipping an app.

Select a file from the project navigator to open it in Xcode’s editor.

AppDelegate

The AppDelegate.swift file lets you add code to run when your app launches and terminates.

ViewController

The ViewController.swift file contains a class file for the view controller Xcode creates in the storyboard. A view controller manages a view. You will create a view controller class for every view controller you add to the storyboard.

Projects that use xib files instead of storyboards do not have a view controller source code file.

Assets Folder

The Assets folder contains the images in your project. The most common use of the Assets folder is to add an icon for your app.

Storyboard

The storyboard contains your app’s user interface. Select the storyboard to open it and build your app’s user interface.

Info.plist

The Info.plist file contains information about your app, such as a copyright notice.

While you can edit the Info.plist file directly, it’s usually easier to use Xcode’s project editor. Select the project (it’s the first item) from the project navigator to open the project editor. Select the app target from the left side of the project editor. Click the Info button at the top of the project editor to start editing Info.plist.

Entitlements File

The entitlements file contains a list of Apple technology capabilities that your app supports. If you select the entitlements file, you will notice that the App Sandbox is turned on.

While you can add and remove capabilities from the entitlements file, it’s usually easier to do it from Xcode’s project editor. Select the app target from the left side of the project editor. Click the Capabilities button at the top of the project editor.

If you want your app to support things like iCloud and push notifications, turn the switch from Off to On. Keep in mind that most of the capabilities require your app to be code signed, which means you have to be a paid member of Apple’s developer program.

Exercise 1: Run the Project

Choose Product > Run in Xcode or click the Run button in the upper left corner of the project window to run the project. An empty window should appear.

Exercise 2: Experiment with Project Options

Create different types of projects and compare the files that are created. Create a project that doesn’t use storyboards. Create a document-based app project. Create a project that uses Core Data.

Resources for Learning Mac Development

Tue, 05 Mar 2019 19:42:05 +0000

Last update: December 2025

I’ve seen a lot of questions from people on Reddit and Slack looking for resources on Mac development in Swift. Compared to iOS development there are relatively few resources for learning to write Mac apps in Swift. I’ve collected what I found and am sharing with you.

Books and Courses

The book Hacking with macOS teaches Mac development by building 18 projects.

TrozWare publishes the book macOS by Tutorials, where you build two SwiftUI apps and a menu bar app with AppKit. This book is geared towards iOS developers who want to learn how to make Mac apps.

If you’re completely new to Mac development, Kodeco has the book macOS Apprentice.

I wrote an introductory book on Mac development, Swift Dev Journal’s Intro to Cocoa. The book walks you through the creation of a complete Mac app using AppKit, Swift, and storyboards.

The book Cocoa Programming for Mac OS X is the only other Mac programming book I see people recommend online. The book uses Swift 1.2 so a lot of the code is not going to compile with recent versions of Swift and Xcode. If you can work around that limitation, the book does do a good job of introducing Mac development with Cocoa.

Mohammad Azam has the course Programming macOS Using SwiftUI – Project Based Learning that teaches Mac development with SwiftUI.

The book Building macOS Apps With SwiftUI: A Practical Learning Guide by Grace Huang covers Mac development with SwiftUI.

The course Build That MacOS App teaches Mac development with SwiftUI.

Christian Tietze has a book that covers a different aspect of Mac development, Make Money Outside the Mac App Store. The book shows you how to sell Mac apps without using the Mac App Store.

Websites

Kodeco (formerly raywenderlich.com) has the largest collection of modern tutorials on Mac development. They stopped making Mac tutorials so some tutorials may be slightly out of date.

AppCoda has several Mac programming tutorials.

The site you’re currently reading has a small but growing collection of articles on Mac development, including SwiftUI articles.

If you prefer videos, Lucas Derraugh has a YouTube channel with videos on Mac development.

TrozWare has articles on making SwiftUI Mac apps.

The Nil Coalescing blog has a collection of SwiftUI articles, some of which cover Mac development.

SerialCoder.dev has tutorials on Mac and SwiftUI development.

Christian Tietze blogs about Mac app development.

Places to Ask Questions

Stack Overflow. Use the cocoa tag when asking Mac programming questions that aren’t about SwiftUI.
Apple’s developer forums
SwiftUI Reddit group
MacRumors forums

Slack Workspaces

The following workspaces on Slack are places where people talk about Mac development:

AppKit Abusers is the most active Slack room for Mac development.
Hacking with Swift has a Mac development room.
CocoaHeads doesn’t get a lot of Mac development discussion, but the workspace covers both iOS and Mac development.

Have a Resource to Add?

Use the Contact page to send me an email with your resource for learning Mac development.

Adding Folders of Files to Xcode Projects

Mon, 25 Feb 2019 05:04:25 +0000

When you add a folder of files to an Xcode project by choosing File > Add Files to “ProjectName”, you should see the following options at the bottom of the Open panel:

As you can see there are two options for adding folders to a project.

Create groups
Create folder references

What’s the difference between creating groups and folder references?

When you create a group for a folder, Xcode creates a gray folder (yellow folder in earlier Xcode versions) for the folder in the project navigator. Create a group when you need to edit the folder’s files in Xcode. If you’re adding a folder of source code files, you should create a group for the folder.

When you create a folder reference, Xcode creates a blue folder in the project navigator. The folder will also be copied to the app bundle when you build the project. Create a folder reference when you don’t need to edit the folder’s files in Xcode. If you’re adding a folder of image or sound files, you should create a folder reference.

I have a great idea for an app. How do I get started?

Mon, 11 Feb 2019 19:31:20 +0000

I see this question come up a lot. Someone has an idea for an iOS app, and they want to know how to get started making the app. You have two options for making an iOS app: hiring a developer to make the app or making the app yourself.

Hire a Developer to Write the App for You

Hiring a developer is expensive. A good iOS developer charges $100(US) or more per hour. If you can afford to hire a developer, you can find one at iOS Dev Directory.

You may think you can hire someone to write an iOS app for a percentage of the profits. Unless you have a friend who’s an iOS developer, you’re going to have a tough time finding someone to work for a percentage of the profits. Working for a percentage of the profits is basically working for free because the chances of making lots of money from an iOS app are slim. Most people are unwilling to work for free.

Learn Programming

The cheaper, more time consuming option is to make the app yourself. If you’re asking how to make an iOS app, chances are high you have never programmed before. Learning to program is the first step in making an iOS app. Trying to develop an iOS app without knowing how to program is like trying to write a book without knowing how to write. It’s going to be very difficult.

Swift is the language to learn to develop iOS apps. Get a book to learn Swift. People recommend the following books to learn Swift:

Despite Apple’s claims, Swift is not an easy language to learn. If you struggle learning Swift, I recommend learning Python and going back to learn Swift. Python is an easier language to learn than Swift. Once you learn Python or another programming language, learning Swift will be easier.

Learn iOS Development

Once you learn how to program, you can move on to learning iOS development. My Learning iOS Development article has many resources for learning how to make iOS apps.

Fixing and Avoiding Crashes in Swift Code

Tue, 05 Feb 2019 19:54:48 +0000

When you start out developing iOS or Mac apps in Swift, you run into a common problem. Your project builds without any errors but crashes when you run it. It’s frustrating to have your code not work, and the cryptic messages Xcode spews don’t help much.

In this article you’ll learn how to get Xcode to show you where the crash occurs in your code. You’ll also learn the most common causes of crashes in Swift apps and how to avoid them.

Add an Exception Breakpoint to Locate the Crash

Adding an exception breakpoint in Xcode makes it easy to find where your code crashes. Open Xcode’s breakpoint navigator by choosing View > Navigators > Show Breakpoint Navigator.

Click the Add (+) button at the bottom of the breakpoint navigator and choose Exception Breakpoint. A popover opens for the breakpoint.

Make sure the Exception menu is set to break on all exceptions and to break when an exception is thrown.

Now when your app crashes, Xcode breaks into the debugger and shows you the line of code where the crash occurred. Showing the line of code where the crash occurred comes in handy when you’re trying to figure why your app crashed.

If you look at the screenshot of the breakpoint navigator, you will notice the exception breakpoint is in the User section. User breakpoints apply to all projects so you don’t have to set them for each project.

Because exception breakpoints help so much to find where your apps crash, they’re strong candidates to be user breakpoints. To make a breakpoint a user breakpoint, select it in the breakpoint navigator, control-click, and choose Move Breakpoint To > User. Now the exception breakpoint will fire when any of your projects crash.

Common Crash Causes

Now that you can determine where your app crashes, you want to know why your code is crashing and how to fix it. Without seeing your code, I can’t tell you exactly why your code is crashing, but I can tell you the most common causes of crashes.

Unwrapping a nil Swift optional
Disconnected outlets
Accessing an element outside an array’s bounds
Accessing an uninitialized variable

Unwrapping a Nil Optional

The leading cause of crashes in Swift apps is unwrapping a nil optional value. When you unwrap a nil optional value, you will see the following error message in Xcode’s debug console:

Fatal error: Unexpectedly found nil while unwrapping an Optional value

This error is usually caused by two things. First, force unwrapping an optional by adding an exclamation point to a variable’s name. Second, using as! to downcast an optional value to a specific type.

The fix is to avoid force unwrapping. Use if let or guard statements to safely unwrap your optionals. Use as? instead of as! when downcasting. The following articles provide more detailed information on optionals:

Disconnected Outlets

The second most common cause of crashes in Swift apps is having a disconnected outlet for a user interface element and accessing that outlet in your code.

You can check if an outlet is connected in Xcode’s source code editor. Next to an outlet is a circle. The following screenshot shows a disconnected outlet:

A connected outlet has the circle filled in.

To connect the outlet open Xcode’s assistant editor so the storyboard and the source code file are both open. Select the user interface element in the storyboard. Hold down the Control key and drag to the outlet in the source code file.

Out of Range Array Access

If you try to access an element in an array that is not in the array’s range, your app will crash. Out of range errors are usually off-by–1 errors because array indices start at 0 instead of 1. An array with 10 elements has indices 0–9, not 1–10. If you try to access the tenth element with the following code:

myArray[10]

The app will crash with an out of range error because the subscript [10] references the 11th member of an array with only 10 elements.

You can also get an out of range error if you try to access elements in an empty array. An empty array has no elements so any subscript is out of range. Swift arrays have an isEmpty property you can check to see if the array is empty.

Accessing an Uninitialized Variable

This error usually occurs in view controllers when you try to access a property in viewDidLoad or similar initialization function. viewDidLoad is called before the code that initializes the property, causing a crash.

A common fix for accessing a property before it’s initialized is to access the property in viewDidAppear, which gets called after viewDidLoad.

UndoManager Introduction Swift

Sat, 19 Jan 2019 19:39:59 +0000

I recently needed to add undo support for a Mac app after not dealing with undo for several years. I noticed some subtle changes so I’m sharing what I learned here. I have not worked with the undo manager in an iOS app, but most of the material in this article should apply to iOS apps as well as Mac apps.

Accessing the Undo Manager

The first step to adding undo support in your app is to access the undo manager. Document-based Mac and iOS apps have an undo manager for each document. Use the undoManager property to access the document’s undo manager.

Core Data apps also have an undo manager. The managed object context has an undo manager, which you access with the undoManager property.

Registering an Undo Operation

When someone performs an action in your app that can be undone, register an undo operation for that action. Registering an undo operation adds the action to the undo stack so the action can be undone.

The easiest way to register an undo operation is to call the registerUndo method. There are two registerUndo methods: one that takes a closure (unnamed function) as an argument and one that takes a selector as an argument. The method that takes a closure is the better option for Swift developers. Swift’s closure syntax is less painful to work with than its syntax for working with Objective-C selectors.

When calling registerUndo, supply a target for the undo operation and a closure handler that calls the function to perform the undo operation.

Suppose you have a note taking app. In a note taking app people can remove notes. An important undo feature is to undo note removal. If someone accidentally removes a note, they would like to get it back.

To support undoing note removal in the app, you would write two functions: one function to remove a note and a second function to restore a removed note.

In the function to remove a note, call registerUndo. Call the function that restores the note in the handler closure.

func removeNote(note: Note) {
	undoManager.registerUndo(withTarget: self) { targetSelf in
    targetSelf.restoreNote(note)
  }
  undoManager.setActionName("Remove Note")
    
  // Code to remove the note goes here.
}

In the removeNote function, the code calls registerUndo. The closure is the block that starts with the brace before targetSelf. The name targetSelf is one I created. You can use whatever name you want to indicate the variable is the target. The closure calls the restoreNote function to restore the removed note. When someone removes a note and undoes it, the app restores the note by calling restoreNote.

The last line of code in the function sets an action name for the Undo menu item in the Edit menu. The code sets the menu item to Undo Remove Note.

Now let’s look at the function to restore the removed note.

func restoreNote(note: Note) {
  undoManager.registerUndo(withTarget: self) { targetSelf in
    targetSelf.removeNote(note)
  }
  undoManager.setActionName("Remove Note")
    
  // Code to restore the note goes here.
}

Like the removeNote function, restoreNote calls registerUndo. The main difference is the handler closure. The handler calls removeNote because removing the note is the undo operation in this case. If someone undoes removing a note and chooses Redo, the code calls removeNote to redo removing the note.

You might be wondering why the action name is Remove Note instead of Restore Note. When you undo an action in a Mac app, a Redo menu item appears in the Edit menu. In this note taking app example, when you redo, you are redoing removing a note. A menu title Redo Remove Note makes more sense than Redo Restore Note.

Finding the Slow Spots in Your Code with the Time Profiler Instrument

Mon, 07 Jan 2019 19:55:55 +0000

I continue my coverage of Instruments with the Time Profiler instrument. If your app is running slowly, use the Time Profiler instrument to find the slow spots in your code so you know where to optimize.

If you are new to Instruments, I recommend reading the Measuring Your App’s Memory Usage with Instruments article. That article provides an introduction to Instruments and covers some aspects of using Instruments this article glosses over.

How the Time Profiler Instrument Works

The Time Profiler instrument records the call stack every millisecond. The function at the top of the call stack is the function your app is currently executing. If a function appears at the top of the call stack in a lot of samples, that’s a sign your app is spending a lot of time in that function.

Launch and Record

Choose Product > Profile in Xcode to launch Instruments. Select the Time Profiler template and click the Choose button.

Click the Record button to launch your app and start profiling.

Controlling the Graph

When you pause recording you’ll notice the Time Profiler instrument shows a lot of graphs. There’s a graph for each thread, and iOS and Mac apps have a surprisingly high number of threads.

Above the graph is a series of buttons to control what graphs appear in the trace document window.

You can show instruments, threads, or CPU cores. You can also use the search field to filter what graphs appear. At the start you should focus on instruments, specifically CPU usage, because it helps find the slow spots in your code.

CPU Usage Graph

Starting with Xcode 10 the Time Profiler instrument has two graphs: CPU usage and life cycle. If you move the mouse cursor over the CPU usage graph, tooltips appear with the percentage of CPU usage at that moment in the recording.

Life Cycle Graph

The life cycle graph reports the current state of your app: initializing, launching, foreground, or background. If you move the mouse over the life cycle graph, tooltips tell you the state of the app and the amount of time the app was in that state.

Older versions of Xcode do not have a life cycle graph.

Profile Data

The Time Profiler instrument shows the call tree view initially. Click the Call Tree button at the bottom of the window and select the Invert Call Tree and Hide System Libraries checkboxes to make your code easier to find in the call tree view.

For each function the call tree tells you its weight and it self weight. The weight is expressed as a time and a percentage. The weight measures the amount of time the function was on the call stack. The self weight measures the amount of time the function was at the top of the call stack.

The Self Weight column is more important. Suppose you have a function A that calls functions B and C. The Weight column for A tells you the amount of time your app was in functions A, B, and C. The Self Weight column for A tells you the amount of time your app was in A. When you’re looking for the slow spots in your code, look at functions with a high self weight.

Double-clicking a function opens the source view, where you can see the lines of code that take the most time in the function.

Narrative

The narrative section has a listing for each event in the Life Cycle graph. Each listing has the start time relative to the start of the recording and a description of what the app is doing.

Older versions of Xcode do not have a narrative section.

Samples

If you choose Samples from the jump bar, you can look at every sample the Time Profiler instrument took during the recording. Instruments shows the following data for each sample:

Sample time, relative to the start of recording
Core, the CPU core
Process, which is the name of your app
Thread
State, which is usually Running
Backtrace, which lists the function at the top of the call stack

The extended detail view shows a compressed backtrace. If you want to see every function in the call stack, click the button at the top right of the backtrace.

Remember that the Time Profiler instrument takes a sample every millisecond so there are a lot of samples to go through.

CPU Cores

If you move the mouse cursor over a CPU core in the graph, a tooltip appears showing you the percentage of CPU usage for that core at that moment in the recording.

Selecting a CPU core from the instrument list fills the detail view with call tree statistics for that core. Choosing Samples from the jump bar shows all the samples Instruments recorded for that CPU core.

Threads

If you move the mouse cursor over a thread in the graph, a tooltip appears showing the percentage of CPU usage for that thread at that moment in the recording. The graph can tell you if the main thread is doing too much work.

Selecting a thread from the instrument list fills the detail view with call tree statistics for that thread. Choosing Samples from the jump bar shows all the samples Instruments recorded for that thread.

Summary

The main point of using the Time Profiler instrument is to find the slow spots in your code. Look for functions in the call tree with a high self weight. If you need to make your app run faster, start by optimizing those functions with a high self weight.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Creating a Draggable iOS View

Thu, 27 Dec 2018 23:29:19 +0000

Some iOS apps have items like cards or sticky notes that you can drag. Making an iOS view draggable is less difficult than you think. Use a pan gesture recognizer, and you can drag a view around with your finger.

The Steps

Take the following steps to create a draggable view in iOS:

Add a view to the view controller scene in your storyboard.
Drag a pan gesture recognizer to the view so the view becomes draggable.
Create an action (IBAction) for the pan gesture recognizer by making a connection from the storyboard to the view controller’s source code file. Set the type for the sender to UIPanGestureRecognizer.

I have a demo project for draggable views on GitHub.

The Code

To make the view move around when you drag it, you must implement the action for the pan gesture recognizer. The following code shows an example of panning a view:

@IBAction func panView(_ sender: UIPanGestureRecognizer) {
  let translation = sender.translation(in: self.view)
    
  if let viewToDrag = sender.view {
    viewToDrag.center = CGPoint(x: viewToDrag.center.x + translation.x, 
      y: viewToDrag.center.y + translation.y)
    sender.setTranslation(CGPoint(x: 0, y: 0), in: viewToDrag)
  }
}

By setting the type of the IBAction to UIPanGestureRecognizer, you can access the view being dragged through the pan gesture recognizer’s view property.

The first line of code determines how far the view dragged. Using an if-let statement avoids force unwrapping optionals when accessing the dragged view.

The first line of code inside the if-let block moves the center of the view by the amount of the drag. The second line of code clears the translation for future drags.

Measuring Your App’s Memory Usage with Instruments

Fri, 14 Dec 2018 05:11:05 +0000

On Stack Overflow I see many questions from people who have trouble interpreting the data Instruments generates. After reading this article you’ll know how to interpret the data Instruments generates for the Allocations and Leaks instruments and learn tips you can use with other instruments.

What is Instruments?

Instruments is an app that is bundled with Xcode to record and display statistics about your app as it runs. Instruments comes with a collection of instruments, each of which records a specific set of statistics. Some popular instruments include the following:

The Leaks instrument checks your app for memory leaks.
The Allocations instrument records statistics about memory allocations.
The Time Profiler instrument measures CPU usage and helps you find the slow spots in your code.

If you’re learning iOS or Mac development, you’re not going to use Instruments at first. You normally use Instruments when you get closer to shipping an app. But if your iOS app is generating memory warnings when you run it or your app runs really slow, you’ll want to profile the app with Instruments.

Launching Instruments

Because Instruments is located inside Xcode’s app bundle, you won’t be able to find it in the Finder. The easiest way to launch Instruments is to profile your project by choosing Product > Profile in Xcode. When Instruments launches, you will be asked to choose a template.

Select the Leaks template and click the Choose button. The Leaks template include both the Leaks and Allocations instruments.

The Trace Document Window

When you click the Choose button, an empty trace document window opens in Instruments.

Running from top to bottom, the main areas of the trace document window are the following:

Toolbar
Instrument list
Jump bar
Detail view
Extended detail view
Bottom bar

For this article the only toolbar items you need to worry about are the buttons to start/stop recording and pause recording on the left side of the toolbar. The toolbar also has controls to choose an app to profile, add an instrument to the trace, and show/hide different parts of the trace document window.

The instrument list shows the instruments being used in the trace along with a graph for each instrument. The graph is going to be empty until you start recording.

The jump bar allows you to choose what to show in the detail view. The detail view shows the profiling statistics. The extended detail view shows additional statistics. For most instruments the extended detail view shows the call stack.

The bottom bar contains controls to filter the information that appears in the detail view.

Configuring an Instrument (Optional)

You won’t need to configure any instruments to follow along with this tutorial. But when you use Instruments, you may need to configure an instrument, and it helps to configure the instrument before you start recording.

Choose File > Recording Options to configure an instrument. The following screenshot shows the configuration options for the Allocations instrument:

Profiling Your App

At this point you can start profiling your app. Click the Record button on the left side of the toolbar. Your app will launch. Use your app. When you are finished, you can either click the Pause button or the Stop button. The Leaks instrument is set to check for leaks every 10 seconds so you should run your app for at least 10 seconds.

If you want to save your trace so you can look at the results later, choose File > Save.

Reading the Profiling Data

Now comes the hard part: making sense of all the data that Instruments generates. Let’s start with the graph. If you move the mouse cursor inside the graph, Instruments shows a tooltip with a piece of data about the graph. The following image shows the memory usage for the Allocations instrument:

You can focus on a specific time interval in the graph by setting an inspection range. Click inside an instrument’s graph and drag to create the inspection range. The inspection range is shaded blue, which you can see in the following screenshot:

When you set an inspection range, the statistics in the detail view change to reflect the time interval in the inspection range. Clicking in the graph outside of the inspection range you set clears the inspection range.

Allocations Instrument Results

Now it’s time to look at data for specific instruments. Let’s start with the Allocations instrument. If you select the Allocations instrument from the instrument list, the detail view shows a summary of the memory allocation data. The most important data is at the top.

To determine how much memory your app is currently using, look at the Persistent Bytes column for the category All Heap Allocations. The text is a little small in the screenshot, but it says the app is using 9.64 MB of memory, which is good for an iOS or Mac app. The Allocations instrument does not record OpenGL/ES or Metal texture memory. If your app allocates texture memory, your actual memory use will be higher than what Instruments reports. You may also want to click the checkbox in the Graph column to show the heap allocation totals in the graph.

The Allocations instrument has the following columns of data for each memory category:

Persistent Bytes, which is the amount of allocated memory that hasn’t been freed yet.
# Persistent, which is the number of memory allocations that haven’t been freed yet.
# Transient, which is the total number of memory allocations that have been freed.
Total Bytes, which is the total amount of allocated memory, including freed memory.
# Total, which is the total number of memory allocations, including freed memory. The # Total column should equal the sum of the # Persistent and # Transient columns.

Suppose your app makes 20 memory allocations of 1,000 bytes and frees the memory for 15 of the allocations. The Allocations instrument would report the following information:

Persistent Bytes: 5,000
# Persistent: 5
# Transient: 15
Total Bytes: 20,000
# Total: 20

Allocations Instrument Call Tree

If your app allocates a high amount of memory, the first thing you’ll want to know is where your code is making the big memory allocations. To find where you’re allocating memory, switch to the call tree view. In the jump bar, click on Statistics and choose Call Trees to switch to the call tree view.

When you switch to the call tree view, you should configure Instruments to make finding your code easier in the call tree view. Click the Call Tree button in the bottom bar to open a popover with a series of checkboxes.

Select the Invert Call Tree and Hide System Libraries checkboxes. Inverting the call tree brings the memory allocating functions to the top. Hiding the system libraries hides Apple’s code, leaving your code in the call tree view.

After selecting the checkboxes, the call tree view should show your code.

Option-clicking a disclosure triangle next to a function in the call tree view expands its subtree so you don’t have to be constantly clicking disclosure triangles. Option-clicking again on the expanded disclosure triangle contracts the subtree.

For each function in the call tree, the Allocations instrument shows the bytes used and the allocation count. The bytes used is represented both as an amount and a percentage of the total memory allocated. Here’s the listing from the Framesetter.init listing:

308.86 KB   1.2%    42

The line says the Framesetter.init function and any functions in its subtree allocated 308.86 KB of memory, which is 1.2% percent of the total allocated memory. This function and any functions in its subtree made 42 allocations.

The subtrees keep Instruments from telling you the exact amount of memory each function allocates. Inverting the call tree reduces the subtree, which makes the listing for a function in an inverted call tree the closest approximation to the amount of memory that function is allocating. If you set an inspection range in the graph, the listing reflects the amount of memory allocated in the inspection range’s time interval.

main Listing

For most Mac and iOS apps, the first listing in the call tree view is the main function. This function is going to have a high amount of bytes used and allocations. If you don’t invert the call tree, the main function will show 100% bytes used. That’s because main is the starting point of your app. Every function in your app will have main in its call stack so every memory allocation your app makes will have main in its call stack.

When trying to figure out where your app allocates memory, don’t worry about the main listing. The main function doesn’t do much in most Mac and iOS apps. There isn’t much you can do in the main function to reduce your app’s memory usage.

Source View

Double-clicking a function in the call tree view shows the source view. For the Allocations instrument, the source view shows you the lines of code that allocated the memory along with the percentage of memory allocated. The percentage is relative to the function. If a line of code says 80%, it means that line of code allocated 80% of the memory the function allocated.

Notice how each listing in the source view has an icon with an exclamation point. Clicking that icon shows the heaviest call stack for that line of code.

Leaks Instrument Results

Now it’s time to look at the Leaks instrument. The graph will tell you if you have any memory leaks in your app. A memory leak occurs when your app allocates memory and never frees the memory. The following screenshot shows an example of the graph for the Leaks instrument:

The screenshot shows six memory leak checks. For the first four checks, Leaks found no memory leaks so it leaves a green icon with a checkmark on the graph. On the fifth check, Leaks found some leaks so it leaves a red icon with an X on the graph. On the last check Leaks found no new leaks so it leaves a gray icon with a dash on the graph.

Leaks Instrument Call Tree

If Instruments finds memory leaks in your app, the next step is to find where the leaks are occurring in your code. The steps to do this are the same as for the Allocations instrument: switch to the call tree view by using the jump bar and select the Invert Call Tree and Hide System Libraries checkboxes from the Call Tree popover in the bottom bar. Selecting the checkboxes will limit the call tree listing to functions you wrote.

For each function in the call tree listing, Instruments shows the bytes used and the number of leaks. Like the Allocations instrument, the bytes used is represented both as an amount and a percentage, but in the Leaks instrument the percentage represents the percentage of total leaked memory. Here’s the listing for the malloc function in the screenshot.

19.12 KB    98.0%   92

The listing says the malloc function has 92 memory leaks totaling 19.12 KB. The leaks totaled 98% of the leaked memory in the app.

Double-click any functions in your call tree view to see where the leaked memory is allocated.

The fact that a function allocates leaked memory doesn’t necessarily mean the function is responsible for leaking the memory. But it’s a good place to start looking for the source of the leak.

Troubleshooting

This section contains fixes for common issues people run into with Instruments.

The Call Tree View Shows Memory Addresses

A problem many people run into when using Instruments is the call tree view shows memory addresses instead of the names of functions. The usual cause of this problem is Instruments being unable to locate the dSYM file that contains the project’s debugging symbols. The function names are in the debugging symbols.

To locate the dSYM file, choose File > Symbols in Instruments. A sheet like the following will open:

Select your app from the left side of the sheet. Click the Locate button to find the dSYM file.

The dSYM file is usually located in the same directory as the app bundle of the release version of your project. The app bundle is in the Derived Data folder. You can check the location of your Derived Data folder in Xcode by choosing File > Project Settings, but the Derived Data folder is usually in the following folder:

/Users/YourUsername/Library/Developer/Xcode/DerivedData

There will be a folder for your project in the Derived Data folder with a long string of random characters after the project name. The release version of the project is in the following folder:

.../DerivedData/ProjectName/Build/Products/Release

An iOS project will have the name Release-iphoneos instead of Release.

The Source View Doesn’t Show Source Code

You double-click a function in the call tree view, expecting to see that function’s code in the source view. But instead you see either assembly language code or a blank view that says Unavailable.

The usual cause of this issue is double-clicking a function you didn’t write. Examples of functions you didn’t write include functions from Apple’s frameworks and default initializers in your structs and classes. Make sure you double-click a function you wrote.

Summary

I want to summarize the most important points to take away from this article. These points apply to most instruments, not just the Leaks and Allocations instruments.

Choose Product > Profile in Xcode to profile your app.
Use the call tree view to find problem areas in your code.
Select the Invert Call Tree and Hide System Libraries checkboxes to find your code in the call tree view.
Option-click the disclosure triangles in the call tree view to minimize the amount of clicking you have to do.
Double-click a function in the call tree view to see statistics on specific lines of code.
Don’t worry about the listing for the main function in the call tree view. You have no control over main.

Do you want to learn more about Instruments?

Profiling Swift Apps page

Learning iOS Development

Wed, 05 Dec 2018 20:01:09 +0000

Last update: December 2025

A lot of people are interested in developing iOS apps but don’t know where to get started. Getting started questions come up frequently on Reddit’s iOS programming forum and the same answers pop up over and over again so I’m compiling them here.

Hacking with Swift

Hacking with Swift is a website that teaches Swift and iOS development. They have a free book that teaches the Swift language by building 39 projects. The site also has free 100 day iOS development courses, one that uses UIKit and one that uses SwiftUI.

When you finish the free book, Hacking with Swift has books you can buy to delve deeper into Swift and iOS development.

Stanford’s CS193P Course

If you have experience developing software on other platforms and want to quickly get up to speed developing iOS apps, Stanford has their CS193P course on iOS development available for free.

Keep in mind that this is a college course at Stanford that students take in one quarter. This course moves at a much faster pace than Hacking with Swift.

Angela Yu’s Udemy Course

If you prefer video learning and want something that moves at a slower pace than the Stanford course, check out Angela Yu’s iOS App Development Bootcamp. This course is not free, but it gets recommended a lot when people ask how to get started with iOS development.

Kodeco

When you go through one or more of the resources I mentioned earlier in this article, you’ll be ready for Kodeco. Kodeco has a vast collection of text and video tutorials on iOS development as well as books to buy. They are moving towards more video tutorials. The tutorials tend to focus on one specific topic, such as table views. After you learn the basics of iOS development and want to go deeper on a specific topic, check out Kodeco

Checking API Availability in Swift

Tue, 27 Nov 2018 20:51:49 +0000

In a previous article I explained how to set up your Xcode projects to support older versions of iOS and macOS. But I didn’t explain how to use new functions on new iOS and macOS versions and older functions on older systems.

Swift provides two statements to help support older OS versions: #available and @available.

#available

The #available keyword works with if and guard statements. Supply an operating system version version, and the code inside the if block runs only on suitable systems.

Let’s work through an example. Apple added the NSPersistentContainer class in iOS 10 and macOS 10.12 to simplify setting up the Core Data stack. You would like to use NSPersistentContainer on systems that have the class and not use it on older versions of iOS and macOS. The following example shows how to use NSPersistentContainer on systems running iOS 10 and later:

if #available (iOS 10, *) {
	// Use NSPersistentContainer to set up Core Data stack
} else {
  // Set up the Core Data stack the old way
}

The asterisk as the second argument to #available tells the compiler to require the minimum deployment target for other platforms. The minimum deployment target is the earliest version of iOS or macOS that can run your app.

The following code shows how to use NSPersistentContainer on systems running macOS 10.12 and later:

if #available (OSX 10.12, *) {
	// Use NSPersistentContainer to set up Core Data stack
} else {
  // Set up the Core Data stack the old way
}

Apple added the #available statement before changing the name of the Mac operating system from OS X to macOS.

If you have some code that should run only on later versions of iOS or macOS, use #available with a guard statement. By using #available with guard, your code can exit if it’s running on an older version of iOS or macOS.

guard #available(iOS 11, *) else {
  // Exit on iOS 10 and earlier
  return
}
// Call the functions added in iOS 11.

@available

Place @available in front of a function or class to make that function or class available only on supported iOS and Mac versions. Like #available, supply an operating system version. The following code shows how to use @available with a function:

@available(iOS 12, *)
func myFunctionThatRequiresIOS12() {
    
}

The following code uses @available with a class:

@available(OSX 10.13, *) {
class MyHighSierraClass: NSObject {
    
}

Supporting Older Versions of iOS and macOS

Mon, 19 Nov 2018 19:53:05 +0000

I recently answered a question from someone who wanted to know what version of Xcode and Swift to use to develop an app for iOS 9 and another question from someone who wanted to know what version of Xcode to use to develop an app to run on macOS 10.7. Answering what is basically the same question twice in one week is a sign that people are not sure how to make their apps run on older versions of iOS and macOS. This article should clarify things.

Short version: use the latest version of Xcode and set the deployment target for the project to the earliest version of iOS or macOS you want to support.

What Version of Xcode Should You Use?

You should use the most recent version of Xcode that will run on your Mac. Currently the most recent version of Xcode is version 10.1, which runs on macOS 10.13 and 10.14. The site Xcode Releases has a list of every Xcode release and the operating system requirements.

Why should you use the most recent Xcode version? Each version of Xcode ships with a SDK (Software Development Kit) for iOS and macOS. Xcode 10 ships with the iOS 12 and macOS 10.14 SDKs. The SDK contains the features your app can use. By using the latest SDK, your app can take advantage of the features Apple added in the latest version of iOS and macOS. The macOS 10.14 SDK includes support for dark mode. If you want your Mac app to look good in dark mode, you have to build it with the 10.14 SDK.

Some of you are asking the following question: if I use the iOS 12 SDK, will my app run only on devices running iOS 12? No. The SDK determines the latest features your app can take advantage of. The deployment target determines the operating systems that can run your app. If you use the iOS 12 SDK and set the deployment target to iOS 10, your app can run on devices running iOS 10, 11, and 12 (and future versions of iOS too).

What Version of Swift Should You Use?

All versions of Swift support the same operating systems: iOS 7 and later and macOS 10.9 and later. You can use the latest version of Swift and support older versions of iOS and macOS.

The main reason to use an older version of Swift is if you are using any non-Apple libraries or frameworks that were built with an older version of Swift. In that situation you should use the same version of Swift that was used to build the library or framework.

Setting the Deployment Target for Your Project

To make your app run on older versions of iOS and macOS, change the deployment target for your project by selecting the project file from the left side of the project window.

The deployment target is the earliest version of iOS or macOS that can run your app. Set the deployment target to the earliest version of iOS or macOS that you want to support. Keep in mind that Apple makes supporting earlier versions of iOS and macOS difficult. Most app developers support the most recent operating system version and the previous version, such as supporting iOS 11 and 12.

Setting the deployment target is mandatory for your app to run on older versions of iOS and macOS, but it’s not the only thing you have to do. You have to make sure your app isn’t using any technologies or calling any code that Apple introduced in a later iOS or macOS version. As an example Apple added a document browser class, UIDocumentBrowserViewController, in iOS 11 to simplify creating and opening documents. If your app uses the new document browser, it will run only on iOS 11 and later. Setting the deployment target to iOS 9 isn’t going to make your document-based app run on iOS 9 or 10.

Summary

Use the latest version of Xcode so your app can take advantage of the latest features in iOS and macOS. Change the deployment target for your project to support earlier versions of iOS and macOS, making sure not to use any new technologies or functions.

Swift Optionals

Thu, 15 Nov 2018 05:04:41 +0000

I saw in a talk by Paul Hudson at NSSpain 2018 that optionals are what people learning Swift struggle with the most. That makes optionals a good topic to cover on a site called Swift Dev Journal.

What Is an Optional?

An optional is a data type for a variable where the variable either exists or doesn’t exist, in which case it’s nil. Pretty much anything in Swift can be an optional, including integers, strings, views, structs, and classes. Add ? to a variable’s type to make that variable an optional.

var description: String?

In this example if there’s a description, the description variable contains a string with the description. If there’s no description, description is nil.

Implicitly Unwrapped Optionals

A special kind of optional is an implicitly unwrapped optional. An implicitly unwrapped optional assumes the value of the optional is not nil. If the value is nil and you access that value in your app, the app crashes. Add ! to a variable’s type to make that variable an implicitly unwrapped optional.

@IBOutlet var textView: UITextView!

Outlets are the most common use of implicitly unwrapped optionals. You can assume your outlets are not nil after loading a storyboard or xib file. If you forget to connect the outlets, your app will crash, but in that case, you want the app to crash so you can connect the outlets.

Outside of outlets you should avoid using implicitly unwrapped optionals because they’re not safe. Every implicitly unwrapped optional in your code is a potential crash.

Force Unwrapping

Force unwrapping an optional uses the value without checking if it’s nil. Add ! to an optional variable to force unwrap it.

print(description!)

Don’t force unwrap implicitly unwrapped optionals. They’re already unwrapped. If you add ! to an implicitly unwrapped optional, you’ll get a compiler error.

Force unwrapping is dangerous. In this example if description is nil, the app will crash.

You should avoid force unwrapping optionals because force unwrapping isn’t safe. Every optional you force unwrap is a potential crash.

Safely Unwrapping with if-let and guard

When writing Swift code, you often end up checking if an optional value is not nil, then assigning a constant with something from the optional value. Suppose you wanted to get a view controller’s parent (which is an optional because a view controller may not have a parent) and do something with it, you could write code like the following:

if parent != nil {
  let parentViewController = parent
  // Do something with parentViewController
}

But this code is a bit tedious to write. Swift provides the if-let statement to combine the nil check and the assignment into one statement.

if let parentViewController = parent {
  // Do something with parentViewController
}

If parent is nil, the code inside the if block won’t execute.

Another way to safely unwrap an optional is to use a guard statement. The guard statement lets you exit quickly if the optional value is nil.

guard let parentViewController = parent else { 
  return 
}
// Do something with parentViewController

Make a Simple Mac App in Swift

Mon, 12 Nov 2018 05:03:05 +0000

I have seen some questions from people looking for information on developing Mac apps in Swift. To help people who want to write Mac apps in Swift, I’ve written this tutorial that walks you through creating a simple Mac app in Swift. The app generates and displays a random number when you click a button.

Create the Project

The first step is to open Xcode and create a project. Choose File > New > Project to create a new Xcode project. The New Project Assistant opens.

The project is a Mac app so click the macOS button at the top of the window. Select Cocoa App. Click the Next button to move on to the next step.

Enter the name of the project in the Product Name text field.

Select None from the Team menu. You need a team only if you’re going to submit an app to the Mac App Store. This project is not going on the Mac App Store.

Enter either your name or a company name in the Organization Name text field. Use the organization name to fill out the organization identifier, which takes the form com.OrganizationName.

Choose Swift from the Language menu.

Select the Use Storyboards checkbox. Deselect the Create Document-Based Application and Use Core Data checkboxes. This project is not a document-based application and does not use Core Data.

Xcode 11 Update

Xcode 11 replaced the Use Storyboards checkbox with an Interface menu. Choose Storyboard from the menu.

This project does not use unit tests or UI tests so you can deselect the Include Unit Tests and Include UI Tests checkboxes if you want.

Click the Next button. Choose a location to save your project. Click the Create button to finish making the project.

After creating the project you should see a list of the project’s files on the left side of the project window. You’re going to work with two files in this tutorial: Main.storyboard, which contains the user interface, and ViewController.swift, which contains the source code for the view controller.

Build the User Interface

Let’s start by building the user interface. Select the Main.storyboard file to open it. The user interface for this project has two items: a label to display the random number and a button to click to generate the random number.

Drag a label and a button from the object library to the view controller scene. If you’re using Xcode 10 or later, the button to access the object library is on the right side of the project window toolbar.

If you’re using an earlier version of Xcode, the object library is in the lower right portion of the project window.

Configure the Label

The label you added can use some configuration so it looks better. You’re going to perform the following configurations:

Change the label’s text
Center the text
Increase the size of the label’s text
Resize the label

To configure the label select it in the canvas and open the attributes inspector.

Enter the text 0 in the Title text field. Center the text from the Alignment segmented control by clicking the second button.

Use the steppers (up and down arrows) next to the Font text field to increase the size of the text to 36 points.

Resize the label if you need to so it’s big enough to show two digits with the larger text. Select the label in the canvas to resize the label.

Configure the Button

The button has the text Button. Change the text to Show Number from the attributes inspector or by double-clicking the button in the canvas. The user interface should look similar to the following when you’re finished:

Create Outlets

Now that you created the user interface, you want to access the label and button in your code. Create outlets so you can do this. Outlets are variables in your code that hold items in your project’s storyboards and xib files.

The first step to creating an outlet is to open the assistant editor so the storyboard and source code file are both open. Choose View > Assistant Editor > Show Assistant Editor to open the assistant editor. Open the file Main.storyboard in one editor and the file ViewController.swift in the other editor.

Select the button in the storyboard. Hold down the Control key and drag to the ViewController.swift file. When the mouse cursor is inside the definition of the ViewController class, you should see the text Insert Outlet or Action. When you see that text you can let go of the mouse button. A popover like the following will open:

Enter a name for the outlet in the Name text field. Notice how Xcode knows the type is NSButton. Click the Connect button to finish creating the outlet.

Repeat the process for the label. Select it and control-drag to the ViewController.swift file. This time you’ll notice the type is NSTextField instead of NSButton. Labels in Mac apps are text fields and not their own special class like they are in iOS. After creating the outlets, the code should look similar to the following:

Make sure the outlets are connected with filled-in circles like they are on the left side of the screenshot. If the outlets aren’t connected, the app will crash when you try to access the outlets.

Create an Action

When someone clicks the button, the app should generate a random number and display it. Create an action so you can add the code to generate the random number and display it. An action is a function that is connected to an item in your user interface. Clicking on the item calls the action.

Creating an action is similar to creating an outlet. Select the button and control-drag to the ViewController.swift file. When you see the Insert Outlet or Action, let go of the mouse button to open a popover.

The connection is now an action. Enter the name in the Name text field. The Type combo box determines the data type of the action’s sender. For this project all you care about is the button was clicked so you can stick with Any, which can be any type. If you needed to access the button’s title, you would choose NSButton from the Type combo box. Click the Connect button to create the action, which should look similar to the following:

Make sure the action is connected on the left side of the editor or nothing will happen when you click the button.

Write the Code

Now it’s time to write some code. There are two functions you need to write. The first function generates a random number. The second function updates the label with the random number.

The following function generates a random number:

func generateRandomNumber() -> Int {
  let minValue = 0
  let maxValue = 99
  return Int.random(in: minValue...maxValue)
}

The first two lines of code define the range for the random number, 0–99. The last line of code generates a random integer in the range I defined. I could have reduced this function to one line,

return Int.random(in: 0...99)

But I didn’t want to hardcode the values so I created the two constants for the minimum and maximum values.

The following function updates the label with the generated random number:

func updateLabel(value: Int) {
  valueLabel.stringValue = value.description
}

The code sets the label’s text to the value of the number I passed to the function. The description property holds the string representation of the number so it can be displayed in the label.

The last thing to do is to call the two functions in the showRandomNumber action. If you don’t add the code to the action, nothing will happen when you click the button.

@IBAction func showRandomNumber(_ sender: Any) {
  let randomValue = generateRandomNumber()
  updateLabel(value: randomValue)
}

Conclusion

Click the Play button in the project window toolbar to build and run the project. When you click the Show Number button, a new number appears above the button.

I have the project on GitHub if you run into any problems.

If you’re looking to build on this project, I have a few suggestions.

Try creating the project with a xib file instead of a storyboard. Deselect the Use Storyboards checkbox when creating the project. You’ll be using the AppDelegate.swift file instead of ViewController.swift.
Add arguments to the generateRandomNumber function for the minimum and maximum values so you can specify the minimum and maximum values for the random number generator.
Add text fields to the user interface so people can specify the minimum and maximum values for the random number generator.

Core Data Code Generation

Tue, 06 Nov 2018 05:01:18 +0000

Starting with Xcode 8, you can let Xcode generate the code for your Core Data entities. Access an entity’s code generation options by selecting the entity and opening the data model inspector.

The Codegen menu is where you specify the code generation for the entity. There are three code generation options.

Choosing Manual/None tells Xcode not to generate code for the entity. You must create the class for the entity by creating a new file or by choosing Editor > Create NSManagedObject Subclass.
Choosing Class Definition tells Xcode to create the entity’s class files when you build the project.
Choosing Category/Extension tells Xcode to create a Swift class extension for the entity when you build the project. The class extension has accessors for the entity’s attributes.

Where are the Source Code Files?

If you choose Class Definition or Category/Extension from the Codegen menu, you’ll notice there are no source code files for the entities in the project navigator. Where are the files?

The source code files are in the project’s derived data location. You’re not meant to access and edit the source code files Xcode creates for your Core Data entities. The point of Xcode creating the files is to automatically update the files when you make changes to the data model.

What do you do if you want to add methods to your Core Data entities? Create Swift class extension files for your entities and add your methods there.

Duplicate Classes

When you create a new Xcode project that uses Core Data, the code generation is initially set to Class Definition. If you manually add class files for your entities, your project won’t build because you have two versions of each class, the one you manually created and the one Xcode creates. This issue can be tough to find because you can’t see the Xcode-created class files in the project navigator.

There are two ways to deal with the duplicate class problem. The first way is to remove the class files you added to the project and let Xcode create the classes for you. The second way is to switch to manual code generation by choosing Manual/None from the Codegen menu.

Which Code Generation Option Should You Choose?

Choose manual code generation if you’re using version control in your project. By writing the entity’s code yourself, you can track the changes in your version control system and go back if you make a mistake.

Choose the Class Definition code generation option if you don’t want to worry about keeping the data model and code in sync. When you make changes to the data model, you don’t have to worry about updating the code if you choose Class Definition. Xcode updates the code for you.

Choose the Category/Extension code generation option if you need more control over the class hierarchy. If you choose the Class Definition code generation option or choose Editor > Create NSManagedObject Subclass to generate your classes manually, Xcode assumes the entity and class hierarchies are the same. If you want a different class hierarchy for your data model, choose the Category/Extension code generation option.

Creating Document-Based iOS Apps Part 2: Make a Text Editor

Fri, 26 Oct 2018 04:13:07 +0000

In Part 1 of this tutorial, you learned the concepts of creating an iOS document-based app. In Part 2 of the tutorial, you will put those concepts into practice by building a simple rich text editor. You must be running Xcode 9 or later to follow along, as Apple added the document-based app project template in Xcode 9.

If you haven’t read Part 1 of the tutorial, you should do so before you read this tutorial. The first part explains some higher-level concepts that this part glosses over.

Create The Project

Let’s start by creating the project. Open Xcode and choose File > New > Project. The New Project Assistant opens.

Click the iOS button at the top of the window. Select Document Based App. Click the Next button to move to the next step.

Name the project in the Product Name text field. Choose your iOS developer profile from the Team menu. Enter your company name or your name in the Organization Name text field. Use that name to fill in the organization identifier. The organization identifier usually takes the form com.CompanyName. This site is called Swift Dev Journal so choose Swift from the Language menu. Click the Next button to choose a location to save the project.

If you look at the project navigator on the left side of the project window, you should see Swift files for the document browser view controller, the document view controller, and the document. You should also see a storyboard. Those are the files you are going to use in the project.

Build the User Interface

Now that you created the project, the next step is to build the user interface, which mostly consists of a text view. Select the Main.storyboard file from the project navigator to open it. The storyboard has two scenes: one for the document browser view controller and one for the document view controller. You’re going to lay out the user interface in the document view controller. Apple creates the document browser user interface for you.

You’re going to perform the following tasks to build the user interface:

Remove most of the user interface in the document view controller.
Add a text view to the document view controller scene.
Configure the text view so you’re editing rich text instead of plain text.
Add constraints to the Done button so it’s centered on all iOS devices.
Add constraints to the text view so the text isn’t on the edges of the screen.
Create an outlet for the text view and connect the outlet so you can access the text view in your code.

Remove Most of the Existing User Interface

The document view controller looks like the following initially:

Keep the Done button so people can go back to the document browser when they’re finished editing a document. Move the Done button out of the stack view and place it at the top center of the screen. After moving the Done button out of the stack view, delete the stack view.

Add a Text View

To add a text view, select the text view element from the object library and drag it to the document view controller. If you can’t find the object library, remember that Apple moved the object library in Xcode 10. The button to open the object library is on the right side of the toolbar.

Place the text view below the Done button and have it fill the rest of the view. The document view controller scene should look similar to the following screenshot:

Configure the Text View

Select the text view and open the attributes inspector. Choose Attributed from the Text menu so the text view shows rich text instead of plain text. You can also remove the Lorem ipsum text if you want. Select the Allows Editing Attributes checkbox.

Make sure the Editable checkbox is also selected. A text editor that doesn’t let you edit text is not much fun to use.

Add Constraints for the Done Button

Add a constraint to center the Done button horizontally at the top of the view so that it’s centered on all iOS devices. Select the Done button. Click the Add Constraints button to open a popover to add an alignment constraint.

Select the Horizontally in Container checkbox. Click the Add 1 Constraint button at the bottom of the popover to add the constraint.

Add Constraints for the Text View

The container for the text view fills the entire view by default. This means the text you type is pushed against the left edge of the text view. Add some constraints to add some padding.

Select the text view. Click the Add Constraints button to open a popover to add new constraints.

Click the four struts surrounding the square at the top of the popover to add some spacing for the text view. Enter spacing values in the text fields. I added 16 points of spacing to the left and right edges and added 10 points of spacing for the top and bottom edges. Click the Add 4 Constraints button at the bottom of the popover to finish adding the constraints.

Create and Connect the Text View Outlet

To be able to access the text view in your code, you must add an outlet for the text view in your code and connect the text view in the storyboard to the outlet. Add the following property to the DocumentViewController class to create an outlet:

@IBOutlet weak var textView: UITextView!

Now connect the text view in the storyboard to this outlet. Open the assistant editor (choose View > Assistant Editor > Show Assistant Editor) so the source code file and storyboard are both open. Select the text view in the storyboard, hold down the Control key, and drag it to the outlet to make the connection.

Creating the Document

If you run the project at this point, you’ll notice that tapping the Create Document button does nothing. To create a new document when someone taps the Create Document button, you must do the following:

Add an empty document file to your project with the same file extension as your document.
Edit the document type in Xcode.
Add code to load the empty document in the document browser view controller.

If you were creating a new document type, you would also have to add an exported UTI for the document. But this app saves RTF files so you don’t need to add an exported UTI.

Add an Empty Document File

Fortunately Xcode has a RTF file template to use as the empty document file. To add an empty RTF file to the project, choose File > New > File. The Rich Text File is in the Resource section under iOS.

Name the file. I named the file New Document. You can choose a different name if you want, but remember the name.

Edit the Document Type

Enter RTF in the Name text field.
Enter public.rtf in the Types text field. public.rtf is the standard UTI (Uniform Type Identifier) for RTF files.
Set the CFBundleTypeRole key’s value to Editor so people will be able to edit RTF files in the text editor.
Set the LSHandlerRank key’s value to Alternate. This will let people edit RTF files in the app without forcing them to use the app to edit all RTF files.

Load the Empty Document

Open the DocumentBrowserViewController.swift file and go to the didRequestDocumentCreationWithHandler function. You should see the following line of code at the start of the function:

let newDocumentURL: URL? = nil

Change this line of code so it retrieves the empty document file you added to the project.

let newDocumentURL = Bundle.main.url(forResource: "New Document", 
  withExtension: "rtf")

Make sure the name of the resource matches the name of the empty document file you added to the project. If the names don’t match, the new document won’t be created.

There’s one more change to make to the code.

if newDocumentURL != nil {
	importHandler(newDocumentURL, .move)
} else {
	importHandler(nil, .none)
}

There’s a problem with the code inside the if block.

importHandler(newDocumentURL, .move)

If you keep this code, your app will crash the second time you create a document because the empty document file was moved out of the app bundle when you created the first document. When you try to load the empty document file the second time, the app can’t find it in the app bundle, causing a crash. You must copy the file from the app bundle to create multiple documents without crashing.

importHandler(newDocumentURL, .copy)

Update Document When Text View Changes

The user interface consisting mainly of a text view has a potential problem. If you wait for the person using the app to stop editing to update the document contents and save, you won’t be updating and saving until the person taps the Done button. You run the risk of losing data.

For this project you’re going to update the document’s data to match the text view contents when the text view’s contents change. This behavior is not the most efficient, but it minimizes the risk of losing data.

Start by adding the following property to the Document class that stores the document’s text:

var text: NSAttributedString? = nil

Now it’s time to write some code to update the document when the text view’s contents change. Add the following function to the document view controller:

func textViewDidChange(_ textView: UITextView) {
  document?.text = textView.attributedText
	document?.updateChangeCount(.done)
}

When the contents of the text view change, change the document’s text property so it holds the text view’s contents. Update the change count for the document to trigger autosaving for the document.

Save the Document

To save the document, implement the function contentsForType in the Document class.

override func contents(forType typeName: String) throws -> Any {
	guard let textToSave = text else { return Data() }
	return NSKeyedArchiver.archivedData(withRootObject: textToSave)
}

The first line of code makes sure the text property is not nil before saving. The second line grabs the document’s text and calls the NSKeyedArchiver method archivedData to save the text.

Open the Document

To open the document, start by implementing the load function in the Document class.

override func load(fromContents contents: Any, 
  ofType typeName: String?) throws {
    
	// Load your document from contents
  guard let data = contents as? Data else { return }
  guard let fileContents = NSKeyedUnarchiver.unarchiveObject(
    with: data) as? NSAttributedString else { return }
  text = fileContents
}

The first line of code in the function makes sure the file has suitable data to load. The second line loads the document text from the file by calling the NSKeyedUnarchiver method unarchiveObject. The last line sets the document’s text property to the text you loaded from the file.

Now you must set the text view’s contents to the document’s text you just loaded. The document view controller’s viewDidAppear method has a block of code to open the file. If the open is successful, set the text view’s attributed text to the document’s text.

document?.open(completionHandler: { (success) in
  if success {
  	// Display the content of the document.
    self.textView.attributedText = self.document?.text
  } else {
    // Make sure to handle the failed import appropriately.
  }
})

Conclusion

I put this project on GitHub for you to look at if you run into problems. If you look at the GitHub project, you can see how to scroll the text view when the onscreen keyboard appears and disappears. Scrolling the text view is important for a text editor so the keyboard doesn’t block what you’re typing, but scrolling the text view doesn’t involve document-based apps so I didn’t write about it in the article.

Creating Document-Based iOS Apps Part 1

Thu, 25 Oct 2018 18:59:00 +0000

iOS support for document-based apps opens up new categories of apps for you to develop. Want to develop screenwriting software? A video editing app? A level editor for a game? By making a document-based app you can make iOS versions of these types of apps.

In iOS 11 Apple simplified creating and opening documents, making it easier for developers to create document-based apps. Unfortunately Apple did not update their documentation to reflect these changes.

This article helps document those changes. To make things more manageable, I divided it into two parts. This part covers the higher-level concepts. The second part walks you through creating a rich text editor.

What Are Document-Based Apps?

Document-based apps let people create documents that they can share. Examples of document-based apps include text editors, spreadsheets, and image editors. The document is the text, spreadsheet, or image that you’re editing.

Document-based apps are more common on Macs than on iOS. But by learning how to create document-based apps in iOS, you can build powerful apps that used to require a Mac to run.

The Classes

There are two classes to study to develop document-based apps. The first class is UIDocumentBrowserViewController, which controls the document browser.

The document browser is where someone using your app creates and opens documents. The following screenshot shows what the document browser looks like initially:

The second class is UIDocument, which represents the document. When you create a document-based app project, Xcode includes a UIDocument subclass for you. You use this class to store any data properties related to your document.

Your Tasks

You have to perform the following tasks to develop an iOS document-based app:

Create a document-based app project in Xcode.
Set up your document type to create new documents.
Implement delegate functions in the document browser view controller to handle creating new documents and selecting documents from the document browser.
Save the document.
Open the document.

It looks like a lot of work to make a document-based app, but there’s much less code to write than you think. In the project I wrote for the second part of this article, I wrote less than ten lines of code to implement the delegate functions, save the document, and open the document. Apple’s document-based app project template does a lot of work for you.

Creating a Document-Based App Project in Xcode

Creating a document-based app project in Xcode gives you a document browser view controller, a view controller for the document, and a UIDocument subclass.

Setting Up Your Document Type to Create New Documents

There’s a surprising amount of work involved in creating a new document when someone taps the Create Document button in the document browser. You must perform the following tasks:

Set up the document type.
Supply a blank file to create documents.

If you are creating a brand new document type, you must also add an exported UTI for the document. UTI stands for Uniform Type Identifier. A UTI uniquely identifies a file type. The exported UTI lets the operating system and other apps know about the existence of your file type.

Set Up the Document Type

When you create a document-based app project, Xcode creates a document type for you. Use Xcode’s project editor to configure the document type. Start by selecting your project from the project navigator to open the project editor and selecting your app target from the left side of the project editor. Click the Info button at the top of the project editor to access the Document Types section.

Enter the UTIs for your document type in the Types text field. If you are creating a new file type, the UTI should take the form com.CompanyName.FileType. If you are using an existing file type, supply its UTI. Suppose you are developing a plain text editor. The UTI for your document would be public.plain-text. Apple has a list of system-declared UTIs, but it’s not being actively maintained.

The Document Types section has a subsection called Additional document type properties. You must add two document type properties. The first property has the key CFBundleTypeRole. Its type is String. Its value should be Editor if you want people to edit your documents.

The second property has the key LSHandlerRank. Its type is String. For new file types, the value should be Owner because your app owns the file type. For existing file types the value should be Alternate. The alternate handler rank allows your app to edit files of the file type but keeps your app from being the default app to edit files of that type. Suppose you’re making an image editor that lets people edit PNG files. By making your app the alternate editor, you can edit PNG files in your app without forcing people to use your app to edit all PNG files.

Supply a Blank File to Create Documents

You need to create a blank file when someone chooses to create a new document. Otherwise tapping the Create Document button does nothing. The easiest way to create a blank file is to add an empty file to your project whose file extension matches the name of your document’s file extension. Your app will load this file from the app bundle when someone creates a new document.

Add an Exported UTI

If you are creating a new document type, you must add an exported UTI for the document type. The exported UTI lets the operating system and other apps know of the existence of your new file type. Exported UTIs are in the same section as document types in Xcode’s project editor.

Enter your document’s UTI in the Identifier text field. The UTI should take the form com.CompanyName.FileType. Enter any additional UTIs your exported UTI supports in the Conforms To text field. If your document saves its contents in a file package instead of a single file, you would add the UTI com.apple.package in the Conforms To text field.

You also must add an additional exported UTI property. The key is UTTypeTagSpecification, and its type is Dictionary. You must create two dictionary items. The first item has the key public.mime-type. Its type is String. Its value is the UTI for your document type.

The second item has the key public.filename-extension. Its type is String. Its value is the file extension for your document. Do not add a dot in front of the file extension.

Document Browser Delegate Functions

Handling creating a new document requires you to implement two delegate functions in the document browser view controller: didRequestDocumentCreationWithHandler and didImportDocumentAt. You load the empty document file from the app bundle in didRequestDocumentCreationWithHandler when someone creates a new document.

Fortunately the document browser view controller in Xcode’s document-based app project template provides basic versions of these two delegate functions for you. Unless you’re doing something like Pages, where creating a document opens a template chooser, you won’t have to write much code. In the project for the second part of this article, I had to add one line of code in didRequestDocumentCreationWithHandler and change one other line of code.

Handling selecting a document from the document browser requires you to implement the delegate function didPickDocumentURLs in the document browser view controller. The document browser view controller provides a basic version for you to use. In the project for the second part of this article, I didn’t have to change anything in didPickDocumentURLs.

Saving Documents

To save a document you must override the contentsOfType function in the UIDocument subclass. Xcode’s document-based app project template provides an empty function for you to fill in. In most cases you’ll use the NSKeyedArchiver class to save the document data.

Opening Documents

To open a document you must override the load function in the UIDocument subclass. Xcode’s document-based app project template provides an empty function for you to fill in. In most cases you’ll use the NSKeyedUnarchiver class to read the document data from the file.

On to Part 2

Part 2

Crashing with Swift Optionals

Thu, 18 Oct 2018 17:53:35 +0000

If you have done any iOS or Mac programming in Swift, you have probably had your app crash with the following message in Xcode’s debugger:

Fatal error: Unexpectedly found nil while unwrapping an Optional value

If you don’t understand this error message, keep reading. In this article you’ll learn what this error message means, common causes of the message, and ways to fix your code so your app stops crashing.

What Does the Message Mean?

Before I can tell you what the error message means, I need to explain Swift optionals. An optional is a data type for a variable where the variable either exists or doesn’t exist, in which case it’s nil. Pretty much anything in Swift can be an optional, including integers, strings, arrays, table views, structs, and classes. The following code shows an example of declaring an optional variable:

var description: String?

A special kind of optional is an implicitly unwrapped optional. While an optional can either exist or not exist, an implicitly unwrapped optional must exist. If an implicitly unwrapped optional is nil and you attempt to use it, the app crashes. The following code shows an example of using an implicitly unwrapped optional:

print(description!)

If description exists, the code will print the description, but if description is nil, the code crashes.

Now to answer the question in the section heading. The error message Fatal error: Unexpectedly found nil while unwrapping an Optional value is saying the app is implicitly unwrapping a nil optional value. The error is similar to accessing a nil pointer in C, C++, or Objective-C.

What Causes the Error?

The general cause of the error is having an implicitly unwrapped optional that’s nil. But you’re looking for specific causes. I can think of three common sources of implicitly unwrapped optionals that are nil.

The first common source is forgetting to connect the outlets for your user interface elements. Outlets in Interface Builder are usually declared as implicitly unwrapped optionals because you can assume the outlet is going to exist after loading the storyboard or xib file. But if you forget to connect the outlet, the outlet is nil and your app will crash when it tries to use the outlet. The following screenshot shows what a disconnected outlet looks like in Xcode:

The disconnected outlet is the circle above Line 14. A connected outlet has a filled-in circle.

The second common source is using as! to downcast to a specific type. Look at the following code to instantiate a view controller from a storyboard:

let documentViewController = storyBoard.instantiateViewController(
	withIdentifier: "DocumentViewController") 
  as! DocumentViewController

This code will crash in any of the following situations:

I forgot to give the view controller an identifier in the storyboard.
The identifier in the storyboard doesn’t match the string in the code.
I forgot to set the class of the view controller in the storyboard.

With implicitly unwrapped optionals it doesn’t take much to cause a crash.

The last common source is using implicitly unwrapped optionals in your code. If you see an exclamation point at the end of any of your variable names, you have a potential crash in your code. What doesn’t help matters is when you have a compiler syntax error in your code involving optionals, Xcode’s suggested fix is to make an implicitly unwrapped optional. Following Xcode’s advice makes your code more likely to crash.

How Do You Fix the Error?

The general fix to avoid these crashes is to avoid using implicitly unwrapped optionals. The following techniques will help you avoid crashes caused by implicitly unwrapped optionals:

Connect your user interface elements to the outlets in your code.
Use as? instead of as! when downcasting.
Use if let or guard statements to safely unwrap your optionals.
Use the ?? operator to provide a default value in case the optional value is nil.

To connect your user interface elements to your outlets, open Xcode’s assistant editor so your source code file and your storyboard or xib file are both open. Select the user interface element in the storyboard or xib file. Hold the Control key down and drag to the outlet in your code to make the connection.

I can demonstrate the last two techniques by fixing the earlier example of instantiating a view controller from the storyboard. Using an if let statement and as? to downcast is enough to fix the code. The following code makes sure the view controller has been instantiated, then presents the view controller:

if let documentViewController = storyBoard.instantiateViewController(
  withIdentifier: "DocumentViewController") 
  as? DocumentViewController {
    
  present(documentViewController, animated: true, completion: nil)
}

Now if I forgot to give the view controller an identifier or misspelled the name of the identifier, the app won’t crash. The app won’t present the view controller, but at least there won’t be a crash.

Putting Your Xcode Project on GitHub, Bitbucket, or GitLab

Tue, 09 Oct 2018 19:14:38 +0000

GitHub, Bitbucket, and GitLab simplify working on projects with other people. These sites also provide online backup for your projects in case your computer is damaged or stolen. Starting with Xcode 10 (Xcode 9 for GitHub) you can put your Xcode projects on GitHub, BitBucket, or GitLab without leaving Xcode. This article shows you how.

Prerequisites

You must have an account on GitHub, Bitbucket, or GitLab. Xcode can’t create an online account for you. If you don’t have an account, go to the site you want to use and create an account. GitHub is the most popular place to host projects online, but Bitbucket and GitLab are also fine to use.

Your Xcode project must be under version control. The easiest way to place your project under version control is to select the checkbox to create a git repository when you create the project.

If you have an existing Xcode project that is not under version control, choose Source Control > New Git Repository in Xcode to create a git repository for the project.

Adding Your Account to Xcode

Adding your GitHub, Bitbucket, or GitLab account to Xcode isn’t mandatory, but doing so makes things a little easier when you put your project online. Open Xcode’s Account preferences by choosing Xcode > Preferences and clicking the Accounts button in the preference window’s toolbar.

Click the Add button to add an account.

Choose GitHub to add a GitHub account, Bitbucket Cloud to add a Bitbucket account, and GitLab.com to add a GitLab account. Xcode will ask you for your username and password.

UPDATE

GitHub requires you to create a personal access token and use that instead of a password for authentication.

Putting the Project Online

You’re going to use Xcode’s source control navigator to put the project online. Open the source control navigator by choosing View > Navigators > Show Source Control Navigator or by pressing Cmd–2.

Newer versions of Xcode have Changes and Repositories buttons at the top of the source control navigator. Click the Repositories button to show the branches in the git repository.

Creating a remote branch is how you put your project online. Select the Remotes folder, control-click, and choose Create Remote. A sheet like the following will open:

Choose your account from the Account menu. If you did not add your account to Xcode, choose Add an account to add your account. Choosing an account will set the Owner menu to the username for your account.

Xcode sets the repository name to the name of the project for you, but you can change it if you want. Xcode has problems with uppercase letters in Bitbucket repository names. Use all lowercase letters if you’re using Bitbucket. If you would like to enter a more detailed description of the project, use the Description text view.

Choose the visibility for your project online: private or public.

The remote name is initially set to origin. If you want a different name, enter it in the text field. The most common reason to change the name is hosting your project on multiple sites. Suppose you want to host your project on both GitHub and Bitbucket. To avoid confusion it would make sense to name the GitHub remote github and the Bitbucket remote bitbucket.

Click the Create button to create the remote branch and place your Xcode project online.

Where to Go from Here?

Now that your Xcode project is online, you’ll have the option to push your changes online every time you commit.

Work on your Xcode project in a local branch. Push your changes to move them to the remote branch on GitHub, Bitbucket, or GitLab.

If you want other people to work on your project with you, they can clone your project by choosing Source Control > Clone in Xcode.

Swift Dev Journal

Composing Parsers with the swift-parsing Library

Creating a parser

Parsing example

Parsing the change ID

Parsing the author

Parsing the timestamp

Parsing the change description

Composing a change parser

Measure App Launch Time with Instruments

Do you want to learn more about Instruments?

Add an Open Recent Menu to a SwiftUI app

Using NSDocumentController to track recent items

Initial version of the Open Recent menu

Create the @Observable class

Add the @Observable class to the Menu

Supporting SwiftUI Sidebar Selection with Multiple Data Types

Creating the enum

Using the enum for the selection

Adding the .tag modifier

Introduction to the Swift Subprocess Package

Launching a program

Launching a program from a Mac app bundle

Passing arguments

Setting the working directory

Output options

Returning error messages

Supplying input

Check if a program ran successfully

A more complex example

Related reading

Reducing the Number of .sheet Modifiers in Your SwiftUI Views

Creating an enum for the sheets

Creating a sheet view

Creating a focused value

Showing a sheet

Add @State property

Add .focusedSceneValue modifier

Set the sheet to show

Add .sheet modifier

Related reading

Find the SwiftUI Views that Update the Most Using Instruments

Profile your app

Find the views that update the most

Find what causes a view to update

Do you want to learn more about the SwiftUI instrument?

Swift-Parsing Library Introduction

Example

Parsing the Change ID

Parsing the Author

Parsing the Timestamp

Parsing the Description

Skipping the Remaining Text

Find the Slow Spots in Your Code with the CPU Profiler Instrument

Launching Instruments

Profiling Your App

Reading the Profiling Data

Finding Your Code in the Call Tree

Finding the Slow Code

Viewing the Slow Code

Do you want to learn more about Instruments?

Show an Alert from a Menu Item in a SwiftUI Mac App

Apply .alert to the Content View

NSAlert

Open Document-like Windows Using SwiftUI WindowGroup

Setting up the Window Group

Opening the Window

Sample Project

Instruments Flame Graph Introduction

Showing the Flame Graph

Reading the Flame Graph

Finding Your Code in the Flame Graph

Navigating the Flame Graph

Zooming the Flame Graph

Summary

Acknowledgments

Do you want to learn more about Instruments?

Using Jujutsu Version Control in Xcode Projects

Adding Jujutsu to an Xcode Project with a Git Repo

Putting the Jujutsu Repo on GitHub

Using `NSDocumentController` to track recent items

Create the `@Observable` class

Add the `@Observable` class to the Menu

Add `@State` property

Add `.focusedSceneValue` modifier

Add `.sheet` modifier