The third choice is to click the Remove Old Then Create button. The action of this button is equivalent to fi rst checking all of the fi les listed and clicking the Overwrite Selected Files button. When the dialog box is fi rst presented, all of the fi les are checked, making the action of the two buttons identical. After the fi les are moved aside, new fi les are created in the same location from the template. If there were already source items for these fi les, you now have duplicate source items. Make note of the new source items (which will be selected) and remove the duplicates. The fi les that were moved aside are no longer referred to from the project. You can examine the fi les, recover what you want, and then trash them along with the spontaneously generated folder that contains them. CREATING AN EMPTY FILE The File ➪ New File command performs several common steps and can be a great time saver, but sometimes you just want an empty fi le that doesn ’ t have a name, isn ’ t based on a template, isn ’ t added to a project, and isn ’ t included in one or more targets. The File ➪ New Empty File command (Command+Control+N) does exactly that. In fact, the New Empty File command is very similar to the New command found in most text editor applications. It opens an empty, untitled, editor window. The content of the new window is not associated with a fi le until it is saved. The fi rst time it is saved, Xcode kindly offers to add the new fi le to the active project. You can accept or decline. If you accept, you are presented with the same options you ’ re given when you add any existing source fi le to a project. These options are explained fully in the next section. ADDING EXISTING ITEMS You won ’ t create every fi le in your project from scratch. There will be many occasions when you have an existing fi le or document that you want to add to your project — and you certainly don ’ t write the frameworks you link to. At some point, you are going to need to add existing fi les, folders, and frameworks to your project. Essentially, you select the fi lesystem items you want to add and Xcode creates new source items in your project group that refer to those items. Once the references are created, those fi les become assets of your project. Selecting the Items to Add You have basically two ways of selecting the items to add to your project: start in Xcode or start in the Finder. The fi rst is to use Xcode ’ s Project ➪ Add to Project command (Option+Command+A). Just as you did when creating new fi les, begin by selecting the source group that will contain the new source items, or an existing source item within that group, and then choose the Add to Project command from the Project menu. You can also Right/Control+click a source item and choose Add ➪ Existing Adding Existing Items ❘ 75 c05.indd 75c05.indd 75 1/21/10 1:22:03 PM1/21/10 1:22:03 PM Download at getcoolebook.com 76 ❘ CHAPTER 5 SOURCES Files. Xcode presents an open fi le dialog box to select the fi le, fi les, or folders to be added. This is a multi - selection dialog box; use the Command or Shift key while clicking items to select more than one fi le or folder. Xcode creates a new item reference for every item you select in the dialog box. Figure 5 - 19 shows two new source fi les being added to a project. Note that items already referred to in the project are disabled (grey) and can ’ t be added again. FIGURE 5-19 The second method is more direct. Select any group of items in the Finder (or any application that lets you drag fi les) and drag them into the source group of your project. A drop indicator shows you where in the source group the new item, or items, will be created — exactly as it does when you ’ re dragging items around in the tree. The only signifi cant disadvantage of the drag - and - drop method is that Xcode permits you to create duplicate items to fi les that are already referred to in the project. One quirk to be aware of when using the drag - and - drop technique, at least when dragging from the Finder, is that symbolic links and aliases are not resolved. The source item created will refer to the alias, not to the fi le or folder to which the alias resolves. As soon as Xcode knows where to create the new source items in the project and what fi les will be used to create those items, it presents the dialog box shown in Figure 5 - 20. c05.indd 76c05.indd 76 1/21/10 1:22:04 PM1/21/10 1:22:04 PM Download at getcoolebook.com This dialog box contains several controls that determine what kind of source items are created, the type of references they will have, and where the fi nal source fi les will reside. The effect of these options is often interconnected; some options behave differently depending on the choices you make for other options. Copying Items into the Destination Group ’ s Folder Check the Copy Items into Destination Group ’ s Folder (If Needed) option to make physical copies of the original fi les or folders inside the group ’ s folder. The group ’ s folder is the folder referred to by the group to which the new source items are being added. If you select this option, all of the fi les and folders being added are fi rst copied into the group ’ s folder. Each source item created refers to the copy made in the group ’ s folder, not the original. Note that items contained inside a subfolder of the group ’ s folder are not considered to be in the group ’ s folder. Files or folders in any other folder on the fi lesystem are copied; if you ’ ve selected fi les already in your project this will create duplicate source fi les. Use this option only to import sources from locations outside of the project folder. The “ (If Needed) ” qualifi er is there because this option is ignored if the fi les are already in the enclosing group ’ s folder. Well, not entirely ignored. Due to a long - standing bug in Xcode, this works with fi les but not folders. If you check this option when you ’ re adding a folder to a group whose folder already contains that folder, Xcode displays an error that it can ’ t copy the folder to itself. No harm will come of this, but you will have to perform the operation again, this time turning the Copy option off. Reference Type The Reference Type option controls what type of reference each new source item will have. The choice you make applies to all items being added. Choosing the special reference type of Default individually selects a reference type best suited for each item ’ s location, as listed in the following table. FIGURE 5-20 Adding Existing Items ❘ 77 c05.indd 77c05.indd 77 1/21/10 1:22:09 PM1/21/10 1:22:09 PM Download at getcoolebook.com 78 ❘ CHAPTER 5 SOURCES LOCATION OF EXISTING FILE OR FOLDER DEFAULT REFERENCE TYPE In the enclosing group ’ s folder Enclosing - group Inside any subfolder in the enclosing group ’ s folder Enclosing - group, with a path into the subfolders Anywhere inside the project folder but not inside the enclosing group ’ s folder Project - relative Anywhere outside the project folder, but inside /Users Project - relative, with a path that refers outside of the project folder Anywhere outside the /Users folder Absolute Another volume Absolute If you select any other type of reference, all items created have that reference type regardless of their location. Text Encoding The Text Encoding option applies only to source items created for text fi les. It sets the text encoding for the fi le, which determines how the bytes in the fi le are translated into characters when the fi le is opened for editing. Normally, you wouldn ’ t need to change this for regular program source fi les. The gcc compiler always assumes plain ASCII text, so all program source fi les must be ASCII text fi les. Change this option if you are adding things like XML fi les that are in UTF - 8 or UTF - 16 encoded Unicode, or text fi les in any other ISO encoding. You can always change the encoding later if you need to. See the “ Source Item Attributes ” section earlier in this chapter on how to change the encoding of a fi le. Recursively Creating Groups and Creating Folder References The two radio buttons, Recursively Create Groups for Any Added Folder and Create Folder References for Any Added Folders, determine whether folders added to the project will create source groups or folder items. With the Recursively Create Groups radio button selected, adding a folder creates a source group. After that, every fi le and folder in that folder is recursively added to the new group using the same settings. The folder reference of the new group points to the folder that was added, using the reference type selected. The recursively added items get the same treatment. If the reference type is Default — all of the recursively added items will (by defi nition) have enclosing - group references regardless of the reference type or location of the fi rst new group. Does that organization sound familiar? Look again at the Root3 project. Each source group refers to a single subfolder in the folder of its enclosing group, and every source item refers to a fi le in the folder of its enclosing group. When you use these Add to Project settings, Xcode turns an entire folder hierarchy into an equivalent tree of source groups and source items with a single command. c05.indd 78c05.indd 78 1/21/10 1:22:10 PM1/21/10 1:22:10 PM Download at getcoolebook.com If, instead, you choose Create Folder References for Any Added Folders, Xcode does not recursively process the contents of the folders being added. Instead, it creates a single source folder item as described in the “ Source Item Types ” section earlier in this chapter. Adding an existing folder and choosing this option is the only way of creating a source folder item. Adding the New Items to Targets At the bottom of the dialog box is a list of targets defi ned in the project. If you check the box next to a target, Xcode attempts to add each source item created to that target. The key word is “ attempts. ” Some targets only accept, or understand, certain types of source items. An item is added to a target only if the target accepts that type of item. When everything is set, click the Add button to add the items to the project. Adding a Framework Xcode has a special interface just for adding frameworks. Right/Control+click the source group where you want the framework added and choose the Add ➪ Existing Framework command. A framework picker dialog box appears, like the one in Figure 5 - 21. Xcode assembles a list of all known frameworks and libraries. Choose one or more from the list and click Add. If you ’ re having trouble fi nding what you ’ re looking for, the pop - up menu at the top will narrow the list to a specifi c class of library or framework. To add a framework that isn ’ t one of the standards, use the Project ➪ Add to Project command, exactly as you did in the previous section, and select the framework folder. Make sure the Copy Items into Destination Group ’ s Folder option is not checked. Xcode will recognize that you ’ re adding a framework and create the correct framework source item. Adding an Open File Xcode can open an arbitrary fi le into an editor window. The fi le does not have to belong to a project. You can add the fi le of any open editor window to the current project by selecting the Project ➪ Add Current File to Project command. A dialog box presents the same set of options that the Project ➪ Add to Project command does. Ridding Targets of Unwanted Files It is very easy, when you ’ re adding lots of new source fi les to a project, to end up with fi les in targets where they don ’ t belong. This most often happens when you ’ re adding source and header fi les at the same time. Targets that compile C source into object fi les (native targets) normally only accept C, C++, FIGURE 5-21 Adding Existing Items ❘ 79 c05.indd 79c05.indd 79 1/21/10 1:22:11 PM1/21/10 1:22:11 PM Download at getcoolebook.com 80 ❘ CHAPTER 5 SOURCES or Objective - C source fi les. Trying to add the companion header fi les to those targets at the same time does nothing, but some native targets have a Copy Files phase that accepts any kind of fi le. The end result is that all of the .h fi les get added to the target ’ s Copy Files phase, and the target dutifully copies all of the headers fi les in your project into the fi nal application. This is probably not what you want. To fi x this, select the project structure group in the Groups & Files list to display all of the fi les in the project in the details window (choose View ➪ Details if you are using the Condensed layout style). In the details list, click the icon (fi le type) column to sort the items by type. Click the fi rst header fi le in the list, then scroll down and Shift - click the last one to select all of the header fi les in the project. Now choose File ➪ Get Info to get an aggregate Info window for all of the header fi le items. Switch to the Targets tab and uncheck all of the targets. This removes all of the header fi les from all of the targets in your project. You can adapt this technique to make similar changes in other types of fi les. REMOVING SOURCE ITEMS Removing source items from your project is just about as easy as you would imagine it would be. Select one or more source items and press the Delete key, choose Edit ➪ Delete, or Right/Control+click ➪ Delete. Xcode presents a dialog box, as shown in Figure 5 - 22. The Delete References button only removes the source item (reference) from your project structure group. The Also Move to Trash button removes the source item and moves the fi le(s) it refers to the system Trash folder. FIGURE 5-22 REORGANIZING SOURCES This section walks you through reorganizing the fi les in a project. This usually entails rearranging the actual fi les and then altering the source item references to agree. When you ’ re working with source item references, it ’ s useful to know when an item ’ s reference is valid and when it ’ s broken. Whenever Xcode discovers that a reference no longer refers to a fi le or folder, the item in the source group turns red. Figure 5 - 23 shows invalid references for the Two.h , Two.m , and main.cpp items. c05.indd 80c05.indd 80 1/21/10 1:22:12 PM1/21/10 1:22:12 PM Download at getcoolebook.com . source item within that group, and then choose the Add to Project command from the Project menu. You can also Right/Control+click a source item and choose Add ➪ Existing Adding Existing Items. 1/21/10 1:22: 09 PM1/21/10 1:22: 09 PM Download at getcoolebook.com 78 ❘ CHAPTER 5 SOURCES LOCATION OF EXISTING FILE OR FOLDER DEFAULT REFERENCE TYPE In the enclosing group ’ s folder Enclosing -. Existing Items ❘ 75 c05.indd 75c05.indd 75 1/21/10 1:22: 03 PM1/21/10 1:22: 03 PM Download at getcoolebook.com 76 ❘ CHAPTER 5 SOURCES Files. Xcode presents an open fi le dialog box to select the fi