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 = ""
    + ""
    + ""
    + "";

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