Before you can display anything on the iPhone screen, you must create a window to hold content, and to build a window, you need a display region. A display region is a fancy term for rectangle and represents the portion of the screen where the window should be displayed. The underlying structure itself is a rectangle structure named CGRect that contains two pieces: the coordinates for the upper-left corner of the window and the window’s size (its width and height). Every object displayed on the screen has a display region defining its display area. Most are set when the object is initialized, via an initWithFrame method. Others must be set after the fact using a ubiquitous method named setFrame. In the case of the main window, the region’s coordinates are offset to the screen itself; however, all subsequent objects (including the window’s view) are offset to the object that contains it. As other objects are nested inside the view, those objects’ regions will be offset to the view, and so on.

An application uses the entire iPhone screen when it is displayed, and so the window should be assigned a set of coordinates reflecting the view region of the entire screen. This region can be obtained from a static method found inside a class named UIHardware.

CGRect windowRect = [ UIHardware fullScreenApplicationContentRect ];

This region, named windowRect above, is then used to create and initialize a new UIWindow object:

UIWindow *window = [ UIWindow alloc ];
[ window initWithContentRect: windowRect ];

The window frame has now been created, but contains nothing. An object that can render content is needed to place inside of it. A UIView object must be created to fill the window. Because a window can only hold one view object, the display region for it should likewise use the entire screen so that it will fill up the entire window.

CGRect viewRect = [ UIHardware fullScreenApplicationContentRect ];
viewRect.origin.x = viewRect.origin.y = 0.0;

UIView *mainView = [ [ MainView alloc ] initWithFrame: viewRect ];

The window and view pair has been created, but the view has not been displayed on the screen. To do this, assign the window and instruct the window to display:

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];

The “Hello, Window!” application flows like this:

The “Hello, World!” example contains everything you’ve seen so far, with the addition of a new view designed to display text:

Now that you have something to look at in your application, play around with it for a little while before proceeding.

Because UITextView is ultimately derived from UIView, it is created in the same fashion as the main view objects created in the last section—using an initWithFrame method.

UITextView *textView = [ [ UITextView alloc ]
    initWithFrame: viewRect ];

Once the view is created, a number of different properties can then be set.

[ textView setEditable: YES ];

[ textView setMarginTop: 20 ];

[ textView setTextSize: 12 ];

[ textView setTextFont:
  @"font-family: Helvetica; font-style: italic; font-weight: bold" ];

CGColorSpaceRef colorSpace =
    CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
float opaqueRed[4] = { 1.0, 0.0, 0.0, 1.0 };
CGColorRef red = CGColorCreate(colorSpace, opaqueRed);
[ textView setTextColor: red ];

Two different methods can set the content of a text view: setText and setHTML. As the name suggests, invoking the setText method causes the content to be displayed as text, while the setHTML treats the content like a web page. If you try to call setText using HTML input, it will appear as HTML source code.

An example of the text display is:

[ textView setText: @"Hello, world!" ];

while HTML can be displayed like this:

[ textView setHTML: @"<b><center>Hello, World!</center></b>" ];

Text views are generally attached to the main view of a window. This allows other subviews, such as navigation bars and controls, to be added to the same parent view later on.

[ mainView addSubview: textView ];

Every iPhone shipped by Apple contains a rather lengthy HTML file containing all of Apple’s legal disclaimers. This is displayed in the legal section of Apple’s Settings application. This example will take this file and display it in a text box.

To compile this application, you’ll need to include the Core Graphics framework, which contains the routines needed to mix colors.

This application, shown in Example 3-5 and Example 3-6, can be built using the tool chain on the following command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
 -framework CoreFoundation -framework Foundation -framework UIKit 
 -framework CoreGraphics

#import <CoreFoundation/CoreFoundation.h>
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
#import <UIKit/UITextView.h>

@interface MainView : UIView
{
        UITextView         *textView;
}

- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;

@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#include <stdio.h>
#import "MyExample.h"

int main(int argc, char **argv)
{
   NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {
        FILE *file;
        char buffer[262144], buf[1024];

        textView = [ [ UITextView alloc ] initWithFrame: rect ];
        [ textView setTextSize: 12 ];

        file = fopen("/Applications/Preferences.app/English.lproj/
legal-disclaimer-iphone.html", "r");

        if (!file) {
            CGColorSpaceRef colorSpace =
                CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB);
            float opaqueRed[4] = { 1.0, 0.0, 0.0, 1 };
            CGColorRef red = CGColorCreate(colorSpace, opaqueRed);
            [ textView setTextColor: red ];

            [ textView setText: @"ERROR: File not found" ];
        } else {
            buffer[0] = 0;
            while((fgets(buf, sizeof(buf), file))!=NULL) {
                strlcat(buffer, buf, sizeof(buffer));
            }
            fclose(file);

            [ textView setHTML:
                [ [ NSString alloc ] initWithCString: buffer ]];
        }

        [ self addSubview: textView ];
    }

    return self;
}

- (void)dealloc
{
    [ self dealloc ];
    [ super dealloc ];
}

@end

The example reads in and displays the contents of a file as follows:

Here are some productive ways to play with this example:

To create a navigation bar, instantiate it as an object and call its initWithFrame method—just like a UIView.

UINavigationBar *navBar = [ [UINavigationBar alloc]
    initWithFrame: CGRectMake(0, 0, 320, 48)
];

