Cross Platform
Android
iOS
Mac
Test Cloud

Auto Layout with the Xamarin Designer for iOS

This guide introduces iOS Auto Layout and the new constraints workflow available in the Xamarin Designer for iOS.

Overview

Auto Layout (also called “adaptive layout”) is a responsive design approach. Unlike the transitional layout system, where each element’s location is hard-coded to a point on the screen, Auto Layout is about relationships - the positions of elements relative to other elements on the design surface. At the heart of Auto Layout is the idea of constraints or rules that define the placement of an element or set of elements in the context of other elements on the screen. Because the elements are not tied to a particular position on the screen, constraints help create an adaptive layout that looks good on different screen sizes and device orientations.

In this guide, we introduce constraints and how to work with them in the Xamarin iOS Designer. This guide does not cover working with constraints programmatically. For information on using Auto Layout programmatically, refer to the the Apple documentation.

Requirements

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

This guide assumes knowledge of the Designer's components from the Introduction to the iOS Designer guide.

Introduction to Constraints

A constraint is a mathematical representation of the relationship between two elements on the screen. Representing a UI element’s position as a mathematical relationship solves several problems associated with hard-coding a UI element’s location. For example, if we were to place a button 20px from the bottom of the screen in portrait mode, the button’s position would be off the screen in landscape mode. To avoid this, we could set a constraint that places the bottom edge of the button 20px from the bottom of the view. The position for the button edge would then be calculated as button.bottom = view.bottom - 20px, which would place the button 20px from the bottom of the view in both portrait and landscape mode. The ability to calculate placement based on a mathematical relationship is what makes constraints so useful in UI design.

When we set a constraint, we create an NSLayoutConstraint object which takes as arguments the objects to be constrained and the properties, or attributes, that the constraint will act on. In the iOS designer, attributes include edges such as the left, right, top, and bottom of an element. They also include size attributes such as height and width, and the center point location, centerX and centerY. For example, when we add a constraint on the position of the left boundary of two buttons, the Designer is generating the following code under the covers:

View.AddConstraint (NSLayoutConstraint.Create (Button1, NSLayoutAttribute.Left, NSLayoutRelation.Equal, Button2, NSLayoutAttribute.Left, 1, 10));

Working with Constraints

This section covers working with constraints using the iOS Designer, including enabling and disabling Auto Layout and using the Constraints Toolbar.

Enable Auto Layout

The default iOS Designer configuration has constraint mode enabled. However, should you need to enable or disable it manually, you can do so in two steps:

  1. Click on an empty space on the design surface. This deselects any elements and brings up the properties for the Storyboard document.
  2. Check or uncheck the Use Autolayout checkbox in the property panel:

By default, no constraints are created or visible on the surface. Instead, they are automatically inferred from the frame information at compile time. To add constraints, we need to select an element on the design surface and add constraints to it. We can do that using the Constraint Toolbar.

The Constraint Toolbar

When constraint mode (Auto Layout) is enabled, the following buttons appear in the toolbar at the top of the design surface:

To use these toolbar buttons, select a single view on the canvas and choose one of the following options from the toolbar:

  1. Add constraints — This button adds a default set of constraints to the item. It will always add two position constraints (top/bottom + left/right). It will add size constraints if the element has no intrinsic size (e.g. UIButton has full intrinsic size, whereas UITextField only has an intrinsic height).
  2. Remove constraints — This option will remove all constraints applied to the element and revert to the default compile-time constraint addition.
  3. Update frames based on constraints — Occasionally the element frame may get out of sync with newly added constraints (see the [frame misplacement] section for more information on this issue). If this happens, this button will automatically adjust the element frame to match the position the constraints are defining.

Surface-Based Constraint Editing

In the previous section, we learned to add default constraints and remove constraints using the Constraints Toolbar. For more fine-tuned constraint editing, we can interact with constraints directly on the design surface. This section introduces the basics of surface-based constraint editing, including pin-spacing controls, drop areas, and working with different types of constraints.

Creating Constraints

The iOS Designer tool offers two types of controls for manipulating elements on the design surface. The first type of controls are called dragging controls. These are toggled by clicking on an element once, and they allow us to drag an element to a different place on the design surface. The selection handles of an element in dragging mode should look like this:

We can double-click on an element to toggle pin-spacing controls and enter the constraint editing mode. The selection handles of the element in constraint mode look like this:

The 4 T-shaped handles on each side of the element define the top, right, bottom, and left edges of the element for a constraint. The two I-shaped handles at the right and bottom of the element define height and width constraint respectively. The middle square handles both centerX and centerY constraints.

To create a constraint, pick a handle and drag it somewhere on the design surface. When you start the drag, a series of green lines/boxes will appear on the surface telling you what you can constrain. For example, in the screenshot below, we are constraining the top side of the middle button:

Note the three dashed green lines across the other two buttons. The green lines indicate drop areas, or the attributes of other elements to which we can constrain. In the screenshot above, the other two buttons offer 3 vertical drop areas ( bottom, centerY, top) to constrain our button. The dashed green line at the top of the view means the view controller offers a constraint at the top of the view, and the solid green box means the view controller offers a constraint below the top layout guide .

Note: Layout guides are special types of constraint targets that allow us to create top and bottom constraints that take into account the presence of system bars, such as status bars or toolbars. One of the main uses is to have an app compatible between iOS 6 and iOS 7 since the newest version has the container view extending below the status bar. For more information on the top layout guide, refer to the Apple documentation.

The next three sections introduce working with different types of constraints.

Size Constraints

With size constraints - height and width - you have two options. The first option is to drag the handle to constrain to a neighbor element size, as illustrated by the example above. The other option is to double-click the handle to create a self-constraint. This allows us to specify a constant size value, as illustrated by the screenshot below:

Center Constraints

The square handle will create a centerX or centerY constraint, depending on the context. Dragging the square handle will light up the other elements to offer both vertical and horizontal drop areas, as illustrated by the screenshot below:

If you choose a vertical drop area, a centerY constraint will be created. If you choose a horizontal drop area, the constraint will be based on centerX.

Combinational Constraints

To create both alignment and size equality constraints between two elements, you can select items from a top toolbar to specify - in order - horizontal alignment, vertical alignment and size equalities, as illustrated by the screenshot below:

Visualizing and Editing Constraints

When you add a constraint, it will be displayed on the design surface as a blue line when you select an item:

You can select a constraint by clicking on a blue line and editing the constraint values directly in the property panel. Alternatively, double-clicking on a blue line will bring up a popover that lets you edit the values directly on the design surface:

Constraint Issues

Several types of issues can arise when using constraints:

  • Conflicting constraints — This happens when multiple constraints force the element to have conflicting values for an attribute and the constraint engine is unable to reconcile them.
  • Underconstrained items — An element’s properties (location + size) must be entirely covered by its set of constraints and intrinsic sizes for the constraints to be valid. If these values are ambiguous, the item is said to be underconstrained.
  • Frame misplacement — This occurs when an element’s frame and its set of constraints define two different resulting rectangles.

This section elaborates on the three issues listed above, and provides details on how to handle them.

Conflicting Constraints

Conflicting constraints are marked in red and have a warning symbol. Hovering over the warning symbols brings up a popover with information about the conflict:

Underconstrained Items

Underconstrained items appear in orange and trigger the appearance of an orange marker icon in the view controller object bar:

If you click on that marker icon, you can get information about underconstrained items in the scene and solve the issues by either fully constraining them or by removing their constraints, as illustrated by the screenshot below:

Frame Misplacement

Frame misplacement uses the same color code as underconstrained items. The item will always be rendered on the surface using its native frame, but in the case of a frame misplacement a red rectangle will mark where the item will end up when the application runs, as illustrated by the screenshot below:

To resolve frame misplacement errors, select the Update Frames Based on Constraints button from the constraints toolbar (far right button):

This will automatically adjust the element frame to match the positions defined by the controls.

Summary

This guide introduced iOS Auto (or “adaptive”) Layout and the concept of constraints as mathematical representations of relationships between elements on the design surface. It described how to enable Auto Layout in the iOS designer, working with the Constraints toolbar, and editing constraints individually on the design surface. Finally, it explained how to troubleshoot three common constraints issues.