Auto Layout with the Xamarin Designer for iOS
- PDF for offline use
- Related Articles:
- Related Links:
Let us know how you feel about this
last updated: 2017-03
This guide introduces iOS Auto Layout and the new constraints workflow available in the Xamarin Designer for iOS.
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.
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:
- Click on an empty space on the design surface. This deselects any elements and brings up the properties for the Storyboard document.
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:
- 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).
- Remove constraints — This option will remove all constraints applied to the element and revert to the default compile-time constraint addition.
- 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.
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.
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:
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.
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:
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 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 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 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.
Modifying Constraints in Code
Based on the requirements of your app, there might be times when you need to modify a constraint in code. For example, to resize or reposition the View a Constraint is attached to, to change a Constraint's priority or deactivate a Constraint altogether.
To access a Constraint in code, you first have to expose it in the iOS Designer by doing the following:
- Create the Constraint as normal (using any of the methods listed above).
In the Document Outline Explorer, find the desired Constraint and select it:
Next, assign a Name to the Constraint in the Widget tab of the Properties Explorer:
- Save your changes.
With the above changes in place, you can access the Constraint in code and modify its properties. For example, you can use the following to set the height of the attached View to zero:
ViewInfoHeight.Constant = 0;
Given the following setting for the Constraint in the iOS Designer:
The Deferred Layout Pass
Instead of instantly updating the attached View in response to Constraint changes, the Auto Layout Engine schedules a Deferred Layout Pass for the near future. During this deferred pass, not only is the given View's Constraint updated, the Constraints for every View in the hierarchy are recalculated and updated to adjust for the new layout.
At any point, you can schedule your own Deferred Layout Pass by calling the
SetNeedsUpdateConstraints methods of the parent View.
The Deferred Layout Pass consists of two unique passes through the view hierarchy:
- The Update Pass - In this pass, the Auto Layout Engine traverses the view hierarchy and invokes the
UpdateViewConstraintsmethod on all View Controllers and the
UpdateConstraintsmethod on all Views.
- The Layout Pass - Again, the Auto Layout Engine traverses the view hierarchy, but this time invokes the
ViewWillLayoutSubviewsmethod on all View Controllers and the
LayoutSubviewsmethod on all Views. The
LayoutSubviewsmethod updates the
Frameproperty of each subview with the rectangle calculated by the Auto Layout Engine.
Animating Constraint Changes
In addition to modifying Constraint properties, you can use Core Animation to animate changes to a View's Constraints. For example:
UIView.BeginAnimations("OpenInfo"); UIView.SetAnimationDuration(1.0f); ViewInfoHeight.Constant = 237; View.LayoutIfNeeded(); //Execute Animation UIView.CommitAnimations();
The key here is calling the
LayoutIfNeeded method of the parent view inside of the animation block. This tells the view to draw each "frame" of the animated location or size change. Without this line, the View would simply snap to the final version without animating.
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. Next, it explained how to troubleshoot three common constraints issues. Finally, it showed how to modify constraints in code.