XIB -> XIBH porting process

Chameleon does not (yet!) support NIB loading, so we are using the open source tool nib2objc (https://github.com/akosma/nib2objc) to port over the XIB files from iOS.  The ported files are integrated into the Xcode project as .xibh files, and included in the various source files to build the view hierarchy from code.

There are some limitations to nib2objc (and some bugs, which will be discussed later), which are mainly inherited from ibtool's limitations - most notably:

- it does not assign images to UIButtons or UIImageViews
- it does not setup connections (actions)

These limitations are accounted for in the steps outlined below.


>> Porting process <<

1) Generate the .xibh file.
   Option A - use nib2objc GUI:
	- launch app and open the XIB file
	- export (cmd-s) the file - it automatically adds a .m, so rename it once exported with the xibh extension
   Option B - use nib2objc.pl to do a batch convert
	- from the root Welder folder, run "./nib2objc.pl ./Resources-iPad/"
	- this will generate new xibh files in the "Resources-iPad" directory
	- move those files to "Resources-Mac" 

2) Include the newly generated .xibh file in the corresponding class's (either UIView or UIViewController-based) loadView method.  Call loadView (this is done automatically for UIViewController-based classes) to create the view hierarchy instead of using the nib loading calls.

Eg (for UIView-based):

.
.
        if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPad)
            [[NSBundle mainBundle] loadNibNamed:@"Game-iPad" owner:self options:nil];
        else if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone)
            [[NSBundle mainBundle] loadNibNamed:@"Game" owner:self options:nil];
        else
            [self loadView];
.
.

-(void) loadView
{
#include "Game.xibh"
.
.
.
}

3) After #include of the xibh file, you need to assign the ivars of the class to the local vars created in the xibh file.  These var names are named based on the XIB object id (eg label34, or imageview22).  This can be done by viewing the assignments in the XIB in Xcode, and looking up the object id.

4) Assign the images for the UIImageViews - again this can be done by viewing the UIImageViews in Xcode, obtaining the assigned image name, and assigning it via:

    imageview25.image = [UIImage imageNamed:@"power-plant-bg-ipad.png"];

5) Assign the images for the UIButtons, ala:

    [button274 setImage:[UIImage imageNamed:@"ui-ipad-disable-display-gigawatts.png"] forState:UIControlStateNormal];

6) Create the connections (almost always only for the UIButtons), eg:

    [button237 addTarget:self action:@selector(doPowerPlant) forControlEvents:UIControlEventTouchUpInside];

That's it!


>> Bugs <<

Now, there are a few bugs in nib2objc that need to be accounted for:

1) Occasionally, it will generate a color assignment as:

    label161.textColor = NSCustomColorSpace Generic RGB colorspace 1 1 1 1;

that's obviously not going to compile, so it will have to be replaced with:

    label161.textColor = [UIColor colorWithRed:1.000 green:1.000 blue:1.000 alpha:1.000];

or the equivalent.  Not sure what triggers that bad generation, but there you have it.


2) It doesn't generate the string assignments for multi-line labels nicely - it generates:

    label4.text = @"WATCH OUT... THERE IS A TOXIC TILE ON THE BOARD!
 
    ANY WORDS FORMED BEFORE CLEARING THE TOXIC TILE WILL SCORE NO POINTS.";

which needs to be converted to:

    label4.text = @"WATCH OUT... THERE IS A TOXIC TILE ON THE BOARD!\n\
    \n\
    ANY WORDS FORMED BEFORE CLEARING THE TOXIC TILE WILL SCORE NO POINTS.";


3) The biggest problem is the z-order of the views.  For some reason it occasionally gets that wrong - the "addSubview" calls at the end of the xibh file aren't in the same order as what's defined in the XIB file (I imagine this is a ibtool problem, but I'm not sure).  You'll have to muck with that order if there are obvious issues in your ported view.

One of these days, I'll open up the nib2objc code to see if any of these can be fixed, but until then, these will need to be fixed by hand.
