Common Script Language

  1. UI templates
  2. UI Groups
  3. UI items
  4. Inheritance
  5. Calling UI item methods
    1. Calling methods of an item in another UI
    2. Definition of identifiers
  6. Attributes and references
    1. Read-only attributes
    2. System and service attributes
    3. User-defined attributes
    4. Referencing UI item attributes
    5. Referencing attributes between UIs
    6. Dynamic references and attributes
    7. Arithmetic statements as parameters
  7. Event hooks
    1. Custom event hooks
  8. Common script language methods
    1. defaults
    2. serviceinfo
    3. resource
      1. creation
    4. Bitmap fonts
    5. Image subresource
    6. beginload
    7. endload
    8. executescript
    9. template
    10. command
    11. creation
    12. submenu
    13. creation
    14. quit
    15. setactive
    16. changeservice
    17. removecommand
    18. setreference or ref
    19. foreach
    20. debug
    21. showdebug
    22. reporterrors
    23. alert
    24. send
    25. delete
    26. starttimer
    27. pausetimer
    28. stoptimer
    29. input
    30. in
    31. sendsms
    32. hook
    33. event
    34. loop
    35. attribute
    36. inc
    37. dec
    38. multiply
    39. divide
    40. modulo
    41. absolute
    42. substring
    43. stringlength
    44. stringtoken
    45. findtoken
    46. settoken
    47. removetoken
    48. numberoftokens
    49. equal
    50. notequal
    51. less
    52. greater
    53. switch
    54. inrange
    55. startvibra
    56. stopvibra
    57. flashlights
    58. playsound
    59. pausesound
    60. stopsound
    61. recordaudio
    62. getsnapshot
    63. playvideo
    64. pausevideo
    65. stopvideo
    66. callplatform
  9. Client-side plugin API
    1. load
    2. unload
    3. call

Common Script Language defines a set of methods and conventions available for all UI type, i.e. in canvas and form UI styles. They define a basic functionality of MUPE UI independent of the UI style used. Some of the common script language methods also works without UI.

UI templates

UI template is the basic element of MUPE script language. All the functionality happens through UI templates. Currently the client supports two kinds of UI templates, Canvas and Form. They can be created with "template" method.

The UI templates are dynamic since the content can be changed on-the-fly without recreating the whole screen each time. These changes can be done by the server or by the content itself (triggered by user interaction or various events). The content consists of UI items that be replaced by other UI items. In addition the UI items have attributes and functions that can be used to manipulate the attributes. All the UI manipulation is done via methods that are UI dependent. Each UI type defines a set of methods (method API).

The benefit of this is that the UIs don"t have to be recreated each time when interacting with the server (unlike when using basic HTML). This makes it possible to transfer less data between the client and the server. In addition it is possible to manipulate individual UI items at the same time for instance when user is writing to an edit field, without losing the partly written text in the edit field.


UI Groups


One can download multiple UIs in the client by using UI groups. The idea is that the client can hold one UI group at a time. If the UI group changes or the UI group is not specified in the downloaded UI template the current UI and UI group is discarded and replaced by new UI or group of UIs.

Like the UI items the UI group has an ID that is given with group parameter in the template method. The UIs in UI group don"t have to be the same type but one can mix different types of UIs there as well. The communication between the UIs is also possible and using the messaging they can also share data. For instance, there can be a Canvas UI that defined the actual application and then a Form UI to configure the application. Another example would be to use the Canvas UI as the content viewer and then Form UI to interact with the server.

When downloading UIs in the UI group there is another parameter, called active, that is used for notifying the client, which UI in the group is the current active (read: visible) UI. This is done by setting the active flag to true for one UI and false for the rest.

As a summary, the UI template can contain one UI template or a collection of templates inside a UI group. The possibilities are seen in figure 1.

Figure 1. The possibilities of creating a UI.


UI items


Each UI template contains a set of UI items. The set of UI items can be and in most cases is different for each UI type; Form type UI has a different set of UI items than Canvas type UI. The UI items can be created in a UI template by writing an XML section that describes the UI item. Each UI item has id parameter that is given as parameter in the XML section. The id parameter can be used to refer to the UI item later on. If additional information is needed to make an UI item unique, that can be implemented by the UI. For instance canvas UI needs group parameter in addition to id parameter to make a UI item unique in the name space.

In addition to manipulating UI items with methods from server or by user interaction, there can be also method sequences triggered by so called events. For instance when user is writing to an edit field that creates an on_change event for the edit field item. The script language can “hook” these items and trigger a sequence of UI methods when the event takes place. The events, which can be triggered for each UI item are defined by the UI type.


Inheritance

One can also reduce the size of XML script by using inherits="itemid" parameters within the UI item creation. The inheritance is only allowed inside an item group. Inheritance also reduces the memory requirements of the content, since the script is shared between UI items instead of copying it for each UI item. The inheritance only shares the event hooks. Anything outside the event hooks is considered as item specific extended properties. The inheritance is not restricted to using same UI item types but it also works between different UI item types.

In the example below, we have two image items image1 and image2. The "image1" implements the base class for the other image (image2) to inherit. Image1 does not have to be visible UI item. It only implements the script. When image2 is created it inherits the on_create event hook from image1, but not the extended_attibute attribute. After creation of image2 the on_create event is triggered and it also downloads the "image1.png" data as the content.


Example(s)

<image id='image1' visible='false'>
   <attribute name='extended_attribute' value='not_shared' />

   <hook name='on_create'>
      <setimage url='http://www.images.com/image1.png' />
      <attribute name='foo' value='bar' />
   </hook>
</image>

<image id='image2' visible='true' x='50' y='60' inherits='image1' />


Calling UI item methods

The server sends information to a single UI item in the same way as new items are created. The object is referred to with its group and id parameters and in case such object already exists, its content is changed.

In Form UI the UI items are referenced with id parameter. Canvas UI has different referencing method, since the UI items are in item groups (analogy: window). In Canvas UI the referencing is done via id and group parameters.

However, in both cases one does not have to specify id and group parameters for each method. This is because the script language is running in an item context and the method is pointed to the same UI item, such as when an event has been triggered for a UI item. In such cases if the id and group parameters are not specified it can be assumed that the information can be extracted from the UI item context.

IMPORTANT: The content developer must understand that each tag is in fact a UI medhod and it needs a target UI item information to know to which UI item is meant to be handling the method. In the following (Canvas UI) example there is several different ways of referencing items. There is two event hooks implemented for image1 and it is assumed that there is also another image image2 inside same item group with image1 and also another item group other_group that includes image image3.


There are four hide methods in the on_select event hook that behaves differently because of the UI item context (which is image1).

  • The 1st one hides the image1 itself since the id and group information is left unspecified.
  • The 2nd one hides image2 UI item in the same item group, since the group parameter is left unspecified.
  • The 3rd one hides image3 from another item group called other_group.
  • The 4th one hides the item group other_group


Note: If item group is referenced outside it"s context (from other UI items) the group and id are both set as the item group"s ID.


Example(s)

<image id="image1">
   <hook name="on_select">

       <hide />
       <hide id="image2" />
       <hide id="image3" group="other_group" />
       <hide id="other_group" group="other_group" />
   </hook>    
