Form UI

1. identifier
1. attributes
2. creation
3. allowuserinput
2. string
1. attributes
2. creation
3. settext
4. settitle
5. setstyle
3. stringbutton
4. stringhyperlink
5. br
6. nbsp
7. image
1. attributes
2. creation
3. setimage
4. settitle
5. setlayout
8. Imagebuttton
9. Imagehyperlink
10. Editfield
1. attributes
2. creation
3. settext
4. settitle
5. setmax
6. constraints
11. Choicegroup
1. attributes
2. creation
3. choice
4. settitle
5. delete
6. clear
7. select
12. Multichoicegroup
13. Popupchoicegroup
14. Gauge
1. attributes
2. creation
3. settitle
4. setmax
5. setvalue
15. Interactivegauge
1. attributes
2. creation
3. settitle
4. setmax
5. setvalue
16. Data
1. attributes
2. creation

Form type UI is much like the content inside the

tags in HTML. It is an auto-formatted simple user interface with a small set of widgets. It also has functionality for capturing user-input. The UI items that can be used within form UIs are:

• String (static or interactive)
• Stringbutton
• Stringhyperlink
• Image (static or interactive)
• Imagebutton
• Imagehyperlink
• Editfield
• Choicegroup
• Multichoicegroup
• Popupchoicegroup
• Gauge
• Interactivegauge
• Data

The implementation of the Form UI is very close to the MIDP LCD UI specification. It is very easy and straightforward to create content using Form UI for a content creator who is familiar with the MIDP UI specification.

identifier

In this UI type the UI items are referenced using two parameters: ui and id. The ui parameter can be left unspecified when the referred UI item is in the same UI with the caller. In addition to the UI Items The UI itself can be referred with its id.

Alternatively its possible to refer to ui items using item parameter as follows:

item="ui:id"

attributes

Param	Type	Meaning
width	int	Width of the visible UI.
height	Int	Height of the visible UI.

creation

Forms are created using template tag with type="form" parameter and value. Title parameter describes the current caption text for the UI. The uigroup parameter is there for multi-UI content. In the multi-UI environment one UI would be still visible for the user but multiple UIs (templates) could be still downloaded to the client and the change between the UIs would not require transaction with the server or recreation of the UIs each time they are displayed.

Param	Type	Default	Meaning
id	string	none	Form Id
title	string	none	Form title text
uigroup	string	none	ui group Id
active	boolean	true	true = UI is displayed, false = UI is just stored in ui group.

Example(s)

<template id="name" type="form" title="form test">
   <string text="hello world!" />
</template>

allowuserinput

Enables or disables the user input. This may become handy in certain situations where the application wants to prevent the user from making any changes to the UI before the UI has completed some task.

The task could be for instance sending a message to the server and waiting for reply. In that case the application can disable the user input before sending the message and when the reply arrives or in case of http error the user input can be enabled again.

Parameters

Param	Type	Default	Meaning
ui	string	current	UI Id. If not specified the message is sent to this UI.
value	bool	true	true=user input enabled, false=user input disabled
type	string	“all”	Optional parameter for only disabling certain kinds of user input. Possible values are: “menu”=disables/enables menu. “items”=disables/enables interaction with UI items. “all”=disables/enables all input and resets individual input flags (default)

Example(s)

<allowuserinput value="false" />

string

String item adds a text field to the form UI. The text field consists of two parts, title and text. These two parts are concatenated and displayed as one text string without delimiter. The benefit of this is though that the title and text parts of the text field can be later changed separately without recreating the whole text string again or having two different text fields in one line. In addition the title and text can be referred separately from the script.

attributes

Param	Type	Meaning
id	string	Id of the string
title	string	Title of the text field
text	string	text part

creation

Param	Type	Default	Meaning
id	string	current	Item id
title	string	none	String title
text	string	none	the text
face	string	“system”	Face of the used font:“system”, “monospace” or “proportional”
size	string	“medium”	Size of the used font:“small”, “medium” or “large”
bold	bool	false	Set to true for bold text
italic	bool	false	Set to true for italic text
underlined	bool	false	Set to true for underlined text

Example(s)

<string id="string1" text="hello world!" />

settext

Changes the text part of a string item.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
text	string	none	The text

Example(s)

<settext id="str1" text="hello again" />

<settext>
   <parms>
      <id>str1</id>
      <text>can be used like this too</text>
   </parms>
</settext>

settitle

Changes the title part of a string item.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	String title

Example(s)

<settitle title="this is string title" />
<settitle>
   <parms><title>this is string title</title></parms>
</settitle>

setstyle

