1. The Checkbox

Written by Nick Bonatsakis

In the introduction, you learned about what Catalyst is, how it works and the initial considerations you’ll make when using it to bring your app to the Mac.

In this chapter, you’re going to get your first look at the sample app that you’ll be interacting with for the remainder of this book. Once you familiarize yourself with the basic functionality and architecture, you’ll take your first steps toward bringing the app to macOS.

By the end of this chapter, you’ll have learned:

• The basic functionality and architecture of the sample app.
• The Xcode project changes needed to get your iOS app running on macOS.
• Which features Catalyst gives you for free when running on the Mac.
• Which features don’t work as well out-of-the-box.

It’s time to get comfortable with the sample app that’ll be your companion for the remainder of your Catalytic journey.

The sample app: Journalyst

Meet the last journaling app you’ll ever need; it’s called Journalyst and it has been designed from the ground-up to be the best way to chronicle your daily adventures. Start by taking it for a quick test drive.

Open Journalyst.xcodeproj from the starter project for this chapter in Xcode and then build and run.

You should see the main journal entry list screen:

Here you can see all the journal entries you’ve created as well as an add button in the upper right that will add a new entry when tapped. Try tapping the add button a few times to see new entries get added to the list. Next, tap on any entry in the list to dive into the journal entry detail screen.

At the top of this screen, there is a text area where you can add the textual content for this entry. Below the text area, you’ll find a button that you can tap to add images. Finally, there is a Share button in the upper-right that, when tapped, will bring up the standard iOS activity view, allowing you to share the content. Spend a few moments tapping on the various controls, and then get ready to move on to the code.

In the Xcode project, expand the Journalyst group in the navigation pane. Once you do so, you’ll see a handful of groups that house the various architectural components that make up the app, alongside the standard files you’d expect in a new Xcode project.

Here’s a brief breakdown of the files:

Models

• Entry: A class that represents a single journal entry in the app.
• EntryDataSource: A datasource class that works with table view to update its data.

View Controllers

• MainTableViewController: A table view controller that renders the journal entries list, which is the main screen of the app.
• EntryTableViewController: A table view controller that renders the detail screen for a single journal entry.

Views

• EntryTableViewCell: A table view cell that represents a single journal entry on the main screen.
• ImageCollectionViewCell: A collection view cell that renders an image attachment in the image area of the single journal entry screen.

Take some time to dig into each of the above files so you can get a feel for the overall structure and data flow. The app is not overly complex, but it will serve as a great starting point for taking you through all the aspects of Catalyst.

Once you feel comfortable with the project, it’s time to take your first steps towards Mac-ifying your first app.

The iPad checkbox

“Wait, what? I thought we were migrating this app to run on the Mac. What’s this iPad business about?” You may have noticed that the Journalyst app is currently configured and designed to run on iPhone only. Well, it turns out that an iPhone app, even a great one, doesn’t translate well to the much larger screen of a Mac.

iPhone apps are optimized for single-window use, where you see one screen at a time on a very confined display size. They aren’t typically concerned with things like drag-and-drop, multi-tasking, split views, keyboard shortcuts and all manner of other functionality commonly found in Mac apps.

iPad apps, on the other hand, are concerned with the above features, run on comparable display sizes, and thus have far more in common with Mac apps. For this reason, Apple wisely decided that, for an iOS app to run on macOS, it must be capable of running on iPad. So if you were hoping to take your iPhone-only app straight to macOS, you’re in for a bit more work than you may have expected. This book will guide you through the process of both bringing your iPhone app to iPad, and then bringing that iPad app to the Mac.

Apple states that the first step in making a great Mac app using Catalyst is making a great iPad app. The more your app is designed to be a good citizen on the iPad, the easier it will be to bring it to macOS using Catalyst. So before you can check the “Mac” checkbox, you’ll have to check the “iPad” checkbox.

In the Xcode project, click on the top-level Journalyst entry in the navigation pane, select the main app target, and click on the General tab. You should see three checkboxes within the Deployment Info section, only “iPhone” is currently activated.

Check the iPad checkbox. Just like that, you’ve added support for iPad. Select an iPad simulator as the run target then build and run to have a look at the fruits of your labors.

And there it is! The Journalyst app running on the iPad… Looks great right? Well, maybe not so much.

Through the magic of auto-layout, nothing looks broken per se, and app features still work. However, what you see is an inflated version of the iPhone app. It doesn’t look or feel like a first-class iPad citizen. You can do much better than this, and in the chapters that follow, you will.

Be aware that some features are downright broken when running on iPad. If you try to activate anything that would bring up an action sheet, such as adding an image or sharing an entry, the app will crash. You’ll learn why this is the case, and how to fix it in the next chapter.

