Lifecycle Management

The Hello World tutorial explained how to create a desktop-like application using the EFL_MAIN() macro. Applications targeted at mobile or embedded devices often have additional lifecycle constrains which are explored in this tutorial.

Prerequisites

You should have completed the Hello World tutorial in order to understand the basics of EFL application creation before proceeding with this tutorial.

Application Management Events

EFL will call some special methods in your application to inform you of events related to the application lifecycle such as being paused, resumed or when it is about to be closed.

If you use the EFL_MAIN() macro, as in the Hello World tutorial, these methods are hidden from you. While this is usually convenient for desktop applications, you will likely need to use them when developing mobile or embedded applications. To do this you should use the EFL_MAIN_EX() macro instead.

Begin by creating a lifecycle_main.c file:

#define EFL_BETA_API_SUPPORT 1
 
#include <Eina.h>
#include <Efl_Core.h>
 
EAPI_MAIN void
efl_main(void *data EINA_UNUSED, const Efl_Event *ev)
{
   printf("Lifecycle: launched\n");
}
EFL_MAIN_EX()

This is based on the Hello World tutorial but rewritten to use EFL_MAIN_EX(). If you try to compile it, however, it will complain - admittedly in a rather convoluted way - about missing symbols.

These are the new methods that you need to add. All of them have the same signature as efl_main():

Method	Purpose
`efl_pause()`	Application is entering the paused state
`efl_resume()`	Application is leaving the paused state
`efl_terminate()`	Application is about to be terminated

Add them with a simple printf() so you can more easily keep track of the application state changes:

EAPI_MAIN void
efl_pause(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: paused\n");
}
 
EAPI_MAIN void
efl_resume(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: resumed\n");
}
 
EAPI_MAIN void
efl_terminate(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: terminated\n");
}

The system will typically put your application in the paused state when it leaves the foreground. You should free as many resources as you can in efl_pause() so they are available to other applications. You may then reload them in efl_resume().

In efl_terminate() you will usually commit the application state to permanent storage, such as a file on disk, so it can be retrieved next time the application is started.

Simulating Application Management Events

The above section explains everything you need to know about application lifecycle management in EFL. The code provided so far, however, will not demonstrate much when tested on a desktop environment.

This sections adds a bit of simulation code which will artificially trigger the application management events, for the sake of this tutorial.

Begin by defining this method in your existing code:

static void
_lifecycle_simulation(void *data, const Efl_Event *ev EINA_UNUSED)
{
   Efl_Loop *loop = data;
   static int called = 0;
 
   switch (called)
     {
        case 0:
          // First call, pause the application
          efl_event_callback_call(loop, EFL_LOOP_EVENT_PAUSE, NULL);
          break;
        case 1:
          // Second call, resume the application
          efl_event_callback_call(loop, EFL_LOOP_EVENT_RESUME, NULL);
          break;
        default:
          // Last call, exit the application
          efl_exit(0);
     }
 
   called++;
}

If you have read the Events Programming Guide you will know that the efl_event_callback_call() function is manually emitting an event. This used internally by EFL to inform your application of these events on systems that support them - i.e. not on desktops.

Now create a timer at the end of efl_main() that will periodically call the above defined _lifecycle_simulation() method:

   [...]
   efl_add(EFL_LOOP_TIMER_CLASS, ev->object,
           efl_event_callback_add(efl_added, EFL_LOOP_TIMER_EVENT_TICK, _lifecycle_simulation, ev->object),
           efl_loop_timer_interval_set(efl_added, 1.0));

This call creates a timer, registers a callback to it and configures it to trigger every second. Read the Main Loop Programming Guide for more information on timers.

With this, the program is complete including the simulation code.

Complete Application

The whole program, with some additional comments for clarity, is reproduced below:

#define EFL_BETA_API_SUPPORT 1
 
#include <Eina.h>
#include <Efl_Core.h>
 
/*
 * This helper method triggers lifecycle events for the purpose of this demo.
 * efl_pause and efl_resume may never be called for your application, depending
 * on your environment, therefore this demo triggers them directly to show how
 * you can respond.
 */
 
static void
_lifecycle_simulation(void *data, const Efl_Event *ev EINA_UNUSED)
{
   Efl_Loop *loop = data;
   static int called = 0;
 
   switch (called)
     {
        case 0:
          // First call, pause the application
          efl_event_callback_call(loop, EFL_LOOP_EVENT_PAUSE, NULL);
          break;
        case 1:
          // Second call, resume the application
          efl_event_callback_call(loop, EFL_LOOP_EVENT_RESUME, NULL);
          break;
        default:
          // Last call, exit the application
          efl_exit(0);
     }
 
   called++;
}
 
EAPI_MAIN void
efl_pause(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: paused\n");
}
 
EAPI_MAIN void
efl_resume(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: resumed\n");
}
 
EAPI_MAIN void
efl_terminate(void *data EINA_UNUSED, const Efl_Event *ev EINA_UNUSED)
{
   printf("Lifecycle: terminated\n");
}
 
EAPI_MAIN void
efl_main(void *data EINA_UNUSED, const Efl_Event *ev)
{
   printf("Lifecycle: launched\n");
 
   // The timer function will trigger the chain of simulated events to show
   // how an app could respond to system lifecycle events.
   efl_add(EFL_LOOP_TIMER_CLASS, ev->object,
           efl_event_callback_add(efl_added, EFL_LOOP_TIMER_EVENT_TICK, _lifecycle_simulation, ev->object),
           efl_loop_timer_interval_set(efl_added, 1.0));
}
EFL_MAIN_EX()

A copy of this program is available in the EFL git repository: tutorial/c/lifecycle/src/lifecycle_main.c.

Execute the program and you will see how it receives events for Launch, Pause, Resume and Termination, spaced every second.

Summary

At the end of this tutorial you have learned:

To use EFL_MAIN_EX() instead of EFL_MAIN() if you are interested in application management events.
The methods to implement in that case: efl_pause(), efl_resume() and efl_terminate().

Navigation