Working with the Source Editor - Building RoadTrip - iOS 6 Application Development For Dummies (2013)

iOS 6 Application Development For Dummies (2013)

Part II. Building RoadTrip

Chapter 7. Working with the Source Editor

In This Chapter

arrow Using the Standard source editor to add code

arrow Fixing syntax errors as you code

arrow Getting the help you need from the documentation and other forms of help

arrow Searching and finding symbols

If you’ve been reading through the chapters in order, by now you may be beginning to hate me because I haven’t shown you much in the way of coding yet. Isn’t developing apps about coding? Well, yes and no.

Think of painting a room in your house. So much time and effort needs to be spent in the prep work because you know that if you prepare correctly, the job will take you less time in the long run by saving you a lot of rework.

That’s what the chapters in this book have been doing so far — preparing you to code by showing you the ins and outs of Xcode and the UIKit framework. At this point, all you have left to do is find out about the Xcode source editor and a few other features. After that, you’ll be ready to code, and take my word for it, you will.

In this chapter, I tell you how to navigate the files in your project using the Jump bar and the navigators, as well as how to work with the source editor to enter code. And for when you are confused, or simply just curious, I explain how to access the documentation and Xcode’s Help system. This chapter finishes the explanation on how to use Xcode, and you’ll know what you need to know to make it easy to start coding in the next chapter.

Navigating in the Xcode Source Editors

In previous chapters, I give you quite a bit of information about the Xcode Workspace, albeit primarily focusing on storyboards. I mention the Assistant as well, and in this chapter, I want to extend that knowledge and describe most of the rest of the tasks you need to be able to do in Xcode.

As you’ve seen, most development work in Xcode is done in the Editor area, the main area that’s always visible within the Workspace window. The Editor area can also be further configured, with the Standard editor pane always shown, as well as an optional Assistant pane that shows related content. (If you select an interface [.h] header file, the Assistant pane shows the corresponding implementation [.m] code file, and vice versa; I don’t talk about the Version pane, but showing that area is also an option.) I use the term pane (Standard editor pane and Assistant pane) to refer to certain configurations, even though Apple doesn’t use that term. I do this to distinguish between the Editor area configuration (the Standard editor isn’t actually an editor at all, but simply a single pane configuration in the editor area) and the built-in editors — an editor operates in an Editor area. The main editors are the following:

image Source editor: You use this editor to write and edit your source code, as well as to set and enable (or disable, for that matter) breakpoints as well as to control program execution.

image Project editor: With this editor, you view and edit project and target settings, such as build options, target architectures, and code signing characteristics.

image Interface Builder: Here, you graphically create and edit user interface files in storyboards and .xib files.

The editor you use is determined by what you have selected in the Project navigator. An editor pane appears for that (selected) item in the Editor area.

So far, you’ve worked primarily in the Interface Builder editor, but when you code, you do the bulk of your work in the source editor in the Standard editor pane, with some forays, as needed, in the Assistant editor pane and an occasional excursion into the Utility area as well.

As described earlier in the book, you use the View selector in the Workspace toolbar to hide or show the Navigator, Debug, and Utility areas. (To review the Xcode workspace landscape, see Chapter 2.) If you like, you can hide the other areas and see just the source editor (and perhaps the Assistant).

imageFigure 7-1 shows the Project navigator. Because I selected RTMasterViewController.m, you see the source editor displaying that file in the Standard editor pane. (If you were to select one of the storyboard files in the Project navigator, you’d see Interface Builder as your editor of choice; that’s the editor I highlight in Chapter 5.) In Figure 7-1, I also selected the Assistant in the Editor selector and split the panes using the split controls (the next to the last “+” icon on the right in the Jump bar).

image Notice that when I selected the Assistant, the RTMasterViewController.h file opened. That’s because the Assistant editor pane automatically (depending how you have set it — see the next section) shows the related content for whatever I select in the Project navigator so that you can edit both easily. You then see RTMasterViewController.m (the implementation code file) in the Standard source editor pane and RTMasterViewController.h (the header file) in the Assistant editor pane. Clicking the split controls opens a second pane as well.

The Standard editor pane (the left editor pane, or the top one if you have a horizontal split) is the one that’s affected by changing your selection in the Project navigator.