The above creates a navigation bar 48 pixels high (the default) at position 0x0 (the upper-left corner of its parent view). This is the general convention, but a navigation bar can be created anywhere within the window. By using a different vertical offset, you can place the navigation bar at the bottom of the window or underneath another navigation bar.

To know when something happens on the navigation bar, such as a button press, use the navigation bar’s delegate. A delegate is an object that acts on behalf of another object. By setting the navigation bar’s delegate to self, you can have it send events such as button presses to the object that created the navigation bar.

[ navBar setDelegate: self ];

Animations are simple fade transitions that occur when transitioning from an old set of buttons to a new set—for example, if a button is changed after it is pressed. Calling enableAnimation uses these smoother transitions instead of an instantaneous change.

[ navBar enableAnimation ];

Once the navigation bar has been created and initialized, its title and buttons can then be configured. These can be changed even after the navigation bar is displayed; the bar will change to accommodate its new settings.

UINavigationItem *navItem = [ [ UINavigationItem alloc ]
    initWithTitle:@"My Example" ];
[ navBar pushNavigationItem: navItem ];

[ navItem setTitle: @"Another Example" ]

[ navBar showLeftButton:@"Good" withStyle: 0
            rightButton:@"Evil" withStyle: 0 ];

[ navBar showLeftButton:nil withStyle: 0
            rightButton:@"Evil" withStyle: 0 ];

[ navBar showButtonsWithLeftTitle:@"Back"
                       rightTitle: nil
                         leftBack: YES ];

[ navBar setBarStyle: 0 ];

Once you’ve laid out the initial look for your navigation bar, it’s time to display it within your application. Navigation bars are attached to a view object, such as the main view you created in the last example.

[ self addSubview: navBar ];

If you would like to hide the navigation bar, just pull it off the view:

[ navBar removeFromSuperview ];

When you’re finished with the navigation bar entirely, it can be disposed of by releasing it. This can be done in the view class’s dealloc method:

[ navBar release ];

At this point, your navigation bar is displayed on the screen, but the buttons do nothing. Earlier, the navigation bar’s delegate was set to self, the calling view. Because the calling view is acting on the navigation bar’s events, it will need the ability to intercept button presses.

To do this, a method named buttonClicked must be overridden. As you’ll see in the coming chapters, many different types of objects have a buttonClicked method, but take different arguments. Objective-C supports polymorphism, which allows the developer to support multiple methods sharing the same name, but with different argument types. The runtime will choose the most appropriate version of the method to call.

As the view class has already been set as the delegate for the navigation bar, it will be receiving all button click events that occur on it. This requires that the view class have a method named buttonClicked accepting the same arguments as if it were the navigation bar itself.

- (void)navigationBar:(UINavigationBar *)navbar
    buttonClicked:(int)button;

The buttonClicked method in the view class gets notified as if it belonged to the navigation bar. It is called with the same arguments that the navigation bar’s buttonClicked method would be called; a pointer to the navigation bar and an integer identifying the button number that was pressed. When using left and right navigation buttons, the value for button is either a 1 or a 0, signifying the left or right button, respectively.

- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button
{
    switch(button) {
        case 1:
            /* Left button handled here */
            break;
        case 0:
            /* Right button handled here */
            break;
    }
}

If at any point you would like to disable an existing navigation bar button, you have two options. You can make another call to one of the show-button methods (showLeftButton or showButtonsWithLeftTitle) using nil to make the button disappear. Alternatively, if you would like the button to remain visible, but be disabled so that the user can’t press it, use the setButton method:

[ navBar setButton: 0 enabled: NO ];

Just as in the buttonClicked method, the button number used here corresponds with either the left (1) or the right (0) button.

Controls are small, self-contained user interface components that can be used by various UIKit classes. They can be glued to many different types of objects, allowing the developer to add additional interaction to a window. One common control found in the navigation bars of Apple’s preloaded applications is the segmented control.

You’ll notice in many preloaded applications that Apple has added buttons to further separate the display of information. For example, the navigation bar in the iTunes WiFi Store application sports “New Releases,” “What’s Hot,” and “Genres” buttons at the top. These further separate the user’s music selection choice. Segmented controls are useful for any such situation where an overabundance of data would best be organized into separate tabs.

An example of setting up such a control with two segments follows:

UISegmentedControl *segCtl = [ [ UISegmentedControl alloc ]
    initWithFrame:CGRectMake(70.0, 8.0, 180.0, 30.0)
    withStyle: 2
    withItems: NULL ];
[ segCtl insertSegment:0 withTitle:@"All" animated: TRUE ];
[ segCtl insertSegment:1 withTitle:@"Missed" animated: TRUE ];
[ segCtl setDelegate:self ];

The control is then added to the navigation bar in the same way the navigation bar was added to the main view, by adding it as a subview. Only this time, the segmented control is added to the navigation bar. This means the offset of the display region is in relation to the navigation bar, not the enclosing view or the window.

[ navBar addSubview: segCtl ];

Each button in a segmented control is referred to as a segment. The selected segment can be accessed with a call to the selectedSegment method of the control itself.

int selectedSegment = [ segCtl selectedSegment ];

Chapter 7 offers more on controls.

Someone is designing a mute button to mute their spouse during arguments. In this example application, a navigation bar will be created in an application’s view and assigned a Mute button. When the button is selected, the button will be changed to red and will also change the title to reflect that the spouse is muted.

