Organizing your UI with containers

These methods are being deprecated, while they still work it is recommended that you use the qnx.fuse.ui.core API andqnx.fuse.ui.layouts to develop your application's UI.

You can use the Container class to create a container to organize the UI components of your application. The Container class manages the positioning, size, and layout of any UI component that it contains. A container can also contain other containers, called subcontainers.

Containers are also useful for resizing and laying out child components to respond to orientation changes. An orientation change occurs when the user tilts the device, such as when the user switches from portrait to landscape mode.

A parent container refers to any container that contains one or more subcontainers. A child container refers to any container that is nested within a parent container. To understand how child components are arranged and sized within a parent container, you must understand the following concepts:

  • Placing a child component within a flow
  • Aligning a child within a flow
  • Adjusting the size of a child parallel to the container flow
  • Adjusting the size of a child perpendicular to the container flow
  • Docking a child component

Placing a child component within a container flow

Container flow is the layout orientation and direction of all child components relative to the near edge of the parent container. A container can define two flow directions: vertical and horizontal. In a container with a vertical flow, the near edge is the top edge of the container. In a container with a horizontal flow, the near edge is the left edge of the container. The flow position is the position of a child component within the flow of a parent container.

If flow property for a parent container is set to ContainerFlow.HORIZONTAL, the children of the container (which may also be containers) will appear horizontally opposed, or side by side within the container.

If a container uses a vertical flow (ContainerFlow.VERTICAL) all subcomponents within this container appear vertically-opposed, or one on top of another. The mySub container is show below.

Components appear in the order in which you add them to a container, such that the top-most component in a container is the component that is first added to the container. This is always true unless a component is docked.

Aligning a child component within a container flow

The opposite position refers to the position of a child in the direction opposite to the flow of the container. You can define the opposite position of a child by setting the align property of the parent container. The align property defines the alignment of each subcomponent in the direction opposite to the flow of the container. In a container with a vertical flow, the align property specifies the horizontal position (x coordinate) of the subcomponent, relative to the left edge of the container. In a container with a horizontal flow, the align property specifies the vertical position (y coordinate) of the subcomponent relative to the top edge of the container.

The align property has the following values:

  • ContainerAlign.NEAR
  • ContainerAlign.MID
  • ContainerAlign.FAR
Each value represents a position relative to the initial edge of the container. You can specify the ContainerAlign.NEAR property to place a subcomponent closest to the initial edge of a parent container. You can specify the ContainerAlign.FAR property to place a subcomponent furthest from the initial edge of the parent container. The ContainerAlign.MID value is the default.

The following figure illustrates each align property in a single container. You can use the container's padding property to set the amount of space (in pixels) between each subcomponent.

Adjusting the size of a child parallel to the container flow

Flow size refers to the size of a child component in the direction of the flow of the parent container. For example, the height of a button in a container with a vertical flow, or the width of a button in a container with a horizontal flow.

The container sets the flow size for a child only if the child implements IContainable and the child's IContainable.size property is not 0. Otherwise, the flow size of the child component is not changed during layout operations.

Adjusting the size of a child perpendicular to the container flow

Opposite size refers to the size of a child in the direction opposite to the flow of the parent container. For example, the height of a button in the container with a horizontal flow, or the width of a button in a parent container with a vertical flow.

The parent container resizes a child component in the opposite direction if the child implements IContainable and IContainable.sizeMod is set to SizeMode.BOTH. When SizeMode.BOTH is set, any container alignment settings are ignored, and the opposite size for a child is set to fill the available remaining container space in the opposite direction.

The following illustration shows the opposite size and flow size of subcomponents as it relates to the flow direction of a parent container.

Docking a child component

You can dock a child component to anchor it adjacent to any edge of the parent container.

If a component implements IContainment, you can set its containment property to dock it to any edge of the stage. When a resize event occurs, all docked components are laid out first, in the order in which they are added to the parent. The remaining child objects are placed in the remaining container space.