Using Cocoa Layout Instrument to inspect automatic layout

Some time ago, MarkD discussed with us many useful diagnostic tools in Instruments, such as TimeProfiler and Energy Diagnostics template. Similarly, here I will provide an overview of CocoaLayoutInstrument.

[[154997]]

To help with exploration, I’ve created a simple example. This is an iPhone app that uses AutoLayout to lay out a UICollectionView and its UICollectionViewCell content. Download the example project with trace output here and get started.

CocoaLayoutInstrument can be used in the iOS simulator and Cocoa desktop applications, but cannot be used with a connected iOS device. CocoaLayoutInstrument provides a timeline of all events related to an instance of the NSLayoutConstraint class, which is very similar to a backtrace. Apple introduces the tool in the documentation related to AnalysisTools.

How to start Instrument?

Follow the steps below to open CocoaLayoutInstrument

1. Open the sample project

2. Select Product>Profile (shortcut)

3. Select the Cocoa layout template

4. The Instruments window will appear and will be paused. Click the red record button () in the upper left corner.

5. Slide the picture and click the Pause button to end the recording of the event.

In the rest of this post, I will use the traceback I provided for instructions and results. If you are like me, please open the cocoa-layout-instrument.trace file.

What can you see here?

The series of events listed below the timeline are collectively called the impact of the NSLayoutConstraint object, as shown in the figure below. All impact events are listed in chronological order, with the latest event at the end. Each event contains the following information:

• Caller: Which class and method triggers a constraint change

• Constraint: This column is the real meat and blood of the trace. You can identify which constraint is affected by the memory address of the constraint or by the identifier property (if available). The Constraint column also contains the VFL string that explains the relationship between the axis corresponding to the constraint line and the constraint definition.

• Constant: Defines the constant value of the constraint.

• Event: Details what operation has been performed on a constraint. The constraint may have been created, removed, or added to the window, or properties such as the identifier may have been modified or removed. These change events include:

①Create

②Add to window

③ Constant correction

④Identifier change

⑤Remove from window

Filtered event lists and timelines

First, filter the list to get the content you are interested in. In the upper right text box, mark the recorded data (RecordedData) and type 0x7ff4e948dce0 and 0x7ff4e948d6e0. Of course, your memory addresses will be different, so use the addresses you see here. Interestingly, this text box only filters VFL strings and memory addresses.

Now the list is the constraints we want. Let's look at the first event in the list, starting at line 0, where the (_:attribute:relatedBy:toItem:attribute:multiplier:constant:) method creates a constraint. In the constraint line of the list, you can see the relationship and attributes that make up this constraint, UILabel:0x7ff4e948dce0.leading==UIImageView:0x7ff4e948d6e0.leading. This means that the top edge of this UILabel object is equal to the top edge of this UIImageView. In the implementation, as this constraint is created, its identifier property is immediately set. The record output in the backtrace is an event: the identifier property is changed to subtitleLeadingConstraint.

In addition to filtering by memory address or constraint value, you can also focus on a subset of events. Click and drag the timeline horizontally to the top to specify a specific time range of events, as shown above. Similar to other tool sets, you will find that dragging the trace range slider on the left to zoom in on the stack depth (StackDepth) to peek at events at a finer time scale on the timeline.

Drag the scale slider to the right to see more

Other Control Panels and Buttons

Let's look at a few additional configurations this tool provides.

To change the visualization of events on the timeline, open the Recording Settings panel () and check the Stack Depth option under Statistics to Graph:

Optional configuration of the timeline in the record settings panel

For example, to change the visual style of the timeline:

Modify the timeline style

For a given event, you can also view the stack trace of all events leading up to that event. First, select an event and then open the Extended Detail panel (?-3). In the right panel of the Toolset window, the stack trace for that particular event is displayed.

A stack trace of an Auto Layout event

See the essence through appearance

The value of Instruments is that they give us deep insight into the inner workings of our code. CocoaLayoutInstrument extends this for Auto Layout, providing rich details about every step involved in the lifecycle of an interface.