Example 3-7 and Example 3-8 can be built using the tool chain on the following command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
    -framework CoreFoundation -framework Foundation -framework UIKit

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <UIKit/UINavigationBar.h>
#import <UIKit/UINavigationItem.h>

@interface MainView : UIView
{
        UINavigationBar  *navBar;     /* Our navigation bar */
        UINavigationItem *navItem;    /* Navigation bar title */
        BOOL              isMuted;    /* Is mute turned on? */
}

- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;
- (UINavigationBar *)createNavBar:(CGRect)rect;
- (void)setNavBar;
- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button;
@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {
        isMuted = NO;

        navBar = [ self createNavBar: rect ];

        /* Update the navBar for the first time */
        [ self setNavBar ];

        [ self addSubview: navBar ];
    }

    return self;
}

- (void)dealloc
{
    [ navBar release ];
    [ navItem release ];
    [ self dealloc ];
    [ super dealloc ];
}

- (UINavigationBar *)createNavBar:(CGRect)rect {
    UINavigationBar *newNav = [ [UINavigationBar alloc]
      initWithFrame:
      CGRectMake(rect.origin.x, rect.origin.y, rect.size.width, 48.0)
    ];

    [ newNav setDelegate: self ];
    [ newNav enableAnimation ];

    /* Add our title */
    navItem = [ [UINavigationItem alloc]
        initWithTitle:@"My Example" ];
    [ newNav pushNavigationItem: navItem ];

    return newNav;
}

- (void)setNavBar
{
    if (isMuted == YES) {
        [ navItem setTitle: @"Spouse (Muted)" ];
        [ navBar showLeftButton:nil withStyle: 0
                   rightButton:@"Mute" withStyle: 1 ];
    } else {
        [ navItem setTitle: @"Spouse" ];
        [ navBar showLeftButton:nil withStyle: 0
                    rightButton:@"Mute" withStyle: 0 ];
    }
}

- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button
{
    if (button == 0) /* Right button */
    {
        if (isMuted == YES) /* Toggle isMuted */
            isMuted = NO;
        else
            isMuted = YES;

        [ self setNavBar ]; /* Update navbar buttons */
    }
}

@end

This example shows you how to accomplish the user-interface portion of this application. You’ll have to write the source code to do the actual spouse muting yourself. Here’s how the example works:

With the example snippets from this section and the previous examples, try having a little fun with this example:

Transition views inherit from UIView, so they have most of the properties of a regular view, including a frame. To create a transition, the display region belonging to the view is passed to the transition’s initWithFrame method.

UITransitionView *transitionView = [ [ UITransitionView alloc ]
    initWithFrame: viewRect ];

The same transition view can be used for multiple transition calls and even multiple transition types, so generally only one transition view is needed for a particular display region. If a navigation bar is being used, you must account for its presence by subtracting its height and coordinates from the transition view’s display region:

UITransitionView *transitionView = [ [ UITransitionView alloc ]
     initWithFrame:
     CGRectMake(viewRect.origin.x, viewRect.origin.y + 48.0,
            viewRect.size.width, viewRect.size.height − 48.0
];

Once the transition has been created, it is added to the view in the same way as other view objects, as a sublayer.

[ self addSubview: transitionView ];

To effect a transition, call the class’s transition method. You’ll supply the transition style and pointers to the two views between which you are transitioning.

[ transitionView transition: 0
  fromView: myOldView
  toView: myNewView
];

Alternatively, a transition can be called supplying only the new view, not the old one. But be forewarned that this appears to work with only some transitions. Those that do not support this behavior automatically default to using no transition.

[ transitionView transition: 0 toView: myNewView ];

UIKit presently supports 10 distinct transitions. A single transition view can be called repeatedly with different styles, listed in the following table. This allows developers to choose the best transition depending on the particular action at hand, without having to worry about creating a new object for every possible transition they might want to perform.

The best example of using page transitions is to illustrate reading a book. In this example, 10 pages of text are created using the UITextView object covered earlier in this chapter. Using a navigation bar, the user is presented with two buttons to navigate to the previous or next page. Depending on which direction the user has chosen, a different transition is used. When the user reached either end of the book, the corresponding navigation button is disabled to keep them from going any further.

Example 3-9 and Example 3-10 can be compiled using the tool chain on the following command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
    -framework CoreFoundation -framework Foundation -framework UIKit

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <UIKit/UINavigationBar.h>
#import <UIKit/UINavigationItem.h>
#import <UIKit/UITransitionView.h>
#import <UIKit/UITextView.h>

#define MAX_PAGES 10

@interface MainView : UIView
{
    UINavigationBar    *navBar;    /* Our navigation bar */
    UINavigationItem   *navItem;   /* Navigation bar title */
    UITransitionView   *transView; /* Our transition */
    int                pageNum;    /* Current page number */

    /* Some pages to scroll through */
    UITextView         *textPage[MAX_PAGES];
}

- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;
- (UINavigationBar *)createNavBar:(CGRect)rect;
- (void)setNavBar;
- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button;
- (void)flipTo:(int)page;

@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {
        CGRect viewRect;
        int i;

        /* Create a new view port below the navigation bar */
        viewRect = CGRectMake(rect.origin.x, rect.origin.y + 48.0,
            rect.size.width, rect.size.height - 48.0);

        /* Set our start page */
        pageNum = MAX_PAGES / 2;

        /* Create ten UITextView objects as pages in our book */

        for(i=0;i<MAX_PAGES;i++) {
            textPage[i] = [ [ UITextView alloc ]
                initWithFrame: rect ];
            [ textPage[i] setText: [ [ NSString alloc ]
                initWithFormat: @"Some text for page %d", i+1 ] ];
        }

        /* Create a navigation bar with 'Prev' and 'Next' buttons */
        navBar = [ self createNavBar: rect ];
        [ self setNavBar ];
        [ self addSubview: navBar ];

        /* Create our transition view */
        transView = [ [ UITransitionView alloc ]
                initWithFrame: viewRect ];
        [ self addSubview: transView ];

        /* Transition to the first page */
        [ self flipTo: pageNum ];
    }

    return self;
}

