UI Application
PUBLISHED
To create a basic UI application, you must:
- Define the application fundamentals, mainly the entry point and life-cycle methods for event handling.
The entry point starts the event loop, which is mandatory for every Tizen .NET application. Within the event loop, the application can receive both basic system events and application state change events. You can override the methods triggered for these events to react to them.
- Manage application states and transitions during the application life-cycle.
- Define a background category for your application, if you want it to run in the background.
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 [1] 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
Prerequisites
To use the methods and properties of the Tizen.Applications [1] namespace, include it in your application:
using Tizen.Applications;
Handling the Application Fundamentals
The Tizen.Applications [1] 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:
-
Make a class derived from the Tizen.Applications.CoreUIApplication [2] class and start the application with the
Main()
method. The method initializes the application and starts the main event loop with theRun()
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); } }
- 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 theRun()
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); } }
-
Define any required application controls. The Tizen.Applications.ReceivedAppControl [3] class, derived from the Tizen.Applications.AppControl [4] 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. TheTizen.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 asimage/jpg
.ExtraData
: Retrieve the data associated with a given key, using the Tizen.Applications.AppControl.ExtraDataCollection [5] class. First check whether the data is an array using theIsCollection()
method of theTizen.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 [6] | media |
Download | Downloading data with the classes and methods of the Tizen.Content.Download namespace | Tizen.Content.Download [7] | download |
Background network | Processing general network operations in the background (such as sync-manager, IM, and VOIP) | Tizen.Account.SyncManager [8] | background-network |
Location | Processing location data in the background | Tizen.Location [9]
Tizen.Maps [11] |
location |
Sensor (context) | Processing context data from the sensors, such as gesture | Tizen.Sensor [12] | sensor |
IoT Communication/Connectivity | Communicating between external devices in the background (such as Wi-Fi and Bluetooth) | Tizen.Network.WiFi [13] | 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>