imageThe interface (.h) header file defines the class’s interface by specifying the following:

image The class declaration (and what it inherits from).

image Methods.

image Any instance variables (that is, variables defined in a class). Note that Apple has suggested moving away from declaring instance variables in the interface and moving those declarations to the implementation file to keep them more private, as I explain in Chapter 6.


Figure 7-1: The source editor with Standard and Assistant editor panes.

The implementation (.m) code file, on the other hand, contains the code for the class, which includes each method definition. It also can contain the instance variable declarations. See Chapter 6 for more on this topic as well.

imageBy default, the Assistant editor pane appears to the right of the source editor pane. To change the orientation of the Assistant editor pane to the source editor pane, choose View⇒Assistant Layout and then choose a layout. If the header file doesn’t appear for you, navigate to it using the Jump bar, as explained in the next section.

Using the Jump bar

A Jump bar appears at the top of each Editor area pane to provide an alternative way to navigate through the files and symbols in your project. You can use the Jump bar to go directly to items at any level in the Workspace.

A Jump bar is an interactive, hierarchical mechanism for browsing items in your workspace. Each editor area includes a Jump bar, as do Interface Builder and the documentation organizer. The configuration and behavior of each Jump bar is customized for the context in which it appears.

imageThe darker Jump bar you see in Figure 7-1 indicates that the Standard editor pane is the active pane.

The Standard editor Jump bar

The Standard editor Jump bar has the basic configuration, which includes the following:

image image Context-related items: Click the Related Items menu (represented by an icon showing a cluster of tiny rectangles on the far left side) to see additional selections relevant to the current context, such as recently opened files or the interface (.h) header file for an implementation (.m) code file you’re editing.

image image Previous and Next buttons: These are the left- and right-arrow buttons on the left side of the Jump bar. You use these to step back and forth through your navigation history.

image A hierarchical path menu: This menu shows the same structure that you see in the Project navigator, down to individual files and the symbols inside the files. The path you would see in the source editor in the Standard editor pane is shown in Figure 7-2.

The hierarchical path menu lets you quickly choose a file. For example, in Figure 7-3, I get an overview of all the RoadTrip files when I select the RoadTrip project in the hierarchical path menu.

Selecting the last item in the hierarchical path menu provides a list of all the symbols in that file, as shown in Figure 7-4.


Figure 7-2: The hierarchal path menu in the Standard editor pane.


Figure 7-3: A file hierarchy.


Figure 7-4: A tour of RTMasterViewCon-troller.m.

Another example of a Jump bar with the basic configuration is in the Documentation Organizer. It simply allows you to select documents from installed libraries. Other Jump bars have more components.

The Assistant modes and the Jump bar

When you use the Assistant, you’ll find that the Jump bar differs somewhat from the Jump bar of the Standard editor. The Assistant’s Jump bar has two modes: Tracking (or Automatic) mode and Manual mode.

image Tracking mode: The default behavior for the Assistant is to display the counterpart of the file displayed in the Standard editor pane. That is, if you’ve opened an implementation file, Assistant displays the corresponding header file, and vice versa. You can choose any of several other possible criteria to be used by the Assistant with the help of the Assistant pop-up menu (the first item in the path shown in the Jump bar above the Assistant editor). As you can see in Figure 7-5, the choices offered depend on the type of file being edited (a source file, for example, as shown, or the storyboard).

image Manual mode: You select the file to display in the Assistant pane on your own, rather than have the Assistant choose for you. (As mentioned previously, you can also split the Assistant editor pane to create multiple assistant editors.)

imageHold down the Option key when selecting an item in the Project navigator to open the Assistant and display that item in the Assistant editor pane.

If you have any questions about what something does, just position the mouse pointer above the icon; a tooltip appears to explain it.


Figure 7-5: Assistant options in the source editor.

Organizing your code using the #pragma mark statement

While you’re here, this is a good time to introduce the #pragma mark statement. If you look in the RTDetailViewController, you can see how this statement can be used to group things in your file; such statements are also displayed in the list of symbols.

You use the # pragma mark statement with a label (such as View life cycle or Animation) to add a category header in the Methods list so that you can identify and keep separate the methods that fit logically in the list.