- (void)dealloc
{
    [ navBar release ];
    [ navItem release ];
    [ self dealloc ];
    [ super dealloc ];
}

- (UINavigationBar *)createNavBar:(CGRect)rect {
    UINavigationBar *newNav = [ [UINavigationBar alloc]
      initWithFrame:
      CGRectMake(rect.origin.x, rect.origin.y, rect.size.width, 48.0)
    ];

    [ newNav setDelegate: self ];
    [ newNav enableAnimation ];

    /* Add our title */
    navItem = [ [UINavigationItem alloc]
        initWithTitle:@"My Example" ];
    [ newNav pushNavigationItem: navItem ];

    [ newNav showLeftButton:@"Prev"  withStyle: 0
                rightButton:@"Next" withStyle: 0 ];

    return newNav;
}

- (void)setNavBar
{

    /* Enable or disable our page buttons */

    if (pageNum == 1)
        [ navBar setButton: 1 enabled: NO ];
    else
        [ navBar setButton: 1 enabled: YES ];

    if (pageNum == MAX_PAGES)
        [ navBar setButton: 0 enabled: NO ];
    else
        [ navBar setButton: 0 enabled: YES ];
}

- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button
{
    /* Next Page */
    if (button == 0)
    {
        [ self flipTo: pageNum+1 ];
    }

    /* Prev Page */
    else {
        [ self flipTo: pageNum−1 ];
    }

}

- (void)flipTo:(int)page {
    int transitionNum; /* What transition number should be used? */

    if (page < pageNum)
        transitionNum = 2;
    else if (page > pageNum)
        transitionNum = 1;
    else
        transitionNum = 0;

    [ transView transition: transitionNum
      fromView: textPage[pageNum−1] toView: textPage[page−1] ];

    pageNum = page;

    [ self setNavBar ];
}

@end

Here’s how the page-flipping example works:

Here are some productive things you can do with the page-flipping example:

The alert sheet is an object that can be instantiated on top of any view, and a single view can host a number of different alert sheets. A basic alert sheet consists of a title, body text, and whatever choices the user should be presented with. It is instantiated in the same way as other UIView objects, using an initWithFrame method. Because alert sheets appear at the bottom, the window’s origin can begin halfway down the screen (Y = 240).

UIAlertSheet *alertSheet = [ [ UIAlertSheet alloc ]
    initWithFrame: CGRectMake(0, 240, 320, 240) ];
[ alertSheet setTitle:@"Computer doesn't like people" ];
[ alertSheet setBodyText: [ NSString stringWithFormat:
    @"I did not complete your request because I don't like humans." ]
];
[ alertSheet setDelegate: self ];

Alert sheets can stretch their frame to accommodate whatever elements it’s required to hold, so a static 320×240 rectangle should be sufficient for standard alert sheets.

Like navigation bars, alert sheets can be set to support one of three different styles.

The style can be set with a call to setAlertSheetStyle.

[ alertSheet setAlertSheetStyle: 0 ];

On rare occasion, it makes sense to display an alert sheet without buttons—for example, to display a progress bar (explained in Chapter 7). In most cases, however, alert sheets are displayed for the purpose of prompting the user. An alert sheet can accommodate as many buttons as can fit on the screen. To add a button, call the alert sheet’s addButtonWithTitle method:

[ alertSheet addButtonWithTitle:@"OK" ];

[ alertSheet setDestructiveButton: [ alertSheet
               addButtonWithTitle:@"Confirm Delete" ] ];

Once you’ve set up the text and buttons to be displayed, you can then display the sheet to the user. Five different methods can be called depending on the behavior desired. Each of these methods accepts a class derived as a UIView, which should be a pointer to whatever view class affected by the alert sheet.

[ alertSheet presentSheetFromAboveView: myView ];
[ alertSheet presentSheetFromBehindView: myView ];
[ alertSheet presentSheetFromButtonBar: buttonBar ];
[ alertSheet presentSheetInView: myView ];
[ alertSheet presentSheetToAboveView: myView ];

The most common way to call an alert sheet is with presentSheetInView, which can be called from within a view using self as an argument.

When the alert sheet has been displayed, control returns to the program. As seen earlier in the chapter, many objects use a callback method named buttonClicked whenever the user taps a button. This allows the application to continue running in the background, to be interrupted only when something actually happens.

The prototype for the alert sheet callback method is below. If the alert sheet’s delegate has been set to the calling view, it is the calling view that will be expected to respond to a button click.

- (void)alertSheet:(UIAlertSheet *)sheet buttonClicked:(int)button;

