Component Based Application

Note

EFLComponentBasedApplication class and EFLWindowInfo class are deprecated since API Level 10 and will be removed in API Level 12.

The component based application is one of the Tizen application models. This application model enables you to create an application that provides multiple components in one process. In the component based application model, there are three types of components. Each component type has its own life cycle. Named below are the components:

• Service component: The service component has a life cycle for managing services without UI.
• Frame component: The frame component has a life cycle for managing UI resources.
• Widget component: The widget component has a life cycle for managing widget resources.

As you create a Tizen project, you can add components to your project. The registered components create instances when the component based application receives a launch request.

The main component based application API features include the following:

• Application states

  A Tizen dotnet component based application transitions through various states during its life cycle.

• Application event callbacks

  The component based application can receive applications state change events. You can register callbacks for these events to react to them.

• Component’s states and event callbacks

  • Frame component states

    A frame component transitions through various states during its life cycle.

  • Frame component event callbacks

    The component based application can receive frame component state change events. You can register callbacks for these events to react to them.

  • Service component states

    A service component transitions through various states during its life cycle.

  • Service component event callbacks

    The component based application can receive service component state change events. You can register callbacks for these events to react to them.

  • Widget component states

    A widget component transitions through various states during its life cycle.

  • Widget component event callbacks

    The component based application can receive widget component state change events. You can register callbacks for these events to react to them.

• Application behavior attributes

  You can declare components and their specific attributes in the application manifest file.

Application states

The following figure and table describe the component based application states:

Note

The component based application is created by requesting the creation of the first component and terminates if there are no running instances. In the Running state, the component based application creates instances of registered components. The registered component can have multiple instances.

Application event callbacks

You can control the component based application execution by managing the application state events.

The following table lists the callbacks for the application state events:

Component’s states and event callbacks

Component based API provides state and event callbacks for each component.

Frame component states

The following figure and table describe the frame component states:

Frame component event callbacks

You can control the frame component life cycle by managing the frame component state events.

The following table lists the callbacks for the frame component state events:

The frame component instance can also receive some basic system events. The following table shows available system events callbacks:

Service component states

The following figure and table describe the service component states:

Service component event callbacks

You can control the service component life cycle by managing the service component state events.

The following table lists the callbacks for the service component state events:

The service component instance can also receive some basic system events. The following table shows available system events callbacks:

Widget component states

Note

The widget component APIs are supported since Tizen 6.5

The following figure and table describe the widget component states:

Widget component event callbacks

Note

The widget component APIs are supported since Tizen 6.5

You can control the widget component life cycle by managing the widget component state events.

The following table lists the callbacks for the widget component state events:

The widget component instance can also receive some basic system events. The following table shows available system events callbacks:

Application attributes

Define your component based application attributes in the manifest file. The attributes determine the application behavior. The following code example illustrates how you can define the attributes:

                
xml
                

                    
Copy
                    

                
            
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns="http://tizen.org/ns/packages" api-version="9" package="@PACKAGE_NAME@" install-location="internal-only" version="0.1.1">
    <label>Sample</label>
    <author email="tizenappfw@samsung.com" href="www.samsung.com">Tizen App Framework</author>
    <description>Sample</description>
    <component-based-application appid="org.tizen.base-component" exec="@BINDIR@/base-component" type="dotnet">
        <label>Base-component application</label>
        <icon>@DESKTOP_ICON@</icon>
        <service-component id="base-service" main="false">
            <label>base-service</label>
        </service-component>
        <frame-component id="base-frame" launch_mode="caller" main="true" icon-display="true" taskmanage="true">
            <icon>org.tizen.sample.png</icon>
            <label>base-frame</label>
            <label xml:lang="en-us">base-frame</label>
            <label xml:lang="ko-kr">base-frame[KOR]</label>
        </frame-component>
	<widget-component id="base-widget" main="false" setup-appid="base-widget" update-period=0 max-instance=0>
            <icon>org.tizen.sample.png</icon>
            <label>base-widget</label>
            <label xml:lang="en-us">base-widget</label>
            <label xml:lang="ko-kr">base-widget[KOR]</label>
            <support-size>2x2</support-size>
        </widget-component>
    </component-based-application>
    <privileges>
        <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
    </privileges>
</manifest>

Following are the main application attributes:

• id

  Every component element has an id attribute. The attribute ID must be globally unique in a device. If not, the application installation fails. This attribute is also used by other applications to confirm which component must be created.

• main

  Component based applications can have multiple components and there is one main component. The main component is the component that is created when the component based application receives a launch request without a specific component ID. To set the main component, set the main attribute to true.

• icon-display

  This attribute is only for the frame component element. If this value is set to true, the home application displays an icon on the app tray for the frame components.

• launch_mode

  This attribute is only for the frame component element. Application launch mode values are:

  • Single: Launched as the main application.
  • Group: Launched as a sub-application.
  • Caller: Defines the launch mode with AppControl.SetLaunchMode().

• taskmanage

  This attribute is only for the frame component element. This attribute indicates whether the application appears in the task manager or not. The available values are true and false.

• setup-appid

  This attribute is only for the widget component element. This attribute is app ID that is used when the widget component element is launched.