Changes the style of a string item.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
face	string	“system”	Face of the used font:“system”, “monospace” or “proportional”
size	string	“medium”	Size of the used font:“small”, “medium” or “large”
bold	bool	false	Set to true for bold text
italic	bool	false	Set to true for italic text
underlined	bool	false	Set to true for underlined text

Example(s)

<setstyle id="str1" bold="true" />

stringbutton

Same as regular string but with different look.

stringhyperlink

Same as regular string but with different look.

br

This is a tag that adds a new line char to the UI layout. It does not have id, so it can not be referenced later on. It can be used to set the string layout of the UI without breaking the layout when the string items are chanced via settext method (the newline chars are not included in the strings).

Example(s)

<template type="form" id="brtest">
  <string id="str1" text="first line" />
  <br />
  <string id="str2" text="second line" />
</template>

nbsp

This is a tag that adds non-breaking space char to the UI layout. It does not have id, so it can not be referenced later on. It can be used to set the string layout of the UI without breaking the layout when the string items are chanced via settext method.

Example(s)

<template type="form" id="brtest">
   <string id="str1" text="Beginning and" />
   <nbsp />
   <string id="str2" text="the end." />
</template>

image

Image message describes a picture for the content. The picture is either downloaded within web URL and when the data is ready the decoded image placed into content OR the data can be already loaded as an image resource. The format of the image may depend on the MIDP implementation, but at least support for PNG (Portable Network Graphics) format is required. The Image can also have a title string, which is placed just before the image in the content and alternative text string, which describes the image if the data could not be downloaded for some reason.

There are also a few flags to specify the placement in the image in the content. Such as layout_center, layout_left and layout_right, which are used for aligning the image to center, left or right side of the screen. In Addition there is newline_before and newline_after for inserting new line character before or after the image.

attributes

Param	Type	Meaning
text	string	Alternative text of the image
title	string	Title text of the image

creation

Param	Type	Default	Meaning
id	string	none	Item id
title	string	none	Image title
text	string	none	Alternative text
url	string	none	Image http URL
resource	string	none	Resource ID, alternate to URL.
layout_center	bool	false	Flag for centering the image horizontally
layout_left	bool	false	Flag for aligning the image to left
layout_right	bool	false	Flag for aligning the image to right
newline_after	bool	false	Flag for inserting new line char before image
newline_before	bool	false	Flag for adding new line char after the image
cache	string	"true"	Set to "false" if the image should not be cached but loaded each time. Set to "update" if the image data in cache needs to be updated.

Example(s)

<image id="image1" url="http://www.images.com/test.png" />
<image id="image2" resource="pic1"/>

setimage

Changes the content of an image item. Downloads a new image data, decodes it and gives it to the image item. The item is not reinserted to the content but only the data is changed. If the image downloading fails the alternative text or a default error image is displayed to replace the image.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
url	string	none	Http URL to an image data
resource	string	none	Resource ID, alternate to URL.
cache	string	"true"	Set to "false" if the image should not be cached but loaded each time. Set to "update" if the image data in cache needs to be updated.

Example(s)

<setimage id="image1" url="http://images.com/newimage.png" />

settitle

Sets the title text of an image item.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	Title text of the image

Example(s)

<settitle id="image1" title="this is an image" />

setlayout

Changes the layout and spacing of the image image item. See image item description for more detailed descriptions of the parameters.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
layout_center	bool	false	Flag for centering the image horizontally
layout_left	bool	false	Flag for aligning the image to left
layout_right	bool	false	Flag for aligning the image to right
newline_after	bool	false	Flag for inserting new line char before image
newline_before	bool	false	Flag for adding new line char after the image

Example(s)

<setlayout id="image1" newline_after="true" />

Imagebuttton

Same as regular image but with different look.

Imagehyperlink

Same as regular image but with different look.

Editfield

Editfield is an editable text field. User can write text into it and change the text using the default text editing capabilities of the mobile phone. The behaviour of the edit field depends greatly on the MIDP implementation of the mobile phone.

Usually user activates the edit field with pressing a select key in the mobile device. After that the user can change the text using means implemented in the mobile phone and accept the changed. What is common to the MIDP implementations of the edit field is that the editfield can filter out different character sets or require a certain kind of input from user. These are called input constraints. The available input constraints are:

• input_any
• input_numeric
• input_url
• intput_password
• input_phonenumber

The changes cannot be saved after editing the text until the edit field contains a string that fullfils the contraints. The default input constraint is input_any, which lets user input to be anything.

Some of the constraints can be combined. For instance, if the content asks the user to enter his/her PIN number, it could be best to use both input_password (replaces the visible characters with “*” marks) and input_numeric. In addition if the user must enter an IP number instead of network address, input_url and input_numeric could be combined.

