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  *
  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.
  29  *
  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
  35  *
  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.
  38  *
  39  * <p>
  40  * <table>
  41  * <tr>
  42  *   <th> Callback </th>
  43  *   <th> Description </th>
  44  * </tr>
  45  * <tr>
  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.
  51  * </td>
  52  * </tr>
  53  * <tr>
  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.
  58  *  </td>
  59  * </tr>
  60  * </table>
  61  * </p>
  62  *
  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"
  65  *
  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.
  71  *
  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.
  74  *
  75  * <p>
  76  * <table>
  77  * <tr>
  78  *   <th> Callback </th>
  79  *   <th> Description </th>
  80  * </tr>
  81  * <tr>
  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.
  86  *   </td>
  87  * </tr>
  88  * <tr>
  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.
  92  *  </td>
  93  * </tr>
  94  * <tr>
  95  *  <td> widget_instance_pause_cb() </td>
  96  *  <td> Called when the widget is invisible.
  97  *   The paused instance may be destroyed by framework
  98  *  </td>
  99  * </tr>
 100  * <tr>
 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.
 104  *  </td>
 105  * </tr>
 106  * <tr>
 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.
 110  *  </td>
 111  * </tr>
 112  * <tr>
 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.
 116  *  </td>
 117  * </tr>
 118  * </table>
 119  * </p>
 120  *
 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"
 123  *
 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
 127  *
 128  *
 129  */