Grid Layout

SmartUI Grid Layout Behavior operation and ACEs.

Grid Layout is an excellent option to arrange and present your components in a scene within a grid-like disposition. The component offers two operation modes: a layouter for static objects, and renderer for dynamic object rendering. It provides sufficient flexibility to handle multiple different objects per cell, opening the door to create really complex layouts and interactions, in combination with the rest of the elements of the SmartUI framework. It also inherits its features directly from the Container component, and provides the same navigation capabilities.

Rows and columns can have different width and height, set the properties: Cols Width, and Rows Height. See Changing Columns and Rows Size

Properties

Property	Description
Enabled	Enables or Disables the Grid-Layout and all its children.
Index	Index of the Grid-Layout within layout. Used for focusing the elements in the sequence order.
Invisible Component	Turns the component opacity to 0 while rendering it to allow invisible interactions.
Focusable	Marks if the component can have the focus.
Automatic-Color	Enables the component to darken a bit when its state is Disabled or when it's focused. Auto-Color is meant to provide a quick identification of the component state. For more specialized customizations, use the component events and disable this check.
Name	Unique name string for identifying the selected Grid-Layout
Operation Mode	Defines wheter the component behaves like a layouter, arranging objects; or as a Renderer, creating and destroying objects as per the datasource.
Render first	Render columns or rows first.
Columns	Number of columns for the Grid-Layout
Rows	Number of rows for the Grid-Layout
Scale Mode	Scale mode for the elements arranged in the Grid-layout
Col.Padding	Column's padding in pixels.
Row.Padding	Row's padding in pixels.
Cols.Width	Array of width percentage values per column, to render the width in pixels based on the Grid-Layout width . Values must be from 0 to 1. Greater values will be normalized
Rows.Height	Array of height percentage values per column, to render the height in pixels based on the Grid-Layout height . Values must be from 0 to 1. Greater values will be normalized
Paging	Enables paging for all the items in the data array. Paging is only relevant in Renderer mode, otherwise it has no effect.
Items per Page	Maximum number of items to render per page. Only relevant in Renderer mode.

📺 Video Demo

Layouter Mode

Layouter mode provides a quick arrangement of static objects in the scene. By static, we mean all the existing objects in the scene that are children of the Grid Layout container. Layouter is the default mode for the Grid Layout component.

By simply linking the child objects in the scene, the Grid Layout component will automatically identify what’s in its hierarchy and the grid configuration to arrange them instantly after the layout is created.

By design, Layouter's mode main purpose is to quickly arrange objects in a scene without the need to handle additional data sources, not to render dynamic data. For that purpose, see Renderer mode.

Initial object arrangement in the Layout

Grid Layouter will use the Document Flow determine the order of the components. Objects are handled in a list data structure, and their indexes are automatically mapped against the grid to render them in the correct cell."

Each object in the hierarchy is iterated. If the grid determines that it doesn’t use any of the SmartUI behaviors, the sequence index is omitted, and the object’s position becomes the only relevant attribute to determine the order.

Any world object can become a cell of the grid; you are not restricted to using only the Smart UI behaviors.

After running the scene, the objects are arranged as show below:

Objects are automatically arranged in the grid

Notice how the content of each cell does not match the size of the Grid Layout object. This is because, by default, the layouter will render the objects' original size in the layout you are designing. You can change the Scale Mode property of the Grid Layout from None to either fit the cell size or stretch the content to match the cell size.

None is de default scaling mode, keeping the original size of the object.

Scaling mode: None

Scaling mode: Fit

Scaling mode: Stretch

Changing Columns and Rows Size

Grid Layout supports multiple sizes for rows and columns. To change them, set the Cols Width and Rows Height properties. The input for those attributes is a list of values between 0 and 1, where 1 represents 100% of either the width or height of the Grid Layout's size.

For instance, if you have a 4x4 grid and want to add a titles row at the top, and also set the first column to contain a numeric ID, you can achieve this by keeping in mind the document flow logic to semi-arrange your objects in the layout. Your scene might look like the following to set up your Grid Layout.

Scene composition in Construct 3

Notice how the rows and columns have an approximate location, but are not quite precise, and that's perfectly fine. We are taking advantage of how the Document Flow iterates the objects in the scene.

The next step is to set up the width and height sizes as follows:

Columns and rows size distrubution.