</image>


Calling methods of an item in another UI

When using UI groups, a UI can call a method in another UI using "ui" parameter. The "ui" parameter is the ID of the UI that was given in the template method at creation. This is a way of sharing data between UIs. The method call can contain several parameters, which are not constant values but references to (see next chapter for details) to different attributes of the source UI, which are then evaluated to constant values before calling another UI. The destination UI can then take the parameter and store/use the value for its own purposes.


Example(s)

<settext ui="form1" id="string1" text="$(canvas1.group1.text1)" />

<settext target='form1:string1' text="$(canvas1.group1.text1)" />


Definition of identifiers


Almost all methods take item identifiers as parameters. As mentioned before, depending on the script context, some of the parameters can be left unspecified. In addition to that the item identifier can vary depending on the used UI type. For instance in Canvas type UI the items belong to item groups which adds one parameter (group) into the method calls. The following table shows how identifiers is defined in each available UI type.


Identifier UI types Refers to
ui All User-interface Id.
id All Item Id.
group Canvas Item group
item All Alternative way of referring to ui items with syntax: ui:group/id


Attributes and references

Each UI item can hold information, so called attributes. This information can be extracted from the UI items and for instance sent to server. There are two kinds attributes; read-only attributed and user-defined attributes. The difference between these two is that read-only attributes cannot be directly changed, but they change according to UI item initialization and when interacting with the UI item. Unlike the read-only attributes the user-defined attributes are not directly used by UI items, but they exist only to store information. The user-defined attributes can only be used by the XML script.


Read-only attributes

Each UI item has a set of read-only attributes. Again what attributes is defined for each UI item is defined by the UI type. The only common read-only attribute that is defined for every UI item is id. The values of read-only attributes cannot be directly set using "attribute" method in Canvas UI, but they can be changed indirectly with the UI specific API. As an example in Canvas UI each item has x and y attributes that determines the placement of the UI item. One cannot move an UI item by changing the x attribute with "attribute" method, but the moving is done via "move" method that changes the x and y attributes according to the parameters and along with many other required procedures when the UI item is moved on screen.


System and service attributes

There are a set of static attributes stores in the MIDP system. They can either be set compile time using JAD extensions or defined by the platform itself. The developer can access this information by using client keyword as the attribute container. In addition the there are a few special attributes:

Attribute Meaning
cachetotal Maximum cache size.
cacheused Used cache size.
cachefree Available cache space.
cachefiles Number of files cached.
memorytotal Total memory.
memoryfree Available memory. (Java can allocate more memory if needed, so this usually does not tell how much memory is really available, but how much is free from the current allocated chunk of memory.)


The client can also store service specific information using serviceinfo method. This type of information can be accessed by using service keyword as the container. See serviceinfo section for more details.


User-defined attributes

User-defined attributes are used for storing information in the UI items. Currently only Canvas UI supports this feature with its more advanced script language support. The user-defined attributes are created for an UI item using "attribute" method, with given initial value. When an attribute value is changed the change can be done with the same method using different value parameter.

The benefit of user defined attributes is to create more logic in the client-side by making it possible to do simple calculations with the attributes and also sharing common data between the UI items, without asking the remote server to do these things. This makes the client content less dependent on the server and more effective as user-interface.


Referencing UI item attributes

To use the UI item attributes one must refer to them using a certain notation. Both read-only and user-defined attributes can be referred with same kind of notation. The syntax for the notation is as follows:

$(ui_item_identifier.ui_item_attibute)


where the ui_item_identifier tells the client which UI item has the attribute and ui_item_attibute is the attribute identifier. For instance, when referring to a x coordinate of an image item image1 in Canvas UI the reference would look like this:

$(image1.x)


The previous example assumes that the method is called from the same item group with the image1 item. In Canvas UI the ui_item_identifier can consist of two parts, item group and item id. The item group can be left unspecified if the method was called from same item group. The general notation for UI items in Canvas type UI would look like this:

$(ui_item_group.ui_item_identifier.item_attribute)


And the previous example in general format:

$(itemgroup1.image1.x)


Referencing item group itself in Canvas UI:

$(itemgroup1.itemgroup1.x)


Referencing attribute of Canvas UI itself.

$(canvasid. canvasid.width)


Referencing attribute of Form UI. Form UI only has one level notation.

$(formid.width)


Referencing attributes between UIs

It is possible to reference attributes between two different UIs. One can access the attributes in just by including the UI ID in the attribute reference in following way:

$(ui_id:<item_id>)

The ui_id is the identifier of the UI where the attribute is defined, and the item_id is an attribute reference as defined in chapter Referencing UI item attributes. The ui_id and item_id are separated with a colon. As an example, lets say we have two Uis in a UI group: ui1 and ui2. The ui1 has editfield item edit1 and the ui2 has string item str1. Its now possible to write following hook in ui2 for displaying the contents of the edit1 in ui2.

<hook name="on_activation">
   <settext id="str1" text="$(ui1:edit1.text)" />
</hook>


Dynamic references and attributes

In addition to referering the UI items with static references there is also a set of reserved words that can be used for referring attributes dynamically. These reserved words can be used to replace the item indentifier in the attribute reference. One cannot create UI Items using these as the item id. Here is a list of the reserved keywords:


Keyword UI types Refers to
this All Current UI item context in script.
service All Information stored with service info.
resources All Use resource id as the attribute name. Returns base64 encoded data of a snaphot taken by camera or recorded audio clip. Returns empty string for downloaded content.
reference# All UI item set by setreference method. # can be 0..7 or left unspecified for index 0.
ref# All Alias for "reference#" defined above.
global All Referring to attributes of the UI the item belongs to.
client All Referring to MIDP property values.
random All Accesses random number generator. For instance $(random.integer) returns 32bit random integer.
group Canvas item group of an UI item.
selected Canvas Referencing to currently selected item in Canvas UI.
anchor Canvas Tells the id of the UI item the current item is anchored to.

Example(s)

$(this.id)
$(selected.text)


Arithmetic statements as parameters

Using arithmetic statements makes it considerably easier to make calculations in the script language. The usage of arithmetic statements is pretty straightforward with only one exception: when using arithmetic statement as value parameter of attribute method, one must remember to specify the type="int" parameter. Otherwise the parameter will be evaluates as a string. With method calls that assume the parameter as integer value (parameter types are told in the method definitions) will evaluate the value automatically.

Also, when using parentheses within the arithmetic statements one must use [ ] characters instead of normal ( ). The parentheses can be nested.

Here is a couple of examples of using arithmetic statements:

<i_attribute name='four' value='2+2' type='int' />

<move id="img" deltax="$(global.movestep)+ 4" />
<move id="img2" deltay="[$(global.movestep) - 3] * 4" />
<move id="img3" x="[[$(a.b) – $(c.d)] - 2 ] / 3" />
<move id="img3" deltax="$(a.b) % 10" />


Event hooks


Event hooks allow the client device to respond to user input, timers and client created events. These features allow great flexibility and customizability for the client. The system contains a number of predefined hooks and the programmer can also define new hooks.

