Events

A mobile application receives events as a result of

  • User’s gestures like TAP
  • Change in the state of the application

Actions are executed when an event occurs. In XMADL an action is associated with an event by specifying event_list attribute of <action> element

<control..>
    <action name="<action_name>" event_list="<list of events>"..../>
</control>

Example 1 - On TAP of a PUSHBUTTON in screen 1, call actions <save data> and <show screen 2>

<control type="PUSHBUTTON"...>
    <actions>
        <action name="EXECUTE_SQL" event_list="TAP"...>
            <action name="NEXT_SCREEN" event_list="TAP" target="screen 2".../>
        </action>
    </actions>
</control>

Example 2 - On TAP of a list item in screen 3, call action <show screen 4 with item details>

<control type="LIST"...>
    <action name="NEXT_SCREEN" event_list="TAP" target="screen 4".../>
</control>

Example 3 - When a screen is created, get data from server

<screen name="home"...>
    <action name="CALL_URL" event_list="ON_CREATE_SCREEN" .../>
</screen>

The list of events that AVM supports is given below.

Alarm

Event Name When does it occur Use Cases
ON_PLAY_ALARM Alarm set by the action SET_ALARM invokes.

You can use this event to

  • Call the server to refresh data at regular intervals for example LIVE Scores
  • Check email

Note

The actions that get triggered on ON_PLAY_ALARM must be defined in the <screen_deck> element

Application life cycle

Event Name When does it occur Use Cases
ON_FIRST_TIME_APP_LAUNCHED App is launched for the very first time. It does not gets generated after the app is updated and launched This event can be used to fetch one time data from the server or any one time logic
ON_APP_LAUNCHED App is launched after a phone reboot or after a force close of the application. On this event, you can get server session id ,fetch data from server which is infrequently updated.
ON_APPLICATION_BACKGROUND

App goes to background as a result of

  • User pressing the home button to show the phone’s home screen

  • A phone call, an alarm or any other application pops up pushing the

    application to the background

  • User switching to another application

Use this event to

  • synchronize data with server
ON_APPLICATION_FOREGROUND App has gone to background and is now being shown again. Use this event to get frequently updated data from server

Note

The action that gets triggered on the Application life cycle events is generally defined in the XMADL element <screen_deck> as it is not attached to any screen or control in particular.

Gestures

TAP - This event is received by a control when the user taps on a control or received by the screen where there is not underlying control at the tap location. The action that gets triggered on this event can be attached to the control or the screen.
Event Name When does it occur Comments / Use Cases
TAP
  • When the user taps on a control
  • When the user taps on a screen where there is not underlying control at the tap location
Action must be attached to the control or the screen that receives this event TAP is most commonly used to navigate through the app, save user inputs.

Note

  • The actions that get triggered on gesture related events cannot be attached to screen_deck

List Control

Event Name When does it occur Use Cases
ON_CREATE_LIST_ITEM When a new LIST item is about to be created in the LIST, SEARCHABLE_LIST, SINGLE_CHOICE_PICKER controls. List items get created when the data source is set or when the user scrolls the LIST items. Use this event to change the appearance of a control based on data etc.
ON_EMPTY_LIST When the LIST box receives the data source (Cursor, JSON array or ArrayList) that has 0 rows or elements Use this event to display a message “No data found” Or show a control

Note

  • This event is generated very frequently on LIST scrolling hence the actions for this event must be fast. Otherwise the application will be sticky.

Long Tasks

long_tasks is a type of screen that runs long running tasks in the background. Since the long tasks are running in the background, the application is still responsive to the user’s gesture like TAP. The screen is displayed as long as the task is running. When the task finishes, the screen also ends itself.

