doc/appfw_app_doc.h

   1 /*
   2  * Copyright (c) 2011 - 2016 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef __TIZEN_APPFW_APP_DOC_H__
  19 #define __TIZEN_APPFW_APP_DOC_H__
  20
  21 /**
  22 * @ingroup CAPI_APPLICATION_FRAMEWORK
  23 * @defgroup CAPI_APPLICATION_MODULE Application
  24 * @addtogroup CAPI_APPLICATION_MODULE
  25 * @brief The @ref CAPI_APPLICATION_MODULE API provides functions to manage the main event loop, the application's state change events, basic system events,
  26 *        and get information about the application.
  27 * @section CAPI_APPLICATION_MODULE_HEADER Required Header
  28 *   \#include <app.h>
  29 *
  30 * @section CAPI_APPLICATION_MODULE_OVERVIEW Overview
  31 * The Application API handles an application state change or system events and provides mechanisms that launch other applications.
  32 * The Tizen native application is similar to a conventional Linux application, but has some additional features optimized for mobile devices,
  33 * which may have constraints such as relatively small screen sizes and lack of system resources compared to a larger system.
  34 * For example, for power management reasons, the application may wish to take actions to reduce usage when it finds out that it had its display window
  35 * covered over by another application's window. State change events are delivered so that this is possible.
  36 * The Application API provides interfaces for the following three categories:
  37 * - Starting or exiting the main event loop (mandatory for every Tizen native application)
  38 * - Registering callbacks for application state change events
  39 * - Registering callbacks for basic system events
  40 *
  41 * @subsection CAPI_APPLICATION_MODULE_EVENT_LOOP Event Loop
  42 * For an application to operate successfully, it must receive events from the platform.
  43 * For this, it needs to start the main event loop - this is mandatory for all Tizen native applications.
  44 * The ui_app_main() function is used to start the event loop.
  45 * Before calling this function, you should set up the #ui_app_lifecycle_callback_s structure, which is passed to the function (see the following sections).
  46 *
  47 * @subsection CAPI_APPLICATION_MODULE_STATE_CHANGE_EVENT Registering Callbacks for Application State Change Events
  48 * The application state change events include the following:
  49 * <p>
  50 * <table>
  51 * <tr>
  52 *  <th> State </th>
  53 *  <th> Description </th>
  54 * </tr>
  55 * <tr>
  56 *  <td> app_create_cb() </td>
  57 *  <td>Hook to take necessary actions before the main event loop starts.
  58 *   Your UI generation code should be placed here so that you do not miss any events from your application UI.
  59 * </td>
  60 * </tr>
  61 * <tr>
  62 *  <td> app_pause_cb() </td>
  63 *  <td> Hook to take necessary actions when an application becomes invisible.
  64 *    For example, you might wish to release memory resources so other applications can use these resources.
  65 *    It is important not to starve the application in front, which is interacting with the user.
  66 * </td>
  67 * </tr>
  68 * <tr>
  69 *  <td> app_resume_cb() </td>
  70 *  <td> Hook to take necessary actions when an application becomes visible.
  71 *   If anything is relinquished in app_pause_cb() but is necessary to resume
  72 *   the application, it must be re-allocated here.
  73 *  </td>
  74 * </tr>
  75 * <tr>
  76 *  <td> app_terminate_cb() </td>
  77 *  <td> Hook to take necessary actions when your application is terminating.
  78 *   Your application should release all resources, especially any
  79 *   allocations and shared resources must be freed here, so other running applications can fully use these shared resources.
  80 *  </td>
  81 * </tr>
  82 * <tr>
  83 *  <td> app_control_cb() </td>
  84 *  <td> Hook to take necessary actions when your application called by another application.
  85 *   When the application gets launch request, this callback function is called.
  86 *   The application can get information about what is to be performed by using App Control API from app_control handle.
  87 *  </td>
  88 * </tr>
  89 * </table>
  90 * For further explanation of application state changes, see the @ref CAPI_APPLICATION_MODULE_STATES_TRANSITIONS section.
  91 *
  92 * @subsection CAPI_APPLICATION_MODULE_SYSTEM_EVENT Registering Callbacks for System Events
  93 * The system event callbacks can be registered using ui_app_add_event_handler(). Multiple system event callbacks can be registered.
  94 * The basic system event includes the following:
  95 * <p>
  96 * <table>
  97 * <tr>
  98 *  <th> System event types </th>
  99 *  <th> Description </th>
 100 * </tr>
 101 * <tr>
 102 *  <td> APP_EVENT_LOW_MEMORY </td>
 103 *  <td> The system memory is running low.
 104 *   Recommended actions are as follows:
 105 * - Action 1. Save data in main memory to persistent memory/storage
 106 *   to avoid data loss in case the Tizen platform Low Memory Killer kills your application to get more free memory.
 107 *   The explanation of how Low Memory Killer behaves is here(link), but basically if the low memory notice does not lead to enough
 108 *   memory being freed, something will be killed. Release cached data in main memory to secure more free memory.
 109 * </td>
 110 * </tr>
 111 * <tr>
 112 *  <td> APP_EVENT_LOW_BATTERY </td>
 113 *  <td> The battery power is running low.
 114 *   Recommended actions are as follows:
 115 * - Action 1. Save data in main memory to persistent memory/storage to avoid sudden loss of data in case power goes off completely.
 116 * - Action 2. Stop heavy CPU consumption or power consumption activities to save remaining power.
 117 * </td>
 118 * </tr>
 119 * <tr>
 120 *  <td> APP_EVENT_DEVICE_ORIENT </td>
 121 *  <td> The orientation of device is changed.
 122 *   Recommended action is as follows: change display orientation to match the display orientation
 123 * </td>
 124 * </tr>
 125 * <tr>
 126 *  <td> APP_EVANG_LANGUAGE_CHANGED </td>
 127 *  <td> The language setting is changed.
 128 *   Recommended action: refresh the display into the new language
 129 * </td>
 130 * </tr>
 131 * <tr>
 132 *  <td> APP_EVENT_REGION_FORMAT_CHANGED </td>
 133 *  <td> The region format setting changed.
 134 *   Region change means a different time zone; the application UI may need to update the time to reflect the time zone change.
 135 * </td>
 136 * </tr>
 137 * <tr>
 138 *  <td> APP_EVENT_SUSPENDED_STATE_CHANGED </td>
 139 *  <td> The suspended state is changed.
 140 *   The application will enter the suspended state, or exit from the state. Do the necessary action before or after suspended; the application shall not respond to requests of the other modules.
 141 *  </td>
 142 * </tr>
 143 * </table>
 144 *
 145 * @subsection CAPI_APPLICATION_MODULE_STATES_TRANSITIONS The Application States and Transitions
 146 * The Tizen native application can be in one of the several different states. Typically, the application is launched by the user from the Launcher, or by
 147 * another application. As the application is starting, app_create_cb() is executed, and then the main event loop starts. After executing event loop, app_control_cb() and app_resume_cb() will be invoked.
 148 * The application now normally becomes the front-most window with focus. When the application loses the front-most/focus status, the app_pause_cb() callback is invoked.
 149 * There are many scenarios for your application to go into the pause state, which means your application is not terminated, but is running in the background:
 150 * - A new application is launched from the request of your application
 151 * - The user requests to go to the home screen
 152 * - A system event occurs and it causes a resident application with higher priority (e.g. a phone call is received) to become active, and hides
 153 *   your application temporarily
 154 * - An alarm went off for another application so it now becomes the top-most window and hides your application
 155 *
 156 * Since Tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif, the application on the background goes in to a suspended state. In the suspended state, the application process is executed with limited CPU resources.
 157 * In other words, the platform does not allow the running of the background applications.
 158 *  When your application becomes visible again, the app_resume_cb() callback is invoked. Some possible scenarios for your application to become visible are:
 159 * - Another application requests your application to run (perhaps the Task Navigator which shows all running applications and lets
 160 *   the user select any app to run)
 161 * - All applications on top of your application in the window stack finish
 162 * - An alarm is going off for your application so it becomes the top-most window and hides other applications
 163 * When your application starts exiting, the app_pause_cb() callback is invoked if the application is visible, and then the app_terminate_cb() callback is invoked.
 164 * Possible scenarios to start termination of your application are:
 165 * - Your application itself requests to exit by calling ui_app_exit() to terminate the event loop
 166 * - The Low Memory Killer is killing your application in a low memory situation.
 167 * Note that a service application doesn't have UI, so the service application doesn't have Paused state.
 168 * Application state changes are managed by the underlying framework.
 169 * Refer to the following state diagram to see the possible transitions:
 170 *
 171 * @image html capi_appfw_application_states.png "Application states"
 172 * <p>
 173 * <table>
 174 * <tr>
 175 *  <th> State </th>
 176 *  <th> Description </th>
 177 * </tr>
 178 * <tr>
 179 *  <td> READY </td>
 180 *  <td> The application is launched. </td>
 181 * </tr>
 182 * <tr>
 183 *  <td> CREATED </td>
 184 *  <td> The application starts the main loop. </td>
 185 * </tr>
 186 * <tr>
 187 *  <td> RUNNING </td>
 188 *  <td> The application is running and visible to the user. </td>
 189 * </tr>
 190 * <tr>
 191 *  <td> PAUSED </td>
 192 *  <td> The application is running but invisible to the user. </td>
 193 * </tr>
 194 * <tr>
 195 *  <td> TERMINATED </td>
 196 *  <td> The application is terminated </td>
 197 * </tr>
 198 * </table>
 199 * The Application API defines five states with their corresponding transition handlers.
 200 * The state transition is notified through the state transition callback function,
 201 * whether the application is created, is running, is paused, is resumed, or is terminated.
 202 * And the application has to perform a specific task that is appropriate to those state changes.
 203 *
 204 * @image html capi_appfw_application_lifecycle.png "General application lifecycle"
 205 *
 206 * @subsection CAPI_APPLICATION_MODULE_HOW_TO_START  How to start the Tizen native application
 207 * An application can be launched by the user from the Launcher or by another application.
 208 * Regardless of how an application is launched, the Application Framework starts an application by creating a new process and calls
 209 * the entry point of the application. Like a conventional Linux application, the main function of its application is the entry point.
 210 * In the Tizen application, the main task is to hand over control to the Application Framework by calling the ui_app_main() function.
 211 *
 212 * @code
 213 * bool
 214 * app_create(void *user_data)
 215 * {
 216 *     // Hook to take necessary actions before the main event loop starts
 217 *     // Initialize UI resources and application's data
 218 *     // If this function returns @c true, the main loop of the application starts
 219 *     // If this function returns @c false, the application is terminated
 220 *     return true;
 221 * }
 222 *
 223 * void
 224 * app_control(app_control_h app_control, void *user_data)
 225 * {
 226 *     // Handle the launch request
 227 * }
 228 *
 229 * void
 230 * app_pause(void *user_data)
 231 * {
 232 *     // Take necessary actions when the application becomes invisible
 233 * }
 234 *
 235 * void
 236 * app_resume(void *user_data)
 237 * {
 238 *     // Take necessary actions when the application becomes visible
 239 * }
 240 *
 241 * void
 242 * app_terminate(void *user_data)
 243 * {
 244 *     // Release all resources
 245 * }
 246 *
 247 * int
 248 * main(int argc, char *argv[])
 249 * {
 250 *     struct appdata ad;
 251 *
 252 *     ui_app_lifecycle_callback_s event_callback = {0,};
 253 *
 254 *     event_callback.create = app_create;
 255 *     event_callback.terminate = app_terminate;
 256 *     event_callback.pause = app_pause;
 257 *     event_callback.resume = app_resume;
 258 *     event_callback.app_control = app_control;
 259 *
 260 *     memset(&ad, 0x0, sizeof(struct appdata));
 261 *
 262 *     return ui_app_main(argc, argv, &event_callback, &ad);
 263 * }
 264 * @endcode
 265 *
 266 * The ui_app_main() function initializes the application and then starts the main loop.
 267 * The ui_app_main() function takes four parameters and uses them to initialize the application.
 268 * The @a argc and @a argv parameters contain the values from the Application Framework, so that you should never have to change the values.
 269 * The third parameter is a state transition handler that is responsible for managing the state
 270 * transitions that the application goes through while it is running. The fourth parameter is the application data to be passed to each state handler.
 271 * When ui_app_main() is first invoked, the application moves from the ready state to the created state.
 272 * The application has to initialize itself.
 273 * During this transition, the Application Framework calls the application's app_create_cb() state transition callback function just
 274 * before the application enters the main loop. Within the registered app_create_cb() callback function, you should initialize the
 275 * application's resources and create the main window.
 276 * If the app_create_cb() callback function returns @c false, the application moves to the terminated state.\n
 277 * If the app_create_cb() callback function returns @c true, the application enters the main loop.
 278 *
 279 * @subsection CAPI_APPLICATION_MODULE_LAUNCH_OPTIONS Handling the launch options
 280 * The Application Framework calls the application's app_control_cb() callback function just after the application enters the main loop.
 281 * This callback function is passed to the app_control containing the reason due to which the application is launched.
 282 * For example, the application might be launched to open a file to handle the request that has been sent by another application.
 283 * In all of these cases, the application is responsible for checking the contents of the app_control and responding appropriately.
 284 * The contents of the app_control can be empty in situations where the application is launched by the user from the Launcher.
 285 *
 286 * @code
 287 * static void
 288 * app_control(app_control_h app_control, void *user_data)
 289 * {
 290 *     struct appdata *ad = (struct appdata *)user_data;
 291 *     char *operation;
 292 *     char *uri;
 293 *     char *mime_type;
 294 *
 295 *     app_control_get_operation(app_control, operation);
 296 *
 297 *     if (!strcmp(operation, SERVICE_OPERATION_VIEW)) {
 298 *         app_control_get_uri(app_control, &uri);
 299 *         app_control_get_mime(app_control, &mime_type);
 300 *
 301 *         if (uri && !strcmp(mime_type, "image/jpg"))
 302 *             display_image_file(ad, uri); // Display a specific image file
 303 *     }
 304 *
 305 *     if (ad->win)
 306 *         elm_win_activate(ad->win);
 307 * }
 308 * @endcode
 309 */
 310
 311 #endif /* __TIZEN_APPFW_APP_DOC_H__ */
 312