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

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.

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:

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.

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.

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:

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.

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.

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":"+1 555 5555"},
	{"id":2,"name":"Peter","phone":"+1 444 4445"},
	{"id":3,"name":"Andy","phone":"+1 333 4445"},
	{"id":4,"name":"Mom","phone":"+1 653 6555"}
  ],
  "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.

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.

The event sheet might look like below:

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. https://smartui-docs.pixelperfectstudio.mx/

Actions

`Set Enabled`

Disable/Enable the Grid-Layout

`Set Name`

Sets the name of the Grid-Layout.

`Set Sequence`

Sets the sequence index to influence the selection of components.

`Set Focusable`

Sets the component to be able to receive the focus

`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`

Sets whether the component should be processed when it's invisible. Opacity is not taken in consideration.It doesn't affect the visibility attribute of the object, you are responsible of turning it visible or invisible when needed.

`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.