Event hooks are like subroutines that can be called anytime by the content or by the system. The predefined event hooks define a set of basic events that can happen for each UI item, such as adding more functionality when a UI item is shown, hidden or created.

Common Script Language defines a large set of event hooks available for all UI types and the different UI types can extend the set of events with their own events. In addition there can be also custom event hooks that are not called by the system but by the script itself (via event method).

Note: It is also possible to define an event hook by starting the tag with "on_".

For example:

<on_create>
   ... your script here...
</on_create>


The Following list of events are available for all UI types.


on_create


This event takes place when a UI item is initialized and added to the UI but not yet shown. It only happens once for an UI item. It can be used to initializing UI item attributes or configuring the UI for the item.

Example(s)

<hook name="on_create">
   <debug text="UI item $(this.id) was just created." />
</hook>
<on_create>
   <debug text="UI item $(this.id) was just created." />
</on_create>


on_delete

This event takes place when a UI item is destroyed with delete method, just before the item attributes and event hooks are removed from the system. If the UI item is not explicitly removed with delete method but the UI template is changed, the UI item does not receive this event.


Example(s)

<hook name="on_delete">
   <debug text="UI item $(this.id) was just deleted." />
</hook>
<on_delete>
   <debug text="UI item $(this.id) was just deleted." />
</on_delete>


on_change

This event takes place when the UI item is changed. It"s a way of notifying that the UI item has been changed somehow and other UI items related to the item needs to be updated as well.

Note: This event might become obsolete at later time. It can be replaced with a set of events that describes different ways of manipulating the UI items better.


Example(s)

<hook name="on_change">
   <debug text="UI item $(this.id) was changed." />
</hook>


on_resource_loaded

This event takes place when a resource data has been successfully loaded. Only the UI template can hook this event. In addition to the event there is an attribute named resource_id that is dedicated to tell the ID of the resource that was just loaded. The attribute ‘is set as the property of the default group.


Example(s)

<hook name="on_resource_loaded">
   <debug text="Resource $(this.resource_id) was just loaded." />
</hook>


on_resource_loading

These events are created for the UI during resource loading. There is an attribute named resource_id that is dedicated to tell the ID of the resource that was just loaded. The attribute ‘is set as the property of the UI template. In addition to the id there is also another parameter called resource_status which tells how many percent the resource has been downloaded so far.


Example(s)

<hook name="on_resource_loaded">
   <debug text="Downloading $(this.resource_id), $(this.resource_status)% complete." />
</hook>


on_resource_error


This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. In addition to the event there is attribute named resource_id that is dedicated to tell the ID of the resource of which loading failed. The attribute is set as the property of the default group.


Example(s)

<hook name="on_resource_error">
   <debug text="Error loading $(this.resource_id)." />
</hook>


on_net_request


This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when the content sends a request to a server. It can be used to control the general state of the content when it is interacting with the server.


Example(s)

<hook name="on_http_request">
   <allowuserinput value="false" />
</hook>


on_net_response


This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when the client receives a message from the server. It can be used to control the general state of the content when it is interacting with the server.


Example(s)

<hook name="on_http_response">
   <allowuserinput value="true" />
</hook>


on_net_error


This event takes place when a resource data was not successfully loaded. Only the default group can hook this event. This event triggers when an HTTP request to the server has failed. It can be used to control the general state of the content when it is interacting with the server.


Example(s)

<hook name="on_http_error">
   <allowuserinput value="true" />
</hook>


on_activation


There can be several UIs in so called UI group, where one UI is visible on the screen at a time. UI receives this event when it is shown on screen with setactive method.


Example(s)

<hook name="on_activation">
   <settext id="str1" text="Hello again!" />
</hook>


on_deactivation


There can be several UIs in so called UI group, where one UI is visible on the screen at a time. UI receives this event when it is no longer visible on screen, when setactive method has been received by another UI.

Example(s)

<hook name="on_deactivation">
   <stoptimer id="very_heavy_animation" />
</hook>


Custom event hooks


User defined hooks are like subroutines that can be called by the content using event method. They can be defined as the internal even hooks using hook method, by choosing a different name for the hook, not one of the system specific event hooks. Custom event hooks helps creating applications a great deal. Instead of copying a subroutine into several places in the UI item script one can create just one event hook and then call it from several places in the script.

Like the built-in event hooks, the custom event hooks does not have parameters. However, instead of using parameters one can use a set of attributes as parameters for the event hook. The event hook uses those attributes and so can behave differently according to the attribute values.


Example(s)

<hook name="myownevent">
   <debug text="a=$(this.a)" />
</hook>

<on_myownevent>
   <debug text="my event" />
</on_myownevent>

<hook name="on_show">
   <event hook="on_myownevent" />
</hook>

<hook name="on_hide">
   <attribute name="a" value="2" />
   <event hook="myownevent" />
</hook>


Common script language methods


Common script methods defines the basic functionality of MUPE script language.


defaults

Defaults method overides default parameter values of creating items and resource. Currently this functionality does not work in Form UI. Setting default values for the creation parameters can be used for two purposes:

  • Avoiding parameter repetition in XML script, which makes the XML easier to read and faster to write.
  • Creating different UI styles for service, without changing the XML script: default colors, default placements and sizes, etc.

The default values are service specific, not ui specific. Default values do not work with method call, only for setting the default creation parameters. Also, parameters that identify an UI item (ui, group and id) cannot be set to a default value.

Default values are set using the following syntax:

<defaults>
   <resource|canvas parameter='defaultvalue' ...>
      <itemtype parameter='defaultvalue' .../>
   <resource|canvas>
</defaults>


Example(s)

<defaults>
   <-- resources are clipped to 50x50 subimages by default -->
   <resource cropwidth='50' cropheight='40' />  
   <canvas bgcolor='black'>  <!-- default screen background is black -->
      <group width='120' />  <!-- sets default group width to 100 -->
      <string fgcolor='white' /> <!-- font color is white -->
   </canvas>
<defaults>


serviceinfo

Service info method works as HTML “cookies” in MUPE script language. They are used for storing service specific information on the client device. The information is bound to service name, which is a free form text string defined by the service. In addition to the service specific information there are information tags that are used internally by the client.

Service information can be retrieved in the XML script with $(service.variable) notation, where the variable is the name of the attribute set with serviceinfo call.

Note: Service info attributes do not work as integer parameters. If you need to use service info as integer parameter in method call, you need to set an attribute to the service info value and then use that attribute.



Parameters

Param Type Default Meaning
service string none The service name
variable string none The information tags are strings that stores service specific data. The data can be accessed by the UI-script using $(service.variable) notation.


Example(s)

<serviceinfo service="myservice">
   <parms>
      <username>test1</username>
      <password>testpass</password>
   </parms>
</serviceinfo>


resource

Resources are special items that do not have visual representation on the screen but are used as data stores for UI items. The data, downloadable media, can be images, sound, and binary data. The data can be * stored locally in the client JAR * available in Web * available in Media folder of the service.

Each Media protocol type has different URL prefix which tells the client how to fetch the data. Here a table of media protocol types and URL prefixes:


Protocol URL prefix
Local content/td> "/"
Http/td> "http://"
Mupe media/td> "mupe://"