The sum of the values for the rows height and columns width properties must be 1. If the sum is above 1, the values will be normalized, and the Grid Layout component will try to fit them within its rendering area

According to the image, we’ve indicated that the first column is 10% of the total width of the Grid Layout. Rows will follow the same structure, so the first row will also have 10% of the Grid Layout's height.

Final component arrangement after changing the columns and rows sizes.

If you fail to enter a value for either a column width or a row height in their respective lists, the component will default to an approximate even distribution of sizes for all the cells.

Layouter also supports dynamic insertion of objects; nevertheless, keep in mind that objects are still treated as a list but displayed in a grid arrangement. Therefore, if you add an object to a cell, all subsequent objects will be pushed down in the list, causing the grid to recalculate their positions using the Document Flow.

Renderer Mode

Renderer mode is designed to handle dynamic data and object creation based on a Grid Renderer Configuration File. The file can be imported into the Grid Layout component by calling the Set Datasource action, which takes a JSON object as input. The rendering features used by Layouter mode are still valid for Renderer mode.

Construct already provides AJAX, JSON, and file management capabilities. For this reason, the plugin considers the input throught the existing built-in plugins.

1. Use the AJAX plugin to retrieve the configuration file data.

2. When ajax succesfully retrieves the file, read the LastData attribute, parse it to a JSON object and call the Set Datasource action.

The action Set Datasource reads the JSON data, and creates a copy that is later stored in the Grid Layout component for rendering.

If you change by any mean the JSON plugin data, you must then call the Set Datasource action again and refresh the Grid Layout to render the information.

Data-change listeners attached to construct objects are not supported, primarily because construct does not have event triggers to attach these listeners to. Therefore, the data flow to the Grid Layout remains manual.

Grid Renderer Configuration File

The configuration file has two main keys in its structure: data and meta-data. Both keys have a 1-to-1 cardinality, meaning there should be the same number of entries.

• data (mandatory) key holds an array of objects containing the information you want to flow from the Grid Layout object to each cell.

• meta-data (mandatory) key describes how each cell should be rendered, allowing you to combine multiple different objects in the same grid.

• default-object (mandatory) key describes the object to render by default when there is no matching record between the data and meta-data arrays. This feature is useful in scenarios where you want to render the same object for all data rows. In such cases, the object-list key can be an empty array ([]).

  • object-name (mandatory) key describes the world-instance object that should be created.

  • create-hierarchy (mandatory) key indicates whether the object is created alone or with all its children.

  • template (mandatory) is applicable only if create-hierarchy is set to true. The instances will use the provided hierarchy template to create the instance.

• object-list (mandatory) key contains an array of objects. Its cardinality must be 1-to-1 with the data. However, you can still pass null values for each row. When the grid is rendering, if the meta-data row is either not found or null, the object to render will default to what is indicated in the default-object key. Each entry in this array has the same structure as the default-object key.

Renderer Config Example

{
  "data":[ 
	{"id":1,"name":"John","phone":"[phone]"},
	{"id":2,"name":"Peter","phone":"[phone]"},
	{"id":3,"name":"Andy","phone":"[phone]"},
	{"id":4,"name":"Mom","phone":"[phone]"}
  ],
  "meta-data":{
	"default-object": 
		{
		  "object-name":"MyDataBox",
   		  "create-hierarchy":true,
		  "template":"one"
		},
	"object-list":[
		{
		  "object-name":"MyGenericCell",
		  "create-hierarchy": true,
		  "template":"MyTemplate"
		},
		null,
		null,
		{
		  "object-name":"MyGenericCell",
		  "create-hierarchy": false,
		  "template":""
		},
	]
  }
}

Rendering Objects

Renderer mode, by default, destroys any children in the hierarchy and then takes the information from the configuration file. Objects will render automatically once the datasource is assigned. In contrast to Layouter mode, objects do not have to be children of the Grid Layout because they are created at runtime.

All children attributes (x, y, width, height, etc.) are transformed whenever the parent object changes.

You can customize the way you render the data source by adjusting any of the Grid Layout attributes.

Rendering Attributes

The component supports paging and a set of ACEs (Actions, Commands, and Events) to navigate between the pages created for the data. To enable paging, set the paging attribute to enabled and specify the total number of items to render per page.

Data flows automatically to each cell. To access it, you must use the Smart UI Data Listener Behavior. Add the On Render event from the data listener, which will be triggered by the Grid Layout for each cell.