• max-instance

  This attribute is only for the widget component element. This attribute limits the number of widget instances concurrently executable for a web application. When omitted or its value is 0, unlimited number of widget instances are supported. The expected value is an integer.

Prerequisites

To use the functions and data types of the Tizen.Applications.ComponentBased.Common namespace, include it in your application:

                
C#
                

                    
Copy
                    

                
            
using Tizen.Applications.componentbased.common
using Tizen.Applications.componentbased.default  // if you want to use ELFComponentBasedApplication

Start component based application

To start a component based application, you must register the component based application callbacks and start a main event loop as shown in the following code:

                
C#
                

                    
Copy
                    

                
            
namespace CompBasedCsharp
{
    internal class App : EFLComponentBasedApplication
    {
        App(IDictionary<Type, string> typeInfo) : base(typeInfo)
        {
        }

        static void Main(string[] args)
        {
            Elementary.Initialize();
            Elementary.ThemeOverlay();
            IDictionary<Type, string> typeInfo = new Dictionary<Type, string>();
            typeInfo.Add(typeof(FrameComp), "csharp_frame");
            typeInfo.Add(typeof(ServiceComp), "csharp_service");
            typeInfo.Add(typeof(WidgetComp), "csharp_widget");
            App app = new App(typeInfo);
            app.Run(args);
        }
    }
}

Manage frame component

To add and manage frame components, you must add a frame component and register the frame component object. Follow the steps below to manage frame compnents.

1. Declare a frame component in the manifest file:

   
                   
   xml
                   
   
                       
   Copy
                       
   
                   
               
   <component-based-application appid="org.tizen.base-component" exec="@BINDIR@/base-component" nodisplay="false" multiple="false" type="dotnet">
       <label>Base-component application</label>
       <icon>@DESKTOP_ICON@</icon>
       <frame-component id="base-frame" launch_mode="caller" main="true" icon-display="false" taskmanage="true">
           <icon>org.tizen.sample.png</icon>
           <label>base-frame</label>
           <label xml:lang="en-us">base-frame</label>
           <label xml:lang="ko-kr">base-frame[KOR]</label>
       </frame-component>
   </component-based-application>
   

2. Add a frame component to the component based application:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   public class FrameComp : FrameComponent
   {
       internal static readonly string LogTag = "CompBasedCsharp";
       EFLWindowInfo win_;
   
       public override IWindowInfo CreateWindowInfo()
       {
           Window window = new Window("base-frame");
           win_ = new EFLWindowInfo(window);
           return win_;
       }
       public override bool OnCreate()
       {
           Log.Debug(LogTag, "OnCreate Frame");
           return true;
       }
       public override void OnStart(AppControl control, bool restarted)
       {
           Log.Debug(LogTag, "OnStart Frame");
       }
       public override void OnResume()
       {
           Log.Debug(LogTag, "OnResume Frame");
           base.OnResume();
       }
       public override void OnPause()
       {
           Log.Debug(LogTag, "OnPause Frame");
           base.OnPause();
       }
       public override void OnDestroy()
       {
           Log.Debug(LogTag, "OnDestroy Frame");
           base.OnDestroy();
       }
       public override void OnStop()
       {
           Log.Debug(LogTag, "OnStop Frame");
           base.OnStop();
       }
   }
   
   namespace CompBasedCsharp
   {
       internal class App : EFLComponentBasedApplication
       {
           internal static readonly string LogTag = "CompBasedCsharp";
           App(IDictionary<Type, string> typeInfo) : base(typeInfo)
           {
           }
   
           static void Main(string[] args)
           {
               Elementary.Initialize();
               Elementary.ThemeOverlay();
               Log.Error(LogTag, "start");
               IDictionary<Type, string> typeInfo = new Dictionary<Type, string>();
               typeInfo.Add(typeof(FrameComp), "base-frame");
               App app = new App(typeInfo);
               app.Run(args);
           }
       }
   }
   

Manage service component

To add and manage service component, you must add a service component and register the service component object. Follow the steps below to manage service components.

1. Declare a service component in the manifest file:

   
                   
   xml
                   
   
                       
   Copy
                       
   
                   
               
   <component-based-application appid="org.tizen.base-component" exec="@BINDIR@/base-component" nodisplay="false" multiple="false" type="dotnet">
       <label>Base-component application</label>
       <icon>@DESKTOP_ICON@</icon>
       <service-component id="base-service" launch_mode="caller" main="false" icon-display="false" taskmanage="true">
           <icon>org.tizen.sample.png</icon>
           <label>base-service</label>
           <label xml:lang="en-us">base-service</label>
           <label xml:lang="ko-kr">base-service[KOR]</label>
       </service-component>
   </component-based-application>
   