The resources downloading process creates events for the UI. The events are on_resource_loaded and on_resource_load_error:


Event Meaning
on_resource_loaded resource was successfully loaded
on_resource_load_error resource loading failed


The event hooks can be captured and the special resource_id attribute can be used to define which resource has been loaded or which has failed. This makes it possible to visualize the process of loading resources and activating things, like user input, when the downloading process has ended.


creation

Param Type Default Meaning
id string none Resource id
type string none image = Image (at least PNG |supported)
wave = Audio files compatible with the device
midi = Midi tune
video = Video files compatible with the device
tone = Ringing tone font = Bitmap font resource
url string none URL to the actual data
global bool false Set to true if the created resource is a global resource. Global resources are freed only when the service is changed of quit.
recreate bool true Set to false if the resource should not be created if such resource is already present. This can make loading reloading resources faster and also save a load of temporary memory.
cache string “true” Set to “false” if you want the resource to be downloaded each time when created. Handy for dynamic content that can change any time in the web.
Set to “update” if you want the resource object to be updated in the cache.


Example(s)

<resource id="explo1" type="wave">
   <parms>
      <url>http://audio.com/explosion.wav</url>
   </parms>

</resource>
<resource id="playerchar" type="image">
   <parms>
      <url>![hero.png][134]</url>
   </parms>
</resource>


Bitmap fonts

Bitmap fonts are a special case of an image resource. Bitmap fonts are images that contain a set of characters that various UI items can then use to overide the default set of fonts in MIDP.

The image files contain a set of characters, which can be placed side-by-side or in multiple lines. When creating a font resource the width and height values of one character is given. Ihe image tells the resource how many characters the font specified.

One does not need to specify the font from ascii code zero, but it also possible to specify the starting character code. This might come handy for instance for skipping the first 32 characters from ascii table, which are usually only white space characters. This can be done with specifying the basecode parameter, which tells the first used character code.

Bitmap fonts are always global resources.


Parameters

Param Type Default Meaning
id string none Font resource id
type string "font" Must be set to "font"
url string none URL to the bitmap font image
letterwidth int -1 Width of one character
letterheight int -1 Height of one character
basecode int 0 First used character code in the character set.


Example(s)

<resource type='font' id='font1' letterwidth='6' letterheight='10'>
    <parms>
        <url>mupe://fonts.com/mybitmapfont.png</url>
    </parms>
</resource>    
<string font='font1' text='Some text with bitmap font' />


Image subresource


You can split image resources into sub resources. After the image has been split into sub resources, you can use the sub resources with a “resource.subresource” notation. The sub resources are created at once when the image resource is created and its not possible to create more sub resources later. The original image is discarded from memory after the sub resources are create for saving up memory, thus the original image resource cannot be used as it is, only the sub resources.


Parameters

Param Type Default Meaning
name string none Sub resource id
cropx int 0 Top left x-coordinate of the sub resource inside the main image resource.
cropy int 0 Top left y-coordinate of the sub resource inside the main image resource.
cropwidth int none Width of the sub resource.
cropheight int none Height of the sub resource.
mirror bool false Set to true if the sub image should be mirrored horizontally.
rotate string “deg0” “deg0” = sub image is not rotated “deg90” = sub image is rotated 90 degrees “deg180” = sub image is rotated 180 degrees “deg270” = sub image is rotated 270 degrees


Example(s)

<resource id="playerchars" type="image">
   <parms>
      <url>![heroes.png][136]</url>
   </parms>
   <subresource name="hero1" cropx="0" cropy="0" cropwidth="64" cropheight="64" />
   <subresource name="hero2" cropx="64" cropy="0" cropwidth="64" cropheight="64" mirror="true" />
</resource>


beginload

Beginload and endload can be used to optimise resource loading when using MUPE media protocol. One can put beginload before the resource definitions and endload after. This should make resource loading much faster.


Example(s)

<beginload />


endload

Beginload and endload can be used to optimise resource loading when using MUPE media protocol. One can put beginload before the resource definitions and endload after. This should make resource loading much faster.


Example(s)

<beginload />


executescript

Executescript runs a compressed (MSP file) XML script defined in different locations. The script file can be stored: * locally in the client JAR * in Web * in Media folder of the service.

Each Media protocol type has different URL prefix which tells the client how to fetch the XML script. Here a table of media protocol types and URL prefixes:


Protocol URL prefix
Local content/td> "/"
Http/td> "http://"
Mupe media/td> "mupe://"


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
url string none URL to the XML script
cache string “true” Set to “false” if you want the resource to be downloaded each time when created. Handy for dynamic content that can change any time in the web.
Set to “update” if you want the resource object to be updated in the cache.


Example(s)

<executescript url="mupe://myscript.msp" />


template

Template method creates a new user-interface (UI) for the client. The look-and-feel and functionality of the user-interface is defined by the client implementation and the given UI type parameter. Currently MUPE client supports two different kinds of UIs: forms and canvases. The client is implemented in such way that the template method can create other kinds of Uis in the future, if so needed. The smallest common nominator between the UIs is the “form” type UI, which is a requirement for all MUPE clients.

The client also supports multiple simultaneous UIs, i.e. the client can load a set of UIs called UI group. There can only be one UI group at a time. The UI group is identified by an uigroup parameter. If either the UI group changes or a UI without UI group is created the current UI group is discarded and substitutes by the new UI. If one needs to replace only one UI in the UI group, it can be achieved by specifying the same UI group and id parameters for the template method.

Note: See more information on the UI type specific creation parameters in the chapters defining the UI types: Form UI and Canvas UI.


Parameters

Param Type Default Meaning
id string none User-interface Id.
type string none User-interface type.
uigroup string none UI group this template belongs to.
active boolean true Is user-interface set as the current visible UI.


Example(s)

<template id="canvas_ui" type="canvas">
</template>

<template id="form_ui" type="form">
</template>

<template id="test" type="my_own_ui_type">
</template>


command

Command method adds a new menu command for a UI. Menu commands are part of the UI template, but still they are independent of the UI type.

Menu commands are pretty much like timers but instead of being triggered in given time they are triggered by the user.

As UI element the menu command follows the MIDP UI API specification, with the exception of supporting “empty” menu commands that can be used for separating groups of menu commands.


creation

Param Type Default Meaning
id string none Menu command ID
type string “screen” Available menu command type: “ok”, “cancel”, “back”, “screen”, “exit”, help”, “item”, “stop” and “empty”
priority int 1 Priority of the placement of menu command. The values are positive integers, where 1 = highest priority.
text string “” Caption text for the menu command.


Example(s)

<command id="mycommand" text="toggle item1">
   <show id="item1" />
   <break />
   <hide id="item1" />
</command>


submenu


Creates a menu command with a sub menu. You can use it for creating 2-level menus. This is very recommended since the menus tend to crow very large in Mupe applications. The submenu consists of command statements, which have the same syntax as the command method. Submenus cannot contain other submenus.


creation

Param Type Default Meaning
id string none Menu command ID
type string “screen” Available menu command type: “ok”, “cancel”, “back”, “screen”, “exit”, help”, “item”, “stop” and “empty”
priority int 1 Priority of the placement of menu command. The values are positive integers, where 1 = highest priority.
text string “” Caption text for the menu command.


