com.codename1.ui

Class UIFragment

java.lang.Object

com.codename1.ui.UIFragment

public class UIFragment
extends Object

Encapsulates an XML or JSON template for a UI component hierarchy. The UI can be defined using XML. The XML is compiled into a view at runtime. Custom components may be injected into the template using special placeholder tags (i.e. tags where the tag name begins with '$'.

Supported Tags

• border - A container with layout=BorderLayout
• y - A container with layout=BoxLayout Y
• x - A container with layout=BoxLayout X
• flow - A container with layout=FlowLayout
• layered - A container with layout=LayeredLayout
• grid - A container with layout=GridLayout. Accepted attributes rows and cols
• table - A container with layout=TableLayout. Accepted attributes rows and cols. May have zero or more nested <tr> tags.
• label - A Label
• button - A button

Layout Variant Tags

BorderLayout and BoxLayout include some variant tags to customize their behaviour also:

• borderAbs, borderAbsolute - BorderLayout with center absolute behaviour. This is the same as <border behavior='absolute'/>
• borderTotalBelow - BorderLayout with Total Below center behaviour. This is the same as <border behavior='totalBelow'/>
• yBottomLast, ybl - BoxLayout with Y_BOTTOM_LAST setting.
• xNoGrow, xng - BoxLayout X with No Grow option. This is the same as <x noGrow='true'/>

Supported Attributes

• uiid - The UIID of the component. I.e. Component.getUIID()
• id - The ID of the component so that it can be retrieved using findById(java.lang.String)
• name - The name of the component (i.e. Component.getName()
• constraint - The layout constraint used for adding to the parent. Supports north, south, east, west, center, when parent is border
• rows - Used by grid only. Represents number of rows in grid or table.
• cols - Used by grid only. Represents number of columns in grid or table.
• behavior, behaviour - Used by Border Layout only. Specifies the center behaviour. Accepts values "scale", "absolute", and "totalBelow".
• noGrow - Used by <x> only. Specifies that BoxLayout should be X_AXIS_NO_GROW. Accepts values "true" and "false".
• bottomLast - Used by <y> only. Specifies that BoxLayout should use Y_AXIS_BOTTOM_LAST option. Accepts values "true" and "false"

Example XML Notation

 Form f = new Form("Test", new BorderLayout());
 String tpl = "<border>"
     + "<border constraint='center'><border constraint='south'><$button constraint='east'/></border></border>"
     + "<$search constraint='south'/>"
     + "</border>";

 f.setFormBottomPaddingEditingMode(true);
 TextField searchField = new TextField();
 searchField.addActionListener(e->{
    Log.p("Search field action performed");
 });
 Button submit = new Button("Submit");
 submit.addActionListener(e->{
     Log.p("Button action performed");
 });

 UIFragment template = UIFragment.parseXML(tpl)
     .set("button", submit)
     .set("search", searchField);
 f.add(BorderLayout.CENTER, template.getView());
 f.show();
 

JSON Notation

When trying to express a UI structure inside a Java String, the XML notation may be a little bit verbose and cumbersome. For this reason, there is an alternative JSON-based notation that will allow you to express a UI structure more succinctly.

A JSON object (i.e. curly braces) denotes a Container. If this object includes properties corresponding to the constraints of BorderLayout (e.g. center, east, west, north, south, or overlay), then the container will use a BorderLayout, and the associated properties will represent its children with the appropriate constraint.

E.g.:

 {center:'Center Label', south:'South Content'}

Will create a Container with labels in its BorderLayout.CENTER and BorderLayout.SOUTH positions.

To make things even more succinct, it supports single-character property keys for the BorderLayout constraint values. E.g. The following is equivalent to the previous example:

 {c:'Center Label', s:'South Content'}
 
 
Other Layouts:
 

    
Flow Layout -  {flow:[...]}
    
Grid Layout -  {grid:[...], cols:3, rows:2}
    
Box Layout X -  {x:[...]}
    
Box Layout Y -  {y:[...]}
    
Layered Layout -  {layered:[...]}
    
Table Layout -  {table:[['A1', 'B1', 'C1'], ['A2', 'B2', 'C2'], ...]}
 
 
 
Layout Variants
 
 
BoxLayout and BorderLayout include variant shorthands to customize their behaviour.
 
 

  
xNoGrow, xng - Same as  {x:[...], noGrow:true}
  
yBottomLast, ybl - Same as  {y:[...], bottomLast:true}
  
centerAbsolute, centerAbs, ca - Same as  {center:[...], behavior:absolute}
  
centerTotalBelow, ctb - Same as  {center:[...], behavior:totalBelow}
 
 
 
Embedding Placeholders/Parameters
 
The notation for embedding placeholder components (which must be injected via set(java.lang.String, com.codename1.ui.Component)), 
 is similar to the XML equivalent.  Just place the parmeter name, prefixed with '$'.  E.g. 
 
 $submitButton
 
 
 
Example JSON Notation
 
 
 

 Component view = UIFragment.parseJSON("{n:['Hello', 'World', $checkbox], c:[y, {class:'MyTable', table:[['Username', $username], ['Password', $password]]}, {flow:['Some text'], align:center}], s:$submit}")
     .set("username", new TextField())
     .set("password", new TextField())
     .set("submit", new Button("Submit"))
     .set("checkbox", new CheckBox("Check Me"))
     .getView();
 

Since:

7.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	UIFragment.ComponentFactory A factory for converting XML elements to Components.
static class	UIFragment.DefaultComponentFactory Default component factory that is used in templates.

Method Summary

Modifier and Type	Method and Description
Component	findById(String id) Gets a component in the template by its ID.
UIFragment.ComponentFactory	getFactory() Gets the component factory that is currently set for this fragment.
Container	getView() Gets the view that is generated by this template.
static UIFragment	parseJSON(String json) Parses a JSON string into a template.
static UIFragment	parseXML(InputStream input) Parses input stream of XML into a Template
static UIFragment	parseXML(String xml) Parses XML string into a Template
UIFragment	set(String paramName, Component param) Sets a parameter component in this template.
UIFragment	setFactory(UIFragment.ComponentFactory factory) Sets the component factory to be used.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

parseXML

public static UIFragment parseXML(InputStream input)

Parses input stream of XML into a Template

Parameters:

input - InputStream with XML content to parse

Returns:

The corresponding template, or a RuntimeException if parsing failed.

parseXML

public static UIFragment parseXML(String xml)

Parses XML string into a Template

Parameters:

xml - XML string describing a UI.

Returns:

The corresponding template, or a RuntimeException if parsing failed.

parseJSON

public static UIFragment parseJSON(String json)

Parses a JSON string into a template.

Parameters:

json - A JSON string representing a UI hierarchy.

Returns:

Throws:

IOException

getView

public Container getView()

Gets the view that is generated by this template.

Returns:

set

public UIFragment set(String paramName,
                      Component param)

Sets a parameter component in this template. Templates that include "parameter" tags will inject these parameters into the resulting view.

Parameters:

paramName - The name of the parameter.

param - The component to inject into the template.

Returns:

Self for chaining.

findById

public Component findById(String id)

Gets a component in the template by its ID.

Parameters:

id - The ID of the component.

Returns:

The component with matching ID.

getFactory

public UIFragment.ComponentFactory getFactory()

Gets the component factory that is currently set for this fragment.

Returns:

the factory

setFactory

public UIFragment setFactory(UIFragment.ComponentFactory factory)

Sets the component factory to be used.

Parameters:

factory - the factory to set

Returns:

Self for chaining