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
23 * @section CAPI_WIDGET_APP_MODULE_HEADER Required Header
24 * \#include <widget_app.h>
25 * \#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 APIs support making multiple widget instances per an application.
30 * This API provides interfaces for the following categories:
31 * - Starting or exiting the main event loop
32 * - Registering callbacks for application state change events
33 * - Registering callbacks for basic system events
34 * - Registering callbacks for instance state change events
36 * @subsection CAPI_WIDGET_APP_MODULE_STATE_CHANGE_EVENT Registering Callbacks for Application State Change Events
37 * As for Tizen widget application states, it is very simple and somewhat similer to Tizen service application states.
43 * <th> Description </th>
46 * <td>widget_app_create_cb()</td>
47 * <td>Hook to take necessary actions before the main event loop starts.
48 * Your UI generation code should be placed here so that you do not miss any events from your application UI.
49 * Please make sure that you should make a class handle and return it. It will be used when the event for creating widget instance is received.
50 * You can initialize shared resources for widget instances in this callback function as well.
54 * <td> widget_app_terminate_cb() </td>
55 * <td> Hook to take necessary actions when your application is terminating.
56 * Your application should release all resources, especially any
57 * allocations and shared resources must be freed here so other running applications can fully use these shared resources.
63 * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
64 * @image html widget_app_lifecycle.png "Widget Application States"
66 * @subsection CAPI_WIDGET_APP_MODULE_SYSTEM_EVENT Registering Callbacks for System Events
67 * Tizen widget applications can receive system events with widget_app_add_event_handler() api.
68 * The type of system events that can be received are same as Tizen UI applications except for APP_EVENT_DEVICE_ORIENTATION_CHANGED.
69 * See @ref CAPI_APPLICATION_MODULE.
70 * The event for APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported in this module.
72 * @subsection CAPI_WIDGET_APP_INSTNACE_STATE_CHANGE_EVENT Registering callbacks for instance state change events
73 * As for Tizen widget instance states, it is somewhat similer to Tizen application states.
79 * <th> Description </th>
82 * <td> widget_instance_create_cb() </td>
83 * <td> Called after widget instance is created.
84 * In this callback, you can initialize resources for this instance.
85 * If parameter 'content' is not NULL, You should restore the pervious status.
89 * <td> widget_instance_destroy_cb() </td>
90 * <td> Called before widget instance is destroyed.
91 * In this callback, you can finalize resources for this instance.
95 * <td> widget_instance_pause_cb() </td>
96 * <td> Called when the widget is invisible.
97 * The paused instance may be destroyed by framework
101 * <td> widget_instance_resume_cb() </td>
102 * <td> Called when the widget is visible.
103 * The callback function is called when the widget is visible.
107 * <td> widget_instance_resize_cb() </td>
108 * <td> Called before the widget size is changed.
109 * The callback function is called before the widget size is changed.
113 * <td> widget_instance_update_cb() </td>
114 * <td> Called when the event for updating widget is received.
115 * The callback function is called when the event for updating widget is received.
121 * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
122 * @image html widget_obj_lifecycle.png "Widget Instance States"
124 * @section CAPI_WIDGET_APP_MODULE_RELATED_FEATURES Related Features
125 * This API is related with the following feature:
126 * - http://tizen.org/feature/shell.appwidget