But this chapter is all about instant gratification via checkboxes, so put your dreams of creating the next hit iPad app to the side for now and prepare to see the app running on the Mac.

The Mac checkbox

And now the checkbox you’ve been waiting for! Back in the General tab of the Journalist target settings, go ahead and check the “Mac” checkbox.

Note: Since Catalyst is only supported on macOS 10.15 or higher, if you are on an older version of macOS, this checkbox will be disabled. Make sure you are using macOS 10.15 or higher and Xcode 11 or higher before proceeding.

You’ll notice that, this time, unlike when you checked the “iPad” checkbox, Xcode prompts you to make some changes to the project. Allow it to do so, and the following changes will be made:

• An entitlement for App Sandbox is added to the Journalyst.entitlements file. Apps that are distributed on the Mac App Store must incorporate sandboxing, which you’ll learn more about in a later chapter that covers distributing your Catalyst app.
• A new run destination for My Mac is added to the project so that you can run the app from Xcode.
• Incompatible frameworks, app extensions and other embedded content are excluded from the Mac build. In this case, there aren’t any yet.

Once you’ve enabled the Mac checkbox and accepted project changes, you’ll notice a new dropdown to the right of “Mac”. Go ahead and click it, then select “Optimize Interface for Mac”.

From Apple’s Xcode release notes on the option:

When bringing iPad apps to macOS, you can now use the Optimize Interface for Mac target setting to use native macOS controls and Mac resolution

Since your ultimate goal is to make an app that looks and feels like a first-class macOS app when running on the Mac, you want the interface to be optimized accordingly.

Go to the Signing & Capabilities tab of the Journalyst target settings and under Signing, you’ll notice you have bundle ids for iOS and macOS platforms. Under macOS platform, you’ll notice Use iOS Bundle Identifier is checked.

Go ahead and uncheck the Use iOS Bundle Identifier checkbox. Then, create a macOS Bundle identifier as maccatalyst.com.raywenderlich.Journalyst.

The last thing you’ll need to do before running the Mac app is to specify code signing information. This step isn’t necessary when running the iOS app on simulators, but in this case, your Mac is a real device, so the bundle needs to be signed.

Go ahead and select a team. Make sure Automatically Manage Signing is enabled, and Xcode will take care of the rest.

Finally, change the run destination to My Mac, build and run, then bask in the glory that is your first Catalyst app!

Much like when you ran the app on iPad for the first time, the basic functionality is there after applying almost zero effort, but the app in its current form leaves much to be desired. Still, Catalyst gives you a whole lot of Mac goodness for free, so poke around, and you’ll find that your Mac app already has the following features:

• A basic Mac menu bar.
• Support for trackpad, mouse and keyboard input.
• Support for window resizing and full-screen display.
• Mac-style scroll bars.
• Copy-and-paste support.
• Basic drag-and-drop support.
• Support for system Touch Bar controls.

But it’s not all rainbows and checkboxes at this point — there’s still a lot of work you’ll need to do to make this app a first-class Mac experience. Some of the more notable features that are currently missing are:

• Multi-window support.
• A better navigation structure, given the larger screen size (a split view would do nicely here).
• Extended drag-and-drop support for things like dragging images into journal entries.
• Extended keyboard support for things like shortcuts.
• Extended mouse support for custom contextual menus.
• A Mac-style preferences window for app settings.
• A better look and feel for the app that aligns it more with what you commonly see on macOS.
• Better support for the menu bar, toolbar and the touch bar that go beyond what you get out-of-the-box.

That list might look daunting, but the remainder of this book will guide you through the process of implementing all of these features and more. The rest of the chapters in Section 1 will cover the features that you’ll add to turn Journalyst into a great iPad app. Section 2 will then cover the process of turning your great iPad app into an even greater Mac app. Rounding things out, Section 3 will walk you through the finer points of packaging and distributing your new Mac app.

Key points

• Journalyst is a basic journaling app that you’ll be improving throughout this book.
• Before you can make a great Mac app using Catalyst, you need to make a great iPad app.
• Catalyst gives you plenty of Mac functionality for free.
• To make a truly great Mac app using Catalyst, you need to go above and beyond what comes out-of-the-box, covered above.

Where to go from here?

In this chapter, you became familiar with Journalyst, the sample app you’ll update throughout the rest of this book as you learn how to bring apps from iPhone to iPad, and then to the Mac. You took the first steps along this path by configuring the app to run on both iPad and Mac by changing the Xcode project configuration. Finally, you learned about which features Catalyst provides out of the box and which ones require additional effort to enable.