By default, the title text comes from the Title property of the UIViewController that is topmost on the view stack (the currently displayed one). However, you can also set it directly via the Title property on the navigation controller's NavigationItem. See Listing 8-3.

this.NavigationItem.Title = "Customizing Nav Bar";

Setting it directly is useful when you want it to differ from title text that appears elsewhere, such as when you're using the tab bar controller, which we'll explore later.

The navigation bar itself can be set to one of two styles, Default, or Black, which are included in the UIBarStyle enumeration. See Figure 8-4.

Figure 8.5. Default and Black navigation bar styles

Default gives the bar and its buttons a gray-blue theme, and Black gives the bar and its buttons a black/dark-gray theme. To set the style, set the BarStyle property of the navigation bar to a value from the UIBarStyle enumeration (see Listing 8-4).

this.NavigationController.NavigationBar.BarStyle = UIBarStyle.Black;

In addition to the two color choices in the BarStyle property, you can set the navigation bar to use a specific color via the TintColorProperty. See Figure 8-6.

Figure 8.6. Custom tint color for the navigation bar

For example, Listing 8-5 sets the bar tint color to be red.

this.NavigationController.NavigationBar.TintColor = UIColor.Red;

To reset the color back to the default, simply set the TintColor property to null.

You can specify the navigation bar to take on a partially transparent quality by setting the Translucent property to true (see Listing 8-6).

this.NavigationController.NavigationBar.Translucent = true;

However, when you do this, the content view area of the navigation controller is enlarged to also include the top bar area; so if you have any controls at the top of the view, they will appear behind the top bar! To account for this, make sure to leave extra room at the top of your view. If you're designing your view in Interface Builder, you can set the Top Bar property of the Simulated User Interface Elements section to Translucent Black Navigation Bar to see what this looks like.

In addition to the Back button and the title on the navigation bar, you can add a custom button to the right-hand portion of the bar. This is especially useful if you want to add an Edit button or the like. To set the button, call the SetRightBarButtonItem on the navigation item and pass in a UIBarButtonItem, and determine whether you want it to animate on or off (via a fade). You can either use a custom UIBarButtonItem, or you can use one of the built-in ones via the UIBarButtonSystemItem enumeration as shown in Listing 8-7.

this.NavigationItem.SetRightBarButtonItem(
        new UIBarButtonItem(UIBarButtonSystemItem.Action, null), true);

To remove the button, call the method again, but pass in a null for the button (see Figure 8-8).

this.NavigationItem.SetRightBarButtonItem(null, true);

The tab bar picks up the tab bar item information from each controller you add to it via the TabBarItem property. When creating tab bar items, you can create them from built-in system items, or you can create them from scratch, specifying the title text and the image. You can find the available system items in the UITabBarSystemItem enumeration.

Once you've defined your custom tab bar controller, using it is very easy. Simply instantiate it and then add its view to your window or view, just as you would if you were using a navigation controller. For example, the example application delegate in Listing 8-12 uses the custom tab bar controller we defined as the root view controller on a window.

public class AppDelegate : UIApplicationDelegate
{
        protected UIWindow _window;
        protected MyTabBarController _tabs;

        ...
        public override bool FinishedLaunching (UIApplication app, NSDictionary options)
        {
                //---- create our window
                this._window = new UIWindow (UIScreen.MainScreen.Bounds);
                this._window.MakeKeyAndVisible ();

                this._tabs = new MyTabBarController();
                this._window.AddSubview (this._tabs.View);

                return true;
        }
}

As mentioned before, the tab bar controller supports user rearranging of the tabs out of the box. This is accomplished via the CustomizableViewControllers property of the tab bar controller. Any controllers that are a part of this collection are reorderable. If you don't set this property directly, it automatically gets its values from the ViewControllers property. If you want to make only a subset of your tabs rearrangeable, then you need to specify which ones are customizable. For example, Listing 8-13 specifies that only the third and fourth items in the view controllers should be customizable.

var customizableControllers = new UIViewController[] {
        viewControllers[2],
        viewControllers[3]
};
this.CustomizableViewControllers = customizableControllers;

