Introduction to the Xamarin Designer for iOS

Building Beautiful Interfaces with the Xamarin iOS Designer

This guide covers the features of the Xamarin Designer for iOS. It covers designer basics and demonstrates using the designer to lay out controls visually and edit properties.

Overview

The iOS Designer is Xamarin's alternative to Xcode’s Interface Builder and provides an integrated experience for working with Storyboards in Xamarin Studio. It is similar to Xamarin's Android designer and facilitates building Views using drag-and-drop functionality and property fields.

The iOS Designer is Xamarin's alternative to Xcode’s Interface Builder and provides an integrated experience for working with Storyboards in Visual Studio. It is similar to Xamarin's Android designer and facilitates building Views using drag-and-drop functionality and property fields.

The iOS Designer has several advantages over Xcode’s Interface Builder for Xamarin.iOS developers: first, it integrates seamlessly into Xamarin Studio, and does not require launching Xcode or waiting for changes to sync. Second, it offers a cleaner, more intuitive approach to event handlers, without the use of actions and outlets. Finally, it allows developers to program their own custom controls that are accessible from the designer’s toolbox panel and have design-time rendering support, making it easy to build sophisticated UIs from reusable components.

Xamarin’s iOS Designer is powerful and easy to use. This guide provides a general overview of designer concepts and features.

The iOS Designer has several advantages over Xcode’s Interface Builder for Xamarin.iOS developers: first, it integrates seamlessly into Visual Studio, and does not require launching Xcode or waiting for changes to sync. Second, it offers a cleaner, more intuitive approach to event handlers, without the use of actions and outlets. Finally, it allows developers to program their own custom controls that are accessible from the designer’s toolbox panel and have design-time rendering support, making it easy to build sophisticated UIs from reusable components.

Xamarin’s iOS Designer is powerful and easy to use. This guide provides a general overview of designer concepts and features.

Requirements

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

The iOS Designer requires a minimum of Xcode 5.0.

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

How the Designer Works

The iOS Designer gives developers a way to design user interfaces visually with Storyboards and access the UI elements programmatically, all inside Xamarin Studio. As outlined in the Introduction to Storyboards guide, a Storyboard defines View Controllers and the navigation between them on a design surface. We can think of a View Controller as having two parts - the visual representation in the iOS Designer (visible in the Storyboard file) and a code-behind C# ViewController class. For example, the following screenshots illustrate the DesignerViewController on the design surface and in code:

The iOS Designer gives developers a way to design user interfaces visually with Storyboards and access the UI elements programmatically, all inside Visual Studio. As outlined in the Introduction to Storyboards guide, a Storyboard defines View Controllers and the navigation between them on a design surface. We can think of a View Controller as having two parts - the visual representation in the iOS Designer (visible in the Storyboard file) and a code-behind C# ViewController class. For example, the following screenshots illustrate the DesignerViewController on the design surface and in code:

View Controllers by themselves aren't that interesting because they don't provide anything for the user to see or do. Rather, we populate View Controllers with controls or elements that define what the user sees and interacts with on the screen. Most View Controllers have a View (an instance of the UIView class) that defines a rectangular area on the screen and renders the screen's content. Most Views are populated with other common controls such as buttons, labels, text fields, and more. The following screenshot illustrates a View Controller in a Storyboard with a View and several controls. The control heirarchy is visible in the Document Outline on the right:

Some controls, like labels containing static text, can be added to the View Controller in the Storyboard and left alone. More often, however, we want to do more with a control than just display it. For example, buttons should have a behavior in response to the user's touch, and text fields get a user-provided value that we may want to manipulate in code. To interact with a control programmatically, we need to give it a unique identifier so we can access it in the C# backing code for the View Controller, the ViewController class. In the screenshot below, we've provided a unique identifier for the button using the Name property in the Properties Pad:

Some controls, like labels containing static text, can be added to the View Controller in the Storyboard and left alone. More often, however, we want to do more with a control than just display it. For example, buttons should have a behavior in response to the user's touch, and text fields get a user-provided value that we may want to manipulate in code. To interact with a control programmatically, we need to give it a unique identifier so we can access it in the C# backing code for the View Controller, the ViewController class. In the screenshot below, we've provided a unique identifier for the button using the Name property in the Properties Pane:

If we navigate to the View Controller class in the Solution Pad and open the disclosure triangle, we see that the View Controller class is actually split into two parts, as illustrated by the screenshot below:

If we navigate to the View Controller class in the Solution Exxplorer and open the disclosure triangle, we see that the View Controller class is actually split into two parts, as illustrated by the screenshot below:

The View Controller partial class - DesignerViewController.cs - handles the View lifecycle and everything that happens in the View, including code to respond to the button touch. The designer partial class - DesignerViewController.designer.cs - maps Storyboard controls to C# objects and is the glue that makes the controls we defined in the Storyboard available in the View Controller class. The designer file is auto-generated by Xamarin Studio. It should never be edited by hand as Xamarin Studio will just overwrite manual changes the next time the Storyboard is updated.

