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();
}

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    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
    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 Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    Modifier and Type
    Method
    Description
    protected Object
    clone()
     
    boolean
    equals(Object obj)
    Indicates whether some other object is "equal to" this one.
    final Class
    getClass()
    Returns the runtime class of an object.
    int
    hashCode()
    Returns a hash code value for the object.
    final void
    notify()
    Wakes up a single thread that is waiting on this object's monitor.
    final void
    notifyAll()
    Wakes up all threads that are waiting on this object's monitor.
    String
    toString()
    Returns a string representation of the object.
    final void
    wait()
    Causes current thread to wait until another thread invokes the method or the method for this object.
    final void
    wait(long timeout)
    Causes current thread to wait until either another thread invokes the method or the method for this object, or a specified amount of time has elapsed.
    final void
    wait(long timeout, int nanos)
    Causes current thread to wait until another thread invokes the method or the method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.

  • 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