Example(s)

<submenu id="mysubmenu" text="submenutest">
   <command id="sub1" text="choice1">
      <debug text="choice1 chosen"/>
   <command>
   <command id="sub2" text="choice2">
      <debug text="choice2 chosen"/>
   </command>
</submenu>


quit

By default, quits from the current content and returns the client to the main menu, where the user can connect to a new MUPE server by specifying the address or choosing a service from the favorites list. If the exitmupe parameter is set to true the quit method exits mupe client.

Note: Services should use to quit from the service. I

Parameters

Param Type Default Meaning
exitmupe boolean false Set to true for quitting mupe client, not just the MUPE service.
force boolean false Set to true for exiting mupe without asking.


Example(s)

<command text="quit service">
   <quit />
</command>

<command text="quit mupe">
   <quit exitmupe="true" />
</command>

<commondialog type='quit' />


setactive


Makes this UI the current displayed UI. Activation method can be sent from the server or by another UI. Works with UI group that contains multiple Uis.


Parameters

Param Type Default Meaning
ui string current UI Id.


changeservice


Changes the currently active service. By default it shows the user a dialog, which asks if it is ok to change to the new service. If the user confirms all activities in the current service are stopped (also timers) and the service is changed, otherwise the client stays connected to the current service.

The client sends subscribe message to the newly connected service if the service has not been subscribed yet. Otherwise the client sends a activation message. if the service has already been subscribed the url parameter is not necessary. In addition, if the service has not been subscribed yet service parameter is not necessary.

Parameters

Param Type Default Meaning
service string none Name of the service.
url string none URL to the service.
confirm bool true Set to false, if MUPE should not confirm the service change from user


Example(s)

<changeservice service="Mupe Master Server" url="mupe.net:8780" />


removecommand


Removes a command, submenu or submenu item from a UI.


Parameters

Param Type Default Meaning
id string none Id of the menu command or submenu..
sub string none Specified in case of removing a single sub menu item instead of removing the whole submenu.


Example(s)

<removecommand id='command1' />


setreference or ref

Sets a UI item as the referenced item. This has no implications to the visible UI by it is a handy way of putting one item into a “register” and then reference to it"s attributes from another item. The item attributes can be referenced using reference keyword. For instance referencing the Id of the referenced item would be like this:


Note: has alias , which is faster to write.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
index int 0 Reference number. Values 0-7 are valid.


Example(s)

<setreference id="sprite1" />

<ref id="sprite1" />


foreach

This method runs a script for each item in an item group that has ID that matches the given pattern. The pattern consist of three possible filters:

  • contains
  • begins
  • ends


They all can be speficied or left unspecified. Unspecified filter means that the script is run for all items according to that filter. As implication from that if all three filters are left unspecified the script is run for all items in that group. Inside the script the item context temporarily is changed to the item the script is run for.

The script is run sequentially for each item instead of running one clause at at time for each item that matches the pattern.

Note: If the Ui group is left unspecified when using this method with canvas UI, the script is run for each item group, instead of items in one item group.


Parameters

Param Type Default Meaning
identifiers params current item Item container identifiers.
contains string none Item Id must contain this text
begins string none Item Id must begin with this text
ends string none item Id must end with this text


Example(s)

<foreach begins="icon_">
   <hide />
</foreach>


debug

Writes debug text on the console and in the client's debug console and also if onscreen parameter is set to true the client is stopped for 3 second debug message box.

note: The debug console can be shown with

<showdebug />


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
text string “” debug text
onscreen bool false Set to true for showing the debug text on device screen instead of default console.


Example(s)

<debug group="group1" item="image1">
   <parms>
      <text>coords: $(this.x) , $(this.y)</text>
   </parms>
</debug>


showdebug

Shows the client's debug console and pauses the client while the user is examining the debug texts.


Example(s)

<showdebug />


reporterrors

With parameter "value='true'" enables error reporting to server. Every error taking place in the client's end is sent to the server. The default implementation in the server writes these error reports into log file. Handy for field testing MUPE service.


Parameters

Param Type Default Meaning
value bool true Set to true for enabling error reporting.


Example(s)

<reporterrors />


alert

Alert method displays an alert box for user containing the given text string and title. The alert box is either disposed after a given time or it waits for user input. If the time is in not specified the alert box waits for user input. There are several different types of alert boxes, which are documented in detail in the “Alert” MID Profile specification J2MESPEC. The valid types are:

  • alarm
  • confirmation
  • error
  • warning
  • info


The “info” alert type is used as default if the type parameter is not specified.

Parameters

Param Type Default Meaning
title string none Title text of alert box
text string none Text content of the alert
type string “info” Alert type: “info”, “alarm”,”confirmation”,”error”,”warning”
time int forever How long the alert is displayed until discarded (ms)


Example(s)

<alert title="test" text="hello world" type="info" time="5000" />


send

Sends a message to the server. Uses the specified UI item as the context for evaluating attribute references. The message can be either a request or a notify message (see "Introduction" chapter for more details).

The content defines which message type it wants to use.

The message is an xml section inside the send method call. If can be free-form text or an xml section, with the exception that the attribute references are evaluated to appropriate attribute values before the text is sent to the server. (See MUPE server documentation for the message syntax).


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
Type string “tcp” “tcp” = Send a tcp message to the server. “http” = Send a http request to the server.
url string current service Alternative HTTP address that receives the message.
event string “on_net_response” Event that is created for the UI when the request is responded.
error string “on_net_error” Event that is created for the UI in case for HTTP error.
port int 8780 Server port for TCP messages.
notifyonly bool false Set to true for notification messages. Client does not wait for reply, nor does server send one.
encode bool true Set to false if the message should not be iso8859-1 encoded before sending.


Example(s)

<send type="tcp">
   clientPoll
</send>
<send notifyonly="true">
   clientSetX $(item1.x)
</send>


delete

Deletes an UI item or item group with given group and Id information. If the referred item is not found the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.


Example(s)

<delete id="sprite1" />


starttimer

Adds a new timer task for the client. Timers can be used to delayed actions, repeated actions and create background task that does not block the UI from user. A timer waits for certain period of time and then invokes the action given to it. After the action has been done it can be repeated with given number of times.

The action can actually be multiple sequences of method calls, which are separated by break methods. Each time the timer is triggered next sequence of method calls is run until next break method. if the end of sequences is exceeded before the timer is disposed the first method call is started again.


Parameters

Param Type Default Meaning
id string none timer id
time int 1000 Timer delay in milliseconds
times int -1 Amount of times the timer activates. –1 = forever
initialise bool false The 1st method call sequence is run only once at timer creation.
finalise bool false The last method call sequence is run only at timer disposal.


Example(s)

<starttimer id="newtimer" time="1000" times="20">
   <move id="sprite1" deltax="20" />
   <break />
   <move id="sprite1" deltay="20" />
   <break />
   <move id="sprite1" deltax="-20" />
   <break />
   <move id="sprite1" deltay="-20" />
</starttimer>