attributes

Param	Type	Meaning
title	string	Edit field title
text	string	Current content of the edit field

creation

Param	Type	Default	Meaning
id	string	current	Item id
title	string	none	Edit field title
text	string	none	Default text of edit field
max	int	32	Max characters allowed to be entered in the field
input_any	bool	true	All kinds of input is allowed
input_numeric	bool	false	Input contains of numeric characters
input_url	bool	false	Input is an URL
input_password	bool	false	Input is a password
input_phonenumber	bool	false	Input is a phone number

Example(s)

<editfield id="name" title="user name" text="anonymous" />

settext

Sets the current text of the edit field if user is not editing it at the moment.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
text	string	none	Edit field content

Example(s)

<settext id="name" text="unknown" />

settitle

Sets the title text of the edit field.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	Edit field title

Example(s)

<settitle id="name" title="illegal name" />

setmax

Sets the max amount characters allowed to be entered into the edit field text. User cannot enter more characters than the amount given here. If the current text string is longer than the max, the text is cut to be size of max.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
max	int	32	Max characters allowed to enter in the edit field

Example(s)

<setmax id="password" max="8" />

constraints

Changes the input constraint flags of an edit field.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
input_any	bool	true	All kinds of input is allowed
input_numeric	bool	false	Input contains of numeric characters
input_url	bool	false	Input is an URL
input_password	bool	false	Input is a password
input_phonenumber	bool	false	Input is a phone number

Example(s)

<constraints id="edit1" input_numeric="true" />

Choicegroup

Choice group is a UI item that gives the user a set of choices of which the user can select one. The choices are radio buttons and only one can be active at a time. By default the first item in the list is selected.

The functionality of the choice group depends much on the implementation of the MIDP. in general the user can change the active choice by browsing the selections by pressing up and down buttons on the phone and then activating the selection with the default select key. Each choice has its own ID, which does not have to be unique in the name space of the UI items but in the choice group the choice is part of. The choices have text and image parts, which are both visible to the user if defined. In case of using images the behaviour is the same as with in case of image items; the image is downloaded using the url parameter and displayed to the user when the data is ready and successfully decoded.

The content can access the choice group using references to the read-only attributes of the item (see Using references section for more details). In addition to the predefined selected attribute each choice ID is also seen as boolean attribute from the global context that gives the true or false condition of each choice if its selected by user or not. This functionality is not very important for choicegroup"s case but its there for multichoicegroup.

attributes

Param	Type	Meaning
id	string	UI item id
title	string	Choice group title
selected	string	Current/least selected item of the choice group
values	string	Returns a list of Boolean values separated with space character. Boolean values represents the truth values of each choice element.
	bool	true if there is a choice with Id choiceId and it is selected, otherwise false

creation

Param	Type	Default	Meaning
id	string	current	Item id
title	string	None	Item title

Example(s)

<choicegroup id="cg1" title="choose an avatar">
   <choice name="ava1"  text="Aragorn" />
   <choice name="ava2"  text="Gandalf" />
   <choice name="ava3"  text="Sauron" />
   <choice name="ava4"  text="Bilbo" />
   <choice name="ava5"  text="Legolas" />
</choicegroup>

choice

Appends a choice in a choice group. The choice can have separate text and image parts, which are both displayed for the user if specified. User can leave one of them unspecified. If both text and url are left unspecified, the used MIDP implementation defines how the situation is handled (some MIDP implementations can set some default text for the choice item).

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
name	string	none	Choice Id
text	string	none	Displayed text for the choice
url	string	none	Image url for the choice
cached	bool	true	Set to false if the image should not be cached but downloaded each time.

Example(s)

<choice id="cg1" name="choice1"  text="this is the 1st choice" />

settitle

Sets the title of the choice group.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	Choice group title

Example(s)

<settitle id="cg1" title="Choose your avatar" />

delete

Deletes a choice in the choice group. If there is no such choice found with the given name parameter the message does nothing.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
name	string	none	Choice Id

Example(s)

<delete id="cg1" name="choice1" />

clear

Removes all choices from a choice group and leaves the choice group empty.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.

Example(s)

<clear id="cg1" />

select

Selects of deselects a choice in choice group.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
name	string	none	Name of the choice
state	bool	true	true = choice is selected, false = choice is deselected

Example(s)

<select id="cg1" name="ava1" state="true" />

Multichoicegroup

Multichoicegroup is a special case of choice group. The difference between the multichoicegroup and choicegroup is that with a choicegroup user can only select one of the choices, but with a multichoicegroup the user can select multiple choices. Instead of displaying a set of radio buttons for the user the multichoice group uses a set of on/off buttons each of which can be activated or disabled.

