CELL
Base element for layout design. It provides complex layout capabilities with embedded rows and columns, and relative pixel-positioning.
CELL is an invisible element, which is used for the calculation of the position of other elements inside it (other CELLs or widgets). CELL can have one of three layout_types that defines how inner elements are placed: in a row, column, or layer_stack (one over another).
You can write <CELL layout_type="row"> or <ROW>. So, there are three shortcut elements for CELL named ROW, COLUMN, and LAYER_STACK. By the way, default CELL's layout_type is "column", so COLUMN or CELL are usually the same. The only difference is that you can't change layout_type for COLUMN, as it is fixed.
Many of KUIML elements inherit CELL properties, so you can use them inside WIDGETs or SKIN (which is a root CELL and can also have layout_type, font_face, etc).
See some examples below, they show most of the KUIML layout possibilities.
Attributes brief detailed show all inherited
Examples
As CELLs are invisible, let's use a few WIDGET elements with background_color attribute for the following examples. Instead of these colored squares you can use knobs, text and other elements of your layout.
The SKIN is the root cell and its layout_type is "column" by default.
- <?xml version="1.0" encoding="utf-8" ?>
- <SKIN>
- <!-- define some new elements -->
- <DEFINE>
- <_SQUARE base_type="WIDGET" width="25" height="25" />
- <BLUE base_type="_SQUARE" background_color="#5799F0" />
- <MAGENTA base_type="_SQUARE" background_color="#BC69FB" />
- <PURPLE base_type="_SQUARE" background_color="#FB78D5" />
- <RED base_type="_SQUARE" background_color="#FB6E6E" />
- <ORANGE base_type="_SQUARE" background_color="#FBB469" />
- <YELLOW base_type="_SQUARE" background_color="#F9DC00" />
- <LIME base_type="_SQUARE" background_color="#B0D604" />
- <GREEN base_type="_SQUARE" background_color="#2ED604" />
- </DEFINE>
- <!-- using the elements we've just defined -->
- <BLUE />
- <MAGENTA />
- <PURPLE />
- <RED />
- <ORANGE />
- <YELLOW />
- <LIME />
- <GREEN />
- </SKIN>

