// in a UIViewController subclass

- (void)viewWillAppear:(BOOL)animated {
	[self.navigationController setToolbarHidden:NO animated:YES];
    [super viewWillAppear:animated];
}

- (void)viewWillDisappear:(BOOL)animated {
	[self.navigationController setToolbarHidden:YES animated:YES];
	[super viewWillDisappear:animated];
}

// Automatically highlight the field and change to email keyboard.
UITableViewCell *cell = (UITableViewCell *)[tableView cellForRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]];
[cell.field becomeFirstResponder];
cell.field.keyboardType = UIKeyboardTypeEmailAddress;

A year ago, when I first implemented it, I was averse to adding a secret preferences window, because I couldn’t think of a natural place for accessing it. Instead, I added a quick key-value pair to Info.plist. Users wouldn’t happen across it; most of them probably don’t know app bundles are folders. But the preference was there if needed. So, I shipped that. Multiple times. Recently, I decided this preference needed to be dynamic, for those times when a user wants to enable logging without restarting the application. I set up an NSTimer to read the key-value pair from Info.plist every minute. After finding out the dictionary was cached, I figured out how to manually read it. Problem solved.

And yet, I completely ignored all the signs that pointed to a bad user experience. The workflow for setting the preference was complicated to explain to other developers (who know app bundles are folders). Non-developers asked for the specific steps multiple times. And yes, the Info.plist dictionary is cached, implying it’s for general application information, not debug settings. Still, it took two thoughtful comments on my other post to snap me out of my developer haze and think about the feature from a user’s perspective.

The goal of the feature was to hide the user-configurable preference from immediate view, not to bury it completely. The Info.plist workflow didn’t work, so I started brainstorming. How about a secret preference window? Fine, but where would it go? Perhaps an NSMenuItem, but that’s not hidden. Then I realized an alternate NSMenuItem was the perfect fit: hold the option key and “Preferences…” switches to “Secret Preferences…”. A user won’t stumble across it, but the menu item is a key away. Moreover, an NSTimer isn’t necessary; Cocoa Bindings make a preference change instant. That’s what I implemented today.

Never be afraid to iterate your design. The product I work on went through many iterations before arriving at its current form. Apple agrees. When I’ve talked to their UI evangelists, John Geleynse and Eric Hope, both consistently cite design iteration as one of the most important processes for developing award-winning applications (along with product definition statements). Most apps start out looking mediocre; the best user experiences are the culmination of many iterations. Keep iterating.

Recently, I wanted to read the key-value pair dynamically. That way, the user could change the value at any time, and within a minute, the app would use the new value. This proved harder. As it turns out, Apple optimized the infoDictionary query, so that it caches the contents at startup and returns that cached version through the application lifetime. If the user modified the key-value pair, that change wouldn’t show up until the next startup. Instead of using that builtin method, I had to read the Info.plist file directly. See the code below.

// [[NSBundle mainBundle] infoDictionary] is cached at app startup, so we need to read the file directly for latest data.
NSString *infoPlistFilePath = [NSString stringWithFormat:@"%@/Contents/Info.plist", [[NSBundle mainBundle] bundlePath]];
NSString *infoDictionary = [NSDictionary dictionaryWithContentsOfFile:infoPlistFilePath];
NSString *value = [infoDictionary valueForKey:@"InfoPlistKey"];

UPDATE: This is a lesson in design. While the code does function as described, I now agree that no user should be subjected to this workflow. Check out my longer explanation about the feature’s design.

In both cases, we’ll use a custom UITableViewCell to drive the animation, unlike the model-driven approach we used on the Mac. See my custom UITableViewCell post for a tutorial.

Animate using image array

UIImageView has three properties available to facilitate animations: animationDuration, animationImages, and animationRepeatCount. We can use these to easily incorporate the six iPhoto arrow images (see the Mac syncing arrows post) into our custom UITableViewCell. For indefinite animation (which we want), set animationRepeatCount to zero, according to Apple’s documentation. Then, after setting the duration, we simply start the animation.