<starttimer id="newtimer" time="10000" times="1">
   <send>poll_ui $(sprite1.x)</send>
</starttimer>


pausetimer

Pauses a timer with given id. If the timer is already paused calling pausetimer resumes it. If the timer is still active it will be paused after it has completed the current action.

Parameters

Param Type Default Meaning
id String none Timer Id

Example(s)

<pausetimer id="newtimer" />


stoptimer

Stops a timer with given id. If the timer is still active it will be stopped after it has completed the current action. If the timer is waiting for the next trigger it is stopped. Stoptimer not only stops the timer but also destroys it, so the timer cannot be resumed other way than with the starttimer statement.


Parameters

Param Type Default Meaning
id String none Timer Id


Example(s)

<stoptimer id="newtimer" />


input

Implements a generic text input functionality. The input method opens an edit box, where the use can input text. The visual representation of the edit box depends on the MIDP implementation.

When the edit box is closed an event occurs for the item in which context input was called. If the user cancelled editing the cancel event is send for the item, and if the result was accepted accept event is sent. The cancel and accept events can be given as parameters or the input uses default events on_textinput_ok and on_textinput_cancel.

If the user accepts the edited text input, the text can be read from $(item.textinput) attribute.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
title string “” Title of the edit box.
text sring “” Current text of the edit box.
max int 128 Maximum characters allowed.
event string “on_textinput_ok” Event created on the item if the user accepts the text input.
cancel string “on_textinput_cancel” Event created on the item if the user cancels the text input.
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)

<template type="canvas">
   <string id='namestatic' text='name:' bold='true' x='5' y='5' />
   <string id='nameedit' text='anonymous' anchor='top_right' anchorid='namestatic' x='5' selectable='true'>
      <hook name='on_select'>
         <input title='Your name?' text='$(this.text)' />
      </hook>
      <hook name='on_textinput_ok'>
         <settext text='$(this.textinput)' />
      </hook>
   </string>
   <allowuserinput value='true' />
</template>


in

Runs a script with given item context if the item exists. If the item does not exist it tries to run the script under else branch. This method can be used for two different purposes:

  1. Making writing xml faster since one does not need to specify the group and id parameters in certain situations.
  2. Can be used for testing if an ui item exists or not.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.


Example(s)

<in id='item1' group='group1'>
   <debug text='The item context on $(this.id) in this xml section' />
</in>


sendsms

This method is used for either sending plain sms messages to any user or sending sms invites to offline users. The sms invite invokes the client in the recipient phone and asks the user if he/she wants to connect the mupe server where the sender is connected to at the moment.


Parameters

Param Type Default Meaning
type string "message" "message" = Message is plain sms message "invite" = Message is an sms invite
messsage string none The message that is sent to the recipient
number string none The phone number of the recipient
sender string none (for sms invites only) Sender avatar name
param string none (for sms invites only) Server state where the recipient is invited to
phone string none (for sms invites only) Phone number of the sender (optional)


Example(s)

<sendsms number='+5550000' message='Hello there!' />

<sendsms number='+5550000' message='Come talk with me!' sender='Jack' param='chatroom' />


hook

This method(re)defines an event hook handler for a UI item. The event handlers can be one of the build-in handlers (for intance on_show) or defined by the content. The event hooks works as subroutines and they can be either invoked with a event method or by the system (in case of predefined event hooks). The script that is run for each event hook is inside the corresponding hook tag.

One can define event hooks for both UI items and item groups. If the event hook is defined in the global level in the template it is defined for the default group.

It is also possible to define an event hook another way (since 2.30b). The client assumes that every tag starting with characters "on_" are event hooks. For example:

<on_create>
   ...scripthere...
</on_create>


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
name string none Name of the event hook


Example(s)

<hook name="on_show">
   <move id="sprite1" x="10" />
</hook>


event

Invokes an event for a UI item (or the UI). Events are like calls to subroutines defined for a UI item. The events can be "hooked" using the hook method. If the given event is hooked the subroutine under the appropriate the hook tag is run.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
hook string none Name of the hook that handles the event
parameters params None Extra parameters for the event. Set of attributes that are set for the item before calling the event.


Example(s)

<event hook="on_show" />

<event hook="my_own_event_hook" myparam="foo" />


loop

Runs a script in a loop for given number of times. If the times parameter is zero the method does nothing.