For example, in the RTDetailViewController template, I added

#pragma mark - Managing the detail item

The first part of the statement (with a space and a dash) places a horizontal line in the Methods list. The second one places the text “View life cycle” in the Methods list.

This is a useful trick for finding code sections, organizing your code, and adding new code in the proper sections.

Using the Xcode Source Editor

The main tool you use to write code for an iPad application is the Xcode source editor, which appears as the Standard editor pane in the editor area on the right side of the Xcode Workspace window after you select a source code file in the Project navigator. It also appears as the Assistant editor in a second pane if you click the Assistant Editor button — the middle Editor selector button in the top-right corner of the Workspace window.

Apple has gone out of its way to make the source editor as useful as possible by including the following:

image Code completion: Code completion is a feature of the editor that shows symbols — arguments, placeholders, and suggested code — as you type statements. Code completion can be really useful, especially if you’re like me and forget exactly what the arguments are for a function. When code completion is active (as it is by default), Xcode uses the text you typed — as well as the context within which you typed it — to provide inline suggestions for completing what it thinks you’re going to type. You can accept inline suggestions by pressing Tab or Return. You can also see a pop-up list of suggestions by clicking an item in the suggestion list or clicking the up and down arrows to select an item. As you do so, the inline suggestion changes depending on what you selected. Press the Esc key, or Control+spacebar, to cancel a code completion operation. You can turn off code completion, or set options for code completion, by choosing Xcode⇒Preferences and clicking the Text Editing tab.

image Automatic indenting, formatting, and closing braces: As I explain in Chapter 3 in the section on preferences, the source editor indents the text you type according to rules you can set in the Text Editing preferences pane. It also uses fonts and colors for the various syntax elements (variables, constants, comments, and so on) according to the settings in the Fonts & Colors pane of Xcode preferences. As for closing braces, anytime you type an opening brace ({) and then press Return, Xcode automatically adds a closing brace (}) — unless you’ve deactivated the Automatically Insert Closing “}” option in the Text Editing preferences.

image Code folding in the Focus ribbon: With code folding, you can collapse code that you’re not working on and display only the code that requires your attention. You do this by clicking in the Focus ribbon column (see Figure 7-6) to the left of the code you want to hide (between the gutter, which displays line numbers and breakpoints, and the editor). A disclosure triangle appears, and clicking it hides or shows blocks of code.

image Opening a file in a separate window: Double-click the file in the Project navigator to open the file in a new window.


Figure 7-6: The Gutter and Focus ribbon.

Using Live Issues and Fix-it

The Apple LLVM compiler engine wants to be your best friend, so Live Issues continuously evaluates your code in the background and alerts you to coding mistakes. Before this feature came along, you had to build your app first, and trust me, this new way saves lots of time and effort.

But not only is Live Issues happy to point out your mistakes (like someone else I know, but I won’t go there), Fix-it will also offer (when it can) to fix the problem for you. Clicking the error displays the available Fix-its, such as correcting an assignment to a comparison, repairing a misspelled symbol, or appending a missing semicolon. With a single keyboard shortcut, you can instantly have the error repaired, and you can continue coding. Fix-it marks syntax errors with a red underline or a caret at the position of the error and with a symbol in the gutter.

For example, in Figure 7-7, the semicolon is missing after the [super viewDidLoad] statement. (Notice the error indicator — the red circle with exclamation point — in the Activity viewer, your Go To place for showing status messages, build progress, and errors.) Pressing Return will automatically fix this problem. This is a very useful feature and will cut down your debugging time significantly (especially if you actually use it).


Figure 7-7: Live Issues and Fix-it.

Compiler warnings

Although Xcode and the compiler working together are very good at giving you warnings and errors, sometimes they’re a little slow on the uptake when you actually get around to fixing the problem. So don’t be surprised by random warnings and errors, especially if the compiler for some reason can’t find the header file.

If you see a warning or error that you’re just sure you’ve fixed, you can click the Run button. Xcode and the compiler will reset, and the warning will go away. (Unless, of course, it was right all along and you hadn’t fixed the problem.)

The Issue navigator

