Getting Started with Xcode

This entry is part 2 of 2 in the series Developing In The Dark

I briefly-explained the role of Xcode in development in my post about teaching myself how to code, but I didn’t explain how much of a beast it is to tackle with Voiceover. Xcode is incredibly powerful, capable,  and mostly-accessible, which is why I was able to create Zanagrams using it.

A great philosopher once said, “With great power comes great Voiceover complexity.”

No specific person has ever claimed these words as their own, but word on the street is that their name rhymes with “Tach Zidwell”.

While I’d love to credit those words to their owner, the important takeaway here is that this holds true for Xcode: It’s very complex, especially when you’re new to programming and don’t have an understanding for the coding-related terms used throughout the app. As I move-into explaining Xcode, I’m going to assume that you’ve read my article about my own path to becoming a programmer, and that you know how to use Voiceover(VO) and basic Mac-based keyboard commands, are familiar with the role of Xcode in development, and the terms Swift and SwiftUI.


Each time you open Xcode, you’ll be presented with a “Welcome to Xcode” screen that allows you to:

1: Create a new project

2: Clone an existing project

3: Open an existing project or file

I’m not going to explain these three options, as the only one that pertains to a budding developer is the first one, and creating a new project is explained in the Hacking With Swift tutorials I mentioned in my previous article.

Once you’ve created your first project, you’ll notice that, at the highest levels, Xcode is split into three main groups: Navigator, Editor, and Inspector. I’m only going to explain the Navigator and Editor groups because the Inspector group is for analyzing a project’s accessibility. However, if you’re developing with accessibility in-mind and testing your projects on physical devices with the appropriate accessibility features enabled, you won’t need this group.

Please note: From here-on, any keys listed in parentheses are referring to the hotkey to quickly-access whichever Xcode element precedes the parentheses.

1: Navigator Group

Upon interacting with the Navigator group, you’ll notice a series of nine radio buttons, each of which represent one subsection of the Navigator group. Selecting any of these buttons will display that subsection of the Navigator group. So, let’s go through them one-by-one.

1A: Project


After selecting the “Project” radio button, you’ll find two important elements below the rest of the radio buttons: The Project Navigator Table and a button labeled “Menu”.