Every time a cell is rendered, the information from the data field is passed to the data listener. To access it, use the expression Value followed by the name of the key you want to retrieve.

On Render is called just once per cell.

The DataListener behavior must be attached to the top-level object being rendered.

Using the configuration file example, we can render the contact information of a phone list in a Grid Layout component.

Rendering the contact information.

The event sheet might look like below:

On Render event receives the data from the Grid Layout

Accesing the "name" field of the data being rendered.

The MyBoxData has a child Text plugin attached to it, whenever the MyBoxData On Render event is called, the child Text plugin is picked and its value is then set from the DataListener.Value expression.

Smart UI GridLayout

Smart UI Grid-Layout behavior groups UI components, provides focusing abilities and default interactions to navigate within the Grid-Layout and its children components that uses Smart UI behaviors, and handles cascading Enabling/Disabling events. It also responds to pointer interactions prioritizing by zIndex.

Actions

---

Set Enabled

Disable/Enable the Grid-Layout

Parameter	Description
Enabled	Enabled/Disabled

Set Name

Sets the name of the Grid-Layout.

Parameter	Description
Name	Name of the component

Set Sequence

Sets the sequence index to influence the selection of components.

Parameter	Description
Index	Sequence index value. E.g. Indexes values of 0 are processed before indexes values of 1 and 2.

Set Focusable

Sets the component to be able to receive the focus

Parameter	Description
Focusable	Flag to allow the component to be focused.

Set Focus

Request the focus for this Grid-Layout

Focus First Element

Request the focus for the first interactable element of the Grid-Layout.

Focus Last Element

Request the focus for the last interactable element of the Grid-Layout.

Set Invisible Component

Turns the component opacity to 0 while rendering it to allow invisible interactions.

Parameter	Description
Invisible Component	Set if the component processed even if it's invisible: True/False

Refresh

Refreshes the layout, and arranges all the children in their corresponding cells. On Layouter mode, the grid-layout will try to determine the objects position sequentially. On Renderer mode, it will read all the entries from the datasource to render them in sequence.

Set Datasource

Sets the JSON plugin object that will provide the information to render the grid.

Parameter	Description
Datasource	JSON plugin object

Set Columns

Sets the number of columns the grid will render.

Parameter	Description
Columns	Max number of columns to render

Set Rows

Sets the number of rows the grid will render.

Parameter	Description
Rows	Max number of rows to render

Set Column Padding

Sets padding between columns.

Parameter	Description
Padding	Padding size in pixels

Set Row Padding

Sets padding between rows.

Parameter	Description
Padding	Padding size in pixels

Set Scaling

Sets the type of scaling the grid-layout will perform over all its content.

Parameter	Description
Mode	Scaling mode

Insert At

In Layouter mode, inserts an object in the specified column and row, displacing the following components on cell. The object is not added to the hierarchy of the grid-layout.

Parameter	Description
Object	Object instances to insert
Column	Zero-index based Column
Row	Zero-index based Row

Set Page

In Renderer mode, changes the page. Page numberes are zero-index based.

Parameter	Description
Page	Zero-index based page number.

Set Items per Page

Sets the total number of items to render per page.

Parameter	Description
Items	Max number of items to render per page.

Next Page

Switches to the next page available.

Previous Page

Switches to the previous page available.

Conditions

---

Is Enabled

Returns true if the Grid-Layout is enabled

Is Invisible Component

Returns true if the Grid-Layout is configured as an invisible component.

Compare Name

Returns true if the component's name equals the parameter

Parameter	Description
Name	Name to compare with the component picked.

Is Focused

Returns true if the Grid-Layout has the focus

Has Control

True if the Grid-Layout has the control to navigate over components.

On Focus

Triggered when the Grid-Layout gets the focus

On Focus Lost

Triggered when the Grid-Layout loses focus

Expressions

---

Name

Component name

Columns

Total Columns

Rows

Total rows

ColumnPadding

Column padding

RowPadding

Component name

CellHeight

Cell's height of the given coordinates (column,row)

Parameter	Description
Column	Zero-index based Column
Row	Zero-index based Row

CellWidth

Cell's width of the given coordinates (column,row)

Parameter	Description
Column	Zero-index based Column
Row	Zero-index based Row

Page

Current Page

MaxPages

Maximum Pages

(c) Pixel Perfect Studio 2024