Understanding Application Life Cycle Events

A view controller manages the life cycle of a storyboard through a number of events such as OnActivated, ViewDidLoad, and FinishedLaunching. ViewDidLoad is an important event, and its handler allows you to add initialization code to the view controller that will be executed after the view has been loaded. In this case, ViewDidLoad defines a couple of properties and sets up event handlers for the two buttons, as demonstrated in the following code:

using System;
using Foundation;
using MessageUI;
using UIKit;

namespace SendPicture
{
    public partial class ViewController : UIViewController
    {

        UIImagePickerController imagePicker;
        MFMailComposeViewController mailController;

        public ViewController(IntPtr handle) : base(handle)
        {
        }

        public override void ViewDidLoad()
        {
            base.ViewDidLoad();

            Title = "Choose Photo";
            View.BackgroundColor = UIColor.White;

            SelectButton.TouchUpInside += SelectButton_TouchUpInside;
            SendButton.TouchUpInside+= SendButton_TouchUpInside;
        }

Notice the following:

• The using directives import some namespaces from the Apple frameworks, such as Foundation, UIKit, and MessageUI. MessageUI exposes objects for sending e-mails, while Foundation and UIKit provide the objects that are required to access the user interface APIs.

• The class inherits from UIViewController, which is the base class for all controllers, and has an empty constructor. This might contain some startup code, but it’s not necessary in this case.

• Two fields of type UIImagePickController and MFMailComposeViewController, respectively, are defined for later use.

• The ViewDidLoad event handler must call its base class’s ViewDidLoad for initialization purposes, and after this invocation, it can execute initialization code. In this case, it is assigning a title to the page and a background color. More important, two event handlers are assigned to the two buttons in the UI using the typical C# syntax. The TouchUpInside event can be thought of as the counterpart of Click, Clicked, and Tapped events in other platforms.

Both event handle bodies are provided shortly.

Using System Features

The first feature that must be implemented is selecting a picture from the local library and displaying the selected picture inside the UIImageView control. This basically requires these three steps:

1. Handle the TouchUpInside event of the SelectButton control in order to display a UIImagePickerController, an iOS object that allows for selecting pictures from disk.

2. Handle the cancellation of the picture selection so that the UIImagePickerController is dismissed.

3. Handle the FinishPickingMedia event of the UIImagePickerController, which is raised once the user has selected the image and which is where the selected image is assigned to the UIImageView control.

The following is the code for the three event handlers, which includes detailed comments that explain each code snippet:

private void SelectButton_TouchUpInside(object sender, EventArgs e)
{
    // create a new picker controller
    imagePicker = new UIImagePickerController();

    // set our source to the photo library
    imagePicker.SourceType = UIImagePickerControllerSourceType.PhotoLibrary;

    // set what media types
    imagePicker.MediaTypes = UIImagePickerController
               .AvailableMediaTypes(UIImagePickerControllerSourceType.PhotoLibrary);

     imagePicker.FinishedPickingMedia += Handle_FinishedPickingMedia;
     imagePicker.Canceled += Handle_Canceled;

     // show the picker
     PresentModalViewController(imagePicker, true);
     //UIPopoverController picc = new UIPopoverController(imagePicker);
}

void Handle_Canceled(object sender, EventArgs e)
{
    imagePicker.DismissModalViewController(true);
}

// This is a sample method that handles the FinishedPickingMediaEvent
protected void Handle_FinishedPickingMedia(object sender,
               UIImagePickerMediaPickedEventArgs e)
{
    // determine what was selected, video or image
    bool isImage = false;
    switch (e.Info[UIImagePickerController.MediaType].ToString())
    {
        case "public.image":
             isImage = true;
             break;

        case "public.video":
             break;
    }

    // if it was an image, get the other image info
    if (isImage)
    {

        // get the original image
        UIImage originalImage = e.Info[UIImagePickerController.OriginalImage]
                                as UIImage;
        if (originalImage != null)
        {
            // do something with the image
            ImageView.Image = originalImage;
        }

        // get the edited image
        UIImage editedImage = e.Info[UIImagePickerController.EditedImage] as UIImage;
        if (editedImage != null)
        {
            // do something with the image
            ImageView.Image = editedImage;
        }
    }
        // if it's a video
        else
        {
            // simply return, we don't support videos
            return;
        }

        // dismiss the picker
        imagePicker.DismissModalViewController(true);
    }

It is worth mentioning that you can invoke a controller that represents a system picker, such as the UIImagePickerController, and calls the ViewController.PresentModalViewController method, whose first argument is the controller that you want to display and the second argument is a bool value that determines whether displaying the picker should support an animation. To dismiss the picker, you instead call the DismissModalViewController method that is exposed by the instance of the object that represents the picker (in this case, UIImagePickerController).

Sending E-mails

The next step is handling the TouchUpInside event for the SendButton button, where you will write the code required to send an e-mail with the selected picture as an attachment. Here is the code required to accomplish this, followed by a number of explanations and considerations:

private void SendButton_TouchUpInside(object sender, EventArgs e)
{
    if (MFMailComposeViewController.CanSendMail)
    {
        // an array of strings that represents recipients
        var to = new string[] { "[email protected]" };

        // MFMailComposeViewController calls the UI to send an email
        if (MFMailComposeViewController.CanSendMail)
        {
            mailController = new MFMailComposeViewController();
            mailController.SetToRecipients(to);
            mailController.SetSubject("A picture");
            mailController.SetMessageBody("Hi, I'm sending a picture from iOS", false);

            mailController.AddAttachmentData(ImageView.Image.AsJPEG(),
                          "image/jpeg", "image.jpg");

            mailController.Finished += (object s, MFComposeResultEventArgs args) =>
            {
                BeginInvokeOnMainThread(() =>
                {
                    args.Controller.DismissViewController(true, null);
                });
            };
        }

        PresentViewController(mailController, true, null);
    }
}

The iOS APIs offer a specific controller that you can use to send e-mails, called MFMailComposeViewController, whose CanSendMail bool property allows you to understand if sending e-mails is supported on the current device.

MFMailComposeViewController exposes a number of methods that you can use to set up a new e-mail message, such as SetToRecipients, which receives an array of strings representing the e-mail recipients; SetSubject, which allows for specifying the e-mail subject; and SetMessageBody, which you invoke to provide the e-mail body. Of course, invoking these methods is optional since users will be able to enter the required information in the user interface of the e-mail client. Here you have to pay particular attention to the AddAttachmentData method, which takes three arguments: an object of type NSData that represents the attachment, a string that represents the MIME type for the attachment file, and the file name. The NSData class offers static methods that allow you to generate an NSData object from different data sources, but in this case things are easier because the UIImageView.Image property, which represents the image you see in the UIImageView control, exposes methods such as AsJPEG and AsPNG that return an NSData object from the image, and so they do the whole job. You still need to supply the MIME type, which is image/jpeg for JPEG images, and a file name such as image.jpg (you can certainly supply a different file name). Notice how the code handles the Finished event of MFMailComposeViewController using the lambda expressions syntax. In the lambda’s body, the code calls the DismissViewController for MFMailComposeViewController, making sure this is invoked in the main UI thread via the BeginInvokeOnMainThread method. The ViewController.PresentViewController method is invoked to display the e-mail client’s UI; when displaying the image picker, you called PresentModalViewController, and that made sense because the picture selection happens in-app. In this case, the app is calling another app, the e-mail client, and therefore this must not be in a modal controller. Now comes one of the most important tasks in developing for iOS (and macOS): setting app properties and permissions.

Understanding and Editing Entitlements.plist

With the Entitlements.plist file, you can specify a number of capabilities that your app will include and that must be explicitly specified in order to enable features such as (but not limited to) payments with the built-in Wallet feature or Siri integration. If you double-click the Entitlements.plist file in the Solution pad, the editor will appear and will look like Figure 6-10.

Figure 6-10. Editing the Entitlements.plist file

Visual Studio for Mac provides a description of each capability that you can enable by simply selecting the proper check box. Capabilities you can enable are iCloud support, push notifications, Wallet support, Siri support, Apple Pay, network access with a VPN, Keychain access, sharing audio with other apps with Inter-app Audio, associating domains to your app with associated domains, App Group interaction, HomeKit for home automation, HealthKit to access personal health information, and wireless access configuration. Notice that almost all of these capabilities require a paid developer account. Actually, you can click the Source tab at the bottom and add custom properties to include additional options. An example will be provided in the next paragraph about Info.plist.

Understanding and Editing Info.plist

The Info.plist file is the standard file you use to edit an app’s properties and settings, meaning it is also included in Xcode projects, not only Xamarin projects. The purpose of Info.plist is providing information about identity, deployment, icons and launch images, and basic capabilities. When you double-click the Info.plist in the Solution pad, the editor will look like Figure 6-11.

Figure 6-11. Editing the Info.plist file

In the Identity group, you will find the information you entered when creating the project, such as the name, bundle identifier, and version numbers. Here you can make edits; for example, you can change the version numbers when releasing app updates. In the Deployment Info group, you can specify your app targets by indicating the minimum iOS version (Deployment Target), the device family (iPhone, iPad, or Universal), the supported orientations, and the main interface, and you can control the appearance of the iOS status bar. If your app targets the iPad, you might want to select the “Requires full screen” check box. In the App Icon and Launch Images groups, you can specify the app icon and the images that will be used as splash screens. There are default settings that you can override by supplying your custom images through a specific editor, which you enable by double-clicking the Assets.xcassets folder in the Solution pad. This editor, which looks like Figure 6-12, allows you to specify icons and images for different screen factors based on the device. It shows the size for each image you need to supply and allows you to supply both app icons and launch images by clicking the desired item in the left bar.

Figure 6-12. Supplying app icons and launch images

Going back to Info.plist, you can specify the so-called iTunes artwork—two images that will be used in the iTunes App Store to showcase the app. Regarding capabilities, here you can specify if your app needs to connect to the Game Center, if it supports Maps, and if it needs to run in the background.

Specifying Privacy Permissions

Info.plist is also important for another reason: it allows you to specify privacy permissions your app will request to the user, based on the device and system features it uses. For instance, the sample application needs to access the local photo library, and therefore it must request the user permission to do so. This is important, especially because of the more restrictive privacy requirements in iOS 10.

To specify a permission, first click the Source tab. Here you will see the list of properties that were already specified in the Application view of the editor, and here you can insert additional properties and options, including privacy settings. To add one, click “Add new entry.” When “Custom property” appears, click the drop-down arrow at the right, and scroll the list of properties until you see those whose name starts with Privacy. Among these, select Privacy – Photo Library Usage Description, then specify the String type in the Type column, and finally enter a description that the app will display when requesting the user permission, as exemplified in Figure 6-13.

Figure 6-13. Specifying privacy permissions

You can specify additional privacy settings with the same steps, and the privacy items in the list are really self-explanatory. When you specify privacy items, iOS will ask the user permission to access a given resource displaying the informational message you supplied in the editor. Further information about iOS privacy permissions is available in the Xamarin official blog at https://blog.xamarin.com/new-ios-10-privacy-permission-settings/ .

Configuring the Build Process

In Chapter 2, you saw how to configure project options that are commonly available to all the supported project types in Visual Studio for Mac; then in Chapter 5, you saw how specific project options are available to Android projects and allow for configuring the build process. As you might expect, specific options are also available to iOS projects.

To manage these options, in the Solution pad right-click the project name and then select Options. Under the Build node of the Project Options dialog, you will find the iOS Build, iOS Debug, iOS On-Demand Resources, iOS Bundle Signing, and iOS IPA Options tabs. The iOS Build tab allows you to control the build process in a similar way to what you saw for Android in the previous chapter. For your convenience, I will summarize the most relevant options on the iOS Build tab, which is represented in Figure 6-16.

Figure 6-16. Controlling the build options

Like for Android, if you click the information icon, you will see a tooltip that explains what an option is about. Remember that options in the iOS Build dialog are per configuration, which means that Debug, Release, Ad-hoc, and AppStore might have different settings. Here I will cover the most relevant options. The “SDK version” option allows you to select which version of the Apple SDK must be used to build the app. I recommend you leave the Default selection so that Visual Studio knows what is the best version to use. Regarding the Linker Behavior option, you can decide to remove unused code, such as types and their members, from the build output to reduce the package size. It is recommended that you leave the default setting for each configuration, which is Link Framework SDKs Only. The “Supported architectures” box allows you to specify the supported processor architectures, and leaving the default value is the best choice. The “Enable incremental builds” and “Enable device-specific builds” options are intended to be enabled only when the active configuration is Debug. The first option only updates files that have changes from the previous build, while the second option optimizes the build for the selected target device. In the Internationalization group, you can specify one or more optional codesets so that the linker can include the appropriate resources in the build output. On the iOS Debug tab, you have options that are normally available to the Debug configuration. Among others, you can enable debugging over Wi-Fi and specify a port that the target device can use to connect. On the iOS On-Demand Resources tab, you can specify contents that are hosted on the App Store with a different bundle identifier and that your app will consume. More details are available at http://apple.co/2rHiY4i . On the iOS IPA Options tab, you can provide customizations to the information required by iTunes and that will be bundled into the .ipa app package. The iOS Bundle Signing tab contains probably the most important set of options and therefore needs a more thorough discussion. Figure 6-17 shows how this tab appears, which you can use as a reference.

Figure 6-17. The iOS Bundle Signing options

The first important concept to understand is that an iOS app package must be signed not only for publishing to the App Store but also for debugging. To accomplish this, Xcode (invoked by Visual Studio for Mac) needs you to specify the so-called signing identity, which is represented by a digital certificate that can be of different types, such as Developer or Distribution. By default, your Apple ID is enabled as a free developer account, with the limitations described in Chapter 1, and Xcode generates a development certificate for it. With this certificate, you can sign an app for debugging on both the simulator and a physical device. When you purchase a developer account on the Apple’s web site ( http://developer.apple.com ), you become eligible for removing all the restrictions on your developer account, which you can therefore use to debug and test multiple apps on a larger number of physical devices. You can also create distribution certificates that you can use to sign an app package once you are ready for publishing. This last step is explained in more detail in the next section, but it is interesting how Visual Studio for Mac can automatically detect the best signing identity based on the selected configuration. If you look at Figure 6-17, in the Signing Identity box you see Developer (Automatic). This means Visual Studio has detected that the Developer signing identity is appropriate for the selected configuration, which is Debug. Of course, you can choose a different signing identity, for example, when multiple Apple IDs are registered on the same machine. When you click the drop-down box, Visual Studio will display the list of available identities, and you will be able to understand to whom an identity belongs. Similarly, Visual Studio automatically selects the most appropriate provisioning profile based on the current configuration and signing identity. As you will see shortly, these settings will change when you want to distribute an app using the Ad-hoc and AppStore configurations. As you can imagine, if you are able to immediately start debugging your app, it is because Visual Studio automatically selected the proper signing identity and provisioning profile for you. Finally, you can supply a different, custom Entitlements.plist file, which I suggest you do only when you get experienced with Xamarin and iOS development.

Hints About the Xamarin Live Player

As you learned in Chapter 5, Microsoft offers the Xamarin Live Player app that you can install on Android and iOS devices and that allows you to debug an app on a physical device by pairing the device with Visual Studio. Using this app for debugging will not be covered in this chapter, because one of the app’s purposes is making it simpler to debug a Xamarin.iOS project for people who do not have a Mac, such as developers working with Visual Studio on Windows. This certainly does not apply to you since you are already working on a Mac.

Having a Mac with Visual Studio provides full development and debugging experiences with no limitations, so using the Xamarin Live Player app will not bring additional value to you with this book. You can always get further information at http://xamarin.com/live .