Cross Platform
Android
iOS
Mac
Test Cloud

Walkthrough - Using the Xamarin Designer for iOS

Building Beautiful Interfaces with the iOS Designer

Show instructions for:

In the Introduction to the Xamarin Designer for iOS guide we introduced the key concepts and parts of the iOS Designer. This guide walks through the steps of creating a multi-screened application using the iOS Designer.

Overview

In this guide, we use the Xamarin Designer for iOS and Storyboards to create a multi-screened application that lets us navigate between different screens. We are going to explore the navigation between View Controllers using Modal and Push Segues and navigation in code using a button event.

Our application will consist of a Main View Controller, a Flipside View Controller, and two View Controllers managed by a Navigation Controller. We will use the iOS Designer to populate our Views with controls, provide names and backing classes to access those controls in code, and respond to the user’s interactions with the controls using custom event handlers. Along the way, we’ll also use the Designer for navigation as we create Modal and Push Segues to move between screens. The screenshot below illustrates the final application we are going to make, with the arrows highlighting the navigation between each View:

Our application will consist of a Main View Controller, and two View Controllers managed by a Navigation Controller. We will use the iOS Designer to populate our Views with controls, provide names and backing classes to access those controls in code, and respond to the user’s interactions with the controls using custom event handlers. Along the way, we’ll also use the Designer for navigation as we create Modal and Push Segues to move between screens. The screenshot below illustrates the final application we are going to make, with the arrows highlighting the navigation between each View:

By the end of the walkthrough you should feel confident building an application visually inside Xamarin Studio.

By the end of the walkthrough you should feel confident building an application visually inside Visual Studio.

Requirements

The Xamarin Designer for iOS is available in Xamarin Studio 5.0 for Mac and Xamarin 3.0 for Windows.

This guide assumes a familarity with the contents convered in the Getting Started guides.

Walkthrough