The buttonClicked method is called with a pointer to the selected sheet and the index of the button. Buttons are numbered from topmost position to bottom, beginning with 1 (they are not zero-indexed like other values).

- (void)alertSheet:(UIAlertSheet *)sheet buttonClicked:(int)button {
    if (sheet == alertSheet) {
        switch(button) {
            case 1:
                /* Top-most button was clicked */
                break;
            case 2:
                /* Second-to-top button was clicked */
                break;
        }
    }
}

Finally, after processing a button press, the alert sheet should vanish—unless, of course, the application has a reason for the user to press more than one button. Use the dismiss method to make the sheet go away:

[ sheet dismiss ];

The government thought it would be more convenient for the President to carry an iPhone around instead of a suitcase with a big red button. One of their chief programmers conveniently wrote End-of-the-World.app, which the President can press at any time to launch nukes and end the world (or at least start a pie fight). The problem, however, is that he’s almost pressed it accidentally many times. You’ve been contracted to add a confirmation sheet to it—just in case the President didn’t really mean to end the world.

Our example application displays a navigation bar with an End World button. When pressed, it will first confirm before ending the world as we know it. Polymorphism will be illustrated with the presence of two buttonClicked methods. When the navigation bar’s button is pressed, the correct buttonClicked method will be automatically called.

Example 3-11 and Example 3-12 can be built using the tool chain on the following command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m -lobjc 
    -framework CoreFoundation -framework Foundation -framework UIKit

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import <UIKit/UIAlertSheet.h>
#import <UIKit/UINavigationBar.h>

@interface MainView : UIView
{
    UIAlertSheet    *endWorldSheet;
    UIAlertSheet    *deniedSheet;
    UINavigationBar *navBar;
}

- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;
@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
   NSAutoreleasePool *autoreleasePool = [
        [ NSAutoreleasePool alloc ] init
    ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {

        /* Create a button to end the world */

        navBar = [ [UINavigationBar alloc] initWithFrame:
            CGRectMake(rect.origin.x, rect.origin.y, rect.size.width, 48.0f)
        ];
        [ navBar setDelegate: self ];
        [ navBar enableAnimation ];
        [ navBar showLeftButton:nil withStyle: 0
                    rightButton:@"End World" withStyle: 1 ];

        [ self addSubview: navBar ];
    }

    return self;
}

