The first approach I took was to loop through all the files, building a path to each, one by one:

// Path to the Documents directory
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
if ([paths count] > 0)
{
  NSError *error = nil;  
  NSFileManager *fileManager = [NSFileManager defaultManager];
 
  // Print out the path to verify we are in the right place
  NSString *directory = [paths objectAtIndex:0];
  NSLog(@"Directory: %@", directory);
 
  // For each file in the directory, create full path and delete the file
  for (NSString *file in [fileManager contentsOfDirectoryAtPath:directory error:&error])
  {    
    NSString *filePath = [directory stringByAppendingPathComponent:file];
    NSLog(@"File : %@", filePath);
 
    BOOL fileDeleted = [fileManager removeItemAtPath:filePath error:&error];
 
    if (fileDeleted != YES || error != nil)
    {
      // Deal with the error...
    }
  }
 
}

The code above works fine, however, I was interested in something that didn’t build each path separately – the code below deletes all the files in one fell swoop:

 
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
if ([paths count] > 0)
{
  NSLog(@"Path: %@", [paths objectAtIndex:0]);
 
  NSError *error = nil;  
  NSFileManager *fileManager = [NSFileManager defaultManager];
 
  // Remove Documents directory and all the files
  BOOL deleted = [fileManager removeItemAtPath:[paths objectAtIndex:0] error:&error];
 
  if (deleted != YES || error != nil)
  {
    // Deal with the error...
  }
 
}

Given the requested item to remove was a directory, as you’d expect, not only were the files deleted, so was the Documents directory. Problem is, I ran into errors when I attempted to drag/drop new files into the file sharing areas iTunes.

To get things working again, I changed up the code above to create the Documents directory:

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
if ([paths count] > 0)
{
  NSLog(@"Path: %@", [paths objectAtIndex:0]);
 
  NSError *error = nil;  
  NSFileManager *fileManager = [NSFileManager defaultManager];
 
  // Remove all files in the documents directory
  BOOL deleted = [fileManager removeItemAtPath:[paths objectAtIndex:0] error:&error];
 
  if (deleted != YES || error != nil)
  {
    // Deal with the error...
  }
  else
    // Recreate the Documents directory
    [fileManager createDirectoryAtPath:[paths objectAtIndex:0] withIntermediateDirectories:NO attributes:nil error:&error];
 
}

Although there is less code to delete the Documents directory, something tells me it may simply be a better (and more robust) solution to loop and delete each file in sequence.

For those unfamiliar with the quick look previewer, it is a framework that provides quick previewing of a range of document types – supported documents include iWork documents, Microsoft Office, Rich Text Format, PDF, images, text files and comma-separated (csv) files.

Document Previewer Demo App

What follows are a few screenshots of the previewer application covered in this post. I’ve added three different file types in the application, an image, a pdf and an MS Office document. The screenshot in the upper left is the list of available files to preview. In the lower left is Remodel.xls, an Excel document. The upper right screenshot is the iOSDevTips.png image. Notice in this same image in the upper right corner is a directional arrow (outlined with the red box), this leads you to one nice addition you get for free with preview, support for printing (assuming you have a wireless printer in the vicinity).

Document Previewer Interface

The interface file for the application is shown below, notice the reference to the QL Data Source, when using the QLPreviewController you must adopt this protocol. The only instance variable is an array that will hold strings value representing the title of each document available for previewing. The UITableViewController class will be used to display the list of documents to preview.

#import <QuickLook/QuickLook.h>
 
@interface TestViewController : UITableViewController <QLPreviewControllerDataSource>
{
  NSArray *arrayOfDocuments;
}
 
@end

Document Previewer Implementation

In this section I’ll show a selection of code applicable to setting up the previewer. The code for creating the table view and populating the same can be viewed in the Xcode project which you can download from the link below.

The initialization code populates the array of document names:

-(id)init
{
  if (self = [super init])
  {
    arrayOfDocuments = [[NSArray alloc] initWithObjects: 
        @"iOSDevTips.png", @"Remodel.xls", @"Core J2ME Technology.pdf", nil];
  }
  return self;
}

The method below is one of the two required when adopting the QLPreviewControllerDataSource protocol, this method informs the preview controller how many items are in the preview navigation list:

- (NSInteger) numberOfPreviewItemsInPreviewController: (QLPreviewController *) controller 
{
  return [arrayOfDocuments count];
}

The method that does all the work (other than the previewer itself of course) is shown below – this method returns a NSURL object of the item to display. Given the objects to display are packaged within the application, I create a path to the relevant file in the application bundle and return a URL using that same path.:

- (id <QLPreviewItem>)previewController: (QLPreviewController *)controller previewItemAtIndex:(NSInteger)index 
{
  // Break the path into its components (filename and extension)
  NSArray *fileComponents = [[arrayOfDocuments objectAtIndex: index] componentsSeparatedByString:@"."];
 
  // Use the filename (index 0) and the extension (index 1) to get path
  NSString *path = [[NSBundle mainBundle] pathForResource:[fileComponents objectAtIndex:0] ofType:[fileComponents objectAtIndex:1]];
 
  return [NSURL fileURLWithPath:path];
}

The remaining code in the project is typical iPhone/iOS stuff, creating the app delegate, adding a subview (a navigation controller) to the delegate’s UIWindow and making the window visible. I’ve included code from the delegate below, here you can get the bigger picture view of how I setup the view controller for this application.

- (void)applicationDidFinishLaunching:(UIApplication *)application 
{   
  // Create and initialize the window
  window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
 
  // Create test view controller
  vc = [[TestViewController alloc] init];
 
  // Create navigation controller 
  nav = [[UINavigationController alloc] initWithRootViewController:vc];
 
  [window addSubview:[nav view]];  
  [window makeKeyAndVisible];
}

One point worth mentioning is that you have two different options when working with a preview controller. First, you can push the object with the preview controller onto a view using a UINavigationController object, which you can see is what I’ve done here. The preview controller for my app lives in TestViewController and this object is set as the root view controller for a navigation controller.

The second approach to display the preview controller is modally, using the method presentModalViewController.

Document Previewer Source Code

Xcode project for iPhone Document Previewer

Get Free Disk Space

To get free space available, the class NSFileManager provides a method attributesOfFileSystemForPath:error: which will return a dictionary that includes five entries with various file system information.

// Get access to a file manager as our means
// to perform file operations
NSFileManager *fileManager = [NSFileManager defaultManager];
 
// Using the application home directory, get dictionary of attributes
NSDictionary *attributesDict = [fileManager attributesOfFileSystemForPath:NSHomeDirectory() error:NULL];
 
// Print total file system size and available space  
NSLog(@"File system size: %lld", [[attributesDict objectForKey:NSFileSystemSize] longLongValue]);
NSLog(@"File system free space: %lld", [[attributesDict objectForKey:NSFileSystemFreeSize] longLongValue]);

Notice that the objects for the keys requested are NSNumbers. Calling the method longLongValue returns the value of the object as a long long type, which I use to print information to console.

For information on the additional attributes in the dictionary, check out the NSFileManager API documenation.

As an example of the later, often times I find it helpful to put json (or xml) content into a file that I know is valid based on a remote server that I will eventually connect with. I add this file to the application bundle and read it into an internal data structure. I can then do various tests with known data, and once that is working, I can then proceed to the networking side of things to connect and retrieve live data.

// Read in and store as string
NSString *file = [[NSBundle mainBundle] pathForResource:@"jsonTest" ofType:@"txt"];
NSString *str = [NSString stringWithContentsOfFile:file 
   encoding:NSUTF8StringEncoding error:NULL];
debug(@"str: %@", str);
 
// Do something with the test data...
 
// Read in and store as raw data bytes
NSString *file2 = [[NSBundle mainBundle] pathForResource:@"data" ofType:@"txt"];
NSData *data = [NSData dataWithContentsOfFile:file2];

Get UIImage Data as PNG or JPEG

UIKit includes two C functions, UIImageJPEGRepresentation and UIImagePNGRepresentation which will return an NSData object that represents an image in JPEG or PNG format, respectively. With this information in hand, you can then use the writeToFile method of the NSData object to write the image data to a specified path.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// Create paths to output images
NSString  *pngPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents/Test.png"];
NSString  *jpgPath = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents/Test.jpg"];
 
// Write a UIImage to JPEG with minimum compression (best quality)
// The value 'image' must be a UIImage object
// The value '1.0' represents image compression quality as value from 0.0 to 1.0
[UIImageJPEGRepresentation(image, 1.0) writeToFile:jpgPath atomically:YES];
 
// Write image to PNG
[UIImagePNGRepresentation(image) writeToFile:pngPath atomically:YES];
 
// Let's check to see if files were successfully written...
 
// Create file manager
NSError *error;
NSFileManager *fileMgr = [NSFileManager defaultManager];
 
