2 * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @ingroup CAPI_WIDGET_FRAMEWORK
20 * @defgroup CAPI_WIDGET_APP_MODULE Widget Application
21 * @brief Widget application API.
22 * @section CAPI_WIDGET_APP_MODULE_HEADER Required Header
23 * \#include <widget_app.h>
24 * \#include <widget_app_efl.h>
26 * @section CAPI_WIDGET_APP_MODULE_OVERVIEW Overview
27 * The @ref CAPI_WIDGET_APP_MODULE API provides functions for handling Tizen widget application state changes or system events. Tizen widget application can be shown in the home screen.
28 * This API supports making multiple widget instances per an application.
29 * This API provides interfaces for the following categories:
30 * - Starting or exiting the main event loop.
31 * - Registering callbacks for application state change events.
32 * - Registering callbacks for basic system events.
33 * - Registering callbacks for instance state change events.
35 * @subsection CAPI_WIDGET_APP_MODULE_STATE_CHANGE_EVENT Registering Callbacks for Application State Change Events
36 * As for Tizen widget application states, it is very simple and somewhat similar to Tizen service application states.
41 * <th> Description </th>
44 * <td>widget_app_create_cb()</td>
45 * <td>Hook to take necessary actions before the main event loop starts.
46 * Your UI generation code should be placed here so that you do not miss any events from your application UI.
47 * Please make sure that you make a class handle and return it. It will be used when the event for creating widget instance is received.
48 * You can initialize shared resources for widget instances in this callback function as well.
52 * <td> widget_app_terminate_cb() </td>
53 * <td> Hook to take necessary actions when your application is terminating.
54 * Your application should release all resources, especially any
55 * allocations and shared resources must be freed here so that other running applications can fully use these shared resources.
60 * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
62 * @image html widget_app_lifecycle.png "Widget Application States"
64 * @subsection CAPI_WIDGET_APP_MODULE_SYSTEM_EVENT Registering Callbacks for System Events
65 * Tizen widget applications can receive system events with widget_app_add_event_handler() API.
66 * The type of system events that can be received are same as Tizen UI applications except for APP_EVENT_DEVICE_ORIENTATION_CHANGED.
67 * See @ref CAPI_APPLICATION_MODULE.
68 * The event for APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported in this module.
70 * @subsection CAPI_WIDGET_APP_INSTNACE_STATE_CHANGE_EVENT Registering callbacks for instance state change events
71 * As for Tizen widget instance states, it is somewhat similar to Tizen application states.
76 * <th> Description </th>
79 * <td> widget_instance_create_cb() </td>
80 * <td> Called after widget instance is created.
81 * In this callback, you can initialize resources for this instance.
82 * If parameter 'content' is not NULL, you should restore the previous status.
86 * <td> widget_instance_destroy_cb() </td>
87 * <td> Called before widget instance is destroyed.
88 * In this callback, you can finalize resources for this instance.
92 * <td> widget_instance_pause_cb() </td>
93 * <td> Called when the widget is invisible.
94 * The paused instance may be destroyed by framework
98 * <td> widget_instance_resume_cb() </td>
99 * <td> Called when the widget is visible.
100 * The callback function is called when the widget is visible.
104 * <td> widget_instance_resize_cb() </td>
105 * <td> Called before the widget size is changed.
106 * The callback function is called before the widget size is changed.
110 * <td> widget_instance_update_cb() </td>
111 * <td> Called when the event for updating widget is received.
112 * The callback function is called when the event for updating widget is received.
117 * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
119 * @image html widget_obj_lifecycle.png "Widget Instance States"
121 * @section CAPI_WIDGET_APP_MODULE_RELATED_FEATURES Related Features
122 * This API is related with the following feature:
123 * - http://tizen.org/feature/shell.appwidget