Event Name When does it occur Comments / Use Cases
ON_DO_IN_BACKGROUND When the screen type “Long Tasks” screen is created. When the screen type “Long Tasks” screen is created. This event is raised on the background thread and the associated action is executed in the background thread. This event is used when a long running task is to be executed. Tasks that may take long time for example, could be fetching more than 10MB of data. from a remote server.
ON_DO_IN_BACKGROUND_ERROR When the background thread is finished and the return result from the action running on ON_DO_IN_BACKGROUND returns false This event can be used to display a message to the user.

Remote URL Calls

Event Name When does it occur Comments
ON_POST_CALL_URL Upon return of a server response. URL’s can be invoked from remote data source, CALL_URL Use this event to do post processing on data received after receiving data from the remote server or trigger other actions based on the received data.

Screen life cycle

When the screen gets created it foes through different stages in its life cycle. Show the screen life cycle diagram or the link to it. TODO.

Event Name When does it occur Comments / Use cases
BEFORE_ON_CREATE_SCREEN The first event generated while the screen is being created. At the time of this event, no controls have been created. This event is generally used to change the screen layout dynamically based on application logic. Is generated only once in the lifetime of the screen. Use this event to dynamically change the layout of the screen based on application (or data) state
ON_CREATE_SCREEN While the screen is being created and the controls have already been placed on the screen This event like BEFORE_ON_CREATE_SCREEN is called only once in the lifetime of the screen. On this event, you could do a one time initialization tasks like setting the TEXT label based on business logic.
ON_START_SCREEN When the screen and its controls have been created. This event is similar to ON_CREATE_SCREEN and is generated only once in the lifetime of the screen. On this event, you could do a one time initialization tasks like setting the TEXT label based on business logic.
BEFORE_ON_RESUME_SCREEN When the screen resumes. The screen resumes after being created or when it comes to foreground again. On this event, you could change the data sources using action FUNCTION.
ON_RESUME_SCREEN Similar to BEFORE_ON_RESUME_SCREEN except that it is generated after the data has been fetched from local and remote data sources and populated in the controls. On this event, you could put additional logic to set control value using SET_CONTROL_ATTRIBUTES.
ON_POST_RESUME_SCREEN Similar to ON_RESUME_SCREEN but gets generated after it. Similar to ON_RESUME_SCREEN, you could set control values using SET_CONTROL_ATTRIBUTES
ON_PAUSE_SCREEN When the screen goes to background. The screen is paused when another screen is shown on top of it. On this event, you can save data locally (EXECUTE_SQL) or remotely (CALL_URL) if the screen supports auto-save
BEFORE_ON_DESTROY_SCREEN Before the screen is being finished. Actions triggered on this event generally do a cleanup or save data locally (EXECUTE_SQL) or remotely (CALL_URL). This event is generated only once in the lifetime of the screen.
ON_STOP_SCREEN Generated right after the BEFORE_ON_DESTROY_SCREEN and before the ON_DESTROY_SCREEN. At this time, no part of the screen is visible and is generated only once in the lifetime of the screen.
ON_DESTROY_SCREEN Generated after the screen is finished and all its views have been destroyed. Actions triggered on this event generally do a cleanup. The controls may not be available on this event. This is generated only once in the lifetime of the screen. You can use this event to stop any listeners or release device resources like Media Player.

Selection control

AVM has following basic selection controls - CHECKBOX, RADIOGROUP, RADIOBUTTON, TOGGLEBUTTON, SINGLE_CHOICE_PICKER.

Event Name When does it occur Comments
ON_CHECKED When the selection controls are set to checked. Use this event to display controls that were hidden initially using SET_CONTROL_ATTRIBUTES or save data locally or remotely.
ON_UNCHECKED When the selection controls are set to unchecked. Use this event to hide some controls no longer applicable using SET_CONTROL_ATTRIBUTES or save data locally or remotely.

Pick Contacts

Event Name When does it occur Comments
ON_PICK_CONTACT The action ADD_FROM_CONTACT displays the device’s contact list. When the user selects the contact from the contact list. Use this event to use or save the contact details with the app.