The tab bar controller allows you to add a badge to tab bar items in order to bubble up information to the user that pertains to that particular tab. The badges show up as a red circle with white text on the upper-right portion of the tab icon. See Figure 8-10.

Figure 8.10. Badges on tab bar items

To specify a badge value, the tab bar item exposes a property called BadgeValue that takes a string. See Listing 8-14.

myController.TabBarItem.BadgeValue = "3";

Simply set your value to that property and a badge will appear on the tab bar item.

If you're using Interface Builder to create your master and detail view controllers, it will automatically size your views appropriately if you change the Split View setting in the Simulated User Interface Elements in the Attributes Inspector. See Figure 8-13.

Figure 8.13. Changing the Split View setting will automatically resize your view in Interface Builder

That way, your view is automatically sized to simulate the actual size it will be in the split view.

Out of the box, the split view doesn't automatically add the button to your detail view that shows the master view. However, it does provide an event that gives you a button that is already wired up to show the view in a popover controller. In order to use this button, you should first define a place for it in your detail view, and then provide a method to add the button to that place. For example, in Listing 8-16, I put a toolbar at the top of the detail view, and then provided the following methods to add and remove the button.

public void AddContentsButton (UIBarButtonItem button)
{
        button.Title = "Contents";
        this.tlbrTop.SetItems(new UIBarButtonItem[] { button }, false );
}
public void RemoveContentsButton ()
{
        this.tlbrTop.SetItems(new UIBarButtonItem[0], false);
}

How and where you add the button is your choice, but for consistency purposes, it's a good idea to show it in the upper left corner.

Next, in your split view controller, you should handle the WillHideViewController and WillShowViewController events to call the methods that you define in your detail view controller.

this.WillHideViewController += (object sender, UISplitViewHideEventArgs e) => {
        this._detailView.AddContentsButton(e.BarButtonItem);
};
this.WillShowViewController += (object sender, UISplitViewShowEventArgs e) => {
        this._detailView.RemoveContentsButton();
};

You could also handle this in the delegate, but in this case it's simplest to use the events. WillHideViewController is raised when the device is rotated into portrait mode, and therefore the master view will be hidden, so in that event handler you should call your method to show the button.

WillShowViewController is raised when the device is rotated into landscape mode, and therefore the master controller will be shown, so in that event handler you should call your method to remove/hide the button.

Once you have your master and detail view up and running, it quickly becomes necessary to formulate a way for them to communicate with each other. There are a couple ways to handle this, depending on your needs. One way is to pass a reference to the other controller in each controller; however, the problem with this is that when something occurs in one of the controllers - say a button click that should affect the other controller - the split view controller doesn't know that anything has occurred.

Therefore, the best practice is to raise events in each controller, and then have the split view controller handle them and call the appropriate methods on the appropriate controller, thereby acting as a controller/mediator between the two child controllers. For example, in Listing 8-17, when a user clicks on a row in the master view, I raise an event that is handled in the split view controller and sets the appropriate data on the detail controller.

this._masterView.RowClicked +=
        (object sender, MasterView.MasterTableView.RowClickedEventArgs e) => {
        this._detailView.Text = e.Item;
};

The nice thing about this pattern is that, because the split view controller is the main controller, you can then swap out detail controllers based on what's happening in the master controller. For instance, say you had several different options on the master view, that when clicked, each one should show a different detail view.

NSUrl represents a URL in CocoaTouch and has a couple of different constructors, depending on what kind of URL you're creating. If you just want to do a plain-old web URL, you can use it by simply supplying the fully qualified web address (in this case, www.google.com.)

We'll look at some of the other constructors in just a bit.

Just like a browser, the web view control shares the concept of navigating backward and forward through page history. To this end, it exposes two methods, GoBack and GoForward, which navigate backward and forward in the page history. Before you call them, you should check the CanGoBack and CanGoForward properties to see if navigation in that particular direction is allowed. For example, Listing 8-19 handles the back and forward button clicks in the web browser example in the Example_ContentControls companion application and code:

this.btnBack.TouchUpInside += (s, e) => {
        if (this.webMain.CanGoBack) { this.webMain.GoBack (); } };
this.btnForward.TouchUpInside += (s, e) => {
        if (this.webMain.CanGoForward) { this.webMain.GoForward (); } };

If you want to stop a request while it's loading, you can call the StopLoading method on the web view. For example, Listing 8-20 handles the stop button click in the sample web browser.

this.btnStop.TouchUpInside += (s, e) => { this.webMain.StopLoading (); };

The web view exposes events related to loading that allow you to respond to various states and inform users of the loading process. As with other controls, you can either choose to handle them as events, assign a strongly-typed delegate, or use a weak delegate (see Chapter 6 for more information on this pattern). The events are described in the following sections.

public void LoadStarted (object source, EventArgs e)
{
        this.btnStop.Enabled = true;
        this.SetBackAndForwardEnable ();
        this.imgBusy.StartAnimating ();
}
protected void SetBackAndForwardEnable ()
{
        this.btnBack.Enabled = this.webMain.CanGoBack;
        this.btnForward.Enabled = this.webMain.CanGoForward;
}

public void LoadingFinished (object source, EventArgs e)
{
        this.btnStop.Enabled = false;
        this.SetBackAndForwardEnable ();
        this.imgBusy.StopAnimating ();
}

LoadError

The LoadError event is raised when there is a problem with the request. This most commonly happens if the device does not have connectivity. As per the Apple Human Interface Guidelines, you are required to handle this event and notify the user if they do not have connectivity. If you load internet requests, Apple will test your application with and without connectivity, and if you don't fail gracefully and let your user know that they don't have connectivity, your application is almost certain to be rejected.

For example, Listing 8-23 is again from the web browser sample. It alerts the user with the reason why their web request failed to load.

Example 8.23. Handling the LoadError method

public void LoadError (object sender, UIWebErrorArgs e)
{
        this.imgBusy.StopAnimating ();
        this.btnStop.Enabled = false;
        this.SetBackAndForwardEnable ();
        //---- show the error
        UIAlertView alert = new UIAlertView ("Browse Error"
                , "Web page failed to load: " + e.Error.ToString ()
                , null, "OK", null);
        alert.Show ();
}

Running this with no Internet connectivity will result in the alert shown in Figure 8-14.

Figure 8.14. Alerting the user that there is no Internet connection

The web view exposes a method called EvaluateJavascript that allows you to run JavaScript code within the context of the page. You can pass the function any executable script in the method and the web view will run it. This can be extremely effective if you have methods that you want to call on the page. For instance, say that you have the JavaScript shown in Listing 8-26 in your page.

<script language="javascript">
        function RunAction()
        {
                alert('RunAction javascript method called'),
        }
</script>

You can run that script by calling:

myWebView.EvaluateJavascript ("RunAction();");

Unfortunately, the web view doesn't give us an easy way to listen for events the way it allows us to run JavaScript, so we have to get a little crafty.

The web view exposes an event called ShouldStartLoad that we can use for just this purpose. You can use ShouldStartLoad to intercept load requests by the web view, figure out what the request is, and then return false if you want to handle the request, instead of letting the browser do it. For example, let's say that we have the following link, and we want to handle it by loading a screen in the application:

<a href="//LOCAL/Action=Image">action test</a>

One of the parameters of ShouldStartLoad is a UIWebViewNavigationType enumeration which tells us whether the request was from a link, a form submission, or something else. It'll even tell us if the user is navigating backward or forward (via the GoBack or GoForward methods). You can then use this, in conjunction with the NSUrlRequest parameter, to parse the request and then handle it in the application. For example, Listing 8-27 looks for the link that we just defined and shows an alert when it's clicked:

public bool HandleStartLoad (UIWebView webView, NSUrlRequest request
        , UIWebViewNavigationType navigationType)
{
        Console.WriteLine (navigationType.ToString ());

        //---- first, we check to see if it's a link
        if (navigationType == UIWebViewNavigationType.LinkClicked)
        {

//---- next, we check to see if it's a link with //LOCAL in it.
                if(request.Url.RelativeString.StartsWith("file://LOCAL"))
                {
                        new UIAlertView ("Action!", "You clicked an action.", null,
                                "OK", null).Show();
                        //---- return false so that the browser doesn't try to navigate
                        return false;
                }
        }
        //---- if we got here, it's not a link we want to handle
        return true;
}

The map view supports the display of the map in the following three modes, contained in the MKMapType enumeration:

You can set the current map view mode via the MapType property. For example, Listing 8-30 handles the ValueChanged even on a button segment control and updates the map display to the appropriate type, depending on which segment is selected.

this.sgmtMapType.ValueChanged += (s, e) => {
        switch(this.sgmtMapType.SelectedSegment)
        {
                case 0:
                        this.mapMain.MapType = MKMapType.Standard;
                        break;
                case 1:
                        this.mapMain.MapType = MKMapType.Satellite;
                        break;

case 2:
                        this.mapMain.MapType = MKMapType.Hybrid;
                        break;
        }
};

When Hybrid is selected, the view looks like Figure 8-16.

Figure 8.16. The map view in Hybrid mode showing a satellite image with features overlayed.

The previous example will get you a basic annotation, but to really customize it, you need to implement an MKMapViewDelegate and override the GetViewForAnnotation method. GetViewForAnnotation is exactly like the GetCell method in the table delegate, but instead returning a cell, you return an MKAnnotationView object.

GetViewForAnnotation is called by the map view whenever an annotation needs to be retrieved to display on the screen. This can happen quite often, as a user scrolls around on the map because just as with table cells, when the annotation goes out of view, the iOS scavenges its object and puts it in a pool so that it can be reused for other annotations.

Listing 8-34 is a sample map view delegate that implements the GetViewForAnnotation method and returns an MKPinAnnotationView as the annotation view.

protected class MapDelegate : MKMapViewDelegate
{
        protected string _annotationIdentifier = "BasicAnnotation";

        public override MKAnnotationView GetViewForAnnotation (
                MKMapView mapView, NSObject annotation)
        {
                //---- try and dequeue the annotation view
                MKAnnotationView annotationView =
                        mapView.DequeueReusableAnnotation(this._annotationIdentifier);

                //---- if we couldn't dequeue one, create a new one
                if (annotationView == null)
                {
                        annotationView =
                        new MKPinAnnotationView(annotation, this._annotationIdentifier);
                }
                else //---- if we did dequeue one for reuse, assign the annotation to it
                { annotationView.Annotation = annotation; }

                //---- configure our annotation view properties
                annotationView.CanShowCallout = true;
                (annotationView as MKPinAnnotationView).AnimatesDrop = true;
                (annotationView as MKPinAnnotationView).PinColor =
                        MKPinAnnotationColor.Green;
                annotationView.Selected = true;

                return annotationView;
        }
}

The pattern in this code example is almost exactly the same pattern for table cells. The iOS keeps a pool of annotation view objects for the map, and you can reuse them via the DequeueReusableAnnotation method in conjunction with a reuse identifier (for more context see Chapter 9). To understand the rest of the code, though, we need to examine annotation views.

An MKAnnotationView object is different from an MKAnnotation in that it contains the callout view that the annotation displays when it's selected, as well as the MKAnnotation object that specifies the coordinates. When you create an MKAnnotation, you pass it your MKAnnotation (it can later be found on the read-only Annotation property), and a reuse identifier. The reuse identifier is used to identify the type of annotation view so that you can reuse them like templates.

The easiest way to customize an annotation view is to set properties on it that control its display. For example, the following are some common properties that you can set on an annotation view:

For example, setting the properties shown in Listing 8-35 will result in a callout similar to the one in Figure 8-18.

annotationView.CanShowCallout = true;
annotationView.RightCalloutAccessoryView = UIButton.FromType(UIButtonType.DetailDisclosure);
annotationView.LeftCalloutAccessoryView =
        new UIImageView(UIImage.FromBundle("Images/Apress-29x29.png"));