While the loop is running other methods are not handled (i.e. it's a blocking call). In addition, there is no functionality to time or delay the actions. If the content creator wants to implement animations or timed events he/she should use a timer instead of loop.

Note: By default the index of the current iteration loop can be found from attribute loop_index.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
times int 0 Number of times the loop is run
attr string "loop_index" Alternative attribute name for loop_index. Needed for nested loops.


Example(s)

<loop times="5">
   <show id="image_$(global.loop_index)" />
</loop>


attribute

Defines an attribute for an UI item. There are three basic types that the attribute may use by default

  • int
  • bool
  • string

The "int" type is used for initializing an integer attribute, "bool" type is used for boolean values and the "string" for strings. If the type parameter is not specified the "string" type is used by default.

Attributes are properties of an UI item. The use of attributes is comparable to conventional object-oriented languages, with the exception that the attributes are not protected by any way. Any UI item can change or refer to an attribute of another UI item.

Note: when using arithmetic statement as value parameter of attribute method, one must to specify the type="int" parameter.


Parameters

type ||string||“string”||“int” = value is initialized as integer “string” = value is initialised as string“bool” = value is initialized as Boolean

Param Type Default Meaning
identifiers params current item Item reference.
name string none Attribute name
value any none The initial attribute value.
string None Sets attribute to given value.


Example(s)

<attribute name="str_test" value="foobar" />
<attribute name="int_text" type="int" value="5 + $(this.height)" />
<attribute name="bool_test" type="bool" value="true" />
<attribute str_test2="test 1 2 3" />


inc

Increases the value of an integer attribute. The attribute is referred with group, id and attr parameters, where the group and id define the item and the attr defines the attribute in question. The value is increased by the amount of value parameter. If the value parameter is not specified the value is increased by 1.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value int 1 The amount how attribute value is changed.


Example(s)

<inc attr="amount" value="10" />


dec

Decreases the value of an integer attribute. The attribute is referred with group, id and attr parameters, where the group and id define the item and the attr defines the attribute in question. The attribute value is decreased by the amount of value parameter. If the value parameter is not specified the value is decreased by 1.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value int 1 The amount how attribute value is changed


Example(s)

<dec attr="amount" value="10" />


multiply

Multiplies the value of an integer attribute with a given value. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. The value is multiplied by the amount of value parameter and the result is stored in the attribute. If the value parameter is not specified the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value int 1 The multiplier


Example(s)

<multiply attr="amount" value="2" />


divide

Divides the value of an integer attribute with a given value. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. The value is divided with the value parameter. If the value parameter is not specified the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value int 1 The divider


Example(s)

<divide attr="amount" value="2" />


modulo

Calculates modulo for an integer attribute and the given value and stores the result back to the attribute. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. If the value parameter is not specified the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value int 1 The divider


Example(s)

<modulo attr="amount" value="100" />


absolute

Calculates absolute value for an integer attribute and stores the result back to the attribute. The attribute is referred with group, id and attr parameters, where the group and id defines the item and the attr defines the attribute in question. If the value parameter is not specified the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name


Example(s)

<absolute attr="negative_int" />


substring

Cuts a substring from a given string. The result will be set as the value of given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the specified substring cannot be extracted from the source string the resulting string will be an empty string.

If the end parameter is left unspecified the sub string will be the end of the string starting from the given start index.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be cut.
start int 0 Start index of the sub string (zero based).
end int none End index of the sub string.


Example(s)

<substring attr="title1" text="$(edit1.text)" start="5" end="10" />


stringlength

Calculates length of a given string argument. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String which length is calculated.


Example(s)

<stringlength attr="title1" text="hello world" />


stringtoken

Extracts a string token from a given string using given delimiter (space character by default). The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be tokenized.
delimiter string “ “ Delimiter string that is used for tokenizing the original string.
Index int none Index of the token.
allowmultiple bool false Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.


Example(s)

<stringtoken attr="title1" text="hellofooworld" delimiter="foo" index="1" />


findtoken

Returns index of a given token. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be tokenized.
delimiter string “ “ Delimiter string that is used for tokenizing the original string.
allowmultiple bool false Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.
value string "" Token that is searched in the string.


Example(s)

<findtoken attr="tokenindex" value="world" text="hellofooworld" delimiter="foo" />


settoken

Sets a new value for token with given index. The modified string will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be tokenized.
delimiter string “ “ Delimiter string that is used for tokenizing the original string.
Index int none Index of the token.
allowmultiple bool false Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.
value string "" New value of the token.


Example(s)

<settoken attr="title1" value="bar" text="hellofooworld" delimiter="foo" index="1" />


removetoken

Removes given token completely and also removes the delimiters around the token. The result will be set as the value given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be tokenized.
delimiter string “ “ Delimiter string that is used for tokenizing the original string.
Index int none Index of the token.
allowmultiple bool false Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.


Example(s)

<removetoken attr="worldremoved" text="hellofooworld" delimiter="foo" index="1" />


numberoftokens

Calculates how many string tokens a given string has using given delimiter (space character by default). The result will be set as the value of given attribute. Keep in mind that you cannot change values of read-only attributes (such as title or id) but you need to use content attribute and manipulate the read-only attribute using appropriate set-method (such as settitle).

If the allowmultiple parameter is set to true sub sequent delimiter string are handled as one delimiter string. By default there is an empty token between two subsequent delimiter strings.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute where the result is stored.
text string none String that is to be examined.
delimiter string “ “ Delimiter string that is used for tokenizing the original string.
allowmultiple bool false Set to true if sub sequent delimiters are skipped. By default there is empty string token in between two sub sequent delimiters.


Example(s)

<numberoftokens attr="title1" text="hello foo world" delimiter="foo" />


equal

Conditional statement that tests if two attribute values are equal. if the test fails the script tries to find else branch inside the conditional statement.

The attribute is referred with group, id and attr parameters, where the group and id defines the item of which property the attribute is and the attr parameter is the attribute name.

In addition the method can used to test to integer values instead of testing an attribute. This can be done by specifying parameter value0 instead of attr. Parameter value0 represents the left side of the conditional statement (value0 = value).

If the referred attribute value is equal to the given value parameter the script under the tag is run.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value0 int/string none Optional value that is tested instead of attribute.
value int/string "true" Compared value. Default value has changed to "true" for easier boolean value tests.
numeric bool false Set to true for forcing numeric comparison.
nocase bool false Set to true if comparison of two strings should be case insensitive.


Example(s)

<equal attr="nameattr" value="cat">
   <show id="sprite1" />
   <else>
      <show id="sprite2" />
   </else>
</equal>

<equal value0="2+$(a.b)" value="3\*5" numeric="true">
   <show id="sprite1" />
</equal>


notequal

Conditional statement that tests if two attribute values are not equal. if the test fails the script tries to find else branch inside the conditional statement. The attribute is referred with group, id and attr parameters, where the group and id defines the item of which property the attribute is and the attr parameter is the attribute name.

In addition the method can used to test to integer values instead of testing an attribute. This can be done by specifying parameter value0 instead of attr. Parameter value0 represents the left side of the conditional statement (value0 != value).

If the referred attribute value is not equal to the given value parameter the script under the tag is run.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value0 int/string none Optional value that is tested instead of attribute.
value int/string none Compared value
numeric bool false Set to true for forcing numeric comparison.


Example(s)

<notequal attr="nameattr" value="cat">
   <hide id="sprite1" />
</notequal>

<notequal value0="2+$(a.b)" value="3\*5" numeric="true">
   <show id="sprite1" />
</notequal>


less

Conditional statement that tests if value of an integer attribute is less (or equal) than the given value. if the test fails the script tries to find else branch inside the conditional statement. The attribute is referred with group, id and attr parameters, where the group and id define the item and attr the attribute which is compared.

In addition the method can be used to test to given values instead of testing an attribute. This can be done by specifying parameter value0 instead of attr. Parameter value0 represents the left side of the conditional statement (value0 < value).

If the referred attribute value is less (or equal) than the given value parameter the script under the tag is run. If the attribute value is not an integer the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value0 int/string -1 Optional value that is tested instead of attribute.
value int/string 0 Compared value
orequal bool false Set to true if the script should be run when the values are equal.


Example(s)

<less attr="int_value" value="10">
   <hide id="sprite1" />
</less>

<less value0="2+$(a.b)" value="3\*5" orequal="true">
   <show id="sprite1" />
</less>


greater

Conditional statement that tests if value of an integer attribute is greater (or equal) than given value. if the test fails the script tries to find else branch inside the conditional statement. The attribute is referred with group, id and attr parameters, where the group and id define the item and the attr defines the attribute name that is compared.

In addition the method can used to test two values instead of testing an attribute. This can be done by specifying parameter value0 instead of attr. Parameter value0 represents the left side of the conditional statement (value0 > value).

If the referred attribute value is greater (or equal) than the given value parameter the script under the tag is run. If the attribute value is not an integer the method does nothing.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
attr string none Attribute name
value0 int/string -1 Optional value that is tested instead of attribute.
value int 0 Compared value
orequal bool false Set to true if the script should be run when the values are equal.


Example(s)

<greater attr="int_value" value="10">
   <show id="sprite1" />
</greater>

<greater value0="2+$(a.b)" value="3\*5" orequal="true">
   <show id="sprite1" />
</greater>


switch

Switch is a conditional statement for situation where heavy branching is necessary. It tests is a value against a set of values and then chooses the branch that has the same value as the tested value. The branches are defined inside case tags. The value parameters in the case tags should contain static values. If they don't the value parameters of the case statements are only evaluated once.

One can also speficy default tag that is run if none of the defined cases are equal to the tested value.

Note: Even it works the same way as a set of equal statements it is optimized for testing against static values. It is a lot more effective than a set of equal statements.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
value string none Compared value.
attr string none Optionally name of the attribute that is tested instead of _value_.


Example(s)

<switch value='$(this.x)>
  <case value='0'>
    ... do something here ...
  </case>
  <case value='100'>
    ... do something here ...
  </case>       
</switch>
<default>
    ... run if x != 0 and x != 100 ...
</default>


inrange

Inrange is a conditional statement that tests if an integer value is inside a given range. The value can also be equal to the min and max parameters. if the test fails the script tries to find else branch inside the conditional statement.


Parameters

Param Type Default Meaning
identifiers params current item Item reference.
value int -1 Compared value.
min int 0 Minimum of the range
max int 0 Maximum of the range


Example(s)

<inrange value='$(this.x) min='0' max='100'>
    ... do something here ...
    <else>
       ... run if the test fails ...
    <else>
</inrange>


startvibra

Starts the phone vibrator and vibrates the phone for given time (milliseconds).

Note: This feature is not implemented in all phone models.


Parameters

Param Type Default Meaning
time int 1000 Enable vibration for specific time (ms)


Example(s)

<startvibra time="1000" />


stopvibra

Stops vibration effect from the phone.


Parameters

none


Example(s)

<stopvibra />


flashlights

Flashes the phone lights for a given time (milliseconds).

Note: This feature is not implemented in all phone models.


Parameters

Param Type Default Meaning
time int 0 Time of the effect (ms)


Example(s)

<flashlights time="200" />


playsound

Plays a given sound resource. The sound can be replayed for given amount of times (loops parameter) and it can be played using given volume. If the sound resource does not exist the method does nothing. If the loops is set to zero the sound is played until the playback is stopped with stopsound call.


Parameters

Param Type Default Meaning
resource string none Sound resource Id
loops int 1 How many times the sound is repeated. 0 = forever
volume int -1 Volume of the sound 0-255. –1 = current volume


Example(s)

<playsound resource="soundres1" loops="0" volume="50" />


pausesound

Pauses a currently playing sound resource. If the sound if already paused, it resumes the playback. The method does nothing if the sound resource is not playing of it does not exist.


Parameters

Param Type Default Meaning
resource string none Sound resource Id


Example(s)

<stopsound resource="soundres1" />


stopsound

Stops a currently playing sound resource. The method does nothing if the sound resource is not playing of it does not exist.


Parameters

Param Type Default Meaning
resource string none Sound resource Id


Example(s)

<stopsound resource="soundres1" />


recordaudio

Records an audio clip using the microphone on the phone. The length of the audio clip is given as a parameter, so its not possible to record continuously with the current implementation of the sound recorder.

Note: You can access base64 decoded version of the actual resource data via $(resources.resourceid) reference. This comes handy if you want to send the data to the server.


Parameters

Param Type Default Meaning
resource string none Sound resource Id
accept string none Event that is created when user accepts the sound clip and exits the recorder.
cancel string none Event that is created if user cancels the sound recording.
global bool false Set to true for creating a global resource.
time int -1 Length of the audio clip (milliseconds).


Example(s)

<recordaudio id="item1" resource="soundres1" accept="audio_accepted" cancel="audio_cancelled" time="5000" />


getsnapshot

Gets a snapshot using the built in camera in the phone. The size of the resulting image is specified with width and height parameters. If only one of them is given as a parameter the image keeps its aspect ratio by calculating the missing metric according to the given metric and the original image aspect ratio.

Note: You can access base64 decoded version of the actual resource data via $(resources.resourceid) reference. This way it is possible to send the image data to the server.

Note: Some multi megapixel cameras may not operate correctly is there are several UIs and lots of resources loaded when trying to get a snapshot. In this case the getsnapshot will generate "on_media_error" event. To prevent this, keep the UI simple and use minimal resources when calling getsnaphot.


Parameters

Param Type Default Meaning
resource string none Image resource Id
accept string none Event that is created when user accepts the sound clip and exits the recorder.
cancel string none Event that is created if user cancels the sound recording.
global bool false Set to true for creating a global resource.
width int none Width of the image.
height int none Height of the image.
showpreview bool false Set to true if the camera ui should view a thumbnail of the image before returning to the content. The thumbnail version is reduced size image that fits the screen. Especially handy if the resulting image is high resolution and would not fit the screen.


Example(s)

<getsnapshot id="item1" resource="imageres1" accept="snap_accepted" cancel="snap_cancelled" time="5000" />


playvideo

Plays a video resource on screen. The size and placement of the video is specified with width, height, x and y parameters. If only one of them is given as a parameter the video keeps its aspect ratio by calculating the missing metric according to the given metric and the original video aspect ratio.

It depends on the device capabilities if the client can a) decode the video format b) display the video on the screen.