First is the Project Navigator Table(CMD + 1), which is where you can view all of the files in your project, add new ones(CMD + N), and delete old ones(CMD + delete). Again, this article is focused on navigating Xcode, so I’m not going to explain the default files you’ll find in a new project, as the aforementioned Hacking With Swift tutorials explain them as-needed. The important thing to remember about using the Project Navigator Table is that you do not actually select a file to view it in the Editor Group; all you need to do is focus Voiceover on the file you’d like to edit, then leave the table. To jump directly to the source editor from here, you can press ‘control + `’.

              If you want to edit the name of a file, focus Voiceover on it and press ‘enter’. After typing your new file name, press ‘enter’ again to confirm, or press ‘escape’ to stop editing the name and revert to the original. Either way, be sure to retain the file extension, like “.swift”, or “.json”. Removing the file extension will lead to errors at build-time. Addressing those errors will be covered in section ‘1E’.

Note: Voiceover tends to be a bit finnicky when editing file names, and may stop speaking. To correct this, just press ‘escape’ and attempt to edit the name again.

Secondly, the “Menu” button is one you’ll want to familiarize yourself with once you start working on your own projects, as it allows you to keep your files well-organized. As your projects expand, so will the number of files. You can open this menu by pressing the button, at which point yo8u’ll be presented with the options below:

Note: Choosing any of these options adds an element of the corresponding type to your Project Navigator Table.

1: File

              Just as it sounds, this adds a new file to your project, which you can also do by pressing command + N. Either way, your new file will appear just after the file that Voiceover was focused on prior to the creation of the new file.

2: Group

              Groups are my best friend when it comes to project organization. They present as expandable folders whose contents can be viewed from within the Project Navigator Table. Upon creation, groups are always empty, but you can use Voiceover relocate files to a group. As with editing file names, this can be very buggy with Voiceover, so mileage may very. I recommend creating groups often, then creating new files inside of your groups, rather then relocating them later.

3: Group without folder

              In your Project Navigator Table, these groups will function the same as any other group. Where you’ll notice a difference is when you examine your project inside of Finder. There you’ll find that your project’s files aren’t as organized are they appear in the Project Navigator Table. Personally, I never use this option.

4: Folder

In theory, folders serve the same function as groups, but they display their contained files differently. To view files contained within a folder, focus Voiceover on the folder, then attempt to navigate to the Source Editor just as you would when editing a file. You’ll find that, instead of any code, the files contained inside the folder are displayed here. So, choosing between groups and folders all comes-down to personal preference.

1B: Source Control

              This section of the Project Navigator is dedicated to version control, both local(on your device) and remote(on a server or external hard drive ). This is a more-intermediate topic, and it’s explained beautifully here. As you’re first learning, I wouldn’t worry about it. Instead, revisit this subject once you’ve begun working on your own projects. In the meantime, it’s a good call to store backups of your projects both locally and remotely, if possible. This just ensures that you won’t lose all of your work if your project is corrupted, and instead will only have to make-up the ground you lost between your last backup and when your project was corrupted.

1C: Symbols

The first two elements you’ll notice in this section are the two radio buttons: Hierarchical and Flat, which change the way information is presented in the Symbol Navigator Table(CMD + 3) just below them. The idea behind this table is that it grants you a secondary (and sometimes faster) way of navigating to various functions and types throughout your projects.

              Navigation inside this table is very-similar to navigating the Project Navigator Table, though the different structs and classes in your project will be organized alphabetically here. As you navigate through the table and bring the Voiceover focus to one of your types, you can press the right arrow to expand that type and show all of the methods of that type. Navigate to the one you’re interested in, leave the VO focus on it, then navigate to the Source Editor to view the code inside that method.

1D: Find

Personally, I’ve never used this section of the Navigator Group; I find the Project Navigator Table and the Symbol Navigator Table to be sufficient in-terms of navigating my projects. However, know that you can always use this section to find specific snippets of code throughout your project. Similarly to any search engine, you’ll notice a series of filters you can apply to your searches, and any matching results will be displayed in the Find Navigator Table(CMD + 4). To navigate to one of the results in the editor , be sure to orient the VO focus on that result before leaving the table.

1E: Issues

              I spend a lot of time jumping back-and-forth between my code and this section, and you will too. When you attempt to run or build your project and Xcode finds syntax errors in your code, it will alert you that it failed, then display clues as to what went wrong in the Issues Navigator Table(CMD + 5). For your essay, these messages are called “exceptions”, and you’ll have to decipher their meaning each time you come across the. As you work to do this, situating the VO focus over a given error before leaving the table will present the line of code it was referring to in the Source Editor.

              Occasionally, you’ll also notice warnings inside of the Issue Navigator Table. While warnings won’t prevent you from building or running your project, they typically reference deprecated Swift APIs, and will eventually present as issues, rather than warnings. So, though they don’t have to be addressed immediately, it’s a good ide4a to fix them when you have the time.

1F: Advanced sections

Testing, Debugging, Breakpoints, and Reports are all more-advanced topics that are covered in the later days of 100 Days of SwiftUI. Unfortunately, delving into each of these sections would lead us down separate rabbit holes. So, I’m going to skip covering them in this article, because you will not need them early-on, and we already have more than enough to cover.

2: Editor Group

              The Editor group is where you’ll bring your project to life. Here you’ll write code, track-down bugs, alter project settings, and basically do all of your actual work.

As you expand your knowledge of Swift and begin experimenting with different file types, or even editing different settings for the identity of your project, you’ll notice that The Editor Group presents differently under different circumstances, relevant to the type of file you’re interacting with. In the interest of informing beginners, I’m only going to cover how the Editor Group presents when viewing “.swift” files, as that’s all you’ll be using in the early days of development.

              Upon interacting with the Editor Group, you’ll find either three or four more groups that are all on the same level in the Editor Group Voiceover hierarchy, and I’ll cover them from left-to-right:

2A: Jum Bar Group

Interacting with this group will present different display options for your Editor Group. From what I can tell, all of these changes seem to be visual, as I don’t notice any differences when navigating with Voiceover upon changing these settings.

2B: File Editor Group

The next group you’ll find displays the name of the file you’re viewing. Every Swift project contains a “ContentView.swift” file, so I’ll be using that name as an example throughout this explanation. To reiterate, whichever file Voiceover was focused on in the Project Navigator Table is what will be displayed here.

2B1:      Nested within this group, you’ll find one more “Jump Bar” group and a scroll area. This Jump Bar group allows you to shift the Voiceover focus to sources of warnings and errors within your Source Editor, which I’ll explain in the next section. You’ll find that you don’t use the “Jump Bar” often, as the Voiceover rotor inside the Source Editor contains faster ways of completing the same tasks.

              2B2: When you interact with the scroll area, you’ll find four more groups contained within, but you only need to worry about one: the Source Editor(CMD + `). This area contains the actual code contained within whatever file you’re viewing, and is where you’ll edit the code contained within.

2C: Another “Jump Bar” Group!

In contrast to Similarly to the other “Jump Bar” group on this level in the Editor Group, this group is one you’ll occasionally use. It contains other Source Editors that you have open. You can think of these extra Source Editors like tabs in Safari; you can interact with them to find another instance of the very File Editor Group we’re discussing now.

2D: Debug Bar

Personally, I don’t find this area to be useful with Voiceover, aside from and one very-important setting that presents as a checkbox: “Hide Debug Area”. For now, be sure to leave this unchecked, as it presents another group at the top-level of the Editor Group Voiceover hierarchy that I’ll cover in the next section. Other than that, feel free to ignore it until you’re farther along in your journey and you begin to experiment with Xcode’s debugging features.

2E: Debug Area

Though this section has a similar name to the one I just covered, I used this one very-often because it contains another good friend of mine, the “console”. Though the term “print() statements” may not mean anything to you yet, you’ll learn about them early-on as you learn Swift. All you need to remember is that the arguments you pass to print() calls will appear here. Personally, that’s how I track-down all of the bugs in my apps, as Xcode’s debugging tools aren’t very Voiceover-friendly in my opinion.


                             We’ve just covered the navigating the essential parts of Xcode with Voiceover, which is all you’ll need to get started with the 100 Days of SwiftUI course. With that in-mind, know that Xcode is capable of much, much more, and that it’s mostly-accessible with Voiceover. You’ll find that even tackling the basics will keep you busy for quite some time. Just remember that it’s okay to take a break when you get frustrated, and that coming-back later with a fresh mind will often lead to a solution. I’m excited to be helping other visually-impaired people create accessible apps, and I can’t wait to check-out your future projects. As always, feel free to reach-out with any questions you have or other topics you’d like me to cover.

Series Navigation<< How I Taught Myself How to Code