The functionality of the multichoicegroup depends much on the implementation of the MIDP. in general the user can change the states of active choices by browsing the selections by pressing up and down buttons on the phone and then activating the selection with the default select key.

Each choice has its own ID, which does not have to be unique in the name space of the UI items but in the choice group the choice is part of. The choices have text and image parts, which are both visible to the user if defined. In case of using images the behaviour is the same as with in case of image items; the image is downloaded using the url parameter and displayed to the user when the data is ready and successfully decoded. The content can access the choice group using references to the read-only attributes of the item (see Using references section for more details). In multichoicegroup"s case the selected attribute is the last enabled choice, which is not very informative as it was with choicegroup"s case. One should use the attributes instead since they are seen as boolean attribute from the global context that gives the true or false condition of each choice if its selected by user or not. In addition its possible to access the whole value set using the values attribute.

Refer to documentation of choicegroup for the item specific API and attributes.

Popupchoicegroup

Popupchoicegroup is a special case of choice group. The difference between the popupchoicegroup and choicegroup is its visual representation. The functionality of the popupchoicegroup depends much on the implementation of the MIDP. in general the user can change the states of active choices by browsing the selections by pressing up and down buttons on the phone and then activating the selection with the default select key.

Each choice has its own ID, which does not have to be unique in the name space of the UI items but in the choice group the choice is part of. The choices have text and image parts, which are both visible to the user if defined. In case of using images the behaviour is the same as with in case of image items; the image is downloaded using the url parameter and displayed to the user when the data is ready and successfully decoded. Refer to documentation of choicegroup for the item specific API and attributes.

Gauge

Gauge is a UI item that illustrates a numeric value inside a value range. Usually its done with a slider widget where the minimum and maximum value are in the ends of the slider and the current value is marked somehow on the slider. The visual looks are dependant on the MIDP implementation.

The range is zero based and the max value is given 0…max. The current value is always inside that range. Gauge is not interactive, but for displaying data only. There is an interactivegauge item for getting input from user.

attributes

Param	Type	Meaning
title	string	Gauge title
max	int	Value range 0..max
value	int	Current value of the gauge

creation

Param	Type	Default	Meaning
id	string	current	Item id
title	string	None	Gauge title
max	int	10	Value range 0...max
value	int	0	Initial value of the gauge

Example(s)

<gauge id="gauge1" title="Current speed" max="200" value="150" />

settitle

Sets the title text of gauge.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	New title text for gauge

Example(s)

<settitle id="gauge1" title="Rounds per minute" />

setmax

Set the maximum value of the gauge. If the current value is larger than the maximum, the value is capped with the new maximum value.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
max	int	10	New maximum value for gauge

Example(s)

<setmax id="gauge1" max="6500" />

setvalue

Sets current value of the gauge. The value is capped with the valid value range 0..max.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
value	int	0	New value for gauge

Example(s)

<setvalue id="gauge1" value="5700" />

Interactivegauge

Interactivegauge is a UI item that illustrates a numeric value inside a value range. The difference from regular gauge item is that the current value of interactivegauge can be changed by the user.

The range is zero based and the max value is given 0…max. The current value is always inside that range. User can change the value by selecting the interactive gauge item and moving the slider with left and right keys. The functionality might differ between MIDP implementations.

attributes

Param	Type	Meaning
identifiers	params	Item reference.
title	string	Gauge title
max	int	Value range 0..max
value	int	Current value of the gauge

creation

Param	Type	Default	Meaning
id	string	current	Item id
title	string	none	Gauge title
max	int	10	Value range 0...max
value	int	0	Initial value of the gauge

Example(s)

<gauge id="gauge1" title="Current speed" max="200" value="150" />

settitle

Sets the title text of gauge.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
title	string	none	New title text for gauge

Example(s)

<settitle id="gauge1" title="Rounds per minute" />

setmax

Set the maximum value of the gauge. If the current value is larger than the maximum, the value is capped with the new maximum value.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
max	int	10	New maximum value for gauge

Example(s)

<setmax id="gauge1" max="6500" />

setvalue

Sets current value of the gauge. The value is capped with the valid value range 0..max.

Parameters

Param	Type	Default	Meaning
identifiers	params	current item	Item reference.
value	int	0	New value for gauge

Example(s)

<setvalue id="gauge1" value="5700" />

Data

Data is an dummy item for storing scripts and attributes. It works similar to UI items, but it does not have a visual representation. Sometimes its handy to store all the scripts and attributes in one place and for instance inherit the scripts to UI items.

attributes

Param	Type	Meaning
id	string	Item Id

creation

Param	Type	Default	Meaning
id	string	current	Item id