- (void)alertSheet:(UIAlertSheet *)sheet buttonClicked:(int)button
{
    if (sheet == endWorldSheet) {
        if (button == 1) {

            /* Oops, Access Denied */
            deniedSheet = [ [ UIAlertSheet alloc ] initWithFrame:
                CGRectMake(0, 240, 320, 240)
            ];
            [ deniedSheet setTitle: @"Access Denied" ];
            [ deniedSheet setBodyText: @"Sorry, you must be super-user to
end the world" ];
            [ deniedSheet addButtonWithTitle:@"OK" ];
            [ deniedSheet setDelegate: self ];
            [ deniedSheet presentSheetInView: self ];
        }
    }

    [ sheet dismiss ];
}

- (void)navigationBar:(UINavigationBar *)navbar buttonClicked:(int)button
{
    /* Ask about the end of the world */

    endWorldSheet = [ [ UIAlertSheet alloc ] initWithFrame:
        CGRectMake(0, 240, 320, 240)
    ];
    [ endWorldSheet setTitle: @"Please Confirm" ];
    [ endWorldSheet setBodyText:@"I noticed you are trying to end the world.
Are you sure you want to do this?" ];
    [ endWorldSheet setDestructiveButton:
        [ endWorldSheet addButtonWithTitle:@"End World" ]
    ];
    [ endWorldSheet addButtonWithTitle:@"Cancel" ];
    [ endWorldSheet setDelegate: self ];
    [ endWorldSheet presentSheetInView: self ];

}


- (void)dealloc
{
    [ self dealloc ];
    [ super dealloc ];
}

@end

The process flow for this program works in the following fashion.

Play around with alert sheets for a bit to get a feel for how they work:

A table has three primary components: the table itself, table columns, and table cells (the individual rows in a table). The table’s data is queried from a table’s data binding. A data binding is an interface used by the table to query information about what data to display, such as filenames, email messages, etc. The data source is an object that responds to this query. When the table is created, a data source must be attached to it in order for the table to display anything. It gets called whenever the table is reloaded or new cells are scrolled into view and tells the table which columns and rows to display, along with the data within them.

@interface MyTable : UITable
{

}
-(id)initWithFrame:(struct CGRect)rect;
-(void) dealloc;

- (int)numberOfRowsInTable:(UITable *)_table;
- (UITableCell *)table:(UITable *)table
    cellForRow:(int)row
    column:(UITableColumn *)col;

- (id)initWithFrame:(struct CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {

        /* Add additional initialization code here */
    }
}

        UITableColumn *myColumn = [ [ UITableColumn alloc ]
            initWithTitle: @"Column 1"
            identifier:@"column1"
            width: rect.size.width
        ];
        [ self addTableColumn: myColumn ];

        [ self setDataSource: self ];

- (void)dealloc {
    [ myColumn release ];
    [ super dealloc ];
}

- (int)numberOfRowsInTable:(UITable *)_table {
    return 3;
}

- (UITableCell *)table:(UITable *)table
  cellForRow:(int)row
  column:(UITableColumn *)col
{
    UISimpleTableCell *cell = [ [ UISimpleTableCell alloc ] init ];
    NSString *title;

    title = [ [ NSString alloc ] initWithFormat: @"Row %d", row ];
    [ cell setTitle: title ];
    return [ cell autorelease ];
}

UIWebViewLabel *label = [ [ UIWebViewLabel alloc ] initWithFrame:
    CGRectMake(0.0, 3.0f, 320.0, 20.0) ];
[ label setText: @"My UIWebView" ];
[ cell addSubview: label ];

[ cell setShowDisclosure: YES ];

[ cell setDisclosureStyle: 0 ];

UIImageAndTextTableCell *cell =
    [ [ UIImageAndTextTableCell alloc ] init ];
UIImageView *image = [ [ UIImage alloc ]
    initWithContentsOfFile: @"/path/to/file.png" ];
[ cell setTitle: @"My row, now with image!" ];
[ cell setImage: image ];
 return [ cell autorelease ];

[ cell setAlignment: 2 ];

[ self setRowHeight: 64 ];

- (int)swipe:(int)type withEvent:(struct _  _GSEvent *)event;
{
    CGPoint point = GSEventGetLocationInWindow(event);
    CGPoint offset = _startOffset;

    point.x += offset.x;
    point.y += offset.y;
    int row = [ self rowAtPoint:point ];

    [ [ self visibleCellForRow: row column:0 ]
       _showDeleteOrInsertion: YES
       withDisclosure: NO
       animated: YES
       isDelete: YES
       andRemoveConfirmation: YES
    ];

    return [ super swipe:type withEvent:event ];
}

- (void)_willDeleteRow:(int)row
    forTableCell:(id)cell
    viaEdge:(int)edge
    animateOthers:(BOOL)animate
{
    /* Perform any additional deletion operations here */

    [ fileList removeObjectAtIndex: row ];
    [ super _willDeleteRow: row
        forTableCell: cell
        viaEdge: edge
        animateOthers: animate
    ];
}

- (void)tableRowSelected:(NSNotification *)notification
{
    int index = [ self selectedRow ];

    /* A file was selected. Do something here. */
}

In this example, we create a custom UITable class for general use as a file browser. The browser reads a directory supplied by caller, using its setPath method, and displays all of the files downwind of it matching a file extension also supplied by the caller, using its setExtension method. The swipe-to-delete functionality has been added for the sake of the example, but (in order to prevent you from trashing files by mistake while experimenting with the example) it deletes the item only from the list, not from the iPhone’s filesystem.

This example can be easily added to any iPhone application to display lists of files by including the following code in an application’s view class:

#import "FileTable.h"

FileTable *fileTable = [ [ FileTable alloc ] initWithFrame: rect ];
[ fileTable setPath: @"/Applications" ];
[ fileTable setExtension: @"app" ];
[ fileTable reloadData ];
[ self addSubview: fileTable ];

A complete application, shown in Example 3-13 through Example 3-18, can be compiled from the tool chain using the following command line:

$ arm-apple-darwin-gcc -o MyExample MyExample.m FileTable.m DeletableCell.m 
    -lobjc -framework CoreFoundation -framework Foundation -framework UIKit

#import <CoreFoundation/CoreFoundation.h>
#import <UIKit/UIKit.h>
#import "FileTable.h"

@interface MainView : UIView
{
        FileTable *fileTable;
}
- (id)initWithFrame:(CGRect)frame;
- (void)dealloc;
@end

@interface MyApp : UIApplication
{
    UIWindow *window;
    MainView *mainView;
}
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification;
@end

#import "MyExample.h"

int main(int argc, char **argv)
{
    NSAutoreleasePool *autoreleasePool = [ [ NSAutoreleasePool alloc ] init ];
    int returnCode = UIApplicationMain(argc, argv, [ MyApp class ]);
    [ autoreleasePool release ];
    return returnCode;
}

@implementation MyApp

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    window = [ [ UIWindow alloc ] initWithContentRect:
        [ UIHardware fullScreenApplicationContentRect ]
    ];

    CGRect rect = [ UIHardware fullScreenApplicationContentRect ];
    rect.origin.x = rect.origin.y = 0.0f;

    mainView = [ [ MainView alloc ] initWithFrame: rect ];

    [ window setContentView: mainView ];
    [ window orderFront: self ];
    [ window makeKey: self ];
    [ window _setHidden: NO ];
}
@end

@implementation MainView
- (id)initWithFrame:(CGRect)rect {

    if ((self == [ super initWithFrame: rect ]) != nil) {

        fileTable = [ [ FileTable alloc ] initWithFrame: rect ];
        [ fileTable setPath: @"/Applications" ];
        [ fileTable setExtension: @"app" ];
        [ fileTable reloadData ];
        [ self addSubview: fileTable ];
    }

    return self;
}

- (void)dealloc
{
    [ self dealloc ];
    [ super dealloc ];
}
@end

#import <UIKit/UIKit.h>
#import <UIKit/UISimpleTableCell.h>
#import <UIKit/UIImageAndTextTableCell.h>
#import <UIKit/UITableColumn.h>
#import <UIKit/UIImage.h>
#import <GraphicsServices/GraphicsServices.h>

@interface FileTable : UITable
{
    NSString *path;
    NSString *extension;
    NSMutableArray *fileList;
    UITableColumn *colFilename;
    UITableColumn *colType;
}
- (id)initWithFrame:(struct CGRect)rect;
- (void)setPath:(NSString *)_path;
- (void)setExtension:(NSString *)_extension;
- (void)reloadData;
- (int)swipe:(int)type withEvent:(struct _  _GSEvent *)event;
- (int)numberOfRowsInTable:(UITable *)_table;
- (UITableCell *)table:(UITable *)table
    cellForRow:(int)row
    column:(UITableColumn *)col;
- (void)_willDeleteRow:(int)row forTableCell:(id)cell viaEdge:(int)edge
animateOthers:(BOOL)animate;
- (void)dealloc;
@end

#import "FileTable.h"
#import "DeletableCell.h"

@implementation FileTable

- (id)initWithFrame:(struct CGRect)rect {
    if ((self == [ super initWithFrame: rect ]) != nil) {

        colFilename = [ [ UITableColumn alloc ]
            initWithTitle: @"Filename"
            identifier:@"filename"
            width: rect.size.width - 75
        ];
        [ self addTableColumn: colFilename ];

        colType = [ [ UITableColumn alloc ]
            initWithTitle: @"Type"
            identifier:@"type"
            width: 75
        ];
        [ self addTableColumn: colType ];

        [ self setSeparatorStyle: 1 ];
        [ self setDelegate: self ];
        [ self setDataSource: self ];
        [ self setRowHeight: 64 ];

        fileList = [ [ NSMutableArray alloc] init ];
    }

    return self;
}

- (void) setPath:(NSString *)_path {
    path = [ _path copy ];
}

- (void) setExtension:(NSString *)_extension {
    extension = [ _extension copy ];
}

- (void) reloadData {
    NSFileManager *fileManager = [ NSFileManager defaultManager ];
    NSDirectoryEnumerator *dirEnum;
    NSString *file;

    if ([ fileManager fileExistsAtPath: path ] == NO) {
        return;
    }

    [ fileList removeAllObjects ];

    dirEnum = [ [ NSFileManager defaultManager ] enumeratorAtPath: path ];
    while ((file = [ dirEnum nextObject ])) {
        if ([ file hasSuffix: extension ] == YES) {
            [ fileList addObject: file ];
        }
    }

    [ super reloadData ];
}

- (int)numberOfRowsInTable:(UITable *)_table {
    return [ fileList count ];
}

- (UITableCell *)table:(UITable *)table
  cellForRow:(int)row
  column:(UITableColumn *)col
{
    if (col == colFilename) {
        DeletableCell *cell = [ [ DeletableCell alloc ] init ];
        [ cell setTable: self ];

        UIImageView *image = [ [ UIImage alloc ]
            initWithContentsOfFile:
            [ [ NSString alloc ]
               initWithFormat: @"/Applications/%@/icon.png",
                   [ fileList objectAtIndex: row ] ] ];
        [ cell setTitle: [ [ fileList objectAtIndex: row ]
        stringByDeletingPathExtension ]];
        [ cell setImage: image ];
        [ cell setShowDisclosure: YES ];
        [ cell setDisclosureStyle: 3 ];
        return [ cell autorelease ];
    } else if (col == colType) {
        DeletableCell *cell = [ [ DeletableCell alloc ] init ];
        [ cell setTable: self ];
        [ cell setTitle: extension ];
        return [ cell autorelease ];
    }
}

- (int)swipe:(int)type withEvent:(struct _  _GSEvent *)event;
{
    CGPoint point= GSEventGetLocationInWindow(event);
    CGPoint offset = _startOffset;

    if (point.x < 100 || point.x > 200) {
        point.x += offset.x;
        point.y += offset.y;
        int row = [ self rowAtPoint:point ];

        [ [ self visibleCellForRow: row column: 1 ]
           _showDeleteOrInsertion: YES
           withDisclosure: NO
           animated: YES
           isDelete: YES
           andRemoveConfirmation: YES
        ];

        return [ super swipe:type withEvent:event ];
    }
}

- (void)_willDeleteRow:(int)row
    forTableCell:(id)cell
    viaEdge:(int)edge
    animateOthers:(BOOL)animate
{
    [ fileList removeObjectAtIndex: row ];
    [ super _willDeleteRow: row forTableCell: cell viaEdge: edge
      animateOthers: animate ];
}

- (void)tableRowSelected:(NSNotification *)notification {
    NSString *fileName = [ fileList objectAtIndex: [ self selectedRow ] ];

    /* A file was selected. Do something here. */
}

- (void)dealloc {
    [ colFilename release ];
    [ colType release ];
    [ fileList release ];
    [ super dealloc ];
}
@end

#import "FileTable.h"

@interface DeletableCell : UIImageAndTextTableCell
{
    FileTable *table;
}
- (void)setTable:(FileTable *)_table;

@end

#import "DeletableCell.h"

@implementation DeletableCell

- (void)removeControlWillHideRemoveConfirmation:(id)fp8
{
    [ self _showDeleteOrInsertion:NO
          withDisclosure:NO
          animated:YES
          isDelete:YES
          andRemoveConfirmation:YES
    ];
}

- (void)_willBeDeleted
{
    int row = [ table _rowForTableCell: self ];

    /* Do something; this row is being deleted */
}

- (void)setTable:(FileTable *)_table {
    table = _table;
}
@end

The FileTable class works like this:

Try some of these exercises to test your knowledge of tables:

The status bar mode determines its color, opacity, and orientation. It can also be used to animate the status bar when transitioning between different modes. To set the mode, one of four different setStatusBarMode methods can be used from within the instance of your application, a UIApplication object.

- (void)setStatusBarMode:(int)mode duration:(float)duration
- (void)setStatusBarMode:(int)mode orientation:(int)orientation
    duration:(float)duration
- (void)setStatusBarMode:(int)mode orientation:(int)orientation
    duration:(float)duration fenceID:(int)fenceID
- (void)setStatusBarMode:(int)mode orientation:(int)orientation
    duration:(float)duration fenceID:(int)fenceID
    animation:(int)animation;

If you’re planning on removing the status bar for a particular purpose, its size must be altered to release the screen space to other views. The status bar size can be set using the UIHardware class.

To remove the status bar entirely, set its height to zero:

[ UIHardware _setStatusBarHeight: 0.0 ];
[ self setStatusBarMode:2 duration: 0 ];

To restore it:

[ UIHardware _setStatusBarHeight: 20.0 ];
[ self setStatusBarMode:0 duration: 0 ];

Images can be placed on the status bar to notify the user that your application is in a particular state, such as playing music or being logged in to a chat room. Images remain on the status bar even when your application has exited, allowing the user to be notified of future events, such as an alarm. If your application exits prematurely, the image can be automatically removed.

Status bar images are controlled by the SpringBoard application. This makes for a slightly complicated setup in that your application will need to copy the images you use into SpringBoard’s program folder (and restart SpringBoard) before they will work.

Two files are needed to correctly display a status bar image: one for the white status bar and one for the black. Depending on what application is running, the status bar used will automatically switch to the appropriate image.

# launchctl stop com.apple.SpringBoard

[ UIApp addStatusBarImageNamed: @"NAME" removeOnAbnormalExit: YES ];

[ UIApp removeStatusBarImageNamed: @"NAME" ];

Application badges are one of the easier features to take advantage of, requiring only one call to the UIApplication class.

 [ UIApp setApplicationBadge: @"Hi!" ];

The setApplicationBadge method takes an NSString object, which can be built with standard string formatting.

NSString *badgeText = [ [ NSString alloc ]
    initWithFormat:@"%d", numNewMessages ];
[ UIApp setApplicationBadge: badgeText ];

An application badge should be removed when the user has clicked to the page with the important events they were being notified about. Removing the application badge is also an easy task. A good place to put such code is after transitioning to the view with the events. For example:

[ transitionView transition: 0 toView: missedCalls ];
[ UIApp removeApplicationBadge ];

An application badge will continue to hang around even after an application has terminated. This can be useful, but it’s not always what you want. If an application badge should be removed when the program exits, you’ll also need to make a call to removeApplicationBadge in the application’s applicationWillTerminate method.

- (void)applicationWillTerminate {
    /* We are about to exit, so remove the application badge */
    [ UIApp removeApplicationBadge ];
}

You’ll learn more about this kind of application state control in the next section.

Before going on to learn some of the situations in which application badges can help improve your application’s response to state changes, do a little exploration:

When the home button is pressed, the default behavior for an application is to suspend. It’s also told to suspend during a phone call or when the screen is locked. When this happens, the application’s suspend methods are called.

Depending on the nature of the event, three different suspend methods might be called.

Because one method picks up the slack for others, most applications can service all suspend events by simply overriding applicationSuspend.

- (void)applicationSuspend:(struct _  _GSEvent *)event {
    /* We're about to suspend, so do something here */
}

Resources are always a concern with the iPhone, as memory and battery life are finite. If the application doesn’t need to run in the background and there’s no reason to keep the state of the application, it may make sense to just terminate instead of suspending. The iPhone is smart enough to restart the last application being used, so the user might not even know the difference.

- (void)applicationSuspend:(struct _  _GSEvent *)event {
    [ self terminate ];
}

It may also be appropriate to suspend or terminate depending on the state of the application. For example, if the application is an instant messaging client, it makes sense to suspend only if it’s got a live connection to a server, so that it continue running in the background and maintain the connection. If the user is logged out, there’s no reason to stay alive, and so terminating makes more sense.

- (void)applicationSuspend:(struct _  _GSEvent *)event {
    if (connected == NO) {
        [ self terminate ];
    }else {
        /* Set away in IM Client */
    }
}

When the application is suspended, it’s simply moved to the background and can continue to run. If a separate thread is running to check for new events, such as new instant messages, it is still able to communicate with the process and even send sound events to alert the user (discussed in Chapter 6).

When an application is brought back to a run state, another set of methods are called to prepare the application after it has been brought back to life. These can be overridden to check (and reestablish) connectivity or perform other tasks.

The same three methods used earlier to handle different types of suspends also have complementary resume methods.

The resume methods are overridden in the same way as their suspend counterparts.

-   (void)applicationDidResume {

    /* We've resumed. Do something */
}

Unless an application terminates itself, it’s generally not terminated unless the iPhone is being shut down. Because most good applications do terminate themselves (rather than suspend), it’s a good idea to override the termination method just before an application terminates.

The applicationWillTerminate method is called whenever an application is about to be cleanly terminated. It is not called when an application is killed by holding down the home button. This method should perform any remaining cleanup of resources, make sure all connections are properly closed, and any other tasks necessary before the program exits.

- (void)applicationWillTerminate {
    /* We're about to exit, so do something */
}

Here are some other ways you can play with the various application services: