Essence » Wiki » Grids » Version 17598

UI Elements > Grids


Grids are UI elements designed for layouting other elements. Grids are created using OSGridCreate.

A grid has two dimensions: the number of columns, and the number of rows. Each cell in the grid can either be empty or contain one child element. Child elements are added using OSGridAddElement. Each element has an additional layout field which determines how it will be laid out.

A grid can have a border. This is a space between the 4 sides of the grid's boundaries and the area in which elements will be placed. A grid can also keep elements spaced apart using a constant gap between columns and rows. Some grids have a background image.

Each column in the grid can have a different width, and each row in the grid can have a different height.

An example grid layout.

This is an example of 2x2 grid. This grid has a small border on each side, and a slightly smaller gap size. It has a background color, which makes it ideal for the placement of controls like labels. Each row has the same height, but the second column (index 1) has a greater width than the first column (index 0).

Grids use a simple algorithm for layouting, which occurs when it receives a OS_MESSAGE_LAYOUT message.

  • First, it measures the size of each element by sending each a OS_MESSAGE_MEASURE message.
  • It finds the widest element in each column, and makes that the width of the column.
  • It finds the tallest element in each row, and makes that the height of the row.
  • Each element is then sent their bounds through a OS_MESSAGE_LAYOUT message.

There are a few complications to this however.

Each element has an additional layout field which determines what happens when the cell bounds it receives are greater than its preferred size. The layout field is a combination of OS_CELL_ flags.

  • OS_CELL_H_EXPAND: regardless of the preferred width, use the cell bounds
  • OS_CELL_H_LEFT: align the element to the left of the cell bounds
  • OS_CELL_H_CENTER: align the element to the center of the cell bounds
  • OS_CELL_H_RIGHT: align the element to the right of the cell bounds
  • OS_CELL_V_EXPAND: regardless, of the preferred height, use the cell bounds
  • OS_CELL_V_TOP: align the element to the top of the cell bounds
  • OS_CELL_V_CENTER: align the element to the center of the cell bounds (beware: this may prove confusing to CSS developers)
  • OS_CELL_V_BOTTOM: align the element to the bottom of the cell bounds

An example of cell layouts.

This example shows the following cell layouts from left to right:


Using grids




OSObject OSGridCreate(unsigned columns, unsigned rows, OSGridStyle *style);