dynamicbox_viewer/doc/dynamicbox_viewer_doc.h

   1 /*
   2  * Copyright 2013  Samsung Electronics Co., Ltd
   3  *
   4  * Licensed under the Flora License, Version 1.1 (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://floralicense.org/license/
   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  * @ingroup CAPI_DYNAMICBOX_FRAMEWORK
  19  * @defgroup DYNAMICBOX_VIEWER_MODULE Dynamic Box Viewer
  20  * @brief API for dynamic box viewer (widget screen, home screen, ...)
  21  * @section DYNAMICBOX_VIEWER_MODULE_HEADER Required Header
  22  * \#include <dynamicbox.h>
  23  * @section DYNAMICBOX_VIEWER_MODULE_OVERVIEW Overview
  24  * Tizen homescreen S/W framework is supporing the Dynamic Box. (aka widget which is similiar with the android widget)
  25  *
  26  * @image html front.jpg
  27  *
  28  * @subsection WhatIsTheDynamicBox 1. What is the Dynamic Box
  29  * The Dynamic Box is the widget of the TIZEN.
  30  *
  31  * It works as a small application displayed on other applications' (such as homescreen, lockscreen, etc ...) view.
  32  * Each Dynamic Box can have (not a mandatory option) a Glance Bar (Glance Bar) in which more detailed information can be found.
  33  * The content of Glance Bar can be exposed when a certain gesture (e.g., flick-down) has been applied to the Dynamic Box.
  34  * If you are interested in developing a dynamic box, there are things you should know prior to making any source code for the box.
  35  * To make your Dynamic Box added to any Dynamic Box viewer application (e.g., live panel in our case), then you need to create and prepare
  36  * controller(SO file), layout script (EDJE for a Glance Bar if necessary), configuration files.
  37  *
  38  * A dynamic box is managed by data provider, since each SO file of a dynamic box is loaded on and controlled by data provider using predefined ABI.
  39  * A viewer will receive any dynamic box's content in forms of "image file", "buffer" or "text" and display the content in various formats on its window.
  40  * A dynamic box developer needs to make sure that your Dynamic Box generates desirable content in-time on a explicit update-request or periodic update.
  41  *
  42  * After a data provider loads a dynamic box's SO file, it then assigns a specific "file name" for the dynamic box via an argument of a dynamic box function.
  43  * Since then the dynamic box just generates content using then given file name.
  44  * Passing an image file (whose name is the previously given name) is the basic method for providing contents to the viewer.
  45  * But if you want play animation or handles user event in real-time, you can use the buffer type.
  46  *
  47  * And you should prepare the content of the Glance Bar.
  48  * The Glance Bar is only updated by the "buffer" type. so you should prepare the layout script for it.
  49  * If you didn't install any script file for Glance Bar, the viewer will ignore the "flick down" event from your dynamic box.
  50  *
  51  * @subsubsection DynamicBox 1.1 Dynamic Box
  52  * Live box is a default content of your widget. It always displays on the screen and updated periodically.
  53  * It looks like below captured images.
  54  * @image html weather.png Weather Dynamic Box
  55  * @image html stock.png Stock Dynamic Box
  56  * @image html twitter.png Twitter Dynamic Box
  57  *
  58  * @subsubsection GlanceBar 1.2 Glance Bar
  59  * @image html PD.png Glance Bar
  60  * Glance Bar will be displayed when a user flicks down a dynamic box. (basically it depends on the implementation of the viewer applications)
  61  * To supports this, a developer should prepare the layout script (EDJE only for the moment) of the dynamic box's Glance Bar. (or you can use the buffer directly)
  62  * Data provider supports EDJE script but the developer can use various scripts if (which is BIG IF) their interpreters can be implemented based on evas & ecore.
  63  *
  64  * When a layout script has been installed, data provider can load and rendering the given layout on the buffer.
  65  * The content on the buffer can be shared between applications that need to display the content on their window.
  66  * Description data file is necessary to place proper content components in rendered layout.
  67  * Check this page Description Data.
  68  *
  69  * @subsubsection ClusterCategory 1.3 What is the "cluster" and "category"
  70  * The cluster and the sub-cluster is just like the grouping concept.
  71  * It is used for creating/destorying your dynamic box instance when the data provider receives any context event from the context engine.
  72  * You will only get "user,created" cluster and "default" category(sub cluster) info.
  73  *
  74  * @subsection DynamicBoxContent 2. How the dynamic box can draw contents for viewer?
  75  * There are several ways to update the content of a dynamic box.
  76  *
  77  * @li Image file based content updating
  78  * @li Description file based content updating (with the layout script file)
  79  * @li Buffer based content updating
  80  *
  81  * Each method has specific benefit for implementing the dynamic box.
  82  *
  83  * @subsubsection ImageFormat 2.1 Via image file
  84  * This is the basic method for providing content of a dynamic box to the viewer application.
  85  * But this can be used only for the dynamic box. (Unavailable for the Glance Bar).
  86  * When your dynamic box is created, the provider will assign an unique ID for your dynamic box(it would be a filename).
  87  * You should keep that ID until your dynamic box is running. The ID will be passed to you via dynamicbox_create function.
  88  * \image html image_format.png
  89  *
  90  * When you need to update the output of your dynamic box, you should generate the image file using given ID(filename).
  91  * Then the data provider will recognize the event of updated output of a dynamic box and it will send that event to the viewer to reload it on the screen.
  92  *
  93  * @subsubsection ScriptFormat 2.2 Via layout script
  94  * @image html script_format.png
  95  * This method is supported for static layout & various contents (text & image)
  96  * When you develop your dynamic box, first design the layout of box content using script (edje is default)
  97  * Then the provider will load it to the content buffer and start rendering.
  98  * After the sciprt is loaded, you can fill it using description data format.
  99  * libdynamicbox defines description data handling functions.
 100  *
 101  * @subsubsection TextFormat 2.3 Via text data
 102  * @image html text_format.png
 103  * This is the simplified method to update the content of dynamic box.
 104  * So your box only need to update the text data using description data format.
 105  * Then the viewer will parse it to fill its screen.
 106  * So there is no buffer area, just viewer decide how handles it.
 107  *
 108  * @subsubsection BufferFormat 2.4 Via buffer
 109  * This method is very complex to implement.
 110  * The provider will give a content buffer to you, then your box should render its contents on this buffer.
 111  * This type is only supported for 3rd party dynamic box such as OSP and WEB.
 112  * Inhouse(EFL) dynamic box is not able to use this buffer type for the box content.
 113  *
 114  * @subsection DynamicBoxDirectory 3. Dynamic Box directory hierachy
 115  * @image html preload_folder.png
 116  * @image html download_folder.png
 117  *
 118  * @subsection WritingViewerApp 4. Writing a new application for displaying Dynamic Boxes
 119  * If you want install dynamic boxes on your application screen, you should initialize the viewer system first.
 120  *
 121  * @code
 122  * extern int dynamicbox_init(void *disp, int prevent_overwrite, double event_filter, int use_thread);
 123  * @endcode
 124  *
 125  * @a disp should be current display object. if we are on X11 based windowing system, it will give you a Display Object, when you connect to X Server.
 126  * Viewer application also needs it to preparing rendering buffer to display contents of dynamic boxes.
 127  *
 128  * @a prevent_overwirte flag is used for image or script type dynamic boxes.
 129  * If this option is turn on, the viewer library will copy the image file of dyanmic box content to "reader" folder.
 130  * To prevent from overwriting content image file.
 131  *
 132  * @a event_filter is used for feeding events.
 133  * Basically, the dynamic box can be feed touch event by viewer application or master widget controller. (aka, data-provider-master).
 134  * If a viewer feeds event to the dynamic box, it could more slow than data-provider-master's direct feeding.
 135  * But sometimes, the viewer requires to feeds event by itself.
 136  * In that case, we should choose the feeding option. feeding every events can be slow down.
 137  * To save it, this event_filter will be used. if the event is generated in this time-gap, it will be ignored.
 138  *
 139  * @a use_thread if this flag is turned on, the viewer library will create a new thread for handling the IPC packets only.
 140  * It will helps to increase the throughput of main thread. because it will not be interrupted to handles IPC packets.
 141  *
 142  * After the viewer is initiated, you can create a new box and locate it in your screen.
 143  *
 144  * Opposite function is "dynamicbox_fini"
 145  *
 146  * @code
 147  * extern int dynamicbox_fini(void);
 148  * @endcode
 149  *
 150  * Here is a sample code
 151  *
 152  * @code
 153  * #include <stdio.h>
 154  * #include <errno.h>
 155  * #include <dynamicbox.h>
 156  * #include <app.h>
 157  *
 158  * #include <dlog.h>
 159  *
 160  * int errno;
 161  *
 162  * static bool _create_cb(void *data)
 163  * {
 164  *      int ret;
 165  *      ret = dynamicbox_init(NULL, 1, 0.0f, 1);
 166  *      if (ret != DBOX_STATUS_ERROR_NONE) {
 167  *          LOGE("Failed to initialize the dynamic box viewer");
 168  *      }
 169  *      return true;
 170  * }
 171  *
 172  * static void _terminate_cb(void *data)
 173  * {
 174  *     dynamicbox_fini();
 175  * }
 176  *
 177  * int main(int argc, char *argv[])
 178  * {
 179  *     app_event_callback_s event_callback;
 180  *     event_callback.create = _create_cb;
 181  *     event_callback.terminate = _terminate_cb;
 182  *     event_callback.pause = _pause_cb;
 183  *     event_callback.resume = _resume_cb;
 184  *     event_callback.app_control = _app_control;
 185  *     event_callback.low_memory = NULL;
 186  *     event_callback.low_battery = NULL;
 187  *     event_callback.device_orientation = NULL;
 188  *     event_callback.language_changed = _language_changed;
 189  *     event_callback.region_format_changed = NULL;
 190  *
 191  *     return app_efl_main(&argc, &argv, &event_callback, &main_info);
 192  * }
 193  * @endocde
 194  *
 195  * If you want add a new dynamic box, you can call "dynamicbox_add()" function.
 196  *
 197  */