Parameters

Param Type Default Meaning
resource string none Sound resource Id
width int none Width of the image.
height int none Height of the image.
x int 0 video x-coordinate.
y int 0 video y-coordinate.
loops int 1 How many times the video is played. -1 Means forever.


Example(s)

<playvideo resource="videores1" width='120' height='80' x='20' y='20' loops='3' />


pausevideo

Pauses a currently playing video resource. If the video if already paused, it resumes the playback. The method does nothing if the video resource is not playing of it does not exist.


Parameters

Param Type Default Meaning
resource string none Video resource Id


Example(s)

<stopvideo resource="videores1" />

stopvideo

Stops a currently playing video resource. The method does nothing if the video resource is not playing of it does not exist.


Parameters

Param Type Default Meaning
resource string none Video resource Id


Example(s)

<stopvideo resource="videores1" />


callplatform

Callplatform method enables platform specific functionality such as making a phone call. The functionality available via this method is solely platform dependent. However, if the platform is a mobile phone it can be assumed that at it is possible least to make a phone call or install a JAR from url.


Parameters

Param Type Default Meaning
request string none The platform request


Example(s)

<!-- make a phone call -->
<callplatform request='tel:+358-555-1234567' />

<!-- install a jar file -->
<callplatform request='http://my.site.com/application.jar' />

<!-- if supported, this should open a web page in external browser -->
<callplatform request='http://my.homepage.com/index.html' />


Client-side plugin API

The client can include a set of plugins. These plugins can for instance handle data transfer between the mupe client and devices connected to the mobile phone or implement MIDP optional API support. Each plugin implements an API that can be handled from the XML script in straightforward way.


load

The main purpose of this method is to load a plugin into client"s memory. If the plugin already is loaded, the plugin is reinitialized. There can only be one instance of each plugin running. The call creates an event with name generated from the plugin name such as follows: on_"pluginname"_loaded_status. Attribute named "pluginname"_loaded_status has the actual status information. The attribute has value “yes” for successful call to load and value “no” in case of error. All parameters are passed to the plugin for its internal use.


Parameters

Param Type Default Meaning
plugin String none Name of plugin .
any none Parameter passed to the plugin.


Example(s)

<load plugin="myplugin" testparm="$(client.version)" />


unload

Unloads a plugin from client"s memory. The call creates an event with name generated from the plugin name such as follows: on_"pluginname"_unloaded_status. Service info named "pluginname"_unloaded_status has the actual status information. The attribute has value “yes” for successful call to unload and value “no” in case of error.


Parameters

Param Type Default Meaning
plugin string none Name of plugin.


Example(s)

<unload plugin="myplugin" />


call

Calls a plugin"s method. The call creates an event with name generated from the plugin name and m