The View Controller partial class - DesignerViewController.cs - handles the View lifecycle and everything that happens in the View, including code to respond to the button touch. The designer partial class - DesignerViewController.designer.cs - maps Storyboard controls to C# objects and is the glue that makes the controls we defined in the Storyboard available in the View Controller class. The designer file is auto-generated by Visual Studio. It should never be edited by hand as Visual Studio will just overwrite manual changes the next time the Storyboard is updated.

If we open DesignerViewController.designer.cs, we see that the submitButton is defined:

namespace Designer
{
  [Register ("DesignerViewController")]
  partial class DesignerViewController
  {
    [Outlet]
    [GeneratedCodeAttribute ("iOS Designer", "1.0")]
    UIKit.UIButton submitButton { get; set; }

    void ReleaseDesignerOutlets ()
    {
      if (submitButton != null) {
        submitButton.Dispose ();
        submitButton = null;
      }
    }
  }
}

We can type the button name into the View Controller class as we add code to handle the button touch, and Xamarin Studio will recognize it as our submitButton:

We can type the button name into the View Controller class as we add code to handle the button touch, and Visual Studio will recognize it as our submitButton.

The designer makes it easy to design interfaces and work with them in code. The rest of this guide introduces the iOS Designer and demonstrates how to use it to build beautiful user interfaces painlessly.

Designer Basics

This section introduces the parts of the iOS Designer and provides a tour of its features.

Launching the Designer

To launch the iOS designer, create a new project. All Xamarin Studio project templates use Storyboards, provided it contains at least one View:

To launch the iOS designer, first create a new project. All Visual Studio project templates use Storyboards, provided it contains at least one View:

Once a project has been created, double-click on the .storyboard file to open it in Xamarin Studio. The designer window will open as illustrated by the following screenshot:

Once a project has been created, double-click on the .storyboard file to open it in Visual Studio. The designer window will open as illustrated by the following screenshot:

Designer Features

The designer is composed of five panes that support its various features, as outlined below:

  • Design Surface – Shown in the document area. Enables the visual construction of user interfaces.
  • Designer Toolbar – Perched at the top of the document area, the toolbar offers options for viewing manipulating the design surface and the objects on it, including screen size, orientation, OS version, constraints, and zoom.
  • Toolbox – Shows a list of controllers, views, objects, gesture recognizers, etc. that you can drag and drop onto the design surface.
  • Properties Pad – Shows the properties for the selected control including identity, look, and behavior.
  • Document Outline – Shows the tree of controls that compose the layout you are editing. You can click on an item in the tree to select it in the designer and see the properties in the Properties Pad. This is handy for selecting controls that are in a highly nested user interface, and hard to select on the designer surface.
  • Design Surface – Shown in the document area. Enables the visual construction of user interfaces.
  • Designer Toolbar – Perched at the top of the document area, the toolbar offers options for viewing manipulating the design surface and the objects on it, including screen size, orientation, OS version, constraints, and zoom.
  • Toolbox – Shows a list of controllers, views, objects, gesture recognizers, etc. that you can drag and drop onto the design surface.
  • Properties Window – Shows the properties for the selected control including identity, look, and behavior.
  • Solution Explorer – Shows current solution and all projects and files contained in it.
  • Document Outline(not shown) – Shows the tree of controls that compose the layout you are editing. You can click on an item in the tree to select it in the designer and see the properties in the Properties Pad. This is handy for selecting controls that are in a highly nested user interface, and hard to select on the designer surface.

Design Workflow

The designer allows controls from the toolbox to be dragged and dropped onto the designer surface. When you interact with controls on the designer either to add new ones or reposition existing ones, vertical and horizontal lines appear to mark the available insertion points where the controls can be added, as illustrated by the screenshot below:

The blue dotted line in the example above provides visual alignment guidelines to help with the Button placement.

Context Menu Commands

A context menu is available both on the designer surface and in the outline view. This menu shows commands available for the selected control as well as its parent view making it possible to run commands on containers, which are not easy to select on the designer surface. The menu is shown below:

Designer Toolbar

The designer toolbar appears at the top of the design surface and lets you select options for your layout. The toolbar resembes the following screenshot:

Size

With the introduction of the iPhone 6, 6 Plus, and Apple Watch, there are now a plethora of different screen sizes to cater for. These are explained in more detail in the Sizes and Filename guide. You can switch between the different iPhone Screen sizes using the drop down on the tool bar, as shown below:

Orientation

You can check the behavior of the controls at different orientations by using the orientation control to switch between landscape and portrait mode:

There is no available option for orientation lock in the iOS Designer. Orientation switching is for reference purposes only, and any changes made in one orientation will be reflected in the other.

Version

The look and feel of iOS was changed dramatically in iOS 7, when new UI guidelines were introduced. By default the design surface will show render your app in the most recent iOS version. You can use the designer toolbar to see what your app will look like in iOS 6 and earlier versions:

There is no available option for version lock in the iOS Designer. The version selection is for reference purposes only, and any changes made in one version will be reflected in the other.

Constraints

The constraints toolbar allows you to add and remove constraints and refresh the view to reflect new constraints:

Refer to the Auto Layout with the iOS Designer guide for more information on working with constraints.

Zoom Controls

The designer surface supports zooming via several controls as shown:

The controls include:

  1. Zoom to fit screen
  2. Zoom out
  3. Zoom in
  4. Zoom to actual size (1:1 pixel size)

These controls change the zoom level, making it easier to see certain areas of the user interface in the designer. They do not affect the user interface of the application at runtime.

Size Classes

iOS 8 introduced Unified Storyboard, which allow developers to create one, unified storyboard file that can be displayed in different sized devices by targeting multiple Size Classes. You can read more about Unified Storyboards, and size classes in the Introduction to Unified Storyboards guide.

Size classes are enabled on any new peoject as default. To enabled Size Classes for older projects, select the checkbox in the the Properties Pad:

You will be prompted by the dialog box below, select Enable Size Classes:

You can now select the size class required, straight from the toolbar:

For more guidance size classes, refer to the Size Classes section in Intro to Unified Storyboards guide.

Properties Pad

Properties Pane

The Properties Pad is the place to edit element identity, look, and behavior. The following screenshot illustrates the Properties Pad options for a button:

The Properties Pane is the place to edit element identity, look, and behavior. The following screenshot illustrates the Properties Pane options for a button:

Properties Pad Sections

Properties Pane Sections

The properties of a control can be changed in the Properties Pad. The Properties Pad is split into several sections, which make it easier to locate the properties:

The properties of a control can be changed in the Properties Pane. The Properties Pane is split into several sections, which make it easier to locate the properties:

  1. Widget - Main properties of the control, such as name, class, etc. Properties for managing the control’s content are usually placed here.
  2. Layout - Properties that keep track of the location and size of the control, as well as any constraints placed on that control.
  3. Events – For handling events such as touch, tap, drag, etc. Events can also be handled directly in code.

Editing Properties in the Property Pad

Editing Properties in the Property Pane

In addition to visual editing on the design surface, the designer supports editing control properties in the Properties Pad. The available properties change based upon what control is selected on the designer surface, as illustrated by the screenshots below:

In addition to visual editing on the design surface, the designer supports editing control properties in the Properties Pane. The available properties change based upon what control is selected on the designer surface, as illustrated by the screenshots below:

The Identity section of the Properties Pad now shows a module. It's rarely necessary to fill in this section as this is only used when interoperating with Swift classes. It allows you to enter a module name for Swift classes, which are namespaced.

Default Values

The properties of most controls will be blank in the Properties Pad because their values are inherited, usually from appearance proxies or themes. Themes are UI templates that "thematically" set the appearance and layout values of UI elements. They can be installed through the Xamarin Components Store.

The properties of most controls will be blank in the Properties Pane because their values are inherited, usually from appearance proxies or themes. Themes are UI templates that "thematically" set the appearance and layout values of UI elements. They can be installed through the Xamarin Components Store.

The Properties Pad will only show values that are explicitly set for the selected control, as opposed to passively inherited from a theme.

The Properties Pane will only show values that are explicitly set for the selected control, as opposed to passively inherited from a theme.

Event Handlers

You can specify custom handlers for events by filling out the Events tab of the Properties Pad. For example, the screenshot below specifies a HandleClick method to handle a TouchUpInside event on a button:

You can specify custom handlers for events by filling out the Events tab of the Properties Pane. For example, the screenshot below specifies a HandleClick method to handle a TouchUpInside event on a button:

Once an event handler is specified, a method of the same name must be added to the corresponding View Controller class to avoid the unrecognized selector exception:

For an example of using a custom event handlers, refer to the Using the iOS Designer Walkthrough.

Outline View

The control hierarchy that composes the layout can also be viewed in an Outline View. The outline is available by selecting the Document Outline tab, as shown below:

The selected control in the outline view stays in sync with the selected control on the designer surface. This is useful for selecting parent views, as well as any controls that might not be easy to select on the designer surface.

Revert Back to Xcode

While it is not recommended, it is possible to use the iOS Designer and Xcode Interface Builder interchangeably. To open a Storyboard in Xcode Interface Builder, right-click on a .storyboard file and select Open With... > Xcode Interface Builder, as illustrated by the screenshot below:

To revert back to the iOS Designer, double-click on the .storyboard file to open it.

Summary

This guide is an introduction to the iOS Designer for Xamarin Studio. It featured an overview of the designer features, and outlined the tools available for designing beautiful user interfaces using Xamarin Studio.

This guide is an introduction to the iOS Designer for Visual Studio. It featured an overview of the designer features, and outlined the tools available for designing beautiful user interfaces using Visual Studio.