// Point to Document directory
NSString *documentsDirectory = [NSHomeDirectory() stringByAppendingPathComponent:@"Documents"];
 
// Write out the contents of home directory to console
NSLog(@"Documents directory: %@", [fileMgr contentsOfDirectoryAtPath:documentsDirectory error:&error]);

Important note, on lines 6 and 9, the value image must be a UIImage object.

Source Code

I’ve changed the example from the original post that wrote a UIImage from the camera to the Photo Album, to write instead to the test files shown above. You can download the source code for the application here: Write UIImage Object as a PNG or JPEG File.

Simulator Not Supported

One last note, this application will only run on an actual device as the simulator does not have camera support.

Read and Write Collections to File

NSArray *array = [NSArray arrayWithObjects: 
    @"Hefeweizen", @"IPA", @"Pilsner", @"Stout", nil];
 
NSDictionary *dictionary = [NSDictionary dictionaryWithObjectsAndKeys:
  array, @"array", @"Stout", @"dark", @"Hefeweizen", @"wheat", @"IPA", 
  @"hoppy", nil];
 
// Get path to documents directory
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, 
  NSUserDomainMask, YES);
if ([paths count] > 0)
{
  // Path to save array data
  NSString  *arrayPath = [[paths objectAtIndex:0] 
      stringByAppendingPathComponent:@"array.out"];
 
  // Path to save dictionary
  NSString  *dictPath = [[paths objectAtIndex:0] 
      stringByAppendingPathComponent:@"dict.out"];
 
  // Write array
  [array writeToFile:arrayPath atomically:YES];
 
  // Write dictionary
  [dictionary writeToFile:dictPath atomically:YES];
 
  // Read both back in new collections
  NSArray *arrayFromFile = [NSArray arrayWithContentsOfFile:arrayPath];
  NSDictionary *dictFromFile = [NSDictionary dictionaryWithContentsOfFile:dictPath];
 
  for (NSString *element in arrayFromFile) 
    NSLog(@"Beer: %@", element);
 
  for (NSString *key in dictFromFile) 
    NSLog(@"%@ Style: %@", key, [dictionary valueForKey:key]); 
}

Verify the Output

The output in the console window for the above looks as follows:

This is the second tip in a series of four that is based on content from the O’Reilly book Head First iPhone Development. The first tip described how to adjust textfields that are hidden when the onscreen keyboard is shown.

O’Reilly and iPhone Developer Tips are collaborating to give away a free ebook (electronic copy) of Head First iPhone Development each Friday in November. You can register in this weeks drawing by referring a friend to this iPhone Developer tip – see the Refer-a-Friend button near the bottom of this post. You can read more about last weeks winner, Bill Mietelski, on this post.

This tip, based on content in Chapter 4 – Multiple View, shows how to read a plist from a file in the resource bundle, into an array.

Hardcoded Array

Based on the example in the book, let’s assume we are keeping a list of mixed drinks inside our application. Somewhere in the initialization process we might write something like the following to build an array of NSString values:

NSMutableArray *array = [[NSMutableArray alloc] initWithObjects:
    @"Firecracker", @"Lemon Drop", @"Mojito", nil];
 
// Show the string values  
for (NSString *str in array)
  NSLog(@"%@", str);

Creating a plist

Although the code above works, a better solution would be to keep the list of values in a plist as part of the resource bundle, then read the plist into an array.

To create plist, in Xcode, right click on Resources then select Add, New File, Mac OS X, Resource, Property List. Name the file DrinkArray.plist. Change the root type to Array and then add the four string values shown below:

Reading a plist into an NSArray

Reading the plist into an array is straight forward:

// Path to the plist (in the application bundle)
NSString *path = [[NSBundle mainBundle] pathForResource:
    @"DrinkArray" ofType:@"plist"];
 
// Build the array from the plist  
NSMutableArray *array2 = [[NSMutableArray alloc] initWithContentsOfFile:path];
 
// Show the string values  
for (NSString *str in array2)
  NSLog(@"--%@", str);

plists and Other Data Types

One of the benefits of working with plists, is that other types, for example NSDictionary, can be read from a plist. This means that you can create more complex data collections in a plist, such as an array of dictionaries.

For example, the plist below is also an array, however, the third value in the array is a dictionary.

With plists you can build various data types needed by your application and read those values directly into your program.

Point to the Documents Directory

Each application has its own sandbox in which you can read/write files. Files written to the sandbox are persistent across invocations of the application, including across application updates.

You can locate the Documents directory in the sandbox as shown below:

// For error information
NSError *error;
 
