UI Application

To create a basic UI application, you must:

Event Handling

The following table lists the methods that are triggered when the application state changes.

Table: Application state change methods

Method Description
OnCreate() Used to take necessary actions before the main event loop starts. Place the UI generation code here to prevent missing any events from your application UI.
OnPause() Used to take necessary actions when the application becomes invisible. For example, release memory resources so other applications can use them. Do not starve the foreground application that is interacting with the user.
OnResume() Used to take necessary actions when the application becomes visible. If you relinquish anything in the OnPause() method, re-allocate those resources here before the application resumes.
OnTerminate() Used to take necessary actions when the application is terminating. Release all resources, especially any allocations and shared resources, so that other running applications can fully use any shared resources.

For more information, see Application States and Transitions.

To react to system events, override the methods that are triggered when system events occur. The following table lists the related methods.

Table: System event methods

Method Description
OnLowMemory() This method is responsible for saving data in the main memory to a persistent memory or storage to avoid data loss in case the Tizen platform Low Memory Killer kills your application to get more free memory. The event handler must also release any cached data in the main memory to secure more free memory.
OnLowBattery() This method is responsible for saving data in the main memory to a persistent memory or storage to avoid data loss in case the power goes off completely. The method must also stop heavy CPU consumption or power consumption activities to save the remaining power.
OnDeviceOrientationChanged() This method is responsible for changing the display orientation to match the device orientation.
OnLocaleChanged() This method is responsible for refreshing the display into the new language.
OnRegionFormatChanged() This method is responsible for refreshing the display into the new time zone.

Application States and Transitions

The Tizen .NET application can be in one of several application states.

The Tizen.Applications namespace defines 5 states with corresponding state change methods. A state change method is triggered after each state change: whenever the application is created, starts running, or is paused, resumed, or terminated. The application must react to each state change appropriately.

Table: Application states

State Description
READY Application is launched.
CREATED Application starts the main loop.
RUNNING Application is running and visible to the user.
PAUSED Application is running but invisible to the user.
TERMINATED Application is terminated.

The following figure illustrates the application state transitions.

Figure: Application state transitions

Application state transitions

Prerequisites

To use the methods and properties of the Tizen.Applications namespace, include it in your application:

using Tizen.Applications;

Handling the Application Fundamentals

The Tizen.Applications namespace is a simple framework all Tizen .NET applications are based on. It only handles interactions between applications and the operating system. In order for an application to operate successfully, it must receive events from the platform. For this, it must start the main event loop - this is mandatory for all Tizen .NET applications.

To manage the application life-cycle:

  1. Make a class derived from the Tizen.Applications.CoreUIApplication class and start the application with the Main() method. The method initializes the application and starts the main event loop with the Run() method.

    The following code is a minimal application using the Tizen.Applications namespace. It only builds and runs.

    class App : CoreUIApplication
    {
        static void Main(string[] args)
        {
            /// Run the application
            App app = new App();
            app.Run(args);
        }
    }
    
  2. Override the methods triggered for application state changes and system events.

    The following example shows a basic implementation with overridden methods for application state change events:

    • OnCreate(): Called after the Run() method and used to initialize the UI.
    • OnAppControlReceived(): Triggered when the application is started to do something. It can be called several times during the lifespan of an application, and it shows the screen for the action requested. It requires specific information provided as parameters.
    • OnTerminate(): Saves work, releases resources, and exits.
    • OnPause(): Sets the application window not visible and switches to a mode which uses less resources.
    • OnResume(): Sets the application window to be visible again.
    class App : CoreUIApplication
    {
        protected override void OnCreate()
        {
            /// Hook to take necessary actions before main event loop starts; this
            /// usually means initializing the UI
    
            base.OnCreate();
        }
    
        protected override void OnAppControlReceived(AppControlReceivedEventArgs e)
        {
            /// Handle the launch request, show the user the task requested through the
            /// "AppControlReceivedEventArgs" parameter
    
            base.OnAppControlReceived(e);
        }
    
        protected override void OnPause()
        {
            /// Take necessary actions when application becomes invisible
    
            base.OnPause();
        }
    
        protected override void OnResume()
        {
            /// Take necessary actions when application becomes visible
    
            base.OnResume();
        }
    
        protected override void OnTerminate()
        {
            /// Release all resources
    
            base.OnTerminate();
        }
    
        static void Main(string[] args)
        {
            App app = new App();
            app.Run(args);
        }
    }
    
  3. Define any required application controls. The Tizen.Applications.ReceivedAppControl class, derived from the Tizen.Applications.AppControl class, is a mechanism through which the application receives additional information about why it was started and with which parameters.

    The application receives a handle to an app control object in the OnAppControlReceived() method. The Tizen.Applications.ReceivedAppControl class is opaque and information can only be extracted from it through properties, such as:

    • Operation: Retrieve a string describing which operation the application was started for.
    • Mime: Retrieve the MIME type of the data, such as image/jpg.
    • ExtraData: Retrieve the data associated with a given key, using the Tizen.Applications.AppControl.ExtraDataCollection class. First check whether the data is an array using the IsCollection() method of the Tizen.Applications.AppControl.ExtraDataCollection class.

Background Categories

An application is not allowed to run in the background except when it is explicitly declared to do so. The following table lists the background categories that allow an application to run in the background.

Table: Allowed background application policy

Background category Description Related namespaces Manifest file <background-category> element value
Media Playing audio, recording, and outputting streaming video in the background Tizen.Multimedia media
Download Downloading data with the classes and methods of the Tizen.Content.Download namespace Tizen.Content.Download download
Background network Processing general network operations in the background (such as sync-manager, IM, and VOIP) Tizen.Account.SyncManager background-network
Location Processing location data in the background Tizen.Location

Tizen.Location.Geofence

Tizen.Maps

location
Sensor (context) Processing context data from the sensors, such as gesture Tizen.Sensor sensor
IoT Communication/Connectivity Communicating between external devices in the background (such as Wi-Fi and Bluetooth) Tizen.Network.WiFi

Tizen.Network.Bluetooth

iot-communication

Describing the Background Category

An application with a background running capability must declare the background category in its manifest file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns="http://tizen.org/ns/packages" api-version="4" package="org.tizen.example.TestApp" version="1.0.0">
   <profile name="common" />
   <ui-application appid="org.tizen.example.TestApp" exec="TestApp.dll" type="dotnet" multiple="false"
	               taskmanage="true" nodisplay="false" launch_mode="single">
     <label>TestApp</label>
     <icon>TestApp.png</icon>
     <background-category value="media"/>
     <background-category value="download"/>
     <background-category value="background-network"/>
   </ui-application>
</manifest>