Controls: LIST - Simple List

What you will learn in this chapter
LIST control
Attributes, Size and Scrolling, Background, Child controls of LIST
Reference Tutorials: How to create a Simple list, Navigation from LIST control
Other lists: Section List, Searchable list
Reference: Actions, Data Sourcing, appearance

LIST control

List is a widely used UI element. It allows you to display a collection of items in a list. For example, displaying emails, contact list use LIST control to display data.

You can create a simple list by using LIST control. It is a group control which has one or more child controls.

In XMADL, LIST control is defined as follows

<!-- Parent Control-->
<control type="LIST"...............>
    <!-- Child Controls-->
    <control .........../>
    <control .........../>
    <control .........../>
    <control .........../>

Fig below shows list on Android and on iOS

../_images/local-list_small.png ../_images/iOS_local_list_childcontrol.png


Attribute Value Mandatory
type LIST Yes
x   Yes
y   Yes
width   Yes
height   Yes
appearance_name   Yes
data_type JSONARRAY, CURSOR default is CURSOR
on_empty_show comma separated name(s) of the control that should become visible when the data set is empty. If and when the data set is available these controls will be hidden. No
local_data_source sql query No
remote_data_source url No


If the data_type is CURSOR, then local_data_source must be defined. Learn more about Data Sourcing

Size and Scrolling

The size of the list is determined by the attributes width and height. height attribute determines the maximum height of LIST on the device screen. When the height of all list items combined together exceeds the height of the LIST control, scroll bar appears automatically.


Make sure that on a screen containing List, the attribute “scroll” of <screen> element should equal NONE. By default it is scroll=”NONE”, so you need not specify the attribute scroll in screen element.


Background of a LIST can be set by the attribute appearance_name. To set LIST with transparent background, make sure the appearance has alpha=”0”. To set a different background, make sure that the appearance has background_color and alpha greater than 0. You can set other properties such as border, radius also. Learn more about appearance

Child controls of LIST

A list is essentially used to display information. The controls supported as child controls of a LIST control are:

The appearance of child controls is based on the appearance_name attribute of that control.

Example - This list displays shopping list. On tap of a list item, you go to the screen which displays details about that item.

<control name="shoppinglist" type="LIST" x="0" y="0" width="100"
        height="100" appearance_name="black"
    local_data_source="select list_item_id as _id, item, category from myshopping_list order by category">
                <action event_list="TAP" action_name="NEXT_SCREEN" target="listdetails"
                                input_parameter_list="item, category" />

        <!-- Child controls of list -->
        <control type="TEXT" x="3" y="2" width="27" height="7"
                appearance_name="black" data_type="VARCHAR" field_name="item" />
        <control type="TEXT" x="35" y="2" width="50" height="7"
                appearance_name="black" data_type="VARCHAR" field_name="category" />
        <control type="IMAGE" x="85" y="1" width="15" height="7"
                appearance_name="black" default_value="IMAGE:arrow.png" />

LIST control can also be used to take user input. To capture the value of a list item, custom code needs to be written. Learn more about how to integrate Business Logic

Controls that can be used for taking user inputs in a list are -