// Animate using image array.
syncIconView.animationImages = [NSArray arrayWithObjects:
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows1" ofType:@"png"]] autorelease],
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows2" ofType:@"png"]] autorelease],
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows3" ofType:@"png"]] autorelease],
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows4" ofType:@"png"]] autorelease],
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows5" ofType:@"png"]] autorelease],
    [[[UIImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows6" ofType:@"png"]] autorelease],
    nil];
syncIconView.animationDuration = interval;
syncIconView.animationRepeatCount = 0;
[syncIconView startAnimating];

Animate using rotation transform

Instead of leveraging UIImageView-specific methods, we utilize the iPhone’s layer-backed UIViews and create a CAAnimation, with a rotation transform. To match the array animation, we make the toValue equal to pi radians (180 degrees). Unlike the array animation, we cannot supply a specific argument to have the animation repeat indefinitely, so we just assign a really large value. (Let me know if there is a better workaround.) Finally, we add the new animation to the UIImageView’s layer.

// Animate using rotate transform.
CABasicAnimation* rotateAnimation = [CABasicAnimation animationWithKeyPath:@"transform.rotation"];
rotateAnimation.toValue = [NSNumber numberWithFloat:M_PI];
rotateAnimation.duration = interval;
rotateAnimation.repeatCount = 1e100;
[syncIconView.layer addAnimation:rotateAnimation forKey:@"rotateAnimation"];

Results

The difference between the two animations is quite striking. At a small duration (around .3s), the array animation looks fine without comparison. The animation is almost imperceptibly jumpy but is, again, just fine. However, a side-by-side comparison of it to the rotation transform animation reveals the stark contrast between the two approaches. The latter shows how amazing Core Animation makes the UI; it’s magic pixie dust. I committed a sample project (10.5, Xcode 3.1.4) to Google Code. Check it out in SVN, run it, and compare “Array at 1.00s” with “Rotate at 1.00s”. The rotate transform wins. As does Core Animation.

On an side note, comparing the Resources folders in iTunes and iPhoto gives some insight into Apple’s approach with each product. (Right-click on any application and click “Show Package Contents” to navigate to the Resources folder.) iTunes’ Resources folder holds a mere 118 items, including 19 language folders. Only 118! There are extremely few icons in the folder, implying that iTunes draws almost all of them in code. On the other hand, iPhoto has 1,532 items in its Resources folder. Seemingly every state of every icon in the entire photo application comes from an icon in this folder. Different approaches. The end result is iTunes weighing in at 150MB and iPhoto at 410MB. Perhaps the stark differences are market-driven, as iTunes is predominately delivered online whereas iPhoto is typically pre-installed or comes on a DVD. For this tutorial, I’m going with iPhoto’s approach.

Let’s make syncing arrows for a sample Mac application. Originally, I thought I should use Core Animation, as it’s in 10.5+. However, at WWDC, an Apple Core Animation engineer told me that only the iPhone apps can rotate table cells like that, as only UITableViewCells subclass a view object (UIView). On the Mac, NSCell subclasses NSObject directly, so he said to go with a simple NSTimer and cycle through a set of images. So, that’s what I did here.

I want a simple application for this demo: just a list (NSTableView). Inside each row, I want those syncing arrows, rotating at varying speeds to see which interval is the optimal. There are two parts to this UI: an NSTimer and a set of icons in my cell class. To make the code very simply, I leverage Cocoa Bindings to trigger a UI refresh, instead of calling NSView::setNeedsDisplay. The screenshot below shows how to connect the NSArrayController in Interface Builder to the two NSTableColumns in the NSTableView.

The icons are straight out of iPhoto. Go into iPhoto.app/Contents/Resources and search for “sl-status_syncanimation-01.tiff”. There are six total.

First, I initialize the cell’s state, including the timer and the icon array.

- (id) initWithInterval:(NSTimeInterval)interval {
	self = [super init];
	if (self != nil) {
		// Set item's title.
		self.title = [NSString stringWithFormat:@"Item with interval %1.2fs", interval];
		// Set up status array.
		icons = [[NSArray alloc] initWithObjects:
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows1" ofType:@"png"]],
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows2" ofType:@"png"]],
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows3" ofType:@"png"]],
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows4" ofType:@"png"]],
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows5" ofType:@"png"]],
				 [[NSImage alloc] initWithContentsOfFile:[[NSBundle mainBundle] pathForResource:@"syncing_arrows6" ofType:@"png"]],
				 nil];
		// Initialize icon state.
		icon = [icons objectAtIndex:0];
		statusState = 0;
		// Set up status timer.
		stateTimer = [NSTimer scheduledTimerWithTimeInterval:interval target:self selector:@selector(updateStatus) userInfo:nil repeats:YES];
	}
	return self;
}

Next, I simply add the method called by the NSTimer. In there, I update the status icon and increment to the next state.

- (void)updateStatus {
	self.icon = [icons objectAtIndex:statusState];
	statusState = (statusState + 1) % [icons count];
}

I posted the code on Google Code as SyncingArrows. Keep in mind that I wrote it in Leopard (10.5) using Xcode 3.1.2; let me know if you have issues trying it.

I’m pretty happy with the iteration.

readme

=Localization Readme=
This readme covers four scripts I wrote to utilize ibtool. They're all available on Google Code with MIT license.
- Brian (brian@bdunagan.com)

Finally, the last part of the script's workflow actually generates .strings files for the old and new versions of the localized XIB. I always diff this pair of files to ensure the update process went smoothly.

localize_xibs_incremental.rb

#!/usr/bin/ruby
# MIT license

# localize_xibs_incremental.rb
# This script takes a set of localized strings, a set of old and new English XIBs, and a set of current
# localized XIBs and incrementally localizes the localized XIBs with the localized strings and the diff between
# the old English XIBs and the new English XIBs.

# ibtool
#   --previous-file English.lproj/MainWindow.old.xib
#   --incremental-file fr.lproj/MainWindow.old.xib
#   --strings-file path_to_strings/fr/MainWindow.strings
#   --localize-incremental
#   --write fr.lproj/MainWindow.xib
#   English.lproj/MainWindow.new.xib

# More info: http://developer.apple.com/documentation/developertools/conceptual/IB_UserGuide/LocalizingNibFiles/LocalizingNibFiles.html

require 'FileUtils'

# Check for arguments.
if ARGV.length != 2
  puts "Usage: ruby localize_xibs_incremental.rb path_to_project path_to_strings"
  exit
end

# Get path arguments and 'cd' to that project path.
SOURCE_XIB_FOLDER = "English.lproj"
PROJECT_PATH = ARGV[0]
STRINGS_PATH = ARGV[1]
FileUtils.cd(PROJECT_PATH)
FILES_TO_IGNORE = [".svn", "." ,"..", ".DS_Store"]
NON_XIB_LOCALIZED_FILES = ["InfoPlist.strings","Localizable.strings"]

# Iterate through the current directory.
Dir.entries(STRINGS_PATH).each do |localized_folder|
  if (!FILES_TO_IGNORE.include?(localized_folder))
    puts "Generating localizations for #{localized_folder}"
    # Iterate over the .strings language folders.
    Dir.entries(STRINGS_PATH + "/" + localized_folder).each do |strings_file|
      strings_path = STRINGS_PATH + "/" + localized_folder + "/" + strings_file
      if (NON_XIB_LOCALIZED_FILES.include?(strings_file))
        %x[cp \"#{strings_path}\" \"#{localized_folder}.lproj/#{strings_file}\"]
        puts "COPIED #{strings_file} to #{localized_folder}"
      elsif (!FILES_TO_IGNORE.include?(strings_file))
        filename = strings_file.slice(0,strings_file.length-8)
        source_xib = SOURCE_XIB_FOLDER + "/" + filename

        # Create a new localized XIB based on older localized version and two English versions.
        command = "ibtool --previous-file \"#{source_xib}.old.xib\" " +
                         "--incremental-file \"#{localized_folder}.lproj/#{filename}.old.xib\" " +
                         "--strings-file \"#{strings_path}\" " +
                         "--localize-incremental " +
                         "--write \"#{localized_folder}.lproj/#{filename}.xib\" " +
                         "\"#{source_xib}.new.xib\""
        results = %x[#{command}]
        if results.length > 0
          puts "FAILURE: #{command}:\n#{results}"
        else
          puts "SUCCESS: #{localized_folder}.lproj/#{filename}.xib"
        end

        # Generate .strings files for both localized versions to easily compare. Erase after.
        command = "ibtool --generate-strings-file \"#{localized_folder}.lproj/#{filename}.old.strings\" \"#{localized_folder}.lproj/#{filename}.old.xib\""
        results = %x[#{command}]
        command = "ibtool --generate-strings-file \"#{localized_folder}.lproj/#{filename}.new.strings\" \"#{localized_folder}.lproj/#{filename}.xib\""
        results = %x[#{command}]
      end
    end
  end
end

Creating a custom UITableViewCell using Interface Builder is straight-forward.

1. In Xcode, create a new UITableViewCell subclass and add the desired IBOutlets to the header file.
2. In Interface Builder, create an “Empty” XIB from the Cocoa Touch palette.
3. Drag a UITableViewCell from the Library into it, configure the class to be your new custom UITableViewCell subclass, and give it the appropriate identifier.
4. Add the desired elements to the UITableViewCell and connect the subclass’s outlets to them.
5. To instantiate the cells using the UIViewController approach, set class of the new XIB’s “File’s Owner” to be “UIViewController”, and connect its view outlet to the customized UITableViewCell.

The XIB is set up, but there are two approaches to instantiating the new customized cell from that XIB. When I was at WWDC a couple weeks ago, I confirmed with one of the Interface Builder engineers at the IB Lab that both work just fine. (He did repeatedly ask if I was using UITableView:dequeueReusableCellWithIdentifier:, just to make sure.)

UIViewController

One approach is to create a temporary UIViewController each time you need a new cell. By setting up the XIB the way we did, the temporary UIViewController has the cell as its view attribute. After we grab a pointer to that, we can release the view controller.

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"BDCustomCell"];
    if (cell == nil) {
		// Create a temporary UIViewController to instantiate the custom cell.
        UIViewController *temporaryController = [[UIViewController alloc] initWithNibName:@"BDCustomCell" bundle:nil];
		// Grab a pointer to the custom cell.
        cell = (BDCustomCell *)temporaryController.view;
		// Release the temporary UIViewController.
        [temporaryController release];
    }

    return cell;
}

NSBundle:loadNibNamed:owner:options:

Another approach is to load the NIB file and grab the cell directly, as it’s the only top-level object in the NIB.

- (UITableViewCell *)tableView:(UITableView *)tableView cellForRowAtIndexPath:(NSIndexPath *)indexPath {
    UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:@"BDCustomCell"];
    if (cell == nil) {
		// Load the top-level objects from the custom cell XIB.
        NSArray *topLevelObjects = [[NSBundle mainBundle] loadNibNamed:@"BDCustomCell" owner:self options:nil];
		// Grab a pointer to the first object (presumably the custom cell, as that's all the XIB should contain).
		cell = [topLevelObjects objectAtIndex:0];
    }

    return cell;
}

“Could not be parsed”

When ibtool encounters an expected bad character, like an unescaped double-quote, it verbally fails, supplying the message below.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.ibtool.errors</key>
	<array>
		<dict>
			<key>description</key>
			<string>ibtool failed with exception: The stringsfile MainMenu.ES.strings could not be parsed.</string>
		</dict>
	</array>
</dict>
</plist>

This error is helpful, but it doesn’t identify the offending line. To do that, we can use another Apple command-line tool: plutil. (Thanks to Cocoa Musings for pointing this out.) plutil can parse a .strings file and provide the line the bad character was on. It’s a very useful program when the .strings file that failed has 3K lines, and the problem is a single unescaped double-quote. ibtool generates these verbal parse errors on all alphanumeric characters and a number of others (" ' : . / - _ $).

Silent Errors

Unfortunately, ibtool (and plutil) fails silently on these other characters:

{ } [ ] ; , < > ? \ | = + ! ` ~ @ # % ^ & * ( )

Let me say that again: ibtool fails silently. The program stops incorporating localized strings when it encounters one of these characters, but it does not produce an error. The bug becomes particularly nasty when scaling up to 150 localized XIBs. I only discovered the bug when I found a single XIB incorrectly localized and tracked it back to a set of brackets randomly inserted into a .strings file.

So, I wrote a ruby script, validate_strings_files.rb, to validate .strings files more completely. The script parses through a directory of .strings files and produces verbal errors, with line numbers, for any out-of-place characters. It works well on the 11 languages I deal with. An error that would silently fail in ibtool would produce the following result with the script:

VERIFYING FILE MainMenu.ES.strings
MainMenu.ES.strings (328): @

Below is the code for validate_strings_files.rb.

#!/usr/local/bin/ruby
# encoding: UTF-8

# NOTE: requires ruby 1.9
# MIT license

# validate_strings_files.rb
# This script reads through the .strings files in a directory and identifies any bad characters inside,
# both those that ibtool would catch and those that ibtool would miss.
# * ibtool verbal errors: " ' : . / - _ $
# * ibtool silent errors: { } [ ] ; , < > ? \ | = + ! ` ~ @ # % ^ & * ( )

require 'FileUtils'

# Check for arguments.
if ARGV.length != 1
  puts "Usage: ruby validate_strings_files.rb path_to_strings"
  exit
end

# Get path argument and 'cd' to that path.
PATH = ARGV[0]
FileUtils.cd(PATH)

def verify_file(file)
  line_number = 0
  is_multi_line_comment = false

  # Use general method unless file encoding is UTF-16.
  file_handle = File.new(file, "r")
  # file_handle = File.new(file, "r:UTF-16LE:UTF-8") (See http://blog.grayproductions.net/articles/ruby_19s_three_default_encodings)

  puts "VERIFYING FILE #{file}"
  while (!file_handle.eof?)
    has_seen_equals_sign = false
    has_seen_semi_colon = false
    is_single_line_comment = false
    is_string = false
    line_number += 1
    previous_char = nil
    second_previous_char = nil

    line = file_handle.readline
    # Use each_char (rather than each_byte) to support unicode.
    line.each_char do |char|
      # Notes:
      # * line can only be 2 strings, N multi-line comments, 1 equals sign (=), 1 semi-colon (;)
      # * ignore character if it's in a string
      # * single-line comments are ended by \n
      # * multi-line comments are ended by */

      if is_string || is_single_line_comment || is_multi_line_comment
        if is_string && previous_char != "\\" && char == "\""
          is_string = false
        elsif is_string && second_previous_char == "\\" && previous_char == "\\" && char == "\""
          is_string = false
        elsif is_single_line_comment && char == "\n"
          is_single_line_comment = false
        elsif is_multi_line_comment && previous_char == "*" && char == "/"
          is_multi_line_comment = false
        end
        # Ignore.
      elsif previous_char == nil && char == "/"
        # Ignore.
      elsif previous_char == "/" && char == "/"
        is_single_line_comment = true
      elsif previous_char == "/" && char == "*"
        is_multi_line_comment = true
      elsif !has_seen_equals_sign && char == "="
        has_seen_equals_sign = true
      elsif !has_seen_semi_colon && char == ";"
        has_seen_semi_colon = true
      elsif char == " " ||char == "\n"  || char == "\r"
        # Ignore.
      elsif char == "\""
        is_string = true
      elsif char == "\000"
        # Ignore unicode padding.
      elsif line_number == 1 && previous_char == nil && char == "\377"
        # Ignore unicode file header.
      elsif line_number == 1 && previous_char == nil && char == "\376"
        # Ignore unicode file header.
      else
        puts "#{file} (#{line_number}): #{char}"
      end

      if char != "\000" && char != "\377" && char != "\376"
        # Save previous character if it's not unicode padding.
        second_previous_char = previous_char
        previous_char = char
      end
    end
  end
end

# Iterate through the current directory.
Dir.entries(".").each do |file|
  filename = file.slice(0,file.length-8)
  extension = file.slice(file.length-8,file.length)
  # Only deal with .strings.
  if (extension == ".strings")
    # Read the file and identify any bad characters.
    verify_file(file)
  end
end

One important sidenote is Unicode support. The script works with Unicode characters but not universally. I have two lines to allow complete Unicode support. The first works on most languages, and the second is used for UTF-16 languages, like Japanese (JA).

# Use general method unless file encoding is UTF-16.
file_handle = File.new(file, "r")
# file_handle = File.new(file, "r:UTF-16LE:UTF-8")

Keep in mind that Ruby 1.9 is required because of its Unicode support; refer to the Hivelogic article for compilation instructions. The r:UTF-16LE:UTF-8 code is from this article on Ruby encodings.

“Class mismatch”

One other error I’ve encountered is “class mismatch”. ibtool produces this error when the class of a UI element associated with a specific ObjectID changes. For instance, imagine two languages were modified independently, and both had a UI element added to them. The first might be an NSTextField whereas the second might be an NSMenuItem; however, the IDs might be the same. The two entries in the .strings files would look like so:

/* Class = "NSTextField"; title = "First Text"; ObjectID = "419"; */
/* Class = "NSMenuItem"; title = "Second Text"; ObjectID = "419"; */

Using the first as the base for localization, incoporating the strings into the second wouldn’t make any sense for this UI element. Luckily, ibtool produces the following error when trying to localize those XIBs:

<plist version="1.0">
<dict>
  <key>com.apple.ibtool.errors</key>
  <array>
    <dict>
      <key>description</key>
      <string>Class mismatch during incremental localization for Object ID: 419.  New Base has class: NSTextField.  Old Base has class: NSTextField.  Old Loc has class: NSMenuItem.</string>
    </dict>
  </array>
</dict>
</plist>

08/10/2009 Update: I updated the validation script to account for escaped backslashes, such as "\\"," = "";.