imageThe Issue navigator is one of the navigators provided by Xcode. The error displayed in Figure 7-7, shown previously, also appears in the Issue navigator, as shown in Figure 7-8.


Figure 7-8: An error message displayed by the Issue navigator.

image To get to the Issue navigator, you select it in the Navigator selector bar.

If, in spite of Live Issues and Fix-it (or any other) warnings, you decide to compile the program, the Issue navigator will automatically launch for you.

The Issue navigator displays the error and warning messages generated in a Project or Workspace and is similar to the other navigators you’ve used so far.

When you select a warning or error in the Issue navigator, an editor displays the item with the issue, and if the error occurs in a source file, the issue message is placed on the line of code with the issue.

imagePlace the pointer over an issue message that ends with an ellipsis (which appears if the pane is too narrow to display the entire message) to get a complete description of the issue.

You can display issues by file or by type using the buttons on the Scope bar (refer to Figure 7-7), filter the issue list with the Filter bar, and even step through issues using the Issue stepper in the Jump bar. Use the Next and Previous buttons in the Jump bar to jump to the previous and next issues.

As you may recall from Chapter 3, I changed Xcode preferences to have the Issue navigator displayed and a sound played when a build fails.

Accessing Documentation

The ability to quickly access documentation is a major feature of Xcode, and one you’ll want to use regularly. If you have no idea how to do something, or how something works, you can often find the answer in the documentation.

Being able to figure out what’s going on will make your life easier. You saw that Xcode will complete your code for you, which is useful when you can’t quite remember the method signature and parameters, but what if you don’t even have a clue?

Or like many developers, you may find yourself wanting to dig deeper when it comes to a particular bit of code. That’s when you’ll really appreciate things like Xcode’s Quick Help, the Documentation pane in the Organizer window, header file access, the Help menu, and the Find tools. With these tools, you can quickly access the documentation for a particular class, method, or property.

Getting Xcode help

To see how easy it is to access the documentation, say that you’ve selected RTMasterViewController.h, as shown in the preceding Figure 7-8. (I’ve hidden the Assistant to have more room). What if you wanted to find out more about UITableViewController, the super class ofRTMasterViewController?

image imageThe Quick Help section of the Utility area provides documentation for a single symbol. (To see the Utility area, click the rightmost View selector button in the top-right corner of the Workspace window and select the second button in the Inspector selector bar.) In an editor, click anywhere in the symbol or select the entire symbol, as shown in Figure 7-9.

The Quick Help section of the Utility area shows a description of the symbol and provides links to more information. For example, you can click the UITableViewController Class Reference link near the bottom of the Quick Help section (refer to Figure 7-9) to bring up the class reference definition in the iOS Library Reference in the Documentation pane of the Organizer window, as shown in Figure 7-10. I use class references a lot!


Figure 7-9: Accessing the Quick Help section of the Utility area.


Figure 7-10: The class reference in the Organizer window.

With the Quick Help section open, information is available for three types of elements in your project, depending on your selection in the open editor:

image Symbols, in the source editor

image Interface objects, in Interface Builder

image Build settings, in the Project editor

It may be more convenient to use a Quick Help window if, for example, you prefer to work with the Utility area hidden. To do so, press Option and click one of the following in the open editor:

image Symbols, in the source editor

image Build settings, in the Project editor

As you can see in Figure 7-11, a Quick Help window appears with the pointer indicating the item you selected (in this case, the symbol UITableViewController):

imageIf you’re like me and want to go directly to the class reference, press Option and double-click the symbol instead.


Figure 7-11: The Quick Help window.

The Organizer window

You can have only one Organizer window (shown in Figure 7-12). You use the organizers in this window to manage all the development resources (projects, the Workspace, repositories, and so forth) on your local system in addition to using documentation, managing devices, and managing archives.

To display the Organizer window, click the Organizer button in the Workspace window’s toolbar (you’ll see it there on the far right) or choose Window⇒Organizer. The window includes five individual organizers, whose tasks I describe in the following list:

image Devices organizer: Lets you provision a device, manage your developer profile, install iOS on the device, and work with your application and its data. This organizer is present only if the iOS SDK is installed.