Let’s get started building our application. You can check out the completed code for this walkthrough at any point by downloading the Designer Walkthrough Sample.

  1. We’ll begin by creating a new Project. Open Xamarin Studio and select Classic API > iPhone > Utility Application, as illustrated below:

    The Utility template creates a new Xamarin.iOS application with a Main View Controller and a second screen called Flipside View Controller, brought into view by a flipside animation.

    Our resulting Solution should resemble the following screenshot. Note that Xamarin Studio has already created a custom MainViewController class in the Solution Pad:

  2. We’ll begin by creating a new Project. Open Visual Studio and select iPhone > Single View Application, as illustrated below:

    Our resulting Solution should resemble the following screenshot. Note that Visual Studio has already created a custom DesignerWalkthroughViewController class in the Solution Exlporer:

  3. Now that we have our template Project, we’ll dive directly into the Storyboard to edit our UI. Let’s double-click MainStoryboard.storyboard to open it in the iOS Designer. Here we can see the Utility application template has defined MainViewController and FlipsideViewController on the Design Surface. The two View Controllers are linked together by a transition called a Segue, as illustrated by the screenshot below:

    If we run the application now, we’ll be able to navigate between the View Controllers using the Information Button on the MainViewController and the Done Button on the FlipsideViewController, as illustrated by the screenshots below:

  4. Now that we have our template Project, we’ll dive directly into the Storyboard to edit our UI. Let’s double-click MainStoryboard.storyboard to open it in the iOS Designer. Here we can see the Single View application template has defined our single View controller, DesignerWalkthroughViewController on the Design Surface.

    If we run the application now, it will build and run, however we haven't added anything to aid interaction with the View.

  5. From our MainViewController we want to be able to navigate and access more screens, so we’ll add a Navigation Controller. The Navigation Controller is a UI-less View Controller responsible for managing a stack of View Controllers and provides tools for navigation, such as a navigation bar with a back button. You can read more about the Navigation Controller in the Multi-Screen Applications guide.

    We can add new elements to the Storyboard with the Toolbox. The Toolbox is located to the right of the Design Surface, and should resemble the screenshot below:


    We’ll find the Navigation Controller and drag it onto the Design Surface. The Zooming Controls on the Design Surface can be used to adjust the view to ensure we can see all our View Controllers. Our View Controllers should now match the screenshot below:


    Note that the Navigation Controller comes with a default Root View Controller, which represents the first screen that the user will see. We’ll be working with the Root View Controller to customize the View that the user sees.

  6. From our DesignerWalkthroughViewController we want to be able to navigate and access more screens, so we’ll add a Navigation Controller. The Navigation Controller is a UI-less View Controller responsible for managing a stack of View Controllers and provides tools for navigation, such as a navigation bar with a back button. You can read more about the Navigation Controller in the Multi-Screen Applications guide.

    We can add new elements to the Storyboard with the Toolbox, which can be added by accessing View > Toolbox, and should resemble the screenshot below:


    We’ll find the Navigation Controller and drag it onto the Design Surface. The Zooming Controls on the Design Surface can be used to adjust the view to ensure we can see all our View Controllers. Our View Controllers should now match the screenshot below:


    Note that the Navigation Controller comes with a default Root View Controller, which represents the first screen that the user will see. We’ll be working with the Root View Controller to customize the View that the user sees.

  7. We want to create a custom class for our Root View Controller so we can access it in the code-behind a little later. To do this, we’ll select the entire Root View Controller by clicking the black bar at the bottom. Then, under the Identity section in the Properties Pad, we’ll change the Class to MonkeyController as illustrated by the screenshot below:

    The Navigation Item Title can also be edited to help the user identify which View Controller they are viewing. To do this double-click the textRoot View Controller and change it to Monkey as shown below:

    Xamarin Studio will automatically generate a MonkeyController class in our Solution Pad, as illustrated by the following screenshot:


    The MonkeyController class lets us access and manage the View Controller in our C# code. We’ll see how this works later in the walkthrough.

  8. We want to create a custom class for our Root View Controller so we can access it in the code-behind a little later. To do this, we’ll select the entire Root View Controller by clicking the black bar at the bottom. Then, under the Identity section in the Properties Pane, we’ll change the Class to MonkeyController as illustrated by the screenshot below:

    The Navigation Item Title can also be edited to help the user identify which View Controller they are viewing. To do this double-click the textRoot View Controller and change it to Monkey as shown below:

    Visual Studio will automatically generate a MonkeyController class in our Solution Explorer, as illustrated by the following screenshot:


    The MonkeyController class lets us access and manage the View Controller in our C# code. We’ll see how this works later in the walkthrough.

  9. If we run the application now, our MonkeyController will be part of the application, but we’ll have no way to navigate to it. One way to solve this is to add a button that triggers navigation from the MainViewController to our MonkeyController.

    Let’s drag a Button control from the Toolbox onto the MainViewController so it resembles the screenshot below:


    We can edit the button’s properties in the Properties Pad. Under Identity > Name, we’ll name the button monkeyButton and under Button > Title we'll change the button text to “To the Monkeys!”. This is illustrated in the screenshot below:


  10. If we run the application now, our MonkeyController will be part of the application, but we’ll have no way to navigate to it. One way to solve this is to add a button that triggers navigation from the DesignerWalkthroughViewController to our MonkeyController.

    Let’s drag a Button control from the Toolbox onto the MainViewController so it resembles the screenshot below:


    We can edit the button’s properties in the Properties Pane. Under Identity > Name, we’ll name the button monkeyButton and under Button > Title we'll change the button text to “To the Monkeys!”. This is illustrated in the screenshot below:


  11. Now let’s add the transition, or Segue, between the MainViewController and MonkeyController

    To create a Segue, hold down the Ctrl key and click-drag from inside monkeyButton to the Navigation Controller (remember, the Navigation Controller is just the stack manager for the View Controllers, so MonkeyController will be the first View the user sees). As we drag our mouse, a blue connector appears, indicating where the Segue will lead.

    On mouse-up, the following menu should appear letting us choose the action for our Segue:

    In this case, we’ll choose the Modal Segue. A Modal Segue will create a relationship between any two View Controllers in your Project. The child View Controller, the MonkeyController, will completely obscure the MainViewController when brought into view and will have to be dismissed in order to return to it.

    The Design Surface should now resemble the following screenshot:


  12. Now let’s add the transition, or Segue, between the DesignerWalkthroughViewController and MonkeyController.

    To create a Segue, hold down the Ctrl key and click-drag from inside monkeyButton to the Navigation Controller (remember, the Navigation Controller is just the stack manager for the View Controllers, so MonkeyController will be the first View the user sees). As we drag our mouse, a blue connector appears, indicating where the Segue will lead.

    If you are using VMWare for your Windows Virtual Machine, note that by default Ctrlclick is mapped as the 'Right-Click' mouse button.
    To create a Segue, edit your Keyboard preferences through Preferences > Keyboard & Mouse > Mouse Shortcuts and remap your Secondary button as illustrated below:

    You should now be able to add a segue between your View Controllers as normal.

    On mouse-up, the following menu should appear letting us choose the action for our Segue:

    In this case, we’ll choose the Modal Segue. A Modal Segue will create a relationship between any two View Controllers in your Project. The child View Controller, the MonkeyController, will completely obscure the DesignerWalkthroughViewController when brought into view and will have to be dismissed in order to return to it.

    The Design Surface should now resemble the following screenshot:


  13. At this point in the walkthrough, we have added a Navigation Controller to our original Utility application and used a Modal Segue to transition between MainViewController and MonkeyController. We now want to drill down into the View hierarchy and see a detail page corresponding to the button we tap on. To do this we will need to add another View Controller and a button to trigger the transition.

    Let’s start by dragging a View Controller onto the Design Surface and then dragging a button onto the MonkeyController. Let’s change the button text to something more meaningful by changing the title in the Properties Pad to ‘Push Next View’. Feel free to leave Identity > Name blank this time, as we aren’t going to be referencing this button in our code.

    Ctrl-click and drag from the button onto the new View Controller to add our Segue.

    This time we will choose Push from the context menu. A Push Segue will add the new View Controller onto the navigation stack of the Navigation Controller, letting the user return to the MonkeyController using the Back Button. The Segue selection is illustrated in the following screenshot:

    This will add the new View Controller to our navigation stack, as illustrated below:


  14. At this point in the walkthrough, we have added a Navigation Controller to our original Utility application and used a Modal Segue to transition between DesignerWalkthroughViewController and MonkeyController. We now want to drill down into the View hierarchy and see a detail page corresponding to the button we tap on. To do this we will need to add another View Controller and a button to trigger the transition.

    Let’s start by dragging a View Controller onto the Design Surface and then dragging a Button onto the MonkeyController. Let’s change the button text to something more meaningful by changing the title in the Properties Pane to ‘Push Next View’. Feel free to leave Identity > Name blank this time, as we aren’t going to be referencing this button in our code.

    Ctrl-click and drag from the button onto the new View Controller to add our Segue.

    This time we will choose Push from the context menu. A Push Segue will add the new View Controller onto the navigation stack of the Navigation Controller, letting the user return to the MonkeyController using the Back Button. The Segue selection is illustrated in the following screenshot:

    This will add the new View Controller to our navigation stack, as illustrated below:


  15. Let’s save the Storyboard and run the application. We should be able to navigate between the screens as demonstrated by the screenshot below:

  16. Let’s save the Storyboard and run the application. We should be able to navigate between the screens as demonstrated by the screenshot below:

  17. Our application is looking great, but right now we have no way to dismiss the MonkeyController and navigate back to the MainViewController. To fix this, let’s go back to our Storyboard and drag a second button onto the MonkeyController to act as a back button. In the Identity section of the Properties Pad, we’ll change the button name to backButton and the button’s text (Title) to “Back to Main”, as depicted in the screenshot below:


  18. Our application is looking great, but right now we have no way to dismiss the MonkeyController and navigate back to the DesignerWalkthroughViewController. To fix this, let’s go back to our Storyboard and drag a second button onto the MonkeyController to act as a back button. In the Identity section of the Properties pane, we’ll change the button name to backButton and the button text (Title) to “Back to Main”, as depicted in the screenshot below:


  19. We have our button, now let’s make it do something. We’re going to wire up this button using an event handler - similar to an Action in XCode – and add some backing code to handle the event in our MonkeyController class.

    We’ll start by adding an event handler to our backButton button, so let’s select the button and open the Events pane of the Designer’s Properties Pane. For this example, we’ll be using the Up Inside touch event, which is the equivalent of calling TouchUpInside in code. This event will fire when the user releases the backButton. In the next step we will define the handler for the touch event in our code, but for now we’ll specify the handler name, Clicked, in the Properties Pane.

    The Properties Pane should resemble the screenshot below:


  20. We have our button, now let’s make it do something. We’re going to wire up this button using an event handler - similar to an Action in XCode – and add some backing code to handle the event in our MonkeyController class.

    We’ll start by adding an event handler to our backButton button, so let’s select the button and open the Events pane of the Designer’s Properties Pane. For this example, we’ll be using the Up Inside touch event, which is the equivalent of calling TouchUpInside in code. This event will fire when the user releases the backButton. In the next step we will define the handler for the touch event in our code, but for now we’ll specify the handler name, Clicked, in the Properties Pane.

    The Properties Pane should resemble the screenshot below:


  21. We need to tell our application what to do when the touch event occurs, so we’ll add some backing code to our MonkeyController. Let’s open MonkeyController.cs and add the following code:

    partial void Clicked (UIButton sender)
    {
        Console.WriteLine("Back to Main pressed");
        DismissViewController(true, null);
    }

    In this code DismissViewController’s job is to get rid of the current View Controller. It takes two arguments: the first makes the View animate onto the screen, and the second is the method to invoke when the animation completes. We aren’t going to use this in our application and so we can set it to null.

  22. If we run the application on a Retina 4" display, it will be letterboxed. To fix this add a splashscreen image (such at the one with this guide) to your application by Right-Clicking on your project name, navigate to Properties > iOS Application, and add it to Launch Images, as illustrated in the screenshot below:
  23. Finally, let’s save and run the application.

    The following screenshot shows the finished application running on a device:


    Congratulations, you have just completed your first application using the iOS Designer!

Summary

In this walkthrough we used the iOS Designer to build a basic application with Storyboards. We learned to create a new Storyboard application, add View Controllers with custom backing classes, handle navigation between Views with Segues, and add custom events to handle user interaction.