UI Application

Before reading this document, we recommend you get familiarized with the application life cycle documentation.

To create a basic UI application, you must do the following:

• 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.

Handle events

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

Table: Application state change methods

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

Prerequisites

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

                
C#
                

                    
Copy
                    

                
            
using Tizen.Applications;

Handle the application fundamentals

The Tizen.Applications namespace is a simple framework on which all Tizen .NET applications are based on. It only handles interactions between applications and the operating system. 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, follow these steps:

1. Make a class derived from the Tizen.NUI.NUIApplication 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:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   class App : NUIApplication
   {
       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.

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   class App : NUIApplication
   {
       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 follows:

   • 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

Describe the background category

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

                
XML
                

                    
Copy
                    

                
            
<?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-nui" 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>

Related information

• Dependencies
  • Tizen 4.0 and Higher