In Depth: Layout

Ares’ Interface Builder has an advanced layout system that is extremely flexible. The core of this system are four basic panel types, each of which lay out their child widgets (widgets inside of the panel) in a certain way. Panels are containers for other widgets, and may be combined and nested to create complex and flexible layouts. First we will go over the four panel types.

Panels

VBox Panel

This is the default behavior of the main Interface Builder canvas (though this can be overridden by setting the layoutKind of the canvas in the property inspector)

VBox lays out its child widgets vertically. So each widget within a VBox panel is stacked above/below other widgets. When you drag a widget out, the designer will only let you drag the widget to a particular spot in the stack. If you want to have a widget go to one side of another widget, you must place a HBox Panel in the stack and put your side-by-side widgets within that.

Hbox Panel

This operates in a similar way to VBox Panel, but arranges its children horizontally. This is used when you want to arrange two or more widgets horizontally across the screen.

Absolute Panel

This operates differently than HBox or VBox Panel. An Absolute Panel lets you exactly position and size its children. This is extremely precise, but less flexible when the screen size or orientation changes. You can use the Resize Behavior control in the property inspector to set which of its parent’s margins you wish to maintain an exact relationship to by setting the red “struts”. In the example picture, the widget will maintain the exact set distance to the left and top margin, regardless of what happens to the size or orientation of the Absolute Panel.

Combining Panels

You can nest panels within other panels to create extremely flexible and advanced layouts. As an example, the entire Ares GUI was made using VBox and HBox panels! This picture is an example of a complex nested layout using all three panel types.

The main canvas is in blue and has a height and width of 100% and contains everything else within it.

The first child in the main canvas is an orange HBox Panel containing 4 widgets next to each other horizontally.

The Absolute Panel is in Green and has a height and width of 100%

Below both of those are two widgets that are within the main canvas so they are stacked vertically at the bottom - one has a set width, and the other has a width of 100%.

If you were to resize or rotate this screen, the absolute panel, because it has a “relative” height (because it is set to 100% which is relative to the space it is given, would resize. The other widgets would stay the same. And the widget in the Absolute Panel would stay exactly in the same spot relative to the red lines, so it would end up closer to the bottom and right margins as the panel shrinks with the UI.

Practice a bit nesting panels within panels and you will pick it up quickly. We recommend using mostly HBox and VBox panels as this provides the most flexibility.

Other Special Panels

 

There are two other panels you can use to create advanced layouts.

Scroller

This is a scrolling panel. If you want your whole app to scroll, which it wont by default (different than mojo), you want to first drag and scroller widget out and select "Maximize" from the property inspector. Then your whole screen will scroll. Alternately any sub-container of your application can be made to scroll this same way - drag a scroller into a panel and select "maximize". Scrollers can be added into any other kind of panel.

Drawer/Collapsable

These panels are similar, only one has a header to control it and the other does not by default. These containers can be activated by event code or user action to expand and collapse to show/hide their contents. This is useful for advanced options on a screen, or other places you wish to hide certain content.

 

Sizing Widgets and Panels

Geometry

In the property inspector, there is a section for “Geometry”. This contains all of the attributes for a given widget or panel, which can be manipulated directly or through a number of different means. First to explain the various properties:

Left, Right, Top, Bottom refer to the distance between a widget’s bounding box and it’s parent container’s margins (the selection box with the resize handles). Valid values in this section are % or px. (e.g. - 100%, 50%, 50px, 50)

Width and Height refer to the widget’s height and width values. These can also be in % of px values. Percentage is relative to the available space - 100% will take up all of the available space not counting other widgets. So three widgets can share a panel, all at 100% width, and they will each take up 33.3% of the actual space. You can adjust these % relative to each other to cause them to take up different widths. Percentage values in width or height make the widgets flexible, which is helpful when designing for different screen resolutions or orientations.

Plane specifies what z-axis plane a widget or panel is on, similar to z-index in CSS. This is used to place specified widgets or panels in the foreground, while other widgets scroll behind, for example.

horizontalAlign and verticalAlign can be used on a widget or panel to align it to the right, left, or center in its parent. In the example images above for VBox Panels, all of the widgets were right aligned, but each widget can have its own independent alignment. On all panels, these properties will override left and right values.

Designer

The designer sets these properties automatically when you position and resize widgets and panels using the resize handles on the edges and corners of the selection box. This is the fastest and easiest way to arrange widgets within a given Panel’s constraints.

Sizing Tools

These are three buttons, which serve as shortcuts to set the width and height to 100% , which will cause the widget to take up all of the available space in both directions. The Maximize button sets it in both directions, while the X and Y buttons set the width or the height respectively.

Resize Behavior

This control can be used to create specific behavior for when the screen size or orientation is changed. The control consists of red “struts” and green “springs” which can be set by clicking them on or off. There is some interaction between the two, depending on what type of Panel you are in.

VBox & HBox Panels - Generally it is best to set the Geometry attributes for VBox and HBox Panels via the properties themselves and the designer. The Resize Behavior control does affect some properties but they are of limited use.

Absolute Panels - Here is where it gets interesting:

• Left Strut selected, Right Strut selected, Horizontal Spring selected: the widget will maintain a set distance between the left and right margin of its parent and its edges, and the widget will grow and shrink in width to maintain this.
• Left Struct selected, all other springs/struts not selected: The widget will maintain a set distance between its parents’ left margin and its left edge, and the width will stay the same. The distance between its parents’ right margin and right edge of the widget will shrink and grow as the screen size changes
• Right Strut selected, all other springs/struts not selected: The widget will maintain a set distance between its parents’ right margin and its right edge, and the width will stay the same. The distance between its parents’ left margin and left edge of the widget will shring and grow as the screen size changes
• For Top/Bottom Struts and the Vertical Spring, the same pattern applies as the Left/Right/Horizontal ones.

The best way to learn how all of this works is trial and error, so please do experiment as much as possible with a test application.

Other Notes

Not all widgets can render in design mode, such as webview, which requires a webkit extension present only on the device/emulator. Those widgets are represented only as a blank container in design mode.