Class UIFragment

java.lang.Object
com.codename1.ui.UIFragment
public final 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 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 ``

  • borderTotalBelow - BorderLayout with Total Below center behaviour. This is the same as ``

  • yBottomLast, ybl - BoxLayout with Y_BOTTOM_LAST setting.

  • xNoGrow, xng - BoxLayout X with No Grow option. This is the same as ``

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 `` only. Specifies that BoxLayout should be X_AXIS_NO_GROW. Accepts values "true" and "false".

  • bottomLast - Used by `` 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'><$search constraint='south'/></border>"
    + "<$button 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 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();

  • Method Details

    • 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.
      Throws
      • IOException

    • getView

      public Container getView()
      Gets the view that is generated by this template.

    • 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