// Create file manager
NSFileManager *fileMgr = [NSFileManager defaultManager];
 
// Point to Document directory
NSString *documentsDirectory = [NSHomeDirectory() 
         stringByAppendingPathComponent:@"Documents"];

Creating a File

With the documents directory available, we can now use that path to create a new file in the sandbox and write a few lines of text:

// File we want to create in the documents directory 
// Result is: /Documents/file1.txt
NSString *filePath = [documentsDirectory 
         stringByAppendingPathComponent:@"file1.txt"];
 
// String to write
NSString *str = @"iPhone Developer Tips\nhttp://iPhoneDevelopTips,com";
 
// Write the file
[str writeToFile:filePath atomically:YES 
         encoding:NSUTF8StringEncoding error:&error];
 
// Show contents of Documents directory
NSLog(@"Documents directory: %@",
         [fileMgr contentsOfDirectoryAtPath:documentsDirectory error:&error]);

We build a path to the file we want to create (file1.txt), initialize a string to write into the file, and write out the contents. The last line shows a directory listing of what is in the Documents directory after we create the file, see the figure below:

Renaming a File

To rename a file we move the file to a new path. The code below creates the destination path we are after, requests to move the file, and shows the Documents directory after the move.

// Rename the file, by moving the file
NSString *filePath2 = [documentsDirectory 
                                 stringByAppendingPathComponent:@"file2.txt"];
 
// Attempt the move
if ([fileMgr moveItemAtPath:filePath toPath:filePath2 error:&error] != YES)
  NSLog(@"Unable to move file: %@", [error localizedDescription]);
 
// Show contents of Documents directory
NSLog(@"Documents directory: %@", 
         [fileMgr contentsOfDirectoryAtPath:documentsDirectory error:&error]);

After moving the file, the output should look similar to the image below:

Deleting a File

To round out this tip, let’s look at how to delete a file:

// Attempt to delete the file at filePath2
if ([fileMgr removeItemAtPath:filePath2 error:&error] != YES)
  NSLog(@"Unable to delete file: %@", [error localizedDescription]);
 
// Show contents of Documents directory
NSLog(@"Documents directory: %@",
         [fileMgr contentsOfDirectoryAtPath:documentsDirectory error:&error]);

Once the file is deleted, as expected, the Documents directory is now empty:

These examples touch the surface of working with files. Check out the documentation for NSFileManager for all the specifics.

In this tip I want to show an example that arrives at the same end result, however, I’ll use methods which will eliminate the hardcoding of paths as shown in the first example.

To quickly recap, the intention was to create a file named User.plist and store that file in the user’s documents folder. In the previous post I specified the full file path I was after (/Documents/User.plist) and then appended that path to the user’s home directory.

Here’s another approach:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, 
    NSUserDomainMask, YES);
 
if ([paths count] > 0)
{
  NSString  *plistPath = [[paths objectAtIndex:0] 
                                 stringByAppendingPathComponent:@"User.plist"];
 
  // Check for existence of the file
  if ([[NSFileManager defaultManager] fileExistsAtPath:plistPath])
    ... 
  else
    ...
}

With this approach I request the path to the documents directory through a call to NSSearchPathForDirectoriesInDomains by specifying NSDocumentDirectory as the search path. To build the fullpath I first retrieve the path to the documents directory ([paths objectAtIndex:0]) and append the filename that I am after through a call to stringByAppendingPathComponent. The later call will prepend a path separator and append the filename requested.

The end result, with no hardcoding: /Documents/User.plist

Here is the code I used to specify the path where I wanted the files written and the code to build an NSString with the full path.

1
2
3
4
5
6
7
8
9
10
11
12

// Folder and file name
#define USER_PLIST_FULLPATH @"/Documents/User.plist"
 
// Path to the user property list
NSString  *plistPath;
plistPath = [NSHomeDirectory() stringByAppendingString:USER_PLIST_FULLPATH];
 
// Check for existence of the file
if ([[NSFileManager defaultManager] fileExistsAtPath:plistPath])
  ...
else
  ...

The key to making this work is NSHomeDirectory() a low level C function that returns the path to the current user’s home directory. See the document Low-Level File Management Programming Topics for the specifics on working with the file system.

In the next post I’ll show another means to generate paths to files, arguably a better approach as it uses the provided frameworks for building paths (versus hardcoding as shown here).

Important Note: There is a /Documents directory created in the sandbox for each iPhone application. In other words, the plist file that I created above will not clash with a file of the same name in another iPhone application.