In a row
If we want to place them horizontally we can either set SKIN layout_type="row", or add another ROW element (or any CELL-ish element with layout_type="row").
Just for fun let's reverse them using <ROW flip="true"> (or flip="1").
Let's make two rows and add some spacing between elements.
As a stack
Let's put elements one over another.
- <BLUE width="100" height="100" />
- <LIME width="80" height="80" />
- <MAGENTA width="60" height="60" />
- <YELLOW width="40" height="40" />
- <RED width="20" height="20" />
- </LAYER_STACK>
As you see they are perfectly centered. We may align them inside the parent cell using h/v_align. Also we can change their position using h/v_offset (relative to calculated position) or h/v_position (relative to parent element).
- <BLUE width="100" height="100" />
- <LIME width="80" height="80" h_align="left" v_align="top" />
- <MAGENTA width="60" height="60" h_offset="15" v_offset="10" layout_type="layer_stack">
- <YELLOW width="40" height="40" />
- <RED width="20" height="20" h_position="35" />
- </MAGENTA>
- </LAYER_STACK>
The cool thing about h/v_offset is that you can change that dynamically, and thus move/animate an object.
- <BLUE width="100" height="100" />
- <YELLOW id="movable" width="60" height="60" />
- </LAYER_STACK>
- <!-- create params with a range and link them to h/v_offset -->
- <PARAM id="xpos" min="-40" max="40" default="0" />
- <PARAM id="ypos" min="-40" max="40" default="0" />
- <PARAM_LINK from="xpos" to="movable.h_offset" />
- <PARAM_LINK from="ypos" to="movable.v_offset" />
- <!-- add controls -->
- <ROW>
- <PARAM_TEXT_CONTROL param_id="xpos" />
- <PARAM_TEXT_CONTROL param_id="ypos" />
- </ROW>
Exploring flex and display
If we set a parent element to a width (or height) greater than sum of its childrens, we can use the flex attribute to distribute that extra space between children (so that they stretch to take that space). We can also use display attribute to dynamically change the layout.
- <ROW width="200">
- <RED />
- <ORANGE flex="1" />
- <YELLOW flex="0.5" />
- <PURPLE id="showable" display="false" />
- <LIME />
- </ROW>
- <!-- the control -->
- <PARAM_TEXT param_id="showable.display" content="display: {text_value}">
- <INVISIBLE_PARAM_BUTTON param_id="showable.display" positions_count="2" width="100%" height="100%" cursor="system::hand" />
- </PARAM_TEXT>
Note that WIDGET-type elements also have "visible" attribute, which can show or hide the element without changing the layout.
To illustrate spacing_flex attribute we also need a parent with a size greater than sum of its children.
- <WIDGET background_color="#5799F0" margin="7">
- <WIDGET background_color="#FFFFFF">
- <COLUMN spacing="10" width="180">
- <ROW width="100%" spacing="5" >
- <RED /><ORANGE /><YELLOW /><GREEN />
- </ROW>
- <ROW width="100%" spacing_flex="1" >
- <RED /><ORANGE /><YELLOW /><GREEN />
- </ROW>
- </COLUMN>
- </WIDGET>
- </WIDGET>
Here we used a margin to create a blue "border" (we just added more space around the the top blue WIDGET to make it bigger than inner white WIDGET, and so the blue is partly visible). There are h_margin and v_margin attributes if you want to set them separately.
Size of the element
We can set the width or the height of the element in pixels or percents (relative to parent). If we omit width or height attributes, they will be calculated using the size of the inner contents.
We can also use min_width, max_width and min_height, max_height attributes designing the layout. They can be set in pixels only.
- <WIDGET background_color="#5799F0" margin="7" spacing="7">
- <!-- auto stretches to content's width -->
- <WIDGET background_color="#FFFFFF" layout_type="row" spacing="10">
- <TEXT value="This width is auto calculated" />
- </WIDGET>
- <!-- min_width is set, though content takes less space -->
- <WIDGET background_color="#FFFFFF" layout_type="row" spacing="10" min_width="150">
- <TEXT value="Min width is set" />
- </WIDGET>
- <!-- max_width is set and it is not reached -->
- <WIDGET background_color="#FFFFFF" layout_type="row" spacing="10" max_width="150">
- <TEXT value="Max width is set" />
- </WIDGET>
- <!-- fixed width - content is truncated -->
- <WIDGET background_color="#FFFFFF" layout_type="row" spacing="10" width="150">
- <TEXT value="This is fixed, so the text is truncated" />
- </WIDGET>
- </WIDGET>
Content alignment
Instead of using h_align and v_align on each element individually, you can set the alignment in the parent cell, usign internal_h_align (works for rows only) and internal_v_align (for columns only).
- <WIDGET background_color="#5799F0" margin="7" spacing="7">
- <WIDGET background_color="#FFFFFF" layout_type="row" spacing="2" width="200" internal_h_align="left">
- <TEXT value="Text" />
- <TEXT value="left" />
- <TEXT value="aligned" />
- </WIDGET>
- <WIDGET background_color="#FFFFFF" layout_type="column" height="120" internal_v_align="top">
- <TEXT value="Text" />
- <TEXT value="top" />
- <TEXT value="aligned" />
- </WIDGET>
- </WIDGET>
Note that the TEXT element inherits CELL attributes, so you can set fixed width or height for the TEXT and use its text_h_align or text_v_align (common for all text widgets) attrubutes for further text alignment.
Magical reflow
This is a trick that can be used for fixed width rows or fixed height columns: if the content doesn't fit, it goes to the "next line" using reflow.
- <WIDGET background_color="#333333" margin="7" spacing="7">
- <!-- example of using text "reflow" on a row with fixed size -->
- <WIDGET background_color="#FFFFFF" layout_type="row" width="120" reflow="true">
- <TEXT value="There" />
- <TEXT value="is" />
- <TEXT value="too" />
- <TEXT value="much" />
- <TEXT value="text" />
- <TEXT value="that" />
- <TEXT value="doesn't" />
- <TEXT value="fit" />
- <TEXT value="but" />
- <TEXT value="reflow" font_weight="bold" />
- <TEXT value="helps!" />
- </WIDGET>
- <!-- content that doesn't fit is taken to the "next line" -->
- <WIDGET background_color="#FFFFFF" layout_type="row" width="110" reflow="true" internal_h_align="left">
- <BLUE /><MAGENTA /><PURPLE /><RED /><ORANGE /><YELLOW /><LIME />
- </WIDGET>
- </WIDGET>