Figure 8.18. A customized annotation view with left and right accessories set

If the basic annotation view isn't quite enough for what you need, you can also subclass it and do the rendering yourself during the Draw method.

In the delegate in Figure 8-18, we created an MKPinAnnotationView. MKPinAnnotationView is a specialized that annotation view that gave us a few more options. Specifically, by using a pin annotation, we were able to do the following (see Listing 8-36).

(annotationView as MKPinAnnotationView).AnimatesDrop = true;
(annotationView as MKPinAnnotationView).PinColor = MKPinAnnotationColor.Green;

If you set the AnimatesDrop property to true, when the map is first displayed, the annotation marker (pin) will drop onto the map.

The PinColor property allows us to select from three different colors for the pin, available in the MKPinAnnotationColor enumeration (Red, Green, and Blue).

In Figure 8-18, we gave the annotation view a detail disclosure button as its right accessory view. The detail disclosure indicates that clicking on the button will result in a detail information screen for that particular item. To handle the click, simply add a handler as you would any other button. For instance, Listing 8-37 creates the button, adds a handler that shows an alert when clicked that displays the coordinates, and then adds that button as the right callout accessory view.

UIButton detailButton = UIButton.FromType(UIButtonType.DetailDisclosure);
detailButton.TouchUpInside += (s, e) => { new UIAlertView("Annotation Clicked", "You
clicked on " +
        (annotation as MKAnnotation).Coordinate.Latitude.ToString() + ", " +
        (annotation as MKAnnotation).Coordinate.Longitude.ToString(), null, "OK",
        null).Show(); };
annotationView.RightCalloutAccessoryView = detailButton;

Clicking on the detail disclosure button would then result in the alert shown in Figure 8-19.

Figure 8.19. Showing an alert when an annotation has been clicked.

Because the map allows an unlimited number of annotations, there are two optimizations that you should consider to ensure a responsive map view as well as a pleasant user experience.

When creating an overlay, you can choose from a number of built-in shapes, or you can define your own custom shape. The built-in overlay shapes are contained in the following classes:

For example, Listing 8-38 is from the Example_ContentControls companion code and application and creates the circle overlay seen in Figure 8-20.

CLLocationCoordinate2D coords = new CLLocationCoordinate2D(29.976111, 31.132778);
this._circleOverlay = MKCircle.Circle(coords, .5);

In addition to the built-in shapes, you can define your own via a CGPath object and then use the MKOverlayPathView class in the GetViewForOverlay method. For more information on how to use a CGPath, see Chapter 14.

Once you've created your overlay shape, you can add it to the map view via either the AddOverlay method, or the AddOverlays method if you have more than one overlay to add. For example, Listing 8-39 adds the circle overlay we just created.

this.mapMain.AddOverlay(this._circleOverlay);

Once you've created and added your overlay to the map view, you need to implement the GetViewForOverlay method as part of your map view delegate (or handle the GetViewForOverlay event, and so on). GetViewForOverlay is different than GetViewForAnnotation in that there is no template reuse, so you don't have to worry about the deque reusable calls or reuse identifiers.

Instead, you simply have to instantiate a view that contains your shape. Each shape has an associated view class: MKCircleView, MKPolygonView, and MKPolylineView. If you're using a custom CGPath, then you use an MKOverlayPathView object. For example, Listing 8-40 uses a Lamda delegate to handle the GetViewForOverlay event.

this.mapMain.GetViewForOverlay += (m, o) => {
        if(this._circleView == null)
        {
                this._circleView = new MKCircleView(this._circleOverlay);
                this._circleView.FillColor = UIColor.LightGray;
        }
        return this._circleView;
};

In this code, we create a view for the shape, assign any display properties we want, such as fill color, line width, color, and so on, and then return that view. In this case, I've defined the view at the class level, so that I check to see if it's already been initialized, and if it hasn't I configure it.

Of course, as specified in Chapter 6, you could also implement a map view delegate and override the GetViewForOverlay method in there as well.