doc/appcore-widget_doc.h

   1 /*
   2  * Copyright (c) 2015 - 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 /**
  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>
  25  *
  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.
  34  *
  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.
  37  * <p>
  38  * <table>
  39  * <tr>
  40  *   <th> Callback </th>
  41  *   <th> Description </th>
  42  * </tr>
  43  * <tr>
  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.
  49  * </td>
  50  * </tr>
  51  * <tr>
  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.
  56  *  </td>
  57  * </tr>
  58  * </table>
  59  * </p>
  60  * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
  61  *
  62  * @image html widget_app_lifecycle.png "Widget Application States"
  63  *
  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.
  69
  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.
  72  * <p>
  73  * <table>
  74  * <tr>
  75  *   <th> Callback </th>
  76  *   <th> Description </th>
  77  * </tr>
  78  * <tr>
  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.
  83  *   </td>
  84  * </tr>
  85  * <tr>
  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.
  89  *  </td>
  90  * </tr>
  91  * <tr>
  92  *  <td> widget_instance_pause_cb() </td>
  93  *  <td> Called when the widget is invisible.
  94  *   The paused instance may be destroyed by framework
  95  *  </td>
  96  * </tr>
  97  * <tr>
  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.
 101  *  </td>
 102  * </tr>
 103  * <tr>
 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.
 107  *  </td>
 108  * </tr>
 109  * <tr>
 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.
 113  *  </td>
 114  * </tr>
 115  * </table>
 116  * </p>
 117  * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.
 118  *
 119  * @image html widget_obj_lifecycle.png "Widget Instance States"
 120  *
 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
 124  */