2. Add a service component to the component based application:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   public class ServiceComp : ServiceComponent
   {
       internal static readonly string LogTag = "CompBasedCsharp";
       public override bool OnCreate()
       {
           Log.Debug(LogTag, "OnCreate Service");
           return true;
       }
       public override void OnStartCommand(AppControl control, bool restarted)
       {
           Log.Debug(LogTag, "OnStartCommand Service");
       }
       public override void OnDestroy()
       {
           Log.Debug(LogTag, "OnDestroy Service");
           base.OnDestroy();
       }
   }
   
   namespace CompBasedCsharp
   {
       internal class App : EFLComponentBasedApplication
       {
           internal static readonly string LogTag = "CompBasedCsharp";
           App(IDictionary<Type, string> typeInfo) : base(typeInfo)
           {
           }
   
           static void Main(string[] args)
           {
               Elementary.Initialize();
               Elementary.ThemeOverlay();
               Log.Error(LogTag, "start");
               IDictionary<Type, string> typeInfo = new Dictionary<Type, string>();
               typeInfo.Add(typeof(ServiceComp), "base-service");
               App app = new App(typeInfo);
               app.Run(args);
           }
       }
   }
   

Manage widget component

Note

The widget component APIs are supported since Tizen 6.5

To add and manage widget components, you must add a widget component and register the widget component object. Follow the steps below to manage widget components.

1. Declare a widget component in the manifest file:

   
                   
   xml
                   
   
                       
   Copy
                       
   
                   
               
   <component-based-application appid="org.tizen.base-component" exec="@BINDIR@/base-component" nodisplay="false" multiple="false" type="dotnet">
       <label>Base-component application</label>
       <icon>@DESKTOP_ICON@</icon>
       <widget-component id="base-widget" setup-appid="base-widget" max-instance=0>
           <icon>org.tizen.sample.png</icon>
           <label>base-widget</label>
           <label xml:lang="en-us">base-widget</label>
           <label xml:lang="ko-kr">base-widget[KOR]</label>
           <support-size>2x2</support-size>
       </widget-component>
   </component-based-application>
   

2. Add a widget component to the component based application:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   public class WidgetComp : WidgetComponent
   {
       internal static readonly string LogTag = "CompBasedCsharp";
       MyWindowProxy win_;
   
       public override IWindowProxy CreateWindowInfo(int width, int height)
       {
           Window window = new Window("base-widget");
           win_ = new MyWindowProxy(window);
           return win_;
       }
       public override bool OnCreate(int width, int height)
       {
           Log.Debug(LogTag, "OnCreate Widget");
           return true;
       }
       public override void OnStart(bool restarted)
       {
           Log.Debug(LogTag, "OnStart Widget");
       }
       public override void OnResume()
       {
           Log.Debug(LogTag, "OnResume Widget");
           base.OnResume();
       }
       public override void OnPause()
       {
           Log.Debug(LogTag, "OnPause Widget");
           base.OnPause();
       }
       public override void OnDestroy(bool permanent)
       {
           Log.Debug(LogTag, "OnDestroy Widget");
           base.OnDestroy(permanent);
       }
       public override void OnStop()
       {
           Log.Debug(LogTag, "OnStop Widget");
           base.OnStop();
       }
   }
   
   namespace CompBasedCsharp
   {
       internal class App : EFLComponentBasedApplication
       {
           internal static readonly string LogTag = "CompBasedCsharp";
           App(IDictionary<Type, string> typeInfo) : base(typeInfo)
           {
           }
   
           static void Main(string[] args)
           {
               Elementary.Initialize();
               Elementary.ThemeOverlay();
               Log.Error(LogTag, "start");
               IDictionary<Type, string> typeInfo = new Dictionary<Type, string>();
               typeInfo.Add(typeof(WidgetComp), "base-widget");
               App app = new App(typeInfo);
               app.Run(args);
           }
       }
   }
   

Launch component based application

To launch a component based application, follow the steps below:

1. Declare the launch privilege in the manifest file:

   
                   
   xml
                   
   
                       
   Copy
                       
   
                   
               
   <?xml version="1.0" encoding="utf-8"?>
   <manifest xmlns="http://tizen.org/ns/packages" api-version="9" package="@PACKAGE_NAME@" install-location="internal-only" version="0.1.1">
       <label>Sample</label>
       <author email="tizenappfw@tizen.com" href="www.tizen.org">Tizen App Framework</author>
       <description>Sample</description>
       <ui-application appid="org.tizen.sample" exec="@BINDIR@/sample" nodisplay="false" multiple="false" type="dotnet" taskmanage="true" launch_mode="caller">
           <label>Sample</label>
           <icon>@DESKTOP_ICON@</icon>
       </ui-application>
       <privileges>
           <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
       </privileges>
   </manifest>
   

2. Send launch request.

   You can send a launch request using AppControl. AppControl contains the component based application’s ID and the component ID. The component ID is optional. If you do not set the component ID, the main component instance is created.

   You can launch a component based application as shown in the following code:

   
                   
   C#
                   
   
                       
   Copy
                       
   
                   
               
   private void ButtonClickedCallback(object sender, EventArgs e)
   {
       AppControl control = new AppControl();
       control.ApplicationId = "org.tizen.example.CompBasedCsharp";
       control.ComponentId = "base-frame";
       control.LaunchMode = AppControlLaunchMode.Group;
       AppControl.SendLaunchRequestAsync(control, null);
   }
   

Related information

• Dependencies
  • Tizen 5.5 and Higher