image Repositories organizer: Lets you create, view, and manage Git and Subversion repositories for your Workspace in a single consistent interface.

image Projects organizer: Lets you find, view, and manage an open project or Workspace, its derived data, and its snapshots.

image Archives organizer: Lets you view and manage build product archives resulting from your distribution scheme.

image Documentation organizer: Lets you find documentation and sample code and use them within Xcode. You can search and explore documentation and set bookmarks, and I suggest that you explore these topics further.

Each of these organizers includes task-oriented contextual help articles that you can view by choosing the Organizer and clicking in its content pane while pressing Control.

I explain a bit more about some of the other organizers as you use them in upcoming chapters.

The Help menu

The Help menu’s search field (in the Xcode menu bar) also lets you search Xcode Help, the Xcode User Guide, and Documentation and API Reference, all of which open the Documentation pane of the Organizer window. You can also choose Quick Help for Selected Item, which displays a Quick Help panel above the selected symbol in the editor.


Figure 7-12: The Organizer window.

Finding and Searching in Your Project

You’ll find that, as your classes get bigger, sometimes you’ll want to find a symbol or some other text in your project. Xcode provides a number of ways to do that.

Using the Find command to locate an item in a file

Need to track down a single symbol or all occurrences of a symbol in a file or class? You can easily locate what you’re looking for by choosing Edit⇒Find⇒Find or pressing Command Key+F, which opens a Find toolbar above the Editor pane to help you search the file in the editor.

For example, as shown in Figure 7-13, I entered viewDidLoad in the Find toolbar. Xcode found six instances of viewDidLoad in the source editor and highlighted them. (Admittedly, the first highlight is a tad darker.)

image You can jump from one instance to the next by pressing Command Key+G. Or you can use the Previous and Next buttons (left and right arrows) on the Find bar.


Figure 7-13: You can use Find to locate something in a file.

Click the Find pop-up menu on Find toolbar and choose Replace to do a file-level replace.

Click the magnifying glass in the Search field in the Find toolbar to display a menu that allows you to show or hide the Find options. For example, you can choose to ignore or match the case of the text in the Search field. Changes you make to this set of options remain persistent for future searches.

Using the Search navigator to search your project or framework

image Whereas the Find command works for locating an item in a file or class, you use the Search navigator (the third button from the left in the Project Navigator toolbar) to find items in your project or even frameworks. You can use Shift+Command+F as a handy keyboard shortcut for the Find command in the Workspace menu item, which also opens the Search navigator pane.

In Figure 7-14, I entered viewDidLoad in the Search field. I also clicked the magnifying glass in the Search field to display search options. (Clicking in the Find pop-up menu will also let you choose Replace to perform a global replace).


Figure 7-14: The Search navigator shows a specific use of the search term in the file.

Note how the initial results of my search are displayed in the Search navigator; if I wanted to filter the Results list still further, I could enter text into the field at the bottom of the pane. Any items that don’t match the text are removed from the Results list.

To go directly to where the search term appears in a file, click an entry under the file’s name in the Search navigator, as shown in Figure 7-14. The file appears in the editor pane on the right, open to the location where the search term appears.

Using the Symbol navigator

image The Symbol navigator allows you to browse through the symbols in your project — just click the Symbol button on the Navigator selector bar. Note that you need to wait until Xcode finishes indexing your project before you can use this feature.

You can display symbols in a hierarchical or flat list using the buttons at the top of the Symbol navigator.

You can specify which symbols are displayed by using the buttons at the bottom of the navigator. Buttons are blue when on and black when off. Use the following buttons in any combination:

image The first button on the Symbol navigator shows only class symbols and hides global symbol types.

image The middle button shows only symbols in this project.

image The third button shows only containers (classes and categories).

You can refine the Results list still more by entering text in the Filter field at the bottom of the navigator.

If you select a symbol to display, its header file definition will be displayed in the source editor. In Figure 7-15, I’ve hidden everything but the member symbols. In the resulting list, I selected the RTDetailViewController viewDidLoad method, and its definition was highlighted in the source editor.


Figure 7-15: The Symbol navigator.

You’re Finally Ready to Code!

Yes, it’s finally time to code, and from here on, it’s full-steam ahead.